From 4379af886aed9bb29af9415ef0e9d6e259e17e3a Mon Sep 17 00:00:00 2001 From: Arman Jahanpour <77515879+rmanaem@users.noreply.github.com> Date: Wed, 20 Mar 2024 17:44:09 -0400 Subject: [PATCH] [DOC] Updated README.md (#89) * Updated README.md * Ran prettier --- README.md | 187 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 164 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index a719a18e..7d21790e 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,175 @@ -# React + TypeScript + Vite +
-This template provides a minimal setup to get React working in Vite with HMR and some ESLint rules. +# Query Tool -Currently, two official plugins are available: +
+ + deployed app + + + component test + + + e2e test + + + Node + + GitHub license + +
+
-- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react/README.md) uses [Babel](https://babeljs.io/) for Fast Refresh -- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react-swc) uses [SWC](https://swc.rs/) for Fast Refresh +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/). -## Developer setup +[Quickstart](#quickstart) | +[Local Installation](#local-installation) | +[Usage](#usage) | +[Testing](#testing) | +[License](#license) -Please run `npx husky install` for the first setup locally to enable husky pre-commits. +
-## Expanding the ESLint configuration +Please refer to our [**official documentation**](https://neurobagel.org/query_tool/) for more detailed information on how to use the query tool. -If you are developing a production application, we recommend updating the configuration to enable type aware lint rules: +## Quickstart -- Configure the top-level `parserOptions` property like this: +The query tool is hosted at https://query.neurobagel.org/ and interfaces with [Neurobagel federation API](https://federate.neurobagel.org/docs). + +## Local Installation + +To run the query tool locally, you have two options: + +1. Use our docker image +2. 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`](#nb_api_query_url) | string | Yes | - | https://federate.neurobagel.org/ | +| [`NB_IS_FEDERATION_API`](#nb_is_federation_api) | boolean | No | true | true | + +#### `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](https://github.com/neurobagel/api) URL that the query tool uses to send requests to for results. + +#### `NB_IS_FEDERATION_API` + +If the API you'd like to send queries to is not a [federation api](https://neurobagel.org/federate/), you need to set the `NB_IS_FEDERATION_API` to `false` as it is `true` by default. + +#### 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](https://github.com/neurobagel/api#local-installation)), your `.env` file would look something like this: + +```bash +NB_API_QUERY_URL=http://localhost:8000/ +NB_IS_FEDERATION_API=false # For node API +``` + +if you're using the remote (in this example federation) api, your `.env` file would look something like this: + +```bash +NB_API_QUERY_URL=https://federate.neurobagel.org/ +``` + +:warning: 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: + +```bash +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 + +```bash +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: + +```bash +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)](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 +``` + +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 ([production](https://vitejs.dev/guide/build)) build of the application by running the following command: + +```bash +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: -```js -export default { - // other rules... - parserOptions: { - ecmaVersion: 'latest', - sourceType: 'module', - project: ['./tsconfig.json', './tsconfig.node.json'], - tsconfigRootDir: __dirname, - }, -}; ``` +npx husky install +``` + +## 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. + +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 and how they are structured. You can also download the raw example output files [here](https://github.com/neurobagel/neurobagel_examples/tree/main/query-tool-results). + +## Testing + +The query tool utilizes [Cypress](https://www.cypress.io/) framework for testing. + +To run the tests execute the following command: + +```bash +npx cypress open +``` + +## License -- Replace `plugin:@typescript-eslint/recommended` to `plugin:@typescript-eslint/recommended-type-checked` or `plugin:@typescript-eslint/strict-type-checked` -- Optionally add `plugin:@typescript-eslint/stylistic-type-checked` -- Install [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react) and add `plugin:react/recommended` & `plugin:react/jsx-runtime` to the `extends` list +The query tool is released under the terms of the [MIT License](LICENSE)