Multiformat-capable streamline format read / write interface
detect_format(fileobj) | Returns the StreamlinesFile object guessed from the file-like object. |
is_supported(fileobj) | Checks if the file-like object if supported by NiBabel. |
load(fileobj[, lazy_load]) | Loads streamlines in RAS+ and mm space from a file-like object. |
save(tractogram, filename, **kwargs) | Saves a tractogram to a file. |
ArraySequence([iterable, buffer_size]) | Sequence of ndarrays having variable first dimension sizes. |
concatenate(seqs, axis) | Concatenates multiple ArraySequence objects along an axis. |
create_arraysequences_from_generator(gen, n) | Creates ArraySequence objects from a generator yielding tuples |
is_array_sequence(obj) | Return True if obj is an array sequence. |
is_ndarray_of_int_or_bool(obj) |
Field class defining common header fields in tractogram files
Field | Header fields common to multiple streamline file formats. |
Read / write access to TCK streamlines format.
TCK format is defined at http://mrtrix.readthedocs.io/en/latest/getting_started/image_data.html?highlight=format#tracks-file-format-tck
TckFile(tractogram[, header]) | Convenience class to encapsulate TCK file format. |
LazyDict(*args, **kwargs) | Dictionary of generator functions. |
LazyTractogram([streamlines, ...]) | Lazy container for streamlines and their data information. |
PerArrayDict([n_rows]) | Dictionary for which key access can do slicing on the values. |
PerArraySequenceDict([n_rows]) | Dictionary for which key access can do slicing on the values. |
SliceableDataDict(*args, **kwargs) | Dictionary for which key access can do slicing on the values. |
Tractogram([streamlines, ...]) | Container for streamlines and their data information. |
TractogramItem(streamline, ...) | Class containing information about one streamline. |
is_data_dict(obj) | True if obj seems to implement the DataDict API |
is_lazy_dict(obj) | True if obj seems to implement the LazyDict API |
Define abstract interface for Tractogram file classes
DataError | Raised when data is missing or inconsistent in a tractogram file. |
DataWarning | Base class for warnings about tractogram file data. |
ExtensionWarning | Base class for warnings about tractogram file extension. |
HeaderError | Raised when a tractogram file header contains invalid information. |
HeaderWarning | Base class for warnings about tractogram file header. |
TractogramFile(tractogram[, header]) | Convenience class to encapsulate tractogram file format. |
abstractclassmethod(callable) |
TrkFile(tractogram[, header]) | Convenience class to encapsulate TRK file format. |
decode_value_from_name(encoded_name) | Decodes a value that has been encoded in the last bytes of a string. |
encode_value_in_name(value, name[, max_name_len]) | Return name as fixed-length string, appending value as string. |
get_affine_rasmm_to_trackvis(header) | |
get_affine_trackvis_to_rasmm(header) | Get affine mapping trackvis voxelmm space to RAS+ mm space |
get_affine_from_reference(ref) | Returns the affine defining the reference space. |
Returns the StreamlinesFile object guessed from the file-like object.
Parameters: | fileobj : string or file-like object
|
---|---|
Returns: | tractogram_file : TractogramFile class
|
Checks if the file-like object if supported by NiBabel.
Parameters: | fileobj : string or file-like object
|
---|---|
Returns: | is_supported : boolean |
Loads streamlines in RAS+ and mm space from a file-like object.
Parameters: | fileobj : string or file-like object
lazy_load : {False, True}, optional
|
---|---|
Returns: | tractogram_file : TractogramFile object
|
Notes
The streamline coordinate (0,0,0) refers to the center of the voxel.
Saves a tractogram to a file.
Parameters: | tractogram : Tractogram object or TractogramFile object
filename : str
**kwargs : keyword arguments
|
---|
Bases: object
Sequence of ndarrays having variable first dimension sizes.
This is a container that can store multiple ndarrays where each ndarray might have a different first dimension size but a common size for the remaining dimensions.
More generally, an instance of ArraySequence of length $N$ is composed of $N$ ndarrays of shape $(d_1, d_2, ... d_D)$ where $d_1$ can vary in length between arrays but $(d_2, ..., d_D)$ have to be the same for every ndarray.
Initialize array sequence instance
Parameters: | iterable : None or iterable or ArraySequence, optional
buffer_size : float, optional
|
---|
Initialize array sequence instance
Parameters: | iterable : None or iterable or ArraySequence, optional
buffer_size : float, optional
|
---|
Appends element to this array sequence.
Append can be a lot faster if it knows that it is appending several elements instead of a single element. In that case it can cache the parameters it uses between append operations, in a “build cache”. To tell append to do this, use cache_build=True. If you use cache_build=True, you need to finalize the append operations with finalize_append().
Parameters: | element : ndarray
cache_build : {False, True}
|
---|---|
Returns: | None : |
Notes
If you need to add multiple elements you should consider ArraySequence.extend.
Matching shape of the elements in this array sequence.
Creates a copy of this ArraySequence object.
Returns: | seq_copy : ArraySequence instance
|
---|
Notes
We do not simply deepcopy this object because we have a chance to use less memory. For example, if the array sequence being copied is the result of a slicing operation on an array sequence.
Elements in this array sequence.
Appends all elements to this array sequence.
Parameters: | elements : iterable of ndarrays or ArraySequence object
|
---|---|
Returns: | None : |
Notes
The shape of the elements to be added must match the one of the data of this ArraySequence except for the first dimension.
Finalize process of appending several elements to self
append() can be a lot faster if it knows that it is appending several elements instead of a single element. To tell the append method this is the case, use cache_build=True. This method finalizes the series of append operations after a call to append() with cache_build=True.
Loads a ArraySequence object from a .npz file.
Saves this ArraySequence object to a .npz file.
Total number of rows in this array sequence.
Concatenates multiple ArraySequence objects along an axis.
Parameters: | seqs: iterable of :class:`ArraySequence` objects :
axis : int
|
---|---|
Returns: | new_seq: :class:`ArraySequence` object :
|
Creates ArraySequence objects from a generator yielding tuples
Parameters: | gen : generator
n : int
|
---|
Return True if obj is an array sequence.
Bases: object
Header fields common to multiple streamline file formats.
In IPython, use nibabel.streamlines.Field?? to list them.
x.__init__(...) initializes x; see help(type(x)) for signature
Bases: nibabel.streamlines.tractogram_file.TractogramFile
Convenience class to encapsulate TCK file format.
Notes
MRtrix (so its file format: TCK) considers streamlines coordinates to be in world space (RAS+ and mm space). MRtrix refers to that space as the “real” or “scanner” space [1]_.
Moreover, when streamlines are mapped back to voxel space [2]_, a streamline point located at an integer coordinate (i,j,k) is considered to be at the center of the corresponding voxel. This is in contrast with TRK’s internal convention where it would have referred to a corner.
NiBabel’s streamlines internal representation follows the same convention as MRtrix.
References
[1] http://www.nitrc.org/pipermail/mrtrix-discussion/2014-January/000859.html [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
Parameters: | tractogram : Tractogram object
header : None or dict, optional
|
---|
Notes
Streamlines of the tractogram are assumed to be in RAS+ and mm space. It is also assumed that when streamlines are mapped back to voxel space, a streamline point located at an integer coordinate (i,j,k) is considered to be at the center of the corresponding voxel. This is in contrast with TRK’s internal convention where it would have referred to a corner.
Parameters: | tractogram : Tractogram object
header : None or dict, optional
|
---|
Notes
Streamlines of the tractogram are assumed to be in RAS+ and mm space. It is also assumed that when streamlines are mapped back to voxel space, a streamline point located at an integer coordinate (i,j,k) is considered to be at the center of the corresponding voxel. This is in contrast with TRK’s internal convention where it would have referred to a corner.
Return an empty compliant TCK header as dict
Check if the file is in TCK format.
Parameters: | fileobj : string or file-like object
|
---|---|
Returns: | is_correct_format : {True, False}
|
Loads streamlines from a filename or file-like object.
Parameters: | fileobj : string or file-like object
lazy_load : {False, True}, optional
|
---|---|
Returns: | tck_file : TckFile object
|
Notes
Streamlines of the tractogram are assumed to be in RAS+ and mm space. It is also assumed that when streamlines are mapped back to voxel space, a streamline point located at an integer coordinate (i,j,k) is considered to be at the center of the corresponding voxel. This is in contrast with TRK’s internal convention where it would have referred to a corner.
Save tractogram to a filename or file-like object using TCK format.
Parameters: | fileobj : string or file-like object
|
---|
Bases: _abcoll.MutableMapping
Dictionary of generator functions.
This container behaves like a dictionary but it makes sure its elements are callable objects that it assumes are generator functions yielding values. When getting the element associated with a given key, the element (i.e. a generator function) is first called before being returned.
Bases: nibabel.streamlines.tractogram.Tractogram
Lazy container for streamlines and their data information.
This container behaves lazily as it uses generator functions to manage streamlines and their data information. This container is thus memory friendly since it doesn’t require having all this data loaded in memory.
Streamlines of a tractogram can be in any coordinate system of your choice as long as you provide the correct affine_to_rasmm matrix, at construction time. When applied to streamlines coordinates, that transformation matrix should bring the streamlines back to world space (RAS+ and mm space) [1]_.
Moreover, when streamlines are mapped back to voxel space [2]_, a streamline point located at an integer coordinate (i,j,k) is considered to be at the center of the corresponding voxel. This is in contrast with other conventions where it might have referred to a corner.
Notes
LazyTractogram objects do not support indexing currently. LazyTractogram objects are suited for operations that can be linearized such as applying an affine transformation or converting streamlines from one file format to another.
References
[1] http://nipy.org/nibabel/coordinate_systems.html#naming-reference-spaces [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
Attributes
streamlines | |
data_per_streamline | |
data_per_point |
Parameters: | streamlines : generator function, optional
data_per_streamline : dict of generator functions, optional
data_per_point : dict of generator functions, optional
affine_to_rasmm : ndarray of shape (4, 4) or None, optional
|
---|
Parameters: | streamlines : generator function, optional
data_per_streamline : dict of generator functions, optional
data_per_point : dict of generator functions, optional
affine_to_rasmm : ndarray of shape (4, 4) or None, optional
|
---|
Applies an affine transformation to the streamlines.
The transformation given by the affine matrix is applied after any other pending transformations to the streamline points.
Parameters: | affine : 2D array (4,4)
lazy : True, optional
|
---|---|
Returns: | lazy_tractogram : LazyTractogram object
|
Returns a copy of this LazyTractogram object.
Creates an instance from a generator function.
The generator function must yield TractogramItem objects.
Parameters: | data_func : generator function yielding TractogramItem objects
|
---|---|
Returns: | lazy_tractogram : LazyTractogram object
|
Creates a LazyTractogram object from a Tractogram object.
Parameters: | tractogram : Tractgogram object
|
---|---|
Returns: | lazy_tractogram : LazyTractogram object
|
Brings the streamlines to world space (i.e. RAS+ and mm).
The transformation is applied after any other pending transformations to the streamline points.
Parameters: | lazy : True, optional
|
---|---|
Returns: | lazy_tractogram : LazyTractogram object
|
Bases: nibabel.streamlines.tractogram.SliceableDataDict
Dictionary for which key access can do slicing on the values.
This container behaves like a standard dictionary but extends key access to allow keys for key access to be indices slicing into the contained ndarray values. The elements must also be ndarrays.
In addition, it makes sure the amount of data contained in those ndarrays matches the number of streamlines given at the instantiation of this instance.
Parameters: | n_rows : None or int, optional
*args : : **kwargs : :
|
---|
Appends the elements of another PerArrayDict.
That is, for each entry in this dictionary, we append the elements coming from the other dictionary at the corresponding entry.
Parameters: | other : PerArrayDict object
|
---|---|
Returns: | None : |
Notes
The keys in both dictionaries must be the same.
Bases: nibabel.streamlines.tractogram.PerArrayDict
Dictionary for which key access can do slicing on the values.
This container behaves like a standard dictionary but extends key access to allow keys for key access to be indices slicing into the contained ndarray values. The elements must also be ArraySequence.
In addition, it makes sure the amount of data contained in those array sequences matches the number of elements given at the instantiation of the instance.
Bases: _abcoll.MutableMapping
Dictionary for which key access can do slicing on the values.
This container behaves like a standard dictionary but extends key access to allow keys for key access to be indices slicing into the contained ndarray values.
Parameters: | *args : : **kwargs : :
|
---|
Bases: object
Container for streamlines and their data information.
Streamlines of a tractogram can be in any coordinate system of your choice as long as you provide the correct affine_to_rasmm matrix, at construction time. When applied to streamlines coordinates, that transformation matrix should bring the streamlines back to world space (RAS+ and mm space) [1]_.
Moreover, when streamlines are mapped back to voxel space [2]_, a streamline point located at an integer coordinate (i,j,k) is considered to be at the center of the corresponding voxel. This is in contrast with other conventions where it might have referred to a corner.
References
[1] http://nipy.org/nibabel/coordinate_systems.html#naming-reference-spaces [2] http://nipy.org/nibabel/coordinate_systems.html#voxel-coordinates-are-in-voxel-space
Attributes
streamlines | |
data_per_streamline | |
data_per_point |
Parameters: | streamlines : iterable of ndarrays or ArraySequence, optional
data_per_streamline : dict of iterable of ndarrays, optional
data_per_point : dict of iterable of ndarrays, optional
affine_to_rasmm : ndarray of shape (4, 4) or None, optional
|
---|
Parameters: | streamlines : iterable of ndarrays or ArraySequence, optional
data_per_streamline : dict of iterable of ndarrays, optional
data_per_point : dict of iterable of ndarrays, optional
affine_to_rasmm : ndarray of shape (4, 4) or None, optional
|
---|
Affine bringing streamlines in this tractogram to RAS+mm.
Applies an affine transformation on the points of each streamline.
If lazy is not specified, this is performed in-place.
Parameters: | affine : ndarray of shape (4, 4)
lazy : {False, True}, optional
|
---|---|
Returns: | tractogram : Tractogram or LazyTractogram object
|
Returns a copy of this Tractogram object.
Appends the data of another Tractogram.
Data that will be appended includes the streamlines and the content of both dictionaries data_per_streamline and data_per_point.
Parameters: | other : Tractogram object
|
---|---|
Returns: | None : |
Notes
The entries in both dictionaries self.data_per_streamline and self.data_per_point must match respectively those contained in the other tractogram.
Brings the streamlines to world space (i.e. RAS+ and mm).
If lazy is not specified, this is performed in-place.
Parameters: | lazy : {False, True}, optional
|
---|---|
Returns: | tractogram : Tractogram or LazyTractogram object
|
Bases: object
Class containing information about one streamline.
TractogramItem objects have three public attributes: streamline, data_for_streamline, and data_for_points.
Parameters: | streamline : ndarray shape (N, 3)
data_for_streamline : dict
data_for_points : dict
|
---|
True if obj seems to implement the DataDict API
Bases: object
Convenience class to encapsulate tractogram file format.
voxmm -> rasmm affine.
Returns an empty header for this streamlines file format.
Checks if the file has the right streamlines file format.
Parameters: | fileobj : string or file-like object
|
---|---|
Returns: | is_correct_format : {True, False}
|
Loads streamlines from a filename or file-like object.
Parameters: | fileobj : string or file-like object
lazy_load : {False, True}, optional
|
---|---|
Returns: | tractogram_file : TractogramFile object
|
Saves streamlines to a filename or file-like object.
Parameters: | fileobj : string or file-like object
|
---|
Bases: nibabel.streamlines.tractogram_file.TractogramFile
Convenience class to encapsulate TRK file format.
Notes
TrackVis (so its file format: TRK) considers the streamline coordinate (0,0,0) to be in the corner of the voxel whereas NiBabel’s streamlines internal representation (Voxel space) assumes (0,0,0) to be in the center of the voxel.
Thus, streamlines are shifted by half a voxel on load and are shifted back on save.
Parameters: | tractogram : Tractogram object
header : dict, optional
|
---|
Notes
Streamlines of the tractogram are assumed to be in RAS+ and mm space where coordinate (0,0,0) refers to the center of the voxel.
Parameters: | tractogram : Tractogram object
header : dict, optional
|
---|
Notes
Streamlines of the tractogram are assumed to be in RAS+ and mm space where coordinate (0,0,0) refers to the center of the voxel.
Return an empty compliant TRK header as dict
Check if the file is in TRK format.
Parameters: | fileobj : string or file-like object
|
---|---|
Returns: | is_correct_format : {True, False}
|
Loads streamlines from a filename or file-like object.
Parameters: | fileobj : string or file-like object
lazy_load : {False, True}, optional
|
---|---|
Returns: | trk_file : TrkFile object
|
Notes
Streamlines of the returned tractogram are assumed to be in RAS and mm space where coordinate (0,0,0) refers to the center of the voxel.
Save tractogram to a filename or file-like object using TRK format.
Parameters: | fileobj : string or file-like object
|
---|
Decodes a value that has been encoded in the last bytes of a string.
Check encode_value_in_name() to see how the value has been encoded.
Parameters: | encoded_name : bytes
|
---|---|
Returns: | name : bytes
value : int
|
Return name as fixed-length string, appending value as string.
Form output from name if value <= 1 else name + \ + str(value).
Return output as fixed length string length max_name_len, padded with \.
This function also verifies that the modified length of name is less than max_name_len.
Parameters: | value : int
name : str
max_name_len : int, optional
|
---|---|
Returns: | encoded_name : bytes
|
Get affine mapping trackvis voxelmm space to RAS+ mm space
The streamlines in a trackvis file are in ‘voxelmm’ space, where the coordinates refer to the corner of the voxel.
Compute the affine matrix that will bring them back to RAS+ mm space, where the coordinates refer to the center of the voxel.
Parameters: | header : dict or ndarray
|
---|---|
Returns: | aff_tv2ras : shape (4, 4) array
|
Returns the affine defining the reference space.
Parameters: | ref : str or Nifti1Image object or ndarray shape (4, 4)
|
---|---|
Returns: | affine : ndarray (4, 4)
|