scilpy.tractanalysis package

scilpy.tractanalysis.afd_along_streamlines module

scilpy.tractanalysis.afd_along_streamlines.afd_and_rd_sums_along_streamlines(sft, fodf, fodf_basis, length_weighting, is_legacy=True)

Compute the mean Apparent Fiber Density (AFD) and mean Radial fODF (radfODF) maps along a bundle.

Parameters:

• sft (StatefulTractogram) – StatefulTractogram containing the streamlines needed.

• fodf (nibabel.image) – fODF with shape (X, Y, Z, #coeffs). #coeffs depend on the sh_order.

• fodf_basis (string) – Has to be descoteaux07 or tournier07.

• length_weighting (bool) – If set, will weigh the AFD values according to segment lengths.

• is_legacy (bool, optional) – Whether or not the SH basis is in its legacy form.

Returns:

• afd_sum_map (np.array) – AFD map.

• rd_sum_map (np.array) – fdAFD map.

• weight_map (np.array) – Segment lengths.

scilpy.tractanalysis.afd_along_streamlines.afd_map_along_streamlines(sft, fodf, fodf_basis, length_weighting, is_legacy=True)

Compute the mean Apparent Fiber Density (AFD) and mean Radial fODF (radfODF) maps along a bundle.

Parameters:

• sft (StatefulTractogram) – StatefulTractogram containing the streamlines needed.

• fodf (nibabel.image) – fODF with shape (X, Y, Z, #coeffs) coeffs depending on the sh_order

• fodf_basis (string) – Has to be descoteaux07 or tournier07

• length_weighting (bool) – If set, will weigh the AFD values according to segment lengths

Returns:

• afd_sum (np.array) – AFD map (weighted if length_weighting)

• rd_sum (np.array) – rdAFD map (weighted if length_weighting)

scilpy.tractanalysis.bingham_metric_along_streamlines module

scilpy.tractanalysis.bingham_metric_along_streamlines.bingham_metric_map_along_streamlines(sft, bingham_coeffs, metric, max_theta, length_weighting)

Compute mean map for a given Bingham metric along streamlines.

Parameters:

• sft (StatefulTractogram) – StatefulTractogram containing the streamlines needed.

• bingham_coeffs (ndarray) – Array of shape (X, Y, Z, N_LOBES, NB_PARAMS) containing the Bingham distributions parameters.

• metric (ndarray) – Array of shape (X, Y, Z) containing the Bingham metric of interest.

• max_theta (float) – Maximum angle in degrees between the fiber direction and the Bingham peak direction.

• length_weighting (bool) – If True, will weigh the metric values according to segment lengths.

scilpy.tractanalysis.bingham_metric_along_streamlines.bingham_metric_sum_along_streamlines(sft, bingham_coeffs, metric, max_theta, length_weighting)

Compute a sum map along a bundle for a given Bingham metric.

Parameters:

• sft (StatefulTractogram) – StatefulTractogram containing the streamlines needed.

• bingham_coeffs (ndarray (X, Y, Z, N_LOBES, NB_PARAMS)) – Bingham distributions parameters volume.

• metric (ndarray (X, Y, Z)) – The Bingham metric of interest.

• max_theta (float) – Maximum angle in degrees between the fiber direction and the Bingham peak direction.

• length_weighting (bool) – If True, will weight the metric values according to segment lengths.

Returns:

• metric_sum_map (np.array) – Bingham metric sum map.

• weight_map (np.array) – Segment lengths.

scilpy.tractanalysis.distance_to_centroid module

scilpy.tractanalysis.distance_to_centroid.associate_labels(target_sft, min_label=1, max_label=20)

Associate labels to the streamlines in a target SFT using their lengths. Even if unequal distance between points, the labels are interpolated linearly so all the points are labeled according to their position.

min and max labels are used in case there is a cut in the bundle.

Parameters:

target_sft: StatefulTractogram

The target SFT to label, streamlines can be in any space.

min_label: int

Minimum label to use.

max_label: int

Maximum label to use.

Returns:

Array: np.uint16

Labels for each point along the streamlines.

scilpy.tractanalysis.distance_to_centroid.closest_match_to_centroid(bundle_pts, centroid_pts, nb_pts)

Assign a label to each point in the bundle_pts based on the closest centroid_pts. The labels are between 1 and nb_pts, where nb_pts is the number of points in the centroid_pts. The labels are assigned based on the order of the centroid_pts.

The 3D points are expected to be in the same space.

Typically the bundle_pts will be voxel indices (from argwhere) and the centroid_pts will be the 3D positions of a single streamline.

Parameters:

• bundle_pts (np.array) – Coordinates of all streamlines (N x nb_pts x 3)

• centroid_pts (np.array) – Coordinates of all streamlines (nb_pts x 3)

• nb_pts (int) – Number of point for the association to centroids

Returns:

Labels (between 1 and nb_pts) for all bundle points

Return type:

Array

scilpy.tractanalysis.distance_to_centroid.compute_distance_map(labels_map, binary_mask, nb_pts, use_manhattan=False)

Computes the distance map for each label in the labels_map.

Parameters:

labels_map (numpy.ndarray):

A 3D array representing the labels map.

binary_mask (numpy.ndarray):

A 3D binary map used to calculate barycenter binary map.

nb_pts (int):

Number of points to use for computing barycenters.

use_manhattan (bool):

If True, use the Manhattan distance instead of the Euclidian distance.

Returns:

numpy.ndarray: A 3D array representing the distance map.

scilpy.tractanalysis.distance_to_centroid.compute_labels_map_barycenters(labels_map, is_euclidian=False, nb_pts=False)

Compute the barycenter for each label in a 3D NumPy array by maximizing the distance to the boundary.

Parameters:

labels_map: (ndarray)

The 3D array containing labels from 1-nb_pts. euclidian (bool): If True, the barycenter is the mean of the points in the mask. If False, the barycenter is the medoid of the points in the mask.

is_euclidian: bool

If True, the barycenter is the mean of the points in the mask. If False, the barycenter is the medoid of the points in the mask. This is useful for the hyperplane method.

nb_pts: int

Number of points to use for computing barycenters.

Returns:

ndarray:

An array of size (nb_pts, 3) containing the barycenter for each label.

scilpy.tractanalysis.distance_to_centroid.correct_labels_jump(labels_map, streamlines, nb_pts)

Correct the labels jump in the labels map by cutting the streamlines where the jump is detected and keeping the longest chunk.

This avoid loops in the labels map and ensure that the labels are consistent along the streamlines.

Parameters:

labels_map (ndarray):

A 3D array representing the labels map.

streamlines (ArraySequence):

The streamlines used to compute the labels map.

nb_pts (int):

Number of points to use for computing barycenters.

Returns:

ndarray: A 3D array representing the corrected labels map.

scilpy.tractanalysis.distance_to_centroid.find_medoid(points, max_points=10000)

Find the medoid among a set of points. A medoid is a point that minimizes the sum of the distances to all other points. Unlike a barycenter, the medoid is guaranteed to be one of the points in the set.

Parameters:

points: ndarray

An array of 3D coordinates.

max_points: int

Maximum number of points to use for the computation (will randomly select points if the number of points is greater than max_points).

Returns:

np.array:

The 3D coordinates of the medoid.

scilpy.tractanalysis.distance_to_centroid.masked_manhattan_distance(mask, target_positions)

Compute the Manhattan distance from every position in a mask to a set of positions, without stepping out of the mask.

Parameters:

mask (ndarray):

A binary 3D array representing the mask.

target_positions (list):

A list of target positions within the mask.

Returns:

ndarray:

A 3D array of the same shape as the mask, containing the Manhattan distances.

scilpy.tractanalysis.distance_to_centroid.subdivide_bundles(sft, sft_centroid, binary_mask, nb_pts, method='centerline', fix_jumps=True)

Function to divide a bundle into multiple section along its length. The resulting labels map is based on the binary_mask, but the streamlines are required for a few internal corrections (for consistency).

The default is to use the euclidian/centerline method, which is fast and works well for most cases.

The hyperplane method allows for more complex shapes and to split the bundles into subsections that follow the geometry of each kind of bundle. However, this method is slower and requires extra quality control to ensure that the labels are correct. This method requires a centroid file that contains multiple streamlines.

Parameters:

sft (StatefulTractogram):

Represent the streamlines to be subdivided, streamlines representation is useful fro the fix_jump parameter.

sft_centroid (StatefulTractogram):

Centroids used as a reference for subdivision.

binary_mask (ndarray):

Mask to be converted to a label mask

nb_pts (int):

Number of subdivision along streamlines’ length

method (str):

Choice between centerline or hyperplane for subdivision

fix_jumps (bool):

Run the correction for streamlines to reduce big transition along its length.

Returns:

ndarray:

A 3D array representing the labels map.

scilpy.tractanalysis.features module

scilpy.tractanalysis.voxel_boundary_intersection module

scilpy.tractanalysis.voxel_boundary_intersection.subdivide_streamlines_at_voxel_faces()

scilpy.tractanalysis.json_utils module

scilpy.tractanalysis.json_utils.average_dict(curr_dict)

Compute the mean and std of a metric in a json file

Parameters:

curr_dict (dict)

Return type:

dictionary with mean and std computed

scilpy.tractanalysis.json_utils.merge_dict(dict_1, dict_2, no_list=False, recursive=False)

Merge two dictionary (used for tractometry)

Parameters:

• dict_1 (dict) – dictionary to merge

• dict_2 (dict) – dictionary to merge

• no_list (boolean) – If False it merge list else it will create a list of list

• recursive (boolean) –

  If true it will try to go as deep as possible in the dict

  to get to the list or value instead of updating dictionaries

Returns:

new_dict – Merged dictionary

Return type:

dict

scilpy.tractanalysis.reproducibility_measures module

scilpy.tractanalysis.scoring module

scilpy.tractanalysis.streamlines_metrics module

scilpy.tractanalysis.streamlines_metrics.compute_tract_counts_map()

scilpy.tractanalysis.todi_util module

scilpy.tractanalysis.todi_util.compute_vectors_norm(vectors)

scilpy.tractanalysis.todi_util.generate_mask_indices_1d(nb_voxel, indices_1d)

scilpy.tractanalysis.todi_util.get_dir_to_sphere_id(vectors, sphere_vertices)

Find the closest vector on the sphere vertices using a cKDT tree

sphere_vertices must be normed (or all with equal norm).

Parameters:

• vectors (numpy.ndarray (2D)) – Vectors representing the direction (x,y,z) of segments.

• sphere_vertices (numpy.ndarray (2D)) – Vertices of a Dipy sphere object.

Returns:

dir_sphere_id – Sphere indices of the closest sphere direction for each vector

Return type:

numpy.ndarray (1D)

scilpy.tractanalysis.todi_util.get_indices_1d(volume_shape, pts)

scilpy.tractanalysis.todi_util.get_segments_dir_and_norm(segments, seg_mid=None, asymmetric=False)

scilpy.tractanalysis.todi_util.get_segments_mid_pts_positions(segments)

scilpy.tractanalysis.todi_util.get_segments_vectors(segments)

scilpy.tractanalysis.todi_util.get_vectors_dir_and_norm(vectors)

scilpy.tractanalysis.todi_util.get_vectors_dir_and_norm_rel_to_center(vectors, seg_mid_pts)

Evaluates vectors direction and norm by taking into account the orientation and position of segments in relation to the center of voxel

scilpy.tractanalysis.todi_util.normalize_vectors(vectors)

scilpy.tractanalysis.todi_util.p_normalize_vectors(vectors, p)

scilpy.tractanalysis.todi_util.psf_from_sphere(sphere_vertices)

scilpy.tractanalysis.todi_util.streamlines_to_endpoints(streamlines)

Equivalent to streamlines resampling to 2 points (first and last).

Parameters:

streamlines (list of numpy.ndarray) – List of streamlines.

Returns:

endpoints – Endpoint array representation with the first and last points.

Return type:

numpy.ndarray (2D)

scilpy.tractanalysis.todi_util.streamlines_to_pts_dir_norm(streamlines, n_steps=1, asymmetric=False)

Evaluate each segment: mid position, direction, length.

Parameters:

streamlines (list of numpy.ndarray) – List of streamlines.

Returns:

• seg_mid (numpy.ndarray (2D)) – Mid position (x,y,z) of all streamlines’ segments.

• seg_dir (numpy.ndarray (2D)) – Direction (x,y,z) of all streamlines’ segments.

• seg_norm (numpy.ndarray (2D)) – Length of all streamlines’ segments.

scilpy.tractanalysis.todi_util.streamlines_to_segments(streamlines, n_steps=1)

Split streamlines into its segments.

Parameters:

streamlines (list of numpy.ndarray) – List of streamlines.

Returns:

segments – Segments array representation with the first and last points.

Return type:

numpy.ndarray (2D)

scilpy.tractanalysis.todi module

class scilpy.tractanalysis.todi.TrackOrientationDensityImaging(img_shape, sphere_type='repulsion724')

Bases: object

compute_average_dir()

Voxel-wise average of TODI orientations.

Average all orientation of each voxel, of the TODI map, into a single direction, warning for crossing.

Returns:

avg_dir – Volume containing a single 3-vector (peak) per voxel.

Return type:

numpy.ndarray (4D)

compute_distance_to_peak(peak_img, normalize_count=True, deg=True, with_avg_dir=True)

Compute distance to peak map.

Compute the distance of the TODI map to peaks at each position, in radian or degree.

Parameters:

• peak_img (numpy.ndarray (4D)) – Peaks image, as written by most of Scilpy scripts.

• normalize_count (bool, optional) – Normalize/weight the error map by the density map (default True).

• deg (bool, optional) – Returned error map as degree instead of radian (default True).

• with_avg_dir (bool, optional) – Average all orientation of each voxel of the TODI map into a single direction, warning for crossing (default True).

Returns:

error_map – Average angle error map per voxel.

Return type:

numpy.ndarray (3D)

compute_todi(streamlines, length_weights=True, n_steps=1, asymmetric=False)

Compute the TODI map.

At each voxel an histogram distribution of the local streamlines orientations (TODI) is computed.

Parameters:

• streamlines (list of numpy.ndarray) – List of streamlines.

• length_weights (bool, optional) – Weights TODI map of each segment’s length (default True).

get_mask()

get_sh(sh_basis, sh_order, smooth=0.006, full_basis=False, is_legacy=True)

Spherical Harmonics (SH) coefficients of the TODI map

Compute the SH representation of the TODI map, converting SF to SH with a smoothing factor.

Parameters:

• sh_basis ({None, 'tournier07', 'descoteaux07'}) – None for the default DIPY basis, tournier07 for the Tournier 2007 [2] basis, and descoteaux07 for the Descoteaux 2007 [1] basis (None defaults to descoteaux07).

• sh_order (int) – Maximum SH order in the SH fit. For sh_order, there will be (sh_order + 1) * (sh_order_2) / 2 SH coefficients (default 4).

• smooth (float, optional) – Smoothing factor for the conversion, Lambda-regularization in the SH fit (default 0.006).

• is_legacy (bool, optional) – Whether or not the SH basis is in its legacy form.

Returns:

todi_sh – SH representation of the TODI map

Return type:

ndarray

References

[1]

Descoteaux, M., Angelino, E., Fitzgibbons, S. and Deriche, R. Regularized, Fast, and Robust Analytical Q-ball Imaging. Magn. Reson. Med. 2007;58:497-510.

[2]

Tournier J.D., Calamante F. and Connelly A. Robust determination of the fibre orientation distribution in diffusion MRI: Non-negativity constrained super-resolved spherical deconvolution. NeuroImage. 2007;35(4):1459-1472.

get_tdi()

Compute the TDI map.

Compute the Tract Density Image (TDI) from the TODI volume.

Returns:

tdi – Tract Density Image

Return type:

numpy.ndarray (3D)

get_todi()

get_todi_shape()

mask_todi(mask)

Mask the TODI map.

Mask the TODI without having to reshape the whole volume all at once (big in memory).

Parameters:

mask (numpy.ndarray) – Given volume mask for the TODI map.

normalize_todi_per_voxel(p_norm=2)

Normalize TODI map.

Normalize TODI distribution on the sphere for each voxel independently.

Parameters:

p_norm (int, optional) – Chosen Norm to normalize.

Returns:

todi – Normalized TODI map.

Return type:

numpy.ndarray

reshape_to_3d(img_voxelly_masked)

Reshape a complex ravelled image to 3D.

Unravel a given unravel mask (1D), image (1D), SH/SF (2D) to its original 3D shape (with a 4D for SH/SF).

Parameters:

img_voxelly_masked (numpy.ndarray (either in 1D, 2D or 3D)) – That will be reshaped to 3D (input data shape) accordingly. Necessary for future masking operation.

Returns:

unraveled_img – Unravel volume in x, y, z (, c).

Return type:

numpy.ndarray (3D, or 4D)

set_todi(mask, todi)

smooth_todi_dir(order=2)

Smooth orientations on the sphere.

Smooth the orientations / distribution on the sphere. Important for priors construction of BST.

Parameters:

order (int, optional) – Exponent blurring factor, based on the dot product (default 2).

smooth_todi_spatial(sigma=0.5)

Spatial Smoothing of the TODI map.

Blur the TODI map using neighborhood information. Important for priors construction of BST.

Parameters:

sigma (float, optional) – Gaussian blurring factor (default 0.5).

scilpy.tractanalysis.tools module