[FIX] Update environment variable name and link to query tool README (#…

…183)

* update API_QUERY_URL to NB_API_QUERY_URL

* add include-markdown plugin

* replace README copied text with include-markdown links

* make paragraph more diff-friendly

* switch default port used by query tool container

Co-authored-by: Arman Jahanpour <[email protected]>

---------

Co-authored-by: Arman Jahanpour <[email protected]>

docs/federate.md

@@ -120,7 +120,7 @@ NB_API_TAG=latest
 
 # Configuration for query tool
 # Define the URL of the f-API as it will appear to a user
-API_QUERY_URL=http://206.12.85.19:8080 # (1)!
+NB_API_QUERY_URL=http://206.12.85.19:8080 # (1)!
 # Chose the docker image tag of the query tool (default latest)
 NB_QUERY_TAG=latest
 # Chose the port that the query tool will be exposed on the host and likely the network (default 3000)
@@ -131,7 +131,7 @@ NB_QUERY_PORT_HOST=3000
     f-API, these requests will be sent from the user's machine,
     not from the machine hosting the query tool.
 
-    Make sure you set the `API_QUERY_URL` in your `.env`
+    Make sure you set the `NB_API_QUERY_URL` in your `.env`
     as it will appear to a user on their own machine 
     - otherwise the request will fail.
 
@@ -170,9 +170,9 @@ services:
   query:
     image: "neurobagel/query_tool:${NB_QUERY_TAG:-latest}"
     ports:
-      - "${NB_QUERY_PORT_HOST:-3000}:3000"
+      - "${NB_QUERY_PORT_HOST:-3000}:5173"
     environment:
-      - API_QUERY_URL=${API_QUERY_URL:-http://localhost:8000/}
+      - NB_API_QUERY_URL=${NB_API_QUERY_URL:-http://localhost:8000/}
 ```
 
 

docs/infrastructure.md

@@ -570,13 +570,13 @@ as a standalone docker container.
 
 
 ```bash
-docker run -d -p 3000:3000 --env API_QUERY_URL=http://localhost:8000/ --name query_tool neurobagel/query_tool:latest
+docker run -d -p 3000:5173 --env NB_API_QUERY_URL=http://localhost:8000/ --name query_tool neurobagel/query_tool:latest
 ```
 
-Make sure to replace the value of `API_QUERY_URL` with the `IP:PORT` or domain name of the
+Make sure to replace the value of `NB_API_QUERY_URL` with the `IP:PORT` or domain name of the
 new neurobagel node-API you just deployed!
 
-If using the default port mappings for the query tool (`-p 3000:3000` in above command),
+If using the default port mappings for the query tool (`-p 3000:5173` in above command),
 you can reach your local query tool at [http://localhost:3000](http://localhost:3000) once it is running.
 
 To verify the exact configuration that your new docker

docs/query_tool.md

@@ -2,83 +2,15 @@
 
 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](https://www.javascript.com/) using a variety of tools including [Nuxt](https://nuxtjs.org/), [Cypress](https://www.cypress.io/), and [BootstrapVue](https://bootstrap-vue.org/docs).
+The query tool is a React application, developed in [TypeScript](https://www.typescriptlang.org/) using a variety of tools including [Vite](https://vitejs.dev/), [Cypress](https://www.cypress.io/), and [MUI](https://mui.com/).
 
 ## Quickstart
-
-The query tool is hosted at https://query.neurobagel.org/ and interfaces with [Neurobagel API](https://api.neurobagel.org/docs).
-
-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)](https://www.npmjs.com/) and [Node.js](https://nodejs.org/en/).
-You can find the instructions on installing npm and node in the official [documentation](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
-
-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:
-
-```bash
-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](https://github.com/nuxt/nuxt/issues/10844)).
-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](https://github.com/nvm-sh/nvm) 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](https://github.com/neurobagel/api) URL that the query tool uses to send requests to for results. The query tool utilizes [nuxt dotenv module](https://github.com/nuxt-community/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](https://github.com/neurobagel/api#local-installation)), your `.env` file would look something like this:
-
-```bash
-API_QUERY_URL=http://localhost:8000/
-```
-
-if you're using the remote api, your `.env` file would look something like this:
-
-```bash
-API_QUERY_URL=https://api.neurobagel.org/
-```
-
-### Launch the Query Tool
-
-To launch the tool in developer mode run the following command:
-
-```bash
-npm run dev
-```
-
-You can also build and then run the tool from the (production) build of the application by running the following command:
-
-```bash
-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.
+{%
+   include-markdown "https://raw.githubusercontent.com/neurobagel/query-tool/main/README.md"
+   start="## Quickstart"
+   end="You can refer to [the neurobagel documentation](https://neurobagel.org/query_tool/#downloading-query-results) to see what the outputs of the query tool look like"
+   rewrite-relative-urls=false
+%}
 
 ### Downloading query results
 
@@ -129,8 +61,16 @@ Example:
 
 #### `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](https://neurobagel.org/infrastructure/#set-the-environment-variables).
+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](https://neurobagel.org/infrastructure/#set-the-environment-variables).
 
 Example:
 
 {{ read_table('./repos/neurobagel_examples/query-tool-results/participant-level-results-agg.tsv') }}
+
+## Testing
+{%
+   include-markdown "https://raw.githubusercontent.com/neurobagel/query-tool/main/README.md"
+   start="## Testing"
+%}

mkdocs.yml

@@ -100,3 +100,4 @@ plugins:
       - url: "https://github.com/neurobagel/neurobagel_examples"
         include: [ "query-tool-results" ]
         branch: "main"
+  - include-markdown

requirements.txt

@@ -1,3 +1,4 @@
+mkdocs-include-markdown-plugin[cache]
 mkdocs-material
 mkdocs-table-reader-plugin
 mkdocs-yamp