This readme provides an outline of the functionality of the BrainSuite BIDS App. For more detailed instructions on installation and use, please visit our BrainSuite BIDS App documentation page. We have made a small set of sample data available. A demo of the BrainSuite Dashboard interface, showing the processing of the sample data, is available on our Github site.
The BrainSuite BIDS App provides a portable, streamlined method for applying BrainSuite workflows to process and analyze anatomical, diffusion, and functional MRI data. This release of the BrainSuite BIDS-App is based on version 23a of BrainSuite. The BrainSuite BIDS-App implements three major BrainSuite pipelines for subject-level analysis, as well as corresponding group-level analysis functionality.
BrainSuite BIDS App's participant-level processing comprises three core pipelines:
The BrainSuite Anatomical Pipeline (BAP)processes T1-weighted (T1w) data by extracting cortical surface models (CSE) from a T1w MRI, computing cortical thickness, and performing surface-constrained volumetric registration (SVReg) to align the T1w MRI to a labeled anatomical atlas.The BrainSuite Diffusion Pipeline (BDP)processes diffusion MRI (dMRI) data by correcting for eddy current and motion artifacts using FSL's eddy, co-registering the dMRI to the T1w data, correcting for geometric image distortion, and fitting diffusion models (BDP).The BrainSuite Functional Pipeline (BFP)processes functional MRI (fMRI) data by coregistering the fMRI data to the T1w data, correcting for motion, detecting outliers, and then transforming the data to the anatomical atlas space and to the grayordinate space using tools from BrainSuite, FSL, and AFNI.
-
BrainSuite BIDS App's group-level analysis of structural data uses the BrainSuite Statistics Toolbox in R (bstr), which supports:
- Tensor based morphometry (TBM) analysis.
- Cortical surface analysis of the vertex-wise thickness.
- Diffusion parameter maps analysis (e.g., FA, MD).
- ROI-based analysis of average measurements (e.g., gray matter thickness, surface area).
Additionally, bstr offers:
- Pearson correlation, general linear model, ANOVA, t-test, and permutation tests.
- Automated report generation to visualize statistical results.
-
BrainSuite BIDS App's group-level analysis of fMRI data (functional connectivity) is performed using BrainSync, which synchronizes time-series data temporally. Available analyses include:
- Atlas-based method: linear modeling using a reference dataset created from multiple input datasets.
- Atlas-free method: pairwise testing of all pairs of subjects, which is then used as test statistics for regression or group difference studies.
The BrainSuite Dashboard is a browser-based system that provides interactive visualization of the intermediate participant-level workflow outputs as they are generated. This enables users to monitor the state of processing and identify errors as they occur. A quality control (QC) component in the BrainSuite BIDS App generates snapshots of key stages in the participant-level workflows, which are loaded in real time by the BrainSuite Dashboard for quick visualization and assessment.
usage: run.py [-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}
BrainSuite23a BIDS-App (T1w, dMRI, rs-fMRI). Copyright (C) 2022 The Regents of
the University of California Dept. of Neurology, David Geffen School of
Medicine, UCLA.
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.
{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.
optional arguments:
-h, --help show this help message and exit
--stages {CSE,SVREG,BDP,BFP,DASHBOARD,ALL} [{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 PREPROCSPEC
Optional. BrainSuite preprocessing parameters.Path to
JSON file that contains preprocessing specifications.
--cache CACHE Nipype cache output folder.
--ncpus NCPUS Number of cpus allocated for running subject-level
processing.
--maxmem MAXMEM Maximum memory (in GB) that can be used at once.
-v, --version show program's version number and exit
Options for selectively running specific datasets:
--participant_label PARTICIPANT_LABEL [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 SESSION [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.
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 {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).
Command line arguments for BrainSuite Functional Pipeline (BFP). For more parameter options, please edit the preprocspecs.json file:
--TR TR Repetition time of MRI (in seconds).
--fmri_task_name FMRI_TASK_NAME [FMRI_TASK_NAME ...]
fMRI task name to be processed during BFP. The name
should only containthe contents after "task-". E.g.,
restingstate.
--ignore_suffix 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.
Options for BrainSuite QC and Dashboard:
--QCdir QCDIR Designate directory for QC Dashboard.
--QCsubjList 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 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.
Arguments and options for group-level stage. --modelspec is required for groupmode:
--modelspec MODELSPEC
Optional. Only for group analysis level.Path to JSON
file that contains statistical model specifications.
--analysistype {STRUCT,FUNC,ALL}
Group analysis type: structural (T1 or DWI)or
functional (fMRI). Options: STRUCT, FUNC, ALL.
--rmarkdown RMARKDOWN
Optional. Executable Rmarkdown file that uses bstr
for group 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.
Options for bids-validator:
--ignoreSubjectConsistency
Reduces down the BIDS validator log and the associated
memory needs. This is often helpful forlarge datasets.
--bidsconfig [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.
The BrainSuite BIDS App build process uses a pre-compiled parent image yeunkim/bidsapphead:2023, which is available on Docker Hub. The dockerfile for this parent Docker image is available in this repository as Dockerfile_head.
This enables us to have a faster build process and a more stable BIDS App.
BrainSuite BIDS App relies on multiple source software from third-party repositories.
Frequent rebuilding of all layers may introduce changes that impact the consistency of the software, possibly introducing instabilities or changes that affect the outcomes of the analysis software.
By developing our BrainSuite BIDS App using pre-compiled images, we are able to keep the parent images stable while changing only the top layers of the Docker image.
Our pre-compiled parent images act as snapshots of version-controlled dependencies and file systems that our BrainSuite BIDS App needs.
Questions about usage can be submitted to http://forums.brainsuite.org/. Issues or suggestions can be directly submitted as an issue to this Github Repository. For full documentation on the BrainSuite BIDS App, please visit https://brainsuite.org/BIDS/.
This project is supported by National Institutes of Health grants R01-NS074980, R01-NS121761, and R01-EB026299.
The primary BrainSuite BIDS App source code is licensed under the GNU Public License v2.0 only (GPL-2.0-only)
The BrainSuite BIDS App makes use of several freely available software packages. Details on the licenses for each of these are provide in the files within the LICENSES directory of this repository.