BRACS Breast Lesion Regions on a Gigapixel Whole-Slide Image

# BRACS - BReAst Carcinoma Subtyping: lesion regions on a whole-slide image
#
# Paper: Brancati, N., Anniciello, A. M., Pati, P., Riccio, D., Scognamiglio, G.,
#   Jaume, G., De Pietro, G., Di Bonito, M., Foncubierta, A., Botti, G.,
#   Gabrani, M., Feroce, F., and Frucci, M. (2022). BRACS: A Dataset for BReAst
#   Carcinoma Subtyping in H&E Histology Images. Database, 2022.
#   @article{Brancati_2022,
#     title={BRACS: A Dataset for BReAst Carcinoma Subtyping in H&E Histology Images},
#     volume={2022}, journal={Database}, publisher={Oxford University Press (OUP)},
#     author={Brancati, Nadia and Anniciello, Anna Maria and Pati, Pushpak and Riccio, Daniel and Scognamiglio, Giosue and Jaume, Guillaume and De Pietro, Giuseppe and Di Bonito, Maurizio and Foncubierta, Antonio and Botti, Gerardo and Gabrani, Maria and Feroce, Florinda and Frucci, Maria},
#     year={2022}, DOI={10.1093/database/baac093} }
# DOI: 10.1093/database/baac093
# Dataset: https://www.bracs.icar.cnr.it/ (registration required to download;
#   Creative Commons Attribution-NonCommercial 4.0, per the dataset's Background
#   page. The paper's data-access section instead calls the terms of use a CC0
#   license; the sources disagree, and this design follows the website.)
#
# The dataset holds 547 whole-slide images (WSIs) from 189 patients and 4539
# regions of interest (ROIs) extracted from 387 WSIs collected on 151 patients,
# scanned at 40x (0.25 um/pixel). Three pathologists
# annotated both levels. Per the paper, each pathologist labeled a WSI with the
# most aggressive subtype found, the three then checked every label together, and
# a label without consensus was discarded. Each pathologist then extracted ROIs
# in QuPath, and "each extracted ROI corresponds to a unique category".
#
# Label glossary (the seven categories, from the paper's introduction):
#   Normal (N), Pathological Benign (PB), Usual Ductal Hyperplasia (UDH),
#   Flat Epithelial Atypia (FEA), Atypical Ductal Hyperplasia (ADH),
#   Ductal Carcinoma in Situ (DCIS), Invasive Carcinoma (IC).
# The paper groups them as benign (N, PB, UDH), atypical (FEA, ADH), and
# malignant (DCIS, IC).
#
# THE SAMPLE DATA IS ILLUSTRATIVE. BRACS 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 from BRACS, its tissue type is not stated in
# the listing, and it is a single-level 2220 x 2967 pixel file, far smaller than a
# real gigapixel slide. The deepzoom viewer, the tile pyramid and the training
# loop are the same ones a 100,000-pixel scan uses.
# See media/LICENSE-media.txt.
#
# Adaptations:
#   - One image per item, drawn on with polygons and boxes. BRACS ROIs are
#     exported as PNG crops with a label in the filename; here an ROI is a
#     labeled shape on the slide, as the pathologists marked them in QuPath.
#   - A slide-level label (the most aggressive subtype) is a separate radio scheme.
#   - Three annotators per item stand in for the three pathologists. Potato keeps
#     each annotator's answer; the consensus discussion in the paper is not modeled.
#   - Labels use the paper's full names; abbreviations appear only in comments.
#
# 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 lesion_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.
# Its predictions come back as editable polygon prelabels in whole-slide
# coordinates. It does not serve or deploy the model and it makes no diagnosis.
# A diagnostic claim needs a clinical study, not this demo.

port: 8000
annotation_task_name: "BRACS breast lesion regions on a whole slide"
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: []

# Three pathologists read every case in the BRACS protocol.
num_annotators_per_item: 3

annotation_instructions: |
  Open the slide and zoom in. Outline each lesion region with the polygon tool,
  or box it, and give it one of the seven BRACS categories. Each region gets a
  single category. Then choose the slide-level label, which is the most
  aggressive subtype you found anywhere on the slide.
  The slide here is a CC0 sample that is not from BRACS, so regions are for practice.

annotation_schemes:
  - annotation_type: image_annotation
    name: lesion_regions
    description: "Outline or box each lesion region on the slide and assign one BRACS category."
    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, bbox]
    labels:
      - name: Normal
        color: "#2e9e5b"
      - name: Pathological Benign
        color: "#6cc4a1"
      - name: Usual Ductal Hyperplasia
        color: "#e3c341"
      - name: Flat Epithelial Atypia
        color: "#f19a3e"
      - name: Atypical Ductal Hyperplasia
        color: "#e0602f"
      - name: Ductal Carcinoma in Situ
        color: "#b8307a"
      - name: Invasive Carcinoma
        color: "#6a2c91"

  - annotation_type: radio
    name: slide_label
    description: "Slide-level label: the most aggressive subtype present on the slide."
    labels:
      - Normal
      - Pathological Benign
      - Usual Ductal Hyperplasia
      - Flat Epithelial Atypia
      - Atypical Ductal Hyperplasia
      - Ductal Carcinoma in Situ
      - Invasive Carcinoma

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