9. Running the 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.

9.1. Prerequisites (2 Required User-Defined Files)

9.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.

Example demographics TSV file.

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

9.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.

Example model specification JSON file. Highlighted line indicate file paths that must be relative to the container file system.

{
  "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"
      }
	}
}

9.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:ro \
      -v /path/to/local/output/:/output \
      bids/brainsuite:v23a \
      /data /output group --modelspec modelspec.json

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. The :ro next to the /data mount point indicates that the folder will be read-only in the Docker container. This ensures that the input data directory will not be modified or deleted.

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:v23a) are paths relative to the container, and not the local computer.

9.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_v23a.simg \
      /path/to/local/input /path/to/local/output group --modelspec modelspec.json

where bids_brainsuite_v23a.simg is the Singularity-based 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.

Note

If you would like to specify which analyses to run, you can do so by using the --analysistype argument.

9.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 bstr
                    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
                    bstr analysis commands.