xcp_d.utils.qcmetrics module

Quality control metrics.

xcp_d.utils.qcmetrics.compute_dvars(datat)

Compute standard DVARS.

Parameters:

datat (numpy.ndarray) – The data matrix from which to calculate DVARS. Ordered as vertices by timepoints.

Returns:

The calculated DVARS array. A (timepoints,) array.

Return type:

numpy.ndarray

xcp_d.utils.qcmetrics.compute_registration_qc(bold2t1w_mask, anat_brainmask, bold2template_mask, template_mask)

Compute quality of registration metrics.

This function will calculate a series of metrics, including:

• Dice’s similarity index,

• Pearson correlation coefficient, and

• Coverage

between the BOLD-to-T1w brain mask and the T1w mask, as well as between the BOLD-to-template brain mask and the template mask.

Parameters:

• bold2t1w_mask (str) – Path to the BOLD mask in T1w space.

• anat_brainmask (str) – Path to the T1w mask.

• bold2template_mask (str) – Path to the BOLD mask in template space.

• template_mask (str) – Path to the template mask.

Returns:

reg_qc – Quality control measures between different inputs.

Return type:

dict

xcp_d.utils.qcmetrics.coverage(input1, input2)

Estimate the coverage between two masks.

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:

cov – Coverage between two images.

Return type:

float

xcp_d.utils.qcmetrics.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 Dice[1] and Sorensen[2].

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:

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

Return type:

float

References

[1]

Lee R Dice. Measures of the amount of ecologic association between species. Ecology, 26(3):297–302, 1945. URL: https://doi.org/10.2307/1932409, doi:10.2307/1932409.

[2]

Th A Sorensen. A method of establishing groups of equal amplitude in plant sociology based on similarity of species content and its application to analyses of the vegetation on danish commons. Biol. Skar., 5:1–34, 1948.

xcp_d.utils.qcmetrics.make_dcan_df(filtered_motion, name, TR)

Create an HDF5-format file containing a DCAN-format dataset.

Parameters:

• filtered_motion (str) – Framewise displacement timeseries, potentially after bandstop or low-pass filtering. This is a TSV file with one column: ‘framewise_displacement’.

• name (str) – Name of the HDF5-format file to be created.

• TR (float) – Repetition time of the BOLD run, in seconds.

Notes

The metrics in the file are:

• FD_threshold: a number >= 0 that represents the FD threshold used to calculate the metrics in this list.

• frame_removal: a binary vector/array the same length as the number of frames in the concatenated time series, indicates whether a frame is removed (1) or not (0)

• format_string (legacy): a string that denotes how the frames were excluded. This uses a notation devised by Avi Snyder.

• total_frame_count: a whole number that represents the total number of frames in the concatenated series

• remaining_frame_count: a whole number that represents the number of remaining frames in the concatenated series

• remaining_seconds: a whole number that represents the amount of time remaining after thresholding

• remaining_frame_mean_FD: a number >= 0 that represents the mean FD of the remaining frames

xcp_d.utils.qcmetrics.pearson(input1, input2)

Calculate Pearson product moment correlation between two 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:

corr – Correlation between the two images.

Return type:

float