11. Modifying Group-level Analysis Parameters

To modify group-level analysis parameters, create a file with the following contents (a sample file is provided in our repo sample_modelspec.json).

{
  "BrainSuite": {
    "Structural":{
      "tsv_fname": "/path/to/participants.tsv",
      "measure": "sba",
      "test": "anova",
      "main_effect": "age",
      "covariates": [
        "sex"
      ],
      "corr_var": "",
      "group_var": "",
      "paired": 0,
      "smooth": 2.0,
      "mult_comp": "fdr",
      "pvalue":"parametric",
      "niter": 0,
      "roiid": [],
      "hemi": "both",
      "maskfile": "",
      "atlas": "",
      "roimeas": "",
      "dbameas": "" ,
      "exclude_col": "Exclude",
      "out_dir": "stats"},

    "Functional":{
      "tsv_fname": "",
      "file_ext": "-rest_bold.32k.GOrd.filt.mat",
      "lentime": 240,
      "matchT": 0,
      "stat_test": "atlas-linear" ,
      "pw_pairs": 2000,
      "pw_fdr": 0,
      "pw_perm": 2000,
      "outname": "BFPstats",
      "sig_alpha" : 0.05,
      "smooth_iter": 100,
      "save_surfaces": 1,
      "save_figures": 0,
      "atlas_groupsync": 1,
      "atlas_fname": "/output/atlas.mat",
      "test_all": 1,
      "colvar_main": "LogAge",
      "colvar_reg1": "age",
      "colvar_reg2": "sex",
      "colvar_exclude": "Exclude",
      "colvar_atlas": "Atlas",
      "out_dir": "FC_stats"
      }
	}
}

11.1. Usage

To run group-level stage using a preprocspec.json file, you can use the --modelspec argument:

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

For Singularity-based images:

singularity run bids_brainsuite_v23a.simg \
    /path/to/local/input /path/to/local/output group \
    --modelspec /path/to/modelspec.json

11.2. Model specification JSON file field descriptions

For parameters whose options are Boolean values, 1 (True) and 0 (False) are used, e.g., 1 enables an option and 0 disables it.

11.2.1. Group-level analysis for anatomical and diffusion data

Parameters for model specification for group-level analysis of anatomical and diffusion data
Parameter	Purpose
tsv_fname	Specifies the TSV file containing demographic data and/or clinical variables that will be used for group analysis
out_dir	Output directory location where statistical analysis results will be stored. This folder will be created if it does not exist
measure	Specifies the imaging measure of interest. Available options are: cortical thickness measures from surface files (sba); tensor-based morphometry using the Jacobian determinant of the deformation map from subject to atlas (tbm); ROI-based analysis using scalar summary statistics (roi); DTI parametric maps (dba). Options: {sba, tbm, roi, dba}
test	Specifies the model. Available options are: ANOVA (anova); correlations test (corr); t-test (ttest). Options: {anova, corr, ttest}
main_effect	Specifies the main predictor variable for ANOVA. Used only if test=anova. This value must match the corresponding column header in the TSV file specified in the tsv_fname field.
covariates	Specifies the covariates for ANOVA. Used only if test=anova. Values must match column headers from the TSV file in the tsv_fname field. Must be in list form and can contain multiple elements.
corr_var	Specifies the variable for correlation test. Used only if test=corr.
group_var	Specifies the group variable for paired t-test. Used only if test=ttest and paired=1.
paired	Specifies the t-test type. If enabled (1), then paired t-test will be performed. If disabled (0), then unpaired t-test will be performed. Used only if test=ttest.
smooth	Specifies the smoothing level used for sba, tbm, and dba. The smoothing levels must match the levels used during preprocessing. For example, if surface smoothing levels were set to 2.0mm for participant-level processing, then sba’s smoothing level should be set to 2.
mult_comp	Specifies the method for multiple comparison correction. Used only if measure is sba, tbm, or dba. Available options are: FDR (fdr); max-T permutation test (perm). Options: {fdr, perm}
niter	Specifies the number of iterations for the permutation method. Only used if mult_comp=perm.
pvalue	Specifies the method for computing p-values. Options: parametric, perm. Available options are: parametric method, which is the classical p-value method (parametric); permutation method, which is the Freedman-Lane method (Freedman & Lane, 1983) (perm). Options: {parametric, perm}
roiid	BrainSuite ROI ID number for ROI analysis. Only used if measure= roi. Must be in list format. Multiple IDs can be listed. For example, to study the left (641) and right thalamus (640): [640,641].
hemi	(For measure: sba) Hemisphere selection. Options: {left, right, both}.
maskfile	(For measure: tbm, dba) If mask file is specified, then only the regions within the mask will be considered for statistical analysis. The mask file must be in the same space as the atlas that was used to register the subjects during SVReg.
atlas	Atlas file. Default is the atlas that was used to run SVReg.
roimeas	(For measure: roi) ROI measure of interest. Available options are: average GM thickness in cortical regions (gmthickness); average GM volume (gmvolume); average wm volume (wmvolume). Options: {gmthickness, gmvolume, wmvolume}.
dbameas	(For measure: dba) Diffusion measure of interest. Options: {FA, MD, axial, radial, mADC, FRT_GFA}.
exclude_col	You can specify column header name in the TSV file (the same TSV file in the tsv_fname field). This column must exist in the TSV file for each subject/row, in which 0 indicates no exclusion and 1 indicates exclusion

11.2.2. Group-level analysis for functional data

Parameters for group-level analysis for functional data
Parameter	Purpose
tsv_fname	Specifies the TSV file containing demographic data and/or clinical variables that will be used for group analysis
out_dir	Output directory location where statistical analysis results will be stored. This folder will be created if it does not exist
file_ext	Input file suffix, which is the BFP output in grayordinate space, e.g., ‘-rest_bold.32k.GOrd.filt.mat’.
lentime	Number of timepoints in the fMRI data.
matchT	If some subjects have less than timepoints (‘lentime’), enabling this field will add zero values to match number of timepoints. Options: {0, 1}
stat_test	Model to be run. Options:{atlas-linear, atlas-group, pairwise-linear}.
pw_pairs	(For stat_test: pairwise-linear) Number of random pairs to measure
pw_fdr	(For stat_test: pairwise-linear) Multiple comparisons correction method. If enabled (1), FDR correction will be used. If disabled (0), max-T permutations will be used
pw_perm	(For stat_test: pairwise-linear and pw_fdr: 0) Number of permutations used for max-T permutation method.
outname	File prefixes for statistical output files.
sig_alpha	P-value significance level (alpha).
smooth_iter	Level of smoothing applied on brain surface outputs.
save_surfaces	If enabled (1), save surface files. If disabled (0), do not save surface files. Options: {True, False}
save_figures	If enabled (1), to save PNG snapshots of the surface files. If disabled (0), does not save. Options: {True, False}
atlas_groupsync	If enabled, an atlas is generated by first performing group alignment of fMRI data and then averaging over the entire group. If disabled, a reference atlas is created by identifying one representative subject. Options: {True, False}
atlas_fname	File name of user-defined atlas. Variable should be called atlas_data. Leave empty if no user-defined atlas should be used
test_all	If enabled (1), subjects used for atlas generation are included during hypothesis testing. If disabled (0), subjects used for atlas creation are excluded from testing your hypothesis. Options: {True, False}
colvar_main	For linear regression or group testing, the main effect of study.
colvar_reg1	For group comparisons. assign all rows with zero values if running linear regression. Control up to 2 variables by linearly regressing out the effect. If you only have less than 2 variable you would like to regression out, you can create and assign a dummy column(s) with zero values for all rows.
colvar_reg2	See explanation for colvar_reg1.
colvar_exclude	You can specify column header name in the TSV file (the same TSV file in the tsv_fname field). This column must exist in the TSV file for each subject/row, in which 0 indicates no exclusion and 1 indicates exclusion
colvar_atlas	You can specify column header name in the TSV file (the same TSV file in the tsv_fname field). This column must exist in the TSV file for each subject/row, 1 subjects that would be used to create a representative functional atlas, and 0 otherwise