pipeline.cfg /.json
preprocessing-pipeline definition file
#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 coregistrationINDIVIDUAL 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)