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.