7. BrainSuite Dashboard

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

To use the Dashboard, the BrainSuite BIDS App QC system generates snapshot images during processing and status information regarding the processing of the data for each subject. These outputs are monitored by the Dashboard, which presents them in an interactive browser page.

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

7.2. Running real-time QC and BrainSuite Dashboard without a web server

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

7.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 9095:9095
  -v /path/to/local/bids/input/dataset/:/data:ro \
  -v /path/to/local/output/:/output \
  bids/brainsuite:v23a \
  /data /output participant --stages DASHBOARD --localWebserver

where -p 9095:9095 tells the Docker to expose the local host’s port 9095 to Docker container’s port 9095. If you would like to change the local host’s port number, you can do so by modifying the first port number in -p (e.g., -p 9999:9095). If you decide to change the container’s port number, please also specify this new container’s port number using the argument --port for the BrainSuite BIDS App.

Important

If you are running a remote desktop or any other connections, please check that you are not using the same port as the one you have chosen to expose, as defined in -p (i.e. port 9999 in -p 9999:9095). Using the same port number may disconnect the active connections using this specific port.

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.

7.2.3. Command-line interface using Singularity

Unlike Docker, for Singularity, you can directly use your local host’s file system paths and are not required to expose your local host’s port.

To run real-time monitoring using Singularity:

singularity run bids_brainsuite_v23a.simg \
      /path/to/local/input /path/to/local/output participant \
      --stages DASHBOARD --localWebserver

where bids_brainsuite_v23a.simg is the path and name of the converted Singularity BrainSuite BIDS App image.

If you would like to modify the port number, you can use the --port argument from the BrainSuite BIDS App to specify the port number. Again, make sure that the output directory will contain/contains the processed outputs.

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

7.3.1. Run 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.

7.3.2. Command-line interface using Docker

To run real-time monitoring using Docker:

docker run -ti --rm \
  -v /path/to/local/bids/input/dataset/:/data:ro \
  -v /path/to/local/output/:/output \
  bids/brainsuite:v23a \
  /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.

7.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_v23a.simg \
      /path/to/local/input /path/to/local/output participant \
      --stages DASHBOARD --QCdir /path/to/QC/output

where bids_brainsuite_v23a.simg is the path and name of 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.

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