Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[DOC] Remove usage instructions & update development environment section in README #365

Merged
merged 2 commits into from
Oct 24, 2024
+34 −118
Merged

[DOC] Remove usage instructions & update development environment section in README #365

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
208f21b
remove usage instructions & update dev env section
alyssadai Oct 24, 2024
74e1b9a
bold docs link
alyssadai Oct 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 34 additions & 118 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,150 +3,66 @@
# `bagel-cli`
[![Coverage Status](https://coveralls.io/repos/github/neurobagel/bagel-cli/badge.svg?branch=main)](https://coveralls.io/github/neurobagel/bagel-cli?branch=main)
[![Tests](https://github.com/neurobagel/bagel-cli/actions/workflows/test.yml/badge.svg)](https://github.com/neurobagel/bagel-cli/actions/workflows/test.yml)
[![Docker Image Version](https://img.shields.io/docker/v/neurobagel/bagelcli?label=docker)](https://hub.docker.com/r/neurobagel/bagelcli/tags)

</div>

The Bagel CLI is a simple Python command line tool to automatically read and annotate a
[BIDS dataset](https://bids-specification.readthedocs.io/en/stable/)
so that it can be integrated into the Neurobagel graph.
The `bagel-cli` is a Python command-line tool to automatically parse and describe subject phenotypic and imaging attributes in an annotated dataset for integration into the Neurobagel graph.

Please refer to our [**official Neurobagel documentation**](https://neurobagel.org/cli/) for more information on how to use the CLI.
**Please refer to our [official Neurobagel documentation](https://neurobagel.org/cli/) for information on how to install and use the CLI.**

## Installation
### Docker
Option 1 (RECOMMENDED): Pull the Docker image for the CLI from Docker Hub: `docker pull neurobagel/bagelcli`

Option 2: Clone the repository and build the Docker image locally:
```bash
git clone https://github.com/neurobagel/bagel-cli.git
cd bagel-cli
docker build -t bagel .
```

### Singularity
Build a Singularity image for `bagel-cli` using the Docker Hub image:
`singularity pull bagel.sif docker://neurobagel/bagelcli`

## Running the CLI
CLI commands can be accessed using the Docker/Singularity image.

NOTE: The Docker examples below assume that you are using the official [Neurobagel Docker Hub](https://hub.docker.com/u/neurobagel) image for the CLI.
If you have instead locally built an image, replace `neurobagel/bagelcli` in commands with your built image tag.

### To see the CLI options:
```bash
# Docker
docker run --rm neurobagel/bagelcli # this is a shorthand for `docker run --rm neurobagel/bagelcli --help

# Singularity
singularity run bagel.sif
```
For a specific command:
```bash
# Docker
docker run --rm neurobagel/bagelcli <command-name> --help

# Singularity
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-cli` container and include your CLI command at the end in the following format:
```bash
# Docker
docker run --rm --volume=$PWD:$PWD -w $PWD neurobagel/bagelcli <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`:
```
home/
└── data/
└── Dataset1/
├── neurobagel/
│ ├── Dataset1_pheno.tsv
│ └── Dataset1_pheno.json
└── bids/
├── sub-01
├── sub-02
└── ...
```

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 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"
```

## Development environment

To ensure that our Docker images are built in a predictable way,
we use `requirements.txt` as a lock-file.
That is, `requirements.txt` includes the entire dependency tree of our tool,
with pinned versions for every dependency (see [also](https://pip.pypa.io/en/latest/topics/repeatable-installs/#repeatability))
with pinned versions for every dependency (see [here](https://pip.pypa.io/en/latest/topics/repeatable-installs/#repeatability) for more information).


### Setting up a local development environment
We suggest that you create a development environment
To work on the CLI, we suggest that you create a development environment
that is as close as possible to the environment we run in production.

To do so, we first need to install the dependencies from our lockfile (`dev_requirements.txt`):
1. Install the dependencies from the lockfile (`dev_requirements.txt`):

```bash
pip install -r dev_requirements.txt
```
```bash
pip install -r dev_requirements.txt
```

And then we install the CLI without touching the dependencies
2. Install the CLI without touching the dependencies:

```bash
pip install --no-deps -e .
```
```bash
pip install --no-deps -e .
```

Finally, to run the test suite we need to install the `bids-examples` and `neurobagel_examples` submodules:
```bash
git submodule init
git submodule update
```
Confirm that everything works well by running a test
3. Install the `bids-examples` and `neurobagel_examples` submodules needed to run the test suite:
```bash
git submodule init
git submodule update
```

Confirm that everything works well by running the tests:
`pytest .`

### Update python lock-file
The `requirements.txt` file is automatically generated from the `setup.cfg`
constraints. To update it, we use `pip-compile` from the `pip-tools` package.
Here is how you can use these tools to update the `requirements.txt` file.

To install:
```bash
pip install pip-tools
```

To update the runtime dependencies in `requirements.txt`, run
```bash
pip-compile -o requirements.txt --upgrade
```

The above command only updates the runtime dependencies.
To update the developer dependencies in `dev_requirements.txt`, run:
```bash
pip-compile -o dev_requirements.txt --extra all
```
1. Ensure `pip-tools` is installed:
```bash
pip install pip-tools
```
2. Update the runtime dependencies in `requirements.txt`:
```bash
pip-compile -o requirements.txt --upgrade
```
3. The above command only updates the runtime dependencies.
Now, update the developer dependencies in `dev_requirements.txt`:
```bash
pip-compile -o dev_requirements.txt --extra all
```

## Regenerating the Neurobagel vocabulary file
Terms in the Neurobagel namespace (`nb` prefix) and their class relationships are serialized to a file
Expand Down
Loading