tractolearn.filtering package

Submodules

tractolearn.filtering.latent_space_distance_informer module

class tractolearn.filtering.latent_space_distance_informer.LatentSpaceDistanceInformer(encoder, ref_latent_space_samples, num_neighbors=1)

Bases: object

compute_distance_on_latent(projected_latent_space_sample)

compute_distances(streamlines, batch=128)

tractolearn.filtering.latent_space_featuring module

class tractolearn.filtering.latent_space_featuring.ROCSalientPoint(value)

Bases: Enum

An enumeration.

INV_DIAGONAL_INTERSECT = 'inv_diagonal_intersect'

MAX_ACCURACY = 'max_accuracy'

tractolearn.filtering.latent_space_featuring.compute_filtering_roc_curve(y_plaus_track_classes, y_implaus_track_classes, distances_plaus, distances_implaus, roc_data_fname)

tractolearn.filtering.latent_space_featuring.compute_maximum_accuracy_roc_threshold_index(thresholds, y_true, distances)

tractolearn.filtering.latent_space_featuring.compute_optimal_roc_difference_index(tpr, fpr)

tractolearn.filtering.latent_space_featuring.compute_optimal_roc_intersection_index(tpr, fpr)

tractolearn.filtering.latent_space_featuring.filter_streamlines_only(streamline_classes, latent_streamline_data, latent_atlas_all, y_latent_atlas_all, model, thresholds, reference, output_path, trk_ids, trk, num_neighbors=1, id_bundle=None)

tractolearn.filtering.latent_space_featuring.find_tractogram_filtering_threshold_v2(y_latent_atlas_brain_plaus, current_class, latent_space_dims, bundles_classes_dict, fname_root, dataset_name, y_thres_plaus, y_thres_implaus, distances_plaus, distances_implaus, nearest_indices_plaus, nearest_indices_implaus, roc_optimal_point=ROCSalientPoint.INV_DIAGONAL_INTERSECT)

tractolearn.filtering.latent_space_featuring.get_dataset_long_name_from_dataset_name(dataset_name)

tractolearn.filtering.latent_space_featuring.plot_filtering_threshold_features(roc_dict, plaus_streamlines_latent_distances, implaus_streamlines_latent_distances, y_plaus_track_classes, y_implaus_track_classes, latent_space_dims, bundles_classes_dict, fname_root, dataset_name, roc_optimal_point=ROCSalientPoint.INV_DIAGONAL_INTERSECT)

tractolearn.filtering.latent_space_featuring.plot_horizontal_lines(ys, ax=None, **plot_kwargs)

Draw horizontal lines on plot.

Parameters:

• ys (A scalar, list, or 1D array) – Vertical offsets.

• ax (the axis) – The axis. None to use gca.

• plot_kwargs – Keyword arguments to be passed to plot.

Return type:

The plot object corresponding to the lines.

tractolearn.filtering.latent_space_featuring.plot_latent_space(latent_samples, classes, latent_space_dims, fname_root, rbx_classes=True)

tractolearn.filtering.latent_space_featuring.plot_latent_space_distance_features(distances_plaus, distances_implaus, track_classes, class_names, latent_space_dims, fname_root, dataset_name, bundles_classes_dict, threshold=None, **rc_parameters)

tractolearn.filtering.latent_space_featuring.plot_latent_space_histogram(distances, classes, class_names, latent_space_dims, fname_root, dataset_name, bundles_classes_dict, threshold=None, **rc_parameters)

tractolearn.filtering.latent_space_featuring.plot_latent_space_stats(distances, classes, class_names, latent_space_dims, fname_root, dataset_name, bundles_classes_dict, threshold=None, **rc_parameters)

tractolearn.filtering.latent_space_featuring.plot_roc(fpr, tpr, thresholds, auc, filename, dataset_name, optimal_diff_idx=None, optimal_intersect_idx=None, optimal_max_acc_idx=None, **rc_parameters)

tractolearn.filtering.latent_space_featuring.plot_vertical_lines(xs, ax=None, **plot_kwargs)

Draw vertical lines on plot.

Parameters:

• xs (A scalar, list, or 1D array) – Horizontal offsets.

• ax (the axis) – The axis. None to use gca.

• plot_kwargs – Keyword arguments to be passed to plot.

Return type:

The plot object corresponding to the lines.

tractolearn.filtering.latent_space_featuring.roc_curve_computation(y_plaus_track_classes, y_implaus_track_classes, plaus_streamlines_latent_distances, implaus_streamlines_latent_distances, fname_root, filtering_time_probe, dataset_name)

tractolearn.filtering.streamline_space_filtering module

class tractolearn.filtering.streamline_space_filtering.StreamlineFeatures(value)

Bases: Enum

An enumeration.

CORTICAL_GAP = 'cortical_gap'

FA = 'fa'

GM_OCCUPANCY = 'gm_occupancy'

LENGTH = 'length'

LOCAL_ORIENTATION_ANGLE = 'local_orientation_angle'

MEAN_CURVATURE = 'mean_curvature'

REGION = 'region'

SURFACE_INCIDENCE_ANGLE = 'surface_incidence_angle'

SURFACE_INTERSECTION = 'surface_intersection'

SURFACE_PROJECTED_ANGLE = 'surface_projected_angle'

WINDING = 'winding'

WM_MEMBERSHIP = 'wm_membership'

WM_OCCUPANCY = 'wm_occupancy'

WM_VOXEL_OCCUPANCY_RATIO = 'wm_voxel_occupancy_ratio'

class tractolearn.filtering.streamline_space_filtering.StreamlineLocalOrientationAnalyzer

Bases: TractographyFeatureAnalyzer

analyze(sft, peaks, affine)

static compute_alignment(sft, peaks, affine)

class tractolearn.filtering.streamline_space_filtering.StreamlineLocalOrientationChecker(local_orient_analyzer: StreamlineLocalOrientationAnalyzer, allowed_angle=20.0, mask_value=90.0, allowed_ratio=0.1)

Bases: TractographyChecker

Check streamline alignment with the fODFs along its trajectory.

verify_conditions(sft, peaks, affine)

class tractolearn.filtering.streamline_space_filtering.TractographyChecker

Bases: object

get_compliant_indices()

class tractolearn.filtering.streamline_space_filtering.TractographyFeatureAnalyzer

Bases: object

tractolearn.filtering.streamline_space_filtering.compute_local_orientation_alignment2(sft, peak_dirs)

Compute streamline local orientation to peak direction angle by computing the streamline local (i.e. segment-wise) orientation, iterating over each peak index to get the (interpolated) peak value at each segment, computing the angle between the interpolated peak and the streamline segment, and choosing the peak that is closest to the streamline segment orientation (i.e. having the lowest angle value). :param sft: Tractogram. :type sft: StatefulTractogram :param peak_dirs: Peak directions. Q must be a multiple of 3. :type peak_dirs: ndarray (X, Y, Z, Q)

Returns:

• Streamline_local_orientations (list) – Streamline local orientations.

• closest_peak_dirs (list) – Closest peak directions.

• closest_angles (list) – Closest angles.

tractolearn.filtering.streamline_space_filtering.compute_streamline_local_orientation(streamlines)

Compute local orientation of streamlines. A streamline’s local orientation is computed by subtracting the coordinate data at consecutive locations and normalizing the result. Thus, for each streamline we will have a list of vectors whose length will be len(streamline)-1. :param streamlines: Streamlines :type streamlines: ArraySequence

Returns:

streamline_local_orientations – Streamline local orientations.

Return type:

list

tractolearn.filtering.streamline_space_filtering.compute_streamline_to_peaks_angles(streamline_local_orientations, interpolated_peak_dirs, attribute_straight_angles_to_null_peaks=True)

Compute streamline local orientation to peak direction angles. Does not take into account the sign. :param streamline_local_orientations: Streamline local orientations. Contains as many items as streamlines,

each item containing an ndarray of shape (N, 3). Usually N is the length of the streamline-1.

Parameters:

• interpolated_peak_dirs (list) – Interpolated peak directions. Contains as many items as streamlines, each item containing a list of P items, P being the peak count, and these items being an ndarray of shape (N, 3).

• attribute_straight_angles_to_null_peaks (bool, optional) – Whether straight angles (90°) are attributed to peak directions being null.

Returns:

angles – Streamline to peak direction angles.

Return type:

list

tractolearn.filtering.streamline_space_filtering.cut_streamlines_outside_mask(sft, mask, streamlines)

Cut streamlines so their longest segment are within the bounding box. This function keeps the data_per_point and data_per_streamline.

Parameters:

• sft (StatefulTractogram) – The sft to remove invalid points from.

• mask (np.array) – Mask used to cut streamlines

Returns:

new_sft – Trimmed sft

Return type:

StatefulTractogram

tractolearn.filtering.streamline_space_filtering.filter_grid_roi(sft, mask, filter_type, is_exclude, soft_percentage: float | None = None)

Parameters:

• sft (StatefulTractogram) – StatefulTractogram containing the streamlines to segment.

• target_mask (numpy.ndarray) – Binary mask in which the streamlines should pass.

• filter_type (str) – One of the 3 following choices, ‘any’, ‘all’, ‘either_end’, ‘both_ends’.

• is_exclude (bool) – Value to indicate if the ROI is an AND (false) or a NOT (true).

Returns:

ids – Filtered sft. Ids of the streamlines passing through the mask.

Return type:

tuple

tractolearn.filtering.streamline_space_filtering.get_closest_peaks_from_angles(angles, peak_dirs)

Get the closest peaks by identifying the minimum angle values. Typically used to identify the minimum values in streamline (local orientation) to peak alignment angle values, and the peaks corresponding to such values. :param angles: Angle values. Contains as many items as streamlines, each item

containing an ndarray of shape (P, N), P being the number of peaks and N the number of streamline segments. Usually N is the length of the streamline-1.

Parameters:

peak_dirs (list) – Peak directions values. Contains as many items as streamlines, each item containing a list with as many items as peaks (P). Each of these lists contains an array of shape (N, 3), N being the number of streamline segments. Usually N is the length of the streamline-1.

Returns:

• closest_angles (list) – Closest angle values. Contains as many items as streamlines, each item containing an ndarray of shape (N,), N being the number of streamline segments.

• closest_peak_dirs (list) – Peak directions corresponding to the closest angle values. Contains as many items as streamlines, each item containing an ndarray of shape (N, 3), N being the number of streamline segments.

tractolearn.filtering.streamline_space_filtering.interpolate_peak_dirs_at_streamline_locations(streamlines, peak_dirs)

Interpolate peaks at streamline locations. Will return a list of peaks with as many elements as streamlines, each element being an array of length size len(streamline)-1 and each atom in the array having as many peaks as in peak_dirs. :param streamlines: Streamlines :type streamlines: ArraySequence :param peak_dirs: Peak directions. Q must be a multiple of 3. :type peak_dirs: ndarray (X, Y, Z, Q)

Returns:

interpolated_peak_dirs – Interpolated peak directions.

Return type:

list

tractolearn.filtering.streamline_space_filtering.is_feature_plausible(feature_value, thresholds)

Checks whether the values of the features are within the range of values to determine whether a streamline is plausible. :param feature_value: Streamline-wise values of the given feature. :type feature_value: scalar or array-like :param thresholds: Minimum (‘min’) and maximum (‘max’) or 3rd_quartile tolerated value

for the feature. For the first case, any value below the minimum or above the maximum will lead to the streamline being considered implausible; alternatively, the 3rd_quartile criterion might be used to check the streamline plausibility based on local feature values (e.g. local orientation alignment, streamline to surface distance or strealine to surface normal alignment): a streamline is considered implausible if the 3rd quartile of provided feature values are above the given threshold. A scalar mask_value can be provided to avoid outlier values from introducing a bias in the 3rd quartile computation (i.e. a mask is built to include only values strictly smaller than the provided mask value). For global features, if no thresholds are specified, a boolean true value is considered to imply a likely plausible streamline (i.e. the streamline is within the WM), a false value implying a possibly implausible one. For the

Returns:

is_plausible – True if the value of the feature is within the range of values implying that the streamline is likely plausible.

Return type:

list

Module contents

class tractolearn.filtering.LatentSpaceKeys(value)

Bases: Enum

An enumeration.

balanced_accuracy_label = 'balanced_accuracy'

colorbar_fname_label = 'colorbar'

confusion_matrix_fname_root = 'confusion_matrix'

filtering_stats_file_basename = 'filtering_stats.json'

implaus_streamlines_tractogram_latent_distances_cbar_file_basename = 'implausible_streamlines_tractogram_latent_space_distances_colorbar.png'

implausible_streamlines_latent_distances_file_basename = 'implausible_streamlines_latent_distances.pickle'

latent_space_fname_label = 'latent_space'

latent_space_histogram_cont_fname_label = 'histogram_cont'

latent_space_histogram_fname_label = 'histogram'

latent_space_roc_fname_label = 'roc'

latent_space_stats_fname_label = 'stats'

latent_space_stats_raincloud_fname_label = 'stats_raincloud'

nearest_neighbor_fname_label = 'nearest_neighbor'

plaus_streamlines_tractogram_latent_distances_cbar_file_basename = 'plausible_streamlines_tractogram_latent_space_distances_colorbar.png'

plausible_streamlines_latent_distances_file_basename = 'plausible_streamlines_latent_distances.pickle'

roc_data_file_basename = 'roc_data.pickle'

test_data_fn_tractogram_fname_root = 'test_data_fn'

test_data_fp_tractogram_fname_root = 'test_data_fp'

test_data_reconst_implaus_tractogram_fname_root = 'test_data_reconst_implausibles'

test_data_reconst_plaus_tractogram_fname_root = 'test_data_reconst_plausibles'

test_data_tn_tractogram_fname_root = 'test_data_tn'

test_data_tp_tractogram_fname_root = 'test_data_tp'

threshold_fname_label = 'thr'

tractogram_fname_label = 'tractogram'