pipeline.cfg /.json

preprocessing-pipeline definition file

A preprocessing pipeline definition file lists the configuration options for preprocessing and denoising the functional and anatomical data.

These files can be stored in [.cfg] or [.json] format.

Preprocessing definition files may have a combination of the following fields:

#steps : list of preprocessing steps

sorted list of preprocessing/denoising steps (or keywords for individual pre-defined pipelines, see PIPELINES below)

PIPELINES:

                         default_mni : default MNI-space preprocessing pipeline                         default_mnifield : same as default_mni but with vdm/fieldmap information and indirect normalization                         default_mnidirectfield : same as default_mni but with vdm/fieldmap information and direct normalization                         default_ss : default subject-space preprocessing pipeline                         default_ssfield : same as default_ss but with vdm/fieldmap information                         default_ssnl : same as default_ss but with non-linear coregistration
                       INDIVIDUAL STRUCTURAL STEPS:                         structural_center : centers structural data to origin (0,0,0) coordinates                         structural_manualorient : applies user-defined affine transformation to structural data                         structural_manualspatialdef : applies user-defined spatial deformation to structural data                         structural_mask : masks structural data using inclusive or exclusive mask                         structural_segment&normalize : structural unified normalization and segmentation                          structural_segment&normalize&lesion : structural unified normalization and segmentation with lesion mask                                                                     (normalizes structural data and creates a modified TPM for functional                                                                     normalization that includes the lesion as an added tissue class)                         structural_normalize : structural normalization to MNI space (without segmentation)                         structural_normalize_preservemasks : structural normalization to MNI space with user-defined Grey/White/CSF masks                                                                      (normalizes structural data and applies same transformation to user-defined                                                                      Grey/White/CSF mask ROIs)                         structural_segment : structural segmentation (Grey/White/CSF tissue classes)
                       INDIVIDUAL FUNCTIONAL (or combined functional/structural) STEPS:                         functional_art : functional identification of outlier scans (from motion                                                                      displacement and global signal changes)                         functional_bandpass : functional band-pass filtering                         functional_center : centers functional data to origin (0,0,0) coordinates                         functional_coregister_affine : functional affine coregistration to structural volumes                         functional_coregister_nonlinear : functional non-linear coregistration to structural volumes                         functional_label : labels current functional files (to list of Secondary Datasets)                         functional_load : assigns current functional files (from list of Secondary Datasets)                         functional_manualorient : applies user-defined affine transformation to functional data                         functional_manualspatialdef : applies user-defined spatial deformation to functional data                         functional_mask : masks functional data using inclusive or exclusive mask                         functional_motionmask : creates functional motion masks (mean BOLD signal spatial                                                                      derivatives wrt motion parameters)                         functional_normalize_direct : functional direct normalization                         functional_normalize_indirect : functional indirect normalization (coregister to structural;                                                                      normalize structural; apply same transform to functionals)                         functional_normalize_indirect_preservemasks: functional indirect normalization with user-defined Grey/White/CSF masks                                                                     (coregister to structural; normalize structural; apply same transformation to                                                                      functionals as well as to Grey/White/CSF masks)                         functional_realign : functional realignment                         functional_realign_noreslice : functional realignment without reslicing                                                                      (applies transform to source header files)                         functional_realign&unwarp : functional_realignment + unwarp                                                                      (removes motion-by-inhomogeneity interactions)                         functional_realign&unwarp&fieldmap : functional_realignemnt&unwarp + distortion correction                                                                      (corrects static inhomogeneity distortions)                         functional_regression : denoising / removal of user-defined temporal components from BOLD timeseries (keeps                                                                      residuals of linear regression model)                         functional_removescans : removes user-defined number of initial scans from functional                         functional_roiextract : extraction of ROI timeseries (compute BOLD timeseres within ROI)                         functional_segment : functional segmentation (Grey/White/CSF tissue classes)                         functional_segment&normalize_direct : functional direct unified normalization and segmentation                         functional_segment&normalize_indirect : functional indirect unified normalization and segmentation                                                                     (coregister to structural; normalize and segment structural;                                                                      apply same transformation to functionals)                         functional_sliceintensity : functional slice-intensity correction (e.g. for sparse acquisition sequences)                         functional_slicetime : functional slice-timing correction (for continuous acquisition sequences)                         functional_smooth : functional spatial smoothing                         functional_smooth_masked : functional spatial masked-smoothing (spatial convolution with Gaussian kernel                                                                      restricted to voxels within custom functional mask                         functional_vdm_create : creation of vdm (voxel-displacement-map) from fieldmap dataset (reads 'fmap'                                                                      secondary functional dataset containing magnitude and phasediff images and                                                                      creates 'vdm' secondary functional dataset containing voxel-displacement map)
                        INDIVIDUAL SURFACE FUNCTIONAL STEPS:                         functional_surface_resample : resample functional data at the location of FreeSurfer subject-specific                                                                      structural cortical surface                         functional_surface_smooth : functional spatial diffusion of surface data                          functional_surface_coreg&resample : coregister&resample functional data at the location of FreeSurfer subject-specific                                                                      structural cortical surface
                       If steps is left empty or unset a gui will prompt the user to specify the desired preprocessing pipeline                        If steps points to an existing preprocessing-pipeline file (e.g. saved from CONN's GUI) the corresponding                         preprocessing-pipeline will be run
OPTIONS FOR INDIVIDUAL PREPROCESSING STEPS:
#affreg : (normalization) affine registration and regularizationapplies affine registration before normalization (mni|eastern|subj|none) ['mni' : affine registration with regularization to ICBM space template - European brains]
#art_thresholds : (functional_art) outlier detection thresholdsART thresholds for identifying outlier scans                                              art_thresholds(1): threshold value for global-signal (z-value; default 5)                                              art_thresholds(2): threshold value for subject-motion (mm; default .9)                          additional options: art_thresholds(3): 1/0 global-signal threshold based on scan-to-scan changes                                                                in global-BOLD measure (default 1)                                              art_thresholds(4): 1/0 subject-motion threshold based on scan-to-scan changes                                                                 in subject-motion measure (default 1)                                              art_thresholds(5): 1/0 subject-motion threhsold based on composite-movement                                                                 measure (default 1)                                              art_thresholds(6): 1/0 force interactive mode (ART gui) (default 0)                                              art_thresholds(7): [only when art_threshold(5)=0] subject-motion threshold                                                                 based on rotation measure                                              art_thresholds(8): N number of initial scans to be flagged for removal                                                                 (default 0)                             note: when art_threshold(5)=0, art_threshold(2) defines the threshold based on the translation                               measure, and art_threhsold(7) defines the threshold based on the rotation measure; otherwise                               art_threshold(2) defines the (single) threshold based on the composite-motion measure                              note: the default art_thresholds(1:2) [5 .9] values correspond to the "intermediate"                               (97th percentile) settings; to use the "conservative" (95th percentile) settings use                               [3 .5]; to use the "liberal" (99th percentile) settings use [9 2] values instead                             note: art needs subject-motion files to estimate possible outliers. If a 'realignment'                               first-level covariate exists it will load the subject-motion parameters from that first-                              level covariate; otherwise it will look for a rp_*.txt file (SPM format) in the same                               folder as the functional data                             note: subject-motion files can be in any of the following formats: a) *.txt file (SPM                               format; three translation parameters in mm followed by pitch/roll/yaw in radians);                               b) *.par (FSL format; three Euler angles in radians followed by translation parameters                               in mm); c) *.siemens.txt (Siemens MotionDetectionParameter.txt format); d) *.deg.txt (same                               as SPM format but rotations in degrees instead of radians)
#boundingbox : (normalization) bounding boxtarget bounding box for resliced volumes (mm) [-90,-126,-72;90,90,108]
#bp_filter : (functional_bandpass, functional_regression) band-pass filterLow- and High- frequency thresholds (in Hz)
#bp_keep0 : (functional_bandpass) band-pass filter treatment of average BOLD signal 0: removes average BOLD signal (freq=0Hz component); 1: keeps average BOLD signal in output independent of band-pass filter values; [1]
#coregtomean : (functional_coregister/segment/normalize) coregister to mean0: use first volume; 1: use mean volume (computed during                           realignment); 2: use user-defined source volume (see #coregsource_functionals field) [1]
#coregsource_functionals : (for functional_coregister/segment/normalize) user-defined source volume
#diffusionsteps : (surface_smooth) number of diffusion steps
#fwhm : (functional_smooth) Smoothing factor (mm) [8]
#interp : (normalization) target voxel interpolation method 0:nearest neighbor; 1:trilinear; 2 or higher:n-order spline [4]
#label : (functional_label) label of secondary dataset(note: alternatively use syntax #functional_label_as_<label>)
#load_label : (functional_load) label of secondary dataset(note: alternatively use syntax #functional_load_as_<label>)
#mask_names_anat : (structural_mask) name of ROI/maskif multiple ROIs, the intersection of all ROIs will be used as mask
#mask_inclusive_anat : (structural_mask) inclusive or exclusive mask1: inclusive ROI mask (keep voxels inside ROI); 0: exclusive ROI mask (keep voxels outside ROI) [1]
#mask_names_func : (functional_mask) name of ROI/maskif multiple ROIs, the intersection of all ROIs will be used as mask
#mask_inclusive_func : (functional_mask) inclusive or exclusive mask1: inclusive ROI mask (keep voxels inside ROI); 0: exclusive ROI mask (keep voxels outside ROI) [1]
#reg_names : (functional_regression) model regressorslist of first-level covariates to use as model regressors / design matrix (valid entries are                           first-level covariate names or ROI names)
#reg_dimensions : (functional_regression) number of components/dimensionslist of maximum number of dimensions (one value for each model regressor in reg_names)
#reg_deriv : (functional_regression) add temporal derivativeslist of 0/1/2 values (one value for each model regressor in reg_names): add first- or                           second- order derivatives to each model regressor
#reg_filter : (functional_regression) filter regressors list of 0/1 values (one value for each model regressor in reg_names): band-pass filter individual model regressors (filter specified in bp_filter field)
#reg_lag : (functional_regression) optimize lag   list of 0/1 values (one value for each model regressor in reg_names):                                              removes lagged regressor (estimating optimal lag between each regressor and the BOLD signal at each voxel)#reg_lagmax : (functional_regression) maximum lag  maximum lag (in seconds) when estimating optimal lag (see reg_lag) lags                                              between -reg_lagmax and +reg_lagmax are considered
#reg_detrend : (functional_regression) add detrending1: adds a linear/detrending term to model regressors [1]
#reg_skip : (functional_regression) skip regression1: does not create output functional files, only creates session-specific dp_*.txt files with covariate timeseries to be included later in an arbitrary first-level model [0]
#removescans : (functional_removescans) number of initial scans to remove
#reorient : (functional/structural_manualorient) transformation matrix3x3 or 4x4 transformation matrix or filename containing corresponding matrix
#respatialdef : (functional/structural_manualspatialdef) transformation fileNIFI deformation file (e.g. y_*.nii or *seg_sn.mat files)
#roi_names : (functional_roiextract) list of ROI namesadditional 1st-level covariate names may be included (to be regressed-out from ROI timeseries)
#roi_dimensions : (functional_roiextract) number of components/dimensionslist of maximum number of dimensions (one value for each model regressor in reg_names)
#roi_deriv : (functional_roiextract) add temporal derivativeslist of 0/1/2 values (one value for each entry in roi_names): adds                           first- or second- order derivatives to each extracted timeseries
#roi_filter : (functional_roiextract) filter extracted BOLD timeseries list of 0/1 values (one value for each model entry in roi_name): band-pass filter individual timeseries (filter specified in bp_filter field)
#roi_detrend : (functional_roiextract) detrends extracted BOLD timeseries1: adds a linear/detrending [0]
#roi_scale : (functional_roiextract) raw/PSC units1: scales extracted BOLD timeseries to PSC units (within each ROI) [1]
#rtm              : (functional_realign) realign-to-mean0: use first volume; 1: use mean volume [0]
       #rmask : (functional_realign) implicit masking1: applies implicit masking (voxels outside of field of view in >=1 image are set to NaN); [1]
#sliceorder : (functional_slicetime) acquisition ordervector of indexes; 1=first slice in image;                       alternatively sliceorder may also be defined as one of the following strings: 'ascending',                      'descending','interleaved (middle-top)','interleaved (bottom-up)','interleaved (top-down)',                      'interleaved (Siemens)','interleaved (Philips)','BIDS' (this option reads slice timing information from .json files)                      alternatively sliceorder may also be defined as a vector containing the acquisition time in                       milliseconds for each slice (e.g. for multi-band sequences)
#ta : (functional_slicetime) acquisition timeacquisition time (TA) in seconds (used to determine slice times when sliceorder is defined by a vector of slice indexes; note: use vector for subject-specific values). Defaults to (1-1/nslices)*TR where nslices is the number of slices
#template_structural: (structural_normalize SPM8 only) structural templateanatomical template file for approximate coregistration [spm/template/T1.nii]
#template_functional: (functional_normalize SPM8 only) functional templatefunctional template file for normalization [spm/template/EPI.nii]
#tpm_template : (functional/structural segment/normalize) tissue probability maptissue probability map file [spm/tpm/TPM.nii]alternatively, location of subject-specific TPM files (secondary functional dataset number or name ['tpm'])
#tpm_ngaus : (functional/structural segment/normalize) gaussian mixturenumber of gaussians for each tissue probability map
#tpm_structlesion: (structural_segment&normalize&lesion) name of ROI containing a structural-lesion maskthe lesion mask is expected to be coregistered with the structural image of the same subjectAs part of structural normalization a new subject-specific TPM template will be created with the lesion as an added tissue class
#vdm_et1 : (functional_vdm_create) ET1ET1 (Echo Time first echo in fieldmap sequence) (default [] : read from .json file / BIDS)
#vdm_et2 : (functional_vdm_create) ET2ET2 (Echo Time second echo in fieldmap sequence) (default [] : read from .json file / BIDS)
#vdm_ert : (functional_vdm_create) ERTERT (Effective Readout Time in funcional data) (default [] : read from .json file / BIDS)
#vdm_blip : (functional_vdm_create) BLIP DIRECTIONk-space traversal blip direction along the y-axis following SPM convention (i.e. positive for P>A, negative for A>P)use +1 or -1 to specify this value explicitlyleave empty to read from .json file /BIDS PhaseEncodingDirection field and use the formula BLIP = sign([0 1 0 0]*vol.mat*[i j k 0]'; e.g. PhaseEncodingDirection='j+', mat=[-1 0 0;0 1 0;0 0 1] => BLIP=sign([0 1 0 0]*mat*[0 1 0 0])=+1use 0 to reverse the sign from the above formula
#vdm_type : (functional_vdm_create only) type of fieldmap sequence files [] : automatically detect1 : magnitude+phasediff (or magnitude1+magnitude2+phasediff)2 : real1+imag1+real2+imag23 : fieldmapHz (e.g. --fout output from TOPUP)
#vdm_fmap : (functional_vdm_create only) location of fieldmap sequence files (secondary functional dataset number or label containing fieldmap sequence files) ['fmap']
#voxelsize_anat : (structural normalization) voxel sizetarget voxel size for resliced structural volumes (mm) [1]
#voxelsize_func : (functional normalization) voxel sizetarget voxel size for resliced functional volumes (mm) [2]
#warpreg : (normalization) warping regularisation factors in SPMdefault values [0 0.001 0.5 0.05 0.2]enter a single number if you want to scale the default parameters by that value enter 5 values to manually specify alternative warping regularization parameters

preprocessing .cfg example:

#functionals

/data/func/func_run01.nii

/data/func/func_run02.nii

#structurals

/data/anat/anat01.nii

#steps

default_mni

#RT

2

#sliceorder

interleaved (Siemens)