xcp_d.interfaces.censoring module

Interfaces for the post-processing workflows.

class xcp_d.interfaces.censoring.Censor(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Apply temporal mask to data.

If a column other than “framewise_displacement” is used, then this assumes that the outliers flagged by “framewise_displacement” have already been removed from the BOLD file, and it reduces the data further.

Mandatory Inputs:

  • in_file (a pathlike object or string representing an existing file) – BOLD file after denoising, interpolation, and filtering.

  • temporal_mask (a pathlike object or string representing an existing file) – Temporal mask; all motion outlier volumes set to 1. This is a TSV file with one column: ‘framewise_displacement’.

Optional Inputs:

column (a string) – Column name in the temporal mask to use for censoring. (Nipype default value: framewise_displacement)

Outputs:

out_file (a pathlike object or string representing an existing file) – Censored BOLD file.

class xcp_d.interfaces.censoring.GenerateConfounds(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Load confounds according to a configuration file.

This function basically checks that each confounds file has the right number of volumes, selects the requisite columns from each input tabular file, and puts those columns into a single tabular file.

It also applies the motion filter to motion-based regressors, if any are detected. NOTE: This interface identifies motion-based regressors based on their names. If the names of the motion-based regressors are not as expected, the motion filter will not be applied.

Parameters:

  • confounds_files (dict) – Dictionary of confound names and paths to corresponding files. Keys are confound names, values are dictionaries with keys “file” and “metadata”.

  • confounds_config (dict) – Configuration file for confounds.

  • n_volumes (int) – Number of volumes in the fMRI data.

Returns:

  • confounds_tsv (str or None) – Path to the TSV file containing combined tabular confounds. None if no tabular confounds are present.

  • confounds_images (list of str) – List of paths to the voxelwise confounds images.

Mandatory Inputs:

  • TR (a float) – Repetition time in seconds.

  • band_stop_max (a float or None) – Upper frequency for the band-stop motion filter, in breaths-per-minute (bpm).

  • band_stop_min (a float or None) – Lower frequency for the band-stop motion filter, in breaths-per-minute (bpm).

  • confounds_config (a dictionary with keys which are any value and with values which are any value) – Configuration file for confounds.

  • confounds_files (a dictionary with keys which are any value and with values which are any value) – Dictionary of confound names and paths to corresponding files. Keys are confound names, values are dictionaries with keys ‘file’ and ‘metadata’.

  • dataset_links (a dictionary with keys which are any value and with values which are any value) – Dataset links for the XCP-D run.

  • in_file (a pathlike object or string representing an existing file) – Preprocessed BOLD file.

  • motion_filter_order (an integer or None)

  • motion_filter_type (a string or None)

  • out_dir (a string) – Output directory for the XCP-D run. Not used to write out any files- just used for dataset links.

Outputs:

  • confounds_images (a list of items which are a pathlike object or string representing an existing file) – The aggregated confounds in image files.

  • confounds_metadata (a dictionary with keys which are any value and with values which are any value) – Metadata associated with the confounds output.

  • confounds_tsv (a pathlike object or string representing an existing file) – The aggregated confounds in a tabular file.

class xcp_d.interfaces.censoring.ProcessMotion(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Load and filter motion regressors in order to generate a temporal mask.

Mandatory Inputs:

  • TR (a float) – Repetition time in seconds.

  • band_stop_max (a float or None) – Upper frequency for the band-stop motion filter, in breaths-per-minute (bpm).

  • band_stop_min (a float or None) – Lower frequency for the band-stop motion filter, in breaths-per-minute (bpm).

  • motion_file (a pathlike object or string representing an existing file) – FMRIPrep confounds tsv.

  • motion_filter_order (an integer or None)

  • motion_filter_type (a string or None)

  • motion_json (a pathlike object or string representing an existing file) – FMRIPrep confounds json.

Optional Inputs:

  • fd_thresh (a float) – Framewise displacement threshold. All values above this will be dropped. (Nipype default value: 0.3)

  • head_radius (a float) – Head radius in mm. (Nipype default value: 50)

Outputs:

  • motion_file (a pathlike object or string representing an existing file) – The filtered motion parameters.

  • motion_metadata (a dictionary with keys which are any value and with values which are any value) – Metadata associated with the motion_file output.

  • temporal_mask (a pathlike object or string representing an existing file) – Temporal mask; all values above fd_thresh set to 1. This is a TSV file with one column: ‘framewise_displacement’.

  • temporal_mask_metadata (a dictionary with keys which are any value and with values which are any value) – Metadata associated with the temporal_mask output.

class xcp_d.interfaces.censoring.RandomCensor(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Randomly flag volumes to censor.

Mandatory Inputs:

  • exact_scans (a list of items which are an integer) – Numbers of scans to retain. If None, no additional censoring will be performed.

  • temporal_mask (a pathlike object or string representing an existing file) – Temporal mask; all motion outlier volumes set to 1. This is a TSV file with one column: ‘framewise_displacement’.

Optional Inputs:

  • random_seed (an integer or None) – Random seed. (Nipype default value: None)

  • temporal_mask_metadata (a dictionary with keys which are any value and with values which are any value) – Metadata associated with the temporal_mask output.

Outputs:

  • temporal_mask (a pathlike object or string representing an existing file) – Temporal mask file.

  • temporal_mask_metadata (a dictionary with keys which are any value and with values which are any value) – Metadata associated with the temporal_mask output.

class xcp_d.interfaces.censoring.RemoveDummyVolumes(from_file=None, resource_monitor=None, **inputs)[source]

Bases: SimpleInterface

Removes initial volumes from a nifti or cifti file.

A bold file and its corresponding confounds TSV (fmriprep format) are adjusted to remove the first n seconds of data.

Mandatory Inputs:

  • bold_file (a pathlike object or string representing an existing file) – Either cifti or nifti .

  • dummy_scans (an integer or ‘auto’) – Number of volumes to drop from the beginning, calculated in an earlier workflow from dummy_scans.

  • motion_file (a pathlike object or string representing an existing file) – TSV file with motion regressors. Used for motion-based censoring.

  • temporal_mask (a pathlike object or string representing an existing file) – Temporal mask file.

Optional Inputs:

  • confounds_images (a list of items which are a pathlike object or string representing an existing file or None) – List of images with confounds. May be None if denoising is disabled.

  • confounds_tsv (a pathlike object or string representing an existing file or None) – TSV file with selected confounds for denoising. May be None if denoising is disabled.

Outputs:

  • bold_file_dropped_TR (a pathlike object or string representing an existing file) – Bold or cifti with volumes dropped.

  • confounds_images_dropped_TR (a list of items which are a pathlike object or string representing an existing file or None) – List of images with confounds. May be None if denoising is disabled.

  • confounds_tsv_dropped_TR (a pathlike object or string representing an existing file or None) – TSV file with selected confounds for denoising. May be None if denoising is disabled.

  • dummy_scans (an integer) – Number of volumes dropped.

  • motion_file_dropped_TR (a pathlike object or string representing an existing file) – TSV file with motion parameters.

  • temporal_mask_dropped_TR (a pathlike object or string representing an existing file) – Temporal mask file.