5. Running QC and BrainSuite Dashboard¶

BrainSuite Dashboard integrates with the BrainSuite BIDS App and is a browser-based system that provides interactive visualization of the intermediate participant-level workflow outputs as they are generated, enabling users to track the state of processing and identify errors as they occur.

5.1. Run a separate BrainSuite BIDS App instance to monitor processing in real-time¶

To run QC and BrainSuite Dashboard along with your processing for real-time updates, you will need to launch a separate instance of the BrainSuite BIDS App image.

You can do so by opening another terminal while your participant-level processing is running and executing one of the following commands.

Note

You can still launch the BrainSuite Dashboard even after your processing has completed. All you have to do is run participant level again with --stages DASHBOARD. See below for more details.

5.2. Running real-time QC and BrainSuite Dashboard without a web server¶

5.2.1. Launching web server from BIDS App¶

If your institution does not have a running web server, you can launch a local web server from BrainSuite BIDS App. A web server required to view the BrainSuite Dashboard in the web browser.

Important

The web server instance must be run on a system with read access to the output folder and with the ability to serve content through any firewalls between itself and the user.

5.2.2. Command-line interface using Docker¶

You can launch a web server using BrainSuite BIDS App by adding the flag --localWebserver. You will also need to expose a port to the image; for example:

docker run -ti --rm \
  -p 8080:8080
  -v /path/to/local/bids/input/dataset/:/data \
  -v /path/to/local/output/:/output \
  bids/brainsuite:v21a \
  /data /output participant --stages DASHBOARD --localWebserver

where -p 8080:8080 tells the Docker to expose port local host’s port 8080 to Docker container’s port 8080. If you would like to change the port number, you can do so by adding --port ## after --localWebserver.

Stages include DASHBOARD, which indicates that the BrainSuite BIDS App will launch the real-time monitoring.

Again, 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. IMPORTANT: Make sure that the output directory will contain/contains the processed outputs.

5.2.3. Command-line interface using Singularity¶

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

To run real-time monitoring:

singularity run bids_brainsuite_v21a_$date_###.img \
      /path/to/local/input /path/to/local/output participant --stages DASHBOARD --localWebserver

where bids_brainsuite_v21a_$date_###.img is the converted Singularity BrainSuite BIDS App image.

5.3. Running real-time QC and BrainSuite Dashboard with an existing web server¶

If your institution has a running web server and you would like to serve using this web server, you do not need to expose ports or start a local web server. Instead, all you need to do is to set the path to the QC output directory (where the snapshot PNG files will be stored). Also, this QC output directory must be where the web server will be serving from.

5.3.1. Explain running a separate instance to monitor real-time¶

As a reminder, to run QC and BrainSuite Dashboard along with your processing for real-time updates, you will need to launch a separate instance of the BrainSuite BIDS App image.

You can do so by opening another terminal while your participant-level processing is running and executing one of the following commands.

5.3.2. Command-line interface using Docker¶

To run real-time monitoring using Docker:

docker run -ti --rm \
  -p 8080:8080
  -v /path/to/local/bids/input/dataset/:/data \
  -v /path/to/local/output/:/output \
  bids/brainsuite:v21a \
  /data /output participant --stages DASHBOARD --QCdir /path/to/QC/output

where --QCdir specifies the folder where the snapshot PNG files will be stored and where the web server will be serving from.

Important

Path specified by --QCdir must be relative to the Docker container’s file system.

5.3.3. Command-line interface using Singularity¶

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

To run real-time monitoring:

singularity run bids_brainsuite_v21a_$date_###.img \
      /path/to/local/input /path/to/local/output participant --stages DASHBOARD --QCdir /path/to/QC/output

where bids_brainsuite_v21a_$date_###.img is the converted Singularity BrainSuite BIDS App image. And --QCdir specifies the folder where the snapshot PNG files will be stored and where the web server will be serving from.

5.4. Arguments for BrainSuite QC/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 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.