LIDC-IDRI Lung Nodule Outlines and Ratings on Chest CT

# LIDC-IDRI: lung nodule outlines and nodule characteristic ratings on chest CT
#
# THE SAMPLE DATA IS ILLUSTRATIVE AND THE VOLUMES ARE SYNTHETIC. LIDC-IDRI is
# released under CC BY 3.0 but is distributed under the TCIA Data Usage Policy
# and Restrictions, so none of its images are bundled. Each of the ten volumes
# in media/ is a small chest phantom generated with numpy and nibabel, written
# as NIfTI in RAS orientation.
# They are not patient data and not LIDC-IDRI images. The anatomy is ellipsoids,
# so nothing painted here says anything about real nodules. See
# media/LICENSE-media.txt.
#
# Paper: Armato, S. G., McLennan, G., Bidaut, L., et al. (2011). The Lung Image
#   Database Consortium (LIDC) and Image Database Resource Initiative (IDRI): A
#   Completed Reference Database of Lung Nodules on CT Scans. Medical Physics
#   38(2), 915-931. (56 authors)
#   @article{Armato_2011,
#     title = {The Lung Image Database Consortium (LIDC) and Image Database Resource Initiative (IDRI): A Completed Reference Database of Lung Nodules on CT Scans},
#     volume = {38}, ISSN = {2473-4209},
#     url = {http://dx.doi.org/10.1118/1.3528204},
#     DOI = {10.1118/1.3528204}, number = {2},
#     journal = {Medical Physics}, publisher = {Wiley},
#     author = {Armato, Samuel G. and McLennan, Geoffrey and Bidaut, Luc and others},
#     year = {2011}, month = Jan, pages = {915--931} }
#   (Author list shortened here; the full Crossref BibTeX is in metadata.json.)
# DOI: 10.1118/1.3528204
# Dataset: https://www.cancerimagingarchive.net/collection/lidc-idri/
#   Data DOI 10.7937/K9/TCIA.2015.LO9QL9SX (Data From LIDC-IDRI, version 4).
# Licence: Creative Commons Attribution 3.0 Unported, plus the TCIA Data Usage
#   Policy and Restrictions.
#
# Protocol, as quoted from the sources below.
#   TCIA collection page: "In the initial blinded-read phase, each radiologist
#   independently reviewed each CT scan and marked lesions", and "In the
#   subsequent unblinded-read phase, each radiologist independently reviewed
#   their own marks" together with the anonymized marks of the other three
#   readers, without forcing consensus. Four thoracic radiologists read each scan.
#   Lesion categories (Armato et al. 2011): "nodule>=3 mm", "nodule<3 mm", and
#   "non-nodule>=3 mm".
#   LIDC Radiologist Instructions (LIDC_Reader_Instructions_pub.doc): a nodule
#   >=3 mm is outlined "in all sections in which it appears"; the range is
#   "3 mm < Nodule < 30 mm" and "A mass that exceeds 30 mm should be marked as a
#   'non-nodule > 3 mm'". A nodule <3 mm and a non-nodule >=3 mm each get a
#   centroid only ("approximate three-dimensional center-of-mass"). Only nodules
#   >3 mm identified after the unblinded read are rated, and malignancy is rated
#   "assuming a 60-year-old male smoker".
#   Rating wording below is quoted from the commented annotation XML file that
#   TCIA distributes with the collection (annotated_xml_file_Mar-2010.rtf). The
#   file defines every level of subtlety, internal structure, calcification and
#   malignancy, three levels of sphericity and texture (1, 3 and 5), and only
#   the extremes of margin, lobulation and spiculation. Levels the file does not
#   define appear here as bare numbers.
#
# Label glossary:
#   Nodule >=3 mm / Nodule <3 mm / Non-nodule >=3 mm: the three lesion categories.
#   Characteristics (1 to 5 unless noted): subtlety, internalStructure (1 to 4),
#   calcification (1 to 6), sphericity, margin, lobulation, spiculation, texture,
#   malignancy.
#
# Adaptations:
#   - Synthetic phantoms replace LIDC-IDRI cases (licence above).
#   - The two-phase read is NOT reproduced. Potato's volume_annotation shows one
#     annotator only their own marks, and the sample items carry no marks from
#     other readers, so there is no unblinded phase. This design is the blinded
#     phase. In a real study, the unblinded phase would be a second pass over
#     the same items with each reader's other-reader marks supplied as prefill.
#   - LIDC readers drew a contour per slice. Potato's volume_annotation stores a
#     painted voxel mask per label, so the outline is a filled mask. Centroids
#     for the two small categories are approximated by a small brush dab, since
#     the tool list has no point tool.
#   - Each volume carries one target nodule, so one set of nine ratings per
#     item stands in for the per-nodule ratings of the original.
#   - Ratings are shown for every item. The original asks for them only for
#     nodules >3 mm after the unblinded read.
#   - Window presets (lung and soft tissue) are common CT settings chosen for
#     this design. The sources give none.
#   - The characteristics paper text also mentions solidity; the distributed XML
#     calls the corresponding field texture, and this design follows the XML.
#
# Install and run (volumes need the volumes extra):
#   pip install "potato-annotation[volumes]"
#   potato start config.yaml -p 8000
#
# Agreement: with several annotators per volume, /admin/iaa reports agreement on
# the painted masks. Disagreement is kept and not resolved, as in LIDC.
#
# 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 nodule_marks 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 trains on the masks only and not on the ratings. 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: "LIDC-IDRI lung nodules (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. Outline the target
  nodule in every slice where it appears with the "Nodule >=3 mm" brush, as
  you would for a nodule between 3 mm and 30 mm. Mark a nodule under 3 mm or a
  non-nodule over 3 mm with a single small dab of its own label. Then rate the
  nodule on the nine characteristics. Rate malignancy as if the patient were a
  60-year-old male smoker. These volumes are synthetic phantoms, so the
  practice is the tooling and not the anatomy.

annotation_schemes:
  - annotation_type: volume_annotation
    name: nodule_marks
    description: "Outline each nodule 3 mm or larger in every slice where it appears. Mark the other two categories with a small dab."
    source_field: volume
    labels:
      - name: "Nodule >=3 mm"
        color: "#e6553a"
        key_value: "1"
      - name: "Nodule <3 mm"
        color: "#e6b83a"
        key_value: "2"
      - name: "Non-nodule >=3 mm"
        color: "#3a8ee6"
        key_value: "3"
    tools: [navigate, brush, eraser, polygon]
    default_window: Lung
    # The NIfTI files carry no modality header, so the presets are set here.
    window_presets:
      - {name: Lung, center: -600, width: 1500}
      - {name: Soft tissue, center: 40, width: 400}

  - annotation_type: radio
    name: subtlety
    description: "Subtlety of the nodule (1 = extremely subtle, 5 = obvious)"
    horizontal: true
    labels:
      - "1 extremely subtle"
      - "2"
      - "3"
      - "4"
      - "5 obvious"

  - annotation_type: radio
    name: internal_structure
    description: "Internal structure of the nodule"
    horizontal: true
    labels:
      - "1 soft tissue"
      - "2 fluid"
      - "3 fat"
      - "4 air"

  - annotation_type: radio
    name: calcification
    description: "Internal calcification of the nodule"
    horizontal: true
    labels:
      - "1 Popcorn Appearance"
      - "2 Laminated Appearance"
      - "3 Solid Appearance"
      - "4 Non-Central Appearance"
      - "5 Central Calcification"
      - "6 Absent"

  - annotation_type: radio
    name: sphericity
    description: "Shape of the nodule in terms of roundness or sphericity (1 = Linear, 3 = Ovoid, 5 = Round)"
    horizontal: true
    labels:
      - "1 Linear Appearance"
      - "2"
      - "3 Ovoid Appearance"
      - "4"
      - "5 Round Appearance"

  - annotation_type: radio
    name: margin
    description: "Margin of the nodule (1 = Poorly Defined, 5 = Sharp)"
    horizontal: true
    labels:
      - "1 Poorly Defined"
      - "2"
      - "3"
      - "4"
      - "5 Sharp Margin"

  - annotation_type: radio
    name: lobulation
    description: "Lobulation of the nodule (1 = No Lobulation, 5 = Marked Lobulation)"
    horizontal: true
    labels:
      - "1 No Lobulation"
      - "2"
      - "3"
      - "4"
      - "5 Marked Lobulation"

  - annotation_type: radio
    name: spiculation
    description: "Spiculation of the nodule (1 = No Spiculation, 5 = Marked Spiculation)"
    horizontal: true
    labels:
      - "1 No Spiculation"
      - "2"
      - "3"
      - "4"
      - "5 Marked Spiculation"

  - annotation_type: radio
    name: texture
    description: "Internal texture of the nodule (1 = Non-Solid/Ground Glass Opacity, 3 = Part Solid/Mixed, 5 = Solid Texture)"
    horizontal: true
    labels:
      - "1 Non-Solid/Ground Glass Opacity"
      - "2"
      - "3 Part Solid/Mixed"
      - "4"
      - "5 Solid Texture"

  - annotation_type: radio
    name: malignancy
    description: "Likelihood of malignancy of the nodule, assuming a 60-year-old male smoker"
    horizontal: true
    labels:
      - "1 Highly Unlikely for Cancer"
      - "2 Moderately Unlikely for Cancer"
      - "3 Indeterminate Likelihood"
      - "4 Moderately Suspicious for Cancer"
      - "5 Highly Suspicious for Cancer"

model_training:
  enabled: true
  writeback:
    schemas: ["nodule_marks"]
    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