6. Running the Participant-level BrainSuite BIDS App

As with all BIDS Apps, BrainSuite BIDS App takes a minimum of three positional arguments:

Input data in BIDS format
Output directory (where you would like to store the processed files)
Analysis mode (participant or group)

6.1. Command-line interface using Docker

When running using Docker, you will need to preface the bids/brainsuite:v23a command with docker run, which will execute the BrainSuite BIDS App (bids/brainsuite:v23a) using Docker.

Because the Docker container does not have read access to your local file system (i.e., it cannot see the folders/files on your computer), you will need to mount the directories to the container (the container is the instantiated version of a Docker image) to allow the Docker container to read and write to your local file system.

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.

To run the BrainSuite BIDS App in participant-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 participant

Explanation of the command-line call:

Docker-based command-line arguments:
- docker run : calls on Docker to run commands inside the BrainSuite BIDS App Docker container instance.
- -ti : opens up an interactive container instance and allows commands to be passed into the container. -it is a shorthand version of the flags --interactive and --tty.
- --rm : indicates that the the Docker container should be immediately removed after the docker is closed (i.e. after BrainSuite BIDS App is has completed running).
- -v : defines the mount points (-v local:container). In the above command, mount points are specified for the input data directory (-v /path/to/local/bids/input/dataset/:/data:ro) and the output directory (-v /path/to/local/output/:/output). This way, the Docker container can see/read the contents in the input directory and write to the output directory.
- ro : the :ro in to the -v /path/to/local/bids/input/dataset/:/data:ro 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.
- bids/brainsuite:v23a : name of the BrainSuite BIDS App Docker image.
BrainSuite BIDS App command-line arguments:
- /data : path to the input data directory inside the container. Since the input data directory on the host machine is mounted on /data in the container (via -v /path/to/local/bids/input/dataset/:/data:ro), /data in the container is the same as the host’s /path/to/local/bids/input/dataset/.
- /output : path to the output directory inside the container. Again, since the output directory on the host machine is mounted (via /path/to/local/output/:/output), output is essentially the same as /path/to/local/output/ on the host machine. If the output directory does not exist, BrainSuite BIDS App will automatically create this directory.
- participant : sets the BrainSuite BIDS App to run in participant mode. Available options are participant and group.

Note

Notice that the two positional arguments following the command (bids/brainsuite:v23a) are paths relative to the container, and not the local computer.

6.2. Command-line interface using Singularity

Unlike Docker, for Singularity, you can directly use your local host’s file system paths.

To run participant-level mode using Singularity:

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

Explanation of the command-line call:

Singularity-based command-line arguments:
- singularity run : calls on Singularity to run commands inside the BrainSuite BIDS App Singularity container instance.
- bids_brainsuite_v23a.simg : the path and name of the BrainSuite BIDS App Singularity image.
BrainSuite BIDS App command-line arguments:
- /path/to/local/input : path to the input data directory on the host computer. Unlike Docker, Singularity uses the host’s file system paths.
- /path/to/local/output : path to the output directory on the host computer. Again, unlike Docker, Singularity uses the host’s file system paths. If the output directory does not exist, BrainSuite BIDS App will automatically create this directory.
- participant : sets the BrainSuite BIDS App to run in participant mode. Available options are participant and group.

Tip

If your Singularity image cannot see your files on your system, try adding --bind /path/to/folder after singularity run.

Note

Participant-level processing generates snapshots of processed images in intermediate stages. For more instructions on launching real-time monitoring of the processing, please take a look at “Running QC and BrainSuite Dashboard” page.

6.3. Command-line arguments

usage: brainsuitebidsapp [-h] [--stages {CSE,SVREG,BDP,BFP,DASHBOARD,ALL} [{CSE,SVREG,BDP,BFP,DASHBOARD,ALL} ...]] [--preprocspec PREPROCSPEC] [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [--session SESSION [SESSION ...]] [--skipBSE]
                         [--atlas {BSA,BCI-DNI,USCBrain}] [--singleThread] [--TR TR] [--fmri_task_name FMRI_TASK_NAME [FMRI_TASK_NAME ...]] [--ignore_suffix IGNORE_SUFFIX] [--QCdir QCDIR] [--QCsubjList QCSUBJLIST] [--localWebserver] [--port PORT]
                         [--bindLocalHostOnly] [--modelspec MODELSPEC] [--analysistype {STRUCT,FUNC,ALL}] [--rmarkdown RMARKDOWN] [--ignoreSubjectConsistency] [--bidsconfig [BIDSCONFIG]] [--cache CACHE] [--ncpus NCPUS] [--maxmem MAXMEM] [-v]
                         bids_dir output_dir {participant,group}

6.3.1. Positional Arguments

bids_dir

The directory with the input dataset formatted according to the BIDS standard.

output_dir

The directory where the output files should be stored. If you are running group level analysis this folder should be prepopulated with the results of theparticipant level analysis.

analysis_level

Possible choices: participant, group

Level of the analysis that will be performed. Multiple participant level analyses can be run independently (in parallel) using the same output_dir. The group analysis performs group statistical analysis.

6.3.2. Named Arguments

--stages

Possible choices: CSE, SVREG, BDP, BFP, DASHBOARD, ALL

Participant-level processing stage to be run. Space delimited list. Default is ALL which does not include DASHBOARD. CSE runs Cortical Surface Extractor and cortical thickness computation, which are the initial portions of the BrainSuite Anatomical Pipeline (BAP). SVREG runs Surface-constrained Volumetric registration, which is the latter portion of BAP. BDP runs BrainSuite Diffusion Pipeline. BFP runs BrainSuite Functional Pipeline. DASHBOARD runs the real-time monitoring that is required for BrainSuite Dashboard to update real-time. However, DASHBOARD can still be run after the participant-level processing has ended to generate the browser-based BrainSuite Dashboard.

--preprocspec

Optional. BrainSuite preprocessing parameters.Path to JSON file that contains preprocessing specifications.

--cache

Nipype cache output folder.

--ncpus

Number of cpus allocated for running subject-level processing.

--maxmem

Maximum memory (in GB) that can be used at once.

-v, --version

show program’s version number and exit

6.3.3. Options for selectively running specific datasets

--participant_label: The label of the participant that should be analyzed. The label corresponds to sub-<participant_label> from the BIDS spec (so it does not include “sub-“). If this parameter is not provided, all subjects will be analyzed. Multiple participants can be specified with a space separated list.
--session: The session label of the participant that should be analyzed. The label corresponds to ses-<session label> from the BIDS spec (so it does not include “ses-“). If this parameter is not provided, all sessions will be analyzed. Multiple sessions can be specified with a space separated list.

6.3.4. Command line arguments for BrainSuite Anatomical Pipeline (BAP). For more parameter options, please edit the preprocspecs.json file

--skipBSE

Skips BSE stage when running CSE. Please make sure there are sub-ID_T1w.mask.nii.gz files in the subject folders.

--atlas

Possible choices: BSA, BCI-DNI, USCBrain

Atlas that is to be used for labeling in SVReg. Default atlas: BCI-DNI. Options: BSA, BCI-DNI, USCBrain.

--singleThread

Turns on single-thread mode for SVReg.This option can be useful when machines run into issues with the parallel processing tool from Matlab (Parpool).

6.3.5. Command line arguments for BrainSuite Functional Pipeline (BFP). For more parameter options, please edit the preprocspecs.json file

--TR: Repetition time of MRI (in seconds).
--fmri_task_name: fMRI task name to be processed during BFP. The name should only containthe contents after “task-”. E.g., restingstate.
--ignore_suffix: Optional. You can define which suffix to ignore in the output folder. E.g., if input T1w is sub-01_ses-A_acq-highres_run-01_T1w.nii.gz,and you would like to ignore the “acq-highres” suffix portion, then you can type “–ignore_suffix acq”, which will render sub-01_ses-A_run-01 output folders.

6.3.6. Options for BrainSuite QC and Dashboard

--QCdir: Designate directory for QC Dashboard.
--QCsubjList: For QC purposes, optional subject list (txt format, individual subject ID separated by new lines; subject ID without “sub-” is required (i.e. 001). This is helpfulin displaying only the thumbnails of the queued subjects when running on clusters/compute nodes.
--localWebserver: Launch local webserver for QC.
--port: Port number for QC local webserver. This defines the port number inside the BrainSuite BIDS App container. If using Singularity version of BrainSuite BIDS App, this argument also defines the port number of the local host.
--bindLocalHostOnly: When running local web server through this app, the server binds to all of the IPs on the machine. If you would like to only bind to the local host, please use this flag.

6.3.7. Arguments and options for group-level stage. –modelspec is required for groupmode

--modelspec

Optional. Only for group analysis level.Path to JSON file that contains statistical model specifications.

--analysistype

Possible choices: STRUCT, FUNC, ALL

Group analysis type: structural (T1 or DWI)or functional (fMRI). Options: STRUCT, FUNC, ALL.

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

6.3.8. Options for bids-validator

--ignoreSubjectConsistency: Reduces down the BIDS validator log and the associated memory needs. This is often helpful forlarge datasets.
--bidsconfig: Configuration of the severity of errors for BIDS validator. If this argument is used with no path specification, the bids-validator checks for a .bids-validator-config.json file at the top level of the input BIDS directory. However, if you would like to define the path of your .bids-validator-config.json file, then you can specify the path after this flag (i.e. –bidsconfig /path/to/file). For more information on how to create this JSON file, please visit https://github.com/bids-standard/bids-validator#configuration.