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 React application, developed in TypeScript using a variety of tools including Vite, Cypress, and MUI.

Quickstart

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

Local Installation

To run the query tool locally, you have two options:

Use our docker image
Do a manual install from the cloned git repo.

but before proceeding with either you need to set the environment variables.

Mandatory configuration

Environment variable	Type	Required	Default value if not set	Example
`NB_API_QUERY_URL`	string	Yes	-	`https://federate.neurobagel.org/`
`NB_QUERY_APP_BASE_PATH`	string	No	`/`	`/query/`
`NB_ENABLE_AUTH`	boolean	No	`false`	`false`
`NB_QUERY_CLIENT_ID`	string	Yes (if `NB_ENABLE_AUTH` is set to true)	-	`46923719231972-dhsahgasl3123.apps.googleusercontent.com`

`NB_API_QUERY_URL`

You'll need to set the NB_API_QUERY_URL environment variable required to run the query tool. NB_API_QUERY_URL is the Neurobagel API URL that the query tool uses to send requests to for results.

`NB_QUERY_APP_BASE_PATH`

If you are using a custom configuration where the query tool is accessible via a path other than the root (/), you need to set the NB_QUERY_APP_BASE_PATH to your custom path. This ensures that the query tool is correctly rendered and accessible at the specified URL

`NB_ENABLE_AUTH`

If the API you'd like to send queries to requires authentication, you need to set NB_ENABLE_AUTH to true as it is false by default. This will enable authentication flow of the app.

`NB_QUERY_CLIENT_ID`

If the NB_ENABLE_AUTH is set to true (it is false by default), you need to provide a valid client ID for the authentication. At the moment, query tool uses Google for authentication, so you need to obtain a client ID from Google developer console. See documentation for more information.

Set the environment variables

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

NB_API_QUERY_URL=http://localhost:8000/

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

NB_API_QUERY_URL=https://federate.neurobagel.org/

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

NB_API_QUERY_URL=https://federate.neurobagel.org/
NB_ENABLE_AUTH=true
NB_QUERY_CLIENT_ID=46923719231972-dhsahgasl3123.apps.googleusercontent.com

The protocol matters here. If you wish to use the Neurobagel remote API, ensure your NB_API_QUERY_URL uses https instead of http.

Docker installation

To obtain the query tool docker image, simply run the following command in your terminal:

docker pull neurobagel/query_tool:latest

This Docker image includes the latest release of the query tool and a minimal http server to serve the static tool.

To launch the query tool Docker container and pass in the .env file you have created, simply run

docker run -p 5173:5173 --env-file=.env neurobagel/query_tool:latest

Then you can access the query tool at http://localhost:5173

Note: the query tool is listening on port 5173 inside the docker container, replace port 5173 by the port you would like to expose to the host. For example if you'd like to run the tool on port 8000 of your machine you can run the following command:

docker run -p 8000:5173 --env-file=.env neurobagel/query_tool:latest

Manual installation

To install the query tool directly, 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

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

npm run dev

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

npm run build && npm run preview

You can verify the tool is running by watching for the` info messages from Vite regarding environment, rendering, and what port the tool is running on in your terminal.

Developer setup

Having installed the dependencies, run the following command to enable husky pre-commit and post-merge hooks:

npx husky install

Docker compose testing environment for development

Since the query tool relies on other neurobagel tools to function, their presence is often required during development. To facilitate this, a docker compose containing a complete testing environment has been created. To use it follow the steps below:

Install recipes and neurobagel_examples submodules:

git submodule init
git submodule update

Bring up the stack using the test profile:

docker compose --profile test up -d

NOTE: Make sure your .env file in the root directory doesn't contain any of the environment variables used in the docker compose file as it will conflict with the configuration, since docker compose will try to use .env by default.

Usage

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.\ The query tool offers two different TSV files for results:

Dataset-level results TSV contains: dataset id, dataset name, dataset portal uri, number of matching subjects, and available imaging modalities
Participant-level results TSV contains: dataset id, subject id, age, sex, diagnosis, assessment, session id, session file path, number of sessions, and imaging modality

The output files can be joined using DatasetID as key.

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/e0c7d08c-edcc-4c2a-816a-306878ed7be2	BIDS synthetic	https://github.com/bids-standard/bids-examples	5	http://purl.org/nidash/nidm#FlowWeighted, http://purl.org/nidash/nidm#T1Weighted

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
SessionID: the label of the session
SessionType: either ImagingSession or PhenotypicSession
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
SessionFilePath: the path of the session directory (for imaging sessions) either relative to the dataset root (for datasets available through DataLad) or relative to the root of the filesystem where the dataset is stored
NumPhenotypicSessions: (aggregate variable) total number of phenotypic sessions that match the query for a subject
NumImagingSessions: (aggregate variable) total number of imaging sessions that match the query for a 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	SessionID	SessionType	Age	Sex	Diagnosis	Assessment	SessionFilePath	NumPhenotypicSessions	NumImagingSessions	Modality
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-01	ses-01	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-01/ses-01	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-01	ses-01	http://neurobagel.org/vocab/PhenotypicSession	34.1	http://purl.bioontology.org/ontology/SNOMEDCT/248152002	nan	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed, https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-01	ses-02	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-01/ses-02	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-01	ses-02	http://neurobagel.org/vocab/PhenotypicSession	35.3	http://purl.bioontology.org/ontology/SNOMEDCT/248152002	nan	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed, https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-02	ses-01	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-02/ses-01	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-02	ses-01	http://neurobagel.org/vocab/PhenotypicSession	nan	http://purl.bioontology.org/ontology/SNOMEDCT/248153007	http://purl.bioontology.org/ontology/SNOMEDCT/406506008	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed, https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-02	ses-02	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-02/ses-02	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-02	ses-02	http://neurobagel.org/vocab/PhenotypicSession	39	http://purl.bioontology.org/ontology/SNOMEDCT/248153007	http://purl.bioontology.org/ontology/SNOMEDCT/406506008	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed, https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-03	ses-01	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-03/ses-01	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-03	ses-01	http://neurobagel.org/vocab/PhenotypicSession	22.1	nan	nan	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-03	ses-02	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-03/ses-02	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-03	ses-02	http://neurobagel.org/vocab/PhenotypicSession	23.2	nan	http://purl.bioontology.org/ontology/SNOMEDCT/406506008	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed, https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-04	ses-01	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-04/ses-01	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-04	ses-01	http://neurobagel.org/vocab/PhenotypicSession	21.1	http://purl.bioontology.org/ontology/SNOMEDCT/248152002	nan	https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-04	ses-02	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-04/ses-02	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-04	ses-02	http://neurobagel.org/vocab/PhenotypicSession	22.3	http://purl.bioontology.org/ontology/SNOMEDCT/248152002	nan	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed, https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-05	ses-01	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-05/ses-01	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-05	ses-01	http://neurobagel.org/vocab/PhenotypicSession	42.5	http://purl.bioontology.org/ontology/SNOMEDCT/248153007	http://purl.bioontology.org/ontology/SNOMEDCT/406506008	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed, https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-05	ses-02	http://neurobagel.org/vocab/ImagingSession	nan	nan	nan	nan	/data/neurobagel/bagel-cli/bids-examples/synthetic/sub-05/ses-02	2	2	http://purl.org/nidash/nidm#T1Weighted, http://purl.org/nidash/nidm#FlowWeighted
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	sub-05	ses-02	http://neurobagel.org/vocab/PhenotypicSession	43.2	http://purl.bioontology.org/ontology/SNOMEDCT/248153007	http://purl.bioontology.org/ontology/SNOMEDCT/406506008	https://www.cognitiveatlas.org/task/id/trm_57964b8a66aed, https://www.cognitiveatlas.org/task/id/tsk_4a57abb949ece	nan	2	2	nan

`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	SessionID	SessionType	Age	Sex	Diagnosis	Assessment	SessionFilePath	NumPhenotypicSessions	NumImagingSessions	Modality
http://neurobagel.org/vocab/e0c7d08c-edcc-4c2a-816a-306878ed7be2	protected	protected	protected	protected	protected	protected	protected	protected	protected	protected	protected

Testing

The query tool utilizes Cypress framework for testing.

To run the tests execute the following command:

npx cypress open

License

The query tool is released under the terms of the MIT License

The Neurobagel Query Tool

Quickstart

Local Installation

Mandatory configuration

NB_API_QUERY_URL

NB_QUERY_APP_BASE_PATH

NB_ENABLE_AUTH

NB_QUERY_CLIENT_ID

Set the environment variables

Docker installation

Manual installation

Developer setup

Docker compose testing environment for development

Usage

Downloading query results

Dataset-level results

Participant-level results

protected participant-level results in aggregate mode

Testing

License

`NB_API_QUERY_URL`

`NB_QUERY_APP_BASE_PATH`

`NB_ENABLE_AUTH`

`NB_QUERY_CLIENT_ID`

`protected` participant-level results in aggregate mode