BrainSuite QC System

Overview:

The BrainSuite QC system is designed to allow scientists to launch BrainSuite processing workflows on datasets, and then monitor thumbnails and statistics on the brains through a page in a web browser; the thumbnails and statistics will be updated in real time as each step of the workflow is completed.

The QC system uses Nipype to perform the BrainSuite analysis routines, and expects the dataset in BIDS compliant form. volblend and dfsrender are used to generate thumbnail images.

Development Notes:

  • Statistical analysis options are in development. We have currently developed metrics for BSE, PVC, Cerebro, and DFS.

Requirements:

  1. Must be run on Linux system. (Mac binaries for quality control metrics to be added soon)
  2. BrainSuite must be installed, and the command line executables must be added to your path
  3. Nipype must be installed, and the installation of python that can run Nipype must be added to your path
  4. Dataset must be provided in BIDS compliant form
  5. Web server / public_html directory (for viewing the QC system in a web browser)

Download & Setup:

The source code for the QC system can be obtained by the following commands:
wget http://users.bmap.ucla.edu/~jwong/qc-system.tar.gz
tar -xzf qc-system.tar.gz

Then add qc-system/bin/  to your system PATH variable; this directory contains the quality control modules, and the image rendering binaries. They are compiled for x86_64-redhat-linux-gnu. (Other distributions will be made available in the future)

Usage Instructions:

Customizing BrainSuite Processing Parameters:

The file qc-system/brainsuite_parameters.json contains a JSON representation of the default BrainSuite processing parameters. The top level keys are the names of the BrainSuite stages; these keys map to JSON objects containing parameters for a particular stage. Each stage’s JSON object maps Nipype input names to the desired values. See the BrainSuite Nipype Interface Documentation or the BrainSuite Interface Code for the available Nipype input names and options. You do not need to add mandatory options to your JSON.

To change the processing parameters, you may directly edit qc-system/brainsuite_parameters.json, or you may use the -b option (described later).

Running the Processing:

Run the QC system using run.sh. Call run.sh without any arguments for usage instructions, copied below:

Usage:

run.sh -d <directory_path> [settings]
Settings Description
Required Settings
-d <directory_path> -s <regex> to filter by subject ID and session.
Optional Settings
-p <directory_path> directory where index.html, thumbnails directory, and
brainsuite_state.json will be created. Program will create public
directory if it does not already exist.
[default: <dataset>/derivatives, where <dataset> is input to -d]
-w set up a basic web server to serve files from public directory.
web server defaults to port 8080, increments port number if
if 8080 is unavailable, until available port is found.
-r <processing_steps> Controls what processing will be done in addition to CSE.
If BDP is enabled, will first check for dwi data; if dwi data is
not found, BDP will be disabled.
<processing_steps> must be one of: {bdp, svreg, none, all}
[default: all]
 -b <parameters_file>   Use custom parameters for BrainSuite processing. The parameters_file
must contain a json representation of the desired parameters. The top
level keys are names of the stages. Each stage must map to a json
object, which maps Nipype input names to the desired values.
[default: <scriptdir>/brainsuite_parameters.json]
 -i <regex>   provide a regex to filter subjects by subjectID. Only subjects whose
subject ID match the provided regex will be processed.
Expression will be interpreted in ERE syntax; will act like grep -E
on each subject name in your dataset. Quotes around your expression
are not required, but are recommended when using special operators
such as or (|).
Can be used along with -s <regex>.
[default: .*]
 -s <regex>   provide a regex to filter by session label. If dataset does not
include session layer of directory structure (this is only allowed by
BIDS when each subject has exactly one session), then session label
regex will be ignored. Only data from sessions whose session label
match the provided regex will be processed.
Expression will be interpreted in ERE syntax; will act like grep -E
on each session label in your dataset. Quotes around your expression
are not required, but are recommended when using special operators
such as or (|).
Can be used along with -i <regex>.
[default: .*]
 -t <tmpdir>   change the TMP and TMPDIR shell variables to <tmpdir> when
submitting job to qsub. Should be used if compute nodes
lack tmp space, or if tmp directories are full. <tmpdir>
should be a directory for which you have permissions.
 -x   For testing purposes. Will cause program to print out name of
each file that would have been processed, without actually
starting any processing jobs.
Useful for debugging or for testing your regex matches.
 -l   do all processing locally, without using qsub. Will automatically
activate this option if qsub can not be found in your path.
Additional Information
To view QC system on browser, navigate to public directory in web browser.
(Ideally, public would be a public_html directory, or a directory made
public through a webserver).All derived data will be placed in the Derivatives directory, as required
by BIDS specifications.All intermediate data from each step may be found in:
{dataset}/Derivatives/{subjID_sessionLabel}/CSE_outputsAll thumbnails and statistical reports will be placed in public directory