MSD Spleen Segmentation on Portal-Venous CT

# MSD Spleen: spleen segmentation on portal-venous phase CT (Medical Segmentation Decathlon)
#
# THE SAMPLE DATA IS ILLUSTRATIVE AND THE VOLUMES ARE SYNTHETIC. The Medical
# Segmentation Decathlon (MSD) images are released under CC BY-SA 4.0, a
# share-alike licence, so none of them is bundled. Each of the ten volumes in
# media/ is a small abdominal phantom generated with numpy and nibabel (fixed
# random seeds 101 to 110), written as NIfTI in the same RAS
# orientation the MSD uses. They are not patient data and not MSD images. The
# anatomy is ellipsoids, so a mask painted here teaches nothing about real
# spleens. See media/LICENSE-media.txt.
#
# Paper: Antonelli, M., Reinke, A., Bakas, S., et al. (2022). The Medical
#   Segmentation Decathlon. Nature Communications 13. (59 authors)
#   @article{Antonelli_2022,
#     title = {The Medical Segmentation Decathlon},
#     volume = {13}, ISSN = {2041-1723},
#     url = {http://dx.doi.org/10.1038/s41467-022-30695-9},
#     DOI = {10.1038/s41467-022-30695-9}, number = {1},
#     journal = {Nature Communications},
#     publisher = {Springer Science and Business Media LLC},
#     author = {Antonelli, Michela and Reinke, Annika and Bakas, Spyridon and others},
#     year = {2022}, month = jul }
#   (Author list shortened here; the full Crossref BibTeX is in metadata.json.)
# DOI: 10.1038/s41467-022-30695-9
# Dataset: http://medicaldecathlon.com/ (also https://registry.opendata.aws/msd/)
# Licence of the MSD data: CC BY-SA 4.0. The paper's Methods say all data sets
#   "have been released with a permissive copyright-license (CC-BY-SA 4.0),
#   thus allowing for data sharing, redistribution, and commercial usage".
#
# Spleen task definition, quoted from the paper's "Challenge data sets" section:
#   "Spleen: The data set consists of 61 portal-venous phase CT scans from
#   patients undergoing chemotherapy treatment for liver metastases. The
#   corresponding target ROI was the spleen. This data set was selected due to
#   the large variations in the field-of-view. The data was acquired in the
#   Memorial Sloan Kettering Cancer Center, New York, US."
# Annotation description, same section: "For each segmentation task, a
#   pixel-level label annotation was provided depending on the definition of
#   each specific task." The paper's Discussion lists as a limitation
#   "limiting the annotations to a single human rater", and the Methods note that
#   "inter-rater reliability estimates are not available for the MSD tasks due to
#   the complexity of double-labeling the data". The paper points to its
#   reference 35 for how each data set was annotated; that document was not read
#   for this design, so no per-annotator procedure for the spleen is claimed.
#
# Label glossary: Spleen, the only target region of the task.
#
# Adaptations:
#   - Synthetic phantoms replace the MSD cases (licence above).
#   - One brush label, Spleen, as in the task. Potato stores the mask per axial
#     slice and exports it as a NIfTI label volume.
#   - A radio scheme, spleen_in_view, is added. The paper says the task was chosen
#     for its large variation in field of view; the question records whether the
#     whole organ is inside the scan. It is not part of the MSD protocol.
#   - Window presets are common CT soft tissue settings chosen for this design
#     (center 40 and width 400, and a narrower width 250). The paper gives none.
#
# Install and run (volumes need the volumes extra):
#   pip install "potato-annotation[volumes]"
#   potato start config.yaml -p 8000
#
# Training (what it does and does not do): open /admin/training with the admin
# key below, pick volume-unet (pip install "potato-annotation[train-vision,volumes]")
# and the spleen_mask scheme, and click Train now. The trainer fits a plain-torch
# 3D U-Net on the painted masks, one volume per example, and paints masks on the
# volumes nobody has labeled. Those masks arrive as editable prelabels. It needs
# at least min_instances (3 by default) annotated volumes and a GPU in practice.
# It does not serve or deploy the model, and a model trained on these phantoms
# says nothing about real CT.

port: 8000
annotation_task_name: "MSD Spleen CT segmentation (synthetic volumes)"
task_dir: "."

data_files:
  - sample-data.json

item_properties:
  id_key: id
  text_key: text

media_directory: media

output_annotation_dir: "annotation_output/"
export_annotation_format: jsonl

require_password: false
admin_api_key: "demo-admin-key"

user_config:
  allow_all_users: true
  users: []

annotation_instructions: |
  Scroll through the axial, coronal, and sagittal views and paint the spleen on
  every slice where it appears, using the Spleen brush. Use Interpolate to fill
  the slices between two painted slices, then check the result in the other two
  views. Then say whether the whole spleen is inside the scan.
  These volumes are synthetic phantoms, so the practice is the tooling and not
  the anatomy.

annotation_schemes:
  - annotation_type: volume_annotation
    name: spleen_mask
    description: "Paint the spleen on every slice where it appears."
    source_field: volume
    labels:
      - name: Spleen
        color: "#e6553a"
        key_value: "1"
    tools: [navigate, brush, eraser, polygon]
    default_window: Soft tissue
    # The NIfTI files carry no modality header, so the presets are set here.
    window_presets:
      - {name: Soft tissue, center: 40, width: 400}
      - {name: Narrow soft tissue, center: 40, width: 250}

  - annotation_type: radio
    name: spleen_in_view
    description: "Is the whole spleen inside the scan?"
    labels:
      - "yes"
      - "no, it is cut off"

model_training:
  enabled: true
  writeback:
    schemas: ["spleen_mask"]
    include_unlabeled: true
    min_confidence: 0.5
  # Keys verified in potato/training/trainers/volume_unet.py. Small patches fit
  # the small phantoms.
  trainer_params:
    volume-unet:
      patch: 32
      epochs: 30
      patches_per_epoch: 60