xcp_d.utils.utils module

Miscellaneous utility functions for xcp_d.

xcp_d.utils.utils.butter_bandpass(data, sampling_rate, low_pass, high_pass, padtype='constant', padlen=None, order=2)

Apply a Butterworth bandpass filter to data.

Parameters:

• data ((T, S) numpy.ndarray) – Time by voxels/vertices array of data.

• sampling_rate (float) – Sampling frequency. 1/TR(s).

• low_pass (float) – frequency, in Hertz

• high_pass (float) – frequency, in Hertz

• padlen

• padtype

• order (int) – The order of the filter.

Returns:

filtered_data – The filtered data.

Return type:

(T, S) numpy.ndarray

xcp_d.utils.utils.check_deps(workflow)

Make sure dependencies are present in this system.

xcp_d.utils.utils.denoise_with_nilearn(preprocessed_bold, confounds, sample_mask, low_pass, high_pass, filter_order, TR)

Denoise an array with Nilearn.

This function does the following:

1. Interpolate high-motion volumes in the BOLD data and confounds.

2. Detrend interpolated BOLD and confounds. - Only done if denoising is requested. - This also mean-centers the data.

3. Bandpass filter the interpolated data and confounds.

4. Censor the data and confounds.

5. Estimate betas using only the low-motion volumes.

6. Apply the betas to denoise the interpolated BOLD data. This is re-censored in a later step.

Parameters:

• preprocessed_bold (numpy.ndarray of shape (T, S)) – Preprocessed BOLD data, after dummy volume removal, but without any additional censoring.

• confounds (pandas.DataFrame of shape (T, C) or None) – DataFrame containing selected confounds, after dummy volume removal, but without any additional censoring. May be None, if no denoising should be performed.

• sample_mask (numpy.ndarray of shape (T,)) – Low-motion volumes are True and high-motion volumes are False.

• low_pass, high_pass (float) – Low-pass and high-pass thresholds, in Hertz. If 0, that bound will be skipped (e.g., if low-pass is 0 and high-pass isn’t, then high-pass filtering will be performed instead of bnadpass filtering).

• filter_order (int) – Filter order.

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

Returns:

denoised_interpolated_bold – The denoised, interpolated data.

Return type:

numpy.ndarray of shape (T, S)

Notes

This step only removes high-motion outliers (not the random volumes for trimming).

The denoising method is designed to follow recommendations from Lindquist et al.[1]. The method is largely equivalent to Lindquist et al.’s HPMC with orthogonalization.

This function is a modified version of Nilearn’s clean() function, with the following changes:

1. Use numpy.linalg.lstsq() to estimate betas, instead of QR decomposition, in order to denoise the interpolated data as well.

2. Set any leading or trailing high-motion volumes to the closest low-motion volume’s values instead of disabling extrapolation.

3. Return denoised, interpolated data.

References

[1]

Martin A Lindquist, Stephan Geuter, Tor D Wager, and Brian S Caffo. Modular preprocessing pipelines can reintroduce artifacts into fmri data. Human brain mapping, 40(8):2358–2376, 2019. URL: https://doi.org/10.1002/hbm.24528, doi:10.1002/hbm.24528.

xcp_d.utils.utils.estimate_brain_radius(mask_file, head_radius='auto')

Estimate brain radius from binary brain mask file.

Parameters:

• mask_file (str) – Binary brain mask file, in nifti format.

• head_radius (float or “auto”) – Radius of the head, in millimeters, for framewise displacement calculation.

  xcp_d’s default head radius is 50. The recommended value for infants is 35. A value of ‘auto’ is also supported, in which case the brain radius is estimated from the preprocessed brain mask.

Returns:

brain_radius – Estimated brain radius, in millimeters.

Return type:

float

Notes

This function estimates the brain radius based on the brain volume, assuming that the brain is a sphere. This was Paul Taylor’s idea, shared in this NeuroStars post: https://neurostars.org/t/estimating-head-brain-radius-automatically/24290/2.

xcp_d.utils.utils.fwhm2sigma(fwhm)

Convert full width at half maximum to sigma.

Parameters:

fwhm (float) – Full width at half maximum.

Returns:

Sigma.

Return type:

float

xcp_d.utils.utils.get_bold2std_and_t1w_xfms(bold_file, template_to_anat_xfm)

Find transform files in reverse order to transform BOLD to MNI152NLin2009cAsym/T1w space.

Since ANTSApplyTransforms takes in the transform files as a stack, these are applied in the reverse order of which they are specified.

NOTE: This is a Node function.

Parameters:

• bold_file (str) – The preprocessed BOLD file.

• template_to_anat_xfm – The from field is assumed to be the same space as the BOLD file is in. The MNI space could be MNI152NLin2009cAsym, MNI152NLin6Asym, or MNIInfant.

Returns:

• xforms_to_MNI (list of str) – A list of paths to transform files for warping to MNI152NLin2009cAsym space.

• xforms_to_MNI_invert (list of bool) – A list of booleans indicating whether each transform in xforms_to_MNI indicating if each should be inverted (True) or not (False).

• xforms_to_T1w (list of str) – A list of paths to transform files for warping to T1w space.

• xforms_to_T1w_invert (list of bool) – A list of booleans indicating whether each transform in xforms_to_T1w indicating if each should be inverted (True) or not (False).

Notes

Only used for QCReport in init_postprocess_nifti_wf. QCReport wants MNI-space data in MNI152NLin2009cAsym.

xcp_d.utils.utils.get_std2bold_xfms(bold_file)

Obtain transforms to warp atlases from MNI152NLin6Asym to the same template as the BOLD.

Since ANTSApplyTransforms takes in the transform files as a stack, these are applied in the reverse order of which they are specified.

NOTE: This is a Node function.

Parameters:

bold_file (str) – The preprocessed BOLD file.

Returns:

transform_list – A list of paths to transform files.

Return type:

list of str

Notes

Used by:

• to resample dseg in init_postprocess_nifti_wf for QCReport

• to warp atlases to the same space as the BOLD data in init_functional_connectivity_nifti_wf

• to resample dseg to BOLD space for the executive summary plots

Does not include inversion flag output because there is no need (yet). Can easily be added in the future.

xcp_d.utils.utils.list_to_str(lst)

Convert a list to a pretty string.