The Neurobagel Query Tool

Neurobagel's query tool is a web interface for searching across a Neurobagel graph based on various subject clinical-demographic and imaging parameters.

The query tool is a Vue application, developed in JavaScript using a variety of tools including Nuxt, Cypress, and BootstrapVue.

Quickstart

The query tool is hosted at https://query.neurobagel.org/ and interfaces with Neurobagel API.

NOTE: Currently, to access the query tool, you must be connected to the McGill network.

Local Installation

Install Dependencies

To run the query tool, you'll need node package manager (npm) and Node.js. You can find the instructions on installing npm and node in the official documentation.

Once you have npm and node installed, you'll need to install the dependencies outlined in the package.json file. You can do so by running the following command:

npm install

use node v16.x LTS!

The query tool is built with the Nuxt framework and currently depends on Nuxt2. Nuxt2 does not support node versions beyond the v16 LTS (see e.g. this Github issue). If you want to run the tool locally, make sure you are using node v16.x. A good way to manage different node versions is to use the node version manager tool.

Set the Environment Variables

You'll need to set the API_QUERY_URL environment variable required to run the query tool. API_QUERY_URL is the Neurobagel API URL that the query tool uses to send requests to for results. The query tool utilizes nuxt dotenv module for managing environment variables.

To set environment variables, create an .env file in the root directory and add the environment variables there. If you're running the Neurobagel API locally on your machine (following the instructions here), your .env file would look something like this:

API_QUERY_URL=http://localhost:8000/

if you're using the remote api, your .env file would look something like this:

API_QUERY_URL=https://api.neurobagel.org/

Launch the Query Tool

To launch the tool in developer mode run the following command:

npm run dev

You can also build and then run the tool from the (production) build of the application by running the following command:

npm run build && npm run start

You can verify the tool is running once you receive info messages from Nuxt regarding environment, rendering, and what port the tool is running on in your terminal.

Usage

Running a query

To define a cohort, set your inclusion criteria using the following:

• Age: Minimum and/or maximum age (in years) of participant that should be included in the results.
• Sex: Sex of participant that should be included in the results.
• Diagnosis: Diagnosis of participant that should be included in the results
• Healthy control: Whether healthy participants should be included in the results. Once healthy control checkbox is selected, diagnosis field will be disabled since a participant cannot be both a healthy control and have a diagnosis.
• Minimum number of sessions: Minimum number of imaging sessions that participant should have to be included in the results.
• Assessment tool: Non-imaging assessment completed by participant that should be included in the results.
• Modality: Imaging modality of participant scans that should be included in the results.

Once you've defined your criteria, submit them as a query and the query tool will display the results.

Downloading query results

For a given query, the query tool offers two kinds of TSV files for results that users can download. At least one dataset matching the query must be selected in the interface in order to download the query results.

Dataset-level results

The dataset-level results TSV describes the datasets that contain subjects matching the user's query. This TSV contains the following columns:

• DatasetID: unique identifier (UUID) for dataset in the graph. Note that this ID is not guaranteed to be persistent across versions of a graph/across graphs, but will always be identical across a pair of query tool result files. This column can be used as the key to join the dataset-level and participant-level results TSVs for a given query result, if needed.
• DatasetName: human readable name of the dataset
• PortalURI: URL to a website or page about the dataset, if available
• NumMatchingSubjects: (aggregate variable) number of subjects matching the query within the dataset
• AvailableImageModalites: (aggregate variable) list of unique imaging modalities available for the dataset

Example:

DatasetID	DatasetName	PortalURI	NumMatchingSubjects	AvailableImageModalities
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	BIDS synthetic	https://github.com/bids-standard/bids-examples	5	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted

Participant-level results

The participant-level results TSV contains the available harmonized participant attributes for subject sessions matching the query in each (selected) matching dataset. Each row in the TSV corresponds to a single matching subject session.

This TSV contains the following columns:

• DatasetID: unique identifier (UUID) for dataset in the graph. Note that this ID is not guaranteed to be persistent across versions of a graph/across graphs, but will always be identical across a pair of query tool result files. This column can be used as the key to join the dataset-level and participant-level results TSVs for a given query result, if needed.
• SubjectID: subject label
• Age: subject age, if available
• Sex: subject sex, if available
• Diagnosis: list of diagnoses of subject, if available
• Assessment : list of assessments completed by subject, if available
• SessionID: session label
• SessionPath: the path of the session directory relative to the dataset root (for datasets available through DataLad) or root of the filesystem where the dataset is stored
• NumSessions: (aggregate variable) total number of available sessions for subject. This number will be the same across rows corresponding to the same subject.
• Modality: imaging modalities acquired in the session, if available

Example:

DatasetID	SubjectID	Age	Sex	Diagnosis	Assessment	SessionID	SessionPath	NumSessions	Modality
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-01	34.1	http://purl.bioontology.org/ontology/SNOMEDCT/248152002	nan	https://www.cognitiveatlas.org/task/id/4321, https://www.cognitiveatlas.org/task/id/1234	ses-01	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-01/ses-01	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-01	34.1	http://purl.bioontology.org/ontology/SNOMEDCT/248152002	nan	https://www.cognitiveatlas.org/task/id/4321, https://www.cognitiveatlas.org/task/id/1234	ses-02	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-01/ses-02	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-02	nan	http://purl.bioontology.org/ontology/SNOMEDCT/248153007	http://purl.bioontology.org/ontology/SNOMEDCT/49049000	https://www.cognitiveatlas.org/task/id/4321	ses-01	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-02/ses-01	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-02	nan	http://purl.bioontology.org/ontology/SNOMEDCT/248153007	http://purl.bioontology.org/ontology/SNOMEDCT/49049000	https://www.cognitiveatlas.org/task/id/4321	ses-02	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-02/ses-02	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-03	22.1	nan	nan	https://www.cognitiveatlas.org/task/id/1234	ses-01	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-03/ses-01	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-03	22.1	nan	nan	https://www.cognitiveatlas.org/task/id/1234	ses-02	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-03/ses-02	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-04	21.1	http://purl.bioontology.org/ontology/SNOMEDCT/248152002	nan	https://www.cognitiveatlas.org/task/id/4321	ses-01	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-04/ses-01	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-04	21.1	http://purl.bioontology.org/ontology/SNOMEDCT/248152002	nan	https://www.cognitiveatlas.org/task/id/4321	ses-02	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-04/ses-02	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-05	42.5	http://purl.bioontology.org/ontology/SNOMEDCT/248153007	http://purl.bioontology.org/ontology/SNOMEDCT/49049000	https://www.cognitiveatlas.org/task/id/4321, https://www.cognitiveatlas.org/task/id/1234	ses-01	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-05/ses-01	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	sub-05	42.5	http://purl.bioontology.org/ontology/SNOMEDCT/248153007	http://purl.bioontology.org/ontology/SNOMEDCT/49049000	https://www.cognitiveatlas.org/task/id/4321, https://www.cognitiveatlas.org/task/id/1234	ses-02	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-05/ses-02	2	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted

protected participant-level results in aggregate mode

If the values for all columns except for DatasetID and SessionPath in the participant-level results tsv are set to protected, this indicates the graph being queried has been configured (via its corresponding Neurobagel node API) to return only aggregate information about matches (due to data privacy reasons). This configuration can be modified by setting the NB_RETURN_AGG environment variable to false (the value is by default true). see related section of the documentation here.

Example:

DatasetID	SubjectID	Age	Sex	Diagnosis	Assessment	SessionID	SessionPath	NumSessions	Modality
http://neurobagel.org/vocab/81e47a09-658d-48ea-b7c5-8d54820d038e	protected	protected	protected	protected	protected	protected	protected	protected	protected