scilpy.dwi package

scilpy.dwi.operations module

scilpy.dwi.operations.apply_bias_field(dwi_data, bias_field_data, mask_data)

To apply a bias field (computed beforehands), we need to 1) Divide the dwi by the bias field. This is the correction itself. See the following references: https://simpleitk.readthedocs.io/en/master/link_N4BiasFieldCorrection_docs.html https://mrtrix.readthedocs.io/en/dev/reference/commands/dwibiascorrect.html 2) Rescale the dwi, to ensure that the initial min-max range is kept.

Parameters:

• dwi_data (np.ndarray) – The 4D dwi data.

• bias_field_data (np.ndarray) – The 3D bias field. Typically comes from ANTS’S N4BiasFieldCorrection.

• mask_data (np.ndarray) – The mask where to apply the bias field.

Returns:

dwi_data – The modified 4D dwi_data.

Return type:

np.ndarray

scilpy.dwi.operations.compute_dwi_attenuation(dwi_weights: ndarray, b0: ndarray)

Compute signal attenuation by dividing the dwi signal with the b0.

Parameters:

dwi_weightsnp.ndarray of shape (X, Y, Z, #gradients)

Diffusion weighted images.

b0np.ndarray of shape (X, Y, Z)

B0 image.

returns:

dwi_attenuation – Signal attenuation (Diffusion weights normalized by the B0).

rtype:

np.ndarray

scilpy.dwi.operations.compute_residuals(predicted_data, real_data, b0s_mask=None, mask=None)

Computes the residuals, a 3D map allowing comparison between the predicted data and the real data. The result is the average of differences for each feature of the data, on the last axis.

If data is a tensor, the residuals computation was introduced in: [J-D Tournier, S. Mori, A. Leemans. Diffusion Tensor Imaging and Beyond. MRM 2011].

Parameters:

• predicted_data (np.ndarray) – 4D dwi volume.

• real_data (np.ndarray) – 4D dwi volume.

• b0s_mask (np.array, optional) – Vector of booleans containing True at indices where the dwi data was a b0 (on last dimension). If given, the b0s are rejected from the data before computing the residuals.

• mask (np.ndaray, optional) – 3D volume. If given, residual is set to 0 outside the mask.

scilpy.dwi.operations.compute_residuals_statistics(diff_data)

Compute statistics on the residuals for each gradient.

Parameters:

diff_data (np.ndarray) – The 4D residuals between the DWI and predicted data.

scilpy.dwi.operations.detect_volume_outliers(data, bvals, bvecs, std_scale, b0_thr=20)

Detects outliers. Finds the 3 closest angular neighbors of each direction (per shell) and computes the voxel-wise correlation. If the angles or correlations to neighbors are below the shell average (by std_scale x STD) it will flag the volume as a potential outlier.

Parameters:

• data (np.ndarray) – 4D Input diffusion volume with shape (X, Y, Z, N)

• bvals (ndarray) – 1D bvals array with shape (N,)

• bvecs (ndarray) – 2D bvecs array with shape (N, 3)

• std_scale (float) – How many deviation from the mean are required to be considered an outlier.

• b0_thr (float) – Value below which b-values are considered as b0.

Returns:

• results_dict (dict) – The resulting statistics. One key per shell (its b-value). For each key, the associated entry is an array of shape [nb_points, 3] where columns are:

  • point_idx: int, the index of the bvector in the input bvecs.

  • mean_angle: float, the mean angles of the 3 closest bvecs, in degree

  • mean_correlation: float, the mean correlation of the 3D data

  associated to the 3 closest bvecs.

• outliers_dict (dict) – The resulting outliers. One key per shell (its b-value). For each key, the associated entry is a dict {‘outliers_angle’: list[int],

  ’outliers_corr’: list[int]}

  The indices of outliers (indices in the original bvecs).

scilpy.dwi.utils module

scilpy.dwi.utils.extract_b0(dwi, b0_mask, extract_in_cluster=False, strategy=B0ExtractionStrategy.MEAN, block_size=None)

Extract a set of b0 volumes from a dwi dataset

Parameters:

• dwi (nib.Nifti1Image) – Original multi-shell volume.

• b0_mask (ndarray of bool) – Mask over the time dimension (4th) identifying b0 volumes.

• extract_in_cluster (bool) – Specify to extract b0’s in each continuous sets of b0 volumes appearing in the input data.

• strategy (enum) – The extraction strategy. Must be one choice available in our enum B0ExtractionStrategy: either select the first b0 found, select them all or average them. When used in conjunction with the extract_in_cluster parameter set to True, the strategy is applied individually on each continuous set found.

• block_size (int, optional) – Load the data using this block size. Useful when the data is too large to be loaded in memory.

Returns:

b0_data – Extracted b0 volumes. 3D with one b0, else 4D.

Return type:

ndarray

scilpy.dwi.utils.extract_dwi_shell(dwi, bvals, bvecs, bvals_to_extract, tol=20, block_size=None)

Extracts the DWI volumes that are on specific b-value shells. Many shells can be extracted at once by specifying multiple b-values. The extracted volumes are in the same order as in the original file.

If the b-values of a shell are not all identical, use the –tolerance argument to adjust the accepted interval. For example, a b-value of 2000 and a tolerance of 20 will extract all volumes with a b-values from 1980 to 2020.

Files that are too large to be loaded in memory can still be processed by setting the –block-size argument. A block size of X means that X DWI volumes are loaded at a time for processing.

Parameters:

• dwi (nib.Nifti1Image) – Original multi-shell volume.

• bvals (ndarray) – The b-values in FSL format.

• bvecs (ndarray) – The b-vectors in FSL format.

• bvals_to_extract (list of int) – The list of b-values to extract.

• tol (int) – The tolerated gap between the b-values to extract and the actual b-values.

• block_size (int, optional) – Load the data using this block size. Useful when the data is too large to be loaded in memory.

Returns:

• indices (ndarray) – Indices of the volumes corresponding to the provided b-values.

• shell_data (ndarray) – Volumes corresponding to the provided b-values.

• output_bvals (ndarray) – Selected b-values (raw values, not rounded values, even when tol is given).

• output_bvecs (ndarray) – Selected b-vectors.