scilpy.tractograms package

scilpy.tractograms.dps_and_dpp_management module

scilpy.tractograms.dps_and_dpp_management.add_data_as_color_dpp(sft, cmap, data, clip_outliers=False, min_range=None, max_range=None, min_cmap=None, max_cmap=None, log=False, LUT=None)

Normalizes data between 0 and 1 for an easier management with colormaps. The real lower bound and upperbound are returned.

Data can be clipped to (min_range, max_range) before normalization. Alternatively, data can be kept as is, but the colormap be fixed to (min_cmap, max_cmap).

Parameters:

• sft (StatefulTractogram) – The tractogram

• cmap (plt colormap) – The colormap. Ex, see scilpy.viz.utils.get_colormap().

• data (np.ndarray or list[list] or list[np.ndarray]) – The data to convert to color. Expecting one value per point to add as dpp. If instead data has one value per streamline, setting the same color to all points of the streamline (as dpp). Either a vector numpy array (all streamlines concatenated), or a list of arrays per streamline.

• clip_outliers (bool) – See description of the following parameters in clip_and_normalize_data_for_cmap.

• min_range (float) – Data values below min_range will be clipped.

• max_range (float) – Data values above max_range will be clipped.

• min_cmap (float) – Minimum value of the colormap. Most useful when min_range and max_range are not set; to fix the colormap range without modifying the data.

• max_cmap (float) – Maximum value of the colormap. Idem.

• log (bool) – If True, apply a logarithmic scale to the data.

• LUT (np.ndarray) – If set, replaces the data values by the Look-Up Table values. In order, the first value of the LUT is set everywhere where data==1, etc.

Returns:

• sft (StatefulTractogram) – The tractogram, with dpp ‘color’ added.

• lbound (float) – The lower bound of the associated colormap.

• ubound (float) – The upper bound of the associated colormap.

scilpy.tractograms.dps_and_dpp_management.convert_dps_to_dpp(sft, keys, overwrite=False)

Copy the value of the data_per_streamline to each point of the streamline, as data_per_point. The dps key is removed and added as dpp key.

Parameters:

• sft (StatefulTractogram)

• keys (str or List[str], optional) – The list of dps keys to convert to dpp.

• overwrite (bool) – If true, allow continuing even if the key already existed as dpp.

scilpy.tractograms.dps_and_dpp_management.perform_correlation_on_endpoints(sft, dpp_name='metric')

Peforms correlation across endpoints for each streamline. The data_per_point at each point must be a vector.

Parameters:

• sft (StatefulTractogram) – The streamlines used in the operation.

• dpp_name (str) – The name of the data per point to be used in the operation.

Returns:

new_data_per_streamline – The correlation values that could now be associated to a new data_per_streamline key.

Return type:

List

scilpy.tractograms.dps_and_dpp_management.perform_operation_dpp_to_dps(op_name, sft, dpp_name, endpoints_only=False)

Converts dpp to dps, using a chosen operation.

Performs an operation across all data_per_points for each streamline (mean, sum, min, max). The result is a data_per_streamline.

If the data_per_point at each point is a vector, operation is done on each feature individually. The data_per_streamline will have the same shape.

Parameters:

• op_name (str) – A callable that takes a list of streamline data per streamline and returns a list of data per streamline.

• sft (StatefulTractogram) – The streamlines used in the operation.

• dpp_name (str) – The name of the data per point to be used in the operation.

• endpoints_only (bool) – If True, will only perform operation on endpoints. Other points will be ignored in the operation.

Returns:

new_data_per_streamline – The values that could now be associated to a new data_per_streamline key.

Return type:

list

scilpy.tractograms.dps_and_dpp_management.perform_operation_on_dpp(op_name, sft, dpp_name, endpoints_only=False)

Peforms an operation on the data per point for all streamlines (mean, sum, min, max). The operation is applied on each point invidiually, and thus makes sense if the data_per_point at each point is a vector. The result is a new data_per_point.

Parameters:

• op_name (str) – Name of one possible operation (mean, sum, min, max). Will refer to a callable that takes a list of streamline data per point (4D) and returns a list of streamline data per point.

• sft (StatefulTractogram) – The streamlines used in the operation.

• dpp_name (str) – The name of the data per point to be used in the operation. sft.data_per_point[dpp_name][s] must be a 2D vector: (N, M) with s, a given streamline; N the number of points; M the number of features in the dpp.

• endpoints_only (bool) – If True, will only perform operation on endpoints. Values at other points will be set to NaN.

Returns:

new_data_per_point – The values that could now be associated to a new data_per_point key.

Return type:

list[np.ndarray]

scilpy.tractograms.dps_and_dpp_management.project_dpp_to_map(sft, dpp_key, sum_lines=False, endpoints_only=False)

Saves the values of data_per_point keys to the underlying voxels. Averages the values of various streamlines in each voxel. Returns one map per key. The streamlines are not preprocessed here. You should probably first uncompress your streamlines to have smoother maps. Note: If a streamline has two points in the same voxel, it counts twice!

Parameters:

• sft (StatefulTractogram) – The tractogram

• dpp_key (str) – The data_per_point key to project to a map.

• sum_lines (bool) – Do not average values of streamlines that cross a same voxel; sum them instead.

• endpoints_only (bool) – If true, only project the streamline’s endpoints.

Returns:

the_map – The 3D resulting map.

Return type:

np.ndarray

scilpy.tractograms.dps_and_dpp_management.project_map_to_streamlines(sft, map_volume, endpoints_only=False)

Projects a map onto the points of streamlines. The result is a data_per_point.

Parameters:

• sft (StatefulTractogram) – Input tractogram.

• map_volume (DataVolume) – Input map.

• endpoints_only (bool, optional) – If True, will only project the map_volume onto the endpoints of the streamlines (all values along streamlines set to NaN). If False, will project the map_volume onto all points of the streamlines.

Returns:

streamline_data – The values that could now be associated to a data_per_point key. The map_volume projected to each point of the streamlines.

Return type:

List[List]

scilpy.tractograms.lazy_tractogram_operations module

scilpy.tractograms.lazy_tractogram_operations.lazy_concatenate(in_tractograms, out_ext)

Parameters:

• in_tractograms (list) – List of filenames to concatenate

• out_ext (str) – Output format. Accepting .trk and .tck.

Returns:

• out_tractogram (Lazy tractogram) – The concatenated data

• header (nibabel header or None) – Depending on the data type.

scilpy.tractograms.lazy_tractogram_operations.lazy_streamlines_count(in_tractogram_path)

Gets the number of streamlines as written in the tractogram header.

Parameters:

in_tractogram_path (str) – Tractogram filepath, must be .trk or .tck.

Returns:

count – Number of streamlines present in the tractogram.

Return type:

int

scilpy.tractograms.streamline_and_mask_operations module

scilpy.tractograms.tractogram_operations module

This module regroups small operations and util functions for tractogram. Meaning that these operations are applied on the streamlines as wholes (ex, registration, suffling, etc), not on each point of the streamlines separately / individually. See scilpy.tractograms.streamline_operations.py for the latter.

scilpy.tractograms.tractogram_operations.compress_streamlines_wrapper(tractogram, error_rate)

Compresses the streamlines of a tractogram. Supports both nibabel.Tractogram dipy.StatefulTractogram or list of streamlines.

Parameters:

• tractogram (TrkFile, TckFile, ArraySequence, list) – The tractogram to compress.

• error_rate (float) – The maximum distance (in mm) for point displacement during compression.

Returns:

compressed_streamlines – The compressed streamlines.

Return type:

list of np.ndarray

scilpy.tractograms.tractogram_operations.concatenate_sft(sft_list, erase_metadata=False, metadata_fake_init=False)

Concatenate a list of StatefulTractogram together

scilpy.tractograms.tractogram_operations.difference(left, right)

Difference of two streamlines dict (see hash_streamlines)

scilpy.tractograms.tractogram_operations.difference_robust(streamlines_list, precision=3)

Difference of a list of StatefulTractogram from the first element

scilpy.tractograms.tractogram_operations.flip_sft(sft, flip_axes)

Parameters:

• sft (StatefulTractogram)

• flip_axes (List[str]) – The list of axes to flip. Ex: [‘x’, ‘y’, ‘z’]. The axes correspond to the coordinates of the sft as it is stored in memory, not to axes of the image.

Returns:

flipped_sft

Return type:

StatefulTractogram

scilpy.tractograms.tractogram_operations.get_axis_flip_vector(flip_axes)

Create a flip vector from a list of axes.

Parameters:

flip_axes (list) – List of axes you want to flip

Returns:

shift_vector – Vector with flipped axes

Return type:

list[3,]

scilpy.tractograms.tractogram_operations.intersection(left, right)

Intersection of two streamlines dict (see hash_streamlines)

scilpy.tractograms.tractogram_operations.intersection_robust(streamlines_list, precision=3)

Intersection of a list of StatefulTractogram

scilpy.tractograms.tractogram_operations.perform_tractogram_operation_on_lines(operation, streamlines, precision=None)

Peforms an operation on a list of list of streamlines.

Given a list of list of streamlines, this function applies the operation to the first two lists of streamlines. The result in then used recursively with the third, fourth, etc. lists of streamlines.

A valid operation is any function that takes two streamlines dict as input and produces a new streamlines dict (see hash_streamlines). Union, difference, and intersection are valid examples of operations.

Parameters:

• operation (callable) – A callable that takes two streamlines dicts as inputs and preduces a new streamline dict.

• streamlines (list of list of streamlines) – The streamlines used in the operation.

• precision (int, optional) – The number of decimals to keep when hashing the points of the streamlines. Allows a soft comparison of streamlines. If None, no rounding is performed.

Returns:

• streamlines (list of nib.streamline.Streamlines) – The streamlines obtained after performing the operation on all the input streamlines.

• indices (np.ndarray) – The indices of the streamlines that are used in the output.

scilpy.tractograms.tractogram_operations.perform_tractogram_operation_on_sft(op_name, sft_list, precision, no_metadata, fake_metadata)

Peforms an operation on a list of tractograms.

Parameters:

• op_name (str) – A callable that takes two streamlines dicts as inputs and preduces a new streamline dict.

• sft_list (list[StatefulTractogram]) – The streamlines used in the operation.

• precision (int, optional) – The number of decimals to keep when hashing the points of the streamlines. Allows a soft comparison of streamlines. If None, no rounding is performed.

• no_metadata (bool) – If true, remove all metadata.

• fake_metadata (bool) – If true, fake metadata for SFTs that do not contain the keys available in other SFTs.

Returns:

sft – The final SFT

Return type:

StatefulTractogram

scilpy.tractograms.tractogram_operations.shuffle_streamlines(sft, rng_seed=None)

scilpy.tractograms.tractogram_operations.split_sft_randomly(orig_sft, chunk_sizes, rng_seed, return_indices_only=False)

Divides a stateful tractogram into n sub-tractograms of sizes defined by chunk_sizes. Streamlines are separated randomly from the initial streamlines.

Parameters:

• orig_sft (StatefulTractogram) – Initial tractogram to subdivide

• chunk_sizes (int or list[int]) – Number of streamlines to keep (per sub-tractogram if it is a list).

• rng_seed (int) – Random seed.

• return_indices_only (bool) – If true, return a random list of indices. Else, return the Stateful Tractogram containing the chosen streamlines.

Returns:

all_chunks – The list of sub-tractograms as sfts. The number of tractograms returned is len(chunk_sizes) + 1, where the last item of the list contains streamlines that were not included in any. (Or the lists of indices if return_indices_only.)

Return type:

list[StatefulTractogram] or list[list[int]]

scilpy.tractograms.tractogram_operations.split_sft_randomly_per_cluster(orig_sft, chunk_sizes, seed, thresholds)

Divides a stateful tractogram into n sub-tractograms of sizes defined by chunk_sizes. Streamlines are separated randomly from each Quickbundle cluster created from the initial streamlines (trying to help the randomization to ensure there are streamlines from all bundles in each subset).

Parameters:

• orig_sft (StatefulTractogram) – Initial tractogram to subdivide

• chunk_sizes (list[int]) – Number of streamlines to keep per chunk. We will ensure that the number of streamlines kept per cluster is proportional to the cluster’s size. Final number will be a good approximation of nb_streamlines, but not exact.

• seed (int) – Random seed.

• thresholds (list[float]) – QBx threshold values. Suggestion: [40, 30, 20].

Returns:

all_sfts – The list of sub-tractograms as sfts. The number of tractograms returned is len(chunk_sizes) + 1, where the last item of the list contains streamlines that were not included in any.

Return type:

list[StatefulTractogram]

scilpy.tractograms.tractogram_operations.split_sft_sequentially(orig_sft, chunk_sizes)

Divides a stateful tractogram into n sub-tractograms of sizes defined by chunk_sizes. Streamlines are separated sequentially from the initial streamlines.

Parameters:

• orig_sft (StatefulTractogram) – Initial tractogram to subdivide.

• chunk_sizes (list[int]) – Number of streamlines to keep per chunk.

Returns:

all_chunks – The list of sub-tractograms as sfts. The number of tractograms returned is len(chunk_sizes).

Return type:

list[StatefulTractogram]

scilpy.tractograms.tractogram_operations.transform_warp_sft(sft, linear_transfo, target, inverse=False, reverse_op=False, deformation_data=None, remove_invalid=True, cut_invalid=False)

Transform tractogram using an affine Subsequently apply a warp from antsRegistration (optional). Remove/Cut invalid streamlines to preserve sft validity.

Parameters:

• sft (StatefulTractogram) – Stateful tractogram object containing the streamlines to transform.

• linear_transfo (numpy.ndarray) – Linear transformation matrix to apply to the tractogram.

• target (Nifti filepath, image object, header) – Final reference for the tractogram after registration.

• inverse (boolean) – Apply the inverse linear transformation.

• reverse_op (boolean) – Apply both transformation in the reverse order

• deformation_data (np.ndarray) – 4D array containing a 3D displacement vector in each voxel.

• remove_invalid (boolean) – Remove the streamlines landing out of the bounding box.

• cut_invalid (boolean) – Cut invalid streamlines rather than removing them. Keep the longest segment only.

Returns:

new_sft

Return type:

StatefulTractogram

scilpy.tractograms.tractogram_operations.union(left, right)

Union of two streamlines dict (see hash_streamlines)

scilpy.tractograms.tractogram_operations.union_robust(streamlines_list, precision=3)

Union of a list of StatefulTractogram

scilpy.tractograms.tractogram_operations.upsample_tractogram(sft, nb, point_wise_std=None, tube_radius=None, gaussian=None, error_rate=None, seed=None)

Generates new streamlines by either adding gaussian noise around streamlines’ points, or by translating copies of existing streamlines by a random amount.

Parameters:

• sft (StatefulTractogram) – The tractogram to upsample

• nb (int) – The target number of streamlines in the tractogram.

• point_wise_std (float) – The standard deviation of the gaussian to use to generate point-wise noise on the streamlines.

• tube_radius (float) – The radius of the tube used to model the streamlines.

• gaussian (float) – The sigma used for smoothing streamlines.

• error_rate (float) – The maximum distance (in mm) to the original position of any point.

• spline ((float, int)) – Pair of sigma and number of control points used to model each streamline as a spline and smooth it.

• seed (int) – Seed for RNG.

Returns:

new_sft – The upsampled tractogram.

Return type:

StatefulTractogram

scilpy.tractograms.uncompress module