xcp_d (CBRAIN Tool Config ID: 8503)

External Requirements

These are file-based requirements, external to the pipeline, that must be satisfied for processing to occur. The “Argument IDs” field corresponds to input “id”s within the tool Boutiques Descriptor. “Value”s correspond to either specific configuration files (if there is a numeric value), or otherwise broader file types within CBRAIN (if the entry is text-based).

Argument ID

Flag

Value

Description

subject_dir

n/a

BidsSubject

Subject folder for BIDS (folders name should be sub-XXXXX). This folder is not used under the current implementation but is present for ease of processing workflows.

preproc_fmri_dir

n/a

NibabiesOutput

The root folder of a preprocessed fMRI output from Nibabies, fMRIPREP, or DCAN/HCP outputs that are formed as BIDS derivatives.

preproc_output_json

n/a

5057198

The json descriptor of the original fmri preprocessing derivatives.

fs_license_file

n/a

4323067

Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html

Ancestor Pipelines

This pipeline utilizes outputs from the following pipelines that are also ran in CBRAIN:

  • nibabies

  • bibsnet

Other Processing Settings

These additional settings cover everything outside of files that are used as inputs during processing. The settings cover numeric values, flags, outputs directories, and other settings that are used to configure processing.

Argument ID

Flag

Value

Description

output_dir

n/a

qwerty

The folder to store outputs of XCPD processing.

derivatives_prefix

n/a

Folders to put before the pipeline specific folder. By default this will look like DataProvider/derivatives/PipelineName, where pipeline name is specific to the current pipeline. The provided string must end in /

input_type

–input-type

nibabies

fMRIPprep/nibabies are default structures, DCAN and HCP are optional

despike

–despike

y

Despike the nifti/cifti before postprocessing

warp_surfaces

–warp-surfaces-native2std

y

If used, a workflow will be run to warp native-space (fsnative) reconstructed cortical surfaces (surf.gii files) produced by Freesurfer into standard (fsLR) space. These surface files are primarily used for visual quality assessment. By default, this workflow is disabled. IMPORTANT: This parameter can only be run if the –cifti flag is also enabled.

fd_thresh

–fd-thresh

0.3

Framewise displacement threshold for censoring

head_radius

–head_radius

auto

Head radius for computing FD, default is 50mm, 35mm is recommended for baby

combineruns

–combine-runs

y

Combines all runs into one file.

verbose

-vvv

true

Increases log verbosity

smoothing

–smoothing

6

Smoothing the postprocessed output (fwhm)

lower_bpf

–lower-bpf

0.01

Lower cut-off frequency (Hz) for the butterworth bandpass filter

upper_bpf

–upper-bpf

0.08

Upper cut-off frequency (Hz) for the butterworth bandpass filter

bpf_order

–bpf-order

2

Number of filter coefficients for butterworth bandpass filter

nuisance_regressors

–nuisance-regressors

36P

Nuisance parameters to be selected

min_time

–min-time

210

Minimum amount of time (in seconds) that a run must have following censoring for it to be processed.

mode

–mode

hbcd

The mode of operation for XCP-D. The mode sets several parameters, with values specific to different pipelines. For more information, see the documentation at https://xcp-d.readthedocs.io/en/latest/workflows.html#modes

dummy_scans

–dummy-scans

4

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.

motion_filter_type

–motion-filter-type

none

Type of band-stop filter to use for removing respiratory artifact from motion regressors

create_matrices

–create-matrices

all

If used, this parameter will produce correlation matrices limited to each requested amount of time. If there is more than the required amount of low-motion data, then volumes will be randomly selected to produce denoised outputs with the exact amounts of time requested. If there is less than the required amount of ‘good’ data, then the corresponding correlation matrix will not be produced. Use ‘all’ for all available data.

linc_qc

–linc-qc

y

Add LINC QC to the output

Pipeline Outputs

Following processing, a number of files and folders are identified as outputs that should be saved for future reference. In the following table the ‘Path Relative to Working Directory’ column specifies the location of files that should be saved (with ‘*’ denoting wildcards). The output location for these files in the final ‘DataProvider’ is specified in the ‘Path in Output Data Provider’ column. In the case of HBCD the [DERIVATIVES_PREFIX] entry is empty.

ID

Path Relative to Working Directory

Path in Output DataProvider

Description

xcpd_output_dir

[OUTPUT_DIR]/[SUBJECT_DIR]

[DERIVATIVES_PREFIX]xcp_d

Subject level output for XCP-D

xcpd_ses_summary_html_report

[OUTPUT_DIR]/[SUBJECT_DIR]_ses*_executive_summary.html

[DERIVATIVES_PREFIX]xcp_d

This is the subject level html report generated by XCPD.

xcpd_sub_summary_html_report

[OUTPUT_DIR]/[SUBJECT_DIR].html

[DERIVATIVES_PREFIX]xcp_d

This is the session level html report generated by XCPD.

Command Line Template

The following code-snippet highlights how the tool is referenced on the command-line. The code being displayed is executed within the tool’s container. Some of the directives may describe file manipulations to prepare for processing, and other directives will describe the primary processing command. At the time of processing, the text in brackets will be replaced by text that has been provided to configure processing.

true [SESSION_ID]; true [SUBJECT_DIR]; true [DERIVATIVES_PREFIX]; mkdir -p work; export FS_LICENSE=$PWD/[FS_LICENSE_FILE]; xcp_d [SUBJECT_PREPROC_FMRI_DIR] [OUTPUT_DIR] participant --omp-nthreads 2 [MODE] [COMBINERUNS] [VERBOSE] [INPUT_TYPE] [TASK] [SMOOTHING] [DESPIKE] [LINC_QC] [MIN_TIME] [NUISANCE] --fs-license-file [FS_LICENSE_FILE] [DUMMY_SCANS] [BPF] [LOWER_BPF] [UPPER_BPF] [BPF_ORDER] [MOTION_FILTER_TYPE] [BAND_STOP_MIN] [BAND_STOP_MAX] [MOTION_FILTER_ORDER] [HEAD_RADIUS] [FD_THRESH] [WARP_SURFACES] [BIDS_FILTER] [CREATE_MATRICES] -w work --notrack

File Selection For Processing

The first step of selecting a candidate for processing is determining whether the right files are present. In HBCD processing, pipelines are always run on one session worth of data at a time. With that in mind, we (mostly) query the contents of a subject’s session folder to determine if processing should occur and also which files should be included in processing. For every pipeline there will be at least one requirement group that determines what files are needed for processing to occur. Within a requirement group, there may be criteria that address multiple file (or modality) types, which are known as ‘File Groups’. For processing to occur, the minumum number of files surviving all Included/Excluded terms for a given ‘File Group’ must be satisfied.

To allow for more flexible selection of files for processing, there are often multiple ‘Requirement Groups’. The contents of each ‘File Group’ across ‘Requirement Groups’ must be the same, but which ‘File Groups’ are defined can be different. If multiple ‘Requirement Groups’ are present for the current pipeline, there will be multiple tables in this section. Only one ‘Requirement Group’ needs to be satisfied for processing to occur. If one requirement group is satisfied, then files from all ‘File Groups’ will be included in processing.

Beyond the files that are chosen from this procedure, other associated files defined via the table here will also be included in processing.

Requirement Group: xcp_d_1

File Group

How Many To Keep

Term

Included (True)/Excluded (False)

T1

1

T1w.nii.gz

True

rec-undistorted

False

acq-svslocalizer

False

acq-mrsLoc

False

_QALAS.nii.gz

False

T2

1

T2w.nii.gz

True

rec-undistorted

False

acq-svslocalizer

False

acq-mrsLoc

False

_QALAS.nii.gz

False

FMRI

All

bold.nii.gz

True

rec-undistorted

False

rec-biascorrected

False

AP_FMAP

All

epi.nii.gz

True

dir-AP

True

PA_FMAP

All

epi.nii.gz

True

dir-PA

True

scans.tsv

All

scans.tsv

True

sessions.tsv

All

sessions.tsv

True

Requirement Group: xcp_d_2

File Group

How Many To Keep

Term

Included (True)/Excluded (False)

T2

1

T2w.nii.gz

True

rec-undistorted

False

acq-svslocalizer

False

acq-mrsLoc

False

_QALAS.nii.gz

False

FMRI

All

bold.nii.gz

True

rec-undistorted

False

rec-biascorrected

False

AP_FMAP

All

epi.nii.gz

True

dir-AP

True

PA_FMAP

All

epi.nii.gz

True

dir-PA

True

scans.tsv

All

scans.tsv

True

sessions.tsv

All

sessions.tsv

True

Quality Control Selection Information

The previous section of this page highlighted how to look at a file’s name to determine whether it may belong to a specific ‘File Group’ (such as T2w images) that are needed for processing. Beyond this, it is often necessary to look at some QC criteria to determine whether a file should be included in processing. This section defines the QC criteria that is used to evaluate specific images. These QC criteria always operate on one file group at a time. If a file group uses QC criteria to select images, at least one table will be displayed below. Depending on the context, these criteria will be used to exclude certain images from processing, to find the best available image(s) within a specific category, or to exclude a session from processing. If sorting is the goal, the first row will be considered the most important criteria. In certain cases, not all images will have ratings for a specific QC field. In this case, a backup table (which will be displayed after the first table if available), will be used for that file group.

File Group: T1

Processing will look for best 1 file(s) to keep using the following criteria(s).

scans.tsv Field

Operator

Value

QC

equals

1

QU_motion

less_than

2

aqc_motion

less_than

10000

brain_SNR

greater_than

-1000

scans.tsv Field

Operator

Value

QC

equals

1

aqc_motion

less_than

10000

brain_SNR

greater_than

-1000

File Group: T2

Processing will look for best 1 file(s) to keep using the following criteria(s).

scans.tsv Field

Operator

Value

QC

equals

1

QU_motion

less_than

2

aqc_motion

less_than

10000

brain_SNR

greater_than

-1000

scans.tsv Field

Operator

Value

QC

equals

1

aqc_motion

less_than

10000

brain_SNR

greater_than

-1000

File Group: FMRI

Processing will include all files passing the following criteria.

scans.tsv Field

Operator

Value

QC

equals

1

File Group: AP_FMAP

Processing will include all files passing the following criteria.

scans.tsv Field

Operator

Value

QC

equals

1

File Group: PA_FMAP

Processing will include all files passing the following criteria.

scans.tsv Field

Operator

Value

QC

equals

1