Loads streamlines in RAS+ and mm space from a file-like object.
Parameters:
fileobjstring 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_fileTractogramFile object
Returns 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.
tractogramTractogram object or TractogramFile object
If Tractogram object, the file format will be guessed from
filename and a TractogramFile object will be created using
provided keyword arguments.
If TractogramFile object, the file format is known and will
be used to save its content to filename.
filenamestr
Name of the file where the tractogram will be saved.
**kwargskeyword arguments
Keyword arguments passed to TractogramFile constructor.
Should not be specified if tractogram is already an instance of
TractogramFile.
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.
If None, create an empty ArraySequence object.
If iterable, create a ArraySequence object initialized
from array-like objects yielded by the iterable.
If ArraySequence, create a view (no memory is allocated).
For an actual copy use copy() instead.
buffer_sizefloat, optional
Size (in Mb) for memory allocation when iterable is a generator.
If None, create an empty ArraySequence object.
If iterable, create a ArraySequence object initialized
from array-like objects yielded by the iterable.
If ArraySequence, create a view (no memory is allocated).
For an actual copy use copy() instead.
buffer_sizefloat, optional
Size (in Mb) for memory allocation when iterable is a generator.
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:
elementndarray
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.
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.
elementsiterable of ndarrays or ArraySequence object
If 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 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.
Returns a copy of the elements in this array sequence.
Notes
To modify the data on this array sequence, one can use
in-place mathematical operators (e.g., seq += …) or the use
assignment operator (i.e, seq[…] = value).
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.
Parameters:
tractogramTractogram object
Tractogram that will be contained in this TckFile.
headerNone or dict, optional
Metadata associated to this tractogram file. If None, make
default empty header.
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.
Tractogram that will be contained in this TckFile.
headerNone or dict, optional
Metadata associated to this tractogram file. If None, make
default empty header.
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.
If string, a filename; otherwise an open file-like object in
binary mode pointing to TCK file (and ready to read from the
beginning of the TCK header). Note that calling this function
does not change the file position.
Returns:
is_correct_format{True, False}
Returns True if fileobj is compatible with TCK format,
otherwise returns False.
Loads streamlines from a filename or file-like object.
Parameters:
fileobjstring or file-like object
If string, a filename; otherwise an open file-like object in
binary mode pointing to TCK file (and ready to read from the
beginning of the TCK 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 an object containing tractogram data and header
information.
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:
fileobjstring or file-like object
If string, a filename; otherwise an open file-like object in
binary mode pointing to TCK file (and ready to write from the
beginning of the TCK header data).
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.
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) [3].
Moreover, when streamlines are mapped back to voxel space [4], 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.
Attributes:
streamlinesgenerator 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\).
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\).
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\).
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
Parameters:
streamlinesgenerator 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_streamlinedict 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_pointdict 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_rasmmndarray 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.
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_streamlinedict 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_pointdict 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_rasmmndarray 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.
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_rowsNone 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.
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.
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.
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) [5].
Moreover, when streamlines are mapped back to voxel space [6], 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.
Attributes:
streamlinesArraySequence 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\).
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\).
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\).
References
Parameters:
streamlinesiterable of ndarrays or ArraySequence, optional
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_streamlinedict 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_pointdict 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_rasmmndarray 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.
streamlinesiterable of ndarrays or ArraySequence, optional
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_streamlinedict 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_pointdict 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_rasmmndarray 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.
Tractogram 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 this Tractogram object with updated
streamlines.
Tractogram 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 this
Tractogram object with updated streamlines.
Class containing information about one streamline.
TractogramItem objects have three public attributes: streamline,
data_for_streamline, and data_for_points.
Parameters:
streamlinendarray shape (N, 3)
Points of this streamline represented as an ndarray of shape (N, 3)
where N is the number of points.
data_for_streamlinedict
Dictionary containing some data associated with this particular
streamline. Each key k is mapped to a ndarray of shape (Pt,), where
Pt is the dimension of the data associated with key k.
data_for_pointsdict
Dictionary containing some data associated to each point of this
particular streamline. Each key k is mapped to a ndarray of shape
(Nt, Mk), where Nt is the number of points of this streamline and
Mk is the dimension of the data associated with key k.
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:
tractogramTractogram object
Tractogram that will be contained in this TrkFile.
headerdict, 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.
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.
Loads streamlines from a filename or file-like object.
Parameters:
fileobjstring 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.
refstr 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.
If Nifti1Image object then the affine is obtained from it.
If ndarray shape (4, 4) then it’s the affine.
Returns:
affinendarray (4, 4)
Transformation matrix mapping voxel space to RAS+mm space.