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. |
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. |
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. |
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. |
create_empty_header() | Return an empty compliant TRK header. |
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.
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: _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 lazy tractogram can be in any coordinate system of your choice as long as you provide the correct affine_to_rasmm matrix, at construction time, that brings the streamlines back to RAS+, mm space, where the coordinates (0,0,0) corresponds to the center of the voxel (as opposed to the corner of the voxel).
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.
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 : :
|
---|
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, that brings the streamlines back to RAS+, mm space, where the coordinates (0,0,0) corresponds to the center of the voxel (as opposed to the corner of the voxel).
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.
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: abc.NewBase
Convenience class to encapsulate tractogram file format.
voxmm -> rasmm affine.
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.
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
|
---|
Return an empty compliant TRK header.
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
|
---|---|
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)
|