Dashboard for neuroimaging and phenotypic dataset exploration

• Overview
• Preview
• Input schema
• Creating a dashboard-ready dataset file
• Local development

Overview

digest is a web dashboard that provides interactive visual summaries and subject-level querying based on neuroimaging derivatives and phenotypic variables available for a dataset.

A digest dashboard can be generated for any tabular dataset file that follows a data modality-specific schema, which we refer to as a "bagel" file. The dashboard is compatible with the processing status bagel.csv files automatically generated by the Nipoppy framework for neuroimaging dataset organization and processing.

For more information on how to use digest with the Nipoppy project, also see the official Nipoppy documentation.

Quickstart: https://digest.neurobagel.org/

Preview

Input schema

Input files to the dashboard contain long format data that must be formatted according to the bagel schema (see also the schemas README for more info). A single file is expected to correspond to one dataset, but may contain status information for multiple processing pipelines for that dataset.

Try it out

You can view and download correctly formatted, minimal input tabular files from here to test out dashboard functionality.

Creating a dashboard-ready dataset file (bagel.csv)

While digest works on any input CSV compliant with a bagel schema, the easiest way to generate a dashboard-ready file for a dataset's neuroimaging processing info is to follow the Nipoppy standard structure for organizing raw MRI data and processed outputs (data derivatives). Nipoppy offers scripts that can use this standardized dataset organization to automatically extract info about the raw imaging files and any pipelines that have been run, which is then stored in a dashboard-ready bagel.csv.

Detailed instructions to get started using Nipoppy can be found in their documentation. In brief, generating a bagel.csv for your dataset can be as simple as:

1. Installing Nipoppy to generate a dataset directory tree for your dataset (see Installation section of docs) that you can populate with your existing data
2. Update Nipoppy configuration to reflect the pipeline versions you are using (for tracking purposes), and augment your participant spreadsheet according to Nipoppy requirements (see Configs section of docs)
3. Run the tracker (run_tracker.py) for the relevant pipeline(s) for your dataset to generate a comprehensive bagel.csv
   • To see help text for this script: python run_tracker.py --help
   • This step can be repeated as needed to update the bagel.csv with newly processed subjects

Running in a Docker container

1. To get the most recent changes, pull the neurobagel/digest docker image tagged nightly:

docker pull neurobagel/digest:nightly

2. Currently, digest also relies on a local copy of the nipoppy-qpn repository, which contains ready-to-use digest files that are automatically generated for the Quebec Parkinson Network data.

git clone https://github.com/neurodatascience/nipoppy-qpn.git

3. Run digest and mount the nipoppy-qpn directory into the container:

docker run -d -p 8050:8050 -v ${PWD}/nipoppy-qpn:/app/nipoppy-qpn neurobagel/digest:nightly

Now, the dashboard can be accessed at http://127.0.0.1:8050 on your local machine.

Local development

To install digest from the source repository, run the following in a Python environment:

git clone https://github.com/neurobagel/digest.git
cd digest
pip install -r requirements.txt

To launch the app locally:

python -m digest.app

Once the server is running, the dashboard can be accessed at http://127.0.0.1:8050/ in your browser.

Testing

pytest and dash.testing are used for testing dashboard functionality during development.

To run the tests, run the following command from the repository's root:

pytest tests