Running XCP-D
Warning
XCP-D may not run correctly on M1 chips.
Execution and Input Formats
The XCP-D workflow takes fMRIPrep, Nibabies, HCP Pipelines, ABCD-BIDS, and UK Biobank outputs in the form of BIDS derivatives. In these examples, we use an fmriprep output directory.
The outputs are required to include at least anatomical and functional outputs with at least one preprocessed BOLD image. Additionally, each of these should be in directories that can be parsed by the BIDS online validator (even if it is not BIDS valid - we do not require BIDS valid directories). The directories must also include a valid dataset_description.json.
The exact command to run in XCP-D depends on the Installation method and data that needs to be processed. We start first with the bare-metal Manually Prepared Environment (Python 3.10) installation, as the command line is simpler. XCP-D can be executed on the command line, processesing fMRIPrep outputs, using the following command-line structure, for example:
xcp_d /path/to/fmriprep_dir \
/path/to/output_dir \
participant \ # analysis_level
--mode <mode> \ # required
--participant-label <label> # optional
However, we strongly recommend using Container Technologies. Here, the command-line will be composed of a preamble to configure the container execution, followed by the XCP-D command-line options as if you were running it on a bare-metal installation.
Command-Line Arguments
XCP-D: Postprocessing Workflow of fMRI Data v0.11.0rc2.dev11+gbadbacb
usage: xcp_d [-h] --mode {abcd,hbcd,linc,nichart,none} [--version]
[--participant-label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]]
[--session-id SESSION_ID [SESSION_ID ...]] [-t TASK_ID]
[--bids-filter-file FILE] [-d PACKAGE=PATH [PACKAGE=PATH ...]]
[--bids-database-dir PATH] [--nprocs NPROCS]
[--omp-nthreads OMP_NTHREADS] [--mem-mb MEMORY_MB] [--low-mem]
[--use-plugin USE_PLUGIN] [-v]
[--input-type {fmriprep,dcan,hcp,nibabies,ukb}]
[--file-format {auto,cifti,nifti}] [--dummy-scans {{auto,INT}}]
[--despike [{y,n}]] [-p CONFOUNDS_CONFIG]
[--smoothing {{auto,FLOAT}}] [-m [{y,n}]]
[--motion-filter-type {lp,notch,none}] [--band-stop-min BPM]
[--band-stop-max BPM] [--motion-filter-order MOTION_FILTER_ORDER]
[-r HEAD_RADIUS] [-f FD_THRESH] [--min-time MIN_TIME]
[--output-type {auto,censored,interpolated}]
[--disable-bandpass-filter] [--lower-bpf HIGH_PASS]
[--upper-bpf LOW_PASS] [--bpf-order BPF_ORDER]
[--atlases ATLAS [ATLAS ...] | --skip-parcellation]
[--min-coverage {auto,FLOAT}]
[--create-matrices CORRELATION_LENGTHS [CORRELATION_LENGTHS ...]]
[--random-seed _RANDOM_SEED] [--linc-qc [{y,n}]]
[--abcc-qc [{y,n}]]
[--report-output-level {root,subject,session}]
[--aggregate-session-reports AGGR_SES_REPORTS] [-w WORK_DIR]
[--clean-workdir] [--resource-monitor] [--config-file FILE]
[--write-graph] [--stop-on-first-crash] [--notrack]
[--debug {pdb,all} [{pdb,all} ...]] [--fs-license-file FILE]
[--md-only-boilerplate] [--boilerplate-only] [--reports-only]
[--warp-surfaces-native2std [{y,n}]]
fmri_dir output_dir {participant}
Positional Arguments
- fmri_dir
The root folder of fMRI preprocessing derivatives. For example, ‘/path/to/dset/derivatives/fmriprep’.
- output_dir
The output path for XCP-D derivatives. For example, ‘/path/to/dset/derivatives/xcp_d’. As of version 0.7.0, ‘xcp_d’ will not be appended to the output directory.
- analysis_level
Possible choices: participant
The analysis level for XCP-D. Must be specified as ‘participant’.
Named Arguments
- --version
show program’s version number and exit
required arguments
- --mode
Possible choices: abcd, hbcd, linc, nichart, none
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
Options for filtering BIDS queries
- --participant-label, --participant_label
A space-delimited list of participant identifiers, or a single identifier. The “sub-” prefix can be removed.
- --session-id, --session_id
A space-delimited list of session identifiers, or a single identifier. The “ses-” prefix can be removed. By default, all sessions will be postprocessed.
- -t, --task-id, --task_id
The name of a specific task to postprocess. By default, all tasks will be postprocessed. If you want to select more than one task to postprocess (but not all of them), you can either run XCP-D with the –task-id parameter, separately for each task, or you can use the –bids-filter-file to specify the tasks to postprocess.
- --bids-filter-file, --bids_filter_file
A JSON file describing custom BIDS input filters using PyBIDS. For further details, please check out https://xcp-d.readthedocs.io/en/latest/usage.html#filtering-inputs-with-bids-filter-files
- -d, --datasets
Search PATH(s) for derivatives or atlas datasets. These may be provided as named folders (e.g., –datasets smriprep=/path/to/smriprep).
- --bids-database-dir
Path to a PyBIDS database folder, for faster indexing (especially useful for large datasets). Will be created if not present.
Options for resource management
- --nprocs, --nthreads, --n-cpus, --n_cpus
Maximum number of threads across all processes.
Default:
2
- --omp-nthreads, --omp_nthreads
Maximum number of threads per process.
Default:
1
- --mem-mb, --mem_mb
Upper bound memory limit, in megabytes, for XCP-D processes.
- --low-mem
Attempt to reduce memory usage (will increase disk usage in working directory).
Default:
False
- --use-plugin, --use_plugin, --nipype-plugin-file, --nipype_plugin_file
Nipype plugin configuration file. For more information, see https://nipype.readthedocs.io/en/0.11.0/users/plugins.html.
- -v, --verbose
Increases log verbosity for each occurrence. Debug level is ‘-vvv’.
Default:
0
Input flags
- --input-type, --input_type
Possible choices: fmriprep, dcan, hcp, nibabies, ukb
The pipeline used to generate the preprocessed derivatives. The default pipeline is ‘fmriprep’. The ‘dcan’, ‘hcp’, ‘nibabies’, and ‘ukb’ pipelines are also supported. ‘nibabies’ assumes the same structure as ‘fmriprep’.
Default:
'auto'
- --file-format
Possible choices: auto, cifti, nifti
The file format of the input data. If ‘auto’, the file format will be inferred from the processing mode. If ‘cifti’, the input data are assumed to be in CIFTI format. If ‘nifti’, the input data are assumed to be in NIfTI format.
Default:
'auto'
Postprocessing parameters
- --dummy-scans, --dummy_scans
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.
Default:
0
- --despike
Possible choices: y, n
Despike the BOLD data before postprocessing. If not defined, the despike option will be inferred from the ‘mode’. If defined without an argument, despiking will be enabled. If defined with an argument (y or n), the value of the argument will be used. ‘y’ enables despiking. ‘n’ disables despiking.
Default:
'auto'
- -p, --nuisance-regressors, --nuisance_regressors
Nuisance parameters to be selected. This may be a string indicating one of XCP-D’s built-in nuisance regression strategies (e.g., ‘36P’) or a path to a YAML file formatted according to XCP-D’s confound configuration file format. Descriptions of each of the built-in options are included in XCP-D’s documentation.
Default:
'auto'
- --smoothing
FWHM, in millimeters, of the Gaussian smoothing kernel to apply to the denoised BOLD data. Set to 0 to disable smoothing.
Default:
auto
- -m, --combine-runs, --combine_runs
Possible choices: y, n
After denoising, concatenate each derivative from each task across runs.
Default:
'auto'
Motion filtering parameters
These parameters enable and control a filter that will be applied to motion parameters. Motion parameters may be contaminated by non-motion noise, and applying a filter may reduce the impact of that contamination.
- --motion-filter-type, --motion_filter_type
Possible choices: lp, notch, none
Type of filter to use for removing respiratory artifact from motion regressors. If not set, no filter will be applied.
If the filter type is set to “notch”, then both
band-stop-min
andband-stop-max
must be defined. If the filter type is set to “lp”, then onlyband-stop-min
must be defined. If the filter type is set to “none”, then no filter will be applied.- --band-stop-min, --band_stop_min
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 withmotion-filter-order
andband-stop-max
.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. (2020).- --band-stop-max, --band_stop_max
Upper frequency for the band-stop motion filter, in breaths-per-minute (bpm). Motion filtering is only performed if
motion-filter-type
is not None. This parameter is only used ifmotion-filter-type
is set to “notch”. This parameter is used in conjunction withmotion-filter-order
andband-stop-min
.- --motion-filter-order, --motion_filter_order
Number of filter coefficients for the motion parameter filter. If the motion filter type is ‘lp’, the order is divided by 2 as filtfilt applies the filter twice. If the motion filter type is ‘notch’, the order is divided by 4 as iirnotch is a second-order filter and filtfilt applies the filter twice. Make sure to set this parameter to a multiple of 2 if you choose the ‘lp’ filter and a multiple of 4 if you choose the ‘notch’ filter.
Default:
4
Censoring and scrubbing options
- -r, --head-radius, --head_radius
Head radius used to calculate framewise displacement, in mm. The default value is 50 mm, which is recommended for adults. For infants, we recommend a value of 35 mm. A value of ‘auto’ is also supported, in which case the brain radius is estimated from the preprocessed brain mask by treating the mask as a sphere. The auto option typically results in a higher estimate than the default.
Default:
50
- -f, --fd-thresh, --fd_thresh
Framewise displacement threshold for censoring. Any volumes with an FD value greater than the threshold will be removed from the denoised BOLD data. A threshold of <=0 will disable censoring completely.
Default:
auto
- --min-time, --min_time
Post-scrubbing threshold to apply to individual runs in the dataset. This threshold determines the minimum amount of time, in seconds, needed to post-process a given run, once high-motion outlier volumes are removed. This will have no impact if scrubbing is disabled (i.e., if the FD threshold is zero or negative). This parameter can be disabled by providing a zero or a negative value.
The default is 240 (4 minutes).
Default:
240
- --output-type
Possible choices: auto, censored, interpolated
The type of output to generate. If ‘auto’, the output type will be inferred from the processing mode. If ‘censored’, the BOLD outputs (dense and parcellated time series) will be censored. If ‘interpolated’, the BOLD outputs (dense and parcellated time series) will be interpolated.
Default:
'auto'
Data filtering parameters
These parameters determine whether a bandpass filter will be applied to the BOLD data, after the censoring, denoising, and interpolation steps of the pipeline, but before recensoring.
- --disable-bandpass-filter, --disable_bandpass_filter
Disable bandpass filtering. If bandpass filtering is disabled, then ALFF derivatives will not be calculated.
Default:
True
- --lower-bpf, --lower_bpf
Lower cut-off frequency (Hz) for the Butterworth bandpass filter to be applied to the denoised BOLD data. Set to 0.0 or negative to disable high-pass filtering. See Satterthwaite et al. (2013).
Default:
0.01
- --upper-bpf, --upper_bpf
Upper cut-off frequency (Hz) for the Butterworth bandpass filter to be applied to the denoised BOLD data. Set to 0.0 or negative to disable low-pass filtering. See Satterthwaite et al. (2013).
Default:
0.08
- --bpf-order, --bpf_order
Number of filter coefficients for the Butterworth bandpass filter.
Default:
2
Parcellation options
- --atlases
Selection of atlases to apply to the data. All of XCP-D’s built-in atlases are used by default.
Default:
['4S1056Parcels', '4S156Parcels', '4S256Parcels', '4S356Parcels', '4S456Parcels', '4S556Parcels', '4S656Parcels', '4S756Parcels', '4S856Parcels', '4S956Parcels', 'Glasser', 'Gordon', 'HCP', 'MIDB', 'MyersLabonte', 'Tian']
- --skip-parcellation, --skip_parcellation
Skip parcellation and correlation steps.
- --min-coverage, --min_coverage
Coverage threshold to apply to parcels in each atlas. Any parcels with lower coverage than the threshold will be replaced with NaNs. Must be a value between zero and one, indicating proportion of the parcel.
Default:
auto
abcd/hbcd mode options
- --create-matrices, --create_matrices
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.
This option is only allowed for the “abcd” and “hbcd” modes.
- --random-seed, --random_seed
Initialize the random seed for the ‘–create-matrices’ option.
- --linc-qc, --linc_qc
Possible choices: y, n
Run LINC QC.
This will calculate QC metrics from the LINC pipeline.
Default:
'auto'
linc mode options
- --abcc-qc, --abcc_qc
Possible choices: y, n
Run ABCC QC.
This will create the DCAN executive summary, including a brainsprite visualization of the anatomical tissue segmentation, and an HDF5 file containing motion levels at different thresholds.
Default:
'auto'
Other options
- --report-output-level
Possible choices: root, subject, session
Where should the html reports be written? “root” will write them to the –output-dir. “subject” will write them into each subject’s directory. “session” will write them into each session’s directory. The default is “auto”, which will default to “root” for “none” mode, “session” for “abcd” and “hbcd” modes, and “root” for “linc” and “nichart” modes.
Default:
'auto'
- --aggregate-session-reports
Maximum number of sessions aggregated in one subject’s visual report. If exceeded, visual reports are split by session.
Default:
4
- -w, --work-dir, --work_dir
Path to working directory, where intermediate results should be stored.
Default:
working_dir
- --clean-workdir, --clean_workdir
Clears working directory of contents. Use of this flag is not recommended when running concurrent processes of XCP-D.
Default:
False
- --resource-monitor, --resource_monitor
Enable Nipype’s resource monitoring to keep track of memory and CPU usage.
Default:
False
- --config-file, --config_file
Use pre-generated configuration file. Values in file will be overridden by command-line arguments.
- --write-graph
Write workflow graph.
Default:
False
- --stop-on-first-crash
Force stopping on first crash, even if a work directory was specified.
Default:
False
- --notrack
Opt out of sending tracking information.
Default:
False
- --debug
Possible choices: pdb, all
Debug mode(s) to enable. ‘all’ is alias for all available modes.
- --fs-license-file
Path to FreeSurfer license key file. Get it (for free) by registering at https://surfer.nmr.mgh.harvard.edu/registration.html. This is not currently required, but may be in the future.
- --md-only-boilerplate
Skip generation of HTML and LaTeX formatted citation with pandoc
Default:
False
- --boilerplate-only, --boilerplate_only
generate boilerplate only
Default:
False
- --reports-only
only generate reports, don’t run workflows. This will only rerun report aggregation, not reportlet generation for specific nodes.
Default:
False
Experimental options
- --warp-surfaces-native2std, --warp_surfaces_native2std
Possible choices: y, n
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. Additionally, the fsLR-space surfaces will be warped such that they can be overlaid on the MNI152NLin6Asym template. These surface files are primarily used for visual quality assessment.IMPORTANT: This parameter can only be run if the –file-format flag is set to cifti.
Default:
'auto'
Minimal Inputs
The minimal inputs required to run XCP-D are:
A native-space preprocessed T1w or T2w image.
A preprocessed BOLD image in MNI152NLin6Asym, MNI152NLin2009cAsym, MNIInfant (nibabies derivatives), or fsLR (CIFTI processing) space.
The functional brain mask and boldref image in the same space as the preprocessed BOLD data.
The confounds associated with the BOLD image, along with the associated JSON file.
The anatomical brain mask in the same space as the preprocessed BOLD data.
The transform from the native anatomical space to the standard space the BOLD image is in, and its inverse.
Surface files, such as the pial and white matter GIFTI files, may be required depending on the settings you use.
Below are an example lists of inputs.
Warning
Please note that the filenames may differ based on the pipeline, or even version of the pipeline, used for preprocessing.
The specific files required by XCP-D may also vary slightly depending on the settings you use.
For NIfTI processing:
dataset_description.json
sub-x/
anat/
sub-x_desc-preproc_T1w.nii.gz # Can be T1w or T2w. Note that this is native anatomical space.
sub-x_desc-preproc_T1w.json
sub-x_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
sub-x_space-MNI152NLin6Asym_desc-brain_mask.json
sub-x_from-MNI152NLin6Asym_to-T1w_mode-image_xfm.h5
sub-x_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
func/
sub-x_task-rest_desc-confounds_timeseries.tsv
sub-x_task-rest_desc-confounds_timeseries.json
sub-x_task-rest_space-MNI152NLin6Asym_desc-preproc_bold.nii.gz
sub-x_task-rest_space-MNI152NLin6Asym_desc-preproc_bold.json
sub-x_task-rest_space-MNI152NLin6Asym_boldref.nii.gz
sub-x_task-rest_space-MNI152NLin6Asym_boldref.json
sub-x_task-rest_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
sub-x_task-rest_space-MNI152NLin6Asym_desc-brain_mask.json
For CIFTI processing:
dataset_description.json
sub-x/
anat/
sub-x_desc-preproc_T1w.nii.gz # Can be T1w or T2w. Note that this is native anatomical space.
sub-x_desc-preproc_T1w.json
sub-x_space-MNI152NLin6Asym_desc-brain_mask.nii.gz
sub-x_space-MNI152NLin6Asym_desc-brain_mask.json
sub-x_from-MNI152NLin6Asym_to-T1w_mode-image_xfm.h5
sub-x_from-T1w_to-MNI152NLin6Asym_mode-image_xfm.h5
func/
sub-x_task-rest_desc-confounds_timeseries.tsv
sub-x_task-rest_desc-confounds_timeseries.json
sub-x_task-rest_space-fsLR_den-91k_bold.dtseries.nii
sub-x_task-rest_space-fsLR_den-91k_bold.json
sub-x_task-rest_space-MNI152NLin6Asym_desc-preproc_bold.nii.gz # Needed for QC figures
sub-x_task-rest_space-MNI152NLin6Asym_boldref.nii.gz
sub-x_task-rest_space-MNI152NLin6Asym_boldref.json
Surface files:
dataset_description.json
sub-x/
anat/
# Mesh files in fsnative space, to be warped to fsLR space
sub-x_hemi-L_pial.surf.gii
sub-x_hemi-R_pial.surf.gii
sub-x_hemi-L_white.surf.gii
sub-x_hemi-R_white.surf.gii
# Sphere files for registration
sub-x_hemi-L_space-fsaverage_desc-reg_sphere.surf.gii
sub-x_hemi-R_space-fsaverage_desc-reg_sphere.surf.gii
# Morphometry files in fsLR space, to be parcellated
sub-x_hemi-L_space-fsLR_den-91k_curv.dscalar.nii
sub-x_hemi-L_space-fsLR_den-91k_sulc.dscalar.nii
sub-x_hemi-L_space-fsLR_den-91k_thickness.dscalar.nii
sub-x_hemi-L_space-fsLR_den-91k_myelinw.dscalar.nii
sub-x_hemi-L_space-fsLR_den-91k_desc-smoothed_myelinw.dscalar.nii
Filtering Inputs with BIDS Filter Files
XCP-D allows users to choose which preprocessed files will be post-processed with the
--bids-filter-file
parameter.
This argument must point to a JSON file, containing filters that will be fed into PyBIDS.
The keys in this JSON file are unique to XCP-D.
They are our internal terms for different inputs that will be selected from the preprocessed
dataset.
The full list of keys can be found in the file xcp_d/data/io_spec.yaml
.
"bold"
determines which preprocessed BOLD files will be chosen.
You can set a number of entities here, including “session”, “task”, “space”, “resolution”, and
“density”.
We recommend NOT setting the datatype, suffix, or file extension in the filter file.
Warning
We do not recommend applying additional filters to any of the following fields.
We have documented them here, for edge cases where they might be useful,
but the only field that most users should filter is "bold"
.
"t1w"
selects a native T1w-space, preprocessed T1w file.
"t2w"
selects a native T1w-space, preprocessed T2w file.
If a T1w file is not available, this file will be in T2w space.
"anat_brainmask"
selects an anatomically-derived brain mask in the same space as the BOLD data.
This file is used (1) to estimate head radius for FD calculation (after warping to native space)
and (2) to calculate coregistration quality metrics.
"anat_to_template_xfm"
selects a transform from T1w (or T2w, if no T1w image is available)
space to standard space.
The standard space that will be used depends on the "bold"
files that are selected.
"template_to_anat_xfm"
selects a transform from standard space to T1w/T2w space.
Again, the standard space is determined based on other files.
There are additional keys that control how mesh and morphometry files are selected.
Please refer to io_spec.yaml
for more information on them.
atlas
selects atlases for parcellation.
This is primarily useful for specifying spaces or resolutions.
This field is not reflected in the io_spec.yaml
file.
Example bids-filter-file
In this example file, we only run XCP-D on resting-state preprocessed BOLD runs from session “01”.
{
"bold": {
"session": ["01"],
"task": ["rest"]
}
}
Running XCP-D via containers
Apptainer
If you are computing on an HPC, we recommend using Apptainer. See Container Technologies for installation instructions.
Once a user specifies the container options and the image to be run, the command line options are the same as the bare-metal installation.
apptainer run --cleanenv xcp_d-<version>.simg \ # container args
/path/to/fmriprep_dir \ #xcpd args
/path/to/output_dir \
participant \ # analysis_level
--mode <mode> \ # required
--participant-label <label> # optional
By default, Apptainer will mount (make accessible) your current working directory inside the container.
If you need to access files from other locations on your system, you’ll need to explicitly bind those
directories using the -B
flag. For example:
apptainer run -B /home/user/data \ # Mount data directory
--cleanenv xcp_d-<version>.simg \
/home/user/data/fmriprep \
/home/user/data/xcpd_output \
participant \
--mode <mode>
Docker
If you are running XCP-D locally, we recommend Docker. See Container Technologies for installation instructions.
In order to run Docker smoothly, it is best to prevent permissions issues associated with the root file system. Running Docker as user on the host will ensure the ownership of files written during the container execution.
A Docker container can be created using the following command:
docker run --rm -it \ # docker args
-v /home/user/data/fmriprep \
-v /home/user/data/wkdir \
-v /home/user/data/xcpd_output \
pennlinc/xcp_d:<version> \
/home/user/data/fmriprep \ #xcpd args
/home/user/data/xcpd_output \
participant \ # analysis_level
--mode <mode> \ # required
--participant-label <label> # optional
Custom Confounds
If you would like to denoise your data with confounds that are not included in the built-in confound strategies, you can create your own. Please see The confound configuration file format for more info on the configuration file format.
If you have a set of custom confounds that you would like to use, you need to organize them into a
BIDS dataset.
The dataset should only require the actual confound files, preferably with associated sidecar
JSONs, and a dataset_description.json
file.
Using the same filenames as the fMRIPrep confound files is an easy way to organize this dataset.
Including Signal Regressors
Warning
Signal regressors are not currently supported in combination with voxel-wise regressors.
Warning
Please be careful when including signal regressors. Most of the time this is probably a bad idea. For example, if you run tedana, only noise components from tedana should be orthogonalized with respect to signal components. You wouldn’t want to orthogonalize other noise signals (e.g., motion parameters) with respect to the signal components from tedana.
Let’s say you have some nuisance regressors that are not necessarily orthogonal to some associated regressors that are ostensibly signal. For example, if you want to denoise your data while still retaining task signal, you could include the predicted task signals in your confounds.
For more information about different types of denoising, see tedana’s documentation, this NeuroStars topic, and/or Pruim et al. (2015).
So how do we implement this in XCP-D?
In order to define regressors that should be treated as signal,
and thus orthogonalize the noise regressors with respect to known signals instead of regressing
them without modification,
you should include those regressors in your custom confounds file,
with column names starting with signal__
(lower-case “signal”, followed by two underscores).
Task Regression
If you want to regress task-related signals out of your data, you can use a custom confound configuration.
Here we document how to include task effects as confounds.
Tip
The basic approach to task regression is to convolve your task regressors with an HRF, then save those regressors to a confounds file.
Warning
This method is still under development.
We recommend using a tool like Nilearn to generate convolved regressors from BIDS events files. See this example.
import json
import os
import numpy as np
import pandas as pd
from nilearn.glm.first_level import make_first_level_design_matrix
N_VOLUMES = 200
TR = 0.8
frame_times = np.arange(N_VOLUMES) * TR
events_df = pd.read_table("sub-X_task-Z_events.tsv")
task_confounds = make_first_level_design_matrix(
frame_times,
events_df,
drift_model=None,
add_regs=None,
hrf_model="spm",
)
# The design matrix will include a constant column, which we should drop
task_confounds = task_confounds.drop(columns="constant")
# Prepare the derivative dataset
os.makedirs("/my/project/directory/custom_confounds/sub-X/func", exist_ok=True)
# Include a dataset_description.json file
with open("/my/project/directory/custom_confounds/dataset_description.json", "w") as fo:
json.dump(
{
"Name": "Custom Confounds",
"BIDSVersion": "1.6.0",
"DatasetType": "derivative"
},
fo,
)
# Assuming that the fMRIPrep confounds file is named
# "sub-X_task-Z_desc-confounds_timeseries.tsv",
# we will name the custom confounds file the same thing, in a separate folder.
task_confounds.to_csv(
"/my/project/directory/custom_confounds/sub-X/func/sub-X_task-Z_desc-confounds_timeseries.tsv",
sep="\t",
index=False,
)
Then, create a confounds config file to include derivatives from custom_confounds
.
Something like this should work:
name: my_custom_confounds
description: |
Nuisance regressors were task regressors convolved with an HRF and motion parameters.
confounds:
motion:
dataset: preprocessed
query:
space: null
cohort: null
res: null
den: null
desc: confounds
extension: .tsv
suffix: timeseries
columns:
- trans_x
- trans_y
- trans_z
- rot_x
- rot_y
- rot_z
task:
dataset: custom
query:
space: null
cohort: null
res: null
den: null
desc: confounds
extension: .tsv
suffix: timeseries
columns: # Assume the task regressors are called "condition1" and "condition2"
- condition1
- condition2
Command Line XCP-D with Custom Confounds
Last, run XCP-D with your custom configuration file and the path to the custom derivatives dataset.
apptainer run -B /home/user/data \
--cleanenv xcpd_<version>.simg \
/home/user/data/path/to/fmriprep_dir \
/home/user/data/path/to/output_dir \
participant \ # analysis_level
--mode <mode> \ # required
--participant-label <label> # optional
--datasets custom=/home/user/data/path/to/custom_confounds \
--nuisance-regressors /home/user/data/path/to/custom_config.yaml
External Atlases
While XCP-D comes with many built-in parcellations, we understand that many users will want to use different ones.
As long as the parcellation is organized in a BIDS-Atlas dataset and is in fsLR-32k space (for CIFTI processing) or MNIInfant, MNI152NLin6Asym, or MNI152NLin2009cAsym space (for NIfTI processing), you can use it with XCP-D.
Warning
BIDS Extension Proposal 38 (Atlas Specification) has not been integrated in BIDS yet, so the organization and naming for atlas datasets may change in the future.
We have attempted to follow the proposed structure in XCP-D, but we cannot guarantee that this will not change.
Tip
The main elements from the BIDS-Atlas dataset that XCP-D uses are:
There must be a dataset_description.json file with DatasetType set to “atlas”.
The atlas metadata files must have the same entities as the atlas image files, as PyBIDS does not support the inheritance principle when querying BIDS-Atlas datasets (yet).
There must be a TSV file for the atlas, with “index” and “label” columns.
To do this, use the --datasets
and --atlases
parameters.
The --datasets
parameter should point to the directory containing the BIDS-Atlas dataset,
and the --atlases
parameter should include the names of the atlases in the dataset to use.
For example, consider a scenario where you have two BIDS-Atlas datasets, one containing all of the
Schaefer 2018 resolutions and one containing the AAL atlas.
These datasets are in /data/atlases/schaefer
and /data/atlases/aal
, respectively.
The file structure for these two datasets might look like this:
/data/atlases/
schaefer/
dataset_description.json
atlas-Schaefer100/
atlas-Schaefer100_dseg.tsv
atlas-Schaefer100_space-fsLR_den-32k_dseg.dlabel.nii
atlas-Schaefer100_space-fsLR_den-32k_dseg.json
atlas-Schaefer200/
atlas-Schaefer200_dseg.tsv
atlas-Schaefer200_space-fsLR_den-32k_dseg.dlabel.nii
atlas-Schaefer200_space-fsLR_den-32k_dseg.json
...
atlas-Schaefer1000/
atlas-Schaefer1000_dseg.tsv
atlas-Schaefer1000_space-fsLR_den-32k_dseg.dlabel.nii
atlas-Schaefer1000_space-fsLR_den-32k_dseg.json
aal/
dataset_description.json
atlas-AAL/
atlas-AAL_dseg.tsv
atlas-AAL_space-fsLR_den-32k_dseg.dlabel.nii
atlas-AAL_space-fsLR_den-32k_dseg.json
You may want to only apply the Schaefer100 atlas from the schaefer
dataset and the AAL atlas
from the aal
dataset, along with one of XCP-D’s built-in atlases (4S156Parcels
).
Here’s what the XCP-D call might look like:
apptainer run -B /home/user/data \
--cleanenv xcpd_<version>.simg \
/home/user/data/path/to/fmriprep_dir \
/home/user/data/path/to/output_dir \
participant \ # analysis_level
--mode <mode> \ # required
--datasets schaefer=/home/user/data/path/to/schaefer_atlas aal==/home/user/data/path/to/aal_atlas \
--atlases Schaefer100 AAL 4S156Parcels
XCP-D will search for atlas-Schaefer100
, atlas-AAL
, and atlas-4S156Parcels
across the
schaefer
, aal
, and XCP-D’s built-in atlas datasets.
If the atlases are found, then they will be used for parcellation.
Important
Atlas names must be unique across BIDS-Atlas datasets. If two atlases have the same name, XCP-D will raise an error.
Advanced Applications
XCP-D can be used in conjunction with other tools, such as tedana
and phys2denoise
.
We have attempted to document these applications with working code in
PennLINC/xcp_d-examples.
If there is an application you think would be useful to document, please open an issue in that
repository.
Preprocessing Requirements for XCP-D
XCP-D is designed to ingest data from a variety of different preprocessing pipelines. However, each supported pipeline must be explicitly supported within XCP-D in order for the workflow to select the correct files.
Additionally, XCP-D may require files that are only created with specific settings in the preprocessing pipelines.
fMRIPrep/Nibabies
In order to work on fMRIPrep or Nibabies derivatives, XCP-D needs derivatives in one of a few template spaces, including “MNI152NLin6Asym”, “MNI152NLin2009cAsym”, “MNIInfant”, and “fsLR”. We may add support for additional templates in the future, but currently you must have at least one of these among your output spaces. XCP-D does not have any specific requirements for resolution of volumetric derivatives, but we do require fsLR-space CIFTIs be outputted in 91k density.
Troubleshooting
Logs and crashfiles are outputted into the <output dir>/xcp_d/sub-<participant_label>/log
directory.
Information on how to customize and understand these files can be found on the
nipype debugging
page.
Support and communication
All bugs, concerns and enhancement requests for this software can be submitted here: https://github.com/PennLINC/xcp_d/issues.
If you have a question about using XCP-D, please create a new topic on NeuroStars with the “Software Support” category and the “xcp_d” tag. The XCP-D developers follow NeuroStars, and will be able to answer your question there.