PANDA Gleason Pattern Regions and Grade Group on Biopsies

# PANDA - Prostate cANcer graDe Assessment: Gleason pattern regions and ISUP grade group
#
# Paper: Bulten, W., Kartasalo, K., Chen, P.-H. C., Strom, P., Pinckaers, H., et al.
#   and the PANDA challenge consortium (2022). Artificial intelligence for diagnosis
#   and Gleason grading of prostate cancer: the PANDA challenge. Nature Medicine, 28(1), 154-163.
#   @article{Bulten_2022,
#     title={Artificial intelligence for diagnosis and Gleason grading of prostate cancer: the PANDA challenge},
#     volume={28}, ISSN={1546-170X}, url={http://dx.doi.org/10.1038/s41591-021-01620-2},
#     DOI={10.1038/s41591-021-01620-2}, number={1}, journal={Nature Medicine},
#     publisher={Springer Science and Business Media LLC},
#     author={Bulten, Wouter and Kartasalo, Kimmo and Chen, Po-Hsuan Cameron and others},
#     year={2022}, month=Jan, pages={154--163} }
#   (the author list is shortened here; the full list is in metadata.json)
# DOI: 10.1038/s41591-021-01620-2
# Dataset: https://www.kaggle.com/c/prostate-cancer-grade-assessment/data
#   (also linked from https://panda.grand-challenge.org/data/). Licence: Creative Commons
#   BY-SA-NC 4.0, per the paper's data availability statement. No PANDA image is bundled.
#
# The development set holds 10,616 digitized hematoxylin and eosin stained prostate
# biopsies from 2,113 patients, from Radboud University Medical Center and Karolinska
# Institutet. Each biopsy has an ISUP grade group, the five groups that pathologists
# derive from the distribution of Gleason growth patterns. The paper notes that "Many of
# the solutions demonstrated the feasibility of end-to-end training using case-level
# information only" ("Such weakly supervised approaches do not require detailed
# pixel-level annotations").
#
# Label glossary:
#   ISUP grade group: five groups, 1 to 5, plus non-tumor biopsies (the paper's Table 1
#   lists "Nontumor" and "GG 1" through "GG 5").
#   Region labels: benign, Gleason pattern 3, 4 and 5. These four classes come from
#   the earlier Radboud study (Bulten et al. 2020, Lancet Oncology, DOI
#   10.1016/S1470-2045(19)30739-9, arXiv 1907.07980): "each gland was assigned to a
#   single class: benign, Gleason 3, Gleason 4, Gleason 5, or hard-negative". Those
#   region labels were made semi-automatically, "removing the need for manual annotations
#   by pathologists". The pixel-level mask encoding of the PANDA release itself is not
#   documented in a source this design could read, so it is not reproduced.
#
# THE SAMPLE DATA IS ILLUSTRATIVE. PANDA images cannot be redistributed, so the ten items
# all point at CMU-1-Small-Region.svs, a CC0 Aperio slide region from the OpenSlide test
# data. It is not a PANDA slide, it is not stated to be prostate tissue, and it is a
# single-level 2220 x 2967 pixel file, far smaller than a real gigapixel biopsy scan.
# See media/LICENSE-media.txt.
#
# Adaptations:
#   - PANDA's training labels are one grade group per slide plus semi-automatic region
#     masks. Here annotators draw polygons by hand, a manual workflow the PANDA release
#     does not describe.
#   - The slide-level grade group is a radio scheme with six options (non-tumor, 1 to 5).
#   - The pattern labels are benign and Gleason patterns 3, 4 and 5 only. The 2020
#     study also used a hard-negative class, which is left out here.
#   - A grade group is derived by pathologists from the pattern distribution. Here it is
#     a separate answer, and nothing checks the two against each other.
#
# Install and run (openslide is needed to read .svs files):
#   pip install "potato-annotation[wsi]"
#   potato start config.yaml -p 8000
#
# Training (what it does and does not do): open /admin/training with the admin key below,
# pick torchvision-segment (pip install "potato-annotation[train-vision]") and the
# gleason_regions scheme, and click Train now. The trainer fine-tunes a torchvision
# Mask R-CNN on the annotators' outlines and labels, cutting the slide into tiles
# (model_training.tiling) so a whole slide is never resized to a thumbnail. Predictions
# come back as editable polygon prelabels in whole-slide coordinates. It does not serve
# or deploy the model, it does not learn the grade group, and it makes no diagnosis.
# A diagnostic claim needs a clinical study, not this demo.

port: 8000
annotation_task_name: "PANDA prostate biopsy Gleason patterns"
task_dir: "."

data_files:
  - sample-data.json

item_properties:
  id_key: id
  text_key: note

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: |
  Open the biopsy and zoom in. Outline each region with the polygon tool and give it
  one label, benign or Gleason pattern 3, 4 or 5. Then choose the ISUP grade group for
  the whole biopsy, or non-tumor.
  The slide here is a CC0 sample that is not from PANDA, so regions are for practice.

annotation_schemes:
  - annotation_type: image_annotation
    name: gleason_regions
    description: "Outline each region on the biopsy and assign benign or a Gleason pattern."
    source_field: image
    # Required for slides: the default viewer sends the image as one file.
    viewer: deepzoom
    tiles:
      tile_size: 254
      overlap: 1
      navigator: true
    tools: [polygon]
    labels:
      - name: Benign
        color: "#2e9e5b"
      - name: Gleason pattern 3
        color: "#e3c341"
      - name: Gleason pattern 4
        color: "#e0602f"
      - name: Gleason pattern 5
        color: "#6a2c91"

  - annotation_type: radio
    name: isup_grade_group
    description: "ISUP grade group of the whole biopsy, or non-tumor."
    labels:
      - Non-tumor
      - ISUP grade group 1
      - ISUP grade group 2
      - ISUP grade group 3
      - ISUP grade group 4
      - ISUP grade group 5

model_training:
  enabled: true
  writeback:
    schemas: ["gleason_regions"]
    include_unlabeled: true
    min_confidence: 0.5
  # Keys verified in potato/training/tiling.py. Regions are drawn on part of each slide,
  # so no empty background tiles are sampled.
  tiling:
    enabled: auto
    tile_size: 1024
    overlap: 128
    downsample: 1
    background: 0