generated from FNNDSC/python-chrisapp-template
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Jennings Zhang
authored and
Jennings Zhang
committed
Mar 8, 2023
1 parent
ca72286
commit 0a58d45
Showing
11 changed files
with
197 additions
and
566 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14,5 +14,6 @@ __pycache__/ | |
| .vscode/ | ||
|
|
||
| examples/ | ||
| img/ | ||
|
|
||
| venv/ | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,19 +1,13 @@ | ||
| # Python version can be changed, e.g. | ||
| # FROM python:3.8 | ||
| # FROM docker.io/fnndsc/conda:python3.10.2-cuda11.6.0 | ||
| FROM docker.io/python:3.11.0-slim-bullseye | ||
| FROM docker.io/fnndsc/pl-lgd-hemis:base-1 | ||
|
|
||
| LABEL org.opencontainers.image.authors="FNNDSC <[email protected]>" \ | ||
| org.opencontainers.image.title="ChRIS Plugin Title" \ | ||
| org.opencontainers.image.description="A ChRIS plugin that..." | ||
| org.opencontainers.image.title="LGD WM Hemispheres" \ | ||
| org.opencontainers.image.description="White-matter hemisphere extraction for the LGD project" | ||
|
|
||
| WORKDIR /usr/local/src/app | ||
|
|
||
| COPY requirements.txt . | ||
| RUN pip install -r requirements.txt | ||
| WORKDIR /usr/local/src/pl-lgd-hemis | ||
|
|
||
| COPY . . | ||
| ARG extras_require=none | ||
| RUN pip install ".[${extras_require}]" | ||
|
|
||
| CMD ["commandname"] | ||
| CMD ["lgd_hemis"] |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,176 +1,53 @@ | ||
| # _ChRIS_ Plugin Template | ||
| # LGD White Matter Masking | ||
|
|
||
| [](https://github.com/FNNDSC/python-chrisapp-template/actions/workflows/src.yml) | ||
| [](LICENSE) | ||
| [](https://hub.docker.com/r/fnndsc/pl-lgd-hemis) | ||
| [](https://github.com/FNNDSC/pl-lgd-hemis/blob/main/LICENSE) | ||
| [](https://github.com/FNNDSC/pl-lgd-hemis/actions/workflows/ci.yml) | ||
|
|
||
| This is a minimal template repository for _ChRIS_ plugin applications in Python. | ||
|  | ||
|
|
||
| ## About _ChRIS_ Plugins | ||
| `pl-lgd-hemis` is a [_ChRIS_](https://chrisproject.org/) | ||
| _ds_ plugin which creates left and right hemisphere white matter | ||
| masks from segmentations. | ||
|
|
||
| A _ChRIS_ plugin is a scientific data-processing software which can run anywhere all-the-same: | ||
| in the cloud via a [web app](https://github.com/FNNDSC/ChRIS_ui/), or on your own laptop | ||
| from the terminal. They are easy to build and easy to understand: most simply, a | ||
| _ChRIS_ plugin is a command-line program which processes data from an input directory | ||
| and creates data to an output directory with the usage | ||
| `commandname [options...] inputdir/ outputdir/`. | ||
| Its hard-coded mappings are as follows: | ||
|
|
||
| For more information, visit our website https://chrisproject.org | ||
|
|
||
| ## How to Use This Template | ||
|
|
||
| Go to https://github.com/FNNDSC/python-chrisapp-template and click "Use this template". | ||
| The newly created repository is ready to use right away. | ||
|
|
||
| A script `bootstrap.sh` is provided to help fill in and rename values for your new project. | ||
| It is optional to use. | ||
|
|
||
| 1. Edit the variables in `bootstrap.sh` | ||
| 2. Run `./bootstrap.sh` | ||
| 3. Follow the instructions it will print out | ||
|
|
||
| ## Example Plugins | ||
|
|
||
| Here are some good, complete examples of _ChRIS_ plugins created from this template. | ||
|
|
||
| - https://github.com/FNNDSC/pl-dcm2niix (basic command wrapper example) | ||
| - <https://github.com/FNNDSC/pl-adapt_object_mesh> (parallelizes a command) | ||
| - https://github.com/FNNDSC/pl-mri-preview (uses [NiBabel](https://nipy.org/nibabel/)) | ||
| - https://github.com/FNNDSC/pl-pyvista-volume (example using Python package project structure and pytest) | ||
| - https://github.com/FNNDSC/pl-fetal-cp-surface-extract (has a good README.md) | ||
|
|
||
| ## What's Inside | ||
|
|
||
| | Path | Purpose | | ||
| |----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `app.py` | Main script: start editing here! | | ||
| | `tests/` | Unit tests | | ||
| | `setup.py` | [Python project metadata and installation script](https://packaging.python.org/en/latest/guides/distributing-packages-using-setuptools/#setup-py) | | ||
| | `requirements.txt` | List of Python dependencies | | ||
| | `Dockerfile` | [Container image build recipe](https://docs.docker.com/engine/reference/builder/) | | ||
| | `.github/workflows/ci.yml` | "continuous integration" using [Github Actions](https://docs.github.com/en/actions/learn-github-actions/understanding-github-actions): automatic testing, building, and uploads to https://chrisstore.co | | ||
|
|
||
| ## Contributing | ||
|
|
||
| The source code for the `main` branch of this repository is on the | ||
| [src](https://github.com/fnndsc/python-chrisapp-template/tree/src) | ||
| branch, which has an additional file | ||
| [`.github/workflows/src.yml`](https://github.com/FNNDSC/python-chrisapp-template/blob/src/.github/workflows/src.yml) | ||
| When tests pass, changes are automatically merged into `main`. | ||
| Developers should commit to or make pull requests targeting `src`. | ||
| Do not push directly to `main`. | ||
|
|
||
| This is a workaround in order to do automatic testing of this template | ||
| without including the `.github/workflows/src.yml` file in the template itself. | ||
|
|
||
| <!-- BEGIN README TEMPLATE | ||
| # ChRIS Plugin Title | ||
| [](https://hub.docker.com/r/fnndsc/pl-appname) | ||
| [](https://github.com/FNNDSC/pl-appname/blob/main/LICENSE) | ||
| [](https://github.com/FNNDSC/pl-appname/actions/workflows/ci.yml) | ||
| `pl-appname` is a [_ChRIS_](https://chrisproject.org/) | ||
| _ds_ plugin which takes in ... as input files and | ||
| creates ... as output files. | ||
| ## Abstract | ||
| ... | ||
| | anatomical region | mapped classification | | ||
| |---------------------|-----------------------| | ||
| | cortical plate | grey matter | | ||
| | CSF | CSF | | ||
| | brain stem | CSF | | ||
| | midbrain | CSF | | ||
| | cerebellum | CSF | | ||
| | Clear Label | background | | ||
| | everything else | white matter | | ||
|
|
||
| ## Installation | ||
|
|
||
| `pl-appname` is a _[ChRIS](https://chrisproject.org/) plugin_, meaning it can | ||
| `pl-lgd-hemis` is a _[ChRIS](https://chrisproject.org/) plugin_, meaning it can | ||
| run from either within _ChRIS_ or the command-line. | ||
|
|
||
| [](https://chrisstore.co/plugin/pl-appname) | ||
| [](https://chrisstore.co/plugin/pl-lgd-hemis) | ||
|
|
||
| ## Local Usage | ||
|
|
||
| To get started with local command-line usage, use [Apptainer](https://apptainer.org/) | ||
| (a.k.a. Singularity) to run `pl-appname` as a container: | ||
| (a.k.a. Singularity) to run `pl-lgd-hemis` as a container: | ||
|
|
||
| ```shell | ||
| apptainer exec docker://fnndsc/pl-appname commandname [--args values...] input/ output/ | ||
| apptainer exec docker://fnndsc/pl-lgd-hemis lgd_hemis input/ output/ | ||
| ``` | ||
|
|
||
| To print its available options, run: | ||
|
|
||
| ```shell | ||
| apptainer exec docker://fnndsc/pl-appname commandname --help | ||
| apptainer exec docker://fnndsc/pl-lgd-hemis lgd_hemis --help | ||
| ``` | ||
|
|
||
| ## Examples | ||
| `commandname` requires two positional arguments: a directory containing | ||
| `lgd_hemis` requires two positional arguments: a directory containing | ||
| input data, and a directory where to create output data. | ||
| First, create the input directory and move input data into it. | ||
| ```shell | ||
| mkdir incoming/ outgoing/ | ||
| mv some.dat other.dat incoming/ | ||
| apptainer exec docker://fnndsc/pl-appname:latest commandname [--args] incoming/ outgoing/ | ||
| ``` | ||
| ## Development | ||
| Instructions for developers. | ||
| ### Building | ||
| Build a local container image: | ||
| ```shell | ||
| docker build -t localhost/fnndsc/pl-appname . | ||
| ``` | ||
| ### Running | ||
| Mount the source code `app.py` into a container to try out changes without rebuild. | ||
| ```shell | ||
| docker run --rm -it --userns=host -u $(id -u):$(id -g) \ | ||
| -v $PWD/app.py:/usr/local/lib/python3.10/site-packages/app.py:ro \ | ||
| -v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \ | ||
| localhost/fnndsc/pl-appname commandname /incoming /outgoing | ||
| ``` | ||
| ### Testing | ||
| Run unit tests using `pytest`. | ||
| It's recommended to rebuild the image to ensure that sources are up-to-date. | ||
| Use the option `--build-arg extras_require=dev` to install extra dependencies for testing. | ||
| ```shell | ||
| docker build -t localhost/fnndsc/pl-appname:dev --build-arg extras_require=dev . | ||
| docker run --rm -it localhost/fnndsc/pl-appname:dev pytest | ||
| ``` | ||
| ## Release | ||
| Steps for release can be automated by [Github Actions](.github/workflows/ci.yml). | ||
| This section is about how to do those steps manually. | ||
| ### Increase Version Number | ||
| Increase the version number in `setup.py` and commit this file. | ||
| ### Push Container Image | ||
| Build and push an image tagged by the version. For example, for version `1.2.3`: | ||
| ``` | ||
| docker build -t docker.io/fnndsc/pl-appname:1.2.3 . | ||
| docker push docker.io/fnndsc/pl-appname:1.2.3 | ||
| ``` | ||
| ### Get JSON Representation | ||
| Run [`chris_plugin_info`](https://github.com/FNNDSC/chris_plugin#usage) | ||
| to produce a JSON description of this plugin, which can be uploaded to a _ChRIS Store_. | ||
| ```shell | ||
| docker run --rm localhost/fnndsc/pl-appname:dev chris_plugin_info > chris_plugin_info.json | ||
| ``` | ||
|
|
||
| END README TEMPLATE --> | ||
| The input directory is expected to contain subject folders where each | ||
| folder contains exactly two MINC volumes: segmentation and T1/T2 image. | ||
| For each subject folder input, an output folder is created containing | ||
| `wm_left.mnc` and `wm_right.mnc`. |
Oops, something went wrong.