aslprep.utils.confounds module

Functions for calculating and collecting confounds.

average_cbf_by_tissue(cbf, gm, wm, csf, thresh)

Compute mean GM, WM, and CSF CBF values.

Parameters:

• cbf (str) – Path to CBF file.

• gm, wm, csf (str) – Paths to GM, WM, and CSF tissue probability maps, in same space and resolution as cbf.

• thresh (float) – Threshold to apply to the TPMs. Default is 0.7.

Returns:

mean_tissue_cbfs – Mean CBF values from binarized versions of the tissue maps.

Return type:

list of float

compute_cbf_threshold_stats(cbf, mask, thresholds=(100, 150, 200))

Compute the percentage of in-mask voxels that exceed specified CBF thresholds.

Args:

cbf: path or array of cbf data mask: path or array of binary brain mask thresholds: cutoff to check against (default: 100, 150, 200)

Returns:

a dictionary of percentages like {‘perc_voxels_cbf_gt_100’: 45.2} returns NaN if mask is empty

compute_qei(gm, wm, csf, img, thresh, alpha=-3.0126, beta=2.4419, gamma=0.054, delta=0.9272, epsilon=2.8478, zeta=0.5196)

Compute quality evaluation index (QEI) using the individual components.

The QEI is based on Dolui et al.[1].

\[QEI = \sqrt[3]{(1 - e^{\alpha\rho_{ss}^{\beta}}) e^{-\left(\gamma\text{DI}^{\delta} + \epsilon\text{negGM}^{\zeta}\right)}}\]

The constants used here differ slightlyfrom those in the paper, but match the actual values used in the original QEI implementation.

Parameters:

• gm, wm, csf (str) – Paths to GM, WM, and CSF tissue probability maps, in same space and resolution as cbf.

• img (str or nibabel.nifti1.Nifti1Image) – Path to CBF file or Nifti1Image. This image should NOT be smoothed prior use in this function.

• thresh (float) – Threshold to apply to the TPMs. Default is 0.7.

Returns:

• qei (float) – Quality evaluation index.

• rho_ss (float) – Structural pseudocbf correlation.

• di (float) – Dispersion index (DI).

• neg_gm (float) – Percentage of negative voxels within grey matter mask.

References

dice(input1, input2)

Calculate Dice coefficient between two arrays.

Computes the Dice coefficient (also known as Sorensen index) between two binary images.

The metric is defined as

\[DC=\frac{2|A\cap B|}{|A|+|B|}\]

, where \(A\) is the first and \(B\) the second set of samples (here: binary objects). This method was first proposed in and .

Parameters:

input1/input2 (numpy.ndarray) – Numpy arrays to compare. Can be any type but will be converted into binary: False where 0, True everywhere else.

Returns:

coef – The Dice coefficient between input1 and input2. It ranges from 0 (no overlap) to 1 (perfect overlap).

Return type:

float

References

[1] (1,2,3)

Sudipto Dolui, Ze Wang, Ronald L Wolf, Ali Nabavizadeh, Long Xie, Duygu Tosun, Ilya M Nasrallah, David A Wolk, John A Detre, and Alzheimer’s Disease Neuroimaging Initiative. Automated quality evaluation index for arterial spin labeling derived cerebral blood flow maps. Journal of Magnetic Resonance Imaging, 60(6):2497–2508, 2024.

dispersion_index(wm_mask, gm_mask, csf_mask, cbf_image)

Calculate the dispersion index (DI) from Dolui et al.[1].

Parameters:

• wm_mask, gm_mask, csf_mask (numpy.ndarray) – Binary masks for WM, GM, and CSF.

• cbf_image (str or nibabel.nifti1.Nifti1Image) – Path to CBF file or Nifti1Image. This image should be smoothed prior use in this function.

Returns:

di – Dispersion index.

Return type:

float

References

overlap(input1, input2)

Calculate overlap coefficient between two images.

The metric is defined as

\[DC=\frac{|A \cap B||}{min(|A|,|B|)}\]

, where \(A\) is the first and \(B\) the second set of samples (here: binary objects).

The overlap coefficient is also known as the Szymkiewicz-Simpson coefficient .

Parameters:

input1/input2 (numpy.ndarray) – Numpy arrays to compare. Can be any type but will be converted into binary: False where 0, True everywhere else.

Returns:

coef – Coverage between two images.

Return type:

float

References

pearson(input1, input2)

Calculate Pearson product moment correlation between two mask images.

Parameters:

input1/input2 (numpy.ndarray) – Numpy arrays to compare. Can be any type but will be converted into binary: False where 0, True everywhere else.

Returns:

coef – Correlation between the two images.

Return type:

float

structural_pseudocbf_correlation(gm_probseg, wm_probseg, cbf_image)

Compute structural pseudocbf (rho_ss) from Dolui et al.[1].

Parameters:

• gm_probseg, wm_probseg (str) – Paths to GM, WM tissue probability maps, in same space and resolution as cbf.

• cbf_image (str or nibabel.nifti1.Nifti1Image) – Path to CBF file or Nifti1Image. This image should be smoothed prior use in this function.

Returns:

structural_pseudocbf_correlation – Structural pseudocbf correlation.

Return type:

float

References