spleenseg 1.2.44

Abstract

Based off Project MONAI’s spleen segmentation notebook, this plugin implements both the training and inference phases of the notebook, using data supplied in the parent plugin (see Implementation).

For the most part, the python notebook code could have been mostly used verbatim in the plugin; however, in this example considerable and deeper refactoring was performed. Other than of course now being a complete stand alone implementation, this plugin allows for continuous (or continued) training, as well as saving examples of all training/validation/inference datasets as NIfTI volumes to allow for better understanding of the process.

For the training phase, the parent plugin provides input images (training and labeled) and the output is a model (pth or ONNX format). For the inference phase, the input is a model file, an image (or more) to analyze, and the output is a segmented volume file.

An additional remote inference phase is available. If the mode is specified as <modelID>@<URI> where modelID is the name of a model and URI denotes a pfms server’s base URL, the plugin will transmit input images to the remote endpoint where the pfms service will run the inference and return a segmented volume file.

Implementation

The original notebook is a largely self-contained monolithic application. Exemplar input data is pulled from the web, and the notebook proceeds from there. In the case of this ChRIS plugin, some straightforward organizational changes are necessary. The training data is assumed to already have been downloaded a priori and is provided to this plugin by its parent. Outputs of the training are model weight filesTh.

Installation

pl-monai_spleenseg is a ChRIS plugin, meaning it can run from either within ChRIS or the command-line.

pip install -U ./
spleenseg --help

apptainer exec docker://fnndsc/pl-monai_spleenseg spleenseg_train \
            [--args values...] input/ output/

apptainer exec docker://fnndsc/pl-monai_spleenseg spleenseg_train --help

Usage

ARGS
    [--mode <inference|training>]
    The mode of operation. If the actual text "training" text has any additional characters,
    then the epoch training is skipped and only the post-training logic is executed --
    this allows the system to operate as if in training mode, but only perform the post
    training steps. For example, "--mode trainingPost" would invoke this mode.

    If the mode is specified as <model>@<remote> (e.g. splsegv1@http://pfms.org/api/v1/)
    then the pfms server at (in this example) http://pfms.org with base route /api/v1/
    is used to perform remote inference. Here, the model called "splsegv1" on the remote
    pfms server will be used to run inference. The return from this call is a NIfTI
    segmented volume saved in the <outputDir>.

    [--man]
    If specified, print this help page and quit.

    [--version]
    If specified, print the version and quit.

    [--logTransformVols]
    If specified, log a set of intermediary NIfTI volumes as used for training,
    validation, spacing, and inference.

    [--useModel <modelFile>]
    If specified, use <modelFile> for inference or continued training.

    [--trainImageDir <train> --trainLabelsDir <label>]
    In the <inputDir>, the name of the directory containing files for training
    with their corresponding label targets.

    [--testImageDir]
    In the <inputDir> the name of the directory containing images for inference.

    [--device <device>]
    The device to use, typically "cpu" or "cuda:0".

    [--determinismSeed <seed>]
    Set the training seed.

    [--maxEpochs <count>]
    The max number of training epochs.

    [--validateSize <size>]
    In the training space, the number of images that should be used for validation
    and not training.

Examples

spleenseg_train requires two positional arguments: a directory containing input data, and a directory containing output data (graphs and “model” files). In this plugin, data is downloaded from medicaldecathelon. To get this data, first set an environment variable pointing at the directory to contain the pulled and unpacked data:

export MONAI_DATA_DIR=/some/dir

now, you can pull the data with this python snippet:

# You probably will need to
#   pip install -q "monai-weekly[gdown, nibabel, tqdm, ignite]"
from monai.apps import download_and_extract

directory = os.environ.get("MONAI_DATA_DIRECTORY")
root_dir = tempfile.mkdtemp() if directory is None else directory
print(root_dir)


resource = "https://msd-for-monai.s3-us-west-2.amazonaws.com/Task09_Spleen.tar"
md5 = "410d4a301da4e5b2f6f86ec3ddba524e"
compressed_file = os.path.join(root_dir, "Task09_Spleen.tar")
data_dir = os.path.join(root_dir, "Task09_Spleen")
if not os.path.exists(data_dir):
    download_and_extract(resource, compressed_file, root_dir, md5)

Or simply run the supplied trainingDataPull.py script (which is essentially the above code):

python trainingDataPull.py

Create some output directory, and using our $MONAI_DATA_DIR, we can run the plugin:

mkdir outgoing/
apptainer exec docker://fnndsc/pl-monai_spleenseg:latest spleenseg \
        [--args] $MONAI_DATA_DIR outgoing/

Development

Instructions for developers.

docker build -t localhost/fnndsc/pl-monai_spleenseg .

docker run --rm -it --userns=host -u $(id -u):$(id -g) \
    -v $PWD/spleenseg/spleenseg.py:/usr/local/lib/python3.12/site-packages/spleenseg/spleenseg.py:ro \
    -v $PWD/in:/incoming:ro -v $PWD/out:/outgoing:rw -w /outgoing \
    localhost/fnndsc/pl-monai_spleenseg spleenseg /incoming /outgoing

docker build -t localhost/fnndsc/pl-monai_spleenseg:dev --build-arg extras_require=dev .
docker run --rm -it localhost/fnndsc/pl-monai_spleenseg:dev pytest

Release

Steps for release can be automated by Github Actions. This section is about how to do those steps manually.

docker build -t docker.io/fnndsc/pl-monai_spleenseg:1.2.3 .
docker push docker.io/fnndsc/pl-monai_spleenseg:1.2.3

docker run --rm docker.io/fnndsc/pl-monai_spleenseg:1.2.3 chris_plugin_info \
            -d docker.io/fnndsc/pl-monai_spleenseg:1.2.3 > chris_plugin_info.json