pynets.dmri package¶

Submodules¶

pynets.dmri.utils module¶

pynets.dmri.utils.evaluate_streamline_plausibility(dwi_data, gtab, mask_data, streamlines, affine=array([[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]]), sphere='repulsion724')[source]¶

Linear Fascicle Evaluation (LiFE) takes any connectome and uses a forward modelling approach to predict diffusion measurements in the same brain.

Parameters

dwi_dataarray: 4D array of dwi data.
gtabObj: DiPy object storing diffusion gradient information.
mask_dataarray: 3D Brain mask.
streamlinesArraySequence: DiPy list/array-like object of streamline points from tractography.

Returns

streamlinesArraySequence: DiPy list/array-like object of streamline points from tractography.

References

1: Pestilli, F., Yeatman, J, Rokem, A. Kay, K. and Wandell B.A. (2014). Validation and statistical inference in living connectomes. Nature Methods 11: 1058-1063. doi:10.1038/nmeth.3098

pynets.dmri.utils.extract_b0(in_file, b0_ixs, out_path=None)[source]¶

Extract the b0 volumes from a DWI dataset.

Parameters

in_filestr: DWI NIfTI file.
b0_ixslist: List of B0 indices in in_file.
out_pathstr: Optionally specify an output path.

Returns

out_pathstr: 4D NIfTI file consisting of B0’s.

pynets.dmri.utils.generate_seeds(seeds)[source]¶

Helper function that takes a sequence and returns a generator

Parameters

seedssequence: Usually, this would be a list of 2D arrays, representing seeds

Returns

generator

pynets.dmri.utils.generate_sl(streamlines)[source]¶

Helper function that takes a sequence and returns a generator

Parameters

streamlinessequence: Usually, this would be a list of 2D arrays, representing streamlines
Returns
——-
generator

pynets.dmri.utils.normalize_gradients(bvecs, bvals, b0_threshold, bvec_norm_epsilon=0.1, b_scale=True)[source]¶

Normalize b-vectors and b-values.

The resulting b-vectors will be of unit length for the non-zero b-values. The resulting b-values will be normalized by the square of the corresponding vector amplitude.

Parameters

bvecsm x n 2d array: Raw b-vectors array.
bvals1d array: Raw b-values float array.
b0_thresholdfloat: Gradient threshold below which volumes and vectors are considered B0’s.

Returns

bvecsm x n 2d array: Unit-normed b-vectors array.
bvals1d int array: Vector amplitude square normed b-values array.

pynets.dmri.utils.random_seeds_from_mask(mask, seeds_count, affine=array([[1.0, 0.0, 0.0, 0.0], [0.0, 1.0, 0.0, 0.0], [0.0, 0.0, 1.0, 0.0], [0.0, 0.0, 0.0, 1.0]]), random_seed=1)[source]¶

Create randomly placed seeds for fiber tracking from a binary mask. Seeds points are placed randomly distributed in voxels of mask which are True. If seed_count_per_voxel is True, this function is similar to seeds_from_mask(), with the difference that instead of evenly distributing the seeds, it randomly places the seeds within the voxels specified by the mask.

Parameters

maskbinary 3d array_like: A binary array specifying where to place the seeds for fiber tracking.
affinearray, (4, 4): The mapping between voxel indices and the point space for seeds. The voxel_to_rasmm matrix, typically from a NIFTI file. A seed point at the center the voxel [i, j, k] will be represented as [x, y, z] where [x, y, z, 1] == np.dot(affine, [i, j, k , 1]).
seeds_countint: The number of seeds to generate. If seed_count_per_voxel is True, specifies the number of seeds to place in each voxel. Otherwise, specifies the total number of seeds to place in the mask.
random_seedint: The seed for the random seed generator (numpy.random.seed).

pynets.dmri.estimation module¶

pynets.dmri.estimation.create_anisopowermap(gtab_file, dwi_file, B0_mask)[source]¶

Estimate an anisotropic power map image to use for registrations.

Parameters

gtab_filestr: File path to pickled DiPy gradient table object.
dwi_filestr: File path to diffusion weighted image.
B0_maskstr: File path to B0 brain mask.

Returns

anisopwr_pathstr: File path to the anisotropic power Nifti1Image.
B0_maskstr: File path to B0 brain mask Nifti1Image.
gtab_filestr: File path to pickled DiPy gradient table object.
dwi_filestr: File path to diffusion weighted Nifti1Image.

References

1: Chen, D. Q., Dell’Acqua, F., Rokem, A., Garyfallidis, E., Hayes, D., Zhong, J., & Hodaie, M. (2018). Diffusion Weighted Image Co-registration: Investigation of Best Practices. PLoS ONE.

pynets.dmri.estimation.csa_mod_est(gtab, data, B0_mask, sh_order=8)[source]¶

Estimate a Constant Solid Angle (CSA) model from dwi data.

Parameters

gtabObj: DiPy object storing diffusion gradient information
dataarray: 4D numpy array of diffusion image data.
B0_maskstr: File path to B0 brain mask.
sh_orderint: The order of the SH model. Default is 8.

Returns

csa_modndarray: Coefficients of the csa reconstruction.
modelobj: Fitted csa model.

References

1: Aganj, I., et al. 2009. ODF Reconstruction in Q-Ball Imaging with Solid Angle Consideration.

pynets.dmri.estimation.csd_mod_est(gtab, data, B0_mask, sh_order=8)[source]¶

Estimate a Constrained Spherical Deconvolution (CSD) model from dwi data.

Parameters

gtabObj: DiPy object storing diffusion gradient information.
dataarray: 4D numpy array of diffusion image data.
B0_maskstr: File path to B0 brain mask.
sh_orderint: The order of the SH model. Default is 8.

Returns

csd_modndarray: Coefficients of the csd reconstruction.
modelobj: Fitted csd model.

References

1: Tournier, J.D., et al. NeuroImage 2007. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution
2: Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions
3: Côté, M-A., et al. Medical Image Analysis 2013. Tractometer: Towards validation of tractography pipelines
4: Tournier, J.D, et al. Imaging Systems and Technology 2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions

pynets.dmri.estimation.mcsd_mod_est(gtab, data, B0_mask, wm_in_dwi, gm_in_dwi, vent_csf_in_dwi, sh_order=8, roi_radii=10)[source]¶

Estimate a Constrained Spherical Deconvolution (CSD) model from dwi data.

Parameters

gtabObj: DiPy object storing diffusion gradient information.
dataarray: 4D numpy array of diffusion image data.
B0_maskstr: File path to B0 brain mask.
sh_orderint: The order of the SH model. Default is 8.

Returns

csd_modndarray: Coefficients of the csd reconstruction.
modelobj: Fitted csd model.

References

1: Tournier, J.D., et al. NeuroImage 2007. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution
2: Descoteaux, M., et al. IEEE TMI 2009. Deterministic and Probabilistic Tractography Based on Complex Fibre Orientation Distributions
3: Côté, M-A., et al. Medical Image Analysis 2013. Tractometer: Towards validation of tractography pipelines
4: Tournier, J.D, et al. Imaging Systems and Technology 2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions

pynets.dmri.estimation.reconstruction(conn_model, gtab, dwi_data, B0_mask)[source]¶

Estimate a tensor model from dwi data.

Parameters

conn_modelstr: Connectivity reconstruction method (e.g. ‘csa’, ‘tensor’, ‘csd’, ‘sfm’).
gtabObj: DiPy object storing diffusion gradient information.
dwi_dataarray: 4D array of dwi data.
B0_maskstr: File path to B0 brain mask.

Returns

mod_fitndarray: Fitted connectivity reconstruction model.
modobj: Connectivity reconstruction model.

References

1: Soares, J. M., Marques, P., Alves, V., & Sousa, N. (2013). A hitchhiker’s guide to diffusion tensor imaging. Frontiers in Neuroscience. https://doi.org/10.3389/fnins.2013.00031

pynets.dmri.estimation.sfm_mod_est(gtab, data, B0_mask, BACKEND='loky')[source]¶

Estimate a Sparse Fascicle Model (SFM) from dwi data.

Parameters

gtabObj: DiPy object storing diffusion gradient information.
dataarray: 4D numpy array of diffusion image data.
B0_maskstr: File path to B0 brain mask.

Returns

sf_modndarray: Coefficients of the sfm reconstruction.
modelobj: Fitted sf model.

References

1: Ariel Rokem, Jason D. Yeatman, Franco Pestilli, Kendrick N. Kay, Aviv Mezer, Stefan van der Walt, Brian A. Wandell (2015). Evaluating the accuracy of diffusion MRI models in white matter. PLoS ONE 10(4): e0123272. doi:10.1371/journal.pone.0123272
2: Ariel Rokem, Kimberly L. Chan, Jason D. Yeatman, Franco Pestilli, Brian A. Wandell (2014). Evaluating the accuracy of diffusion models at multiple b-values with cross-validation. ISMRM 2014.

pynets.dmri.estimation.streams2graph(atlas_for_streams, streams, dir_path, track_type, conn_model, subnet, node_radius, dens_thresh, ID, roi, min_span_tree, disp_filt, parc, prune, atlas, parcellation, labels, coords, norm, binary, traversal, warped_fa, min_length, error_margin)[source]¶

Use tracked streamlines as a basis for estimating a structural connectome.

Parameters

atlas_for_streamsstr

File path to atlas parcellation Nifti1Image in T1w-conformed space.

streamsstr

File path to streamline array sequence in .trk format.

dir_pathstr

Path to directory containing subject derivative data for a given pynets run.

track_typestr

Tracking algorithm used (e.g. ‘local’ or ‘particle’).

conn_modelstr

Connectivity reconstruction method (e.g. ‘csa’, ‘tensor’, ‘csd’).

subnetstr

Resting-state subnet based on Yeo-7 and Yeo-17 naming (e.g. ‘Default’) used to filter nodes in the study of brain subgraphs.

node_radiusint

Spherical centroid node size in the case that coordinate-based centroids are used as ROI’s for tracking.

dens_threshbool

Indicates whether a target graph density is to be used as the basis for thresholding.

IDstr

A subject id or other unique identifier.

roistr

File path to binarized/boolean region-of-interest Nifti1Image file.

min_span_treebool

Indicates whether local thresholding from the Minimum Spanning Tree should be used.

disp_filtbool

Indicates whether local thresholding using a disparity filter and ‘backbone subnet’ should be used.

parcbool

Indicates whether to use parcels instead of coordinates as ROI nodes.

prunebool

Indicates whether to prune final graph of disconnected nodes/isolates.

atlasstr

Name of atlas parcellation used.

parcellationstr

File path to atlas parcellation Nifti1Image in MNI template space.

labelslist

List of string labels corresponding to graph nodes.

coordslist

List of (x, y, z) tuples corresponding to a coordinate atlas used or which represent the center-of-mass of each parcellation node.

normint

Indicates method of normalizing resulting graph.

binarybool

Indicates whether to binarize resulting graph edges to form an unweighted graph.

traversalstr

The statistical approach to tracking. Options are: det (deterministic), closest (clos), boot (bootstrapped), and prob (probabilistic).

warped_fastr

File path to MNI-space warped FA Nifti1Image.

min_lengthint

Minimum fiber length threshold in mm to restrict tracking.

error_marginint

Euclidean margin of error for classifying a streamline as a connection: to an ROI. Default is 2 voxels.

Returns

atlas_for_streamsstr

File path to atlas parcellation Nifti1Image in T1w-conformed space.

streamsstr

File path to streamline array sequence in .trk format.

conn_matrixarray

Adjacency matrix stored as an m x n array of nodes and edges.

track_typestr

Tracking algorithm used (e.g. ‘local’ or ‘particle’).

dir_pathstr

Path to directory containing subject derivative data for given run.

conn_modelstr

Connectivity reconstruction method (e.g. ‘csa’, ‘tensor’, ‘csd’).

subnetstr

Resting-state subnet based on Yeo-7 and Yeo-17 naming (e.g. ‘Default’) used to filter nodes in the study of brain subgraphs.

node_radiusint

Spherical centroid node size in the case that coordinate-based centroids are used as ROI’s for tracking.

dens_threshbool

Indicates whether a target graph density is to be used as the basis for thresholding.

IDstr

A subject id or other unique identifier.

roistr

File path to binarized/boolean region-of-interest Nifti1Image file.

min_span_treebool

Indicates whether local thresholding from the Minimum Spanning Tree should be used.

disp_filtbool

Indicates whether local thresholding using a disparity filter and ‘backbone subnet’ should be used.

parcbool

Indicates whether to use parcels instead of coordinates as ROI nodes.

prunebool

Indicates whether to prune final graph of disconnected nodes/isolates.

atlasstr

Name of atlas parcellation used.

parcellationstr

File path to atlas parcellation Nifti1Image in MNI template space.

labelslist

List of string labels corresponding to graph nodes.

coordslist

List of (x, y, z) tuples corresponding to a coordinate atlas used or which represent the center-of-mass of each parcellation node.

normint

Indicates method of normalizing resulting graph.

binarybool

Indicates whether to binarize resulting graph edges to form an unweighted graph.

traversalstr

The statistical approach to tracking. Options are: det (deterministic), closest (clos), boot (bootstrapped), and prob (probabilistic).

min_lengthint

Minimum fiber length threshold in mm to restrict tracking.

error_marginint

Euclidean margin of error for classifying a streamline as a connection: to an ROI. Default is 2 voxels.

References

1: Sporns, O., Tononi, G., & Kötter, R. (2005). The human connectome: A structural description of the human brain. PLoS Computational Biology. https://doi.org/10.1371/journal.pcbi.0010042
2: Sotiropoulos, S. N., & Zalesky, A. (2019). Building connectomes using diffusion MRI: why, how and but. NMR in Biomedicine. https://doi.org/10.1002/nbm.3752
3: Chung, M. K., Hanson, J. L., Adluru, N., Alexander, A. L., Davidson, R. J., & Pollak, S. D. (2017). Integrative Structural Brain subnet Analysis in Diffusion Tensor Imaging. Brain Connectivity. https://doi.org/10.1089/brain.2016.0481

pynets.dmri.estimation.tens_mod_est(gtab, data, B0_mask)[source]¶

Estimate a tensor ODF model from dwi data.

Parameters

gtabObj: DiPy object storing diffusion gradient information
dataarray: 4D numpy array of diffusion image data.
B0_maskstr: File path to B0 brain mask.

Returns

mod_odfndarray: Coefficients of the tensor reconstruction.
modelobj: Fitted tensor model.

References

1: Basser PJ, Mattielo J, LeBihan (1994). MR diffusion tensor spectroscopy and imaging.
2: Pajevic S, Pierpaoli (1999). Color schemes to represent the orientation of anisotropic tissues from diffusion tensor data: application to white matter fiber tract mapping in the human brain.

pynets.dmri.estimation.tens_mod_fa_est(gtab_file, dwi_file, B0_mask)[source]¶

Estimate a tensor FA image to use for registrations.

Parameters

gtab_filestr: File path to pickled DiPy gradient table object.
dwi_filestr: File path to diffusion weighted image.
B0_maskstr: File path to B0 brain mask.

Returns

fa_pathstr: File path to FA Nifti1Image.
B0_maskstr: File path to B0 brain mask Nifti1Image.
gtab_filestr: File path to pickled DiPy gradient table object.
dwi_filestr: File path to diffusion weighted Nifti1Image.
fa_md_pathstr: File path to FA/MD mask Nifti1Image.

pynets.dmri.track module¶

pynets.dmri.track.create_density_map(fa_img, dir_path, streamlines, conn_model, node_radius, curv_thr_list, step_list, subnet, roi, traversal, min_length, namer_dir)[source]¶

Create a density map of the list of streamlines.

Parameters

fa_imgNifti1Image: Dwi data stored as a Nifti1image object.
dir_pathstr: Path to directory containing subject derivative data for a given pynets run.
streamlinesArraySequence: DiPy list/array-like object of streamline points from tractography.
conn_modelstr: Connectivity reconstruction method (e.g. ‘csa’, ‘tensor’, ‘csd’).
node_radiusint: Spherical centroid node size in the case that coordinate-based centroids are used as ROI’s for tracking.
curv_thr_listlist: List of integer curvature thresholds used to perform ensemble tracking.
step_listlist: List of float step-sizes used to perform ensemble tracking.
subnetstr: Resting-state subnet based on Yeo-7 and Yeo-17 naming (e.g. ‘Default’) used to filter nodes in the study of brain subgraphs.
roistr: File path to binarized/boolean region-of-interest Nifti1Image file.
traversalstr: The statistical approach to tracking. Options are: det (deterministic), closest (clos), boot (bootstrapped), and prob (probabilistic).
min_lengthint: Minimum fiber length threshold in mm to restrict tracking.

Returns

streamsstr: File path to saved streamline array sequence in DTK-compatible trackvis (.trk) format.
dir_pathstr: Path to directory containing subject derivative data for a given pynets run.
dm_pathstr: File path to fiber density map Nifti1Image.

pynets.dmri.track.prep_tissues(t1_mask, gm_in_dwi, vent_csf_in_dwi, wm_in_dwi, tiss_class, B0_mask, cmc_step_size=0.2)[source]¶

Estimate a tissue classifier for tractography.

Parameters

t1_maskNifti1Image: T1w mask img.
gm_in_dwiNifti1Image: Grey-matter tissue segmentation Nifti1Image.
vent_csf_in_dwiNifti1Image: Ventricular CSF tissue segmentation Nifti1Image.
wm_in_dwiNifti1Image: White-matter tissue segmentation Nifti1Image.
tiss_classstr: Tissue classification method.
cmc_step_sizefloat: Step size from CMC tissue classification method.

Returns

tiss_classifierobj: Tissue classifier object.

References

1: Zhang, Y., Brady, M. and Smith, S. Segmentation of Brain MR Images Through a Hidden Markov Random Field Model and the Expectation-Maximization Algorithm IEEE Transactions on Medical Imaging, 20(1): 45-56, 2001
2: Avants, B. B., Tustison, N. J., Wu, J., Cook, P. A. and Gee, J. C. An open source multivariate framework for n-tissue segmentation with evaluation on public data. Neuroinformatics, 9(4): 381-400, 2011.

pynets.dmri.track.run_tracking(step_curv_combinations, recon_shelved, n_seeds_per_iter, traversal, maxcrossing, max_length, pft_back_tracking_dist, pft_front_tracking_dist, particle_count, roi_neighborhood_tol, min_length, track_type, min_separation_angle, sphere, tiss_class, tissue_shelved, verbose=False)[source]¶

Create a density map of the list of streamlines.

Parameters

step_curv_combinationslist: List of tuples representing all pair combinations of step sizes and curvature thresholds from which to sample streamlines.
recon_pathstr: File path to diffusion reconstruction model.
n_seeds_per_iterint: Number of seeds from which to initiate tracking for each unique ensemble combination. By default this is set to 250.
directgetstr: The statistical approach to tracking. Options are: det (deterministic), closest (clos), boot (bootstrapped), and prob (probabilistic).
maxcrossingint: Maximum number if diffusion directions that can be assumed per voxel while tracking.
max_lengthint: Maximum number of steps to restrict tracking.
pft_back_tracking_distfloat: Distance in mm to back track before starting the particle filtering tractography. The total particle filtering tractography distance is equal to back_tracking_dist + front_tracking_dist. By default this is set to 2 mm.
pft_front_tracking_distfloat: Distance in mm to run the particle filtering tractography after the the back track distance. The total particle filtering tractography distance is equal to back_tracking_dist + front_tracking_dist. By default this is set to 1 mm.
particle_countint: Number of particles to use in the particle filter.
roi_neighborhood_tolfloat: Distance (in the units of the streamlines, usually mm). If any coordinate in the streamline is within this distance from the center of any voxel in the ROI, the filtering criterion is set to True for this streamline, otherwise False. Defaults to the distance between the center of each voxel and the corner of the voxel.
waymask_datandarray: Tractography constraint mask array in native diffusion space.
min_lengthint: Minimum fiber length threshold in mm to restrict tracking.
track_typestr: Tracking algorithm used (e.g. ‘local’ or ‘particle’).
min_separation_anglefloat: The minimum angle between directions [0, 90].
sphereobj: DiPy object for modeling diffusion directions on a sphere.
tiss_classstr: Tissue classification method.
tissue_shelvedstr: File path to joblib-shelved 4D T1w tissue segmentations in native diffusion space.

Returns

streamlinesArraySequence: DiPy list/array-like object of streamline points from tractography.

pynets.dmri.track.track_ensemble(target_samples, atlas_data_wm_gm_int, labels_im_file, recon_path, sphere, traversal, curv_thr_list, step_list, track_type, maxcrossing, roi_neighborhood_tol, min_length, waymask, B0_mask, t1w2dwi, gm_in_dwi, vent_csf_in_dwi, wm_in_dwi, tiss_class, BACKEND='threading')[source]¶

Perform native-space ensemble tractography, restricted to a vector of ROI masks.

Parameters

target_samplesint: Total number of streamline samples specified to generate streams.
atlas_data_wm_gm_intstr: File path to Nifti1Image in T1w-warped native diffusion space, restricted to wm-gm interface.
parcelslist: List of 3D boolean numpy arrays of atlas parcellation ROI masks from a Nifti1Image in T1w-warped native diffusion space.
recon_pathstr: File path to diffusion reconstruction model.
tiss_classifierstr: Tissue classification method.
sphereobj: DiPy object for modeling diffusion directions on a sphere.
traversalstr: The statistical approach to tracking. Options are: det (deterministic), closest (clos), and prob (probabilistic).
curv_thr_listlist: List of integer curvature thresholds used to perform ensemble tracking.
step_listlist: List of float step-sizes used to perform ensemble tracking.
track_typestr: Tracking algorithm used (e.g. ‘local’ or ‘particle’).
maxcrossingint: Maximum number if diffusion directions that can be assumed per voxel while tracking.
roi_neighborhood_tolfloat: Distance (in the units of the streamlines, usually mm). If any coordinate in the streamline is within this distance from the center of any voxel in the ROI, the filtering criterion is set to True for this streamline, otherwise False. Defaults to the distance between the center of each voxel and the corner of the voxel.
min_lengthint: Minimum fiber length threshold in mm.
waymask_datandarray: Tractography constraint mask array in native diffusion space.
B0_mask_datandarray: B0 brain mask data.
n_seeds_per_iterint: Number of seeds from which to initiate tracking for each unique ensemble combination. By default this is set to 250.
max_lengthint: Maximum number of steps to restrict tracking.
particle_count: pft_back_tracking_dist : float Distance in mm to back track before starting the particle filtering tractography. The total particle filtering tractography distance is equal to back_tracking_dist + front_tracking_dist. By default this is set to 2 mm.
pft_front_tracking_distfloat: Distance in mm to run the particle filtering tractography after the the back track distance. The total particle filtering tractography distance is equal to back_tracking_dist + front_tracking_dist. By default this is set to 1 mm.
particle_countint: Number of particles to use in the particle filter.
min_separation_anglefloat: The minimum angle between directions [0, 90].

Returns

streamlinesArraySequence: DiPy list/array-like object of streamline points from tractography.

References

1: Takemura, H., Caiafa, C. F., Wandell, B. A., & Pestilli, F. (2016). Ensemble Tractography. PLoS Computational Biology. https://doi.org/10.1371/journal.pcbi.1004692

pynets.dmri package¶

Submodules¶

pynets.dmri.utils module¶

pynets.dmri.estimation module¶

pynets.dmri.track module¶

Module contents¶