xcp_d.utils.modified_data module

Functions for interpolating over high-motion volumes.

xcp_d.utils.modified_data.cast_cifti_to_int16(in_file)

Cast a CIFTI file to int16 data.

This function serves as a temporary workaround for a bug in the DerivativesDataSink class from niworkflows version 1.7.1. For more information, see https://github.com/nipreps/niworkflows/issues/778.

NOTE: This is a Node function.

Parameters:

in_file (str) – Path to input CIFTI file.

Returns:

out_file – Path to output CIFTI file. The file will have the same filename, but will be written to the working directory.

Return type:

str

xcp_d.utils.modified_data.compute_fd(confound, head_radius=50)

Compute framewise displacement.

NOTE: TS- Which kind of FD? Power? NOTE: TS- What units must rotation parameters be in?

Parameters:

• confound (pandas.DataFrame) – DataFrame with six motion parameters.

• 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:

fdres – The framewise displacement time series.

Return type:

numpy.ndarray

xcp_d.utils.modified_data.downcast_to_32(in_file)

Downcast a file from >32-bit to 32-bit if necessary.

Parameters:

in_file (None or str) – Path to a file to downcast. If None, None will be returned. If the file is lower-precision than 32-bit, then it will be returned without modification.

Returns:

Path to the downcast file. If in_file is None, None will be returned. If in_file is a file with lower than 32-bit precision, then it will be returned without modification. Otherwise, a new path will be returned.

Return type:

None or str

xcp_d.utils.modified_data.flag_bad_run(fmriprep_confounds_file, dummy_scans, TR, motion_filter_type, motion_filter_order, band_stop_min, band_stop_max, head_radius, fd_thresh)

Determine if a run has too many high-motion volumes to continue processing.

Parameters:

• fmriprep_confounds_file (str) – Confounds TSV file from preprocessing derivatives.

• dummy_scans (int or “auto”) – Number of volumes to remove from the beginning of each run. If set to ‘auto’, xcp_d will extract non-steady-state volume indices from the preprocessing derivatives’ confounds file.

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

• motion_filter_type ({None, “lp”, “notch”}) – Type of filter to use for removing respiratory artifact from motion regressors.

  If None, no filter will be applied.

  If the filter type is set to “notch”, frequencies between band_stop_min and band_stop_max will be removed with a notch filter. In this case, both band_stop_min and band_stop_max must be defined.

  If “lp”, frequencies above band_stop_min will be removed with a Butterworth filter. In this case, only band_stop_min must be defined.

• motion_filter_order (int) – Number of filter coefficients for the motion parameter filter. Motion filtering is only performed if motion_filter_type is not None. This parameter is used in conjunction with band_stop_max and band_stop_min.

• band_stop_min (float or None) – Lower frequency for the motion parameter filter, in breaths-per-minute (bpm). Motion filtering is only performed if motion_filter_type is not None. If used with the “lp” motion_filter_type, this parameter essentially corresponds to a low-pass filter (the maximum allowed frequency in the filtered data). This parameter is used in conjunction with motion_filter_order and band_stop_max.

  Here is a list of recommended values, based on participant age:

  Age Range (years)	Recommended Value
  < 1	30
  1 - 2	25
  2 - 6	20
  6 - 12	15
  12 - 18	12
  19 - 65	12
  65 - 80	12
  > 80	10

  When motion_filter_type is set to “lp” (low-pass filter), another commonly-used value for this parameter is 6 BPM (equivalent to 0.1 Hertz), based on Gratton et al.[1].

• band_stop_max (float or None) – Upper frequency for the motion parameter filter, in breaths-per-minute (bpm). Motion filtering is only performed if motion_filter_type is not None. This parameter is only used if motion-filter-type is set to “notch”. This parameter is used in conjunction with motion_filter_order and band_stop_min.

  Here is a list of recommended values, based on participant age:

  Age Range (years)	Recommended Value
  < 1	60
  1 - 2	50
  2 - 6	35
  6 - 12	25
  12 - 18	20
  19 - 65	18
  65 - 80	28
  > 80	30

• 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.

• fd_thresh (float) – Framewise displacement threshold for censoring, in millimeters. Any framewise displacement values higher than the threshold are flagged as “high motion”. If set to <=0, no censoring will be performed. Default is 0.2 mm.

• brain_mask

Returns:

post_scrubbing_duration – Amount of time remaining in the run after dummy scan removal, in seconds.

Return type:

float

xcp_d.utils.modified_data.scale_to_min_max(X, x_min, x_max)

Scale data to between minimum and maximum values.