6. Running group-level BrainSuite BIDS App¶
After participant-level processing has completed running, you are ready to run group-level analysis on your processed dataset. The default behavior of the group level BrainSuite BIDS App runs both structural and functional analyses.
Important
Although not required, it’s strongly recommended for you to assess and QC your processed images. Pleased see the documentation for using BrainSuite Dashboard to review your data.
6.1. Prerequisites (2 Required User-Defined Files)¶
6.1.1. Demographics TSV file¶
A tab-separated value (TSV) file containing the demographics data that are to be used for group analysis is required. The file must contain a column with a column header ‘participant_id’ with the subject ID listed. An example demographics file is shown below.
The demographics TSV file can include an ‘Exclude’ column in which (1) indicates exclusion and (0) indicates inclusion. Rows with (1) will be excluded in the group analysis.
participant_id Exclude age sex
sub-0001 0 26 F
sub-0000 0 21 F
sub-0001 0 24 F
sub-0002 0 22 F
sub-0003 1 22 F
sub-0004 0 23 F
sub-0005 0 23 F
sub-0006 0 20 F
sub-0007 0 24 F
sub-0008 0 22 F
sub-0009 0 22 F
sub-0010 1 21 F
sub-0011 0 23 F
sub-0012 0 20 F
sub-0013 0 22 F
sub-0014 0 23 M
sub-0015 0 21 M
6.1.2. Model specification JSON file¶
The model specification JSON file contains the specifications for group-level analysis and is required for processing. An example is shown below. For details on customizing the model specification file, please see Modifying group-level analysis parameters.
Warning
When running group mode using Docker, you must define file and folder paths in the model specification JSON file relative to the container path.
{
"BrainSuite": {
"Anatomical": {
"tsv_fname": "/data/participants.tsv",
"measure": "cbm",
"test": "anova",
"main_effect": "age",
"covariates": [
"sex",
"height"
],
"corr_var": "",
"group_var": "",
"paired": 1,
"smooth": 2.0,
"mult_comp": "fdr",
"pvalue": "parametric",
"niter": 5000,
"roiid": [
102
],
"hemi": "left",
"maskfile": "",
"atlas": "",
"roimeas": "",
"dbmmeas": "",
"out_dir": "/output/stats"
},
"Functional": {
"tsv_fname": "/data/participants.tsv",
"file_ext": "_task-rest_bold.32k.GOrd.filt.mat",
"lentime": 240,
"matchT": 0,
"stat_test": "atlas-linear",
"pw_pairs": 2000,
"pw_fdr": 0,
"pw_perm": 2000,
"outname": "BFPtest",
"sig_alpha": 0.05,
"smooth_iter": 100,
"save_surfaces": 1,
"save_figures": 0,
"atlas_groupsync": 1,
"atlas_fname": "/data/atlas.mat",
"test_all": 1,
"colvar_main": "LogAge",
"colvar_reg1": "Age",
"colvar_reg2": "Sex",
"colvar_exclude": "Exclude",
"colvar_atlas": "Atlas",
"out_dir": "/output/stats"
}
}
}
6.2. Command-line interface using Docker¶
To run group-level mode using Docker:
docker run -ti --rm \
-v /path/to/local/bids/input/dataset/:/data \
-v /path/to/local/output/:/output \
bids/brainsuite:v21a \
/data /output group --modelspec modelspec.json
Again, the -v arguments define the mount points ( -v local:container
). In the above command, mount points are specified for
the input data directory and the output directory. Important: Make sure that the output directory contains the outputs from
the participant-level processing. This way, the Docker container can see/read the contents in the input directory
and read/write to the output directory.
The last argument (--modelspec
) specifies the model specifications JSON file that we have defined above.
Note
If you do not mount any points, then all output files that are written out will be removed once the Docker container has finished and gone.
Note
Notice that the two positional arguments following the command (bids/brainsuite:v21a
) are paths relative
to the container, and not the local computer.
6.3. Command-line interface using Singularity¶
Unlike Docker, for Singularity, you can directly use your local host’s file system paths.
To run group-level mode using Singularity:
singularity run bids_brainsuite_v21a_$date_###.img \
/path/to/local/input /path/to/local/output group --modelspec modelspec.json
where bids_brainsuite_v21a_$date_###.img
is the converted Singularity BrainSuite BIDS App image.
Tip
If your Singularity image cannot see your files on your system, try adding --bind /path/to/folder
after singularity run
.
6.4. Arguments for group-level mode¶
--analysistype {STRUCT,FUNC,ALL}
Group analysis type: structural (T1 or DWI)or
functional (fMRI). Options: STRUCT, FUNC, ALL.
--modelspec ModelSpec
Optional. Only for group analysis level.Path to JSON
file that contains statistical models pecifications.
--rmarkdown RMARKDOWN
Optional. Executable Rmarkdown file that uses bssr
forgroup analysis stage. If this argument is
specified, BrainSuite BIDS-App will run this Rmarkdown
instead of using the content found in
modelspec.json.Path to R Markdown file that contains
bssr analysis commands.