XCP Imaging Pipeline

Warning

xcpEngine only support fmriprep outputs with MNI152NLin2009cAsym template

The XCP imaging pipeline (XCP system) is a free, open-source software package for processing of multimodal neuroimages. The XCP system uses a modular design to deploy analytic routines from leading MRI analysis platforms, including FSL, AFNI, and ANTs.

The XCP system is designed to run in the Linux bash shell or from a Docker or Singularity image. We strongly recommend using Docker or Singularity. Users provide XCP Engine with the output from FMRIPREP and specify parameters for the analysis that they wish to perform. XCP Engine parses the user-provided parameters to build and run a processing pipeline. The XCP system supports a number of pipeline modalities, including functional connectivity, structural processing, and task fMRI.

Useful Features

XCP Engine provides tools to take FMRIPREP output and perform the next steps required for many functional connectivity and structural analyses. FMRIPREP is required for initial preprocessing of fMRI data; XCP performs denoising and computes additional derivatives used for analyses. For structural processing, either FMRIPREP or the dedicated struct module in XCP can be used.

Neuroimage processing

Raw to processed time series

Neuroimage processing refers collectively to the set of strategies used to convert the “raw” images collected from the scanner into appropriate inputs to group-level statistical analyses. The results of any group-level neuroimaging analysis will be sensitive to the combination of strategies used to process the subject-level images. Reproducibility of processing strategies is therefore critical.

MRI time series collected from the scanner are typically noisy. Processing mitigates the effect of artefact and moves all subject-specific images into a common atlas space to facilitate direct voxelwise comparison.

It encompasses denoising, filtering, registration, and production of any subject-level derivative maps (for instance, seed-based connectivity maps or task contrasts). Processing includes production of summary measures on both a voxelwise and ROI-wise basis. Notably, processing in XCP does not include group-level statistical analysis.

Processing pipelines

The XCP system was designed with the importance of scientific reproducibility in mind. Often, research groups process neuroimages using a dedicated, standalone “pipeline” for each image modality. For instance, task activation, perfusion, and functional connectivity analyses might each be processed by a separate script.

However, this approach can easily lead to inconsistencies in output directory conventions, difficulty tracking pipeline versions, and limited flexibility in updating pipelines, all of which ultimately combine to compound reproducibility challenges. Often, many common routines are deployed across multiple MRI modalities, and it is in the interest of the investigator to minimize redundancy and maximize reproducibility.

The modular, atomic design of the XCP system allows for streamlined reproduction and recombination of frequently used image processing strategies across multiple pipelines and modalities.

Features

The XCP system aims to provide a multimodal library of common processing routines that will improve scientific reproducibility. Features include:

• Compatability with FMRIPREP
• Standardized output directory structure and naming conventions
• Systematized quality control variables computed and collated for each analysis (for easy identification of motion and registration outliers)
• Region-wise quantification of any voxelwise derivative map for any number of parcellation schemes or regions of interest
• Easy addition of new regions of interest, node systems, or parcellation schemes
• Analyses either in standard/atlas or subject/native space

Standardized directory structure

Contents

Overview

Functional connectivity can be a powerful approach to studying the brain, but must be used carefully. Numerous artifacts can affect the quality of your results. Our approach is to first preprocess fMRI data using FMRIPREP to quantify head motion and other confounds, then to use these estimates in xcpEngine to denoise the fMRI signal and estimate functional connectivity.

To process your data from scanner to analysis, the steps are generally

1. Convert data from DICOMS to a BIDS-compliant format
2. Run FMRIPREP on the BIDS-compliant data set (fmriprep)
3. Run xcpEngine to estimate some of many possible measures

Steps 1 and 2 are well-documented and have active developers who can help you through these steps; this documentation will help you get started with step 3 (xcpEngine).

Installation

The easiest way to use xcpEngine on your laptop or personal computer is to install Docker and the xcpEngine python wrapper. Ensure that Docker has access to at least 8GB of memory. If you are on an HPC system where you cannot run Docker, you can use Singularity. Be sure one of these is installed and then install the xcpEngine container wrapper using Python: Then install the wrapper using:

pip install xcpengine-container

Once this completes you can run xcpEngine without explicitly running Docker:

xcpengine-docker \
  -d /xcpEngine/designs/fc-36p.dsn \
  -c /path/to/cohort.csv \
  -r /path/to/data/directory \
  -i /path/to/workingdir \
  -o /path/to/outputdir

or Singularity:

xcpengine-singularity \
  --image /path/to/xcpEngine.simg \
  -d /xcpEngine/designs/fc-36p.dsn \
  -c /path/to/cohort.csv \
  -r /path/to/data/directory \
  -i /path/to/workingdir \
  -o /path/to/outputdir

Continue reading to learn about the arguments and be sure to use the correct executable

• xcpengine-singularity for Singularity
• xcpengine-docker for Docker

Getting started

Once your data is processed by FMRIPREP you are ready to use xcpEngine. FMRIPREP can write preprocessed data out in multiple spaces. At the moment, xcpEngine only supports volume data, meaning that T1w and MNI152NLin2009cAsym are the only usable options for FMRIPREP’s --output-spaces flag. Either is a viable starting point. Choosing MNI152NLin2009cAsym is the most straightforward route, but T1w adds the possibility of using a custom template for normalization. Here we’ll assume you want to process data that has already been resampled in MNI space (i.e. --output-spaces MNI152NLin2009cAsym was part of your FMRIPREP call) and you’re running on your laptop with Docker installed.

Step 1: Create a cohort file

xcpEngine reads images and metadata from a user-provided csv file called a Pipeline cohort file. Briefly, the cohort file should contain subject metadata (without special shell characters) in id columns and paths to images written by FMRIPREP in the img column. In this example use case, the cohort file might be saved as /home/me/cohort.csv and contain:

id0,img
sub-01,sub-01/func/sub-01_task-mixedgamblestask_run-01_space-MNI152NLin2009cAsym_desc-preproc_bold.nii.gz

We recommend making the paths relative to the --output-dir you used for FMRIPREP.

Step 2: Choose/Configure a Pipeline design

Not all functional connectivity pipelines are equally effective at addressing systematic noise and artifacts. Many papers have proposed different denoising strategies, which may vary in effectiveness. xcpEngine has many of the top performing de-noising strategies implemented available as Pipeline design file that can specify the processing stages and calculation of output measures.

A library of pipelines comes pre-packaged with xcpEngine and are described in the accompanying paper. We test these design files before distributing xcpengine and recommend using them as-is. Changes may produce poor-quality results.

These are pre-packaged in the images in /xcpEngine/designs and a full list can be found in the GitHub repository (https://github.com/PennBBL/xcpEngine/tree/master/designs). These designs implement the processing pipelines found in the following table:

Available pipeline designs

Note

The poor-performance pipelines are not included. Also, you will need to adjust the thresholds for rmss for your TR (Temporal Censoring) if you’re using a pre-packaged design file.

Step 3: Process your data

To run your pipeline with Docker simply:

xcpengine-docker \
  -c /home/me/cohort.csv \
  -d /xcpEngine/designs/fc-36p.dsn \
  -i /home/me/work \
  -o /home/me/xcpOutput \
  -r /home/me/fmriprep_outputdir/fmriprep

Very similarly, the command for Singularity is:

xcpengine-singularity \
  --image /home/me/xcpEngine-latest.simg \
  -c /home/me/cohort.csv \
  -d /xcpEngine/designs/fc-36p.dsn \
  -i /home/me/work \
  -o /home/me/xcpOutput \
  -r /home/me/fmriprep_outputdir/fmriprep

Your outputs will be located on your computer in /home/me/xcpOutput and are ready for testing hypotheses!

Pipeline configuration

This page includes links to everything needed to get started with the pipeline system.

The system’s front end, xcpEngine, accepts two primary arguments: a design file and a cohort file.

• The design file parameterizes the processing streams and specifies the Modules that should be run.
• The cohort file is a list of subjects; it defines the inputs to the pipeline.

Pipeline tutorial

0. Before you begin

To get started, first [create a singularity image of xcpEngine:

$ singularity build /data/applications/xcpEngine.simg docker://pennbbl/xcpengine:latest

Next, download an example output from FMRIPREP

Suppose the downloaded data is extracted to ${DATA_ROOT}/fmriprep, where ${DATA_ROOT}` is an existing directory on your system.

1. Running the anatomical pipeline

You need to create a cohort file and a design file to show XCP where your data is and tell it what to do with it. Since there is only a single subject with a single session, write the following content to ${DATA_ROOT}/anat_cohort.csv:

id0,img
sub-1,fmriprep/sub-1/anat/sub-1_T1w_preproc.nii.gz

Then download the antsCT design file into ${DATA_ROOT}/anat-antsct.dsn

Now you’re ready to run the anatomical pipeline! Create an empty directory in your home directory (we’ll use ${HOME} because it is directly mounted by Singularity by default, so do mkdir ${HOME}/data). This will be the bind point for your system’s ${DATA_ROOT} directory and will let singularity access your files. Binding directories is very important and worth understanding well. See the singularity documentation for details.:

singularity run -B ${DATA_ROOT}:${HOME}/data  \
   /data/applications/xcpEngine.simg
   -d ${HOME}/data/anat-antsct.dsn \
   -c ${HOME}/data/anat_cohort.csv  \
   -o ${HOME}/data/xcp_output \
   -t 1 \
   -r ${HOME}/data

This will take up to 2 days, but when it’s done you will have the full output of antsCorticalThickness for this subject! It also provides all the spatial normalization info to map atlases to your BOLD data. See the Anatomical processing streams stream to learn about the available templates and atlases.

2. Running a functional connectivity pipeline

Processing fMRI data for functional connectivity analysis can be done using another design file. Now save one of the nicely-performing pipeline design files as something like ${DATA_ROOT}/fc-36p.dsn. This will take the preprocessed BOLD output from FMRIPREP and prepare it for functional connectivity analysis. Create a new cohort csv that tells XCP where the output from the struc module is located and where the output from FMRIPREP is located. In ${DATA_ROOT}/func_cohort.csv write:

id0,antsct,img
sub-1,xcp_output/sub-1/struc,fmriprep/sub-1/func/sub-1_task-rest_space-T1w_desc-preproc_bold.nii.gz

This specifies that we will process the task-rest scan from this subject. Other runs from the same session would need to be added as additional lines in the cohort file. Run xcpEngine with this new cohort file:

singularity run -B ${DATA_ROOT}:${HOME}/data  \
   /data/applications/xcpEngine.simg
   -d ${HOME}/data/fc-36p.dsn \
   -c ${HOME}/data/func_cohort.csv  \
   -o ${HOME}/data/xcp_output \
   -t 1 \
   -r ${HOME}/data

3. Running a ASL processing pipeline

Processing ASL data for computation of CBF can be done using design files This will take the ASL, M0 (if available) and anatomical directory. ASL processing steps is the same as both anatomical and functional connectivity pipelines, the only different is cohort file and design files.

4. Arguments

While the pipeline is running, let’s break down the call that we made to the XCP Engine. We passed a total of 5 arguments to the pipeline.

• A design file, -d ${HOME}/data/example/anat-antsct.dsn
• A cohort file, -c ${HOME}/data/example/anat_cohort.csv
• An output path, ${HOME}/data/example/xcp_output
• A verbosity level, -t 1
• A reference/relative directory, -r ${HOME}/data

Let’s discuss each of these, and how a user might go about selecting or preparing them.

Design file

The design file parametrizes the image processing stream. The XCP system supports multimodal image processing, including inter alia functional connectivity and volumetric anatomy. How does the system know which of these available processing streams it should execute? It parses the parameters provided by the user in the design file. In our example, we parametrized the stream using the design file anat-antsct.dsn.

Near the top of the file, you will find a variable called pipeline that should look something like: confound,regress,fcon,reho,alff,net,roiquant,seed,norm,qcfc. The pipeline variable tells the XCP system which modules it should run, and what order they should be run in.

Underneath the pipeline variable, you will find code blocks corresponding to each of the modules defined in pipeline. If you’re curious as to what effects any of the variables have, just look up the variables in the documentation for the relevant pipeline Modules.

Cohort file and reference directory

The design file instructs the pipeline as to how inputs should be processed, but the cohort file (also called a subject list) actually informs the pipeline where to find the inputs. Let’s look at the cohort file that we used for this analysis.:

id0,antsct,img
sub-1,xcp_output/sub-1/struc,fmriprep/sub-1/func/sub-1_task-rest_space-T1w_desc-preproc_bold.nii.gz

The cohort file is formatted as a .csv with 3 variables and 1 observation (subject). The first line of the cohort file is a header that defines each of the variables. Subject identifiers are placed in columns starting with id and ending with a non-negative integer. For instance, the first identifier (id0) of the first subject is sub-1. There could be a second identifier (id1) such as ses-01 if needed.

The inputs for each subject are defined in the remaining columns, here antsct and fmriprep. antsct defines the path to the output files of the subject’s processed ANTs Cortical Thickness pipeline (which has already been run as part of the Anatomical processing streams stream in step 1). fmriprep defines the prefix to the main image that this pipeline will analyze. Since this is the cohort for a functional connectivity stream, the main image will be a functional image (in this case, resting state).

If we look at our call to xcpEngine, we can see that we passed it the argument -r ${DATADIR}. This argument instructs xcpEngine to search within ${DATADIR} for cohort paths. This is very useful when using Singularity of Docker, as you can specify the relative bind path as your root while keeping the paths in your cohort file relative to your system’s root.

Now, let’s suppose that we have already processed this subject through the pipeline system, and we acquire data for a new, 2nd subject. Let’s say this new subject has identifier sub-2. To process this new subject, DO NOT CREATE A NEW COHORT FILE. Instead, edit your existing cohort file and add the new subject as a new line at the end of the file. For our example subject, the corresponding line in the cohort file might be something like sub-2,xcp_output/sub-2/struc,fmriprep/sub-2/func/sub-2_task-rest_space-T1w_desc-preproc_bold.nii.gz. Why edit the existing cohort file instead of creating a new one?

• The pipeline will automatically detect that it has already run for the other subject, so it will not waste computational resources on them.
• The pipeline will then collate group-level data across all 8 subjects. If you were to create a new cohort file with just the new subject, group-level data would be pulled from only that subject. Not much of a group, then.

5. Output files

To see what the remaining arguments to xcpEngine do, we will need to look at the pipeline’s output. By now, the pipeline that you launched earlier will hopefully have executed to completion. Let’s take a look at the output directory that you defined using the -o option, ${output_root}. If you list the contents of ${output_root}, you will find 7 subject-level output directories (corresponding to the values of the id0 variable in the cohort file) and one group-level output directory (called group). (You can change the group-level output path using the additional command-line argument -a out_group=<where you want the group-level output>.)

Begin by looking at the subject-level output. Navigate to the first subject’s output directory, ${output_root}/sub-1. In this directory, you will find:

• A subject-specific copy of the design file that you used to run the pipeline, evaluated and modified to correspond to this particular subject (sub-1). (In the XCP system, the process of mapping the template design file to each subject is called localisation, and the script that handles this is called the localiser.)
• An atlas directory (sub-1_atlas). Inside the atlas directory, each parcellation that has been analyzed will exist as a NIfTI file, registered to the subject’s T1w native space.
• A subdirectory corresponding to each pipeline module, as defined in the pipeline variable in the design file. For the most part, these directories store images and files that the pipeline uses to verify successful processing.
  • Take a look inside the fcon subdirectory. Inside, there will be a separate subdirectory for each of the atlases that the pipeline has processed. For instance, in the power264 subdirectory (corresponding to the 264-node Power atlas), there will be files suffixed ts.1D and network.txt.
  • ts.1D contains 264 columns corresponding to each node of the atlas; each column contains a region’s functional time series.
  • network.txt contains the functional connectivity matrix or connectome for the Power atlas, formatted as a vector to remove redundant edges.
• A log directory (sub-1_logs). Inside the log directory, open the file whose name ends with _LOG. This is where all of the pipeline’s image processing commands are logged. The verbosity of this log can be modified using the argument to the -t option). It is recommended that you use a verbosity level of either 1 or 2. For most cases, 1 will be sufficient, but 2 can sometimes provide additional, lower-level diagnostic information.
• A quality file (sub-1_quality.csv). The contents of the quality file will be discussed in detail later, along with group-level outputs.
• A spatial metadata file (sub-1_spaces.json). The pipeline uses this to determine how to move images between different coordinate spaces.
• The final output of processing (sub-1.nii.gz). This is the primary functional image, after all image processing steps (except for smoothing) have been applied to it. If you have smoothing in your design file, smoothed outputs are saved separately as files like sub-1_img_sm${k}.nii.gz inside the norm and regress folders, with ${k} the smoothing kernel size. However, this preprocessed file usually isn’t as useful for analysis as are its derivatives, which brings us to …
• An index of derivative images (sub-1_derivatives.json).
  • Let’s look at the content of the derivatives file now. Run the command shown, and find the entry for reho. This JSON object corresponds to the voxelwise map of this subject’s regional homogeneity (ReHo).
  • The map can be found in the path next to the Map attribute. (You can open this in fslview if you would like.)
  • The Provenance attributes tell us that the map was produced as part of the 6th pipeline module, reho.
  • The Space attribute tells us that the map is in 2mm isotropic MNI space.
  • The Statistic attribute instructs the pipeline’s roiquant module that it should compute the mean value within each parcel of each atlas when converting the voxelwise derivative into an ROI-wise derivative.
  • The Type attribute is used by the pipeline when it makes decisions regarding interpolations and other processing steps.
  • There will actually be a separate index for each coordinate space that has been processed. Note that there’s also a sub-1_derivatives-sub-1_fc.json, which has the same metadata for derivatives in the subject’s native functional space.

Next, let’s examine the group-level output. Navigate to ${output_root}/group. In this directory, you will find:

• The dependency metadata from earlier (dependencies/*pipelineDescription.json). (A new time-stamped metadata file is generated for each run of the pipeline.)
• An error logging directory (error). This should hopefully be empty!
• A log directory (log), analogous to the log directory from the subject level.
• Module-level directories, in this case for the roiquant and qcfc modules.
  • Let’s look at the group-level roiquant output. Like the subject-level net output, there will be a separate subdirectory for each atlas that has been processed.
  • Inside the atlas-level subdirectory, there will be files corresponding to any derivatives that had a non-null value for their Statistic attribute. For instance, the ReHo that we looked at earlier (Statistic: mean) has been quantified regionally and collated across all subjects in the file ending with the suffix RegionalMeanReho.csv. You may wish to examine one of these files; they are ready to be loaded into R or any other environment capable of parsing .csv s.
• A sample quality file for the modality (fc_quality.csv).
  • The qcfc module’s subdirectory will contain reports analogous to those from our .These aren’t really useful for a sample of only 1 subject, so we won’t look at them here.
• Collated subject-level quality indices (n1_quality.csv, not to be confused with the sample-level quality file). If you examine this file, you will find the quality indices that the functional connectivity stream tracks. This file can be used to establish exclusion criteria when building a final sample, for instance on the basis of subject movement or registration quality.
• An audit file (n1_audit.csv). This file indicates whether each pipeline module has successfully run for each subject. 1 indicates successful completion, while 0 indicates a nonstandard exit condition.

6. Anatomy of the pipeline system

Now, let’s pull this information together to consider how the pipeline system operates.

1. The front end, xcpEngine, parses the provided design and cohort files.
2. The localiser uses the information in the cohort file to generate a subject-specific version of the design file for each subject. (The localiser shifts processing from the sample level to the subject level; this is called the localisation or map step.)
3. xcpEngine parses the pipeline variable in the design file to determine what Modules (or processing routines) it should run. Different imaging and data modalities (e.g., anatomical, functional connectivity, task activation) will make use of a different series of modules.
4. xcpEngine submits a copy of each module for each subject in the cohort using that subject’s local design file. Modules run in series, with all subjects running each module in parallel. As it runs, each module writes derivatives and metadata to its output directory.
5. To collate subject-level data or perform group-level analysis, the pipeline uses the delocaliser. Shift of processing from the subject level to the sample level is called delocalisation or a reduce step.

7. Getting help

To get help, the correct channel to use is ` Github <https://github.com/PennBBL/xcpEngine/issues>`_. Open a new issue and describe your problem. If the problem is highly dataset-specific, you can contact the development team by email, but Github is almost always the preferred channel for communicating about pipeline functionality. You can also use the issue system to request new pipeline features or suggest changes.

8. Common Errors

A non-exhaustive list of some common errors, and fixes to try.

• ImportError: bad magic number in 'site' : Try running unset PYTHONPATH immediately prior to running the pipeline.
• Cannot allocate vector of size xx Mb : Try increasing the amount of memory available for running the pipeline.

Pipeline design file

A pipeline design file (.dsn) defines a processing pipeline that is interpreted by the image processing system.

The design file contains:

• A list of the Modules that should be executed;
• The set of parameters that configure each module, as well as their values

Preparing the design file

We strongly recommend you copy and use one of the standard design files that come with XCP Engine. These are regularly tested and usually work.

Examples

A library of preconfigured pipelines is available for each of the following experiments:

• Anatomical (anat)
• Functional connectivity (fc)
• Functional connectivity benchmarking (qcfc)

Specifications (advanced)

Design variables fall into four main categories:

• Analysis variables are input variables accessible at all stages of the pipeline
• The pipeline definition specifies the modules (stages) of the pipeline that are to be run
• Module variables are input variables accessible at only a single stage of the pipeline, and typically configure the behavior of that pipeline stage
• Output variables are produced as the pipeline is run and are accessible at all stages of the pipeline
• A fifth category of variable is not defined in the design file at all. Subject variables take different values for different subjects. See the Pipeline cohort file file documentation for more information about this type of variable.

Analysis variables

Each design file includes a set of variables that are accessible at all stages of the pipeline.:

analysis=accelerator_$(whoami)
design=${XCPEDIR}/designs/fc-36p.dsn
sequence=fc-rest
standard=MNI%1x1x1

Pipeline definitions

The design file includes the pipeline variable, which defines the backbone of the pipeline: a comma-separated sequence of the Modules that together comprise the processing stream.

The standard functional connectivity processing stream is::

pipeline=confound,regress,fcon,reho,alff,net,roiquant,seed,norm,qcfc

The standard benchmarking processing stream is an abbreviated version of the FC stream::

pipeline=confound,regress,fcon,qcfc

The complete anatomical processing stream is::

pipeline=struc,jlf,gmd,cortcon,sulc,roiquant,qcanat

Module configurations

In addition to the overall backbone of the processing stream, the design file includes specifications for each of its constituent modules. As an illustrative example, the specifications of the regress module in a standard functional connectivity stream are provided here::

regress_tmpf[3]=butterworth
regress_hipass[3]=0.01
regress_lopass[3]=0.08
regress_tmpf_order[3]=1
regress_tmpf_pass[3]=2
regress_tmpf_ripple[3]=0.5
regress_tmpf_ripple2[3]=20
regress_dmdt[3]=2
regress_1ddt[3]=1
regress_smo[3]=6
regress_sptf[3]=susan
regress_usan[3]=default
regress_usan_space[3]=
regress_rerun[3]=0
regress_cleanup[3]=1
regress_process[3]=DMT-TMP-REG

Each row defines a different parameter for the regress module (e.g., regress_smo – the smoothing parameter) and assigns it a value (e.g., 6 – 6mm). When the module is executed, it processes its inputs according to the specifications in the pipeline design file.

Output variables

Output variables aren’t defined in the design file that’s provided as an argument at runtime. Instead, they are defined as the pipeline is run and written to a copy of the design file. Output variables are typically accessible by all pipeline stages after they are produced. An illustrative example is provided, again for the coreg module::

# ··· outputs from IMAGE COREGISTRATION MODULE[2] ··· #
struct2seq_img[9001]=accelerator/9001/coreg/9001_struct2seq.nii.gz
struct2seq_mat[9001]=accelerator/9001/coreg/9001_struct2seq.mat
seq2struct[9001]=accelerator/9001/coreg/9001_seq2struct.txt
seq2struct_img[9001]=accelerator/9001/coreg/9001_seq2struct.nii.gz
struct2seq[9001]=accelerator/9001/coreg/9001_struct2seq.txt
seq2struct_mat[9001]=accelerator/9001/coreg/9001_seq2struct.mat
fit[9001]=0.3
sourceReference[9001]=accelerator/9001/prestats/9001_meanIntensityBrain.nii.gz
targetReference[9001]=9001_antsct/ExtractedBrain0N4.nii.gz
altreg2[9001]=mutualinfo
altreg1[9001]=corratio

Each row corresponds to an output defined by the coreg module that can be used by all downstream modules. For example, struct2seq defines an affine transformation from the subject’s high-resolution anatomical space to the subject’s functional space. This transformation can later be used to align white matter and CSF masks to the functional image, enabling tissue-based confound regression.

Pipeline cohort file

A pipeline cohort file defines the experimental sample – the set of subjects that the pipeline should process.

The cohort file is formatted as .csv and contains:

• A column corresponding to each category of input
• A header naming each category of input
• A row corresponding to each subject

Examples

Cohort files can usually be prepared using a simple command-line call. The contents of a cohort file will vary depending upon:

• The imaging modality
• The experimental objective
• Available inputs

Examples for a few common processing cases are provided below.

Subject identifiers

In general, all cohort files should contain a unique set of identifier variables for each unique subject. The pipeline system uses identifier variables to generate a unique output path for each input. To cast a cohort field as an identifier, give it the name id<i> in the cohort header, where <i> is a nonnegative integer. In the illustrative example, id0 might correspond to the subject’s identifier, id1 to the time point (as in a longitudinal study). So sub-01,ses-01 would denote the first session for subject 001. These can also be used to denote multiple runs in the same session, as sub-01,ses-01,run-01. Note that these do not get automatically added to paths when xcp is looking for files.:

id0,id1
sub-01,ses-01
sub-01,ses-02
sub-02,ses-01
sub-03,ses-01
sub-03,ses-02
sub-04,ses-02
sub-04,ses-01

Guidelines and specifications

• There are no upper or lower limits to the number of identifier variables that can be provided, but in general it is recommended that they be ordered hierarchically. That is, subject should precede time point and not the other way around.
• Identifiers can comprise any combination of alphanumeric characters and underscores. Any other characters should be excised or mapped to the set of valid characters.

Path definitions

Paths defined in a cohort file can be specified either as absolute paths or as relative paths. For portability, relative path definitions are recommended where possible. If relative paths are provided, then the call to xcpEngine should include the -r flag, which accepts as its argument the path relative to which cohort paths were defined. For instance, the provided example would yield a value of /data/example/derivatives/fmriprep/sub-01/ses-01/anat/sub-01_ses-01_T1w.nii.gz for img.:

-r /data/example/derivatives/fmriprep

with:

id0,id1,img
sub-01,ses-01,sub-01/ses-01/anat/sub-01_T1w.nii.gz

This is particularly useful for using directories mounted in Singularity.

Anatomical processing: Already done by FMRIPREP

If you aren’t interested in getting structural measurements (volume, etc) or using a custom template, you can skip this step entirely and go to Functional processing. However, if you want to use a custom template you’ll need to make sure to have T1w in your --output-spaces list when you run FMRIPREP. For anatomical processing, the cohort file is quite minimal: only the subject’s anatomical image is required in addition to the set of identifiers. The subject’s anatomical image should receive the header img. Anatomical processing must occur after ``FMRIPREP`` and before functional processing.:

id0,id1,img
sub-01,ses-01,sub-01/ses-01/anat/sub-01_ses-01_T1w.nii.gz
sub-01,ses-02,sub-01/ses-02/anat/sub-01_ses-02_T1w.nii.gz
sub-02,ses-01,sub-02/ses-01/anat/sub-02_ses-01_T1w.nii.gz
sub-03,ses-01,sub-03/ses-01/anat/sub-03_ses-01_T1w.nii.gz

Again, the structural pipeline is not necessary to run the functional pipeline in most cases.

Functional processing

Directly using preprocessed BOLD data from ``FMRIPREP``

To operate directly on the output from FMRIPREP the cohort file is very simple. The subject identifier variables are specified, followed by the path to the output image from FMRIPREP. These can be in any volumetric output space (T1w, template). Here is an example:

id0,id1,img
sub-01,ses-01,sub-01/ses-01/func/sub-01_ses-01_task-rest_space-T1w_desc-preproc_bold.nii.gz
sub-01,ses-02,sub-01/ses-02/func/sub-01_ses-02_task-rest_space-T1w_desc-preproc_bold.nii.gz
sub-02,ses-01,sub-01/ses-01/func/sub-02_ses-01_task-rest_space-T1w_desc-preproc_bold.nii.gz
sub-03,ses-01,sub-03/ses-01/func/sub-03_ses-01_task-rest_space-T1w_desc-preproc_bold.nii.gz

After running the xcp structural pipeline

There are two ways that the cohort file for the functional processing stream can be specified. In the case where the T1w-space output from FMRIPREP (requires that --output-spaces included T1w in your FMRIPREP call) was processed with the XCP anatomical stream, you need to specify the directory where that output exists. An example cohort file for this use case would look like:

id0,id1,img,antsct
sub-01,ses-01,sub-01/ses-01/func/sub-01_ses-01_task-rest_space-T1w_desc-preproc_bold.nii.gz,xcp_output/sub-01/ses-01/struc
sub-01,ses-02,sub-01/ses-02/func/sub-01_ses-02_task-rest_space-T1w_desc-preproc_bold.nii.gz,xcp_output/sub-01/ses-02/struc
sub-02,ses-01,sub-01/ses-01/func/sub-02_ses-01_task-rest_space-T1w_desc-preproc_bold.nii.gz,xcp_output/sub-02/ses-01/struc
sub-03,ses-01,sub-03/ses-01/func/sub-03_ses-01_task-rest_space-T1w_desc-preproc_bold.nii.gz,xcp_output/sub-03/ses-01/struc

The first line of this cohort file would process the image ${DATA_ROOT}/sub-01/ses-01/func/sub-01_ses-01_task-rest_space-T1w_desc-preproc_bold.nii.gz.

ASL processing

The ASL processing requires ASL image, M0 scan for caibration (if available). In the absence of M0 scan, the average control volumes is used as reference or M0 scan (scale=1). The ASL processing requires anatomical processing directory of either FMRIPREP or the struc: module of xcpEngine. Here is an example of cohort file with anatomical directory of FMRIPREP.:

id0,img,m0,anatdir
sub-1,/path/to/asl.nii.gz,/path/to/m0.nii.gz,fmriprep/sub-xx/anat

With the struc: directory of the xcpEngine output, the cohort file is shown below.:

id0,img,m0,antsct
sub-1,/path/to/asl.nii.gz,/path/to/m0.nii.gz,/path/to/struc

Without struc: or anatomical directory of FMRIPREP, the anatomical image can be included in the design file.:

id0,img,m0,t1w
sub-1,/path/to/asl.nii.gz,/path/to/m0.nii.gz,/path/to/struc/t1w.nii.gz

Subject variables

Each of the columns in the cohort file becomes a subject variable at runtime. Subject variables can be used in the design to assign a parameter subject-specific values. For instance, to use a custom task file for a subject the task_design parameter in the struc can be assigned the fsf subject variable. To indicate that the assignment is a subject variable, include the array index [sub] in the variable’s name as shown.:

task_design[1]=${fsf[sub]}

xcpEngine

xcpEngine is the pipeline system’s front end for image processing. This is the program that parses design and cohort files to deploy processing streams for different imaging modalities. This page documents command-line options and acceptable arguments for the front end. If Docker or Singularity images are used, the default command that is run is xcpEngine.

-d: Design file

The Pipeline design file file parameterizes the processing stream. Standard design files are stored in ${XCPEDIR}/designs. New design files can be generated using the xcpConfig system or via manual editing.

-c: Cohort file

The Pipeline cohort file file parameterizes the pipeline’s input sample, over which image processing is to be executed. Each row corresponds to a subject, and each column corresponds to a variable.

-o: Output path

The output path specifies the parent directory, wherein all output from the instance of the XCP system will be written. The argument to -o must correspond to an valid path on the current filesystem. If the indicated directory does not exist, xcpEngine will attempt to create it. If xcpEngine cannot create the indicated directory, it will abort with an error.

-i: Intermediate path

The intermediate path specifies a directory that the XCP instance will use as a scratch space for storage of temporary files. Some systems operate more quickly when temporary files are written in a dedicated scratch space. The -i option enables a dedicated scratch space for intermediates. Like -o, -i requires an argument that is a valid path on the current filesystem. If -i is unspecified, temporary files will be stored in the argument to -o.

-r: Reference directory

Cohort files can be made more portable if the input paths defined therein are defined relative to some root directory. If input paths are defined relatively rather than absolutely, then xcpEngine requires knowledge of the reference directory relative to which all input paths are defined. This information is provided to xcpEngine as the argument to the -r option.

-a: Direct assignment

The values of single variables in a design file can be overriden via direct assignment, which is discussed in the design file documentation. Direct assignment of variables is not generally advised. Direct assignment is enabled by passing, as the argument to -a, an equality with the variable to be assigned on the left-hand side and its new value on the right-hand side. For instance, to override the default value of the variable standard and replace it with MNI%2x2x2, use -a standard=MNI%2x2x2.

Other ways to override the default value of the variable especially in design files:

-a atlas=power264 # choose preferred atlases such as power264,schaefer

-a spatialsmooth=5 # spatial smoothing for regress (if needed), alff and reho, default is 6mm

-a temporalfilter=0.01,0.10 # temporal filter frequency range, the deafult is [0.01 0.08]

To select confound matrix by overriwriting design filter -a confound=24p # this equivalent to confound2_rps[cxt]=1; confound2_sq[cxt]=2; confound2_dx[cxt]=1

-a confound=36p # this equivalent to onfound2_rps[cxt]=1; confound2_sq[cxt]=2; confound2_dx[cxt]=1,confound2_wm[cxt]=1; confound2_csf[cxt]=1; confound2_gsr[cxt]=1

-a confound=aroma # confound2_wm[cxt]=1; confound2_csf[cxt]=1; confound2_aroma[cxt]=1;

-a confound=tcompcor # confound2_tcompcor[cxt] = 1

-a confound=acompcor # confound2_rps[cxt]=1; confound2_acompcor[cxt]=1; confound2_dx[cxt]=1;

-a fd_thresh=fds:0.083 # override the framewise threshold ( threshold will be 0.083*TRs in mm)

To select the regress option -a regress=despike # despiking, regress_process[cxt]=DMT-DSP-TMP-REG

-a regress=censor # censoring, regress_process[cxt]=DMT-TMP-REG ; censor=1

-t: Trace (verbosity) level

The verbosity level instructs the XCP system and its child scripts whether it should print image processing commands as they are called. Error traces and diagnostics are printed regardless of verbosity level, but increasing the verbosity can make it easier to trace an error to its origin point.

• 0: The default verbosity level prints only human-readable, descriptive explanations of processing steps as they are executed.
• 1: Module-level trace. Any image processing commands that are called by pipeline modules are explicitly printed to the console or log. Calls to utility scripts are printed, but any subroutines of utilities are omitted. For module validation and enhanced diagnosis of errors at the module level.
• 2: Utility-level trace. Like 1, but subroutines of utility scripts are also explicitly printed. For utility validation and enhanced diagnosis of errors at the utility level.
• 3: Maximum verbosity. Absolutely every command is traced. We’ve found that this level of verbosity is almost never warranted and that it will usually make error diagnosis more difficult, not easier, because it’s easy to lose the most relevant information in the noise.

Processing streams

Neuroimage processing refers collectively to the set of strategies used to convert the “raw” images collected from the scanner into appropriate inputs to group-level statistical analyses. A processing stream is the specific set of routines that are selected to extract a desired modality of analytic data from a neuroimage.

In the XCP system, a standard set of processing streams is available for each supported imaging modality. Each processing stream is parameterized by a design file. Detailed information about standard implementations of multimodal processing streams is available at the links below, organized by imaging modality.

Anatomical processing streams

If your FMRIPREP output is written out in the T1w output space, it is already aligned to the preprocessed T1w image. You can send this native space preprocessed T1w into the XCP structural processing stream to

• Register it to one of our many supplied templates (including OASIS, MNI and PNC)
• Warp our many included atlases into the space of your BOLD data to extract time series
• Run structural analysis on your T1w images

The XCP system includes 7 standard processing streams for volumetric anatomy. These base anatomical streams are summarized below. All processing streams are heavily based on the ANTs software library. Base anatomical streams can be modified at will to suit the dataset that is to be processed. Consult module documentation for additional details.

Processing routines

N4 bias field correction

Module: struc_

N4 bias field correction removes spatial intensity bias from the anatomical image using the N4 approach from ANTs, a variant of nonparametric nonuniform intensity normalisation.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/20378467)

ANTs brain extraction

Module: struc_

Products: mask

ANTs brain extraction combines a standard-space estimate of the probability that each voxel is a part of the brain (a brain parenchyma prior), a registration to standard space, and topological refinement in order to estimate the extent of the brain and remove non-brain voxels.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/24879923)

ANTs registration

Module: struc_

ANTs registration uses the top-performing symmetric normalisation (SyN) approach to compute a diffeomorphic function that aligns each subject’s anatomy to a sample- or population-level template brain.

[Reference 1](https://www.ncbi.nlm.nih.gov/pubmed/17659998)

[Reference 2](https://www.ncbi.nlm.nih.gov/pubmed/20851191)

Prior-guided segmentation

Module: struc_

Products: segmentation

ANTs Atropos combines Bayesian tissue-class priors in standard space with a SyN registration and a refinement step in order to produce a high-quality segmentation of the subject’s anatomy into tissue classes. Typical templates will produce a 6-class segmentation, wherein 1 corresponds to cerebrospinal fluid, 2 to cortical grey matter, 3 to cortical white matter, 4 to subcortical grey matter, 5 to cerebellum, and 6 to brainstem.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/21373993)

Priorless segmentation

Module: struc_

Products: segmentation

Priorless segmentation is a faster segmentation step that results in 3 tissue-class priors based on k-means clustering and refinement. For a T1-weighted image, 1 corresponds to cerebrospinal fluid, 2 corresponds to grey matter, and 3 corresponds to white matter.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/21373993)

DiReCT cortical thickness

Module: struc_

Products: corticalThickness

ANTs computes cortical thickness on a voxelwise basis in volumetric images using the DiReCT algorithm.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/24879923)

Grey matter density

Module: gmd_

Products: gmd, segmentation3class

Grey matter density is estimated as the probability that each voxel is assigned to the grey matter tissue class as determined via a k-means 3-class tissue segmentation and subsequent refinements.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/28432144)

Joint label fusion

Module: jlf

Products: JLF MICCAI atlas

Joint label fusion produces a custom, subject-level anatomical segmentation by diffeomorphically registering an ensemble of high-quality, manually segmented images (usually 20-40 LPBA subjects) to the subject’s anatomical image. A voting procedure is then applied in order to assign each voxel of the subject’s brain to a single region.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/24319427)

Regional quantification

Module: roiquant_

Regional quantification converts voxelwise derivative maps (for instance, cortical thickness and grey matter density estimates) into regional values based on any number of provided parcellations. It is implemented in the XCP system’s roiquant module.

Volume estimation

Module: roiquant

Estimates of global, regional, and tissue compartment volumes are computed as a part of regional quantification in the anatomical processing stream. It is implemented in the XCP system’s roiquant.

Quality assessment

Module: qcanat

Several indices of image quality are currently computable during anatomical processing. It is currently recommended to eschew these indices in favor of the Euler number, which has been found to perform better.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/29278774)

Normalization

Module: [struc]

Image normalization shifts derivative maps (and potentially the primary image) into a standard sample-level or population-level space to facilitate comparisons between subjects. The normalization step applies the transformations computed in the ANTs registration step.

Functional connectivity streams

The XCP system includes 6 standard processing streams for functional connectivity. These base processing streams are summarized below. All processing streams draw on FSL, AFNI, and ANTs. Base processing streams can be modified at will to suit the dataset that is to be processed. Consult module documentation for additional details.

Subject movement introduces a substantial amount of spurious variance into the BOLD signal; if data processing fails to account for the influence of motion-related variance, then artefact may subsequently be misconstrued as effect of interest. Accordingly, a number of high-performing processing streams for removing motion artefact are made available in the XCP system. Three families of denoising streams are available:

• High-parameter streams (36P) combine frame-to-frame motion estimates, mean signals from white matter and cerebrospinal fluid, the mean global signal, and quadratic and derivative expansions of these signals. * Reference 1 * Reference 2

• Anatomical component-based correction (aCompCor) identifies sources of signal variance in white matter and cerebrospinal fluid using principal component analysis (PCA). A sufficient number of signals to explain 50 percent of variance in white matter and cerebrospinal fluid are included in the denoising model, as are motion estimates and their derivatives. Global signal regression can be enabled (aCompCor50+gsr) or disabled (aCompCor50). * [Reference 1](https://www.ncbi.nlm.nih.gov/pubmed/17560126) * [Reference 2](https://www.ncbi.nlm.nih.gov/pubmed/24657780)

• ICA-AROMA (aroma) identifies sources of variance across the brain using independent component analysis (ICA), and then uses a heuristic to classify each source as either noise or signal of interest. Noise sources are included in the denoising model along with mean signal from white matter and CSF. Global signal regression can be enabled (aroma+gsr) or disabled (aroma). * *Note that the aroma streams do not strictly follow the original implementation of

  ICA-AROMA.* For a more faithful adaptation, see (smoothing documentation for the aroma module).

  • [Reference](https://www.ncbi.nlm.nih.gov/pubmed/25770991)

• The 24-parameter stream (24P) is never recommended, as previous investigations have not found it to perform well. * [Reference 1](https://www.ncbi.nlm.nih.gov/pubmed/28302591) * [Reference 2](https://www.ncbi.nlm.nih.gov/pubmed/29278773)

• All streams can be supplemented with despiking or framewise censoring. * [Reference 1](https://www.ncbi.nlm.nih.gov/pubmed/17490845) * [Reference 2](https://www.ncbi.nlm.nih.gov/pubmed/22019881)

Note that aroma and acompcor must have been performed during your preprocessing in FMRIPREP.

Available modules

• confound2
• regress
• reho
• alff
• seed
• fcon
• net
• roiquant
• QCFC

Processing routines

Demeaning & detrending

Module: regress

Deameaning and detrending removes the overall mean, as well as linear or polynomial trends, from the functional time series.

Censoring or despiking

Module: regress

Censoring uses criteria such as motion estimates and signal fluctuations to flag volumes likely to be contaminated by noise, and then removes those volumes from the time series entirely. Despike uses AFNI’s 3dDespike tool to identify signal outliers on a voxelwise basis and then interpolates over those outliers.

[Reference 1](https://www.ncbi.nlm.nih.gov/pubmed/17490845)

[Reference 2](https://www.ncbi.nlm.nih.gov/pubmed/22019881)

[Reference 3](https://www.ncbi.nlm.nih.gov/pubmed/22926292)

Mean WM / CSF signal

Module: confound

Variance in the white matter and cerebrospinal fluid compartments is typically not of interest in studies of functional connectivity. Thus, the mean signal from WM and CSF can be included in the denoising model.

Mean global signal

Module: confound

Regression of the global signal is uniquely effective in removing widespread effects of motion and other spatially nonspecific artifacts from a functional time series.

[Reference](https://www.ncbi.nlm.nih.gov/pubmed/15110027)

Mathematical expansions

Module: confound

Temporal derivatives and quadratic expansions are used to model delayed or nonlinear signal fluctuations attributable to artifact.

Temporal filter

Module: regress

A temporal filter removes frequencies of no interest from the functional time series. Functional connectivity is typically driven by synchrony among low-frequency signals, so temporal filters often remove higher frequencies.

Spatial smoothing

Module: regress

Spatial smoothing mitigates noise at the voxel level by enforcing spatial autocorrelation among adjacent voxels. By the same token, however, spatial smoothing also effectively reduces image resolution. For each selected kernel size, the pipeline will produce derivatives with that level of smoothing.

Functional networks

Module: fcon, net

Functional network analysis extracts mean signals from each region of a brain atlas and then estimates the degree of synchrony between each pair of regions. Functional network analysis generates a whole-brain graph; each atlas region is a node of this graph, while each synchrony estimate is an edge. Modeling the brain as a graph allows for the use of analytic tools from graph theory.

Seed-based correlation

Module: seed

Seed-based correlation analysis computes the mean signal in a region of interest (the seed) and then computes the synchrony (typically operationalized as Pearson correlation) between this signal and the signal time series in each voxel.

Regional homogeneity

Module: reho

Regional homogeneity, or ReHo, is a measure of local uniformity in the BOLD signal, operationalized as Kendall’s W among each voxel and all other voxels in its neighborhood.

ALFF

Module: alff

ALFF is an index of the Amplitude of Low-Frequency Fluctuations in the BOLD signal.

Regional quantification

Module: roiquant

Regional quantification converts voxelwise derivative maps (for instance, ReHo and ALFF estimates) into regional values based on any number of provided parcellations.

Quality assessment

Module: QCFC

Several indices of image quality are computed during functional connectivity processing at both subject and group levels.

Arterial spin labeling streams

Arterial spin labeling (ASL) provides non-invasive quantification of cerebral blood flow (CBF).:

The xcpEngine includes 3 standard modules for the quantification of the CBF. The modules are.:

1. CBF: The standard quantification of CBF that base on the relatively basic model Buxton et al 1998

2. BASIL: The BASIL uses Bayesian inference method for the kinetic model inversion and was originially developed for multidelay data. BASIL provides various advantages including spatial regularization of the estimated perfusion image and correction of partial volume effects. It is part of FSL and can also be run as standalone.

3. SCORESCRUB: SCORE (Structural Correlation based Outlier Rejection) developed by Dolui et al 2017 . SCORE algrorithm detects and discards individual CBF volumes of ASL timeseries that contaminate the mean CBF maps. It requires prior computaion of CBF (1) timesseries. SCRUB: SCRUB( Structural Correlation with RobUst Bayesian) was also developed by Dolui et al 2016. SCRUB, like BASIL, uses robust Bayesian estimation of CBF by removing the white noise as opposed to outlier rejection. The SCRUB is implemented in xcpEnigne but use SCORE to first discard outlier CBF volumes.

Each module can be run seperately and all modules can be run together but SCORESCRUB require CBF timeseries ( one of the outputs of CBF module).

Available modules

• cbf
• basil
• scorescrub

xcpEngine containers (Extra Info)

All atlases, software dependencies and scripts are included in the xcpEngine Docker/Singularity image. These instructions are not needed if you are using ``xcpengine-docker`` or ``xcpengine-singularity``. They are here in case you need to run them manually

Using xcpEngine with Singularity

The easiest way to get started with xcpEngine on a HPC system is to build a Singularity image from the xcpEngine released on dockerhub.:

$ singularity build xcpEngine.simg docker://pennbbl/xcpengine:latest

The only potentially tricky part about using a singularity image is the need to bind directories from your host operating system so they can be accessed from inside the container. Suppose there is a /data directory that is shared across your cluster as an nfs mount. All your data is stored in /data/study and you have a cohort file and design file there. When running the container, these will be seen as existing relative to the bind point. This means they need to be specified like so.:

$ singularity run \
    -B /data:/home/user/data \
    xcpEngine.simg \
    -c /home/user/data/study/my_cohort_rel_container.csv \
    -d /home/user/data/study/my_design.dsn \
    -o /home/user/data/study/output \
    -i $TMPDIR

The above command will work fine as long as your cohort file points to the data as it would be seen by the container. Specifically, the paths in my_cohort_rel_container.csv would all need to start with /home/user/data instead of /data. If you would like to keep the paths in your cohort relative to their locations in the host OS, you would need to specify a relative root when you run the container.:

$ singularity run \
    -B /data:/home/user/data \
    xcpEngine.simg \
    -c /home/user/data/study/my_cohort_host_paths.csv \
    -d /home/user/data/study/my_design.dsn \
    -o /home/user/data/study/output \
    -r /home/user \
    -i $TMPDIR

Where the paths in my_cohort_host_paths.csv all start with /data.

NOTE: Singularity typically mounts the host’s /tmp as /tmp in the container. This is useful in the case where you are running xcpEngine using a queueing system and want to write intermediate files to the locally-mounted scratch space provided in a $TMPDIR variable specific to the job. If you want to use a different temporary directory, be sure that it’s accessible from inside the container and provide the container-bound path to it.

Using xcpEngine with Docker

Using Docker is almost identical to Singularity, with the -B arguments substituted for -v. Here is an example::

$ docker --rm -it \
    -v /data:/data \
    -v /tmp:/tmp \
    pennbbl/xcpengine:latest \
    -c /data/study/my_cohort_host_paths.csv \
    -d /data/study/my_design.dsn \
    -o /data/study/output \
    -i $TMPDIR

Mounting directories in Docker is easier than with Singularity.

Using SGE to parallelize across subjects

By running xcpEngine from a container, you lose the ability to submit jobs to the cluster directly from xcpEngine. Here is a way to split your cohort file and submit a qsub job for each line. Note that we are using my_cohort_rel_container.csv, which means we don’t need to specify an -r flag. If your cohort file uses paths relative to the host’s file system you will need to specify -r:

#!/bin/bash
FULL_COHORT=/data/study/my_cohort_rel_container.csv
NJOBS=`wc -l < ${FULL_COHORT}`

if [[ ${NJOBS} == 0 ]]; then
    exit 0
fi

cat << EOF > xcpParallel.sh
#$ -V
#$ -t 1-${NJOBS}

# Adjust these so they work on your system
SNGL=/share/apps/singularity/2.5.1/bin/singularity
SIMG=/data/containers/xcpEngine.simg
FULL_COHORT=${FULL_COHORT}

# Create a temp cohort file with 1 line
HEADER=\$(head -n 1 \$FULL_COHORT)
LINE_NUM=\$( expr \$SGE_TASK_ID + 1 )
LINE=\$(awk "NR==\$LINE_NUM" \$FULL_COHORT)
TEMP_COHORT=\${FULL_COHORT}.\${SGE_TASK_ID}.csv
echo \$HEADER > \$TEMP_COHORT
echo \$LINE >> \$TEMP_COHORT

\$SNGL run -B /data:/home/user/data \$SIMG \\
  -c /home/user\${TEMP_COHORT} \\
  -d /home/user/data/study/my_design.dsn \\
  -o /home/user/data/study/output \\
  -i \$TMPDIR

EOF
qsub xcpParallel.sh

You will need to collate group-level outputs after batching subjects with the script ${XCPEDIR}/utils/combineOutput script, provided in utils.

Using SLURM to parallelize across subjects

By running xcpEngine from a container, you lose the ability to submit jobs to the cluster directly from xcpEngine. Here is a way to split your cohort file and submit an sbatch job for each line. Note that we are using my_cohort_rel_host.csv, which means we need to specify an -r flag. If your cohort file uses paths relative to the container you dont need to specify -r.

#!/bin/bash
# Adjust these so they work on your system
FULL_COHORT=/data/study/my_cohort_rel_host.csv
NJOBS=`wc -l < ${FULL_COHORT}`
HEADER="$(head -n 1 $FULL_COHORT)"
SIMG=/data/containers/xcpEngine.simg
# memory, CPU and time depend on the designfile and your dataset. Adjust values correspondingly
XCP_MEM=0G
XCP_C=0
XCP_TIME=0:0:0

if [[ ${NJOBS} == 0 ]]; then
    exit 0
fi

cat << EOF > xcpParallel.sh
#!/bin/bash -l
#SBATCH --array 1-${NJOBS}
#SBATCH --job-name xcp_engine
#SBATCH --mem $XCP_MEM
#SBATCH -c $XCP_C
#SBATCH --time $XCP_TIME
#SBATCH --workdir /my_working_directory
#SBATCH --output /my_working_directory/logs/slurm-%A_%a.out


LINE_NUM=\$( expr \$SLURM_ARRAY_TASK_ID + 1 )
LINE=\$(awk "NR==\$LINE_NUM" $FULL_COHORT)
TEMP_COHORT=${FULL_COHORT}.\${SLURM_ARRAY_TASK_ID}.csv
echo $HEADER > \$TEMP_COHORT
echo \$LINE >> \$TEMP_COHORT

singularity run -B /home/user/data:/data $SIMG \\
  -d /data/study/my_design.dsn \\
  -c \${TEMP_COHORT} \\
  -o /data/study/output \\
  -r /data \\
  -i \$TMPDIR

EOF
sbatch xcpParallel.sh

Keep in mind that - next to the directories and settings you need to adjust as mentioned in the script above - the logs directory needs to exist in your working-directory (see /my_working_directory/logs ) and you need to define the TMPDIR variable (see $TMPDIR). You will need to collate group-level outputs after batching subjects with the script ${XCPEDIR}/utils/combineOutput script, provided in utils.

Using the bundled software

All the neuroimaging software used by xcpEngine is available inside the Singularity image. Suppose you couldn’t get FSL 5.0.11 to run on your host OS. You could access it by:

$ singularity shell -B /data:/home/user/data xcpEngine.simg
Singularity: Invoking an interactive shell within container...

Singularity xcpEngine.simg:~> flirt -version
FLIRT version 6.0

Singularity xcpEngine.simg:~> antsRegistration --version
ANTs Version: 2.2.0.dev815-g0740f
Compiled: Jun 27 2017 17:39:25

This can be useful on a system where you don’t have current compilers or root permissions.

Modules

Pipeline modules are self-contained image processing routines. An image processing pipeline is created by combining desired modules; modules are the building blocks of an image processing pipeline. Each module either (a) processes the main brain image (the analyte), for instance by filtering or denoising it, or (b) uses the analyte to produce another dataset, called a derivative. (It’s also possible for modules to use derivatives to produce further derivatives).

Functional image processing

Modules that process the analyte for functional data.

• prestats: Formerly an omnibus module for functional preprocessing. Its functionality is largely implemented in FMRIPREP and additional functions have been moved to other modules.
• confound2: Generates a matrix of nuisance time series for confound regression. Supports most frequently used denoising models, including realignment parameters, tissue-based time series, PCA-derived time series, the global signal, and temporal expansions.
• regress: Executes confound regression using the matrix generated by the confound module. Censors any volumes flagged for poor data quality. Incorporates spatial and temporal filtering.

Functional derivatives

Modules that generate derivative maps from functional data.

• task: performs FSL FEAT processing
• reho: Computes voxelwise regional homogeneity.
• alff: Computes the amplitude of low-frequency fluctuations voxelwise.
• seed: Computes functional connectivity to an a priori set of seed regions using seed-based correlation analysis.

Anatomical image processing

Modules that process the analyte for anatomical data. Note that anatomical imaging processing using the struct module is NOT required unless desired, anatomic processing completed as part of fMRIPREP can be used instead.

• struc: Omnibus module for volumetric anatomical preprocessing. Leverages ANTs to execute N4 bias field correction, SyN diffeomorphic registration, Atropos segmentation (prior-driven or priorless), or the complete ANTs Cortical Thickness pipeline.

Anatomical derivatives

Modules that generate derivative maps from anatomical data.

• jlf:: Uses the ANTs Joint Label Fusion algorithm to produce a high-resolution anatomical segmentation of the subject’s anatomical data. Generates a subject-specific atlas of anatomical landmarks that can be used for regional quantification or network mapping.
• gmd: Computes voxelwise grey matter density.

ASL image processing

Modules that process the analyte for ASL image to produced CBF are .

• cbf: compute cerbral blood flow (cbf) from asl data with basic model.
• basil: compute cerbral blood flow (cbf) from asl data using Bayesian model inversion with additional derivatives

such as spatial regularized and partial volume corrected cbf.

ASL derivatives

Modules that generate derivative maps from ASL data:

• scorescrub: detects and discards the cbf volumes that might contribute to artifact and

compute average cbf from cbf timeseries by using Bayesian inference method with the aim of removing the white noise.

Registration

Modules that generate transforms between different coordinate spaces, or that apply those transforms.

• struc: Computes transforms between a high-resolution anatomical image and a template image representing a standard coordinate space using the top-performing SyN algorithm.
• norm: Applies the requisite transforms (computed by struc) to shift all derivative maps from subject native space to a standard coordinate space.

Regional quantification

• roiquant: Uses provided brain atlases or parcellations to compute, for each voxelwise derivative, a value for each region of interest in each provided brain atlas or parcellation. Converts voxelwise derivatives to regional derivatives.

Connectomics and networks

Modules that map or analyse brain networks.

• fcon: Computes the functional connectivity between each pair of regions in each provided brain atlas or parcellation to produce an adjacency matrix for the functional connectome. Computes static FC using a Pearson correlation.

Quality assessment

Modules that produce estimates of data quality.

• QCFC: Quality assessment for functional connectivity. Generates voxelwise plots, QC-FC measures, and QC-FC estimates of distance-dependence to facilitate diagnosis of motion-related contamination and assessment of denoising efficacy.

Quick Lookup

prestats

prestats was previously an omnibus module for the preprocessing of functional MR images. The functionality of prestats is mostly covered by FMRIPREP.

prestats requries a line in the design file that indicates the input image is from FMRIPREP ouput:

# input bold signal is from FMRIPREP output
 prestats_process[cxt]=FMP

The prestats outputs are derived directly from the FMRIPREP. The expected outputs include::

• prefix_preprocessed.nii.gz: Bold signal
• prefix_referenceVolume.nii.gz: reference volume with skull
• prefix_referenceVolumeBrain.nii.gz: reference volume without skull
• prefix_segmenation.nii.gz: segmentation tissues
• prefix_struct.nii.gz: T1w image
• prefix_mask.nii.gz: brain mask
• prefix_fmriconf.tsv: confound regressors from ``FMRIPREP`

All *nii.gz are expected to be have the same voxel size as the input but may have their orientation changed to the FSL standard.

The prestats outputs also consist of Quality Assesmment between structrual and BOLD images::

• prefix_coregCoverage.txt : Coverage index
• prefix_coregCrossCorr.txt : Cross correlation
• prefix_coregDice.txt : Dice index
• prefix_coregJaccard.txt : Jaccard index

confound2

confound2 models artifactual signals present in a 4D time series image. The confound model created by this module can be used to mitigate effects of subject motion and other artifactual processes by residualizing the 4D image with respect to the confound model. (The regression/residualization procedure is managed separately in the regress module.) Several types of artifact can be modeled: physiological sources, including white matter and CSF signals; global signal; realignment parameters; and signals derived from principal component analysis (PCA, CompCor). Derivatives and squares can also be added to the confound model, as can signal during prior time points. It is a rewrite of the original confound module to use outputs from FMRIPREP.

Model construction order

Currently, the confound model is assembled in the following order:

1. Add realignment parameters and mean time series from GM, WM, CSF, and global
2. Add temporal derivatives of any time series in the model
3. Add powers of any time series in the model (e.g., quadratic terms)
4. Add component-based time series (CompCor)
5. Add custom time series

So, for instance, including the second power will also include not only the squared time series, but also the squares of derivatives.

In the future, a control sequence will probably be implemented to support greater flexibility in confound models.

Module configuration

confound2_rps

Realignment parameters

Early models that attempted to correct for the introduction of spurious variance by the movement of subjects in the scanner did so by regressing out the 6 parameters (3 translational, 3 rotational) used to realign each volume in the time series to a reference volume. Later work has demonstrated that a model consisting of realignment parameters alone is ineffective at removing motion artifact from functional MR time series.:

# Use realignment parameters
confound2_rps[cxt]=1

# No realignment parameters
confound2_rps[cxt]=0

confound2_rms

Relative RMS displacement.

The relative root-mean-square displacement is estimated by FSL’s MCFLIRT. This is equivalent to the Jenkinson formulation of framewise displacement and is approximately double the Power formulation of framewise displacement. Using the relative RMS displacement as a confound time series is not recommended; this is an uncommon denoising strategy and is not likely to be effective.:

# Use RMS displacement
confound2_rms[cxt]=1

# No RMS displacement
confound2_rms[cxt]=0

confound2_wm, and confound2_csf

Tissue-based nuisance regressors, including aCompCor.

Tissue-based nuisance regressors are capable of reducing the influence of subject movement (as well as physiological artefacts) on the data. Mean white matter and cerebrospinal fluid signal are most often used to this end (e.g., Windischberger et al., 2002; Satterthwaite et al., 2012), but principal component analysis can also be used to extract signals of no interest from anatomical compartments (Behzadi et al., 2007: aCompCor). The number of aCompCor components removed can either be specified as a fixed number, or by the percent variance explained (usually this is 50% as in Muschelli et al., 2014.) This approach requires a known segmentation of the anatomical image into tissue classes. If you provided an output directory from the ANTsCT routine or the anatomical stream, then a segmentation will automatically be available as the derivative segmentation.:

# Do not use any white matter signals
confound2_wm[cxt]=0

# Use the mean white matter signal
confound2_wm[cxt]=1

Interpreting

• 1 indicates that the mean time series over all voxels inside the tissue boundaries should be used in the confound model.

Use of tissue-based nuisance regressors requires a known segmentation of the anatomical image into tissue classes. If you provided an output directory from the ANTsCT routine or the anatomical stream, then a segmentation will automatically be available as the derivative segmentation. In some segmentations, such as the one output by ANTs Cortical Thickness, each tissue class is assigned a different intensity value in the segmentation volume. For instance, 1 might correspond to CSF, 2 to cortical grey matter, 3 to white matter, etc. If your segmentation is strictly a binary-valued white matter mask, then enter ALL. To enter a range of values, use the colon (:) delimiter; to enter multiple values, use the comma (,) delimiter.:

# Use a custom segmentation for WM
confound_wm_path[cxt]=/path/to/segmentation.nii.gz

# Use the segmentation from ANTsCT or the anatomical stream for WM
confound_wm_path=${segmentation[sub]}

# Use the mean CSF signal. Use the pipeline segmentation for CSF. 1=CSF in the provided CSF segmentation path.
confound_csf[cxt]=1
confound_csf_path[cxt]=${segmentation[sub]}
confound_csf_val[cxt]=1

In order to ensure that the signal extracted from the tissue or region of interest is not mixed with signal from adjacent voxels associated with a different tissue class (partial volume effects), it is possible to erode its mask by removing fringe voxels. An optimal degree of erosion will result in a mask comprising ‘deep’ voxels of the tissue, while excessive erosion may result in a mask whose extent is poorly representative of the tissue. For functional connectivity analysis, more aggressive erosion of WM and CSF masks is recommended to reduce collinearity of WM and CSF signal with global and GM signals. Erosion to a target range of 5 to 10 percent is recommended in this case.:

# Erode CSF mask to the deepest 10 percent
confound_csf_ero[cxt]=10

# Erode WM mask to the deepest 5 percent
confound_wm_ero[cxt]=5

The value of confound_<tissue>_ero specifies the level of erosion that is to be applied to tissue masks. Allowable values range from 0 to 100 and reflect the minimum percentage of tissue remaining after erosion cycles have been applied. For instance, a value of 30 indicates that the tissue mask should be eroded to 30 percent its original size; that is, the mask will comprise only the deepest 30 percent of voxels with the tissue classification. (Depth is computed using ImageMath from ANTs, and the erosion is implemented in the utility erodespare.)

For advanced users: The confound module offers the option of including up to three tissue- or RoI-based regressors. While nominally these are the mean GM, WM, and CSF timeseries, it is possible to include signals from any three RoIs for which a binary mask is available by assigning the appropriate value to the <tissue>_path variable.

confound2_gsr

Global signal regression.

Removal of the mean signal across the entire brain is one of the simplest and most effective means of attenuating the influence of artefactual sources such as subject motion. While earlier studies suggested that global signal regression might be harmful, for instance by introducing artefactual anticorrelations (Murphy et al., 2009) or group differences (Saad et al., 2012), an emerging consensus (e.g., Power et al., 2014; Chai et al., 2012) suggests instead that it is uniquely effective in removing widespread forms of artefact (due to both motion and physiological processes such as respiration).:

# Enable GSR (recommended for functional connectivity analysis)
confound2_gsr[cxt]=1

# Disable GSR
confound2_gsr[cxt]=0

confound2_past

Expansion: previous time points.

Including forward-shifted realignment and nuisance timeseries in the nuisance model (Friston et al., 1996) provides a means of factoring in the subject’s history of motion and for the lingering effects of motion, which may persist for upwards of 10 seconds following motion itself. confound_past must be a nonnegative integer.:

# Include no previous time points
confound2_past[cxt]=0

# Include previous time point
confound2_past[cxt]=1

# Include previous 2 time points
confound2_past[cxt]=2

Note: Do not include both previous time points (confound2_past) and temporal derivatives (confound2_dx) in the same model. Together with the original time series, they form a collinear triple, which will result in an overspecified model. That is to say, for a time series \(T\), its temporal derivative \(D\), and previous/shifted time series \(P\),

\(D + P = T\)

confound2_dx

Expansion: temporal derivatives.

Temporal derivatives of motion parameters encode the relative displacement of the brain from one volume of a timeseries to the next; they are used in major confound models (e.g., Satterthwaite et al., 2012). confound2_dx must be a nonnegative integer.:

# Include no temporal derivatives
confound2_dx[cxt]=0

# Include first temporal derivative
confound2_dx[cxt]=1

# Include first and second temporal derivatives
confound2_past[cxt]=2

Note: Do not include both previous time points (confound2_past) and temporal derivatives (confound2_dx) in the same model. Together with the original time series, they form a collinear triple, which will result in an overspecified model. That is to say, for a time series \(T\), its temporal derivative \(D\), and previous/shifted time series \(P\),

\(D + P = T\)

confound2_sq

Expansion: powers (quadratic, cubic, quartic, etc.).

In addition to the first power of each confound, you may elect to include higher powers to account for potential noise that is proportional to squares or higher powers of motion parameters and nuisance regressors.:

# First power only
confound2_sq[cxt]=1

# First power and quadratic expansion
confound2_sq[cxt]=2

# First power, quadratic and cubic expansions
confound2_sq[cxt]=3

confound2_custom

Custom regressors.

In addition to regressors generated from the image data, custom regressors can be added to the nuisance model. For instance, these might include respiratory traces convolved with an appropriate response function or estimates of task-driven activity. Custom regressors should be formatted as a matrix with regressor time series in columns and time points/frames in rows.:

# No custom regressors
confound2_custom[cxt]=

# Include a custom regressor file
confound2_custom[cxt]=/path/to/custom/file.1D

# Include custom regressors in multiple files
confound2_custom[cxt]=/path/tocustom/file_1.1D,/path/to/custom/file_2.1D

confound_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
confound_rerun[cxt]=0

# Repeat all processing steps
confound_rerun[cxt]=1

confound2_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
confound2_cleanup[cxt]=1

# Retain temporary files
confound2_cleanup[cxt]=0

Example configuration: 36-parameters model

The 36-parameter confound model includes 6 realignment parameters, mean WM and CSF time series, and global signal regression (9 parameters). Additionally, the 36-parameter model includes temporal derivatives of these 9 time series (+9) and squares of the original 9 parameters and of their temporal derivatives (+18) for a total of 36 parameters. As an illustrative example for confound2 module configuration, the variable settings for configuring a 36-parameter model are shown here. The example configuration uses a standard 6-class segmentation, such as that output by the ANTs Cortical Thickness pipeline when provided appropriate priors.:

confound2_rps[2]=1
confound2_rms[2]=0
confound2_wm[2]=1
confound2_csf[2]=1
confound2_gsr[2]=1
confound2_acompcor[2]=0
confound2_tcompcor[2]=0
confound2_aroma[2]=0
confound2_past[2]=0
confound2_dx[2]=1
confound2_sq[2]=2
confound2_custom[2]=
confound2_censor[2]=0
confound2_censor_contig[2]=0
confound2_framewise[2]=fds:0.167,dv:2
confound2_rerun[2]=0
confound2_cleanup[2]=1

regress

regress executes multiple linear regression to fit any confound time series computed using the confound module to the time series of each voxel in the analyte image. Any variance in the BOLD time series that is explained by the confound model is discarded from the analyte image. The residuals (unexplained variance) of the BOLD time series are retained as the denoised image. regress additionally supports temporal filtering, censoring, and production of smoothed derivative time series.

Despiking

Despiking is a process in which large spikes in the BOLD times series are truncated. Despiking reduces/limits the amplitude or magnitude of the large spikes but preserves those data points with an imputed reduced amplitude. Despiking is encouraged to be done before filtering and regression to minimize the impact of spike. Despiking is very effective because it is a voxelwise operation, and no volume is deleted/removed. For despiking in xcpEngine, DSP is added to regress_process:

regress_process[cxt]=DSP-TMP-REG

Temporal Censoring

Temporal Censoring is a process in which data points with excessive motion outliers are identified/flagged. The censored data points are removed from the data. This is effective for removing spurious sources of connectivity in fMRI data but must be applied verycarefully because the censored volumes are removed and the final BOLD signal. To apply censoring in xcpEngine, confound2_censor[cxt]=1 should be specified in confound2 in the design file. However, the threshold to identify the censored volumes or outliers is obtained from framewise displacement. The framewise displacement (FD) is obtained from FMRIPREP regressors.

Framewise displacement (fd) will be used as the threshold. For instance, the spike regression (Satterthwaite et al. 2013) required threshold of 0.25mm for TR of 3s and scrubbing (Power 2012) required threshold of 0.5 mm. Any volume with FD above the threshold will be flagged. The threshold is configured in confound2 as shown below. Scrubbing/censoring uses FD,RMS and DVARS to established the threshold. The threshold is specified in confound2 as well as:

• confound2_framewise[cxt]=fds:0.083,dv:2. For spike regression, with TR of of 3, the threshold will be

0.083*3 ~= 0.25mm. with This is standard or common threshold (Ciric et al. 2012, Satterthwaite et al. 2013) and are provided in the design files. The actual threshold value is determined by the TR of the BOLD signal.

For scrubbing, the threshold will be fds:0.167 which implies that the actual threshold will be 0.167*3 =~0.5mm Scrubbing also includes masking out the non-contiguous segments of data between outliers. The number of contiguous volumes required to survive masking is set flexibly by censor_contig[cst]=x, where x is the minimum number of contiguous threshold-surviving time points required for those time points to survive masking. The default found in non-scrubbing design files is zero. This can be configured by setting:

*confound2_censor_contig[cxt]=5

Surface processing

THe xcpEngine also regresses out the confound regressors from the gifti and cifti files if they are available in the fmriprep output. The residualised files are as follows:

• prefix_residualized.dtseries # residualised cifti files
• prefix_residualized_hemi-R_bold.func.gii # residualized gifti files

regress_process

Specifies the order for execution of filtering and regression. Bandpass filtering the analyte time series but not nuisance regressors re-introduces noise-related variance at removed frequencies when the time series is residualised with respect to the regressors via linear fit (Hallquist et al., 2014). Thus, effective denoising requires either that confound regression be performed prior to temporal filtering or that both the analyte time series and all confound time series be subjected to the same temporal filter in order to prevent frequency mismatch. Format regress_process as a string of concatenated three-character routine codes separated by hyphens (-).

• REG-TMP instructs the module to perform confound regression prior to temporal filtering.
• TMP-REG instructs the module to perform temporal filtering prior to confound regression. If this option is set, then both the analyte time series and all confound time series will be filtered. This option is typically preferable to REG-TMP because it determines the confound fit using only the frequencies of interest.
• Note that censoring is always performed after both filtering and regression.

regress_tmpf

Temporal filtering parameters.

Bandpass filtering the analyte time series but not nuisance regressors re-introduces noise-related variance at removed frequencies when the time series is residualised with respect to the regressors via linear fit (Hallquist et al., 2014). (The XCP Engine is designed so as to make this involuntary reintroduction of noise impossible.) Instead, the recommended approach is filtering both the time series and the nuisance regressors immediately prior to fitting and residualisation (Hallquist et al., 2014).:

# Gaussian filter
regress_tmpf[cxt]=gaussian

# FFT filter
regress_tmpf[cxt]=fft

# Second-order Butterworth filter
regress_tmpf[cxt]=butterworth
regress_tmpf_order[cxt]=2
regress_tmpf_pass[cxt]=2

# First-order Chebyshev I filter with pass-band ripple 0.5
regress_tmpf[cxt]=chebyshev1
regress_tmpf_order[cxt]=1
regress_tmpf_pass[cxt]=2
regress_tmpf_ripple[cxt]=0.5

# First-order elliptic filter with pass-band ripple 0.5 and stop-band ripple 20
regress_tmpf[cxt]=elliptic
regress_tmpf_order[cxt]=1
regress_tmpf_pass[cxt]=2
regress_tmpf_ripple[cxt]=0.5
regress_tmpf_ripple2[cxt]=20

To note:

• FFT-based filters, as implemented in AFNI’s 3dBandpass, use a fast Fourier transform to attenuate frequencies. An FFT-based filter may not be suitable for use in designs that incorporate iterative motion censoring, since it will include interpolated frequencies in its calculations.
• A Gaussian filter, as implemented in FSL, uses a Gaussian-weighted least-squares fit to remove frequencies of no interest from the data. This filter has a very slow frequency roll-off.
• Chebyshev and elliptic filters more ideally discriminate accepted and attenuated frequencies than do Butterworth filters, but they introduce ripples in either the passband (Chebyshev I), stopband (Chebyshev II), or both (elliptic) that result in some signal distortion.
• regress*tmpf*order specifies the filter order. (Relevant only for Butterworth, Chebyshev, and elliptic filters.)
• regress*tmpf*pass specifies whether the filter is forward-only (regress*tmpf*pass[cxt]=1, analogous to filter or lfilter in NumPy or MATLAB) or forward-and-reverse (regress*tmpf*pass[cxt]=2, analogous to filtfilt in NumPy or MATLAB, recommended). (Relevant only for Butterworth, Chebyshev, and elliptic filters.)
• regress*tmpf*ripple specifies the pass-band ripple, while regress*tmpf*ripple2 specifies the stop-band ripple. (ripple relevant only for Chebyshev I or elliptic filter, ripple2 relevant only for Chebyshev II or elliptic filter.)

regress_hipass and regress_lopass

Temporal filter cutoff frequencies.

Any frequencies below the low-pass cutoff and above the high-pass cutoff will be counted as pass-band frequencies; these will be retained by the filter when it is applied.

Functional connectivity between regions of interest is typically determined on the basis of synchrony in low-frequency fluctuations (Biswal et al., 1995); therefore, removing higher frequencies using a low-pass filter may effectively remove noise from the time series while retaining signal of interest. For a contrasting view, see Boubela et al. (2013). Set regress_lopass to n (Nyquist) to allow all low frequencies to pass.:

# Band-pass filter with pass-band 0.01-0.08 Hz
regress_hipass[cxt]=0.01
regress_lopass[cxt]=0.08

# High-pass-only filter (>0.01 Hz)
regress_hipass[cxt]=0.01
regress_lopass[cxt]=n

# Low-pass-only filter (<0.1 Hz)
regress_hipass[cxt]=0
regress_lopass[cxt]=0.1

High-pass filters can be used to remove very-low-frequency drift from an acquisition; this is a form of scanner noise. The demean/detrend option additionally removes linear and polynomial drift. Set regress_hipass to 0 to allow all high frequencies to pass.

regress_sptf and regress_smo: Spatial smoothing parameters.

Endemic noise, for instance due to physiological signals or scanner activity, can introduce spurious or artefactual results in single voxels. The effects of noise-related artefacts can be mitigated by spatially filtering the data, thus dramatically increasing the signal-to-noise ratio. However, spatial smoothing is not without its costs: it effectively reduces volumetric resolution by blurring signals from adjacent voxels. The spatial smoothing implemented in the regress module (i) keeps the unsmoothed analyte image for downstream use and (ii) creates a derivative image that is smoothed using the specified kernel. This allows either the smoothed or the unsmoothed version of the image to be used in any downstream modules as appropriate.:

# No smoothing
regress_sptf[cxt]=none
regress_smo[cxt]=0

# Gaussian kernel (fslmaths) of FWHM 6 mm
regress_sptf[cxt]=gaussian
regress_smo[cxt]=6

# SUSAN kernel (FSL's SUSAN) of FWHM 4 mm
regress_sptf[cxt]=susan
regress_smo[cxt]=4

# Uniform kernel (AFNI's 3dBlurToFWHM) of FWHM 5 mm
regress_sptf[cxt]=uniform
regress_smo[cxt]=5

regress_sptf specifies the type of spatial filter to apply for smoothing, while regress_smo specifies the full-width at half-maximum (FWHM) of the smoothing kernel in mm.

• Gaussian smoothing applies the same Gaussian smoothing kernel across the entire volume.
• SUSAN-based smoothing restricts mixing of signals from disparate tissue classes (Smith and Brady, 1997).
• Uniform smoothing applies smoothing to all voxels until the smoothness computed at every voxel attains the target value.
• Uniform smoothing may be used as a compensatory mechanism to reduce the effects of subject motion on the final processed image (Scheinost et al., 2014).

regress_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
regress_rerun[cxt]=0

# Repeat all processing steps
regress_rerun[cxt]=1

regress_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
regress_cleanup[cxt]=1

# Retain temporary files
regress_cleanup[cxt]=0

Expected outputs

The main output of regress module is prefix_residualised.nii.gz for the completion of the module. Other outputs include:

-  prefix_confmat.1D  # filtered regressors
-  prefix_confcor.txt # Pearson correlation between confound regressors

For Censoring and spike regression and if any volume is flagged, the other outputs include:

- prefix_uncensored.nii.gz # the regressed bold image with  flagged volme  interpolated
- prefix_nVolumesCensored.txt # number of volume censored
- prefix_residualised.nii.gz # residualized volume with deleted flagged volume

The optional output is the spatially smoothed residualised BOLD signal. This is specified with regress_sptf[cxt] and regress_smo[cxt] as explained previously. For instance, with:

regress_sptf[cxt]=gaussian
regress_smo[cxt]=6

This tells xcpEngine to smooth the residualised image with gaussian filter and kernel of 6mm. The derived output, which is saved in the regress folder, will be:

prefix_img_sm6.nii.gz

If the freesurfer is included as part of FMRIPREP outputs, the CIFTI files are produced for filtered and regressed bold data (${prefix}_residualised.nii.gz)

reho

reho computes the regional homogeneity (ReHo) at each voxel of the processed image and/or within user-specified a priori regions of interest. ReHo, or Kendall’s W, is a measure of local uniformity in the BOLD signal. Greater ReHo values correspond to greater synchrony among BOLD activation patterns measured in a neighbourhood of voxels.

reho_nhood

Voxel neighbourhood.

Regional homogeneity is computed as Kendall’s W (coefficient of concordance) among the timeseries of a voxel and its neighbours. The neighbours of a voxel may include either:

• faces: Any of the 6 voxels adjoining that voxel along the surfaces of its faces
• edges: Any of the 18 voxels adjoining that voxel along its faces or edges
• vertices: Any of the 26 voxels adjoining that voxel at any of its faces, edges, or vertices
• sphere: Any voxels that lie within a sphere of user-specified radius from that voxel.

Regional homogeneity may be computed for each voxel in such a manner as to consider any voxels within a user-specified radius of that voxel to be that voxel’s neighbourhood. The regional homogeneity will then be defined as the coefficient of concordance among all voxels in a sphere centred on the target voxel. The neighbourhood radius should be provided in millimeters.:

# 7-voxel neighbourhood incident on faces
reho_nhood[cxt]=faces

# 19-voxel neighbourhood incident on faces or edges
reho_nhood[cxt]=edges

# 27-voxel neighbourhood incident on faces, edges, or vertices
reho_nhood[cxt]=vertices

# spherical neighbourhood of radius 12 mm
reho_nhood[cxt]=sphere,12

reho_sptf and reho_smo

Spatial smoothing parameters.

Endemic noise, for instance due to physiological signals or scanner activity, can introduce spurious or artefactual results in single voxels. The effects of noise-related artefacts can be mitigated by spatially filtering the data, thus dramatically increasing the signal-to-noise ratio. However, spatial smoothing is not without its costs: it effectively reduces volumetric resolution by blurring signals from adjacent voxels. Regional homogeneity will be artificially inflated if the analysis is performed on a smoothed image because smoothing enforces a degree of autocorrelation or synchrony among spatially proximal voxels. Thus, the reho module always performs analysis on an unsmoothed image. The spatial smoothing implemented in the reho module is performed after the regional homogeneity map is computed voxelwise; the voxelwise map is smoothed.:

# No smoothing
reho_sptf[cxt]=none
reho_smo[cxt]=0

# Gaussian kernel (fslmaths) of FWHM 6 mm
reho_sptf[cxt]=gaussian
reho_smo[cxt]=6

# SUSAN kernel (FSL's SUSAN) of FWHM 4 mm
reho_sptf[cxt]=susan
reho_smo[cxt]=4

# Uniform kernel (AFNI's 3dBlurToFWHM) of FWHM 5 mm
reho_sptf[cxt]=uniform
reho_smo[cxt]=5

reho_sptf specifies the type of spatial filter to apply for smoothing, while reho_smo specifies the full-width at half-maximum (FWHM) of the smoothing kernel in mm.

• Gaussian smoothing applies the same Gaussian smoothing kernel across the entire volume.
• SUSAN-based smoothing restricts mixing of signals from disparate tissue classes (Smith and Brady, 1997).
• Uniform smoothing applies smoothing to all voxels until the smoothness computed at every voxel attains the target value.
• Uniform smoothing may be used as a compensatory mechanism to reduce the effects of subject motion on the final processed image (Scheinost et al., 2014).

reho_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
reho_rerun[cxt]=0

# Repeat all processing steps
reho_rerun[cxt]=1

reho_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
reho_cleanup[cxt]=1

# Retain temporary files
reho_cleanup[cxt]=0

Expected output The main outputs from reho include:

- prefix_reho.nii.gz
- prefix_rehoZ.nii.gz # reho in Z score

Other derived outputs are the smoothed images if it is specify in design file.

alff

alff computes the amplitude of low-frequency fluctuations (ALFF) in each voxel of the processed image. Low-frequency fluctuations are of particular importance because functional connectivity is most typically computed on the basis of synchronous activations at low frequencies. It is possible that the magnitude (amplitude) of such activations has utility as a biomarker for pathologies or psychological variables.

alff_hipass and alff_lopass

The output of an ALFF analysis is dependent upon the precise definition of ‘low frequency’. ALFF is determined by computing a power spectrum at each voxel, then integrating over those frequencies of the power spectrum that correspond to the user-specified passband. The low-pass cutoff frequency corresponds to the upper limit of the passband; any frequencies lower than this cutoff are allowed to pass. Similarly, the high-pass cutoff frequency corresponds to the upper limit of the passband; any frequencies higher than this cutoff are allowed to pass. While the power-spectrum integral is probably most informative when the limits of integration encompass low frequencies, advanced users may elect to use this module to compute the amplitude of oscillations in any frequency range.:

# Low-frequency pass-band 0.01-0.08 Hz
alff_hipass[cxt]=0.01
alff_lopass[cxt]=0.08

# Low-frequency pass-band 0.008-0.12 Hz
alff_hipass[cxt]=0.008
alff_lopass[cxt]=0.12

alff_sptf and alff_smo

Spatial smoothing parameters.

Endemic noise, for instance due to physiological signals or scanner activity, can introduce spurious or artefactual results in single voxels. The effects of noise-related artefacts can be mitigated by spatially filtering the data, thus dramatically increasing the signal-to-noise ratio. However, spatial smoothing is not without its costs: it effectively reduces volumetric resolution by blurring signals from adjacent voxels. The spatial smoothing implemented in the alff module (i) keeps the unsmoothed analyte image for downstream use and (ii) creates a derivative image that is smoothed using the specified kernel. This allows either the smoothed or the unsmoothed version of the image to be used in any downstream modules as appropriate.:

# No smoothing
alff_sptf[cxt]=none
alff_smo[cxt]=0

# Gaussian kernel (fslmaths) of FWHM 6 mm
alff_sptf[cxt]=gaussian
alff_smo[cxt]=6

# SUSAN kernel (FSL's SUSAN) of FWHM 4 mm
alff_sptf[cxt]=susan
alff_smo[cxt]=4

# Uniform kernel (AFNI's 3dBlurToFWHM) of FWHM 5 mm
alff_sptf[cxt]=uniform
alff_smo[cxt]=5

alff_sptf specifies the type of spatial filter to apply for smoothing, while alff_smo specifies the full-width at half-maximum (FWHM) of the smoothing kernel in mm.

• Gaussian smoothing applies the same Gaussian smoothing kernel across the entire volume.
• SUSAN-based smoothing restricts mixing of signals from disparate tissue classes (Smith and Brady, 1997).
• Uniform smoothing applies smoothing to all voxels until the smoothness computed at every voxel attains the target value.
• Uniform smoothing may be used as a compensatory mechanism to reduce the effects of subject motion on the final processed image (Scheinost et al., 2014).

alff_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
alff_rerun[cxt]=0

# Repeat all processing steps
alff_rerun[cxt]=1

alff_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
alff_cleanup[cxt]=1

# Retain temporary files
alff_cleanup[cxt]=0

Other derived outputs are the smoothed images if it is specify in design file.

seed

seed performs seed-based correlation analyses given a seed region or set of seed regions. For each seed region, which may be provided either as a 3D volume (mask) in NIfTI format or coordinates. seed computes the pairwise connectivity between each voxel and the seed region, for instance using the Pearson correlation coefficient between timeseries (Biswal et al., 1995).

seed_points,seed_names and seed_radius

seed_names is three-letters to identify a seed for naming purpose and can be more than one.

If this field is left blank, then no seed-based correlation analysis will be performed. The seed_points are three coordnates (in mm) of the seed point in template space. seed_points and seed_names can be specify as shown below:

# for  one seed point correlation

seed_names[cxt]=PCC # for seed at PCC seed_points[cxt]=0,-62,24 # seed location of PCC seed_radius[cxt]=8 # 8mm radius, 5mm will de used as if radius is not specify

# for more than one seed loaction seed_names[cxt]=PCC#VMF#LOC # PCC, VMF and LOC seed_points[cxt]=0,-62,24#0,34,-14#-36,-52,-2 # seed locations

seed_mask

A 3D mask can also be supply the mask must be derived from the template. xcpEngine assumes that the mask in the same dimesnion as template:

seed_names[cxt]=PCC
seed_mask[cxt]=/path/to/mask

seed_sptf and seed_smo

Spatial smoothing parameters.

Endemic noise, for instance due to physiological signals or scanner activity, can introduce spurious or artefactual results in single voxels. The effects of noise-related artefacts can be mitigated by spatially filtering the data, thus dramatically increasing the signal-to-noise ratio. However, spatial smoothing is not without its costs: it effectively reduces volumetric resolution by blurring signals from adjacent voxels. The spatial smoothing implemented in the seed module (i) keeps the unsmoothed analyte image for downstream use and (ii) creates a derivative image that is smoothed using the specified kernel. This allows either the smoothed or the unsmoothed version of the image to be used in any downstream modules as appropriate.:

# No smoothing
seed_sptf[cxt]=none
seed_smo[cxt]=0

# Gaussian kernel (fslmaths) of FWHM 6 mm
seed_sptf[cxt]=gaussian
seed_smo[cxt]=6

# SUSAN kernel (FSL's SUSAN) of FWHM 4 mm
seed_sptf[cxt]=susan
seed_smo[cxt]=4

# Uniform kernel (AFNI's 3dBlurToFWHM) of FWHM 5 mm
seed_sptf[cxt]=uniform
seed_smo[cxt]=5

seed_sptf specifies the type of spatial filter to apply for smoothing, while seed_smo specifies the full-width at half-maximum (FWHM) of the smoothing kernel in mm.

• Gaussian smoothing applies the same Gaussian smoothing kernel across the entire volume.
• SUSAN-based smoothing restricts mixing of signals from disparate tissue classes (Smith and Brady, 1997).
• Uniform smoothing applies smoothing to all voxels until the smoothness computed at every voxel attains the target value.
• Uniform smoothing may be used as a compensatory mechanism to reduce the effects of subject motion on the final processed image (Scheinost et al., 2014).

seed_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
seed_rerun[cxt]=0

# Repeat all processing steps
seed_rerun[cxt]=1

seed_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
seed_cleanup[cxt]=1

# Retain temporary files
seed_cleanup[cxt]=0

Expected outputs

A sub-directory of seed_names is created in seed directory. The directory constist of::

• prefix_connectivity_{seed_name}_seed.nii.gz # seed mask in BOLD space
• prefix_connectivity_{seed_name}_sm*.nii.gz # seed correlation map
• prefix_connectivity_{seed_name}Z_sm*.nii.gz # Fisherz transfromed seed correlation map
• prefix_connectivity_{seed_name}_ts.1D # time series of seed point

task

task module performs the General Linear Model (GLM) with FSL. It require a FSL-FEAT task design file with event files and full model setup. The task module run like FEAT-FMRI analysis and the ouputs is compatible with other xcpEngine modules such as roiquant, fcon and norm.

The six motion parameters are to be included in the FEAT design (by default) but can be changed as required by the user. The following motion nuissance regressors can be added : ‘36p’,’24p’,’acompcor’,’acompcor_gsr’,’aroma’, and ‘tcompcor’,see Ciric et al. 2017 for detail. This can be specify in the design file as:

task_fmriprep[1]=1
task_vol2del[1]=0  # first N volume to be deleted
task_confound[1]='36p' # including 36 motion parameters
task_rerun[1]=N
task_cleanup[1]=Y

The Pipeline cohort file for the task can include a task design if the subjects’ event files are different:

id0,img,task_design
sub-01,/path/to/bold1.nii.gz,/path/to/design1.fsf
sub-02,/path/to/bold2.nii.gz,/path/to/design2.fsf
sub-04,/path/to/bold4.nii.gz,/path/to/design4.fsf

if there are other nuissance regressors like physiological data that want to be included in the design, it can be added to the Pipeline cohort file as

id0,img,task_design,task_custom
sub-01,/path/to/bold1.nii.gz,/path/to/design1.fsf,/path/to/custom.txt

Users can create a design file for each subject (or group) by running one subject in FSL GUI. This is a sample of a template design : https://github.com/PennBBL/xcpEngine/blob/master/utils/template.fsf for simple experiment of EYES OPEN versus EYES CLOSE

The outputs of task module is reorganized as follow::

• task/fsl # the fsl feat directory
• task/model # the supplied design files and model
• task/logs # logs and html report
• task/mc # motion parameters
• task/copes # cope files depend on the design file and model setup
• task/vacopes # varcope files depend on the design file and model setup
• task/pes # arcope files depend on the design file and model setup
• task/sigchange # % signal change computed from pes
• task/stats # zstats files depend on the design file and model setup

The other outputs are derived directly from the FMRIPREP. The expected outputs include::

• prefix_preprocessed.nii.gz: Bold signal
• prefix_referenceVolume.nii.gz: reference volume with skull
• prefix_referenceVolumeBrain.nii.gz: reference volume without skull
• prefix_segmenation.nii.gz: segmentation tissues
• prefix_struct.nii.gz: T1w image
• prefix_mask.nii.gz: brain mask
• prefix_fmriconf.tsv: confound regressors from ``FMRIPREP`
• prefix_meanIntensity.nii.gz # average volume of the BOLD

All *nii.gz are expected to be have the same voxel size as the input but may have their orientation changed to the FSL standard.

The outputs also consist of Quality Assesmment between structrual and BOLD images::

• prefix_coregCoverage.txt : Coverage index
• prefix_coregCrossCorr.txt : Cross correlation
• prefix_coregDice.txt : Dice index
• prefix_coregJaccard.txt : Jaccard index

If the freesurfer is included as part of FMRIPREP outputs, the CIFTI files are produced for task and confound regressed bold data (res4d.nii.gz)

struc

struc is an omnibus module for processing of anatomical MR images. struc can run the ANTs Cortical Thickness (ANTsCT) pipeline in its entirety or can execute any combination of N4 bias field correction, FSL- or ANTs-based brain extraction, Atropos brain segmentation, and ANTs diffeomorphic registration.

Outputs

• corticalThickness
• mask
• segmentation

Omnibus modules

Omnibus modules defy modular logic to an extent: they do not comprise a single, well-encapsulated processing step. Instead, they include a number of routines, each of which corresponds to a common processing step. These routines can be combined and re-ordered within the parent module. Much like the pipeline variable specifies the inclusion and order of modules in the pipeline, the module-level process variable specifies the inclusion and order of routines within an omnibus module. An example is provided here for the struc omnibus module::

pipeline=struc,gmd,cortcon,sulc,jlf,roiquant,qcanat
struc_process[1]=BFC-ABE-REG-SEG

In the example here, the pipeline variable is defined as a standard anatomical stream that begins with struc.

• struc_process: the name of the variable specifying the inclusion and order of routines
• [1]: the scope of the struc_process variable, that is, the first module of the pipeline
• BFC-ABE-REG-SEG: a series of three-letter codes for module routines to be called within struc, offset by hyphens (-) and ordered in the same order that they are to be executed

Available routine codes

ACT

ANTs Cortical Thickness. This routine executes the entire ANTs cortical thickness pipeline. In general, no other routines need to be included if ACT is used.

BFC

N4 bias field correction. This routine removes spatial intensity bias from the anatomical image using the N4 approach from ANTs.

ABE

ANTs brain extraction. This routine uses antsBrainExtraction to identify brain voxels and remove any non-brain voxels from the anatomical image.

FBE

FSL brain extraction. This routine uses FSL’s BET to identify brain voxels and remove any non-brain voxels from the anatomical image.

SEG

Anatomical segmentation. This routine uses ANTs’s Atropos with or without tissue class priors to segment the anatomical image into tissue classes.

REG

Registration. This routine uses antsRegistration to diffeomorphically register the anatomical image to a template.

Module configuration

struc_denoise_anat

Denoise anatomical image.

Routine: SEG, ACT.

During the segmentation procedure, ANTs can use the DenoiseImage program to remove noise from an anatomical image using a spatially adaptive filter with a Gaussian or a Rician noise model.:

# do not denoise
struc_denoise_anat[cxt]=0

# apply denoising
struc_denoise_anat[cxt]=1

struc_denoise_anat must be either 0 or 1.

struc_seg_priors

Prior-driven segmentation.

Routine: SEG.

Segmentation implemented in the SEG routine can be either prior-driven or priorless. In prior-driven segmentation, the segmentation of the brain into tissue classes is guided by prior maps that assign each voxel a probability of belonging to each tissue class, often resulting in a more anatomically correct parcellation. Tissue-class priors are provided for each parcellation. (Disabling this option is not currently available in the ANTsCT routine (ACT); the ANTsCT pipeline will always use prior-driven segmentation.):

# enable prior-driven segmentation
struc_seg_priors[cxt]=1

# do not use priors for segmentation
struc_seg_priors[cxt]=0

struc_seg_priors must be either 0 or 1.

struc_prior_weight

Prior weight for segmentation.

Routine: SEG.

Segmentation implemented in the SEG routine can be either prior-driven or priorless. If prior-driven segmentation (struc_seg_priors) is enabled, the prior weight determines the extent to which the tissue class priors constrain the parcellation. A higher prior weight will result in a segmentation that more closely conforms to the priors.:

# set prior weight to 0.25
struc_prior_weight[cxt]=0.25

struc_seg_priors must be a value in the interval [0,1] (inclusive).

struc_posterior_formulation

Posterior formulation.

Routine: SEG, ACT.

The formulation for posterior probability maps produced by the segmentation routine. The default setting ('Socrates[1]') is usually acceptable. Consult the ANTs documentation for more information.:

# Use Socrates formulation with mixture model proportions
struc_posterior_formulation[cxt]='Socrates[1]'

# Use Plato formulation with mixture model proportions
struc_posterior_formulation[cxt]='Plato[1]'

struc_posterior_formulation can be, for instance, 'Socrates[1]' (default), 'Plato[1]', 'Aristotle[1]' or 'Sigmoid[1]'. Consult the ANTs documentation for all available options.

struc_floating_point

Precision for registrations.

Routine: REG, ABE, ACT.

The precision to be used during registrations. 1 indicates that single-precision registration should be used, while 0 indicates that double-precision registration should be used (default, more precision).:

# Use double precision
struc_floating_point[cxt]=0

# Use single precision
struc_floating_point[cxt]=1

struc_floating_point must be either 0 or 1.

struc_random_seed

Use random seed.

Routine: SEG, ABE, ACT.

The pseudorandom number generator can generate values that appear more random if it is seeded with a value based on the system clock. To use random seeding to initialise the RNG, set struc_random_seed to a value of 1.:

# Use random seed
struc_random_seed[cxt]=1

# Disable random seed
struc_random_seed[cxt]=0

struc_random_seed must be either 0 or 1.

struc_bspline

Deformable B-spline SyN registration.

Routine: REG, ACT.

Regularisation during ANTs registration can be performed using a b-spline approach. Please reference the [original article](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3870320/#B36) for further information.:

# Use deformable B-spline registration
struc_bspline[cxt]=1

# Use deformable registration
struc_bspline[cxt]=0

struc_bspline must be either 0 or 1.

struc_fit

Brain extraction threshold.

Routine: FBE

The fractional intensity threshold determines how much of an image will be retained after non-brain voxels are zeroed during the FSL-based FBE routine. It is not used for ANTs-based brain extraction. A more liberal mask can be obtained using a lower fractional intensity threshold. The fractional intensity threshold should be a positive number greater than 0 and less than 1.:

# Fractional intensity threshold of 0.3
struc_fit[cxt]=0.3

Freesufer run.

Routine: FSF

The freesufer can be run with addition of FSF to the procsess as

struc_process[cxt]=FSF-ACT

If the freesufer has be ran before, the directory of freesufer can be copied by including:

struc_freesurferdir[cxt]=/path/to/freesufer/directory

this can also be included in the cohort file. the cifti files for cortical thickness are generated.

struc_quick

Quick SyN registration.

Routine: REG, ACT.

SyN registration can be performed using an alternative, faster approach. Although the results are not of the same quality as standard SyN registration, this approach nonetheless typically results in a set of transforms that is adequate for many purposes.:

# Use quick SyN registration
struc_quick[cxt]=1

# Use default SyN registration
struc_quick[cxt]=0

struc_quick must be either 0 or 1.

struc_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
struc_rerun[cxt]=0

# Repeat all processing steps
struc_rerun[cxt]=1

struc_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
struc_cleanup[cxt]=1

# Retain temporary files
struc_cleanup[cxt]=0

struc_process

Specifies the order for execution of anatomical processing routines. Exercise discretion when using this option; unless you have a compelling reason for doing otherwise, it is recommended you use one of the default orders provided in the pre-configured design files.

The processing order should be a string of concatenated three-character routine codes separated by hyphens (-). Each substring encodes a particular preprocessing routine; this feature should primarily be used to selectively run only parts of the preprocessing routine.:

# Default processing routine for ANTs Cortical Thickness
struc_process[cxt]=ACT

# Minimal anatomical processing routine (for use with functional MRI)
struc_process[cxt]=BFC-ABE-REG-SEG

# Minimal anatomical processing routine using FSL instead of ANTs for brain extraction
struc_process[cxt]=BFC-FBE-REG-SEG

Permitted codes include:

• ACT: complete ANTs cortical thickness pipeline
• BFC: N4 bias field correction
• ABE: ANTs brain extraction
• FBE: FSL brain extraction
• SEG: Atropos image segmentation
• REG: registration to a template
• FSF: Freesufer or copy freesufer outputs from fmriprep if available

jlf

jlf is a module that uses the ANTs Joint Label Fusion algorithm to produce a

high-resolution anatomical segmentation of the subject’s anatomical data. Generates a subject-specific atlas of anatomical landmarks that can be used for regional quantification or network mapping. Presently, the module uses atlases of 103-OASIS labels.

jlf options

If to use OASIS atlas labels with skullstrip or not:

- jlf_extract[cxt]=1 # with skulltrip

If to keep each warped atlas, that is not advisable, it occupy space:

- jlf_keep_warps[cxt]=0 # dont keep

Fast joint label fusion is no recommended bcos of poor accuracy:

- jlf_quick[cxt]=1 # for fast jlf but no recommended

The cohort of OASIS label can be selected based on their ages:

- jlf_cohort[cxt]=All # Everyone
- jlf_cohort[cxt]=YoungAdult22  # Age range of 18-34
- jlf_cohort[cxt]=Older18  # Age range of 23-90
- jlf_cohort[cxt]=SexBalanced20  #All male subjects (ages 20-68) plus 10 of the female subjects.
- jlf_cohort[cxt]=Subset24 # A subset for general use, slightly more balanced on sex
- jlf_cohort[cxt]=Younger24 #Maintains the same 2:1 female:male ratio of the original, but biased towards younger subjects

Tthe number of cpu cores, the default is 2:

- jlf_ncpu[cxt]=2

Configuring parallelisation,very fast:

- jlf_parallel[3]=1

Outputs

The expected outputs are:

- prefix_Intensity.nii.gz # atlas intensity
- prefix_Labels.nii.gz # atlas labels
- prefix_TargetMaskImageOr.nii.gz # target mask that cover all atlas
- prefix_LabelsGMIntersect.nii.gz # refined atlas with grey matter mask

gmd

gmd computes a voxelwise grey matter density map [based on previous work by Dr. Stathis Gennatas and colleagues](https://www.ncbi.nlm.nih.gov/pubmed/28432144). Grey matter density is loosely defined as the probability that each voxel is a part of the grey matter as determined using an iterative, priorless segmentation in ANTs Atropos.

The gmd module is operational but not configurable.

gmd_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
gmd_rerun[cxt]=0

# Repeat all processing steps
gmd_rerun[cxt]=1

gmd_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
gmd_cleanup[cxt]=1

# Retain temporary files
gmd_cleanup[cxt]=0

Expected outputs

The expected outputs from gmd include the following:

- prefix_gmd.nii.gz # grey matter density
- prefix_probabilityCSF.nii.gz  # CSF probability map
- prefix_probabilityGM.nii.gz   # grey matter probability map
- prefix_probabilityWM.nii.gz  # white matter probability map
- prefix_raw.nii.gz   # raw image
- prefix_segmentation3class.nii.gz  # 3-class tissue segmentation

if the freesurfer is included in the struc module, cifti files are generated for GM:

- prefix_gmd_rh.cort.gii # right gmd surface
- prefix_gmd_lh.cort.gii # left gmd surface
- prefix_gmd.dscalar.nii # scalar values of right and left hemispheres

norm

norm moves 4D and 3D images from input bold space into standard template, usually MNI(2mm or 1mm). This require more disk space.

norm_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
norm_rerun[cxt]=0

# Repeat all processing steps
norm_rerun[cxt]=1

norm_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
norm_cleanup[cxt]=1

# Retain temporary files
norm_cleanup[cxt]=0

Expected output

The main outputs of norm include ::

• prefix_std.nii.gz the residulaised bold signal in template space
• prefix_maskStd.nii.gz the brain mask in template space
• prefix_referenceVolumeBrainStd.nii.gz reference volume brain in template space
• template.nii.gz the template image, usually MNI

Other nifti image outputs depend on derivattive outputs such reho and alff

There are quality control measures obtained to show the qulaity of registration to template space::

• prefix_seq2std.png picture of coregiratipon of template and BOLD signal
• prefix_normCoverage.txt Coverage index between template and reference volume
• prefix_normCrossCorr.txt Cross correlation between template and reference volume
• prefix_normDice.txt Dice Coefficient between template and reference volume
• prefix_normJaccard.txt Jaccard Coefficient between template and reference volume

roiquant

roiquant performs ROI-wise quantification of voxelwise metrics. For each provided atlas or parcellation of the brain, it produces a table of values for each region of that parcellation. While many modules include internal routines for ROI-wise statistics, this module centralises all ROI-wise measures in a single routine. It accepts any number of ROI maps or parcellations, then computes, for each voxelwise metric, the mean across all voxels in each ROI of each provided parcellation.

roiquant_atlas

Brain atlas or parcellation.

Contains a comma-separated list of the names of the atlases over which regional values should be computed. The atlases should correspond to valid paths in $XCPEDIR/atlas or another appropriate $BRAINATLAS directory.:

# Use the Power 264-sphere parcellation only
roiquant_atlas[cxt]=power264

# Use both the Power 264 atlas and the Gordon atlas
roiquant_atlas[cxt]=power264,gordon

# Use the 400-node version of the Schaefer atlas
roiquant_atlas[cxt]=schaefer400

# Use all available resolutions of the Schaefer atlas
roiquant_atlas[cxt]=schaefer

# Use all available atlases
roiquant_atlas[cxt]=all

roiquant_globals

Compute mean values over the brain and tissue compartments.

It is also possible to compute the average values over voxels in the entire brain and over voxels in each tissue compartment from a provided anatomical segmentation (e.g., white matter, grey matter, CSF). The flag roiquant_globals instructs the roiquant module whether these values should also be tabulated.:

# Include global means
roiquant_globals[cxt]=1

# Do not include global means
roiquant_globals[cxt]=0

roiquant_vol

Compute parcel volumes.

The volume of each parcel can be computed by registering the parcellation or atlas into the subject’s native space, counting the number of voxels in each parcel, and finally multiplying the number of voxels by the voxel dimension. This can be more useful for parcellations that are data-driven, such as those produced by atlas fusion techniques.:

# Compute volumes
roiquant_vol[cxt]=1

# Do not compute volumes
roiquant_vol[cxt]=0

roiquant_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
roiquant_rerun[cxt]=0

# Repeat all processing steps
roiquant_rerun[cxt]=1

roiquant_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
roiquant_cleanup[cxt]=1

# Retain temporary files
roiquant_cleanup[cxt]=0

fcon

fcon models the functional connectome by extracting an adjacency matrix from a voxelwise time series image. To do this, fcon requires a brain atlas, or a parcellation of the brain’s voxels into regions of interest (network nodes). First, the local mean timeseries within each network node is extracted. The connectivity between time series is subsequently used to define the edges of an adjacency matrix over the parcellation. Currently, static connectivity is estimated using the Pearson correlation but alternative metrics will likely be introduced in the future.

fcon_atlas

Brain atlas or parcellation.

Contains a comma-separated list of the names of the atlases over which the functional connectome should be computed. The atlases should correspond to valid paths in $XCPEDIR/atlas or another appropriate $BRAINATLAS directory. Each atlas will be warped from its coordinate space into the analyte image space, after which the mean time series will be computed across each parcel or atlas label. fcon will execute for all partial string matches.:

# Use the Power 264-sphere parcellation only
fcon_atlas[cxt]=power264

# Use both the Power 264 atlas and the Gordon atlas
fcon_atlas[cxt]=power264,gordon

# Use the 400-node version of the Schaefer atlas
fcon_atlas[cxt]=schaefer400

# Use all available resolutions of the Schaefer atlas
fcon_atlas[cxt]=schaefer

# Use all available atlases
fcon_atlas[cxt]=all

fcon_metric

Connectivity metric.

As of now, you’re stuck with the Pearson correlation, so this effectively does nothing.:

# Use the Pearson correlation
fcon_metric[cxt]=corrcoef

fcon_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
fcon_rerun[cxt]=0

# Repeat all processing steps
fcon_rerun[cxt]=1

fcon._cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
fcon_cleanup[cxt]=1

# Retain temporary files
fcon_cleanup[cxt]=0

Expected output

The main outputs are::

• prefix_{atlas_name}_network.txt # correlation matrix in vector form
• prefix_{atlas_name}.net # Pajek adjacency matrix
• prefix_{atlas_name}_ts.1D # Nodal time series
• prefix_{atlas_name}.nii.gz # atlas in input BOLD signal space

Other outputs depend on the issues such as poor registration of atlas to BOLD image space::

• prefix_missing.txt # index of nodes that bad, out of coverage of bold

qcfc

qcfc computes benchmark measures for a functional connectivity processing stream. Measures include (i) QC-FC correlations of functional connections with motion (number and fraction of related edges and absolute median correlation), (ii) distance-dependence of residual motion artefact, (iii) an estimate of the degrees of freedom lost through denoising procedures, and (iv) voxelwise activation timeseries plots for a set of example subjects. qcfc is divided into subject-level and group-level modules. The subject-level module collates subject-level estimates of data quality and produces the voxelwise plot, while the group-level module computes QC-FC correlations and distance-dependence.

qcfc_atlas

Brain atlas or parcellation.

Contains a comma-separated list of the names of the atlases over which QC-FC correlations should be computed. The atlases should correspond to valid paths in $XCPEDIR/atlas or another appropriate $BRAINATLAS directory. All atlases listed here must be run through the fcon module before they can be used here.:

# Use the Power 264-sphere parcellation only
qcfc_atlas[cxt]=power264

# Use both the Power 264 atlas and the Gordon atlas
qcfc_atlas[cxt]=power264,gordon

# Use the 400-node version of the Schaefer atlas
qcfc_atlas[cxt]=schaefer400

# Use all available resolutions of the Schaefer atlas
qcfc_atlas[cxt]=schaefer

# Use all available atlases
qcfc_atlas[cxt]=all

qcfc_sig

Correction for multiple comparisons.

Because QC-RSFC correlations are computed at every edge in each graph, the chance of non-significant results being falsely reported as significant is elevated in proportion to the number of edges. The risk of false positives can be reduced by taking into account the number of comparisons being made and applying a correction to the reported p-values. Correction for multiple comparisons can be based either on the Bonferroni correction (strictest) or on the false discovery rate.:

# Use the false discovery rate
qcfc_sig[cxt]=fdr

# Use Bonferroni correction
qcfc_sig[cxt]=bonferroni

# No correction for multiple comparisons
qcfc_sig[cxt]=none

qcfc_custom

Custom time series for plot.

When the qcfc module produces a voxelwise time series plot for each subject (Power, 2017), by default it also plots framewise motion estimates and DVARS for reference. These default plots can be supplemented with custom time series provided by the user. For instance, if task-constrained connectivity is being computed, it could be useful to include a plot the framewise task model. qcfc_custom should be formatted as <name of time series>:<path to 1D file containing time series>:<threshold for acceptable quality>, using the colon as delimiter. If a threshold is not appropriate for the current time series, then format as <name of time series>:<path to 1D file containing time series>.:

# No custom time series
qcfc_custom[cxt]=

# Plot a framewise task model
qcfc_custom[cxt]=task:/path/to/task/estimate.1D

# Plot a framewise task model specified in the cohort variable tstask
qcfc_custom[cxt]=task:${tstask[sub]}

# Separately plot two different task models
qcfc_custom[cxt]=task1:${tstask1[sub]},task2:${tstask2[sub]}

qcfc_confmat and qcfc_conformula

QC-FC: Covariates and model.

When QC-RSFC correlations (motion-connectivity correlations) are computed, any covariates specified here will be included in the model. This can help to disentangle the effects of motion from those of variables that are often related to motion, such as age and sex.

The covariates file (qcfc_confmat) should be formatted as a .csv file that includes a header specifying variable names. Each subject’s identifying variables (fields in the main cohort file that do not correspond to images or files) should be included, as should covariate values for each subject. Fields should be comma-separated. An example is provided below. The covariate model (qcfc_conformula) should be formatted as a valid R formula. Any categorical variables (e.g., diagnosis) should be specified as a factor. It is not necessary to specify the inclusion of subject motion in the model; motion will always be included.:

# No covariates
qcfc_confmat[cxt]=
qcfc_conformula[cxt]=

# Use age and diagnosis as covariates
qcfc_confmat[cxt]=/path/to/covariates/file.csv
qcfc_conformula[cxt]=age+factor(diagnosis)

Example covariates file

The contents of an example covariates file are provided here. Any identifier columns present in the cohort file must also be present in the covariates file (here, id0 and id1). Remaining columns in the:

id0,id1,age,sex
ACC,001,217,0
ACC,002,238,1
ACC,003,238,1
DSQ,001,154,0
CAT,001,176,1

qcfc_rerun

Ordinarily, each module will detect whether a particular analysis has run to completion before beginning it. If re-running is disabled, then the module will immediately skip to the next stage of analysis. Otherwise, any completed analyses will be repeated.If you change the run parameters, you should rerun any modules downstream of the change.:

# Skip processing steps if the pipeline detects the expected output
qcfc_rerun[cxt]=0

# Repeat all processing steps
qcfc_rerun[cxt]=1

qcfc_cleanup

Modules often produce numerous intermediate temporary files and images during the course of an analysis. In many cases, these temporary files are undesirable and unnecessarily consume disk space. If cleanup is enabled, any files stamped as temporary will be deleted when a module successfully runs to completion. If a module fails to detect the output that it expects, then temporary files will be retained to facilitate error diagnosis.:

# Remove temporary files
qcfc_cleanup[cxt]=1

# Retain temporary files
qcfc_cleanup[cxt]=0

Expected output

The main output of qcfc are::

• prefix_depthMap.nii.gz # layer of tissue segmentattion with depth values
• prefix_dvars*.1D # dvars obtained from residualised bold image
• prefix_tdof.txt # number of temporal degree of freedom lost
• prefix_voxts.png # graphical summary of quality assessment measures
• prefix_motionDVCorr.txt # corerelation between dvars and rms ( before regression)

cbf

cbf module computes the mean CBF and CBF timeseries by subtracting label-conttol pairs and modeled by the kinetic model. The module requires some parameters to be specified and standard parameters are supplied if those parameters are not provided.

cbf_first_tagged

Volume label The cbf_first_tagged identifies which pair of volume is label or control volume. If `cbf_first_tagged is 1, that means the first of pair volume is label and the second is control and vice versa.:

# the first volume is label
cbf_first_tagged[cxt]=1

# the first volume is control
cbf_first_tagged[cxt]=0

cbf_perfusion

Labelling approach methods.

As of now, only two popular label strategies are implemente in xcpEngine .:

# for pulsed ASL (PASL)
cbf_perfusion[cxt]=pasl

# for pseudio-continous ASL (CASL/PASL)
cbf_perfusion[cxt]=casl

PASL is default if none is supply.

cbf_m0_scale

M0 scale.

If the M0 scan is included and acquired at different scale to ASL acquisition, the user can supply the M0 scale. if there is no M0, cbf_m0_scale is set to 1, and average control volume is used as reference:

# scale
cbf_m0_scale[cxt]=1

cbf_lambda

The lambda is the blood-brain partition coefficient that scales the signal intentisty of the tissues to that of the blood. The common or standard value is ƛ=0.90 ml/g.:

#
cbf_lambda[cxt]=0.9

cbf_pld, cbf_tau

These two parameters are applicable to only CASL/PCASL. the cbf_tau is the label duration and cbf_pld is the post

labeling delay time. Both are expressed in seconds.:

#
cbf_tau[cxt]=1.8
cbf_pld[cxt]=1.8

cbf_t1blood, cbf_alpha

cbf_t1blood is the longitutdinal relaxation time of the blood in seconds and the standard value denpends on the field strength of MRI machine. For 3T and 1.5T, the standard cbf_t1blood values are 1.650s and 1.350s respectively. The cbf_alpha is the labelling efficiency and values are different for PASL and CASL/PCASL. The standard value is 0.85 for CASL/PCASL and 0.98 for PASL.:

#
cbf_t1blood[cxt]=1.65 # for 3T MRI
cbf_alpha[cxt]=0.85 # for PCASL

Expected output

The main outputs are::

• prefix_cbf.nii.gz # mean cbf
• prefix_cbf_ts.nii.gz # cbf time series
• prefix_cbfR.nii.gz # relative mean cbf
• prefix_cbfZ.nii.gz # zscore mean cbf
• prefix_sub-1_cbf_tsnr.nii.gz # temporal signal to noise ratio of cbf

basil

Basil module computes the CBF and the derivatives using Bayesian inference method for the kinetic model inversion. It also part of FSL and can aslo be run independently.

basil_perfusiion

Labelling approach methods.

As of now, only two popular label strategies are implemented:.:

# for pulsed ASL (PASL)
basil_perfusion[cxt]=pasl

# for pseudio-continous ASL (CASL/PASL)
basil_perfusion[cxt]=casl

PASL is default if none is supply.

basil_inputformat

Volume label The basil_inputformat identifies which pair of volume is label or control volume. There are three types- tc (label-control), ct(control-label) and diff (cbf).:

 # the first volume is label
 basil_inputformat[cxt]=tc

 # the first volume is control
 basil_inputformat[[cxt]=ct

# each volume is cbf, already substracted
 basil_inputformat[[cxt]=diff

basil_spatial and basil_pvc

If the spatial regularization (basil_spatial) by kernel and the partial voulme correction (basil_pvc) are require, they are set to 1s or otherwise 0s

# spatial regulaization
basil_spatial[cxt]=1

# Partial volume correction
basil_pvc[cxt]=1

basil_m0_scale

M0 scale.

If the M0 scan is included and acquired at different scale to ASL acquisition, the user can supply the M0 scale. if there is no M0, basil_m0_scale is set to 1, and average control volume is used as reference/M0:

# scale
basil_m0_scale[cxt]=1

basil_lambda

The lambda is the blood-brain partition coefficient that scales the signal intentisty of tissues to that of blood. The common or standard value is ƛ=0.90 ml/g.:

#
basil_lambda[cxt]=0.9

basil_pld and basil_tis

These are applicable to only CASL/PCASL. basil_pld is the post labeling delay time in seconds and basil_tis is the invertion time. The invetion time is the sum of label duration and post labelling delay. BASIL accepts multiple pld and tis separated by commas:

# single pld
basil_pld[cxt]=1.8
basil_tis[cxt]=3.6 # this implies label duration is 1.8 scale

# multiple plds
basil_pld[cxt]=0.25,0.5,1,1.5
basil_tis[cxt]=2.05,2.55,3.55,5.05 # this implies label duration is 1.8 scale

basil_t1blood, basil_alpha

basil_t1blood is the longitutdinal relaxation time of blood in seconds and the standard value denpend on the field strength of MRI machine. For 3T and 1.5T, the standard cbf_t1blood values are 1.650s and 1.350s respectively. The basil_alpha is the labelling efficiency and values are different for PASL and CASL/PCASL. The standard value is 0.85 for CASL/PCASL and 0.98 for PASL.:

#
basil_t1blood[cxt]=1.65 # for 3T MRI
basil_alpha[cxt]=0.85 # for PCASL

basil_MOTR

This is for the TR of MO scan if it is available. It is very important for the purpose of calibration and also account for shorter TR value. The default is 3.2s but it also read from the MO scan image.

Expected output

The main outputs are::

• prefix_cbfbasil.nii.gz # mean basil cbf
• prefix_cbfpv.nii.gz # partial volume corrected cbf
• prefix_cbfspatial.nii.gz # spatial regularized cbf

All thier respective relative (R) and zscore (Z).

scorescrub

scorescrub module detects and discards oultier cbf volumes and robust Bayesian estimation of CBF by removing the white noise as opposed to outlier rejection. It requires prior run of cbf module

score_thresh

The threshold for structural probabilty maps. The default is 0.90.::

scorescrub_thresh=0.9

Expected output

The main outputs are::

• prefix_cbfscore.nii.gz # mean score cbf
• prefix_cbfscore_ts.nii.gz # cbf time series after discarding the volumes that might contribute to artifact
• prefix_cbfscoreR.nii.gz # relative mean score cbf
• prefix_cbfscoreZ.nii.gz # zscore mean score cbf
• prefix_cbfsrub.nii.gz # mean scrub cbf
• prefix_cbfscrubR.nii.gz # relative mean scrub cbf
• prefix_cbfscrubZ.nii.gz # zscore mean scrub cbf
• prefix_sub-1_cbfscore_tsnr.nii.gz # temporal signal to noise ratio of cbf score

Utilities

Unlike Modules, utilities are standalone image processing scripts that have been designed for use both inside and outside the pipeline context. Some utilities are wrapper scripts that combine binaries from ANTs, FSL, and AFNI to simplify certain functionalities. Other utilities are R scripts that provide functionalities outside of other common image processing libraries.

There are many undocumented utilities if you look in the code. Listed below are the documented utilities.

Denoising and data quality

• QCFC : a utility for quality control measures of functional connectitivty
• QCFC Distance Dependence : a utility to determine the distance dependence of motion artifact on functinal connectivity.
• Combine output files : a utility for combining the output of all subjects simiar file into one file for further analysis in other platform such as Excel, matlab, SPSS, R etc.

Image utilities: voxelwise and regional

• Seed-based connectivity: This computes functional connectitivty between a region or mask and all voxels with in the brain.
• Erodespare : This can be a useful tool for generating tissue maps for nuisance regression in a way that minimizes partial volume effects
• ROI Quantification: This tool allows users to use customed atlases to generate region values

Combine output files

The xcpEgine provides a standalone script that help users to assemble results from each subject and combine to a single file for further analysis in any other platform such as Excel, MATLAB or SPSS. There is ${XCPEDIR}/utils/combineOutput that combine inidcated file from all the subject in the output directory. This can be very important to assemble especially quality control file (/{prefix}_quality.csv) and roiquant outputs

${XCPEDIR}/utils/combineOutput \
-p $outputdir  \  # all subjects directory  after running xcpEngine
-f "*quality.csv" \  # the extention of the file users want to combine
-o XCP_QAVARS.csv  # the output file in csv

The output file will consist of the header and the all subjects correposnding value:

id1,id2,relMeanRMSMotion,nSpikesRMS,nSpikesFD,nSpikesDV,relMaxRMSMotion
ses-01,sub-01,0.07876904,1,0,0,0.2795057
ses-01,sub-02,0.06421208,7,2,0,0.3267097
ses-01,sub-06,0.02349,0,1,0,0.1087066

QCFC

Quality control for functional connectivity.

qcfc computes, for each edge in the connectome, the partial correlation (across subjects) of motion with the strength of that edge, after controlling for the effects of any user-provided covariates. qcfc is currently written as an R script (utils/qcfc.R). It requires as input a sample matrix containing motion estimates for each subject

Output

The root output path, <output root>, is specified as the argument to the -o option. Outputs of qcfc include:

• <output root>.txt: A matrix containing the QC-FC correlation for each edge in the input matrix from the connectivity column provided to the -s argument.
• <output root>_thr.txt: (if -r is true) The QC-FC matrix from above, thresholded to include only significant edges. This can be used to plot glass brain visualisations of significant edges, for instance using BrainNetViewer.
• <output root>_absMedCor.txt: (if -q is true) The absolute median QC-FC correlation over all edges.
• <output root>_nSigEdges.txt, <out>_pctSigEdges.txt: (if -q is true) The number and percentage of edges with significant QC-FC correlations.
• <output root>.svg: (if -f is true) A visualisation of the QC-FC distribution).

Input arguments

Example call from Docker::

docker run --rm -it \
  --entrypoint /xcpEngine/utils/qcfc.R \
  pennbbl/xcpEngine:latest \
  –c <cohort> \
  -o <output root> \
  [-s <multiple comparisons correction> \
   -t <significance threshold> \
   -n <confound> \
   -y <conformula>]

Optional arguments are denoted in square brackets ([]).

-c: Cohort

The primary input to qcfc.R (<cohort>) should be a subject list that includes a separate column for each subject identifier and two additional columns corresponding to subject movement (or another scalar-valued quality control variable) and functional connectivity. Each row in the subject list should correspond to a separate subject. Each column containing identifiers should have a header beginning with the string id, while 2 additional columns should have the headers motion and connectivity. In each subject’s motion column, enter the subject’s mean framewise displacement (or another scalar-valued quality control variable). In each subject’s connectivity column, enter the path to the subject’s connectivity matrix (or any vector of values that may be impacted by subject motion). Save the subject list in .csv format. An example subject list is provided here::

id0,id1,motion,connectivity
ACC,001,0.0391,processedData/ACC_001_fc/connectome.txt
ACC,002,0.0455,processedData/ACC_002_fc/connectome.txt
ACC,003,0.0367,processedData/ACC_003_fc/connectome.txt
DSQ,001,0.1532,processedData/DSQ_001_fc/connectome.txt
CAT,001,0.0811,processedData/CAT_001_fc/connectome.txt

-s: Correction for multiple comparisons

Default value: ``fdr``

The type of correction for multiple comparisons can be specified as fdr, bonferroni, or none. When evaluating only a few subjects, it may be more diagnostically informative to disable multiple comparisons correction (-s none).

-t: Alpha significance threshold

Default value: ``0.05``

The maximal p-value threshold necessary to establish a QC-FC relationship as significant can be specified as an argument to the -t option.

-n and -y: Confound matrix and formula

The values of any model covariates that motion effects might alias (such as age and sex) should be included in another file containing the same subject identifiers as the subject list (argument to -s). The file containing model covariates should be provided as an argument to the -n option, and the formula for the model should be provided as an argument to the -y option, with any categorical variables specified as factors (see example below). (If the user wishes to obtain only the direct correlation between motion and functional connectivity, then no formula or covariates file is necessary.)

For example, to control for the participants’ age and sex when computing motion effects, prepare a file containing the same identifiers and id column headers as the subject list (argument to -s), with additional columns for each of the covariates to be considered. In the example below, age is defined in months and sex is coded as a binary variable::

id0,id1,age,sex
ACC,001,217,0
ACC,002,238,1
ACC,003,238,1
DSQ,001,154,0
CAT,001,176,1

If this file is saved as sample-covariates.csv, then call qcfc.R as above, with the additional argument to -n set to sample-covariates.csv and the argument to -y set to:

age+factor(sex)

Note that sex, treated as a categorical variable in this toy example, is specified as a factor. If the data set contains repeated measures (e.g., multiple scans from the same subject), then the subject identifier can be included in the model specification (argument to -y) as a random intercept::

age+factor(sex)+(1|id0)

-o: Output root

A prefix that points to a valid directory, where all outputs will be written after they are computed.

-d: Data root path

It is sometimes desirable to define paths relative to some root directory instead of as absolute paths in order to facilitate data sharing and reproduction of results. If the paths in the connectivity column of the subject list (argument to -s) are defined in a relative manner, the root path relative to which they are defined should be provided as the argument to the -d option.

-r: Save thresholded matrix

Default value: ``true``

A logical-valued option indicating whether qcfc should save the QC-FC matrix thresholded to include only significant edges. This matrix can, for instance, be used to visualise only significant edges using a tool such as BrainNetViewer.

-q: Save QC-FC summary indices

Default value: ``true``

A logical-valued option indicating whether qcfc should save indices that summarise the QC-FC distribution. These indices include the absolute median correlation and the number and fraction of significant QC-FC relationships.

-f: Save QC-FC distribution plot

Default value: ``true``

A logical-valued option indicating whether qcfc should save a density plot of the QC-FC distribution. If ggplot2 and reshape2 are not installed, then this option is automatically disabled.

QCFC Distance Dependence

Distance-dependence of QC-FC measures.

qcfcDistanceDependence computes the distance-dependence of QC-FC relationships previously estimated using qcfc. (Although it was designed for diagnosing the distance-dependent profile of motion artefact, qcfcDistanceDependence can be used to compute the distance-dependence of any edgewise measure.)

qcfcDistanceDependence executes in the following order, using its inputs as follows:

1. Read in the atlas specified by the -a flag.
2. Call cmass to estimate the centre of mass of each node in the atlas.
3. Call distmat to estimate the pairwise Euclidean distance between nodal centers of mass, saving the output as a distance matrix to the path specified by the argument to -d.
4. Correlate the computed pairwise distances with the test values provided as an argument to -q, saving the overall correlation to the path specified by the argument to -o.
5. Plot a cloud of edgewise values with the Euclidean distance on the abscissa and with the test value on the ordinate; write the plot to the path specified by the argument to -f.

Output

• The distance-dependence of provided test values, defined as the edgewise correlation coefficient between the test values and Euclidean distance (specified by argument to -o).
• A matrix of internodal Euclidean distances (specified by argument to -d).
• A plot of the relationship between test values and Euclidean distances (specified by argument to -f).

Input arguments

Running from Docker::

docker run --rm -it --entrypoint \
/xcpEngine/utils/qcfcDistanceDependence \
  pennbbl/xcpengine:latest \
  –a <atlas> \
  -q <test values> \
  -o <output path> \
  [-d <output distance matrix> -f <output correlation plot> -i <intermediate output>]

Optional arguments are denoted in square brackets ([]).

-a: Atlas

The atlas over which inter-nodal distances should be computed. This atlas should also have been used to define the test values.

-q: Test values

A file containing an edgewise vector of values to evaluate for distance-dependence. Often, these will be the QC-FC estimates produced by the qcfc utility.

-o: Output

The path where the overall correlation coefficient between distance and test values should be saved.

-d: Distance matrix

The path where the matrix of distances between each pair of nodes in the provided atlas (argument to -a) is saved.

-f: Save correlation plot

The path where the scatter plot of edgewise distance and test values will be saved. If ggplot2 and reshape2 are not installed, then the plot is automatically disabled.

-i: Intermediate output path

A path where erodespare stores temporary files. If your machine or file system has a designated space for temporary files (e.g., /tmp), then using this space can substantially improve I/O speed. Note, if running through Docker or Singularity your directories will need to be mounted correctly.

Seed-based connectivity

Seed-based connectivity provides the opportunity to compute the functional connectivity between the a point/region and all other voxels in the brain. The users can specify a 3 coordinates point in mm of a template or a mask with the same dimension and orietation of a template. If no template is provided, MNI152_T1_2mm_brain.nii.gz will be used as default template.

The seed connectivity is done with ${XCPEDIR}/utils/seedconnectivity:

${XCPEDIR}/utils/seedconnectivity   \
-i  input4Dimage  \     #  4D inputimage usually residualised or image or filtered image
-s  x,y,z   \           # 3 cordinates  or a mask (--s=/path/to/mask)
-o  outputpath  \       # output directory
-r  radius \            # radius of the mask for 3 points cordinates, r=5 is default
-k  kernel \            # kernel size if the image is not filtered
-t  template  \         # template; MNI152_T1_2mm_brain.nii.gz is default
-n  seed_name \         # SEED will used as default
-p  subject identifiers

The first three opions (-img,–sand -o ) are mandatory. If the input image is residualised BOLD image (regress/sub-*residualized.nii.gz) from regress module which is not spatially smooth, theuser is encourage to smooth the image. Kernel of 5mm FHWM is preffered for good connectivity results.

Expected outputs A sub-directory of seed_names is created in seed directory. The directory constist of:

-prefix_connectivity_{seed_name}_seed.nii.gz # seed mask in BOLD space
-prefix_connectivity_{seed_name}_smK.nii.gz # seed correlation map, K is kernel size
-prefix_connectivity_{seed_name}Z_smK.nii.gz # Fisherz transfromed seed correlation map
-prefix_connectivity_{seed_name}_ts.1D # time series of seed point/mask

ROI Quantification

Region of Interest Quantification.

roiquant uses atlas provided in design file to compute the regional derivative values especially for reho and alff outputs. The users can also use custom atlases to generate region values from the output. Beware that your directories need to be mounted in the container (see xcpEngine containers (Extra Info))

The customed atlas and the input image such as rehoZ must have the same dimension and orientation. This can be done with ${XCPEDIR}/utils/quantifyAtlas.:

docker run --rm -it --entrypoint /xcpEngine/utils/quantifyAtlas   \
    pennbbl/xcpengine:latest \
 -v  inputfile  \  # this is input image 3D
 -s  mean \ # the statistics, the defualt is the mean of each roi in atlas
 -a  atlas \ # the atlas in 3D
 -n  atlas_name \ # atlas name : option
 -p  id1,id2 \ # subject idenfiers  : option
 -r  region_names \ # name of regions in atlas : option
 -o  output_path.txt

The output will consist of header with ids and region names or numbers with the corresponding values atlas rois as show below:

id1,id2, reho_mean_region1,reho_mean_region2,...
ses-01,sub-1, 0.3456,0.7894,...

Similarly, users can extract time series from BOLD image with the customized atlas. This is similar to the output in fcon module. It is called:

docker run --rm -it --entrypoint /xcpEngine/utils/roi2ts.R   \
   pennbbl/xcpengine:latest \
   -i   $input    \  # the 4D bold image
   -r   $atlas       \ # the atlas in the same orientation as bold
   -l   $atlas_label \ # atlas region label  but not compulsory
   >>    $output.txt   # output file

Erodespare

Label erosion tool.

erodespare erodes a subset of labels (or range of values) in a provided image such that only the deepest k percent of voxels in the label set are retained. erodespare erodes an image while sparing the deepest voxels. This can be a useful tool for generating tissue maps for nuisance regression in a way that minimizes partial volume effects and decreases the correlation between tissue-based nuisance regressors and the global signal.

erodespare executes in the following order, using its inputs as follows:

1. Read in the image specified by the -i flag
2. Binarise the image such that voxels with the values specified by the -v flag are set to 1 while all other voxels are set to 0.
3. Compute a fractional depth map such that, for instance, a voxel in the 33rd percentile of deepest voxels is assigned a value of 33
4. Threshold the depth map according to the criterion set by the -r flag. (This is the erosion step.)
5. Binarise the map and write the eroded mask to the path specified by -o

Output

A binary-valued mask indicating whether each voxel belongs to a specified label set following erosion to the deepest k percent.

Input arguments

-i: Input mask

A mask, image, or label set that the user wishes to erode.

-o: Output path

A path in a valid directory, where the eroded map will be written once it is computed.

Optional input arguments

-r: Retention criterion

Default value: 5 percent

The percent of voxels that should be retained in the eroded mask. The argument should be a percent value, not a fractional value (e.g., 5 not 0.05 for 5 percent). For instance, a value of 5 will erode all but the deepest 5 percent of voxels. (At least 5 percent of voxels will be preserved.)

-v: Value set

If this variable is defined, then the specified range of labels will be extracted from the provided mask prior to erosion. For instance, -v 2,4 will extract cortical and deep grey matter from a standard 6-class segmentation. Syntax follows the -v specification in val2mask. If this option is not provided, then a mask comprising all nonzero values from the input will be generated and eroded.

-n: Intermediate output path

A path where erodespare stores temporary files. If your machine or file system has a designated space for temporary files (e.g., /tmp), then using this space can substantially improve I/O speed.

Developing/Debugging XCP

The easiest way to debug or develop XCP is to download the source code from GitHub and mount it in an xcpEngine Docker or Singularity container. If you are on a laptop you will want to use Docker, whereas if you are on a HPC cluster you will want to use Singularity.

Downloading the source code

To download the master branch from GitHub, you can do the following:

git clone https://github.com/PennBBL/xcpEngine.git

Now you can edit or add to the code however you’d like. xcpEngine depends on number of dependencies including ANTS, FSL, c3d, AFNI, R and Python packages. The main R packages require are RNifti, optparse, pracma, signal, and python packages require are numpy,nibabel,niworkflows, nilearn and matplotlib.

The enviroment should be set as follow in the bash profile:

XCPEDIR=/path/to/xcpEngine/sourcecode
FSLDIR=/path/to/fsldir
AFNI_PATH=/path/to/afni
C3D_PATH=/path/to/c3d
ANTSPATH=/path/to/ANTs

After setting the enviroment, it is require to reset the xcpEngine to link to those dependencies:

source ${XCPEDIR}/xcpReset

You can use docker or singularity image.

Patching a local copy of xcpEngine into a container

Assuming you’re in the same directory as when you ran git clone, you can now mount your local copy of xcpEngine into the container.:

docker run -it \
    -v `pwd`/xcpEngine:/xcpEngine \
    --entrypoint bash \
    pennbbl/xcpengine:latest

This will drop you into a shell inside the container, which contains all of xcpEngine’s dependencies and your local copy of the xcpEngine code. You can run the pipeline directly from inside this shell, but you will need to be certain that it has access to your data. Suppose your data is located on your laptop in /data/fmriprep, your cohort file is at /data/fmriprep/cohort.csv, the working directory should be /data/work and you want the output to go in /data/xcpOutput. You have to start Docker so that you can read and write from these locations. Do this by mounting your data directory in the container:

docker run -it \
  -v /data/fmriprep:/inputs \
  -v /data/xcpOutput:/output \
  -v /data/work:/work \
  -v `pwd`/xcpEngine:/xcpEngine \
  --entrypoint bash \
  pennbbl/xcpengine:latest

Then you can run xcpEngine in the container:

xcpEngine \
  -d /xcpEngine/designs/fc-36p.dsn \
  -c /inputs/cohort.csv \
  -i /work \
  -o /output

and the pipeline should run using the code in your local copy of xcpEngine.

Using singularity

Mounting directories in a container is not as simple using Singularity. Suppose you created a Singularity image using something like::

singularity build xcpEngine-latest.simg docker://pennbbl/xcpengine:latest

Assuming your data is in all the same locations as the laptop Docker example above, you can patch the local copy of the xcpEngine source code by:

singularity shell -B `pwd`/xcpEngine:/xcpEngine xcpEngine-latest.simg

Mounting data directories is somewhat trickier because the mount point must exist inside the container. One convenient location for binding data is /mnt.:

singularity shell \
  -B /data:/mnt \
  -B `pwd`/xcpEngine:/xcpEngine \
  xcpEngine-latest.simg

and you can make the call to xcpengine from inside the shell:

xcpEngine\
  -d /xcpEngine/designs/fc-36p.dsn \
  -c /mnt/fmriprep/cohort.csv \
  -i /mnt/work \
  -o /mnt/xcpOutput

This way you can make quick changes to the xcp source code and see how they would impact your pipeline without needing to create a new Singularity image.

Quality Control Dictionary

The quality control measures (prefix_quality.csv)

Coregsitration of Functional and T1w::

• coregCrossCorr - cross correlation
• CoregJaccard - Jaccard index
• CoregDice - Dice index
• CoregCoverage - Coverage index

Registration of T1w to Template:

• regCrossCorr - cross correlation
• regJaccard - Jaccard index
• regDice - Dice index
• regCoverage - Coverage index

Normalization of T1w/Functional to Template:

• normCrossCorr - cross correlation
• normJaccard - Jaccard index
• normDice - Dice index
• normCoverage - Coverage index

QC for anatomical:

• euler_number_rh,euler_number_lh - Eurler number if freesurfer is included
• meanGMD - mean of Grey matter density
• SignalToNoiseRatio - grey matter signal to noise ratio
• BackgroundKurtosis - background intensity Kurtosis
• GreyMatterKurtosis - grey matter intensity Kurtosis
• EntropyFocusCriterion - entropy focus criterion ( for ghost signals)
• CorticalContrasts - coritical contrasts between white matter and grey matter signals
• FGBGEnergyRatio - Foreground-to-background energy ratio
• ContrastToNoiseRatio - contrast to noise ratio
• WhiteMatterSkewness - WhiteMatter Skewness
• BackgroundSkewness - background intensity Kurtosis

Motion/spikes summary.::

• relMeansRMSMotion - mean value of RMS motion
• relMaxRMSMotion - maximum vaue of RMS motion
• nSpikesFD - number of spikes per FD
• nspikesDV - number of spikes per DV
• pctSpikesDV - percentage of spikes per DV
• pctSpikesFD - percentage of spikes per FD
• meanDV - mean DVARS

regression summary.::

• motionDVCorrInit - correlation of RMS and DVARS before regresion
• motionDVCorrFinal - correlation of RMS and DVARS after regresion
• nNuisanceParameters - total number of nuisance Parameters in addition to custom regressors
• nVolCensored - total number of volume(s) censored
• estimatedLostTemporalDOF - total degree of freedom lost

CBF quality evaluation index.::

• cbf_qei - cbf quality evalution index
• negativeVoxelsTS - total number of negative voxels in CBF timeseries
• negativeVoxels - total number of negative voxels in mean CBF
• cbfscore_qei - cbf score quality evaluation index
• cbfscrub_qei - cbf scrub quality evaluation index
• cbfbasil_qei - cbf basil quality evaluation index
• cbfspatial_qei - cbf basil spatial quality evaluation index
• cbfpv_qei - cbf with partial volume correction quality evaluation index
• nvoldel - number of volume deleted due to score
• negativeVoxels_basil - number of negative voxels of mean cbf basil
• cbftsnr - cbf temporal signal to noise ratio
• cbfscoretsnr - cbf score temporal signal to noise ratio

xcpEngine on Flywheel

The xcpEngine can be run on flywheel. The procedure is the same as runnning it on computers/clusters.

The design file is compulsory for any analysis. Preprocessing of BOLD data require prior preprocessing with FMRIPREP. The FMRIPREP output directory needs to be supplied as shown below.

xcpEngine input layout on Flywheel

---

The cohort file will be created base on the FMRIPREP output and/or img. The img is input directory for asl and structural image. The processing of ASL requires processed anatomical image from FRMIPREP (fmriprepdir) or structural processing output (antsct). The m0 is the M0 directory for CBF calibration if present. In the case of task-activation analysis, task_name and seission are required to be specified in the config of xcpengine gear.

Task-activation analysis

---

Running task-activation (FSL FEAT) analysis on flywheel with xcpEngine requires event files like FSL. The event file (in .txt) can be in any format accpetable by the FSL FEAT. The contrasts and corresponding weights are organized as shown in task.json below.:

{
   "eventname":["0back","1back","2back","inst"],
   "contrast" :{ "0back":          [1,0,0,0],
                 "1back":          [0,1,0,0],
                 "2back":          [0,0,1,0],
                 "2backvs0back":   [-1,0,1,0],
                 "1backvs0back":   [-1,1,0,0] }
 }

The above shown the event names ( “0back”,”1back”,”2back”,”inst”) and the contrast with corresponding weights. The task.json is zipped with all the event files:

0back.txt
1back.txt
2back.txt
inst.txt
task.json

The zipped file is attach to taskfile in the input directory of xcpengine gear on flywheel (check the figure above)

The length of the weight must be equal to the number of events as shown above.