io

References

Dpy

class dipy.io.Dpy(fname, mode='r', compression=0)

Bases: object

Methods

read_track()	read one track each time
read_tracks()	read the entire tractography
read_tracksi(indices)	read tracks with specific indices
write_track(track)	write on track each time
write_tracks(tracks)	write many tracks together

close
version

__init__(fname, mode='r', compression=0)

Advanced storage system for tractography based on HDF5

Parameters:	fname : str, full filename mode : ‘r’ read ‘w’ write ‘r+’ read and write only if file already exists compression : 0 no compression to 9 maximum compression

Examples

>>> import os
>>> from tempfile import mkstemp #temp file
>>> from dipy.io.dpy import Dpy
>>> def dpy_example():
...     fd,fname = mkstemp()
...     fname += '.dpy'#add correct extension
...     dpw = Dpy(fname,'w')
...     A=np.ones((5,3))
...     B=2*A.copy()
...     C=3*A.copy()
...     dpw.write_track(A)
...     dpw.write_track(B)
...     dpw.write_track(C)
...     dpw.close()
...     dpr = Dpy(fname,'r')
...     dpr.read_track()
...     dpr.read_track()
...     dpr.read_tracksi([0, 1, 2, 0, 0, 2])
...     dpr.close()
...     os.remove(fname) #delete file from disk
>>> dpy_example()

close()

read_track()

read one track each time

read_tracks()

read the entire tractography

read_tracksi(indices)

read tracks with specific indices

version()

write_track(track)

write on track each time

write_tracks(tracks)

write many tracks together

load_pickle

dipy.io.load_pickle(fname)

Load object from pickle file fname

Parameters:	fname : str filename to load dict or other python object
Returns:	dix : object dictionary or other object

Examples

dipy.io.pickles.save_pickle

orientation_from_string

dipy.io.orientation_from_string(string_ornt)

Returns an array representation of an ornt string

orientation_to_string

dipy.io.orientation_to_string(ornt)

Returns a string representation of a 3d ornt

ornt_mapping

dipy.io.ornt_mapping(ornt1, ornt2)

Calculates the mapping needing to get from orn1 to orn2

read_bvals_bvecs

dipy.io.read_bvals_bvecs(fbvals, fbvecs)

Read b-values and b-vectors from disk

Parameters:	fbvals : str Full path to file with b-values. None to not read bvals. fbvecs : str Full path of file with b-vectors. None to not read bvecs.
Returns:	bvals : array, (N,) or None bvecs : array, (N, 3) or None

Notes

Files can be either ‘.bvals’/’.bvecs’ or ‘.txt’ or ‘.npy’ (containing arrays stored with the appropriate values).

read_bvec_file

dipy.io.read_bvec_file(filename, atol=0.001)

Read gradient table information from a pair of files with extentions .bvec and .bval. The bval file should have one row of values representing the bvalues of each volume in the dwi data set. The bvec file should have three rows, where the rows are the x, y, and z components of the normalized gradient direction for each of the volumes.

Parameters:	filename : The path to the either the bvec or bval file atol : float, optional The tolorance used to check all the gradient directions are normalized. Defult is .001

reorient_on_axis

dipy.io.reorient_on_axis(input, current_ornt, new_ornt, axis=0)

reorient_vectors

dipy.io.reorient_vectors(input, current_ornt, new_ornt, axis=0)

Changes the orientation of a gradients or other vectors

Moves vectors, storted along axis, from current_ornt to new_ornt. For example the vector [x, y, z] in “RAS” will be [-x, -y, z] in “LPS”.

R: Right A: Anterior S: Superior L: Left P: Posterior I: Inferior

Examples

>>> gtab = np.array([[1, 1, 1], [1, 2, 3]])
>>> reorient_vectors(gtab, 'ras', 'asr', axis=1)
array([[1, 1, 1],
       [2, 3, 1]])
>>> reorient_vectors(gtab, 'ras', 'lps', axis=1)
array([[-1, -1,  1],
       [-1, -2,  3]])
>>> bvec = gtab.T
>>> reorient_vectors(bvec, 'ras', 'lps', axis=0)
array([[-1, -1],
       [-1, -2],
       [ 1,  3]])
>>> reorient_vectors(bvec, 'ras', 'lsp')
array([[-1, -1],
       [ 1,  3],
       [-1, -2]])

save_pickle

dipy.io.save_pickle(fname, dix)

Save dix to fname as pickle

Parameters:	fname : str filename to save object e.g. a dictionary dix : str dictionary or other object

See also

dipy.io.pickles.load_pickle

Examples

>>> import os
>>> from tempfile import mkstemp
>>> fd, fname = mkstemp() # make temporary file (opened, attached to fh)
>>> d={0:{'d':1}}
>>> save_pickle(fname, d)
>>> d2=load_pickle(fname)

We remove the temporary file we created for neatness

>>> os.close(fd) # the file is still open, we need to close the fh
>>> os.remove(fname)

orientation_from_string

dipy.io.bvectxt.orientation_from_string(string_ornt)

Returns an array representation of an ornt string

orientation_to_string

dipy.io.bvectxt.orientation_to_string(ornt)

Returns a string representation of a 3d ornt

ornt_mapping

dipy.io.bvectxt.ornt_mapping(ornt1, ornt2)

Calculates the mapping needing to get from orn1 to orn2

read_bvec_file

dipy.io.bvectxt.read_bvec_file(filename, atol=0.001)

Read gradient table information from a pair of files with extentions .bvec and .bval. The bval file should have one row of values representing the bvalues of each volume in the dwi data set. The bvec file should have three rows, where the rows are the x, y, and z components of the normalized gradient direction for each of the volumes.

Parameters:	filename : The path to the either the bvec or bval file atol : float, optional The tolorance used to check all the gradient directions are normalized. Defult is .001

reorient_on_axis

dipy.io.bvectxt.reorient_on_axis(input, current_ornt, new_ornt, axis=0)

reorient_vectors

dipy.io.bvectxt.reorient_vectors(input, current_ornt, new_ornt, axis=0)

Changes the orientation of a gradients or other vectors

Moves vectors, storted along axis, from current_ornt to new_ornt. For example the vector [x, y, z] in “RAS” will be [-x, -y, z] in “LPS”.

R: Right A: Anterior S: Superior L: Left P: Posterior I: Inferior

Examples

>>> gtab = np.array([[1, 1, 1], [1, 2, 3]])
>>> reorient_vectors(gtab, 'ras', 'asr', axis=1)
array([[1, 1, 1],
       [2, 3, 1]])
>>> reorient_vectors(gtab, 'ras', 'lps', axis=1)
array([[-1, -1,  1],
       [-1, -2,  3]])
>>> bvec = gtab.T
>>> reorient_vectors(bvec, 'ras', 'lps', axis=0)
array([[-1, -1],
       [-1, -2],
       [ 1,  3]])
>>> reorient_vectors(bvec, 'ras', 'lsp')
array([[-1, -1],
       [ 1,  3],
       [-1, -2]])

splitext

dipy.io.bvectxt.splitext(p)

Split the extension from a pathname.

Extension is everything from the last dot to the end, ignoring leading dots. Returns “(root, ext)”; ext may be empty.

Dpy

class dipy.io.dpy.Dpy(fname, mode='r', compression=0)

Bases: object

Methods

read_track()	read one track each time
read_tracks()	read the entire tractography
read_tracksi(indices)	read tracks with specific indices
write_track(track)	write on track each time
write_tracks(tracks)	write many tracks together

close
version

__init__(fname, mode='r', compression=0)

Advanced storage system for tractography based on HDF5

Parameters:	fname : str, full filename mode : ‘r’ read ‘w’ write ‘r+’ read and write only if file already exists compression : 0 no compression to 9 maximum compression

Examples

>>> import os
>>> from tempfile import mkstemp #temp file
>>> from dipy.io.dpy import Dpy
>>> def dpy_example():
...     fd,fname = mkstemp()
...     fname += '.dpy'#add correct extension
...     dpw = Dpy(fname,'w')
...     A=np.ones((5,3))
...     B=2*A.copy()
...     C=3*A.copy()
...     dpw.write_track(A)
...     dpw.write_track(B)
...     dpw.write_track(C)
...     dpw.close()
...     dpr = Dpy(fname,'r')
...     dpr.read_track()
...     dpr.read_track()
...     dpr.read_tracksi([0, 1, 2, 0, 0, 2])
...     dpr.close()
...     os.remove(fname) #delete file from disk
>>> dpy_example()

close()

read_track()

read one track each time

read_tracks()

read the entire tractography

read_tracksi(indices)

read tracks with specific indices

version()

write_track(track)

write on track each time

write_tracks(tracks)

write many tracks together

Streamlines

dipy.io.dpy.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

InTemporaryDirectory

class dipy.io.gradients.InTemporaryDirectory(suffix='', prefix='tmp', dir=None)

Bases: nibabel.tmpdirs.TemporaryDirectory

Create, return, and change directory to a temporary directory

Examples

>>> import os
>>> my_cwd = os.getcwd()
>>> with InTemporaryDirectory() as tmpdir:
...     _ = open('test.txt', 'wt').write('some text')
...     assert os.path.isfile('test.txt')
...     assert os.path.isfile(os.path.join(tmpdir, 'test.txt'))
>>> os.path.exists(tmpdir)
False
>>> os.getcwd() == my_cwd
True

Methods

cleanup

__init__(suffix='', prefix='tmp', dir=None)

Initialize self. See help(type(self)) for accurate signature.

read_bvals_bvecs

dipy.io.gradients.read_bvals_bvecs(fbvals, fbvecs)

Read b-values and b-vectors from disk

Parameters:	fbvals : str Full path to file with b-values. None to not read bvals. fbvecs : str Full path of file with b-vectors. None to not read bvecs.
Returns:	bvals : array, (N,) or None bvecs : array, (N, 3) or None

Notes

Files can be either ‘.bvals’/’.bvecs’ or ‘.txt’ or ‘.npy’ (containing arrays stored with the appropriate values).

splitext

dipy.io.gradients.splitext(p)

Split the extension from a pathname.

Extension is everything from the last dot to the end, ignoring leading dots. Returns “(root, ext)”; ext may be empty.

load_nifti

dipy.io.image.load_nifti(fname, return_img=False, return_voxsize=False, return_coords=False)

save_nifti

dipy.io.image.save_nifti(fname, data, affine, hdr=None)

save_qa_metric

dipy.io.image.save_qa_metric(fname, xopt, fopt)

Save Quality Assurance metrics.

Parameters:	fname: string File name to save the metric values. xopt: numpy array The metric containing the optimal parameters for image registration. fopt: int The distance between the registered images.

PeaksAndMetrics

class dipy.io.peaks.PeaksAndMetrics

Bases: dipy.reconst.peak_direction_getter.PeaksAndMetricsDirectionGetter

Attributes:	ang_thr qa_thr total_weight

Methods

initial_direction

The best starting directions for fiber tracking from point

get_direction

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

Sphere

class dipy.io.peaks.Sphere(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)

Bases: object

Points on the unit sphere.

The sphere can be constructed using one of three conventions:

Sphere(x, y, z)
Sphere(xyz=xyz)
Sphere(theta=theta, phi=phi)

Parameters:

x, y, z : 1-D array_like Vertices as x-y-z coordinates. theta, phi : 1-D array_like Vertices as spherical coordinates. Theta and phi are the inclination and azimuth angles respectively. xyz : (N, 3) ndarray Vertices as x-y-z coordinates. faces : (N, 3) ndarray Indices into vertices that form triangular faces. If unspecified, the faces are computed using a Delaunay triangulation. edges : (N, 2) ndarray Edges between vertices. If unspecified, the edges are derived from the faces.

Attributes:

x y z

Methods

find_closest(xyz)	Find the index of the vertex in the Sphere closest to the input vector
subdivide([n])	Subdivides each face of the sphere into four new faces.

edges
faces
vertices

__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)

Initialize self. See help(type(self)) for accurate signature.

edges()

faces()

find_closest(xyz)

Find the index of the vertex in the Sphere closest to the input vector

Parameters:	xyz : array-like, 3 elements A unit vector

subdivide(n=1)

Subdivides each face of the sphere into four new faces.

New vertices are created at a, b, and c. Then each face [x, y, z] is divided into faces [x, a, c], [y, a, b], [z, b, c], and [a, b, c].

   y
   /               /               a/____
/\    /            /  \  /             /____\/____          x      c     z

Parameters:	n : int, optional The number of subdivisions to preform.
Returns:	new_sphere : Sphere The subdivided sphere.

vertices()

x

y

z

load_peaks

dipy.io.peaks.load_peaks(fname, verbose=False)

Load a PeaksAndMetrics HDF5 file (PAM5)

Parameters:	fname : string Filename of PAM5 file. verbose : bool Print summary information about the loaded file.
Returns:	pam : PeaksAndMetrics object

peaks_to_niftis

dipy.io.peaks.peaks_to_niftis(pam, fname_shm, fname_dirs, fname_values, fname_indices, fname_gfa, reshape_dirs=False)

Save SH, directions, indices and values of peaks to Nifti.

reshape_peaks_for_visualization

dipy.io.peaks.reshape_peaks_for_visualization(peaks)

Reshape peaks for visualization.

Reshape and convert to float32 a set of peaks for visualisation with mrtrix or the fibernavigator.

save_nifti

dipy.io.peaks.save_nifti(fname, data, affine, hdr=None)

save_peaks

dipy.io.peaks.save_peaks(fname, pam, affine=None, verbose=False)

Save all important attributes of object PeaksAndMetrics in a PAM5 file (HDF5).

Parameters:	fname : string Filename of PAM5 file pam : PeaksAndMetrics Object holding peak_dirs, shm_coeffs and other attributes affine : array The 4x4 matrix transforming the date from native to world coordinates. PeaksAndMetrics should have that attribute but if not it can be provided here. Default None. verbose : bool Print summary information about the saved file.

load_pickle

dipy.io.pickles.load_pickle(fname)

Load object from pickle file fname

Parameters:	fname : str filename to load dict or other python object
Returns:	dix : object dictionary or other object

Examples

dipy.io.pickles.save_pickle

save_pickle

dipy.io.pickles.save_pickle(fname, dix)

Save dix to fname as pickle

Parameters:	fname : str filename to save object e.g. a dictionary dix : str dictionary or other object

See also

dipy.io.pickles.load_pickle

Examples

>>> import os
>>> from tempfile import mkstemp
>>> fd, fname = mkstemp() # make temporary file (opened, attached to fh)
>>> d={0:{'d':1}}
>>> save_pickle(fname, d)
>>> d2=load_pickle(fname)

We remove the temporary file we created for neatness

>>> os.close(fd) # the file is still open, we need to close the fh
>>> os.remove(fname)

Dpy

class dipy.io.streamline.Dpy(fname, mode='r', compression=0)

Bases: object

Methods

read_track()	read one track each time
read_tracks()	read the entire tractography
read_tracksi(indices)	read tracks with specific indices
write_track(track)	write on track each time
write_tracks(tracks)	write many tracks together

close
version

__init__(fname, mode='r', compression=0)

Advanced storage system for tractography based on HDF5

Parameters:	fname : str, full filename mode : ‘r’ read ‘w’ write ‘r+’ read and write only if file already exists compression : 0 no compression to 9 maximum compression

Examples

>>> import os
>>> from tempfile import mkstemp #temp file
>>> from dipy.io.dpy import Dpy
>>> def dpy_example():
...     fd,fname = mkstemp()
...     fname += '.dpy'#add correct extension
...     dpw = Dpy(fname,'w')
...     A=np.ones((5,3))
...     B=2*A.copy()
...     C=3*A.copy()
...     dpw.write_track(A)
...     dpw.write_track(B)
...     dpw.write_track(C)
...     dpw.close()
...     dpr = Dpy(fname,'r')
...     dpr.read_track()
...     dpr.read_track()
...     dpr.read_tracksi([0, 1, 2, 0, 0, 2])
...     dpr.close()
...     os.remove(fname) #delete file from disk
>>> dpy_example()

close()

read_track()

read one track each time

read_tracks()

read the entire tractography

read_tracksi(indices)

read tracks with specific indices

version()

write_track(track)

write on track each time

write_tracks(tracks)

write many tracks together

Field

class dipy.io.streamline.Field

Bases: object

Header fields common to multiple streamline file formats.

In IPython, use nibabel.streamlines.Field?? to list them.

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate 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'

LazyTractogram

class dipy.io.streamline.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 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 : 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\).

Methods

apply_affine(affine[, lazy])	Applies an affine transformation to the streamlines.
copy()	Returns a copy of this LazyTractogram object.
extend(other)	Appends the data of another Tractogram.
from_data_func(data_func)	Creates an instance from a generator function.
from_tractogram(tractogram)	Creates a LazyTractogram object from a Tractogram object.
to_world([lazy])	Brings the streamlines to world space (i.e.

__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 object A 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

extend(other)

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 Its data will be appended to the data of this tractogram.
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.

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 objects Generator function that whenever is called starts yielding TractogramItem objects that will be used to instantiate a LazyTractogram.
Returns:	lazy_tractogram : LazyTractogram object New lazy tractogram.

classmethod from_tractogram(tractogram)

Creates a LazyTractogram object from a Tractogram object.

Parameters:	tractogram : Tractgogram object Tractogram from which to create a LazyTractogram object.
Returns:	lazy_tractogram : LazyTractogram object New 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 object A copy of this LazyTractogram instance but with a transformation to be applied on the streamlines.

Streamlines

dipy.io.streamline.Streamlines

alias of nibabel.streamlines.array_sequence.ArraySequence

TckFile

class dipy.io.streamline.TckFile(tractogram, header=None)

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

Attributes:	affine voxmm -> rasmm affine. header streamlines tractogram

Methods

create_empty_header()	Return an empty compliant TCK header as dict
is_correct_format(fileobj)	Check if the file is in TCK format.
load(fileobj[, lazy_load])	Loads streamlines from a filename or file-like object.
save(fileobj)	Save tractogram to a filename or file-like object using TCK format.

__init__(tractogram, header=None)

Parameters:	tractogram : Tractogram object Tractogram that will be contained in this TckFile. header : None 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.

EOF_DELIMITER = array([[inf, inf, inf]], dtype=float32)

FIBER_DELIMITER = array([[nan, nan, nan]], dtype=float32)

MAGIC_NUMBER = 'mrtrix tracks'

SUPPORTS_DATA_PER_POINT = False

SUPPORTS_DATA_PER_STREAMLINE = False

classmethod create_empty_header()

Return an empty compliant TCK header as dict

classmethod is_correct_format(fileobj)

Check if the file is in TCK format.

Parameters:	fileobj : string 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.
Returns:	is_correct_format : {True, False} Returns True if fileobj is compatible with TCK 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 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:

tck_file : TckFile object 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(fileobj)

Save tractogram to a filename or file-like object using TCK format.

Parameters:	fileobj : string 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).

Tractogram

class dipy.io.streamline.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. 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 : 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\).

Methods

apply_affine(affine[, lazy])	Applies an affine transformation on the points of each streamline.
copy()	Returns a copy of this Tractogram object.
extend(other)	Appends the data of another Tractogram.
to_world([lazy])	Brings the streamlines to world space (i.e.

__init__(streamlines=None, data_per_streamline=None, data_per_point=None, affine_to_rasmm=None)

Parameters:

streamlines : iterable 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_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 or LazyTractogram object 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.

copy()

Returns a copy of this Tractogram object.

data_per_point

data_per_streamline

extend(other)

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 Its data will be appended to the data of this tractogram.
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.

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 or LazyTractogram object 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.

TrkFile

class dipy.io.streamline.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.

Attributes:	affine voxmm -> rasmm affine. header streamlines tractogram

Methods

create_empty_header()	Return an empty compliant TRK header as dict
is_correct_format(fileobj)	Check if the file is in TRK format.
load(fileobj[, lazy_load])	Loads streamlines from a filename or file-like object.
save(fileobj)	Save tractogram to a filename or file-like object using TRK format.

__init__(tractogram, header=None)

Parameters:	tractogram : Tractogram object Tractogram 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 = b'TRACK'

SUPPORTS_DATA_PER_POINT = True

SUPPORTS_DATA_PER_STREAMLINE = True

classmethod create_empty_header()

Return an empty compliant TRK header as dict

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 object Returns 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).

partial

class dipy.io.streamline.partial

Bases: object

partial(func, *args, **keywords) - new function with partial application of the given arguments and keywords.

Attributes:	args tuple of arguments to future partial calls func function object to use in future partial calls keywords dictionary of keyword arguments to future partial calls

Methods

__call__($self, /, *args, **kwargs)

Call self as a function.

__init__($self, /, *args, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

args

tuple of arguments to future partial calls

func

function object to use in future partial calls

keywords

dictionary of keyword arguments to future partial calls

aff2axcodes

dipy.io.streamline.aff2axcodes(aff, labels=None, tol=None)

axis direction codes for affine aff

Parameters:	aff : (N,M) array-like affine transformation matrix labels : optional, None or sequence of (2,) sequences Labels for negative and positive ends of output axes of aff. See docstring for ornt2axcodes for more detail tol : None or float Tolerance for SVD of affine - see io_orientation for more detail.
Returns:	axcodes : (N,) tuple labels for positive end of voxel axes. Dropped axes get a label of None.

Examples

>>> aff = [[0,1,0,10],[-1,0,0,20],[0,0,1,30],[0,0,0,1]]
>>> aff2axcodes(aff, (('L','R'),('B','F'),('D','U')))
('B', 'R', 'U')

detect_format

dipy.io.streamline.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 class The class type guessed from the content of fileobj.

load_dpy

dipy.io.streamline.load_dpy(filename, lazy_load=False)

Loads tractogram files (*.tck)

Parameters:	filename : str input trk filename 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:	streamlines : list of 2D arrays Each 2D array represents a sequence of 3D points (points, 3). hdr : dict header from a trk file

load_tck

dipy.io.streamline.load_tck(filename, lazy_load=False)

Loads tractogram files (*.tck)

Parameters:	filename : str input trk filename 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:	streamlines : list of 2D arrays Each 2D array represents a sequence of 3D points (points, 3). hdr : dict header from a trk file

load_tractogram

dipy.io.streamline.load_tractogram(filename, lazy_load=False)

Loads tractogram files (*.tck)

Parameters:	filename : str input trk filename 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:	streamlines : list of 2D arrays Each 2D array represents a sequence of 3D points (points, 3). hdr : dict header from a trk file

load_trk

dipy.io.streamline.load_trk(filename, lazy_load=False)

Loads tractogram files (*.tck)

Parameters:	filename : str input trk filename 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:	streamlines : list of 2D arrays Each 2D array represents a sequence of 3D points (points, 3). hdr : dict header from a trk file

save_tractogram

dipy.io.streamline.save_tractogram(fname, streamlines, affine, vox_size=None, shape=None, header=None, reduce_memory_usage=False, tractogram_file=None)

Saves tractogram files (*.trk or *.tck or *.dpy)

Parameters:

fname : str output trk filename streamlines : list of 2D arrays, generator or ArraySequence Each 2D array represents a sequence of 3D points (points, 3). affine : array_like (4, 4) The mapping from voxel coordinates to streamline points. vox_size : array_like (3,), optional The sizes of the voxels in the reference image (default: None) shape : array, shape (dim,), optional The shape of the reference image (default: None) header : dict, optional Metadata associated to the tractogram file(*.trk). (default: None) reduce_memory_usage : {False, True}, optional If True, save streamlines in a lazy manner i.e. they will not be kept in memory. Otherwise, keep all streamlines in memory until saving. tractogram_file : class TractogramFile, optional Define tractogram class type (TrkFile vs TckFile) Default is None which means auto detect format

save_trk

dipy.io.trackvis.save_trk(filename, points, vox_to_ras, shape)

A temporary helper function for saving trk files.

This function will soon be replaced by better trk file support in nibabel.

Nifti1Image

class dipy.io.utils.Nifti1Image(dataobj, affine, header=None, extra=None, file_map=None)

Bases: nibabel.nifti1.Nifti1Pair

Class for single file NIfTI1 format image

Attributes:	affine dataobj header in_memory True when any array data is in memory cache shape slicer Slicer object that returns cropped and subsampled images

Methods

ImageArrayProxy	alias of nibabel.arrayproxy.ArrayProxy
ImageSlicer	alias of nibabel.spatialimages.SpatialFirstSlicer
as_reoriented(ornt)	Apply an orientation change and return a new image
filespec_to_file_map(filespec)	Make file_map for this class from filename filespec
filespec_to_files(filespec)	filespec_to_files class method is deprecated.
from_file_map(file_map[, mmap, keep_file_open])	class method to create image from mapping in file_map `
from_filename(filename[, mmap, keep_file_open])	class method to create image from filename filename
from_files(file_map)	from_files class method is deprecated.
from_image(img)	Class method to create new instance of own class from img
get_affine()	Get affine from image
get_data([caching])	Return image data from image with any necessary scaling applied
get_fdata([caching, dtype])	Return floating point image data with necessary scaling applied
get_filename()	Fetch the image filename
get_header()	Get header from image
get_qform([coded])	Return 4x4 affine matrix from qform parameters in header
get_sform([coded])	Return 4x4 affine matrix from sform parameters in header
get_shape()	Return shape for image
header_class	alias of Nifti1Header
instance_to_filename(img, filename)	Save img in our own format, to name implied by filename
load(filename[, mmap, keep_file_open])	class method to create image from filename filename
make_file_map([mapping])	Class method to make files holder for this image type
orthoview()	Plot the image using OrthoSlicer3D
path_maybe_image(filename[, sniff, sniff_max])	Return True if filename may be image matching this class
set_filename(filename)	Sets the files in the object from a given filename
set_qform(affine[, code, strip_shears])	Set qform header values from 4x4 affine
set_sform(affine[, code])	Set sform transform from 4x4 affine
to_file_map([file_map])	Write image to file_map or contained self.file_map
to_filename(filename)	Write image to files implied by filename string
to_files([file_map])	to_files method is deprecated.
to_filespec(filename)	to_filespec method is deprecated.
uncache()	Delete any cached read of data from proxied data
update_header()	Harmonize header with image data and affine

get_data_dtype
set_data_dtype

__init__(dataobj, affine, header=None, extra=None, file_map=None)

Initialize image

The image is a combination of (array-like, affine matrix, header), with optional metadata in extra, and filename / file-like objects contained in the file_map mapping.

Parameters:

dataobj : object Object containg image data. It should be some object that retuns an array from np.asanyarray. It should have a shape attribute or property affine : None or (4,4) array-like homogenous affine giving relationship between voxel coordinates and world coordinates. Affine can also be None. In this case, obj.affine also returns None, and the affine as written to disk will depend on the file format. header : None or mapping or header instance, optional metadata for this image format extra : None or mapping, optional metadata to associate with image that cannot be stored in the metadata of this image type file_map : mapping, optional mapping giving file information for this image format

Notes

If both a header and an affine are specified, and the affine does not match the affine that is in the header, the affine will be used, but the sform_code and qform_code fields in the header will be re-initialised to their default values. This is performed on the basis that, if you are changing the affine, you are likely to be changing the space to which the affine is pointing. The set_sform() and set_qform() methods can be used to update the codes after an image has been created - see those methods, and the manual for more details.

files_types = (('image', '.nii'),)

header_class

alias of Nifti1Header

update_header()

Harmonize header with image data and affine

valid_exts = ('.nii',)

decfa

dipy.io.utils.decfa(img_orig, scale=False)

Create a nifti-compliant directional-encoded color FA file.

Parameters:	data : Nifti1Image class instance. Contains encoding of the DEC FA image with a 4D volume of data, where the elements on the last dimension represent R, G and B components. scale: bool. Whether to scale the incoming data from the 0-1 to the 0-255 range expected in the output.
Returns:	img : Nifti1Image class instance with dtype set to store tuples of uint8 in (R, G, B) order.

Notes

For a description of this format, see:

https://nifti.nimh.nih.gov/nifti-1/documentation/nifti1fields/nifti1fields_pages/datatype.html

make5d

dipy.io.utils.make5d(input)

reshapes the input to have 5 dimensions, adds extra dimensions just before the last dimession

nifti1_symmat

dipy.io.utils.nifti1_symmat(image_data, *args, **kwargs)

Returns a Nifti1Image with a symmetric matrix intent

load_polydata

dipy.io.vtk.load_polydata(file_name)

Load a vtk polydata to a supported format file.

Supported file formats are OBJ, VTK, FIB, PLY, STL and XML

Parameters:	file_name : string
Returns:	output : vtkPolyData

optional_package

dipy.io.vtk.optional_package(name, trip_msg=None)

Return package-like thing and module setup for package name

Parameters:	name : str package name trip_msg : None or str message to give when someone tries to use the return package, but we could not import it, and have returned a TripWire object instead. Default message if None.
Returns:	pkg_like : module or TripWire instance If we can import the package, return it. Otherwise return an object raising an error when accessed have_pkg : bool True if import for package was successful, false otherwise module_setup : function callable usually set as setup_module in calling namespace, to allow skipping tests.

save_polydata

dipy.io.vtk.save_polydata(polydata, file_name, binary=False, color_array_name=None)

Save a vtk polydata to a supported format file.

Save formats can be VTK, FIB, PLY, STL and XML.

Parameters:	polydata : vtkPolyData file_name : string

setup_module

dipy.io.vtk.setup_module()