brainhops.io.transformations.fsl

Create an instance of the class from a dictionary-like object.

Only keys in the dictionary that match keyword-like fields of this class, or the keywords its constructor takes without storing them (its InitVars, such as the matrix= of an Affine), will be used. Other keys are ignored, but see from_other, which refuses them.

Additional positional and/or keyword arguments can be provided, and will take precedence over the values in the dictionary.

A key naming a field that this class fixes (a field that cannot be passed to its constructor) is checked instead of used: a dictionary that sets it to anything other than None or the value of this class is refused with a ValueError.

Create an instance of the class from an instance of a similar class.

Only attributes of the other instance that match keyword-like fields of this class will be used. An attribute that is None is unset, and leaves the default of this class in place.

Additional positional and/or keyword arguments can be provided, and will take precedence over the attributes in the instance.

Unless the other instance is already an instance of this class, an attribute naming a field that this class fixes (a field that cannot be passed to its constructor) is checked instead of used: an instance that sets it to anything other than None or the value of this class is refused with a ValueError. A generic Axis whose orientation is right-to-left, for example, cannot be read as a LeftToRightAxis.

Create an instance of the class from any object that can be interpreted as a dictionary, or an instance of a similar class, or an arguments to be passed to the constructor.

A similar class is this class or one of its parents within the data model, or another member of a polymorphic family this class belongs to: calling a polymorphic class such as Axis builds the subclass its arguments select, so a "generic" axis is usually an instance of a sibling (a RightToLeftAxis, a TimeAxis) rather than of a parent. Any other object, including an instance of a parent that is not a data model (such as a plain object), is passed to the constructor.

Unlike from_dict, a dictionary with a key that matches no field of this class is refused with a TypeError naming the keys, so that a misspelt key is not silently dropped.

The closed system of ndim axes that this system describes.

The axes are expanded by AxisSequence.expand: in an open system, ... is replaced with as many unknown Axis() as needed to reach ndim axes. The class is called again with the closed axes, and the other fields, the name included, are kept: the result is of this class, or of the subclass that the closed axes select from it (an ArrayCoordinateSystem closed to two axes is an ArrayCoordinateSystem2D). Each unknown Axis() is first read as the type of axis the class declares, so a SpatialCoordinateSystem closed to three axes has three spatial axes, and is a SpatialCoordinateSystem3D. Use it once the number of axes is known, for instance from the shape of the data.

>>> CoordinateSystem(axes=[Axis(name="x"), ...]).expand(4)
CoordinateSystem(axes=[Axis(name='x'), Axis(), Axis(), Axis()])
>>> CoordinateSystem().expand(2)
CoordinateSystem2D(axes=(Axis(), Axis()))

Parameters:

Returns:

Raises:

The system of the axes at some positions of this system.

The axes are restricted by AxisSequence.restrict: a reference is a position in the space or a name, and a position of an open system that falls among the axes that ... stands for gives an unknown Axis(). The axes are listed in the order of refs. The result describes a different space, so the class and the name of this system are not carried over: it is the closed system that CoordinateSystem(axes=...) builds from the restricted axes, which is a CoordinateSystem2D, an RASCoordinateSystem, ... when the axes select one.

>>> x, y, z = Axis(name="x"), Axis(name="y"), Axis(name="z")
>>> CoordinateSystem(axes=[x, y, z]).restrict(["z", 0])
CoordinateSystem2D(axes=(Axis(name='z'), Axis(name='x')))
>>> CoordinateSystem(axes=[x, ...]).restrict([0])
CoordinateSystem(axes=[Axis(name='x')])

Parameters:

Returns:

Raises:

The system of a larger space in which this system's axes sit.

This is the inverse of restrict. The axes are embedded by AxisSequence.embed: axis j of this system sits at positions[j] of the result, and every other position holds an unknown Axis(). The result describes a different space, so the class and the name of this system are not carried over: it is the system that CoordinateSystem(axes=...) builds from the embedded axes -- a plain, open CoordinateSystem when ndim is not given, and the closed system the axes select when it is.

>>> x = Axis(name="x")
>>> CoordinateSystem(axes=[x]).embed([1])
CoordinateSystem(axes=[Axis(), Axis(name='x'), Ellipsis])
>>> CoordinateSystem(axes=[x]).embed([1], ndim=4)
CoordinateSystem(axes=[Axis(), Axis(name='x'), Axis(), Axis()])

Parameters:

Returns:

Raises:

Whether self and other could describe the same space.

Two systems are compatible when their axes are AxisSequence.compatible_with each other: some choice of the axes that each ... stands for makes them match axis by axis, each pair being Axis.compatible_with. Only the axes are compared, not the names of the systems. None is read as a system about which nothing is known, which is compatible with every system.

For two closed systems, this asks for the same number of axes, pairwise compatible. Unlike ==, an unknown Axis() matches any axis. The relation is symmetric, but not transitive.

>>> x, t = SpaceAxis(name="x"), TimeAxis()
>>> CoordinateSystem(axes=[x, ...]).compatible_with(
...     CoordinateSystem(axes=[x, Axis(), t])
... )
True
>>> CoordinateSystem(axes=[..., t]).compatible_with(
...     CoordinateSystem(axes=[x])
... )
False

Parameters:

Returns:

Raises:

On a dispatcher, identify which registered format would read file. On a concrete format, score how confident it is that file, in any supported form, is its own.

On a dispatcher, identify which registered format would read the file (path or file-like object). On a concrete format, score how confident it is that the file is its own.

Determine if the given filename is of the type that this parser can handle.

Parameters:

Returns:

Determine if the given file-like object is of the type that this parser can handle.

A text stream decodes as it is read, so content that is not text -- a binary file that shares an extension with a text format -- fails there. That is a "no", not a failure to sniff.

Parameters:

Returns:

On a dispatcher, identify which registered format would read the content (text or bytes). On a concrete format, score how confident it is that the content is its own.

Determine if the given bytes are of the type that this parser can handle, by decoding them to text and delegating to sniff_text. Bytes that do not decode are not text, so they score NO.

Parameters:

Returns:

On a dispatcher, identify which registered format would read the text. On a concrete format, score how confident it is that the text is its own.

On a dispatcher, identify which registered format would read the line. On a concrete format, score how confident it is that the line is its own.

On a dispatcher, pick the best-matching registered format and build an instance of it from other. On a concrete format, build an instance of this class from other, in any supported form.

Load a structured source specification through this dispatcher.

On a dispatcher, pick the best-matching registered format and build an instance of it from the file (path or file-like object). On a concrete format, build an instance of this class from the file.

Build an object from a filename.

Parameters:

Returns:

On a dispatcher, pick the best-matching registered format and build an instance of it from the open file object. On a concrete format, build an instance of this class from the file object.

On a dispatcher, pick the best-matching registered format and build an instance of it from the content (text or bytes). On a concrete format, build an instance of this class from the content.

Build an object from bytes, by decoding them to text and delegating to from_text.

Parameters:

Returns:

On a dispatcher, pick the best-matching registered format and build an instance of it from the text. On a concrete format, build an instance of this class from the text.

On a dispatcher, pick the best-matching registered format and build an instance of it from the line. On a concrete format, build an instance of this class from the line.

Create an instance of the class from a dictionary-like object.

Only keys in the dictionary that match keyword-like fields of this class, or the keywords its constructor takes without storing them (its InitVars, such as the matrix= of an Affine), will be used. Other keys are ignored, but see from_other, which refuses them.

Additional positional and/or keyword arguments can be provided, and will take precedence over the values in the dictionary.

A key naming a field that this class fixes (a field that cannot be passed to its constructor) is checked instead of used: a dictionary that sets it to anything other than None or the value of this class is refused with a ValueError.

Create an instance from an instance of a similar class.

See DataModelBase.from_instance. The map of an Affine is copied through its matrix view, not its stored data, which a lazy wrapper derives and a tangent (log=True) stores as its logarithm. A tangent is copied into a tangent through its data.

Create an instance from a file, or from anything the data model reads.

A path (str or os.PathLike), an open file, bytes or a structured source (SourceSpec) is read with load: on a dispatcher such as FileBasedImage, the best-matching registered format reads it, and on a concrete format, that format does. Any other value is handed to the data model's own from_other, which reads a mapping field by field, copies an instance of a similar class, and passes anything else to the constructor.

Parameters:

Returns:

Raises:

Compute the transformation, downcasting it to the cheapest compatible kind.

A concrete transformation holds a parameter, so it simplifies to the simplest compatible kind, whose compatibility can be detected with (almost) no overhead. For example, a transformation whose parameter is set to None is treated as an identity.

Parameters:

Simplify this transformation under a per-kind policy.

Convenience sugar for compute: t.simplify(policy, compute=mode) is t.compute(mode, simplify=policy).

By default simplify() does no computation at all: compute=False maps to mode=False, which composes nothing (no matrices multiplied, no fields sampled, no lazy inverse materialized). It only downcasts each leaf under policy (analytic by default). Pass an explicit compute=<mode> to also compose that kind.

Parameters:

Return the square of this transformation, self @ self.

The square is the sequence [self, self], which composes when it is computed. It is defined for a transformation that maps a space to itself.

Parameters:

Raises:

Convert this transformation to a different type.

Conversion can be

• between type: linear.to(Affine) ; or
• within type: displacement.to(coeff=True) ; or
• both: coords.to(DisplacementField, coeff=True) .

Parameters:

Returns:

On a dispatcher, identify which registered format would read file. On a concrete format, score how confident it is that file, in any supported form, is its own.

On a dispatcher, identify which registered format would read the file (path or file-like object). On a concrete format, score how confident it is that the file is its own.

Determine if the given filename is of the type that this parser can handle.

Parameters:

Returns:

Score how confident the class is that an open file object holds a NIfTI-1 or NIfTI-2 header, or a header of the given version when one is passed.

On a dispatcher, identify which registered format would read the content (text or bytes). On a concrete format, score how confident it is that the content is its own.

Score how confident the class is that bytes hold a NIfTI-1 or NIfTI-2 header.

On a dispatcher, identify which registered format would read the text. On a concrete format, score how confident it is that the text is its own.

On a dispatcher, identify which registered format would read the lines. On a concrete format, score how confident it is that the lines are its own.

On a dispatcher, identify which registered format would read the line. On a concrete format, score how confident it is that the line is its own.

On a dispatcher, pick the best-matching registered format and build an instance of it from other. On a concrete format, build an instance of this class from other, in any supported form.

Load a structured source specification through this dispatcher.

Build an object from a filename.

Parameters:

Returns:

On a dispatcher, pick the best-matching registered format and build an instance of it from the content (text or bytes). On a concrete format, build an instance of this class from the content.

On a dispatcher, pick the best-matching registered format and build an instance of it from the text. On a concrete format, build an instance of this class from the text.

On a dispatcher, pick the best-matching registered format and build an instance of it from the lines. On a concrete format, build an instance of this class from the lines.

On a dispatcher, pick the best-matching registered format and build an instance of it from the line. On a concrete format, build an instance of this class from the line.

Write the object to a file (path or file-like object).

This is the generic front door to the to_* family. It is named save rather than to because to already means something else on the data models these parsers are mixed into: Transformation.to converts an object to another type. A writer's to was shadowed by it on every writable transformation.

Parameters:

Write the object to a NIfTI file.

A path is written gzipped when its name ends in .gz: a local path is handed to nibabel by name, and a remote one is opened through its own backend. See _save_nifti. A file-like object is written the uncompressed NIfTI bytes.

Write the object to a filename.

Parameters:

Write the uncompressed NIfTI-1 encoding of the object to an open file object.

Return the uncompressed NIfTI-1 encoding of the object.

Return a text version of the file.

Parameters:

Returns:

Return a text version of the file as an iterable of lines.

Parameters:

Returns:

Return a line representing the object.

Parameters:

Returns:

Create an instance of the class from a dictionary-like object.

Only keys in the dictionary that match keyword-like fields of this class, or the keywords its constructor takes without storing them (its InitVars, such as the matrix= of an Affine), will be used. Other keys are ignored, but see from_other, which refuses them.

Additional positional and/or keyword arguments can be provided, and will take precedence over the values in the dictionary.

A key naming a field that this class fixes (a field that cannot be passed to its constructor) is checked instead of used: a dictionary that sets it to anything other than None or the value of this class is refused with a ValueError.

Create an instance from an instance of a similar class.

The data model copies the fields both classes share, by name. A field that a file format declares for its own use -- such as the nibabel image and header of the NIfTI and MGH formats -- is only copied from an object of that same format: from any other object, a field of the same name holds something else (a NIfTI image is no MGH image), so this class's default is kept instead. Saving a NIfTI image to MGH, or the converse, therefore converts the data model only, and the format-specific state is rebuilt by the writer.

Create an instance from a file, or from anything the data model reads.

A path (str or os.PathLike), an open file, bytes or a structured source (SourceSpec) is read with load: on a dispatcher such as FileBasedImage, the best-matching registered format reads it, and on a concrete format, that format does. Any other value is handed to the data model's own from_other, which reads a mapping field by field, copies an instance of a similar class, and passes anything else to the constructor.

Parameters:

Returns:

Raises:

Build the object from an already-loaded nibabel header or image.

Build the nibabel image that encodes this object.

Each concrete NIfTI format overrides this method to describe how its own contents map onto a NIfTI image. The other writer methods are defined in terms of this one.

Score how confident the class is that an already-loaded nibabel header or image matches this format.

The header's magic number is checked first. A header that passes is then scored for how well it matches this particular format, as opposed to another kind of NIfTI-based format.

Compute the resulting transform of the sequence of transformations.

Assuming that mode=True:

• If all transformations in the sequence are affine-like transformations, compute() returns an affine-like transform.

• If the first (= rightmost) transform in the sequence is a coordinate field, compute() returns a coordinate field.

• If the first (= rightmost) transform in the sequence is an affine-like transform, and the sequence contains at least one non-affine-like transform, compute() returns a sequence of two transformations:

• the composition of all affine-like transformations that appear before the first non-affine-like transform in the sequence, and

• the composition of all transformations in the sequence, starting from the first non-affine-like transform in the sequence.

Simplify this transformation under a per-kind policy.

Convenience sugar for compute: t.simplify(policy, compute=mode) is t.compute(mode, simplify=policy).

By default simplify() does no computation at all: compute=False maps to mode=False, which composes nothing (no matrices multiplied, no fields sampled, no lazy inverse materialized). It only downcasts each leaf under policy (analytic by default). Pass an explicit compute=<mode> to also compose that kind.

Parameters:

Return the square of this transformation, self @ self.

The square is the sequence [self, self], which composes when it is computed. It is defined for a transformation that maps a space to itself.

Parameters:

Raises:

Return the principal square root of this chain.

The chain is first simplified, which costs nothing. A chain [P, *X, P^-1], where P^-1 is the lazy inverse of P, or both are affines whose product is exactly the identity, is a change of coordinates around X, and its square root is [P, sqrt(X), P^-1]: a field stored in voxels between a world-to-voxel affine and its lazy inverse keeps that form. Any other chain is composed now, and the square root of the transformation it composes to is returned.

Raises:

Convert this chain to a different type or encoding.

See Transformation.to. A chain has no tangent of its own -- the tangent of a composition is not the sum of the tangents -- so log= re-encodes the transformation it reduces to, and anything else is refused before it is computed:

• a chain that simplifies to one transformation is that one;
• a change of coordinates [P, *X, P^-1] (see sqrt) keeps its ends, and re-encodes X: the flow of a velocity commutes with the conjugation, so this is exact. A velocity read between a world-to-voxel affine and its inverse (|svf) is turned into its displacement that way;
• a chain of affines is composed, which is cheap and exact.

Any other chain -- one with a field, between ends that do not undo each other -- raises ConversionError.