data

Read test or example data

DataError
GradientTable(gradients[, big_delta, ...]) Diffusion gradient information
HemiSphere([x, y, z, theta, phi, xyz, ...]) Points on the unit sphere.
Sphere([x, y, z, theta, phi, xyz, faces, edges]) Points on the unit sphere.
SticksAndBall(gtab[, d, S0, angles, ...]) Simulate the signal for a Sticks & Ball model.
as_native_array(arr) Return arr as native byteordered array
dirname(p) Returns the directory component of a pathname
dsi_deconv_voxels()
dsi_voxels()
fetch_bundles_2_subjects() Download 2 subjects from the SNAIL dataset with their bundles
fetch_cenir_multib([with_raw]) Fetch ‘HCP-like’ data, collected at multiple b-values
fetch_cfin_multib() Download CFIN multi b-value diffusion data
fetch_isbi2013_2shell() Download a 2-shell software phantom dataset
fetch_ivim() Download IVIM dataset
fetch_mni_template() fetch the MNI 2009a T1 and T2, and 2009c T1 and T1 mask files
fetch_scil_b0() Download b=0 datasets from multiple MR systems (GE, Philips, Siemens) and different magnetic fields (1.5T and 3T)
fetch_sherbrooke_3shell() Download a 3shell HARDI dataset with 192 gradient direction
fetch_stanford_hardi() Download a HARDI dataset with 160 gradient directions
fetch_stanford_pve_maps()
fetch_stanford_t1()
fetch_syn_data() Download t1 and b0 volumes from the same session
fetch_taiwan_ntu_dsi() Download a DSI dataset with 203 gradient directions
fetch_tissue_data() Download images to be used for tissue classification
fetch_viz_icons() Download icons for dipy.viz
get_3shell_gtab()
get_cmap(name) Makes a callable, similar to maptlotlib.pyplot.get_cmap
get_data([name]) provides filenames of some test datasets or other useful parametrisations
get_gtab_taiwan_dsi()
get_isbi2013_2shell_gtab()
get_sim_voxels([name]) provide some simulated voxel data
get_skeleton([name]) provide skeletons generated from Local Skeleton Clustering (LSC)
get_sphere([name]) provide triangulated spheres
gradient_table(bvals[, bvecs, big_delta, ...]) A general function for creating diffusion MR gradients.
load(filename, **kwargs) Load file given filename, guessing at file type
loads_compat(bytes)
matlab_life_results()
mrtrix_spherical_functions() Spherical functions represented by spherical harmonic coefficients and evaluated on a discrete sphere.
pjoin(a, *p) Join two or more pathname components, inserting ‘/’ as needed.
read_bundles_2_subjects([subj_id, metrics, ...]) Read images and streamlines from 2 subjects of the SNAIL dataset
read_cenir_multib([bvals]) Read CENIR multi b-value data
read_cfin_dwi() Load CFIN multi b-value DWI data
read_cfin_t1() Load CFIN T1-weighted data.
read_isbi2013_2shell() Load ISBI 2013 2-shell synthetic dataset
read_ivim() Load IVIM dataset
read_mni_template([version, contrast]) Read the MNI template from disk
read_scil_b0() Load GE 3T b0 image form the scil b0 dataset.
read_sherbrooke_3shell() Load Sherbrooke 3-shell HARDI dataset
read_stanford_hardi() Load Stanford HARDI dataset
read_stanford_labels() Read stanford hardi data and label map
read_stanford_pve_maps()
read_stanford_t1()
read_syn_data() Load t1 and b0 volumes from the same session
read_taiwan_ntu_dsi() Load Taiwan NTU dataset
read_tissue_data([contrast]) Load images to be used for tissue classification
read_viz_icons([style, fname]) Read specific icon from specific style
relist_streamlines(points, offsets) Given a representation of a set of streamlines as a large array and an offsets array return the streamlines as a list of shorter arrays.
two_cingulum_bundles()

Module: data.fetcher

FetcherError
check_md5(filename[, stored_md5]) Computes the md5 of filename and check if it matches with the supplied
copyfileobj(fsrc, fdst[, length]) copy data from file-like object fsrc to file-like object fdst
copyfileobj_withprogress(fsrc, fdst, ...[, ...])
fetch_bundles_2_subjects() Download 2 subjects from the SNAIL dataset with their bundles
fetch_cenir_multib([with_raw]) Fetch ‘HCP-like’ data, collected at multiple b-values
fetch_cfin_multib() Download CFIN multi b-value diffusion data
fetch_data(files, folder[, data_size]) Downloads files to folder and checks their md5 checksums
fetch_isbi2013_2shell() Download a 2-shell software phantom dataset
fetch_ivim() Download IVIM dataset
fetch_mni_template() fetch the MNI 2009a T1 and T2, and 2009c T1 and T1 mask files
fetch_scil_b0() Download b=0 datasets from multiple MR systems (GE, Philips, Siemens) and different magnetic fields (1.5T and 3T)
fetch_sherbrooke_3shell() Download a 3shell HARDI dataset with 192 gradient direction
fetch_stanford_hardi() Download a HARDI dataset with 160 gradient directions
fetch_stanford_labels() Download reduced freesurfer aparc image from stanford web site
fetch_stanford_pve_maps()
fetch_stanford_t1()
fetch_syn_data() Download t1 and b0 volumes from the same session
fetch_taiwan_ntu_dsi() Download a DSI dataset with 203 gradient directions
fetch_tissue_data() Download images to be used for tissue classification
fetch_viz_icons() Download icons for dipy.viz
gradient_table(bvals[, bvecs, big_delta, ...]) A general function for creating diffusion MR gradients.
md5 Returns a md5 hash object; optionally initialized with a string
pjoin(a, *p) Join two or more pathname components, inserting ‘/’ as needed.
read_bundles_2_subjects([subj_id, metrics, ...]) Read images and streamlines from 2 subjects of the SNAIL dataset
read_bvals_bvecs(fbvals, fbvecs) Read b-values and b-vectors from disk
read_cenir_multib([bvals]) Read CENIR multi b-value data
read_cfin_dwi() Load CFIN multi b-value DWI data
read_cfin_t1() Load CFIN T1-weighted data.
read_isbi2013_2shell() Load ISBI 2013 2-shell synthetic dataset
read_ivim() Load IVIM dataset
read_mni_template([version, contrast]) Read the MNI template from disk
read_scil_b0() Load GE 3T b0 image form the scil b0 dataset.
read_sherbrooke_3shell() Load Sherbrooke 3-shell HARDI dataset
read_siemens_scil_b0() Load Siemens 1.5T b0 image form the scil b0 dataset.
read_stanford_hardi() Load Stanford HARDI dataset
read_stanford_labels() Read stanford hardi data and label map
read_stanford_pve_maps()
read_stanford_t1()
read_syn_data() Load t1 and b0 volumes from the same session
read_taiwan_ntu_dsi() Load Taiwan NTU dataset
read_tissue_data([contrast]) Load images to be used for tissue classification
read_viz_icons([style, fname]) Read specific icon from specific style
update_progressbar(progress, total_length) Show progressbar
urlopen(url[, data, timeout, cafile, ...]) Open the URL url, which can be either a string or a Request object.

DataError

class dipy.data.DataError

Bases: Exception

Attributes

args

Methods

with_traceback Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
__init__()

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

GradientTable

class dipy.data.GradientTable(gradients, big_delta=None, small_delta=None, b0_threshold=0)

Bases: object

Diffusion gradient information

Parameters:

gradients : array_like (N, 3)

Diffusion gradients. The direction of each of these vectors corresponds to the b-vector, and the length corresponds to the b-value.

b0_threshold : float

Gradients with b-value less than or equal to b0_threshold are considered as b0s i.e. without diffusion weighting.

See also

gradient_table

Notes

The GradientTable object is immutable. Do NOT assign attributes. If you have your gradient table in a bval & bvec format, we recommend using the factory function gradient_table

Attributes

gradients ((N,3) ndarray) diffusion gradients
bvals ((N,) ndarray) The b-value, or magnitude, of each gradient direction.
qvals: (N,) ndarray The q-value for each gradient direction. Needs big and small delta.
bvecs ((N,3) ndarray) The direction, represented as a unit vector, of each gradient.
b0s_mask ((N,) ndarray) Boolean array indicating which gradients have no diffusion weighting, ie b-value is close to 0.
b0_threshold (float) Gradients with b-value less than or equal to b0_threshold are considered to not have diffusion weighting.

Methods

b0s_mask()
bvals()
bvecs()
qvals()
__init__(gradients, big_delta=None, small_delta=None, b0_threshold=0)

Constructor for GradientTable class

b0s_mask()
bvals()
bvecs()
info
qvals()

HemiSphere

class dipy.data.HemiSphere(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None, tol=1e-05)

Bases: dipy.core.sphere.Sphere

Points on the unit sphere.

A HemiSphere is similar to a Sphere but it takes antipodal symmetry into account. Antipodal symmetry means that point v on a HemiSphere is the same as the point -v. Duplicate points are discarded when constructing a HemiSphere (including antipodal duplicates). edges and faces are remapped to the remaining points as closely as possible.

The HemiSphere can be constructed using one of three conventions:

HemiSphere(x, y, z)
HemiSphere(xyz=xyz)
HemiSphere(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.

tol : float

Angle in degrees. Vertices that are less than tol degrees apart are treated as duplicates.

See also

Sphere

Attributes

x
y
z

Methods

edges()
faces()
find_closest(xyz) Find the index of the vertex in the Sphere closest to the input vector,
from_sphere(klass, sphere[, tol]) Create instance from a Sphere
mirror() Create a full Sphere from a HemiSphere
subdivide([n]) Create a more subdivided HemiSphere
vertices()
__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None, tol=1e-05)

Create a HemiSphere from points

faces()
find_closest(xyz)

Find the index of the vertex in the Sphere closest to the input vector, taking into account antipodal symmetry

Parameters:

xyz : array-like, 3 elements

A unit vector

classmethod from_sphere(klass, sphere, tol=1e-05)

Create instance from a Sphere

mirror()

Create a full Sphere from a HemiSphere

subdivide(n=1)

Create a more subdivided HemiSphere

See Sphere.subdivide for full documentation.

Sphere

class dipy.data.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

edges()
faces()
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.
vertices()
__init__(x=None, y=None, z=None, theta=None, phi=None, xyz=None, faces=None, edges=None)
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

SticksAndBall

dipy.data.SticksAndBall(gtab, d=0.0015, S0=1.0, angles=[(0, 0), (90, 0)], fractions=[35, 35], snr=20)

Simulate the signal for a Sticks & Ball model.

Parameters:

gtab : GradientTable

Signal measurement directions.

d : float

Diffusivity value.

S0 : float

Unweighted signal value.

angles : array (K,2) or (K, 3)

List of K polar angles (in degrees) for the sticks or array of K sticks as unit vectors.

fractions : float

Percentage of each stick. Remainder to 100 specifies isotropic component.

snr : float

Signal to noise ratio, assuming Rician noise. If set to None, no noise is added.

Returns:

S : (N,) ndarray

Simulated signal.

sticks : (M,3)

Sticks in cartesian coordinates.

References

[R40]Behrens et al., “Probabilistic diffusion tractography with multiple fiber orientations: what can we gain?”, Neuroimage, 2007.

as_native_array

dipy.data.as_native_array(arr)

Return arr as native byteordered array

If arr is already native byte ordered, return unchanged. If it is opposite endian, then make a native byte ordered copy and return that

Parameters:

arr : ndarray

Returns:

native_arr : ndarray

If arr was native order, this is just arr. Otherwise it’s a new array such that np.all(native_arr == arr), with native byte ordering.

dirname

dipy.data.dirname(p)

Returns the directory component of a pathname

dsi_deconv_voxels

dipy.data.dsi_deconv_voxels()

dsi_voxels

dipy.data.dsi_voxels()

fetch_bundles_2_subjects

dipy.data.fetch_bundles_2_subjects()

Download 2 subjects from the SNAIL dataset with their bundles

fetch_cenir_multib

dipy.data.fetch_cenir_multib(with_raw=False)

Fetch ‘HCP-like’ data, collected at multiple b-values

Parameters:

with_raw : bool

Whether to fetch the raw data. Per default, this is False, which means that only eddy-current/motion corrected data is fetched

Notes

Details of the acquisition and processing, and additional meta-data are available through UW researchworks

fetch_cfin_multib

dipy.data.fetch_cfin_multib()

Download CFIN multi b-value diffusion data

fetch_isbi2013_2shell

dipy.data.fetch_isbi2013_2shell()

Download a 2-shell software phantom dataset

fetch_ivim

dipy.data.fetch_ivim()

Download IVIM dataset

fetch_mni_template

dipy.data.fetch_mni_template()

fetch the MNI 2009a T1 and T2, and 2009c T1 and T1 mask files Notes —– The templates were downloaded from the MNI (McGill University) website in July 2015.

The following publications should be referenced when using these templates:

[R41]VS Fonov, AC Evans, K Botteron, CR Almli, RC McKinstry, DL Collins and BDCG, Unbiased average age-appropriate atlases for pediatric studies, NeuroImage, 54:1053-8119, DOI: 10.1016/j.neuroimage.2010.07.033
[R42]VS Fonov, AC Evans, RC McKinstry, CR Almli and DL Collins, Unbiased nonlinear average age-appropriate brain templates from birth to adulthood, NeuroImage, 47:S102 Organization for Human Brain Mapping 2009 Annual Meeting, DOI: http://dx.doi.org/10.1016/S1053-8119(09)70884-5

Copyright (C) 1993-2004, Louis Collins McConnell Brain Imaging Centre, Montreal Neurological Institute, McGill University. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies. The authors and McGill University make no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty. The authors are not responsible for any data loss, equipment damage, property loss, or injury to subjects or patients resulting from the use or misuse of this software package.

fetch_scil_b0

dipy.data.fetch_scil_b0()

Download b=0 datasets from multiple MR systems (GE, Philips, Siemens) and different magnetic fields (1.5T and 3T)

fetch_sherbrooke_3shell

dipy.data.fetch_sherbrooke_3shell()

Download a 3shell HARDI dataset with 192 gradient direction

fetch_stanford_hardi

dipy.data.fetch_stanford_hardi()

Download a HARDI dataset with 160 gradient directions

fetch_stanford_pve_maps

dipy.data.fetch_stanford_pve_maps()

fetch_stanford_t1

dipy.data.fetch_stanford_t1()

fetch_syn_data

dipy.data.fetch_syn_data()

Download t1 and b0 volumes from the same session

fetch_taiwan_ntu_dsi

dipy.data.fetch_taiwan_ntu_dsi()

Download a DSI dataset with 203 gradient directions

fetch_tissue_data

dipy.data.fetch_tissue_data()

Download images to be used for tissue classification

fetch_viz_icons

dipy.data.fetch_viz_icons()

Download icons for dipy.viz

get_3shell_gtab

dipy.data.get_3shell_gtab()

get_cmap

dipy.data.get_cmap(name)

Makes a callable, similar to maptlotlib.pyplot.get_cmap

get_data

dipy.data.get_data(name='small_64D')

provides filenames of some test datasets or other useful parametrisations

Parameters:

name : str

the filename/s of which dataset to return, one of: ‘small_64D’ small region of interest nifti,bvecs,bvals 64 directions ‘small_101D’ small region of interest nifti,bvecs,bvals 101 directions ‘aniso_vox’ volume with anisotropic voxel size as Nifti ‘fornix’ 300 tracks in Trackvis format (from Pittsburgh

Brain Competition)

‘gqi_vectors’ the scanner wave vectors needed for a GQI acquisitions

of 101 directions tested on Siemens 3T Trio

‘small_25’ small ROI (10x8x2) DTI data (b value 2000, 25 directions) ‘test_piesno’ slice of N=8, K=14 diffusion data ‘reg_c’ small 2D image used for validating registration ‘reg_o’ small 2D image used for validation registration ‘cb_2’ two vectorized cingulum bundles

Returns:

fnames : tuple

filenames for dataset

Examples

>>> import numpy as np
>>> from dipy.data import get_data
>>> fimg,fbvals,fbvecs=get_data('small_101D')
>>> bvals=np.loadtxt(fbvals)
>>> bvecs=np.loadtxt(fbvecs).T
>>> import nibabel as nib
>>> img=nib.load(fimg)
>>> data=img.get_data()
>>> data.shape == (6, 10, 10, 102)
True
>>> bvals.shape == (102,)
True
>>> bvecs.shape == (102, 3)
True

get_gtab_taiwan_dsi

dipy.data.get_gtab_taiwan_dsi()

get_isbi2013_2shell_gtab

dipy.data.get_isbi2013_2shell_gtab()

get_sim_voxels

dipy.data.get_sim_voxels(name='fib1')

provide some simulated voxel data

Parameters:

name : str, which file?

‘fib0’, ‘fib1’ or ‘fib2’

Returns:

dix : dictionary, where dix[‘data’] returns a 2d array

where every row is a simulated voxel with different orientation

Notes

These sim voxels were provided by M.M. Correia using Rician noise.

Examples

>>> from dipy.data import get_sim_voxels
>>> sv=get_sim_voxels('fib1')
>>> sv['data'].shape == (100, 102)
True
>>> sv['fibres']
'1'
>>> sv['gradients'].shape == (102, 3)
True
>>> sv['bvals'].shape == (102,)
True
>>> sv['snr']
'60'
>>> sv2=get_sim_voxels('fib2')
>>> sv2['fibres']
'2'
>>> sv2['snr']
'80'

get_skeleton

dipy.data.get_skeleton(name='C1')

provide skeletons generated from Local Skeleton Clustering (LSC)

Parameters:name : str, ‘C1’ or ‘C3’
Returns:dix : dictionary

Examples

>>> from dipy.data import get_skeleton
>>> C=get_skeleton('C1')
>>> len(C.keys())
117
>>> for c in C: break
>>> sorted(C[c].keys())
['N', 'hidden', 'indices', 'most']

get_sphere

dipy.data.get_sphere(name='symmetric362')

provide triangulated spheres

Parameters:

name : str

which sphere - one of: * ‘symmetric362’ * ‘symmetric642’ * ‘symmetric724’ * ‘repulsion724’ * ‘repulsion100’ * ‘repulsion200’

Returns:

sphere : a dipy.core.sphere.Sphere class instance

Examples

>>> import numpy as np
>>> from dipy.data import get_sphere
>>> sphere = get_sphere('symmetric362')
>>> verts, faces = sphere.vertices, sphere.faces
>>> verts.shape == (362, 3)
True
>>> faces.shape == (720, 3)
True
>>> verts, faces = get_sphere('not a sphere name') 
Traceback (most recent call last):
    ...
DataError: No sphere called "not a sphere name"

gradient_table

dipy.data.gradient_table(bvals, bvecs=None, big_delta=None, small_delta=None, b0_threshold=0, atol=0.01)

A general function for creating diffusion MR gradients.

It reads, loads and prepares scanner parameters like the b-values and b-vectors so that they can be useful during the reconstruction process.

Parameters:

bvals : can be any of the four options

  1. an array of shape (N,) or (1, N) or (N, 1) with the b-values.
  2. a path for the file which contains an array like the above (1).
  3. an array of shape (N, 4) or (4, N). Then this parameter is considered to be a b-table which contains both bvals and bvecs. In this case the next parameter is skipped.
  4. a path for the file which contains an array like the one at (3).

bvecs : can be any of two options

  1. an array of shape (N, 3) or (3, N) with the b-vectors.
  2. a path for the file which contains an array like the previous.

big_delta : float

acquisition timing duration (default None)

small_delta : float

acquisition timing duration (default None)

b0_threshold : float

All b-values with values less than or equal to bo_threshold are considered as b0s i.e. without diffusion weighting.

atol : float

All b-vectors need to be unit vectors up to a tolerance.

Returns:

gradients : GradientTable

A GradientTable with all the gradient information.

Notes

  1. Often b0s (b-values which correspond to images without diffusion weighting) have 0 values however in some cases the scanner cannot provide b0s of an exact 0 value and it gives a bit higher values e.g. 6 or 12. This is the purpose of the b0_threshold in the __init__.
  2. We assume that the minimum number of b-values is 7.
  3. B-vectors should be unit vectors.

Examples

>>> from dipy.core.gradients import gradient_table
>>> bvals=1500*np.ones(7)
>>> bvals[0]=0
>>> sq2=np.sqrt(2)/2
>>> bvecs=np.array([[0, 0, 0],
...                 [1, 0, 0],
...                 [0, 1, 0],
...                 [0, 0, 1],
...                 [sq2, sq2, 0],
...                 [sq2, 0, sq2],
...                 [0, sq2, sq2]])
>>> gt = gradient_table(bvals, bvecs)
>>> gt.bvecs.shape == bvecs.shape
True
>>> gt = gradient_table(bvals, bvecs.T)
>>> gt.bvecs.shape == bvecs.T.shape
False

load

dipy.data.load(filename, **kwargs)

Load file given filename, guessing at file type

Parameters:

filename : string

specification of file to load

**kwargs : keyword arguments

Keyword arguments to format-specific load

Returns:

img : SpatialImage

Image of guessed type

loads_compat

dipy.data.loads_compat(bytes)

matlab_life_results

dipy.data.matlab_life_results()

mrtrix_spherical_functions

dipy.data.mrtrix_spherical_functions()

Spherical functions represented by spherical harmonic coefficients and evaluated on a discrete sphere.

Returns:

func_coef : array (2, 3, 4, 45)

Functions represented by the coefficients associated with the mxtrix spherical harmonic basis of order 8.

func_discrete : array (2, 3, 4, 81)

Functions evaluated on sphere.

sphere : Sphere

The discrete sphere, points on the surface of a unit sphere, used to evaluate the functions.

Notes

These coefficients were obtained by using the dwi2SH command of mrtrix.

pjoin

dipy.data.pjoin(a, *p)

Join two or more pathname components, inserting ‘/’ as needed. If any component is an absolute path, all previous path components will be discarded. An empty last part will result in a path that ends with a separator.

read_bundles_2_subjects

dipy.data.read_bundles_2_subjects(subj_id='subj_1', metrics=['fa'], bundles=['af.left', 'cst.right', 'cc_1'])

Read images and streamlines from 2 subjects of the SNAIL dataset

Parameters:

subj_id : string

Either subj_1 or subj_2.

metrics : list

Either [‘fa’] or [‘t1’] or [‘fa’, ‘t1’]

bundles : list

Example [‘af.left’, ‘cst.right’, ‘cc_1’]. See all the available bundles in the exp_bundles_maps/bundles_2_subjects directory of your $HOME/.dipy folder.

Returns:

dix : dict

Dictionary with data of the metrics and the bundles as keys.

Notes

If you are using these datasets please cite the following publications.

References

[R43]Renauld, E., M. Descoteaux, M. Bernier, E. Garyfallidis,

K. Whittingstall, “Morphology of thalamus, LGN and optic radiation do not influence EEG alpha waves”, Plos One (under submission), 2015.

[R44]Garyfallidis, E., O. Ocegueda, D. Wassermann,

M. Descoteaux. Robust and efficient linear registration of fascicles in the space of streamlines , Neuroimage, 117:124-140, 2015.

read_cenir_multib

dipy.data.read_cenir_multib(bvals=None)

Read CENIR multi b-value data

Parameters:

bvals : list or int

The b-values to read from file (200, 400, 1000, 2000, 3000).

Returns:

gtab : a GradientTable class instance

img : nibabel.Nifti1Image

Notes

Details of the acquisition and processing, and additional meta-data are available through UW researchworks

read_cfin_dwi

dipy.data.read_cfin_dwi()

Load CFIN multi b-value DWI data

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_cfin_t1

dipy.data.read_cfin_t1()

Load CFIN T1-weighted data.

Returns:

img : obj,

Nifti1Image

read_isbi2013_2shell

dipy.data.read_isbi2013_2shell()

Load ISBI 2013 2-shell synthetic dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_ivim

dipy.data.read_ivim()

Load IVIM dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_mni_template

dipy.data.read_mni_template(version='a', contrast='T2')

Read the MNI template from disk

Parameters:

version: string

There are two MNI templates 2009a and 2009c, so options available are: “a” and “c”.

contrast : list or string, optional

Which of the contrast templates to read. For version “a” two contrasts are available: “T1” and “T2”. Similarly for version “c” there are two options, “T1” and “mask”. You can input contrast as a string or a list

Returns:

list : contains the nibabel.Nifti1Image objects requested, according to the

order they were requested in the input.

Notes

The templates were downloaded from the MNI (McGill University) website in July 2015.

The following publications should be referenced when using these templates:

[R45]VS Fonov, AC Evans, K Botteron, CR Almli, RC McKinstry, DL Collins and BDCG, Unbiased average age-appropriate atlases for pediatric studies, NeuroImage, 54:1053-8119, DOI: 10.1016/j.neuroimage.2010.07.033
[R46]VS Fonov, AC Evans, RC McKinstry, CR Almli and DL Collins, Unbiased nonlinear average age-appropriate brain templates from birth to adulthood, NeuroImage, 47:S102 Organization for Human Brain Mapping 2009 Annual Meeting, DOI: http://dx.doi.org/10.1016/S1053-8119(09)70884-5

Copyright (C) 1993-2004, Louis Collins McConnell Brain Imaging Centre, Montreal Neurological Institute, McGill University. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies. The authors and McGill University make no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty. The authors are not responsible for any data loss, equipment damage, property loss, or injury to subjects or patients resulting from the use or misuse of this software package.

Examples

Get only the T1 file for version c: >>> T1_nifti = read_mni_template(“c”, contrast = “T1”) # doctest: +SKIP Get both files in this order for version a: >>> T1_nifti, T2_nifti = read_mni_template(contrast = [“T1”, “T2”]) # doctest: +SKIP

read_scil_b0

dipy.data.read_scil_b0()

Load GE 3T b0 image form the scil b0 dataset.

Returns:

img : obj,

Nifti1Image

read_sherbrooke_3shell

dipy.data.read_sherbrooke_3shell()

Load Sherbrooke 3-shell HARDI dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_stanford_hardi

dipy.data.read_stanford_hardi()

Load Stanford HARDI dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_stanford_labels

dipy.data.read_stanford_labels()

Read stanford hardi data and label map

read_stanford_pve_maps

dipy.data.read_stanford_pve_maps()

read_stanford_t1

dipy.data.read_stanford_t1()

read_syn_data

dipy.data.read_syn_data()

Load t1 and b0 volumes from the same session

Returns:

t1 : obj,

Nifti1Image

b0 : obj,

Nifti1Image

read_taiwan_ntu_dsi

dipy.data.read_taiwan_ntu_dsi()

Load Taiwan NTU dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_tissue_data

dipy.data.read_tissue_data(contrast='T1')

Load images to be used for tissue classification

Parameters:

constrast : str

‘T1’, ‘T1 denoised’ or ‘Anisotropic Power’

Returns:

image : obj,

Nifti1Image

read_viz_icons

dipy.data.read_viz_icons(style='icomoon', fname='infinity.png')

Read specific icon from specific style

Parameters:

style : str

Current icon style. Default is icomoon.

fname : str

Filename of icon. This should be found in folder HOME/.dipy/style/. Default is infinity.png.

Returns:

path : str

Complete path of icon.

relist_streamlines

dipy.data.relist_streamlines(points, offsets)

Given a representation of a set of streamlines as a large array and an offsets array return the streamlines as a list of shorter arrays.

Parameters:

points : array

offsets : array

Returns:

streamlines: sequence

two_cingulum_bundles

dipy.data.two_cingulum_bundles()

FetcherError

class dipy.data.fetcher.FetcherError

Bases: Exception

Attributes

args

Methods

with_traceback Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
__init__()

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

check_md5

dipy.data.fetcher.check_md5(filename, stored_md5=None)

Computes the md5 of filename and check if it matches with the supplied string md5

copyfileobj

dipy.data.fetcher.copyfileobj(fsrc, fdst, length=16384)

copy data from file-like object fsrc to file-like object fdst

copyfileobj_withprogress

dipy.data.fetcher.copyfileobj_withprogress(fsrc, fdst, total_length, length=16384)

fetch_bundles_2_subjects

dipy.data.fetcher.fetch_bundles_2_subjects()

Download 2 subjects from the SNAIL dataset with their bundles

fetch_cenir_multib

dipy.data.fetcher.fetch_cenir_multib(with_raw=False)

Fetch ‘HCP-like’ data, collected at multiple b-values

Parameters:

with_raw : bool

Whether to fetch the raw data. Per default, this is False, which means that only eddy-current/motion corrected data is fetched

Notes

Details of the acquisition and processing, and additional meta-data are available through UW researchworks

fetch_cfin_multib

dipy.data.fetcher.fetch_cfin_multib()

Download CFIN multi b-value diffusion data

fetch_data

dipy.data.fetcher.fetch_data(files, folder, data_size=None)

Downloads files to folder and checks their md5 checksums

Parameters:

files : dictionary

For each file in files the value should be (url, md5). The file will be downloaded from url if the file does not already exist or if the file exists but the md5 checksum does not match.

folder : str

The directory where to save the file, the directory will be created if it does not already exist.

data_size : str, optional

A string describing the size of the data (e.g. “91 MB”) to be logged to the screen. Default does not produce any information about data size.

Raises

——

FetcherError

Raises if the md5 checksum of the file does not match the expected value. The downloaded file is not deleted when this error is raised.

fetch_isbi2013_2shell

dipy.data.fetcher.fetch_isbi2013_2shell()

Download a 2-shell software phantom dataset

fetch_ivim

dipy.data.fetcher.fetch_ivim()

Download IVIM dataset

fetch_mni_template

dipy.data.fetcher.fetch_mni_template()

fetch the MNI 2009a T1 and T2, and 2009c T1 and T1 mask files Notes —– The templates were downloaded from the MNI (McGill University) website in July 2015.

The following publications should be referenced when using these templates:

[R47]VS Fonov, AC Evans, K Botteron, CR Almli, RC McKinstry, DL Collins and BDCG, Unbiased average age-appropriate atlases for pediatric studies, NeuroImage, 54:1053-8119, DOI: 10.1016/j.neuroimage.2010.07.033
[R48]VS Fonov, AC Evans, RC McKinstry, CR Almli and DL Collins, Unbiased nonlinear average age-appropriate brain templates from birth to adulthood, NeuroImage, 47:S102 Organization for Human Brain Mapping 2009 Annual Meeting, DOI: http://dx.doi.org/10.1016/S1053-8119(09)70884-5

Copyright (C) 1993-2004, Louis Collins McConnell Brain Imaging Centre, Montreal Neurological Institute, McGill University. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies. The authors and McGill University make no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty. The authors are not responsible for any data loss, equipment damage, property loss, or injury to subjects or patients resulting from the use or misuse of this software package.

fetch_scil_b0

dipy.data.fetcher.fetch_scil_b0()

Download b=0 datasets from multiple MR systems (GE, Philips, Siemens) and different magnetic fields (1.5T and 3T)

fetch_sherbrooke_3shell

dipy.data.fetcher.fetch_sherbrooke_3shell()

Download a 3shell HARDI dataset with 192 gradient direction

fetch_stanford_hardi

dipy.data.fetcher.fetch_stanford_hardi()

Download a HARDI dataset with 160 gradient directions

fetch_stanford_labels

dipy.data.fetcher.fetch_stanford_labels()

Download reduced freesurfer aparc image from stanford web site

fetch_stanford_pve_maps

dipy.data.fetcher.fetch_stanford_pve_maps()

fetch_stanford_t1

dipy.data.fetcher.fetch_stanford_t1()

fetch_syn_data

dipy.data.fetcher.fetch_syn_data()

Download t1 and b0 volumes from the same session

fetch_taiwan_ntu_dsi

dipy.data.fetcher.fetch_taiwan_ntu_dsi()

Download a DSI dataset with 203 gradient directions

fetch_tissue_data

dipy.data.fetcher.fetch_tissue_data()

Download images to be used for tissue classification

fetch_viz_icons

dipy.data.fetcher.fetch_viz_icons()

Download icons for dipy.viz

gradient_table

dipy.data.fetcher.gradient_table(bvals, bvecs=None, big_delta=None, small_delta=None, b0_threshold=0, atol=0.01)

A general function for creating diffusion MR gradients.

It reads, loads and prepares scanner parameters like the b-values and b-vectors so that they can be useful during the reconstruction process.

Parameters:

bvals : can be any of the four options

  1. an array of shape (N,) or (1, N) or (N, 1) with the b-values.
  2. a path for the file which contains an array like the above (1).
  3. an array of shape (N, 4) or (4, N). Then this parameter is considered to be a b-table which contains both bvals and bvecs. In this case the next parameter is skipped.
  4. a path for the file which contains an array like the one at (3).

bvecs : can be any of two options

  1. an array of shape (N, 3) or (3, N) with the b-vectors.
  2. a path for the file which contains an array like the previous.

big_delta : float

acquisition timing duration (default None)

small_delta : float

acquisition timing duration (default None)

b0_threshold : float

All b-values with values less than or equal to bo_threshold are considered as b0s i.e. without diffusion weighting.

atol : float

All b-vectors need to be unit vectors up to a tolerance.

Returns:

gradients : GradientTable

A GradientTable with all the gradient information.

Notes

  1. Often b0s (b-values which correspond to images without diffusion weighting) have 0 values however in some cases the scanner cannot provide b0s of an exact 0 value and it gives a bit higher values e.g. 6 or 12. This is the purpose of the b0_threshold in the __init__.
  2. We assume that the minimum number of b-values is 7.
  3. B-vectors should be unit vectors.

Examples

>>> from dipy.core.gradients import gradient_table
>>> bvals=1500*np.ones(7)
>>> bvals[0]=0
>>> sq2=np.sqrt(2)/2
>>> bvecs=np.array([[0, 0, 0],
...                 [1, 0, 0],
...                 [0, 1, 0],
...                 [0, 0, 1],
...                 [sq2, sq2, 0],
...                 [sq2, 0, sq2],
...                 [0, sq2, sq2]])
>>> gt = gradient_table(bvals, bvecs)
>>> gt.bvecs.shape == bvecs.shape
True
>>> gt = gradient_table(bvals, bvecs.T)
>>> gt.bvecs.shape == bvecs.T.shape
False

md5

dipy.data.fetcher.md5()

Returns a md5 hash object; optionally initialized with a string

pjoin

dipy.data.fetcher.pjoin(a, *p)

Join two or more pathname components, inserting ‘/’ as needed. If any component is an absolute path, all previous path components will be discarded. An empty last part will result in a path that ends with a separator.

read_bundles_2_subjects

dipy.data.fetcher.read_bundles_2_subjects(subj_id='subj_1', metrics=['fa'], bundles=['af.left', 'cst.right', 'cc_1'])

Read images and streamlines from 2 subjects of the SNAIL dataset

Parameters:

subj_id : string

Either subj_1 or subj_2.

metrics : list

Either [‘fa’] or [‘t1’] or [‘fa’, ‘t1’]

bundles : list

Example [‘af.left’, ‘cst.right’, ‘cc_1’]. See all the available bundles in the exp_bundles_maps/bundles_2_subjects directory of your $HOME/.dipy folder.

Returns:

dix : dict

Dictionary with data of the metrics and the bundles as keys.

Notes

If you are using these datasets please cite the following publications.

References

[R49]Renauld, E., M. Descoteaux, M. Bernier, E. Garyfallidis,

K. Whittingstall, “Morphology of thalamus, LGN and optic radiation do not influence EEG alpha waves”, Plos One (under submission), 2015.

[R50]Garyfallidis, E., O. Ocegueda, D. Wassermann,

M. Descoteaux. Robust and efficient linear registration of fascicles in the space of streamlines , Neuroimage, 117:124-140, 2015.

read_bvals_bvecs

dipy.data.fetcher.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_cenir_multib

dipy.data.fetcher.read_cenir_multib(bvals=None)

Read CENIR multi b-value data

Parameters:

bvals : list or int

The b-values to read from file (200, 400, 1000, 2000, 3000).

Returns:

gtab : a GradientTable class instance

img : nibabel.Nifti1Image

Notes

Details of the acquisition and processing, and additional meta-data are available through UW researchworks

read_cfin_dwi

dipy.data.fetcher.read_cfin_dwi()

Load CFIN multi b-value DWI data

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_cfin_t1

dipy.data.fetcher.read_cfin_t1()

Load CFIN T1-weighted data.

Returns:

img : obj,

Nifti1Image

read_isbi2013_2shell

dipy.data.fetcher.read_isbi2013_2shell()

Load ISBI 2013 2-shell synthetic dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_ivim

dipy.data.fetcher.read_ivim()

Load IVIM dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_mni_template

dipy.data.fetcher.read_mni_template(version='a', contrast='T2')

Read the MNI template from disk

Parameters:

version: string

There are two MNI templates 2009a and 2009c, so options available are: “a” and “c”.

contrast : list or string, optional

Which of the contrast templates to read. For version “a” two contrasts are available: “T1” and “T2”. Similarly for version “c” there are two options, “T1” and “mask”. You can input contrast as a string or a list

Returns:

list : contains the nibabel.Nifti1Image objects requested, according to the

order they were requested in the input.

Notes

The templates were downloaded from the MNI (McGill University) website in July 2015.

The following publications should be referenced when using these templates:

[R51]VS Fonov, AC Evans, K Botteron, CR Almli, RC McKinstry, DL Collins and BDCG, Unbiased average age-appropriate atlases for pediatric studies, NeuroImage, 54:1053-8119, DOI: 10.1016/j.neuroimage.2010.07.033
[R52]VS Fonov, AC Evans, RC McKinstry, CR Almli and DL Collins, Unbiased nonlinear average age-appropriate brain templates from birth to adulthood, NeuroImage, 47:S102 Organization for Human Brain Mapping 2009 Annual Meeting, DOI: http://dx.doi.org/10.1016/S1053-8119(09)70884-5

Copyright (C) 1993-2004, Louis Collins McConnell Brain Imaging Centre, Montreal Neurological Institute, McGill University. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies. The authors and McGill University make no representations about the suitability of this software for any purpose. It is provided “as is” without express or implied warranty. The authors are not responsible for any data loss, equipment damage, property loss, or injury to subjects or patients resulting from the use or misuse of this software package.

Examples

Get only the T1 file for version c: >>> T1_nifti = read_mni_template(“c”, contrast = “T1”) # doctest: +SKIP Get both files in this order for version a: >>> T1_nifti, T2_nifti = read_mni_template(contrast = [“T1”, “T2”]) # doctest: +SKIP

read_scil_b0

dipy.data.fetcher.read_scil_b0()

Load GE 3T b0 image form the scil b0 dataset.

Returns:

img : obj,

Nifti1Image

read_sherbrooke_3shell

dipy.data.fetcher.read_sherbrooke_3shell()

Load Sherbrooke 3-shell HARDI dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_siemens_scil_b0

dipy.data.fetcher.read_siemens_scil_b0()

Load Siemens 1.5T b0 image form the scil b0 dataset.

Returns:

img : obj,

Nifti1Image

read_stanford_hardi

dipy.data.fetcher.read_stanford_hardi()

Load Stanford HARDI dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_stanford_labels

dipy.data.fetcher.read_stanford_labels()

Read stanford hardi data and label map

read_stanford_pve_maps

dipy.data.fetcher.read_stanford_pve_maps()

read_stanford_t1

dipy.data.fetcher.read_stanford_t1()

read_syn_data

dipy.data.fetcher.read_syn_data()

Load t1 and b0 volumes from the same session

Returns:

t1 : obj,

Nifti1Image

b0 : obj,

Nifti1Image

read_taiwan_ntu_dsi

dipy.data.fetcher.read_taiwan_ntu_dsi()

Load Taiwan NTU dataset

Returns:

img : obj,

Nifti1Image

gtab : obj,

GradientTable

read_tissue_data

dipy.data.fetcher.read_tissue_data(contrast='T1')

Load images to be used for tissue classification

Parameters:

constrast : str

‘T1’, ‘T1 denoised’ or ‘Anisotropic Power’

Returns:

image : obj,

Nifti1Image

read_viz_icons

dipy.data.fetcher.read_viz_icons(style='icomoon', fname='infinity.png')

Read specific icon from specific style

Parameters:

style : str

Current icon style. Default is icomoon.

fname : str

Filename of icon. This should be found in folder HOME/.dipy/style/. Default is infinity.png.

Returns:

path : str

Complete path of icon.

update_progressbar

dipy.data.fetcher.update_progressbar(progress, total_length)

Show progressbar

Takes a number between 0 and 1 to indicate progress from 0 to 100%.

urlopen

dipy.data.fetcher.urlopen(url, data=None, timeout=<object object>, *, cafile=None, capath=None, cadefault=False, context=None)

Open the URL url, which can be either a string or a Request object.

data must be an object specifying additional data to be sent to the server, or None if no such data is needed. See Request for details.

urllib.request module uses HTTP/1.1 and includes a “Connection:close” header in its HTTP requests.

The optional timeout parameter specifies a timeout in seconds for blocking operations like the connection attempt (if not specified, the global default timeout setting will be used). This only works for HTTP, HTTPS and FTP connections.

If context is specified, it must be a ssl.SSLContext instance describing the various SSL options. See HTTPSConnection for more details.

The optional cafile and capath parameters specify a set of trusted CA certificates for HTTPS requests. cafile should point to a single file containing a bundle of CA certificates, whereas capath should point to a directory of hashed certificate files. More information can be found in ssl.SSLContext.load_verify_locations().

The cadefault parameter is ignored.

This function always returns an object which can work as a context manager and has methods such as

  • geturl() - return the URL of the resource retrieved, commonly used to determine if a redirect was followed
  • info() - return the meta-information of the page, such as headers, in the form of an email.message_from_string() instance (see Quick Reference to HTTP Headers)
  • getcode() - return the HTTP status code of the response. Raises URLError on errors.

For HTTP and HTTPS URLs, this function returns a http.client.HTTPResponse object slightly modified. In addition to the three new methods above, the msg attribute contains the same information as the reason attribute — the reason phrase returned by the server — instead of the response headers as it is specified in the documentation for HTTPResponse.

For FTP, file, and data URLs and requests explicitly handled by legacy URLopener and FancyURLopener classes, this function returns a urllib.response.addinfourl object.

Note that None may be returned if no handler handles the request (though the default installed global OpenerDirector uses UnknownHandler to ensure this never happens).

In addition, if proxy settings are detected (for example, when a *_proxy environment variable like http_proxy is set), ProxyHandler is default installed and makes sure the requests are handled through the proxy.