[ENH] Update instructions for running CLI (#90)

* add config for linked content tabs and code copying * update example Docker commands and add explicit Singularity commands * describe input data needed by CLI * add note on slowness of bids command
neurobagel · Sep 22, 2023 · 375e0d2 · 375e0d2
1 parent 90041f0
commit 375e0d2
Show file tree

Hide file tree

Showing 2 changed files with 108 additions and 42 deletions.
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/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