segmentation_template

Template Segmentation Bundle

This bundle is meant to be an example of segmentation in 3D which you can copy and modify to create your own bundle. It is only roughly trained for the synthetic data you can generate with this notebook so doesn't do anything useful on its own. The purpose is to demonstrate the base line for segmentation network bundles compatible with MONAILabel amongst other things.

To use this bundle, copy the contents of the whole directory and change the definitions for network, data, transforms, or whatever else you want for your own new segmentation bundle. Some of the names are critical for MONAILable but otherwise you're free to change just about whatever else is defined here to suit your network.

This bundle should also demonstrate good practice and design, however there is one caveat about definitions being copied between config files. Ideally there should be a common.yaml file for all the definitions used by every other config file which is then included with that file. MONAILabel doesn't support this yet so this bundle will be updated once it does to exemplify this better practice.

Generating Demo Data

Run all the cells of this notebook to generate training and test data. These will be 3D nifti files containing volumes with randomly generated spheres of varying intensities and some noise for fun. The segmentation task is very easy so your network will train in minutes with the default configuration of values. A test data directory will separately be created since the test and inference configs are configured to apply the network to every nifti file in a given directory with a certain pattern.

Training

To train a new network the train.yaml script can be used alone with no other arguments (assume BUNDLE is the root directory of the bundle):

python -m monai.bundle run \
    --meta_file "$BUNDLE/configs/metadata.json" \
    --config_file "$BUNDLE/configs/train.yaml" \
    --bundle_root "$BUNDLE"

A train.sh script is also provided in docs which implements this invocation with some helper commands. It relies on a Conda environment called monai so comment or modify those lines if you're not using such an environment. See MONAI installation information about what environment to create for the features you want.

The training config includes a number of hyperparameters like learning_rate and num_workers. These control aspects of how training operates in terms of how many processes to use, when to perform validation, when to save checkpoints, and other things. Other aspects of the script can be modified on the command line so these aren't exhaustive but are a guide to the kind of parameterisation that make sense for a bundle.

Testing and Inference

Two configs are provided (test.yaml and inference.yaml) for doing post-training inference with the model. The first requires image and segmentation pairs which are used with network outputs to assess performance using metrics. This is very similar to training validation but is done on separate images. This config can be set to save predicted segmentations by setting save_pred to true but by default it will just run metrics and print their results.

The inference config is for generating new segmentations from images which don't have ground truths, so this is used for actually applying the network in practice. This will apply the network to every image in an input directory matching a pattern and save the predicted segmentations to an output directory.

Using inference on the command line is demonstrated in this notebook with visualisation. Some explanation of some command line choices are given in the notebook as well, similar command line invocations can also be done with the included inference.sh script file.

Other Considerations

There is no scripts directory containing a valid Python module to be imported in your configs. This wasn't necessary for this bundle but if you want to include custom code in a bundle please follow the bundle tutorials on how to do this.

The multi_gpu_train.yaml config is defined as a "mixin" to implement DDP based multi-gpu training. The script train_multigpu.sh illustrates an example of how to invoke these configs together with torchrun.

The inference.yaml config is compatible with MONAILabel such that you can load one of the synthetic images and perform inference through a label server. This doesn't permit active learning however, that is a later enhancement for this bundle. If you're changing definitions in the inference.yaml config file be careful about changing names and consult the MONAILabel documentation about required definition names. An example script to start a server is given in run_monailabel.sh which will download the bundle application and "install" this bundle using a symlink then start the server. Future updates to MONAILabel will improve this process.