Skip to content

Commit

Permalink
Initial commit
Browse files Browse the repository at this point in the history
  • Loading branch information
AdaGondova authored and AdaGondova committed Aug 2, 2024
1 parent 5b90d0a commit a20f52c
Show file tree
Hide file tree
Showing 6 changed files with 111 additions and 103 deletions.
4 changes: 1 addition & 3 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@ on:
jobs:
test:
name: Unit tests
if: false # delete this line to enable automatic testing
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v4
Expand All @@ -41,8 +40,7 @@ jobs:
build:
name: Build
if: false # delete this line and uncomment the line below to enable automatic builds
# if: github.event_name == 'push' || github.event_name == 'release'
if: github.event_name == 'push' || github.event_name == 'release'
# needs: [ test ] # uncomment to require passing tests
runs-on: ubuntu-22.04

Expand Down
10 changes: 5 additions & 5 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
# FROM ghcr.io/mamba-org/micromamba:1.5.1-focal-cuda-11.3.1
FROM docker.io/python:3.12.1-slim-bookworm

LABEL org.opencontainers.image.authors="FNNDSC <[email protected]>" \
org.opencontainers.image.title="ChRIS Plugin Title" \
org.opencontainers.image.description="A ChRIS plugin that..."
LABEL org.opencontainers.image.authors="FNNDSC <[email protected]>" \
org.opencontainers.image.title="FETA ChRIS Plugin" \
org.opencontainers.image.description="code for feta"

ARG SRCDIR=/usr/local/src/app
ARG SRCDIR=/usr/local/src/FeTA_challenge_2024
WORKDIR ${SRCDIR}

COPY requirements.txt .
Expand All @@ -19,4 +19,4 @@ RUN pip install ".[${extras_require}]" \
&& cd / && rm -rf ${SRCDIR}
WORKDIR /

CMD ["commandname"]
CMD ["inference"]
107 changes: 20 additions & 87 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,76 +1,10 @@
# _ChRIS_ Plugin Template
# FETA ChRIS Plugin

[![test status](https://github.com/FNNDSC/python-chrisapp-template/actions/workflows/src.yml/badge.svg)](https://github.com/FNNDSC/python-chrisapp-template/actions/workflows/src.yml)
[![MIT License](https://img.shields.io/github/license/FNNDSC/python-chrisapp-template)](LICENSE)
[![Version](https://img.shields.io/docker/v/fnndsc/FeTA_challenge_2024?sort=semver)](https://hub.docker.com/r/fnndsc/FeTA_challenge_2024)
[![MIT License](https://img.shields.io/github/license/fnndsc/FeTA_challenge_2024)](https://github.com/FNNDSC/FeTA_challenge_2024/blob/main/LICENSE)
[![ci](https://github.com/FNNDSC/FeTA_challenge_2024/actions/workflows/ci.yml/badge.svg)](https://github.com/FNNDSC/FeTA_challenge_2024/actions/workflows/ci.yml)

This is a minimal template repository for _ChRIS_ plugin applications in Python.

## About _ChRIS_ Plugins

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/`.

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
[![Version](https://img.shields.io/docker/v/fnndsc/pl-appname?sort=semver)](https://hub.docker.com/r/fnndsc/pl-appname)
[![MIT License](https://img.shields.io/github/license/fnndsc/pl-appname)](https://github.com/FNNDSC/pl-appname/blob/main/LICENSE)
[![ci](https://github.com/FNNDSC/pl-appname/actions/workflows/ci.yml/badge.svg)](https://github.com/FNNDSC/pl-appname/actions/workflows/ci.yml)
`pl-appname` is a [_ChRIS_](https://chrisproject.org/)
`FeTA_challenge_2024` is a [_ChRIS_](https://chrisproject.org/)
_ds_ plugin which takes in ... as input files and
creates ... as output files.

Expand All @@ -80,34 +14,34 @@ creates ... as output files.

## Installation

`pl-appname` is a _[ChRIS](https://chrisproject.org/) plugin_, meaning it can
`FeTA_challenge_2024` is a _[ChRIS](https://chrisproject.org/) plugin_, meaning it can
run from either within _ChRIS_ or the command-line.

## 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 `FeTA_challenge_2024` as a container:

```shell
apptainer exec docker://fnndsc/pl-appname commandname [--args values...] input/ output/
apptainer exec docker://fnndsc/FeTA_challenge_2024 inference [--args values...] input/ output/
```

To print its available options, run:

```shell
apptainer exec docker://fnndsc/pl-appname commandname --help
apptainer exec docker://fnndsc/FeTA_challenge_2024 inference --help
```

## Examples

`commandname` requires two positional arguments: a directory containing
`inference` 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/
apptainer exec docker://fnndsc/FeTA_challenge_2024:latest inference [--args] incoming/ outgoing/
```

## Development
Expand All @@ -119,18 +53,18 @@ Instructions for developers.
Build a local container image:

```shell
docker build -t localhost/fnndsc/pl-appname .
docker build -t localhost/fnndsc/FeTA_challenge_2024 .
```

### Running

Mount the source code `app.py` into a container to try out changes without rebuild.
Mount the source code `inference.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.12/site-packages/app.py:ro \
-v $PWD/inference.py:/usr/local/lib/python3.12/site-packages/inference.py:ro \
-v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
localhost/fnndsc/pl-appname commandname /incoming /outgoing
localhost/fnndsc/FeTA_challenge_2024 inference /incoming /outgoing
```

### Testing
Expand All @@ -140,8 +74,8 @@ 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
docker build -t localhost/fnndsc/FeTA_challenge_2024:dev --build-arg extras_require=dev .
docker run --rm -it localhost/fnndsc/FeTA_challenge_2024:dev pytest
```

## Release
Expand All @@ -158,8 +92,8 @@ Increase the version number in `setup.py` and commit this file.
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
docker build -t docker.io/fnndsc/FeTA_challenge_2024:1.2.3 .
docker push docker.io/fnndsc/FeTA_challenge_2024:1.2.3
```

### Get JSON Representation
Expand All @@ -168,10 +102,9 @@ Run [`chris_plugin_info`](https://github.com/FNNDSC/chris_plugin#usage)
to produce a JSON description of this plugin, which can be uploaded to _ChRIS_.

```shell
docker run --rm docker.io/fnndsc/pl-appname:1.2.3 chris_plugin_info -d docker.io/fnndsc/pl-appname:1.2.3 > chris_plugin_info.json
docker run --rm docker.io/fnndsc/FeTA_challenge_2024:1.2.3 chris_plugin_info -d docker.io/fnndsc/FeTA_challenge_2024:1.2.3 > chris_plugin_info.json
```

Intructions on how to upload the plugin to _ChRIS_ can be found here:
https://chrisproject.org/docs/tutorials/upload_plugin

END README TEMPLATE -->
77 changes: 77 additions & 0 deletions inference.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
#!/usr/bin/env python

from pathlib import Path
from argparse import ArgumentParser, Namespace, ArgumentDefaultsHelpFormatter

from chris_plugin import chris_plugin, PathMapper

__version__ = '1.0.0'

DISPLAY_TITLE = r"""
______ _____ ___ _ _ _ _____ _____ _____ ___
| ___|_ _/ _ \ | | | | | / __ \| _ |/ __ \ / |
| |_ ___| |/ /_\ \ ___| |__ __ _| | | ___ _ __ __ _ ___ `' / /'| |/' |`' / /'/ /| |
| _/ _ \ || _ | / __| '_ \ / _` | | |/ _ \ '_ \ / _` |/ _ \ / / | /| | / / / /_| |
| || __/ || | | || (__| | | | (_| | | | __/ | | | (_| | __/ ./ /___\ |_/ /./ /__\___ |
\_| \___\_/\_| |_/ \___|_| |_|\__,_|_|_|\___|_| |_|\__, |\___| \_____/ \___/ \_____/ |_/
______ __/ | ______
|______| |___/ |______|
"""


parser = ArgumentParser(description='!!!CHANGE ME!!! An example ChRIS plugin which '
'counts the number of occurrences of a given '
'word in text files.',
formatter_class=ArgumentDefaultsHelpFormatter)
parser.add_argument('-w', '--word', required=True, type=str,
help='word to count')
parser.add_argument('-p', '--pattern', default='**/*.txt', type=str,
help='input file filter glob')
parser.add_argument('-V', '--version', action='version',
version=f'%(prog)s {__version__}')


# The main function of this *ChRIS* plugin is denoted by this ``@chris_plugin`` "decorator."
# Some metadata about the plugin is specified here. There is more metadata specified in setup.py.
#
# documentation: https://fnndsc.github.io/chris_plugin/chris_plugin.html#chris_plugin
@chris_plugin(
parser=parser,
title='FETA ChRIS Plugin',
category='', # ref. https://chrisstore.co/plugins
min_memory_limit='100Mi', # supported units: Mi, Gi
min_cpu_limit='1000m', # millicores, e.g. "1000m" = 1 CPU core
min_gpu_limit=0 # set min_gpu_limit=1 to enable GPU
)
def main(options: Namespace, inputdir: Path, outputdir: Path):
"""
*ChRIS* plugins usually have two positional arguments: an **input directory** containing
input files and an **output directory** where to write output files. Command-line arguments
are passed to this main method implicitly when ``main()`` is called below without parameters.
:param options: non-positional arguments parsed by the parser given to @chris_plugin
:param inputdir: directory containing (read-only) input files
:param outputdir: directory where to write output files
"""

print(DISPLAY_TITLE)

# Typically it's easier to think of programs as operating on individual files
# rather than directories. The helper functions provided by a ``PathMapper``
# object make it easy to discover input files and write to output files inside
# the given paths.
#
# Refer to the documentation for more options, examples, and advanced uses e.g.
# adding a progress bar and parallelism.
mapper = PathMapper.file_mapper(inputdir, outputdir, glob=options.pattern, suffix='.count.txt')
for input_file, output_file in mapper:
# The code block below is a small and easy example of how to use a ``PathMapper``.
# It is recommended that you put your functionality in a helper function, so that
# it is more legible and can be unit tested.
data = input_file.read_text()
frequency = data.count(options.word)
output_file.write_text(str(frequency))


if __name__ == '__main__':
main()
14 changes: 7 additions & 7 deletions setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -19,18 +19,18 @@ def get_version(rel_path: str) -> str:


setup(
name='chris-plugin-template',
version=get_version('app.py'),
description='A ChRIS DS plugin template',
name='FeTA_challenge_2024',
version=get_version('inference.py'),
description='code for feta',
author='FNNDSC',
author_email='[email protected]',
url='https://github.com/FNNDSC/python-chrisapp-template',
py_modules=['app'],
author_email='[email protected]',
url='https://github.com/FNNDSC/FeTA_challenge_2024',
py_modules=['inference'],
install_requires=['chris_plugin'],
license='MIT',
entry_points={
'console_scripts': [
'commandname = app:main'
'inference = inference:main'
]
},
classifiers=[
Expand Down
2 changes: 1 addition & 1 deletion tests/test_example.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
from pathlib import Path

from app import parser, main
from inference import parser, main


def test_main(tmp_path: Path):
Expand Down

0 comments on commit a20f52c

Please sign in to comment.