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.