Outputs of XCP-D

The XCP-D outputs are written out in BIDS format and consist of three main parts.

A note on BIDS compliance

XCP-D attempts to follow the BIDS specification as closely as possible. However, many XCP-D derivatives are not currently covered by the specification. In those instances, we attempt to follow recommendations from existing BIDS Extension Proposals (BEPs), which are in-progress proposals to add new features to BIDS. However, we do not guarantee compliance with any BEP, as they are not yet part of the official BIDS specification.

Four BEPs that are of particular use in XCP-D are BEP011: Structural preprocessing derivatives, BEP012: Functional preprocessing derivatives, BEP017: Relationship & connectivity matrix data schema, and BEP038: Atlas Specification.

In cases where a derivative type is not covered by an existing BEP, we have simply attempted to follow the general principles of BIDS.

If you discover a problem with the BIDS compliance of XCP-D’s derivatives, please open an issue in the XCP-D repository.

Summary Reports

There are two summary reports - a Nipreps-style participant summary and an executive summary per session. The executive summary is based on the DCAN lab’s ExecutiveSummary tool.

xcp_d/
   sub-<label>.html
   sub-<label>[_ses-<label>]_executive_summary.html

Parcellations and Atlases

XCP-D produces parcellated anatomical and functional outputs using a series of atlases. The individual outputs are documented in the relevant sections of this document, with this section describing the atlases themselves.

The atlases currently used in XCP-D can be separated into three groups: subcortical, cortical, and combined cortical/subcortical. The two subcortical atlases are the Tian atlas [1] and the CIFTI subcortical parcellation [2]. The cortical atlases are the Glasser [3] and the Gordon [4]. The combined cortical/subcortical atlases are 10 different resolutions of the 4S (Schaefer Supplemented with Subcortical Structures) atlas.

The 4S atlas combines the Schaefer 2018 cortical atlas (version v0143) [5] at 10 different resolutions (100, 200, 300, 400, 500, 600, 700, 800, 900, and 1000 parcels) with the CIT168 subcortical atlas [6], the Diedrichson cerebellar atlas [7], the HCP thalamic atlas [8], and the amygdala and hippocampus parcels from the HCP CIFTI subcortical parcellation [2]. The 4S atlas is used in the same manner across three PennLINC BIDS Apps: XCP-D, QSIPrep, and ASLPrep, to produce synchronized outputs across modalities. For more information about the 4S atlas, please see https://github.com/PennLINC/AtlasPack.

Tip

You can choose to only use a subset of the available atlases by using the --atlases parameter.

Alternatively, if you want to skip the parcellation step completely, you can use the --skip-parcellation parameter.

Atlases are written out to the atlases subfolder, following BEP038.

xcp_d/
   atlases/
      dataset_description.json
      atlas-<label>/
         atlas-<label>_dseg.json
         atlas-<label>_dseg.tsv

         # NIfTI
         atlas-<label>_space-<label>_dseg.nii.gz

         # CIFTI
         atlas-<label>_space-<label>_dseg.dlabel.nii

Anatomical Outputs

Anatomical outputs consist of anatomical preprocessed T1w/T2w and segmentation images in MNI space.

xcp_d/
   sub-<label>/[ses-<label>/]
      anat/
         <source_entities>_space-MNI152NLin6Asym_desc-preproc_T1w.nii.gz
         <source_entities>_space-MNI152NLin6Asym_desc-preproc_T2w.nii.gz
         <source_entities>_space-MNI152NLin6Asym_dseg.nii.gz

Surface mesh files

If the --warp-surfaces-native2std option is selected, and reconstructed surfaces are available in the preprocessed dataset, then these surfaces will be warped to fsLR space at 32k density.

xcp_d/
   sub-<label>/[ses-<label>/]
      anat/
         <source_entities>_space-fsLR_den-32k_hemi-<L|R>_desc-hcp_midthickness.surf.gii
         <source_entities>_space-fsLR_den-32k_hemi-<L|R>_desc-hcp_inflated.surf.gii
         <source_entities>_space-fsLR_den-32k_hemi-<L|R>_desc-hcp_vinflated.surf.gii
         <source_entities>_space-fsLR_den-32k_hemi-<L|R>_pial.surf.gii
         <source_entities>_space-fsLR_den-32k_hemi-<L|R>_smoothwm.surf.gii

Surface morphometric files

XCP-D will also pass along several morphometric files from the preprocessing derivatives, as long as the files are already in fsLR space at 32k density.

xcp_d/
   sub-<label>/[ses-<label>/]
      anat/
         <source_entities>_space-fsLR_den-32k_hemi-<L|R>_sulc.shape.gii
         <source_entities>_space-fsLR_den-32k_hemi-<L|R>_curv.shape.gii
         <source_entities>_space-fsLR_den-32k_hemi-<L|R>_thickness.shape.gii

XCP-D will additionally parcellate each of these files, when they are present, using each of the atlases it uses to parcellate the functional outputs.

xcp_d/
   sub-<label>/[ses-<label>/]
      anat/
         <source_entities>_space-fsLR_seg-<label>_den-32k_stat-mean_desc-curv_morph.tsv
         <source_entities>_space-fsLR_seg-<label>_den-32k_stat-mean_desc-sulc_morph.tsv
         <source_entities>_space-fsLR_seg-<label>_den-32k_stat-mean_desc-thickness_morph.tsv

Functional Outputs

Functional outputs consist of processed/denoised BOLD data, timeseries, functional connectivity matrices, and resting-state derivatives.

Important

Prior to version 0.4.0, the denoised data outputted by XCP-D was interpolated, meaning that high-motion volumes were replaced with interpolated data prior to temporal filtering. This was a bug. From 0.4.0 on, we have started to only write out the censored version of the denoised data, with high-motion volumes completely removed. This extends to the parcellated time series and correlation matrices as well.

Denoised or residual BOLD data

Important

Smoothed denoised BOLD files will only be generated if smoothing is enabled with the --smoothing parameter.

xcp_d/
   sub-<label>/[ses-<label>/]
      func/
         # NIfTI
         <source_entities>_space-<label>_desc-denoised_bold.nii.gz
         <source_entities>_space-<label>_desc-denoisedSmoothed_bold.nii.gz
         <source_entities>_space-<label>_desc-interpolated_bold.nii.gz

         # CIFTI
         <source_entities>_space-fsLR_den-91k_desc-denoised_bold.dtseries.nii
         <source_entities>_space-fsLR_den-91k_desc-denoisedSmoothed_bold.dtseries.nii
         <source_entities>_space-fsLR_den-91k_desc-interpolated_bold.dtseries.nii

Important

The interpolated denoised BOLD files (desc-interpolated) should NOT be used for analyses. These files are only generated if --skip-dcan-qc is not used, and primarily exist for compatibility with DCAN-specific analysis tools.

The sidecar json files contains parameters of the data and processing steps. The Sources field contains BIDS URIs pointing to the files used to create the derivative. The associated DatasetLinks are defined in the dataset_description.json.

{
   "EchoTime": 0.0424,
   "EffectiveEchoSpacing": 0.000639989,
   "FlipAngle": 51,
   "Manufacturer": "Siemens",
   "ManufacturersModelName": "Skyra",
   "NuisanceParameters": "gsr_only",
   "PhaseEncodingDirection": "j-",
   "RepetitionTime": 3,
   "SoftwareFilters": {
      "Bandpass filter": {
         "Filter order": 2,
         "High-pass cutoff (Hz)": 0.01,
         "Low-pass cutoff (Hz)": 0.08
      }
   },
   "Sources": [
      "bids:preprocessed:sub-0000001/ses-01/func/sub-0000001_ses-01_task-rest_space-MNI152NLin6Asym_desc-preproc_bold.nii.gz",
      "bids:xcp_d:sub-0000001/ses-01/func/sub-0000001_ses-01_task-rest_outliers.tsv",
      "bids:xcp_d:sub-0000001/ses-01/func/sub-0000001_ses-01_task-rest_desc-preproc_design.tsv"
   ],
   "TaskName": "resting state"
}

Functional timeseries and connectivity matrices

This includes the atlases used to extract the timeseries.

Important

Correlation matrices with the desc-<INT>volumes entity are produced if the --exact-time parameter is used.

xcp_d/
   sub-<label>/[ses-<label>/]
      func/
         # NIfTI
         <source_entities>_space-<label>_seg-<label>_stat-coverage_bold.tsv
         <source_entities>_space-<label>_seg-<label>_stat-mean_timeseries.tsv
         <source_entities>_space-<label>_seg-<label>_stat-pearsoncorrelation_relmat.tsv
         <source_entities>_space-<label>_seg-<label>_stat-pearsoncorrelation_desc-<INT>volumes_relmat.tsv

         # CIFTI
         <source_entities>_space-fsLR_seg-<label>_den-91k_stat-coverage_bold.tsv
         <source_entities>_space-fsLR_seg-<label>_den-91k_stat-coverage_boldmap.pscalar.nii
         <source_entities>_space-fsLR_seg-<label>_den-91k_stat-mean_timeseries.tsv
         <source_entities>_space-fsLR_seg-<label>_den-91k_stat-mean_timeseries.ptseries.nii
         <source_entities>_space-fsLR_seg-<label>_den-91k_stat-pearsoncorrelation_relmat.tsv
         <source_entities>_space-fsLR_seg-<label>_den-91k_stat-pearsoncorrelation_boldmap.pconn.nii
         <source_entities>_space-fsLR_seg-<label>_den-91k_stat-pearsoncorrelation_desc-<INT>volumes_relmat.tsv

Resting-state metric derivatives (ReHo and ALFF)

XCP-D calculates both regional homogeneity (ReHo) and amplitude of low-frequency fluctuations (ALFF), depending on the parameters.

Important

Smoothed ALFF will only be generated if smoothing is enabled with the --smoothing parameter.

Important

ALFF will not be generated if bandpass filtering is disabled with the --disable-bandpass-filtering parameter.

XCP-D will also parcellate the ReHo and ALFF maps with each of the atlases used for the BOLD data.

xcp_d/
   sub-<label>/[ses-<label>/]
      func/
         # NIfTI
         <source_entities>_space-<label>_stat-reho_boldmap.nii.gz
         <source_entities>_space-<label>_stat-alff_boldmap.nii.gz
         <source_entities>_space-<label>_stat-alff_desc-smooth_boldmap.nii.gz
         <source_entities>_space-<label>_seg-<label>_stat-alff_bold.tsv
         <source_entities>_space-<label>_seg-<label>_stat-reho_bold.tsv

         # CIFTI
         <source_entities>_space-fsLR_den-91k_stat-reho_boldmap.dscalar.nii
         <source_entities>_space-fsLR_den-91k_stat-alff_boldmap.dscalar.nii
         <source_entities>_space-fsLR_den-91k_stat-alff_desc-smooth_boldmap.dscalar.nii
         <source_entities>_space-fsLR_seg-<label>_stat-alff_bold.tsv
         <source_entities>_space-fsLR_seg-<label>_stat-reho_bold.tsv

Other outputs include quality control, framewise displacement, and confounds files

xcp_d/
   desc-linc_qc.json

   sub-<label>/[ses-<label>/]
      func/
         <source_entities>[_desc-filtered]_motion.tsv
         <source_entities>_outliers.tsv
         <source_entities>_design.tsv
         <source_entities>_space-<label>_desc-linc_qc.tsv

[desc-filtered]_motion.tsv is a tab-delimited file with seven columns: one for each of the six filtered motion parameters, as well as “framewise_displacement”. If no motion filtering was applied, this file will not have the desc-filtered entity. This file includes the high-motion volumes that are removed in most other derivatives.

outliers.tsv is a tab-delimited file with one column: “framewise_displacement”. The “framewise_displacement” column contains zeros for low-motion volumes, and ones for high-motion outliers. This file includes the high-motion volumes that are removed in most other derivatives.

design.tsv is a tab-delimited file with one column for each nuisance regressor, including one-hot encoded regressors indicating each of the high-motion outlier volumes. This file includes the high-motion volumes that are removed in most other derivatives.

Important

Please note that the outlier columns are somewhat misleading, as volumes are removed by censoring, rather than regression.

DCAN style scrubbing file (if `--skip-dcan-qc` is not used)

This file is in hdf5 format (readable by h5py), and contains binary scrubbing masks from 0.0 to 1mm FD in 0.01 steps.

xcp_d/
   sub-<label>/[ses-<label>/]
      func/
         <source_entities>_desc-dcan_qc.hdf5

These files have the following keys:

FD_threshold: a number >= 0 that represents the FD threshold used to calculate the metrics in this list
frame_removal: a binary vector/array the same length as the number of frames in the concatenated time series, indicates whether a frame is removed (1) or not (0)
format_string (legacy): a string that denotes how the frames were excluded – uses a notation devised by Avi Snyder
total_frame_count: a whole number that represents the total number of frames in the concatenated series
remaining_frame_count: a whole number that represents the number of remaining frames in the concatenated series
remaining_seconds: a whole number that represents the amount of time remaining after thresholding
remaining_frame_mean_FD: a number >= 0 that represents the mean FD of the remaining frames

Outputs of XCP-D

Summary Reports

Parcellations and Atlases

Anatomical Outputs

Surface mesh files

Surface morphometric files

Functional Outputs

Denoised or residual BOLD data

Functional timeseries and connectivity matrices

Resting-state metric derivatives (ReHo and ALFF)

Other outputs include quality control, framewise displacement, and confounds files

DCAN style scrubbing file (if --skip-dcan-qc is not used)

DCAN style scrubbing file (if `--skip-dcan-qc` is not used)