API

Welcome to the API. The main packages and modules are available in the ‘Quick access’ below.

All functions are defined in details further down the page.

Quick access

unravel

This package contains an implementation of UNRAVEL, an algorithm used to combine macroscopic tractography information with microscopic multi-fixel model estimates in order to improve the accuracy in the estimation of the microstructural properties of neural fibers in a specified tract.

unravel

analysis

Created on Fri Aug 18 18:23:26 2023

@author: DELINTE Nicolas

unravel.analysis.connectivity_matrix(streamlines, label_volume, inclusive: bool = True, weights=None)

Returns the symetric connectivity matrix of the streamlines. Usage of trk.to_vox(), trk.to_corner() beforehand is highly recommended. This fonction is at least x6 times faster than the implementation in Dipy when inclusive is set to True.

Parameters:

streamlinesstreamline object

DESCRIPTION.

label_volume3D array of size (x,y,z)

Array containing the labels as int.

inclusive: bool, optional

Whether to analyze the entire streamline, as opposed to just the endpoints.

weights: 1D array of size (n), optional

Array containing the weights for the n streamlines in the tract. For example the weights computed with SIFT2. Default: the weight of each streamline is set to 1.

Returns:

matrix2D array

Connectivity matrix.

unravel.analysis.get_metric_along_trajectory(fixel_weights, metric_maps, roi_sections, weighting: str = 'tsl')

Parameters:

fixel_weights4-D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

metric_maps4D array of shape (x,y,z,k)

List of K 4D arrays of shape (x,y,z) containing metric estimations.

roi_sections3D array of size (x,y,z)

Labeled array containing the volumes of the section of the tract.

weightingstr, optional

Weighting used for the mean. The default is ‘tsl’.

Returns:

m_array1D array of size (n)

DESCRIPTION.

std_array1D array of size (n)

DESCRIPTION.

core

Created on Fri Mar 11 11:05:25 2022

@author: DELINTE Nicolas

unravel.core.angle_difference(vs, vf, direction: bool = False)

Computes the angle difference between n vectors.

Parameters:

vs2D array of size (n,3)

Segment vector

vf3D array of size (n,3,k)

List of the k vectors corresponding to each fiber population

directionbool, optional

If False, the vectors are considered to be direction-agnostic : maximum angle difference = 90. If True, the direction of the vectors is taken into account : maximum angle difference = 180. The default is False.

Returns:

ang2D array of size (n,k)

Angle difference (in degrees).

unravel.core.angular_agreement(phi_maps, volume_shape)

Parameters:

phi_mapsdict

Dictionnary containing the lists of the relative contribution and angle difference of the most aligned fixel in each voxel.

Returns:

phifloat

Angular agreement index.

phi_map3D array of shape (x,y,z)

Voxel-wise angular agreement index.

unravel.core.angular_weighting(vs, vf, nf=None)

Computes the relative contributions of the segments in vf to vs using angular weighting.

Parameters:

vs2D array of size (n,3)

Segment vector

vf3D array of size (n,3,k)

List of the k vectors corresponding to each fiber population

nfarray of size (n,k)

List of the null k vectors

Returns:

ang_coef2D array of size (n,k)

List of the k coefficients

unravel.core.closest_fixel_only(vs, vf, nf=None)

Computes the relative contributions of the segments in vf to vs using the closest-fixel-only approach.

Parameters:

vs2D array of size (n,3)

Segment vector

vf3D array of size (n,3,k)

List of the k vectors corresponding to each fiber population

nfarray of size (n,k)

List of the null k vectors

Returns:

ang_coef2D array of size (n,k)

List of the k coefficients

unravel.core.compute_subsegments(start, finish, vox_size=[1, 1, 1], offset=[0, 0, 0], return_nodes: bool = False)

Computes the voxels containing a segment (defined by the start and finish) and the segment length that is contained within them.

Parameters:

start1-D array of shape (d,)

Starting point of segment.

finish1-D array of shape (d,)

End point of segment.

vox_size1-D array of shape (d,)

vox_size[i] is the (strictly positive) voxel size along the i-th axis, with i=1,…,d.

offset1-D array of shape (d,)

offset[i] is the start of the first voxel along the i-th axis, with i=1,…,d. In 3 dimensions (d=3), voxel (0, 0, 0) would be defined as [off_x, off_x + s_x[ x [off_y, off_y + s_y[ x [off_z, off_z + s_z[, where off_x = offset[0], s_x = vox_size[0], off_y = offset[1], etc.

return_nodesboolean, optional

If True, the nodes making the sub-segment(s) are returned. The default is False.

Returns:

tuple

subseg_lengths: list of N-1 scalar(s) of type float, with N>=2.

visited_voxels: list of N-1 1-D array(s) of shape (d,) and type int,

with N>=2.

nodes: only if return_nodes=True. List of N arrays of shape (d,) and

type float, with N>=2.

unravel.core.deltas_to_D(dx: float, dy: float, dz: float, lamb=array([[1, 0, 0], [0, 0, 0], [0, 0, 0]]), vec_len: float = 500)

Function creating a diffusion tensor from three orthogonal components.

Parameters:

dxfloat

‘x’ component.

dyfloat

‘y’ component.

dzfloat

‘z’ component.

lamb2D array of size (3,3), optional

Diagonal matrix containing the diffusion eigenvalues. The default is np.diag([1, 0, 0]).

vec_lenfloat, optional

Value decreasing the diffusion. The default is 500.

Returns:

D2D array of size (3,3)

Matrix containing the diffusion tensor.

Raises:

np.linalg.LinAlgError

DESCRIPTION.

unravel.core.fraction_weighting(point, ff, nf=None)

Computes the relative contribution of each fixel k based on its fraction ff in voxel (point).

Parameters:

point2D array of size (n,3)

x, y, z coordinates.

nf2D array of size (n,k)

List of the null k vectors.

ff4D array of size (x,y,z,k)

Array containing the volume fractions of the k fixels.

Returns:

ang_coef2D array of size (n,k)

List of the k coefficients

unravel.core.get_fixel_weight(trk, peaks, method: str = 'ang', ff=None, return_phi: bool = False, subsegment: int = 10)

Get the fixel weights from a tract specified in trk_file. TODO : re-implement return_phi

Parameters:

trktractogram

Content of a .trk file

peaks4D array of shape (x,y,z,3,k)

List of 4D arrays of shape (x,y,z,3) containing peak information.

methodstr, optional

Method used for the relative contribution, either;

‘ang’ : angular weighting ‘raw’ : relative angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is ‘ang’.

ff4D array of size (x,y,z,k)

Array containing the volume fractions of the k fixels. The default is None.

subsegmentint

Number of subsegments per segment (tractography step), increases precision at the cost of an increased computation time and RAM usage. The default is 10.

return_phibool, optional

If True, returns the phi_maps used for the angular agreement. Currently slows down the code. The default is False.

Returns:

fixel_weight4D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

phi_mapsdict

Dictionnary containing the lists of the relative contribution and angle difference of the most aligned fixel in each voxel.

unravel.core.get_fixel_weight_DIAMOND(trk_file: str, DIAMOND_dir: str, Patient: str, K: int = 2, method: str = 'ang')

Get the fixel weights from a tract specified in trk_file and the tensors obtained from DIAMOND. OUTDATED. TODO: adapt to new architecture.

Parameters:

trk_filestr

Path to tractography file (.trk)

DIAMOND_dirstr

Path to folder containing MF peak files.

Patientstr

Patient name in DIAMOND_dir folder

Kint, optional

Maximum number of fixel in a voxel. The default is 2.

methodstr, optional

Method used for the relative contribution, either;

‘ang’ : angular weighting ‘raw’ : relative angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is ‘ang’.

Returns:

fixel_weights4D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

phi_mapsdict

Dictionnary containing the lists of the relative contribution and angle difference of the most aligned fixel in each voxel.

unravel.core.get_fixel_weight_MF(trk_file: str, MF_dir: str, Patient: str, K: int = 2, method: str = 'ang')

Get the fixel weights from a tract specified in trk_file and the peaks obtained from Microsrcuture Fingerprinting. OUTDATED. TODO: adapt to new architecture.

Parameters:

trk_filestr

Path to tractography file (.trk)

MF_dirstr

Path to folder containing MF peak files.

Patientstr

Patient name in MF_dir folder

Kint, optional

Maximum number of fixel in a voxel. The default is 2.

methodstr, optional

Method used for the relative contribution, either;

‘ang’ : angular weighting ‘raw’ : relative angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is ‘ang’.

Returns:

fixel_weights4D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

phi_mapsdict

Dictionnary containing the lists of the relative contribution and angle difference of the most aligned fixel in each voxel.

unravel.core.get_microstructure_map(fixel_weights, metric_maps)

Returns a 3D volume representing the microstructure map

Parameters:

fixel_weights4D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

metric_maps4D array of shape (x,y,z,K)

List of K 3D arrays of shape (x,y,z) containing metric estimations.

Returns:

micro_map3D array of shape (x,y,z)

Array containing the microstructure map

unravel.core.get_streamline_weights(trk, peaks, method_list: list = ['vol', 'cfo', 'ang', 'raw'], streamline_number: int = 0, ff=None, subsegment: int = 1)

Parameters:

trktractogram

Content of a .trk file

peaks4D array of shape (x,y,z,3,k)

List of 4D arrays of shape (x,y,z,3) containing peak information.

method_listlist, optional

List of methods used for the relative contribution, either;

‘ang’ : angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is [‘vol’, ‘cfo’, ‘ang’].

streamline_numberint, optional

Number of the streamline to analyse. The default is 0.

fListlist, optional

List of 3D arrays (x,y,z) containing the fraction of each fiber population. Only used with ‘vol’ method. The default is [].

Returns:

segmentStream :list, optional

List of the relative contribution of each voxel for the streamline specified.

unravel.core.get_weighted_mean(micro_map, fixel_weights, weighting: str = 'tsl')

Returns the mean value of a microstructure map using either a voxel or total segment length (tsl) weighing method. Totals segment length attributes more weight to voxels containing mulitple streamline segments.

Parameters:

micro_map3D array of shape (x,y,z)

Array containing the microstructure map

fixel_weights4D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

weightingstr, optional

Weighting used for the mean. The default is ‘tsl’.

Returns:

meanfloat

Weighted mean.

devfloat

Weighted sum.

unravel.core.get_weighted_sums(metric_maps: list, fixelWeightList: list)

TODO: unify with get_microstructure_map and total_segment_length Outdated.

Parameters:

metric_mapslist

List of K 3D arrays of shape (x,y,z) containing metric estimations.

fixelWeightListlist

List containing the relative weights of the K fixels in each voxel.

Returns:

weightedMetricSum3D array of shape (x,y,z)

Microstructure map.

fixel_weightsum3D array of shape (x,y,z)

Total length map.

Mint

Number of non-zero pixels in both metric maps.

unravel.core.main_fixel_map(fixel_weights)

Ouputs a map representing the most aligned fixel.

Parameters:

fixel_weights4D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

Returns:

mainFixelMap3D array of shape (x,y,z).

The array contains int values representing the most aligned fixel.

unravel.core.peak_to_tensor(peaks, norm=None, pixdim=[2, 2, 2])

Takes peaks, such as the ones obtained with Microstructure Fingerprinting, and return the corresponding tensor, in the format used in DIAMOND.

Parameters:

peaks4D array of size (x,y,z,3)

Array containing the peaks of shape (x,y,z,3)

norm3D array of size (x,y,z)

Array containing the normalization factor of shape (x,y,z), usually between [0,1].

Returns:

t5D array of size (x,y,z,1,6)

Tensor array of shape (x,y,z,1,6).

unravel.core.plot_streamline_metrics(trk, peaks, metric_maps, method_list: list = ['vol', 'cfo', 'ang', 'raw'], streamline_number: int = 0, ff=None, segment_wise: bool = True, groundTruth_map=None, barplot: bool = True)

Plots the evolution of a metric along the course of a single streamline. TODO: re-implement barplot

Parameters:

trktractogram

Content of a .trk file

peaks4D array of shape (x,y,z,3,k)

List of 4D arrays of shape (x,y,z,3) containing peak information.

metric_maps4D array of shape (x,y,z,3,k)

List of K 4D arrays of shape (x,y,z) containing metric estimations.

method_listlist, optional

List of methods used for the relative contribution, either;

‘ang’ : angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is [‘vol’, ‘cfo’, ‘ang’].

streamline_numberint, optional

Number of the streamline to analyse. The default is 0.

fListlist, optional

List of 3D arrays (x,y,z) containing the fraction of each fiber population. Only used with ‘vol’ method. The default is [].

segment_wisebool, optional

If True then plots for each segment, else plots for each voxel. The default is True.

groundTruth_maparray, optional

3D array of shape (x,y,z) containing the ground truth map.

barplotbool, optional

If False, does not plot the barplots of the relative contributions. The default is True.

Returns:

None.

unravel.core.plot_streamline_metrics_old(streamList: list, metric_maps: list, groundTruth_map=None, barplot: bool = True, method_list: list = ['ang'], fList: list = [])

Plots the evolution of a metric along the course of a single streamline. OUTDATED

Parameters:

streamListlist

List of segment- or voxel-wise relative contributions.

metric_mapslist

List of K 3D arrays of shape (x,y,z) containing metric estimations.

groundTruth_maparray, optional

3D array of shape (x,y,z)containing the ground truth map.

barplotbool, optional

If False, does not plot the barplots of the relative contributions. The default is True.

method_listlist

List of method used for the relative contribution, either;

‘ang’ : angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is ‘ang’.

fListlist, optional

List of 3D arrays (x,y,z) containing the fraction of each fiber population. Only used with ‘vol’ method. The default is [].

Returns:

None.

unravel.core.relative_angular_weighting(vs, vf, nf=None)

Computes the relative contributions of the segments in vList to vs using relative angular weighting, which attributes less weight to fixel perpendicular to the streamline segment.

Parameters:

vs2D array of size (n,3)

Segment vector

vf3D array of size (n,3,k)

List of the k vectors corresponding to each fiber population

nfarray of size (n,k)

List of the null k vectors

Returns:

ang_coef2D array of size (n,k)

List of the k coefficients

unravel.core.t6ToMFpeak(t)

(6,17,1,15) with info on 0,2,5 to (17,1,15,3)

unravel.core.tensor_to_peak(t)

Takes peaks, such as the ones obtained with DIAMOND, and returns the corresponding tensor, in the format used in Microstructure Fingerprinting. TODO : Speed up.

Parameters:

t5D array

Tensor array of shape (x,y,z,1,6).

Returns:

peaks4D array

Array containing the peaks of shape (x,y,z,3)

unravel.core.total_segment_length(fixel_weights)

Parameters:

fixel_weights4D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

Returns:

sc3D array of shape (x,y,z)

Array contains the total segment length in each voxel.

unravel.core.tract_to_streamlines(trk) → list

Return a list with the position of each step of each streamline from a tractogram.

Parameters:

trktractogram

Content of a .trk file

Returns:

sListlist

List of the streamlines contained in the tractogram.

unravel.core.volumetric_agreement(fixel_weights)

Parameters:

fixel_weights4D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

Returns:

indexfloat

Volumetric agreement index.

index_map3D array of shape (x,y,z)

Voxel-wise volumetric agreement index.

unravel.core.voxel_distance(position1: tuple, position2: tuple)

Returns the distance between two voxels in multiple dimensions.

Parameters:

position1tuple

First position. Ex: (1,1,1).

position2tuple

Second position. Ex: (1,2,3).

Returns:

distuple

tuple containing the distance between the two positions in every direction. Ex: (0,1,2).

unravel.core.voxels_from_segment(position1: tuple, position2: tuple, subparts: int = 10) → tuple

Computes the voxels containing a segment (defined by the position 1 and 2) and the segment length that is contained within them.

Parameters:

position1tuple

Position. Ex: (1,1,1).

position2tuple

Position. Ex: (1,2,3).

subpartsint, optional

Divide segment into multiple subsegment. Higher value is more precise but increases computation time. The default is 10.

Returns:

voxListdict

Dictionary of the voxels containing a part of the segment.

unravel.core.weighted_mean_dev(metric_maps: list, fixelWeightList: list, retainAllValues: bool = False, weighting: str = 'tsl')

Return the weighted means and standard deviation from list of metric maps and corresponding fixel weights. Outdated.

Parameters:

metric_mapslist

List of K 3D arrays of shape (x,y,z) containing metric estimations.

fixelWeightListlist

List containing the relative weights of the K fixels in each voxel.

retainAllValuesbool, optional

DESCRIPTION. The default is False.

Returns:

weightedMeanfloat

Weighted mean.

weightedDevfloat

Weighted sum.

weightSumfloat

Total segment length.

minMaxListlist

[Min, Max]

weightedListlist

stream

Created on Wed Aug 16 11:25:30 2023

@author: DELINTE Nicolas

unravel.stream.align_streamline(stream)

Sets the start and end point of a streamline with arbitrary rules.

Parameters:

stream2D array of shape (l, 3)

Coordinates of the l streamline points.

Returns:

stream2D array of shape (l, 3)

Coordinates of the l streamline points.

unravel.stream.extract_nodes(trk_file: str, nodes: int = 32, smooth_iter: int = 10)

Return the streamline with the most density, subsampled into a defined number of nodes.

Parameters:

trk_filestr

Path to tractogram file

nodesint, optional

Number of points in the average pathway. The default is 32.

smooth_iterint, optional

Number of iterations for smoothing the average pathway. Not recommended when there are few nodes. The default is 10.

Returns:

centroid2D array of size (n, 3)

Coordinates (x,y,z) of the n mean trajectory points.

unravel.stream.extract_nodes_legacy(trk_file: str, level: int = 3, smooth: bool = True)

The start is assumed to be the lowest position along the last axis. OUTDATED: use extract_nodes() instead

Parameters:

trk_filestr

Path to tractogram file

levelint, optional

Number of steps in the mean streamline trajectory. The number of steps is equal to (2**level)+1. The default is 3.

Returns:

point_array2D array of size (n, 3)

Coordinates (x,y,z) of the n mean trajectory points.

unravel.stream.get_dist_from_median_trajectory(trk_file: str, point_array, compute_dist: bool = True)

Parameters:

trk_filestr

Path to tractogram file.

point_array2D array of size (n, 3)

Coordinates (x,y,z) of the n mean trajectory points.

compute_distbool, optional

Set to false to only compute median, speeds up the code. The default is True.

Returns:

distTYPE

DESCRIPTION.

median_arrayTYPE

DESCRIPTION.

unravel.stream.get_roi_sections_from_nodes(trk_file: str, point_array)

Create a mask containing the subdivisions of a tract along its mean trajectory.

Parameters:

trk_filestr

Path to tractogram file.

point_array2D array of size (n, 3)

Coordinates (x,y,z) of the n mean trajectory points.

Returns:

mask: 3D array of size (x,y,z)

Labeled array containing the volumes of the section of the tract.

unravel.stream.get_streamline_number_from_index(streams, index: int) → int

Parameters:

streamsstreamlines.array_sequence.ArraySequence

DESCRIPTION.

indexint or array (n,1)

Number of the tractography point (x,y,z).

Returns:

nbint or array(n,)

Streamline number.

unravel.stream.remove_outlier_streamlines(trk_file, point_array, out_file: str = None, outlier_ratio: float = 0, remove_outlier_dir: bool = False, verbose: bool = True, bandwidth: float = 0.2, neighbors_required: int = 5, bandwidth_dir: float = 1, neighbors_required_dir: int = 10, keep_ratio: float = 0.5)

Removes streamlines that are outliers for more than half (default) of the bundle trajectory based on the distance to the mean trajectory. Can also remove streamlines if their main direction is an outlier with the remove_outlier_dir parameter.

Parameters:

trk_filestr

Path to tractogram file.

point_array2D array of size (n, 3)

Coordinates (x,y,z) of the n mean trajectory points.

out_filestr, optional

Path to output file. The default is None.

outlier_ratioint, optional

Percentage of the streamline allowed to be an outlier [0:1]. Increasing the value removes less streamlines. The default is 0 (0%).

remove_outlier_dirbool, optional

If True, removes streamlines whose direction are outliers. The default is False.

verbosebool, optional

If True, prints number of streamlines removed. The default is False.

bandwidthfloat, optional.

Bandwidth for the KDE, recommended values : [0.1-5]. The default is 0.2.

neighbors_requiredint, optional

Approximative number of neighboring points required to not be removed. The default is 5.

bandwidth_dirfloat, optional.

Bandwidth for the KDE, recommended values : [0.1-5]. The default is 1.

neighbors_required_dirint, optional

Approximative number of neighboring points required to not be removed. The default is 10.

keep_ratiofloat, optional

Maximum percentage of streamlines that can be removed. The default is 0.5.

Returns:

None.

unravel.stream.remove_streamlines(streams, idx: int)

TODO: speed up with something along the lines of ‘streams=streams[idx]’

Parameters:

streamsstreamlines.array_sequence.ArraySequence

DESCRIPTION.

idxint

Streamline number.

Yields:

slstreamline generator

DESCRIPTION.

unravel.stream.smooth_streamlines(trk_file: str, out_file: str = None, iterations: int = 1)

Slightly smooth streamlines. The step size will no longer be uniform after smoothing.

Parameters:

trk_filestr

Path to tractogram file.

out_filestr, optional

Path to output file. The default is None.

iterint, optional

Number of times to apply to apply the smoothing. Increases smoothness and compution time. The default is 1.

Returns:

None.

utils

Created on Sat Jun 4 22:17:13 2022

@author: DELINTE Nicolas

unravel.utils.fuse_trk(trk_file_1: str, trk_file_2: str, output_file: str)

Creates a new .trk file with all streamlines contained in the two input .trk files. The second argument can be a list of linames. The input files must be in the same space.

Parameters:

trk_file_1str

Filename of first input .trk file.

trk_file_2str or list

Filename of second input .trk file. Or list of filenames.

output_filestr

Filename of output .trk file.

Returns:

None.

unravel.utils.get_streamline_angle(trk, resolution_increase: int = 1)

Get the fixel weights from a tract specified in trk_file.

Parameters:

trktractogram

Content of a .trk file

resolution_increaseint, optional

Factor multiplying the resolution/dimensions of output array. The default is 1.

Returns:

density3-D array of shape (x,y,z)

Array containing the mean angle of streamline segments in each voxel.

unravel.utils.get_streamline_count(trk) → int

Returns the number of streamlines in a tractogram.

Parameters:

trktractogram

Content of a .trk file

Returns:

countint

Number of streamlines in tractogram.

unravel.utils.get_streamline_density(trk, resolution_increase: int = 1, color: bool = False, subsegment: int = 10, norm_all_voxels: bool = True, weights=None)

Get the total segment length from a tract specified in trk.

Parameters:

trktractogram

Content of a .trk file

resolution_increaseint, optional

Factor multiplying the resolution/dimensions of output array. The default is 1.

colorbool, optional

If True, output a RGB volume with colors corresponding to the directions of the streamlines, modulated by streamline density. The default is False.

subsegmentint, optional

Divides the streamline segment into n subsegments. Increases spatial resolution of streamline segments and computation time. The default is 10.

norm_all_voxelsbool, optional

If True, sets all color voxel with a maximum intensity. Else, the intensity is weighted by the number of fibers. The default is True.

weights1D array of size (n), optional

Array containing the weights for the n streamlines in the tract. For example the weights computed with SIFT2. Default: the weight of each streamline is set to 1.

Returns:

density3-D array of shape (x,y,z)

Array containing the streamline density in each voxel.

unravel.utils.get_streamline_lengths(trk)

Returns an array with the lengths of the n streamlines in a tractogram.

Parameters:

trktractogram

Content of a .trk file

Returns:

length1D array of size (n)

Lengths of the n streamlines in a tractogram.

unravel.utils.load_sift2_weights(weights_file: str, mu_file: str = None)

unravel.utils.normalize_color(rgb, norm_all_voxels: bool = False)

Sets values in RGB array (x,y,z,3) to be within [0,1].

Parameters:

rgb3-D array of shape (x,y,z,3)

RGB volume.

norm_all_voxelsbool, optional

If True, all voxel display maximum intensity. The default is False.

Returns:

norm3-D array of shape (x,y,z,3)

RGB volume.

unravel.utils.peaks_to_RGB(peaks, frac=None, fvf=None, order: str = 'rgb', norm_color: bool = False)

Returns a RGB map of shape (x,y,z,3) representing the main direction of of the peaks. Optionaly scaled by fraction and/or fiber volume fraction.

Parameters:

peaks5D array of shape (x,y,z,3,k)

List of arrays containing the peaks of shape (x,y,z,3)

frac4D array of shape (x,y,z,k), optional

List of arrays of shape (x,y,z) containing the fraction of each fixel. The default is None.

fvf4D array of shape (x,y,z,k), optional

List of arrays of shape (x,y,z) containing the fiber volume fraction of each fixel. The default is None.

orderstr, optional

Order of colors, either ‘rgb’, ‘gbr’ or ‘brg’. The default is ‘rgb’.

Returns:

rgb4-D array of shape (x,y,z,3)

RGB map of shape (x,y,z,3) representing the main direction of of the peaks. With type float64 [0,1].

unravel.utils.peaks_to_peak(peaks, fixel_weights, frac=None, fvf=None)

Fuse peaks into a single peak based on fixel weight and fvf, intensity is then weighted with frac. Mostly used for visualization purposes.

Parameters:

peaks4-D array of shape (x,y,z,3,k)

List of 4-D arrays of shape (x,y,z,3) containing peak information.

fixel_weights4-D array of shape (x,y,z,K)

Array containing the relative weights of the K fixels in each voxel.

Returns:

peak3-D array of shape (x,y,z,3)

unravel.utils.plot_streamline_trajectory(trk, resolution_increase: int = 1, streamline_number: int = 0, axis: int = 1, color: bool = False, subsegment: int = 10, norm_all_voxels: bool = False)

Produces a graph of the streamline density of tract ‘trk’, the streamline specified with ‘streamline_number’ is highlighted along ‘axis’.

Parameters:

trktractogram

Content of a .trk file.

resolution_increaseint, optional

The dimensions of the volume are multiplied by this value to increase resolution. The default is 1.

streamline_numberint, optional

Number of the streamline to be highlighted. The default is 0.

axisint, optional

Axis of inspection, [0:2] in 3D volumes. The default is 1.

colorbool, optional

If True, output a RGB volume with colors corresponding to the directions of the streamlines, modulated by streamline density. The default is False.

norm_all_voxelsbool, optional

If True, all RGB voxels display maximum intensity. Increases computation time. The default is False.

Returns:

None.

unravel.utils.spherical_to_xyz(theta, phi, r=1)

unravel.utils.tensor_to_DTI(t)

Creates fractional anisotropy (FA), axial diffusivity (AD), radial diffusivity (RD) and mean diffusivity (MD) maps from a tensor array.

Parameters:

t5-D array

Tensor array of shape (x,y,z,1,6).

Returns:

FA3-D array

FA array of shape (x,y,z).

AD3-D array

AD array of shape (x,y,z).

RD3-D array

RD array of shape (x,y,z).

MD3-D array

MD array of shape (x,y,z).

unravel.utils.tract_to_ROI(trk_file: str)

Returns a binary mask of each voxel containing a tractography node.The voxels containing streamlines segments but no nodes will not be selected.

Parameters:

trk_filestr

Path to tractography file (.trk)

Returns:

ROI3-D array of shape (x,y,z)

Binary array containing the ROI associated to the tract in trk_file.

unravel.utils.xyz_to_spherical(xyz)

X,y,z coordinates to spherical coordinates.

Parameters:

xyzarray of size (n,3)

X,y,z coordinates of n points

Returns:

rarray of size (n)

DESCRIPTION.

thetaarray of size (n)

DESCRIPTION.

phiarray of size (n)

DESCRIPTION.

viz

Created on Sat Apr 8 20:41:36 2023

@author: DELINTE Nicolas

unravel.viz.compute_alpha_surface(vf, method: str = 'raw', weighting_function=None, mesh_size: int = 200)

Computes the mesh for the alpha coefficient surface based on the vectors of vf.

Parameters:

vflist

List of the k vectors corresponding to each fiber population

methodstr, optional

Method used for the relative contribution, either;

‘ang’ : angular weighting ‘raw’ : relative angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is ‘raw’.

weighing_functionfunction, optional

Overwrites the weighing function given in method to this method. Used for testing. The default is None.

Returns:

xarray of float64 of size ( mesh_size, mesh_size)

Mesh X coordinates.

yarray of float64 of size ( mesh_size, mesh_size)

Mesh Y coordinates.

zarray of float64 of size ( mesh_size, mesh_size)

Mesh Z coordinates.

coefarray of float64 of size ( mesh_size, mesh_size)

Alpha coefficients.

unravel.viz.convert_to_gif(array, output_folder: str, extension: str = 'webp', axis: int = 2, transparency: bool = False, keep_frames: bool = False)

Creates a GIF from a 3D volume.

Parameters:

array3-D array of shape (x,y,z) or (x,y,z,3)

DESCRIPTION.

output_folderstr

Output filename. Ex: ‘output_path/filename’

extensionstr, optional

File format. The default is ‘webp’.

axisint, optional

Axis number to iterate over. The default is 2.

transparencybool, optional

If True, zero is converted to transparent. The default is False.

keep_framesbool, optional

Only if transparent and gif. Overlaps new frames onto old frames. The default is False.

Returns:

None.

unravel.viz.create_gif_pyvista_plotter(plotter, file_path: str)

Create a 360° rotation GIF of the current 3D view. Example usage:

plotter=pv.Plotter() plot_trk(trk_file,plotter=plotter, background=’white’) create_gif(plotter, gif_file)

Parameters:

plotterpyvista Plotter()

DESCRIPTION.

file_pathstr

Filepath of the GIF file.

Returns:

None.

unravel.viz.create_streamline_propagation_gif(trk, out_gif: str, slice_sel: tuple, resolution_increase: int = 6, subsegment: int = 5, n_frames: int = 800, fps: int = 30, color: bool = False)

Create a GIF of neural activity propagating through all streamlines.

Parameters:

trktractogram

Content of a .trk file

out_gifstr

Path and filename of output GIF (can end in .gif or .webp).

slice_seltuple

Exactly one integer and two slice(None), e.g. (x, :, :) or (:, y, :) or (:, :, z)

resolution_increaseint, optional

Factor multiplying the resolution/dimensions of output array. The default is 1.

subsegmentint, optional

Divides the streamline segment into n subsegments. Increases spatial resolution of streamline segments and computation time. The default is 2.

n_framesint, optional

Number of frames. The default is 400.

fpsint, optional

Frames per second. The default is 20.

colorbool, optional

If True, output a RGB volume with colors corresponding to the directions of the streamlines, modulated by streamline density. The default is False.

Returns:

None.

unravel.viz.export_alpha_surface(vf, output_path: str, method: str = 'raw', show_v: bool = True, v_color: str = 'white', weighting_function=None, mesh_size: int = 200)

Computes and exports the mesh for the alpha coefficient surface based on the vectors of vList.

Tutorial to powerpoint: save as .gltf, open with 3D viewer, save as .glb, open with 3D builder then repair then save as .3mf

Parameters:

vListlist

List of the k vectors corresponding to each fiber population

output_pathstr

Output filename.

methodstr, optional

Method used for the relative contribution, either;

‘ang’ : angular weighting ‘raw’ : relative angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is ‘raw’.

weighing_functionfunction, optional

Overwrites the weighing function given in method to this method. Used for testing. The default is None.

show_vbool, optional

Show vectors. The default is True.

v_colorstr, optional

Vector color. The default is white.

mesh_sizeint, optional

Resolution of the 3D surface. The default is 200.

Returns:

None.

unravel.viz.grayscale_to_rgb(array)

Reapeats a 3D array three times to create a 3D rgb image.

Parameters:

array3-D array of shape (x,y,z)

Grayscale array.

Returns:

array3-D array of shape (x,y,z,3)

grayscale (rgb) image.

unravel.viz.overlap_volumes(vol_list: list, rgb: bool = True, order: int = 0)

Overlaps multiple volumes, zero is taken as transparent. Order of list is important : [foreground,…,background]

Parameters:

vol_listlist

List of 3-D array of shape (x,y,z) or (x,y,z,3).

rgbbool, optional

Output rgb volume. The default is True.

orderint, optional

Increases quality when increasing resolution, also increases computation time. The default is 0.

Returns:

back3-D array of shape (x,y,z) or (x,y,z,3).

Overlaped volumes.

unravel.viz.plot_alpha_surface_matplotlib(vf: list, method: str = 'raw', weighting_function=None, show_v: bool = False)

Computes and plots the mesh for the alpha coefficient surface based on the vectors of vf.

Parameters:

vflist

List of the k vectors corresponding to each fiber population

methodstr, optional

Method used for the relative contribution, either;

‘ang’ : angular weighting ‘raw’ : relative angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is ‘raw’.

weighing_functionfunction, optional

Overwrites the weighing function given in method to this method. Used for testing. The default is None.

show_vbool, optional

Show vectors. The default is False.

Returns:

None.

unravel.viz.plot_alpha_surface_pyvista(vf, method: str = 'raw', weighting_function=None, show_v: bool = False, v_color: str = 'white', mesh_size: int = 200, background_color: str = 'grey')

Computes and plots the mesh for the alpha coefficient surface based on the vectors of vf.

Parameters:

vflist

List of the k vectors corresponding to each fiber population

methodstr, optional

Method used for the relative contribution, either;

‘ang’ : angular weighting ‘raw’ : relative angular weighting ‘cfo’ : closest-fixel-only ‘vol’ : relative volume weighting.

The default is ‘raw’.

weighing_functionfunction, optional

Overwrites the weighing function given in method to this method. Used for testing. The default is None.

show_vbool, optional

Show vectors. The default is False.

v_colorstr, optional

Vector color. The default is white.

mesh_sizeint, optional

Resolution of the 3D surface. The default is 200.

background_color: str, otpional

Color of the background in the 3D render. The default is grey.

Returns:

None.

unravel.viz.plot_metric_along_trajectory(mean, dev, new_fig: bool = True, label: str = '', color: str = None, show_default_label=False)

Plots the output of unravel.analysis.get_metric_along_trajectory.

Parameters:

mean1D array of size (n)

List of means for each subsection.

dev1D array of size (n)

List of deviations for each subsection.

new_figbool, optional

If false, print the plot on the previous ‘plt’ figure. Useful when plotting multiple lines in a single plot. The default is True.

labelstr, optional

Line label. The default is ‘’.

colorstr, optional

Line color. The default is None.

Returns:

None.

unravel.viz.plot_nodes_and_surfaces(point_array, only_nodes: bool = False)

Visualize output of stream.extract_nodes

Parameters:

point_array2D array of size (n, 3)

Coordinates (x,y,z) of the n mean trajectory points.

only_nodesbool, optional

Only plot the nodes and not the planes. The default is False.

Returns:

None.

unravel.viz.plot_roi_sections(roi, voxel: bool = False, background: str = 'grey', color_map: str = 'Set3')

Parameters:

roi3D array of shape (x,y,z)

Labeled volume of n sections of a tract.

voxelbool, optional

If true, plots voxels. I False, plots a smoothed surface. The default is False.

backgroundstr, optional

Color of the background. The default is ‘grey’.

color_mapstr, optional

Color map for the labels. The default is ‘Set3’.

Returns:

None.

unravel.viz.plot_trk(trk_file, scalar=None, color_map='plasma', opacity: float = 1, show_points: bool = False, background: str = 'black', plotter=None)

3D render for .trk files.

Parameters:

trk_filestr

Path to tractography file (.trk)

scalar3D array of size (x,y,z), optional

Volume with values to be projected onto the streamlines. The default is None.

opacityfloat, optional

DESCRIPTION. The default is 1.

show_pointsbool, optional

Enable to show points instead of lines. The default is False.

color_mapstr, optional

Color map for the labels or scalar. ‘Set3’ or ‘tab20’ recommend for segmented color maps. If set to ‘flesh’, the streamlines are colored uniformely with a flesh color. The default is ‘plasma’.

backgroundstr, optional

Color of the background. The default is ‘black’.

plotterpyvista.plotter, optional

If not specifed, creates a new figure. The default is None.

Returns:

None.