Merge branch 'main' into maint-83

neurobagel · Sep 22, 2023 · 1f431f8 · 1f431f8
2 parents 0a2c36c + 375e0d2
commit 1f431f8
Show file tree

Hide file tree

Showing 6 changed files with 129 additions and 59 deletions.
diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml
@@ -21,4 +21,4 @@ jobs:
           days-before-stale: 30
           days-before-close: -1
           stale-issue-label: '_flag:stale'
-          exempt-issue-labels: ['Roadmap', 'Milestone', 'Epic', 'someday']
+          exempt-issue-labels: 'Roadmap,Milestone,Epic,someday'
diff --git a/docs/cli.md b/docs/cli.md
@@ -4,7 +4,7 @@ The `bagel-cli` is a simple Python command-line tool to automatically parse and
 
 ## Installation
 ### Docker
-Option 1: Pull the Docker image for the CLI from DockerHub: `docker pull neurobagel/bagelcli`
+Option 1 (RECOMMENDED): Pull the Docker image for the CLI from DockerHub: `docker pull neurobagel/bagelcli`
 
 Option 2: Clone the repository and build the Docker image locally:
 ```bash
@@ -18,41 +18,74 @@ Build a Singularity image for `bagel-cli` using the DockerHub image:
 `singularity pull bagel.sif docker://neurobagel/bagelcli`
 
 ## Running the CLI
-CLI commands can be accessed using the Docker/Singularity image you have built.
+CLI commands can be accessed using the Docker/Singularity image.
 
-### To view the CLI options
-```bash
-# Docker
-docker run --rm bagel  # this is a shorthand for `docker run --rm bagel --help
+!!! note 
+    The Docker examples below assume that you are using the official Neurobagel Docker Hub image for the CLI. 
+    If you have instead locally built an image, replace `neurobagel/bagelcli` in commands with your built image tag.
 
-# Singularity
-singularity run bagel.sif
-```
-For a specific command:
-```bash
-# Docker
-docker run --rm bagel <command-name> --help
+### Input files
+To run the CLI on a dataset you have annotated, you will need:
 
-# Singularity
-singularity run bagel.sif <command-name> --help
-```
+<div class="annotate" markdown>
+- [A phenotypic TSV](./data_prep.md)
+- [A corresponding phenotypic JSON data dictionary](./dictionaries.md)
+- (Optional) The imaging dataset in [BIDS](https://bids-specification.readthedocs.io/en/stable/) format, if subjects have imaging data available (1)
+</div>
+
+1. A valid BIDS dataset is needed for the CLI to automatically generate harmonized subject-level imaging metadata alongside harmonized phenotypic attributes.
+
+### To view the available CLI commands
+
+=== "Docker"
+
+    ```bash
+    # Note: this is a shorthand for `docker run --rm neurobagel/bagelcli --help`
+    docker run --rm neurobagel/bagelcli
+    ```
+
+=== "Singularity"
+
+    ```bash
+    # Note: this is a shorthand for `singularity run bagel.sif --help`
+    singularity run bagel.sif
+    ```
+
+To view the command-line arguments for a specific command:
+
+=== "Docker"
+
+    ```bash
+    docker run --rm neurobagel/bagelcli <command-name> --help
+    ```
+
+=== "Singularity"
+
+    ```bash
+    singularity run bagel.sif <command-name> --help
+    ```
 
 
 ### To run the CLI on data
 1. `cd` into your local directory containing (1) your phenotypic .tsv file, (2) Neurobagel-annotated data dictionary, and (3) BIDS directory (if available). 
-2. Run a `bagel` container and include your CLI command at the end in the following format:
-```bash
-# Docker
-docker run --rm --volume=$PWD:$PWD -w $PWD bagel <CLI command here>
+2. Run a `bagel-cli` container and include your CLI command and arguments at the end in the following format:
+
+=== "Docker"
+    ```bash
+    docker run --rm --volume=$PWD:$PWD -w $PWD neurobagel/bagelcli <CLI command here>
+    ```
+
+=== "Singularity"
+    ```bash
+    singularity run --no-home --bind $PWD --pwd $PWD /path/to/bagel.sif <CLI command here>
+    ```
 
-# Singularity
-singularity run --no-home --bind $PWD --pwd $PWD /path/to/bagel.sif <CLI command here>
-```
 In the above command, `--volume=$PWD:$PWD -w $PWD` (or `--bind $PWD --pwd $PWD` for Singularity) mounts your current working directory (containing all inputs for the CLI) at the same path inside the container, and also sets the _container's_ working directory to the mounted path (so it matches your location on your host machine). This allows you to pass paths to the containerized CLI which are composed the same way as on your local machine. (And both absolute paths and relative top-down paths from your working directory will work!)
 
 ### Example  
-If your data live in `/home/data/Dataset1`:
-```
+If your dataset lives in `/home/data/Dataset1`:
+
+``` { .bash .no-copy }
 home/
 └── data/
     └── Dataset1/
@@ -65,23 +98,53 @@ home/
             └── ...
 ```
 
-You could run the following: (for a Singularity container, replace the first part of the Docker commands with the Singularity command from [the above template](#to-run-the-cli-on-data))
-```bash
-cd /home/data/Dataset1
-
-# 1. Construct phenotypic subject dictionaries (pheno.jsonld)
-docker run --rm --volume=$PWD:$PWD -w $PWD bagel pheno \
-    --pheno "neurobagel/Dataset1_pheno.tsv" \
-    --dictionary "neurobagel/Dataset1_pheno.json" \
-    --output "neurobagel" \
-    --name "Dataset1"
-
-# 2. Add BIDS data to pheno.jsonld generated by step 1
-docker run --rm --volume=$PWD:$PWD -w $PWD bagel bids \
-    --jsonld-path "neurobagel/pheno.jsonld" \
-    --bids-dir "bids" \
-    --output "neurobagel"
-```
+You could run the CLI as follows:
+
+=== "Docker"
+
+    ```bash
+    cd /home/data/Dataset1
+
+    # 1. Generate phenotypic subject-level graph data (pheno.jsonld)
+    docker run --rm --volume=$PWD:$PWD -w $PWD neurobagel/bagelcli pheno \
+        --pheno "neurobagel/Dataset1_pheno.tsv" \
+        --dictionary "neurobagel/Dataset1_pheno.json" \
+        --output "neurobagel" \
+        --name "Dataset1"
+
+    # 2. Add BIDS data to pheno.jsonld generated by step 1
+    docker run --rm --volume=$PWD:$PWD -w $PWD neurobagel/bagelcli bids \
+        --jsonld-path "neurobagel/pheno.jsonld" \
+        --bids-dir "bids" \
+        --output "neurobagel"
+    ```
+
+=== "Singularity"
+
+    ```bash
+    cd /home/data/Dataset1
+
+    # 1. Generate phenotypic subject-level graph data (pheno.jsonld)
+    singularity run --no-home --bind $PWD --pwd $PWD bagel.sif pheno \
+        --pheno "neurobagel/Dataset1_pheno.tsv" \
+        --dictionary "neurobagel/Dataset1_pheno.json" \
+        --output "neurobagel" \
+        --name "Dataset1"
+
+    # 2. Add BIDS data to pheno.jsonld generated by step 1
+    singularity run --no-home --bind $PWD --pwd $PWD bagel.sif bids \
+        --jsonld-path "neurobagel/pheno.jsonld" \
+        --bids-dir "bids" \
+        --output "neurobagel"
+    ```
+
+!!! note
+    The `bids` command of the `bagel-cli` (step 2) currently can take upwards of several minutes for datasets greater than a few hundred subjects, due to the time needed for pyBIDS to read the dataset structure.
+    Once the slow initial dataset reading step is complete, you should see the message:
+    ```bash
+    Parsing BIDS metadata to be merged with phenotypic annotations:
+    ...
+    ```
 
 ## Development environment
 

diff --git a/docs/dictionaries.md b/docs/dictionaries.md
@@ -118,7 +118,8 @@ syntax for [json-ld](https://w3c.github.io/json-ld-syntax/#the-context):
 {
   "@context": {
     "nb": "http://neurobagel.org/vocab/",
-    "purl": "http://purl.obolibrary.org/obo/",
+    "ncit": "http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl#",
+    "nidm": "http://purl.org/nidash/nidm#",
     "snomed": "http://purl.bioontology.org/ontology/SNOMEDCT/",
     "cogatlas": "https://www.cognitiveatlas.org/task/id/"
   }
@@ -208,7 +209,7 @@ Terms from the National Cancer Institute Thesaurus for healthy control status.
           "Label": "Parkinson's disease"
         },
         "CTRL": {
-          "TermURL": "purl:NCIT_C94342",
+          "TermURL": "ncit:C94342",
           "Label": "Healthy Control"
         }
       }

diff --git a/docs/nipoppy/workflow/proc_pipe/mriqc.md b/docs/nipoppy/workflow/proc_pipe/mriqc.md
@@ -8,15 +8,17 @@ MRIQC processes the participants and produces image quality metrics from T1w, T2
 
 
 ### [MRIQC](https://mriqc.readthedocs.io/en/latest/)
-- Ensure you are running the appropriate MRIQC image, as provided [here](https://github.com/neurodatascience/nipoppy/blob/main/nipoppy/workflow/proc_pipe/mriqc/Dockerfile)
-- Use [run_mriqc.py](https://github.com/neurodatascience/nipoppy/tree/main/nipoppy/workflow/proc_pipe/mriqc) to run MRIQC pipeline directly or wrap the script in an SGE/Slurm script to run on cluster
+- Use [run_mriqc.py](https://github.com/neurodatascience/nipoppy/tree/main/workflow/proc_pipe/mriqc) to run MRIQC pipeline directly or wrap the script in an SGE/Slurm script to run on cluster
 
+```bash
 python run_mriqc.py --global_config CONFIG.JSON --subject_id 001 --output_dir OUTPUT_DIR_PATH
-	- Mandatory: Pass in the absolute path to the configuration containing the MRIQC container and data directory to `global_config`
-	- Mandatory: Pass in the subject id to `participant_id`
-	- Mandatory: Pass in the subject id to `session_id`
-	- Mandatory: Pass in the absolute path to the output directory to `output_dir`
-
+```
+
+- Mandatory: Pass in the absolute path to the configuration containing the MRIQC container and data directory to `global_config`
+- Mandatory: Pass in the subject id to `participant_id`
+- Mandatory: Pass in the subject id to `session_id`
+- Mandatory: Pass in the absolute path to the output directory to `output_dir`
+
 !!! note
 	An example config is located [here](https://github.com/neurodatascience/nipoppy/blob/main/nipoppy/sample_global_configs.json)
 

diff --git a/docs/term_naming_standards.md b/docs/term_naming_standards.md
@@ -27,13 +27,14 @@ What this might look like in semantic triples:
     In cases where we reuse a term for a class that comes from an existing controlled vocabulary, and that vocabulary follows a different naming convention (e.g., all lowercase), we should follow the existing naming convention.
 
 ## Currently used namespaces
-| Prefix     | IRI                                            | Types of terms                            |
-| ---------- | ---------------------------------------------- | ----------------------------------------- |
-| `nb`       | http://neurobagel.org/vocab/                   | Neurobagel-"owned" properties and classes |
-| `nbg`      | http://neurobagel.org/graph/                   | Neurobagel graph databases                |
-| `snomed`   | http://purl.bioontology.org/ontology/SNOMEDCT/ | diagnosis and sex values                  |
-| `nidm`     | http://purl.org/nidash/nidm#                   | imaging modalities                        |
-| `cogatlas` | https://www.cognitiveatlas.org/task/id/        | cognitive assessments and tasks           |
+| Prefix     | IRI                                                 | Types of terms                            |
+| ---------- | --------------------------------------------------- | ----------------------------------------- |
+| `nb`       | http://neurobagel.org/vocab/                        | Neurobagel-"owned" properties and classes |
+| `nbg`      | http://neurobagel.org/graph/                        | Neurobagel graph databases                |
+| `snomed`   | http://purl.bioontology.org/ontology/SNOMEDCT/      | diagnosis and sex values                  |
+| `ncit`     | http://ncicb.nci.nih.gov/xml/owl/EVS/Thesaurus.owl# | group designation (e.g., healthy control) |
+| `nidm`     | http://purl.org/nidash/nidm#                        | imaging modalities                        |
+| `cogatlas` | https://www.cognitiveatlas.org/task/id/             | cognitive assessments and tasks           |
 
 
 ## What if an `nb` term already exists in another controlled vocabulary?

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -7,6 +7,8 @@ theme:
   - navigation.tabs.sticky
   - navigation.indexes
   - navigation.expand
+  - content.tabs.link
+  - content.code.copy  # allow user to copy a code block's contents to the clipboard
   palette:
     primary: deep purple
     accent: amber
@@ -60,6 +62,7 @@ markdown_extensions:
   - pymdownx.emoji:
       emoji_index: !!python/name:materialx.emoji.twemoji
       emoji_generator: !!python/name:materialx.emoji.to_svg
+  - md_in_html  # for annotations
 
 plugins:
   - search