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.