diff --git a/.github/workflows/stale.yml b/.github/workflows/stale.yml index e4565fe0..6bdaf383 100644 --- 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 index 5b28c007..f29553a1 100644 --- 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 --help +### Input files +To run the CLI on a dataset you have annotated, you will need: -# Singularity -singularity run bagel.sif --help -``` +
+- [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) +
+ +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 --help + ``` + +=== "Singularity" + + ```bash + singularity run bagel.sif --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 +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 + ``` + +=== "Singularity" + ```bash + singularity run --no-home --bind $PWD --pwd $PWD /path/to/bagel.sif + ``` -# Singularity -singularity run --no-home --bind $PWD --pwd $PWD /path/to/bagel.sif -``` 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 index 8e90f80e..3e5bdd87 100644 --- 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 index d4e771d2..0ba18b69 100644 --- 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 index ef5bed47..db579e83 100644 --- 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 index 8ddc53d6..10b566bb 100644 --- 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