streamlines
¶
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. |
Module: streamlines.array_sequence
¶
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) |
Module: streamlines.header
¶
Field class defining common header fields in tractogram files
Field |
Header fields common to multiple streamline file formats. |
Module: streamlines.tractogram
¶
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 |
Module: streamlines.tractogram_file
¶
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) |
Module: streamlines.trk
¶
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 |
Module: streamlines.utils
¶
get_affine_from_reference (ref) |
Returns the affine defining the reference space. |
detect_format¶
-
nibabel.streamlines.
detect_format
(fileobj)¶ Returns the StreamlinesFile object guessed from the file-like object.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object pointing to a tractogram file (and ready to read from the beginning of the header)
Returns: tractogram_file :
TractogramFile
classThe class type guessed from the content of fileobj.
is_supported¶
-
nibabel.streamlines.
is_supported
(fileobj)¶ Checks if the file-like object if supported by NiBabel.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object pointing to a streamlines file (and ready to read from the beginning of the header)
Returns: is_supported : boolean
load¶
-
nibabel.streamlines.
load
(fileobj, lazy_load=False)¶ Loads streamlines in RAS+ and mm space from a file-like object.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object pointing to a streamlines file (and ready to read from the beginning of the streamlines file’s header).
lazy_load : {False, True}, optional
If True, load streamlines in a lazy manner i.e. they will not be kept in memory and only be loaded when needed. Otherwise, load all streamlines in memory.
Returns: tractogram_file :
TractogramFile
objectReturns an instance of a
TractogramFile
containing data and metadata of the tractogram loaded from fileobj.Notes
The streamline coordinate (0,0,0) refers to the center of the voxel.
save¶
-
nibabel.streamlines.
save
(tractogram, filename, **kwargs)¶ Saves a tractogram to a file.
Parameters: tractogram :
Tractogram
object orTractogramFile
objectIf
Tractogram
object, the file format will be guessed from filename and aTractogramFile
object will be created using provided keyword arguments. IfTractogramFile
object, the file format is known and will be used to save its content to filename.filename : str
Name of the file where the tractogram will be saved.
**kwargs : keyword arguments
Keyword arguments passed to
TractogramFile
constructor. Should not be specified if tractogram is already an instance ofTractogramFile
.
ArraySequence
¶
-
class
nibabel.streamlines.array_sequence.
ArraySequence
(iterable=None, buffer_size=4)¶ 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
, optionalIf None, create an empty
ArraySequence
object. If iterable, create aArraySequence
object initialized from array-like objects yielded by the iterable. IfArraySequence
, create a view (no memory is allocated). For an actual copy usecopy()
instead.buffer_size : float, optional
Size (in Mb) for memory allocation when iterable is a generator.
-
__init__
(iterable=None, buffer_size=4)¶ Initialize array sequence instance
Parameters: iterable : None or iterable or
ArraySequence
, optionalIf None, create an empty
ArraySequence
object. If iterable, create aArraySequence
object initialized from array-like objects yielded by the iterable. IfArraySequence
, create a view (no memory is allocated). For an actual copy usecopy()
instead.buffer_size : float, optional
Size (in Mb) for memory allocation when iterable is a generator.
-
append
(element, cache_build=False)¶ 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 usecache_build=True
, you need to finalize the append operations withfinalize_append()
.Parameters: element : ndarray
Element to append. The shape must match already inserted elements shape except for the first dimension.
cache_build : {False, True}
Whether to save the build cache from this append routine. If True, append can assume it is the only player updating self, and the caller must finalize self after all append operations, with
self.finalize_append()
.Returns: None
Notes
If you need to add multiple elements you should consider ArraySequence.extend.
-
common_shape
¶ Matching shape of the elements in this array sequence.
-
copy
()¶ Creates a copy of this
ArraySequence
object.Returns: seq_copy :
ArraySequence
instanceCopy of self.
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.
-
data
¶ Elements in this array sequence.
-
extend
(elements)¶ Appends all elements to this array sequence.
Parameters: elements : iterable of ndarrays or
ArraySequence
objectIf iterable of ndarrays, each ndarray will be concatenated along the first dimension then appended to the data of this ArraySequence. If
ArraySequence
object, its data are simply appended to the data of this ArraySequence.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_append
()¶ 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, usecache_build=True
. This method finalizes the series of append operations after a call toappend()
withcache_build=True
.
-
is_array_sequence
¶
-
classmethod
load
(filename)¶ Loads a
ArraySequence
object from a .npz file.
-
save
(filename)¶ Saves this
ArraySequence
object to a .npz file.
-
shrink_data
()¶
-
total_nb_rows
¶ Total number of rows in this array sequence.
-
create_arraysequences_from_generator¶
-
nibabel.streamlines.array_sequence.
create_arraysequences_from_generator
(gen, n)¶ Creates
ArraySequence
objects from a generator yielding tuplesParameters: gen : generator
Generator yielding a size n tuple containing the values to put in the array sequences.
n : int
Number of
ArraySequences
object to create.
is_array_sequence¶
-
nibabel.streamlines.array_sequence.
is_array_sequence
(obj)¶ Return True if obj is an array sequence.
Field
¶
-
class
nibabel.streamlines.header.
Field
¶ Bases:
object
Header fields common to multiple streamline file formats.
In IPython, use nibabel.streamlines.Field?? to list them.
-
__init__
()¶ x.__init__(...) initializes x; see help(type(x)) for signature
-
DIMENSIONS
= 'dimensions'¶
-
ENDIANNESS
= 'endianness'¶
-
MAGIC_NUMBER
= 'magic_number'¶
-
METHOD
= 'method'¶
-
NB_POINTS
= 'nb_points'¶
-
NB_PROPERTIES_PER_STREAMLINE
= 'nb_properties_per_streamline'¶
-
NB_SCALARS_PER_POINT
= 'nb_scalars_per_point'¶
-
NB_STREAMLINES
= 'nb_streamlines'¶
-
ORIGIN
= 'origin'¶
-
STEP_SIZE
= 'step_size'¶
-
VOXEL_ORDER
= 'voxel_order'¶
-
VOXEL_SIZES
= 'voxel_sizes'¶
-
VOXEL_TO_RASMM
= 'voxel_to_rasmm'¶
-
LazyDict
¶
-
class
nibabel.streamlines.tractogram.
LazyDict
(*args, **kwargs)¶ 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.
-
__init__
(*args, **kwargs)¶
-
LazyTractogram
¶
-
class
nibabel.streamlines.tractogram.
LazyTractogram
(streamlines=None, data_per_streamline=None, data_per_point=None, affine_to_rasmm=None)¶ 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 (generator function) Generator function yielding streamlines. Each streamline is an ndarray of shape ($N_t$, 3) where $N_t$ is the number of points of streamline $t$. data_per_streamline (instance of LazyDict
) Dictionary where the items are (str, instantiated generator). Each key represents a piece of information $i$ to be kept alongside every streamline, and its associated value is a generator function yielding that information via ndarrays of shape ($P_i$,) where $P_i$ is the number of values to store for that particular piece of information $i$.data_per_point ( LazyDict
object) Dictionary where the items are (str, instantiated generator). Each key represents a piece of information $i$ to be kept alongside every point of every streamline, and its associated value is a generator function yielding that information via ndarrays of shape ($N_t$, $M_i$) where $N_t$ is the number of points for a particular streamline $t$ and $M_i$ is the number of values to store for that particular piece of information $i$.Parameters: streamlines : generator function, optional
Generator function yielding streamlines. Each streamline is an ndarray of shape ($N_t$, 3) where $N_t$ is the number of points of streamline $t$.
data_per_streamline : dict of generator functions, optional
Dictionary where the items are (str, generator function). Each key represents an information $i$ to be kept alongside every streamline, and its associated value is a generator function yielding that information via ndarrays of shape ($P_i$,) where $P_i$ is the number of values to store for that particular information $i$.
data_per_point : dict of generator functions, optional
Dictionary where the items are (str, generator function). Each key represents an information $i$ to be kept alongside every point of every streamline, and its associated value is a generator function yielding that information via ndarrays of shape ($N_t$, $M_i$) where $N_t$ is the number of points for a particular streamline $t$ and $M_i$ is the number of values to store for that particular information $i$.
affine_to_rasmm : ndarray of shape (4, 4) or None, optional
Transformation matrix that brings the streamlines contained in this tractogram to RAS+ and mm space where coordinate (0,0,0) refers to the center of the voxel. By default, the streamlines are in an unknown space, i.e. affine_to_rasmm is None.
-
__init__
(streamlines=None, data_per_streamline=None, data_per_point=None, affine_to_rasmm=None)¶ Parameters: streamlines : generator function, optional
Generator function yielding streamlines. Each streamline is an ndarray of shape ($N_t$, 3) where $N_t$ is the number of points of streamline $t$.
data_per_streamline : dict of generator functions, optional
Dictionary where the items are (str, generator function). Each key represents an information $i$ to be kept alongside every streamline, and its associated value is a generator function yielding that information via ndarrays of shape ($P_i$,) where $P_i$ is the number of values to store for that particular information $i$.
data_per_point : dict of generator functions, optional
Dictionary where the items are (str, generator function). Each key represents an information $i$ to be kept alongside every point of every streamline, and its associated value is a generator function yielding that information via ndarrays of shape ($N_t$, $M_i$) where $N_t$ is the number of points for a particular streamline $t$ and $M_i$ is the number of values to store for that particular information $i$.
affine_to_rasmm : ndarray of shape (4, 4) or None, optional
Transformation matrix that brings the streamlines contained in this tractogram to RAS+ and mm space where coordinate (0,0,0) refers to the center of the voxel. By default, the streamlines are in an unknown space, i.e. affine_to_rasmm is None.
-
apply_affine
(affine, lazy=True)¶ 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)
Transformation matrix that will be applied on each streamline.
lazy : True, optional
Should always be True for
LazyTractogram
object. Doing otherwise will raise a ValueError.Returns: lazy_tractogram :
LazyTractogram
objectA copy of this
LazyTractogram
instance but with a transformation to be applied on the streamlines.
-
copy
()¶ Returns a copy of this
LazyTractogram
object.
-
data
¶
-
data_per_point
¶
-
data_per_streamline
¶
-
classmethod
from_data_func
(data_func)¶ Creates an instance from a generator function.
The generator function must yield
TractogramItem
objects.Parameters: data_func : generator function yielding
TractogramItem
objectsGenerator function that whenever is called starts yielding
TractogramItem
objects that will be used to instantiate aLazyTractogram
.Returns: lazy_tractogram :
LazyTractogram
objectNew lazy tractogram.
-
classmethod
from_tractogram
(tractogram)¶ Creates a
LazyTractogram
object from aTractogram
object.Parameters: tractogram :
Tractgogram
objectTractogram from which to create a
LazyTractogram
object.Returns: lazy_tractogram :
LazyTractogram
objectNew lazy tractogram.
-
streamlines
¶
-
to_world
(lazy=True)¶ 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
Should always be True for
LazyTractogram
object. Doing otherwise will raise a ValueError.Returns: lazy_tractogram :
LazyTractogram
objectA copy of this
LazyTractogram
instance but with a transformation to be applied on the streamlines.
-
PerArrayDict
¶
-
class
nibabel.streamlines.tractogram.
PerArrayDict
(n_rows=None, *args, **kwargs)¶ 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
Number of rows per value in each key, value pair or None for not specified.
*args :
**kwargs :
Positional and keyword arguments, passed straight through the
dict
constructor.-
__init__
(n_rows=None, *args, **kwargs)¶
-
PerArraySequenceDict
¶
-
class
nibabel.streamlines.tractogram.
PerArraySequenceDict
(n_rows=None, *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.
-
__init__
(n_rows=None, *args, **kwargs)¶
-
SliceableDataDict
¶
-
class
nibabel.streamlines.tractogram.
SliceableDataDict
(*args, **kwargs)¶ 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 :
Positional and keyword arguments, passed straight through the
dict
constructor.-
__init__
(*args, **kwargs)¶
-
Tractogram
¶
-
class
nibabel.streamlines.tractogram.
Tractogram
(streamlines=None, data_per_streamline=None, data_per_point=None, affine_to_rasmm=None)¶ 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 ( ArraySequence
object) Sequence of $T$ streamlines. Each streamline is an ndarray of shape ($N_t$, 3) where $N_t$ is the number of points of streamline $t$.data_per_streamline ( PerArrayDict
object) Dictionary where the items are (str, 2D array). Each key represents a piece of information $i$ to be kept alongside every streamline, and its associated value is a 2D array of shape ($T$, $P_i$) where $T$ is the number of streamlines and $P_i$ is the number of values to store for that particular piece of information $i$.data_per_point ( PerArraySequenceDict
object) Dictionary where the items are (str,ArraySequence
). Each key represents a piece of information $i$ to be kept alongside every point of every streamline, and its associated value is an iterable of ndarrays of shape ($N_t$, $M_i$) where $N_t$ is the number of points for a particular streamline $t$ and $M_i$ is the number values to store for that particular piece of information $i$.Parameters: streamlines : iterable of ndarrays or
ArraySequence
, optionalSequence of $T$ streamlines. Each streamline is an ndarray of shape ($N_t$, 3) where $N_t$ is the number of points of streamline $t$.
data_per_streamline : dict of iterable of ndarrays, optional
Dictionary where the items are (str, iterable). Each key represents an information $i$ to be kept alongside every streamline, and its associated value is an iterable of ndarrays of shape ($P_i$,) where $P_i$ is the number of scalar values to store for that particular information $i$.
data_per_point : dict of iterable of ndarrays, optional
Dictionary where the items are (str, iterable). Each key represents an information $i$ to be kept alongside every point of every streamline, and its associated value is an iterable of ndarrays of shape ($N_t$, $M_i$) where $N_t$ is the number of points for a particular streamline $t$ and $M_i$ is the number scalar values to store for that particular information $i$.
affine_to_rasmm : ndarray of shape (4, 4) or None, optional
Transformation matrix that brings the streamlines contained in this tractogram to RAS+ and mm space where coordinate (0,0,0) refers to the center of the voxel. By default, the streamlines are in an unknown space, i.e. affine_to_rasmm is None.
-
__init__
(streamlines=None, data_per_streamline=None, data_per_point=None, affine_to_rasmm=None)¶ Parameters: streamlines : iterable of ndarrays or
ArraySequence
, optionalSequence of $T$ streamlines. Each streamline is an ndarray of shape ($N_t$, 3) where $N_t$ is the number of points of streamline $t$.
data_per_streamline : dict of iterable of ndarrays, optional
Dictionary where the items are (str, iterable). Each key represents an information $i$ to be kept alongside every streamline, and its associated value is an iterable of ndarrays of shape ($P_i$,) where $P_i$ is the number of scalar values to store for that particular information $i$.
data_per_point : dict of iterable of ndarrays, optional
Dictionary where the items are (str, iterable). Each key represents an information $i$ to be kept alongside every point of every streamline, and its associated value is an iterable of ndarrays of shape ($N_t$, $M_i$) where $N_t$ is the number of points for a particular streamline $t$ and $M_i$ is the number scalar values to store for that particular information $i$.
affine_to_rasmm : ndarray of shape (4, 4) or None, optional
Transformation matrix that brings the streamlines contained in this tractogram to RAS+ and mm space where coordinate (0,0,0) refers to the center of the voxel. By default, the streamlines are in an unknown space, i.e. affine_to_rasmm is None.
-
affine_to_rasmm
¶ Affine bringing streamlines in this tractogram to RAS+mm.
-
apply_affine
(affine, lazy=False)¶ 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)
Transformation that will be applied to every streamline.
lazy : {False, True}, optional
If True, streamlines are not transformed in-place and a
LazyTractogram
object is returned. Otherwise, streamlines are modified in-place.Returns: tractogram :
Tractogram
orLazyTractogram
objectTractogram where the streamlines have been transformed according to the given affine transformation. If the lazy option is true, it returns a
LazyTractogram
object, otherwise it returns a reference to thisTractogram
object with updated streamlines.
-
copy
()¶ Returns a copy of this
Tractogram
object.
-
data_per_point
¶
-
data_per_streamline
¶
-
streamlines
¶
-
to_world
(lazy=False)¶ 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
If True, streamlines are not transformed in-place and a
LazyTractogram
object is returned. Otherwise, streamlines are modified in-place.Returns: tractogram :
Tractogram
orLazyTractogram
objectTractogram where the streamlines have been sent to world space. If the lazy option is true, it returns a
LazyTractogram
object, otherwise it returns a reference to thisTractogram
object with updated streamlines.
-
TractogramItem
¶
-
class
nibabel.streamlines.tractogram.
TractogramItem
(streamline, data_for_streamline, data_for_points)¶ 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)
Points of this streamline represented as an ndarray of shape (N, 3) where N is the number of points.
data_for_streamline : dict
Dictionary containing some data associated with this particular streamline. Each key
k
is mapped to a ndarray of shape (Pt,), wherePt
is the dimension of the data associated with keyk
.data_for_points : dict
Dictionary containing some data associated to each point of this particular streamline. Each key
k
is mapped to a ndarray of shape (Nt, Mk), whereNt
is the number of points of this streamline andMk
is the dimension of the data associated with keyk
.-
__init__
(streamline, data_for_streamline, data_for_points)¶
-
is_data_dict¶
-
nibabel.streamlines.tractogram.
is_data_dict
(obj)¶ True if obj seems to implement the
DataDict
API
is_lazy_dict¶
TractogramFile
¶
-
class
nibabel.streamlines.tractogram_file.
TractogramFile
(tractogram, header=None)¶ Bases:
abc.NewBase
Convenience class to encapsulate tractogram file format.
-
__init__
(tractogram, header=None)¶
-
affine
¶ voxmm -> rasmm affine.
-
header
¶
-
classmethod
is_correct_format
(fileobj)¶ Checks if the file has the right streamlines file format.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object pointing to a streamlines file (and ready to read from the beginning of the header).
Returns: is_correct_format : {True, False}
Returns True if fileobj is in the right streamlines file format, otherwise returns False.
-
classmethod
load
(fileobj, lazy_load=True)¶ Loads streamlines from a filename or file-like object.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object pointing to a streamlines file (and ready to read from the beginning of the header).
lazy_load : {False, True}, optional
If True, load streamlines in a lazy manner i.e. they will not be kept in memory. Otherwise, load all streamlines in memory.
Returns: tractogram_file :
TractogramFile
objectReturns an object containing tractogram data and header information.
-
save
(fileobj)¶ Saves streamlines to a filename or file-like object.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object opened and ready to write.
-
streamlines
¶
-
tractogram
¶
-
TrkFile
¶
-
class
nibabel.streamlines.trk.
TrkFile
(tractogram, header=None)¶ 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
objectTractogram that will be contained in this
TrkFile
.header : dict, optional
Metadata associated to this tractogram file.
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.
-
__init__
(tractogram, header=None)¶ Parameters: tractogram :
Tractogram
objectTractogram that will be contained in this
TrkFile
.header : dict, optional
Metadata associated to this tractogram file.
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.
-
HEADER_SIZE
= 1000¶
-
MAGIC_NUMBER
= 'TRACK'¶
-
SUPPORTS_DATA_PER_POINT
= True¶
-
SUPPORTS_DATA_PER_STREAMLINE
= True¶
-
classmethod
is_correct_format
(fileobj)¶ Check if the file is in TRK format.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object pointing to TRK file (and ready to read from the beginning of the TRK header data). Note that calling this function does not change the file position.
Returns: is_correct_format : {True, False}
Returns True if fileobj is compatible with TRK format, otherwise returns False.
-
classmethod
load
(fileobj, lazy_load=False)¶ Loads streamlines from a filename or file-like object.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object pointing to TRK file (and ready to read from the beginning of the TRK header). Note that calling this function does not change the file position.
lazy_load : {False, True}, optional
If True, load streamlines in a lazy manner i.e. they will not be kept in memory. Otherwise, load all streamlines in memory.
Returns: trk_file :
TrkFile
objectReturns an object containing tractogram data and header information.
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
(fileobj)¶ Save tractogram to a filename or file-like object using TRK format.
Parameters: fileobj : string or file-like object
If string, a filename; otherwise an open file-like object pointing to TRK file (and ready to write from the beginning of the TRK header data).
-
create_empty_header¶
-
nibabel.streamlines.trk.
create_empty_header
()¶ Return an empty compliant TRK header.
decode_value_from_name¶
-
nibabel.streamlines.trk.
decode_value_from_name
(encoded_name)¶ 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
Name in which a value has been encoded or not.
Returns: name : bytes
Name without the encoded value.
value : int
Value decoded from the name.
encode_value_in_name¶
-
nibabel.streamlines.trk.
encode_value_in_name
(value, name, max_name_len=20)¶ 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
Integer value to encode.
name : str
Name to which we may append an ascii / latin-1 representation of value.
max_name_len : int, optional
Maximum length of byte string that output can have.
Returns: encoded_name : bytes
Name maybe followed by
\
and ascii / latin-1 representation of value, padded with\
bytes.
get_affine_trackvis_to_rasmm¶
-
nibabel.streamlines.trk.
get_affine_trackvis_to_rasmm
(header)¶ 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
Dict containing trackvis header.
Returns: aff_tv2ras : shape (4, 4) array
Affine array mapping coordinates in ‘voxelmm’ space to RAS+ mm space.
get_affine_from_reference¶
-
nibabel.streamlines.utils.
get_affine_from_reference
(ref)¶ Returns the affine defining the reference space.
Parameters: ref : str or
Nifti1Image
object or ndarray shape (4, 4)If str then it’s the filename of reference file that will be loaded using
nibabel.load()
in order to obtain the affine. IfNifti1Image
object then the affine is obtained from it. If ndarray shape (4, 4) then it’s the affine.Returns: affine : ndarray (4, 4)
Transformation matrix mapping voxel space to RAS+mm space.