scilpy.utils package

scilpy.utils.filenames module

scilpy.utils.filenames.add_filename_suffix(filename, suffix)

This function adds a suffix to the filename, keeping the extension. For example, if filename is test.nii.gz and suffix is “new”, the returned name will be test_new.nii.gz

Parameters:

• filename (str) – The full filename, including extension

• suffix (str) – The suffix to add to the filename

Return type:

The completed file name.

scilpy.utils.filenames.split_name_with_nii(filename)

Returns the clean basename and extension of a file. Means that this correctly manages the “.nii.gz” extensions.

Parameters:

filename (str) – The filename to clean

Returns:

• base, ext (tuple(str, str))

• Clean basename and the full extension

scilpy.utils.metrics_tools module

scilpy.utils.metrics_tools.compute_lesion_stats(map_data, lesion_atlas, single_label=True, voxel_sizes=[1.0, 1.0, 1.0], min_lesion_vol=7, precomputed_lesion_labels=None)

Returns information related to lesion inside of a binary mask or voxel labels map (bundle, for tractometry).

Parameters:

• map_data (np.ndarray) – Either a binary mask (uint8) or a voxel labels map (int16).

• lesion_atlas (np.ndarray (3)) – Labelled atlas of lesion. Should be int16.

• single_label (boolean) – If true, does not add an extra layer for number of labels.

• voxel_sizes (np.ndarray (3)) – If not specified, returns voxel count (instead of volume)

• min_lesion_vol (float) – Minimum lesion volume in mm3 (default: 7, cross-shape).

• precomputed_lesion_labels (np.ndarray (N)) – For connectivity analysis, when the unique lesion labels are known, provided a pre-computed list of labels save computation.

Returns:

lesion_load_dict – For each label, volume and lesion count

Return type:

dict

scilpy.utils.metrics_tools.get_bundle_metrics_mean_std(streamlines, metrics_files, distance_values, correlation_values, density_weighting=True)

Returns the mean value of each metric for the whole bundle, only considering voxels that are crossed by streamlines. The mean values are weighted by the number of streamlines crossing a voxel by default. If false, every voxel traversed by a streamline has the same weight.

Parameters:

• streamlines (list of numpy.ndarray) – Input streamlines under which to compute stats.

• metrics_files (sequence) – list of nibabel objects representing the metrics files

• density_weighting (bool) – weigh by the mean by the density of streamlines going through the voxel

Returns:

stats – list of tuples where the first element of the tuple is the mean of a metric, and the second element is the standard deviation, for each metric.

Return type:

list

scilpy.utils.metrics_tools.get_bundle_metrics_mean_std_per_point(streamlines, bundle_name, metrics, labels, distance_values=None, correlation_values=None, density_weighting=False)

Compute the mean and std PER POINT of the bundle for every given metric.

Parameters:

• streamlines (list of numpy.ndarray) – Input streamlines under which to compute stats.

• bundle_name (str) – Name of the bundle. Will be used as a key in the dictionary.

• metrics (sequence) – list of nibabel objects representing the metrics files

• labels (np.ndarray) – List of labels obtained with scil_bundle_label_map.py

• distance_values (np.ndarray) – List of distances obtained with scil_bundle_label_map.py

• correlation_values (np.ndarray) – List of correlations obtained with scil_bundle_label_map.py

• density_weighting (bool) – If true, weight statistics by the number of streamlines passing through each voxel. [False]

Returns:

stats

Return type:

dict

scilpy.utils.metrics_tools.get_bundle_metrics_profiles(sft, metrics_files)

Returns the profile of each metric along each streamline from a sft. This is used to create tract profiles.

Parameters:

• sft (StatefulTractogram) – Input bundle under which to compute profile.

• metrics_files (sequence) – list of nibabel objects representing the metrics files

Returns:

profiles_values – list of profiles for each streamline, per metric given

Return type:

list

scilpy.utils.metrics_tools.weighted_mean_std(weights, data)

Returns the weighted mean and standard deviation of the data.

Parameters:

• weights (ndarray) – a ndarray containing the weighting factor

• data (ndarray) – the ndarray containing the data for which the stats are desired

Returns:

stats – a tuple containing the mean and standard deviation of the data

Return type:

tuple

scilpy.utils.scilpy_bot module

scilpy.utils.scilpy_bot.prompt_user_for_object()

Prompts the user to select an object from the list of available objects.

scilpy.utils.scilpy_bot.update_matches_and_scores(scores, filename, score_details)

Update the matches and scores for the given filename based on the score details.

Parameters:

• scores (dict) – A dictionary containing the scores for the keywords (to be updated).

• filename (str) – The name of the script file being analyzed.

• score_details (dict) –

  A dictionary containing the scores for the keywords

  and phrases found in the script.

Returns:

Just updates the global matches and scores lists/dictionaries.

Return type:

None

scilpy.utils.spatial module

class scilpy.utils.spatial.WorldBoundingBox(minimums, maximums, voxel_size)

Bases: object

Class to store the bounding box of a volume in world space.

Parameters:

• minimums (np.ndarray) – Minimums of the bounding box.

• maximums (np.ndarray) – Maximums of the bounding box.

• voxel_size (np.ndarray) – Voxel size of the bounding box.

dump(filename, use_deprecated_pickle=False)

Save the bounding box to a json file.

Parameters:

filename (str) – Path to the json file.

classmethod load(filename, use_deprecated_pickle=False)

Load a bounding box from a json file.

Parameters:

filename (str) – Path to the json file.

Returns:

The bounding box object.

Return type:

WorldBoundingBox

scilpy.utils.spatial.compute_distance_barycenters(ref_1, ref_2, ref_2_transfo)

Compare the barycenter (center of volume) of two reference object. The provided transformation will move the reference #2 and return the distance before and after transformation.

Parameters:

• ref_1 (reference object) – Any type supported by the sft as reference (e.g .nii of .trk).

• ref_2 (reference object) – Any type supported by the sft as reference (e.g .nii of .trk).

• ref_2_transfo (np.ndarray) – Transformation that modifies the barycenter of ref_2.

Returns:

• distance_before (float) – The distance between the two barycenters before the transformation.

• distance_after (float) – The distance between the two barycenters after the transformation.

scilpy.utils.spatial.generate_rotation_matrix(angles, translation=None)

scilpy.utils.spatial.get_axis_index(axis, affine=array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]]))

Get the axis index (or position) in the image from the axis, coordinate or basis vector name.

Parameters:

• axis (str) – Either an axis name (see RAS_AXES_NAMES), a coordinate name (see RAS_AXES_COORDINATES) or a basis vector name (see RAS_AXES_BASIS_VECTORS).

• affine (np.array, optional) – An affine used to compute axis reordering from RAS.

Returns:

axis_index – Index of the axis.

Return type:

int

scilpy.utils.spatial.get_axis_name(axis_index, affine=array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]]))

Get the axis name in RAS_AXES_NAMES related to a given index.

Parameters:

• axis_index (int) – Index of the axis.

• affine (np.array, optional) – An affine used to compute axis reordering from RAS.

Returns:

axis_name – Name of the axis.

Return type:

str

scilpy.utils.spatial.get_basis_vector_name(axis_index, affine=array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]]))

Get the signed basis vector name in RAS_AXES_BASIS_VECTORS related to a given axis index.

Parameters:

• axis_index (int) – Index of the axis.

• affine (np.array, optional) – An affine used to compute axis reordering from RAS.

Returns:

basis_vector_name – Name of the basis vector suffixed with sign (see RAS_AXES_BASIS_VECTORS).

Return type:

str

scilpy.utils.spatial.get_coordinate_name(axis_index, affine=array([[1., 0., 0., 0.], [0., 1., 0., 0.], [0., 0., 1., 0.], [0., 0., 0., 1.]]))

Get the signed coordinate in RAS_AXES_COORDINATES related to a given axis index.

Parameters:

• axis_index (int) – Index of the axis.

• affine (np.array, optional) – An affine used to compute axis reordering from RAS.

Returns:

coordinate_name – Name of the coordinate suffixed with sign (see RAS_AXES_COORDINATES).

Return type:

str

scilpy.utils.spatial.voxel_to_world(coord, affine)

Takes a n dimensionnal voxel coordinate and returns its 3 first coordinates transformed to world space from a given voxel to world affine transformation.

Parameters:

• coord (np.ndarray) – N-dimensional world coordinate array.

• affine (np.array) – Image affine.

Returns:

world_coord – Array of world coordinates.

Return type:

np.ndarray

scilpy.utils.spatial.world_to_voxel(coord, affine)

Takes a n dimensionnal world coordinate and returns its 3 first coordinates transformed to voxel space from a given voxel to world affine transformation.

Parameters:

• coord (np.ndarray) – N-dimensional world coordinate array.

• affine (np.array) – Image affine.

Returns:

vox_coord – Array of voxel coordinates.

Return type:

np.ndarray