Please refer to our official documentation for more detailed information on how to use the query tool.
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.
To run the query tool locally, you have two options:
To obtain the query tool docker image, simply run
docker pull neurobagel/query_tool:latest
in your terminal. The Docker image includes the most recent build of the query tool and a minimal http server to serve the static tool.
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!
:warning: 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.
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 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/
:warning: The protocol matters here.
If you wish to use the Neurobagel remote API, ensure your API_QUERY_URL
uses https
instead of http
.
To launch the query tool Docker container and pass in the .env
file you have created, simply run
docker run -p 3000:3000 --env-file=.env neurobagel/query_tool:latest
Then you can access the query tool at http://localhost:3000
Note: the query tool is listening on port 3000
inside the docker container,
replace port 3000
by the port you would like to expose to the host.
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.
To define a cohort, set your inclusion criteria using the following:
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:
The output files can be joined using DatasetID
as key.
You can refer to the neurobagel documentation to see what the outputs of the query tool look like and how they are structured. You can also download the raw example output files here.
The query tool utilizes Cypress framework for testing.
To run the tests execute the following command:
npx cypress open
The query tool is released under the terms of the MIT License