10. Modifying Participant-level Preprocessing Parameters

You can run the participant-level workflow with custom parameters by including a preprocessing configuration file. Prior to running the participant-level workflows, modify the parameters in a preprocspec.json file. To modify preprocessing parameters, create a file with the following contents (a sample JSON file is provided with the source code in our repo sample_preprocspec.json):

{
	"BrainSuite": {
		"Global Settings": {
			"cacheFolder": ""
		},
		"Anatomical": {
			"autoParameters": 1,
			"prescale": 1,
			"diffusionIterations": 3,
			"diffusionConstant": 25,
			"edgeDetectionConstant": 0.64,
			"skipBSE": 0,
			"iterativeMode": 0,
			"spatialPrior": 0.1,
			"costFunction": 0,
			"useCentroids": 1,
			"linearConvergence": 0.01,
			"warpConvergence": 100,
			"warpLevel": 5,
			"tissueFractionThreshold": 50.0,
			"atlas": "BCI-DNI",
			"singleThread": 1
		},
		"Diffusion": {
			"fsleddy": 0,
			"indexFile": "",
			"acqpFile": "",
			"flm": "quadratic",
			"slm": "none",
			"fep": 0,
			"interp": "spline",
			"nvoxhp": 1000,
			"fudge_factor": 10,
			"dont_sep_offs_move": 0,
			"dont_peas": 0,
			"niter": 5,
			"eddy_final_resamp": "jac",
			"repol": 0,
			"eddy_num_threads": 1,
			"is_shelled": 0,
			"useDerivatives": 0,
			"correctedOutputDir": "",
			"correctedOutputSuffix": "",
			"skipDistortionCorr": 0,
			"phaseEncodingDirection": "y",
			"echoSpacing": "",
			"fieldmapCorrection": "",
			"estimateODF_3DShore": 0,
			"diffusion_time_ms": "",
			"estimateODF_GQI": 0,
			"sigma_GQI": "",
			"estimateODF_ERFO": 0,
			"ERFO_SNR": ""
		},
		"PostProc": {
			"smoothSurf": 2.0,
			"smoothVol": 3.0
		},
		"Functional": {
			"task-name": ["restingstate"],
			"TR": 2,
			"EnabletNLMPdfFiltering": 1,
			"fpr": 0.001,
			"FSLOUTPUTTYPE": "NIFTI_GZ",
			"FWHM": 6,
			"HIGHPASS":0.005,
			"LOWPASS": 0.1,
			"MultiThreading": 1,
			"memory": 16,
			"FSLRigid": 0,
			"BPoption": 1,
			"RunDetrend": 1,
			"RunNSR": 1,
			"SimRef": 1,
			"uscrigid_similarity": "inversion",
			"scbPath": "",
			"T1mask": 1
		}
	}
}

10.1. Usage

To run participant-level processing using a preprocspec.json file, you can use the --preprocspec argument:

docker run -ti --rm \
  -v /path/to/local/bids/input/dataset/:/data \
  -v /path/to/local/output/:/output \
  bids/brainsuite:23a \
  /data /output participant --preprocspec /path/to/preprocspec.json

For Singularity-based images:

singularity run bids_brainsuite_v23a.simg \
  /path/to/local/input /path/to/local/output participant \
  --preprocspec /path/to/preprocspec.json

10.2. Preprocessing specification JSON file field descriptions

This optional JSON file defines objects named Anatomical, Diffusion, PostProc, and Functional that can be used to specify parameters for each of those components. For parameters whose options are Boolean values, 1 (True) and 0 (False) are used, e.g., 1 enables an option and 0 disables it.

10.2.1. Global Settings

Parameter	Purpose
cacheFolder	Specifies the location of the cache folder for Nipype. If you would like to rerun a process, you must empty the folders in this cache directory. The default location for the cache folder is the output directory.

10.2.2. BrainSuite Anatomical Pipelines (BAP)

10.2.2.1. Skull-stripping (bse)

Parameter	Purpose
autoParameters	Enables automated selection of optimal parameters for skull-stripping/Brain Surface Extractor (BSE). Options: 0, 1. Default: 1 (enabled).
prescale	Prescales image to uint16 data type. Options: 0, 1. Default: 0 (disabled).
diffusionIterations	Specifies the number of times the anisotropic diffusion filter is applied to the image during BSE. This field will be ignored if autoParameters is 1. Typical range: [0 … 6]. Default: 3.
diffusionConstant	Specifies the anisotropic diffusion constant, which controls the height of the edges that are retained during anisotropic diffusion filtering. This field will be ignored if autoParameters is 1. Typical range: [5 … 35]. Default: 25.
edgeDetectionConstant	specifies the edge detection constant, Ïƒ. During the edge detection step in BSE, Ïƒ influences how wide an edge must be to be identified. Typical range: (0.5 … 1.0). Default: 0.64
skipBSE	If enabled (1), skull stripping (BSE) is skipped and a custom mask is used (e.g., if manual edits to a brain mask were necessary). The custom mask must be copied to the output folder prior to running BAP. Options: {0,1}. Default: 0 (disabled).

10.2.2.2. Bias Field Correction (bfc)

Parameter	Purpose
iterativeMode	If iterative mode is enabled, the bias field correction (BFC) program will run multiple passes using a range of settings to correct for severe artifacts. Options: {0,1}. Default: 0.

10.2.2.3. Tissue classification (pvc)

Parameter	Purpose*
spatialPrior	Controls the weighting of the spatial prior used during tissue classification stage. Reducing this value can be useful if an image has low signal-to-noise. Default: 0.1.

10.2.2.4. Cerebrum labeling (cerebro)

Parameter	Purpose
costFunction	The cost function used by AIR’s alignlinear during the initial linear registration to the atlas for cerebrum labeling. Possible choices are: standard deviation of the ratio image (0), least squares (1), and least squares with intensity rescaling (2). Options: {0,1,2}. Default: 2.
useCentroids	If enabled, the cerebrum labeling program will initialize the registration process using the centroids of the subject image and the atlas image. Options: {0,1}. Default: 0.
linearConvergence	Sets the threshold used by AIR’s alignlinear during cerebrum labeling to determine if the linear registration has converged. Default: 0.1.
warpConvergence	Sets the threshold used by AIR’s align_warp during cerebrum labeling to determine if the nonlinear registration has converged. Default: 100.
warpLevel	Sets the degree of the polynomial model used for the transformation used by AIR’s align_warp during cerebrum labeling. Typical Range: (2 … 8). Default: 5

10.2.2.5. White Matter Mask Generation (cortex)

Parameter	Purpose
tissueFractionThreshold	Minimum percentage of white matter in a voxel needed for it to be included in the mask, in decimal form (e.g., 50% white matter) during initial cortical mask generation. Range: (0 … 100). Default: 50.0

10.2.2.6. Registration and Labeling (svreg)

Parameter	Purpose
atlas	Specifies the atlas used for registration and labeling (see here) for details on the atlases). Options: BSA, BCI-DNI, USCBrain. 1 Default: BCI-DNI.
singleThread	If enabled, SVReg runs in single-threaded mode by disabling multithreading in MATLAB’s parpool. This can be helpful if errors related to MATLAB parpool occur on compute nodes. Options: {0,1}. Default: 0

10.2.3. BrainSuite Diffusion Pipelines (BDP)

Parameter	Purpose
fsleddy	If enabled, FSL eddy (Andersson & Sotiropoulos, 2016) will perform eddy current and motion correction. Options: {0,1}. Default: 0.
acqpFile	Path to a user-defined text file that contains diffusion data acquisition parameter information (e.g., phase encoding direction, blip-up/blip-down, and pixel/bandwidth). This parameter is required when fsleddy (FSL eddy) is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/Faq#How_do_I_know_what_to_put_into_my_–acqp_file.
indexFile	Path to user-defined text file that indicates which volumes in the diffusion data follow which acquisition parameters written in the text file in the acqpFile field. This parameter is required when fsleddy (FSL eddy) is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–index.
flm	Sets the model for estimating the eddy current-induced field. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–flm. Options: {linear,quadratic,cubic}. Default: quadratic.
slm	Sets the model for estimating the eddy currents caused by diffusion gradients. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–slm. Options: {none,linear,quadratic}. Default: none.
fep	If enabled, FSL eddy identifies and fills empty planes. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–fep. Options: {0,1}. Default: 0.
interp	Sets the model for interpolation during resampling. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–interp. Options: {spline,trilinear}. Default: spline.
nvoxhp	Number of voxels to use during the hyperparameter estimation of the Gaussian Process during the prediction phase. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–nvoxhp. Default: 1000.
fudge_factor	Sets the level of Q-space smoothing during the prediction phase. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–ff. Default: 10.
dont_sep_offs_move	If enabled, FSL eddy will not attempt to distinguish the constant component of the eddy current field and subject movement and will only fit one model (the constant component of the eddy current field). This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–dont_sep_offs_move. Options: {0,1}. Default: 0.
dont_peas	If enabled, FSL eddy will not estimate the movement between the b=0 volume and the first diffusion data volume. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–dont_peas. Options: {0,1}. Default: 0.
niter	Specifies the number of iterations. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–niter. Default: 5.
eddy_final_resamp	Sets the method (Jacobian modulation or least-squares reconstruction) for final resampling. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–resamp. Options: {jac,lsr}. Default: jac.
repol	If enabled, replaces outlier slices using predictions from Gaussian Process. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–repol. Options: {0,1}. Default: 0.
eddy_num_threads	Sets the number of threads used for FSL eddy. Default: 1.
is_shelled	If enabled, FSL eddy automatically assumes that the diffusion data are shelled. This parameter is used when fsleddy is enabled. For more information, please visit https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/eddy/UsersGuide#A–data_is_shelled. Options: {0,1}. Default: 0.
useDerivatives	If enabled, BDP will use diffusion data derivatives defined by the fields correctedOutputDir and correctedOutputSuffix. This allows users to preprocess their diffusion data outside of the BrainSuite BIDS App and use them as inputs for BDP. Options: {0,1}. Default: 0.
correctedOutputDir	The path to the directory that contains the preprocessed diffusion data. The subject IDs must be the same as those in the input BIDS data input directory and must adhere to the following folder organization: derivatives_directory/sub-subjectID/dwi/. This parameter is required when useDerivatives is enabled.
correctedOutputSuffix	The file suffix of the preprocessed diffusion data. Since the preprocessing methods can vary, you can defined the file suffix in this field. The suffix contains all the characters after the subject ID but does not include the file extension. For example, for file sub-01_dwi.topup.corr.nii.gz, the file suffix is _dwi.topup.corr. The file suffix must be the same for the diffusion image, the b-value text file, and the b-vector text file. This parameter is required when useDerivatives is enabled.
skipDistortionCorr	If enabled, BDP skips distortion correction completely and performs only a rigid registration of the diffusion and T1-weighted images. This can be useful when the input diffusion images do not have any distortion or they have already been corrected for distortion. Options: {0,1}. Default: 0.
phaseEncodingDirection	Sets the phase encoding direction of the DWI data, which is the dominant direction of distortion in the images. This information is used to constrain the distortion correction along the specified direction. Directions are represented by any one of x, x-, y, y-, z or z-. x direction increases towards the right side of the subject, while x- increases towards the left side of the subject. Similarly, y and y- are along the anterior-posterior direction of the subject, and z and z- are along the inferior-superior direction. When this field is not specified, BDP uses y as the default phase-encoding direction. Options: {x,x-,y,y-,z,z-}. Default: y.
echoSpacing	Sets the echo spacing in units of seconds, which is used during fieldmap-based distortion correction. (Example: For an echo spacing of 0.36ms, use echo-spacing=0.00036). This value is required when using fieldmapCorrection.
fieldmapCorrection	Use an acquired fieldmap for distortion correction. The parameter specifies the path to the field map file to use.
estimateODF_3DShore	If enabled, estimates ODFs using the 3D-SHORE (Ã–zarslan et al., 2013) basis representation. Options: {0,1}. Default: 0.
diffusion_time_ms	Sets the diffusion time parameter (in milliseconds). This parameter is required for estimating ERFO, 3D-SHORE and GQI ODFs.
estimateODF_GQI	Estimates ODFs using the GQI method (Yeh et al., 2010). Options: {0,1}. Default: 0.
sigma_GQI	Sets the GQI adjustable factor, required for calculating diffusion sampling length. Typical range: [1 … 1.3]. Default: 1.25.
estimateODF_ERFO	If enabled, estimates ODFs using the ERFO method. (Varadarajan & Haldar, 2018). Options: {0,1}. Default: 0.
ERFO_SNR	Sets the SNR of the acquired data, required for estimating ERFO ODFs. Default: 35.

10.2.4. Smoothing Parameters Settings

Parameter	Purpose
smoothSurf	Specifies the kernel size (in mm) used for smoothing the surface output data from BAP. Typical range: (2 … 5). Default: 2.
smoothVol	Specifies the kernel size (in mm) used for smoothing the volumetric output data from BAP and BDP. Typical range: (2 … 6). Default: 3.

10.2.5. BrainSuite Functional Pipelines (BFP)

Parameter	Purpose
task-name	The names of the tasks to be processed in list form using square brackets, e.g., [restingstate, emomatching]. The task names should correspond to the task names specified in the input fMRI filenames after the task- delimiter. For example, in the fMRI file sub-0001_task-restingstate_bold.nii.gz, the task name would be ‘restingstate’.
TR	Repetition time (in seconds) of the fMRI data.
EnabletNLMPdfFiltering	If enabled, BFP will apply tNLMPdf (GPDF) filtering. This step can take up to 30 minutes per scan. Options: {0,1}. Default: 1.
fpr	False positive rate regarding the null (noise) distribution. This parameter is used for global non-local means filtering (GPDF) for fMRI denoising. Default: 0.001
FSLOUTPUTTYPE	Specifies the format that FSL uses to save its outputs. 2 Default: NIFTI_GZ
FWHM	Full-width-half-maximum value, in mm, used for spatial smoothing. Default: 6
HIGHPASS	Value for the high-pass cutoff frequency, in Hz, used for bandpass filtering. Default: 0.005
LOWPASS	Value for the low-pass cutoff frequency, in Hz, used for bandpass filtering. Default: 0.1
MultiThreading	If enabled, uses parallel processing for transforming fMRI data onto the grayordinate system and GPDF non local means filtering. If disabled, parallel processing is not used. {0,1}. Default: 1
memory	Specifies the amount of RAM (in gigabytes) available for running for transforming fMRI data onto grayordinate
EnableShapeMeasures	Enable SCT shape measure computation (cortical thickness using anisotropic Laplacian, shape index and curvatures). This step can take up to 1 hr per scan.
T1SpaceProcessing	1: T1 native space will be used for T1 preprocessing. 0: T1 will resample images to 1mm isotropic for preprocessing.
FSLRigid	If enabled, BFP uses FSL’s rigid registration (FLIRT) during processing. If not enabled, BFP uses BrainSuite’s BDP affine registration. FLIRT is run with 6 degrees of freedom, trilinear interpolation, and the correlation ratio cost function (Jenkinson et al., 2002). BrainSuite’s affine registration tool is set to run with 6 degrees of freedom, linear interpolation, and the INVERSION cost function, which is optimized to align the inverted contrasts of T1W and fMRI images (Bhushan et al., 2015). Options: {0,1}. Default: 0
SimRef	Specifies the type of reference volume used for coregistration and motion correction. If enabled, SimRef will be used, which calculates the pair-wise structural similarity index (SSIM) between every tenth time point and all other time points (Wang et al., 2004; Hore & Ziou, 2010). The time point with the highest mean SSIM is chosen as the reference image. If not enabled, all volumes are averaged together to create a mean image. {0,1}. Default: 1
BPoption	If enabled, BFP applies 3dBandpass (updated function with quadratic detrending). If not enabled, BFP applies 3dFourier and linear detrending. Details are found in the AFNI documentation 3 . Options: {0,1}. Default: 1
RunDetrend	Enables detrending. Options: {0,1}. Default: 1
RunNSR	Enables nuisance signal regression. Options: {0,1}. Default: 1
uscrigid_similarity	Specifies the cost function(s) used by BFP during USC rigid registration. Available methods are INVERSION (inversion), INVERSION followed by normalized mutual-information based refinement (bdp), mutual information (mi), correlation ratio (cr), and squared difference (sd). Options: {bdp, inversion, mi, cr, sd}. Default: inversion
scbPath	SCB file is used by tNLM filtering. Set this path somewhere there is a lot of space.
T1mask	If enabled, BFP uses the T1w mask to threshold fMRI data, which may be useful for data with high signal dropout. Options: {0,1}. Default: 1