4. Running 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)

4.1. Command-line interface using Docker¶

When running using Docker, you will need to preface the bids/brainsuite:v21a command with docker run, which will execute the BrainSuite BIDS App (bids/brainsuite:v21a) 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 \
      -v /path/to/local/output/:/output \
      bids/brainsuite:v21a \
      /data /output participant

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. This way, the Docker container can see/read the contents in the input directory and write to the output directory.

Note

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

The last argument (participant) tells the App to run in participant mode.

4.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_v21a_$date_###.img \
      /path/to/local/input /path/to/local/output participant

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.

Note

Default behavior includes QC, which generate snapshots of processed images. For more instructions on launching real-time monitoring of the processing, please take a look at “Running QC and BrainSuite Dashboard” page.

4.2.1. Command-line interface¶

BrainSuite21a BIDS-App (T1w, dMRI, rs-fMRI)

usage: brainsuitebidsapp [-h] [--stages {CSE,SVREG,BDP,BFP,QC,DASHBOARD,ALL} [{CSE,SVREG,BDP,BFP,QC,DASHBOARD,ALL} ...]]
                         [--preprocspec PREPROCSPEC] [--participant_label PARTICIPANT_LABEL [PARTICIPANT_LABEL ...]] [--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}

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

4.2.1.2. Named Arguments¶

--stages

Possible choices: CSE, SVREG, BDP, BFP, QC, 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. SVREG runs Surface-constrained Volumetric registration. BDP runs BrainSuite Diffusion Pipeline. BFP runs BrainSuite Functional Pipeline. QC runs BrainSuite QC and generates status codes and snapshots. DASHBOARD runs the real-time monitoring that is required for BrainSuite Dashboard to update real-time.

--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 for running subject-level processing.

-v, --version

show program’s version number and exit

4.2.1.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 should be analyzed. Multiple participants can be specified with a space separated list.

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

4.2.1.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. Users 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 user would like to ignore the “acq-highres” suffix portion, then user can type “–ignore_suffix acq”, which will render sub-01_ses-A_run-01 output folders.

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

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

4.2.1.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 no path is specified, a default path of .bids-validator-config.json(relative to the input bids directory) file is used.