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)[source]

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.denoise_with_nilearn(preprocessed_bold, confounds_file, temporal_mask, low_pass, high_pass, filter_order, TR)[source]

Denoise an array with Nilearn.

This step does the following:

  1. Orthogonalize nuisance regressors w.r.t. any signal regressors.

  2. Censor the data and associated confounds.

  3. Mean-center the censored and uncensored confounds, based on the censored confounds.

  4. Estimate betas using only the censored data.

  5. Apply the betas to denoise the full (uncensored) BOLD data.

  6. Apply the betas to denoise the censored BOLD data.

  7. Interpolate the censored, denoised data.

  8. Bandpass filter the interpolated, denoised data.

Parameters:

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

  • confounds_file (str) – Path to TSV file containing selected confounds, after dummy volume removal, but without any additional censoring.

  • temporal_mask (str) – Temporal mask; all values above fd_thresh set to 1. This is a TSV file with one column: ‘framewise_displacement’.

  • low_pass, high_pass (float or None) – Lowpass and high_pass thresholds, in Hertz.

  • filter_order (int) – Filter order.

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

Returns:

  • uncensored_denoised_bold (str) – Path to the uncensored, denoised BOLD file. This file is the result of denoising the full (uncensored) preprocessed BOLD data using betas estimated using the censored BOLD data and nuisance regressors.

    This output should not be used for analysis. It is primarily used for DCAN QC plots. Returned as a numpy.ndarray of shape (T, S)

  • interpolated_filtered_bold (str) – Path to the censored, denoised, interpolated, and filtered BOLD file. This file is the result of denoising the censored preprocessed BOLD data, followed by cubic spline interpolation and band-pass filtering.

    This output should not be used for analysis. It is primarily for DCAN QC plots. Returned as a numpy.ndarray of shape (T, S) This is the primary output.

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

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)[source]

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, anat_to_native_xfm)[source]

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.

  • anat_to_native_xfm

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, template_to_anat_xfm, anat_to_native_xfm)[source]

Obtain transforms to warp atlases from MNI152NLin6Asym to the same space 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.

  • %(template_to_anat_xfm)s – The from field is assumed to be the same space as the BOLD file is in.

  • %(anat_to_native_xfm)s

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.