Human Protein Atlas Subcellular Localization Across 28 Labels

# Human Protein Atlas: subcellular localization of a protein, 28 labels per image
#
# Dataset: Human Protein Atlas (HPA) Image Classification competition data
# URL: https://www.proteinatlas.org/humanproteome/subcellular/data
# Competition data page: https://www.kaggle.com/c/human-protein-atlas-image-classification/data
# Licence: HPA licenses "all copyrightable parts of our database" under CC BY 4.0, names no
#   separate image licence, and asks for the credit "Human Protein Atlas"
#   (https://www.proteinatlas.org/about/licence). Because the image terms are not stated,
#   every sample image in this design is synthetic and illustrative.
# Paper: Ouyang, W., Winsnes, C. F., Hjelmare, M., et al. (2019). Analysis of the Human
#   Protein Atlas Image Classification competition. Nature Methods 16(12), 1254-1261.
#   @article{Ouyang_2019, title={Analysis of the Human Protein Atlas Image Classification competition},
#     volume={16}, DOI={10.1038/s41592-019-0658-6}, number={12}, journal={Nature Methods},
#     author={Ouyang, Wei and Winsnes, Casper F. and Hjelmare, Martin and others}, year={2019},
#     pages={1254-1261}}
# DOI: 10.1038/s41592-019-0658-6
#
# Protocol quotes (Ouyang et al. 2019, Nature Methods):
#   "Each image consists of four channels: the antibody-stained protein of interest (green)
#   and three reference channels to outline the cell: microtubules (red), nucleus (blue)
#   and endoplasmic reticulum (ER; yellow)."
#   "Manual annotation of the observed localization pattern is performed by applying one or
#   more labels to the images" (typically two to six labels per sample).
#   "A total of 32 organelle classes from the HPA were merged into 28 classes for the
#   competition."
# Kaggle data page: "The green filter should hence be used to predict the label, and the
#   other filters are used as references."
#
# Label glossary, verbatim from the Kaggle data page (integer codes 0-27 in train.csv):
#   0 Nucleoplasm, 1 Nuclear membrane, 2 Nucleoli, 3 Nucleoli fibrillar center,
#   4 Nuclear speckles, 5 Nuclear bodies, 6 Endoplasmic reticulum, 7 Golgi apparatus,
#   8 Peroxisomes, 9 Endosomes, 10 Lysosomes, 11 Intermediate filaments, 12 Actin filaments,
#   13 Focal adhesion sites, 14 Microtubules, 15 Microtubule ends, 16 Cytokinetic bridge,
#   17 Mitotic spindle, 18 Microtubule organizing center, 19 Centrosome, 20 Lipid droplets,
#   21 Plasma membrane, 22 Cell junctions, 23 Mitochondria, 24 Aggresome, 25 Cytosol,
#   26 Cytoplasmic bodies, 27 Rods & rings
#
# Sample items: ten synthetic, illustrative four-channel OME-TIFF images (media/), drawn
# with numpy. They are cartoons of localization-like patterns, not HPA images, and carry no
# gold labels. See media/LICENSE-media.txt.
#
# Adaptations:
#   - Images are synthetic and illustrative, not HPA images (licence for images not stated).
#   - Each four-channel image is one OME-TIFF (the original ships four PNG or TIFF files per
#     sample), because Potato's microscopy display reads OME-TIFF or OME-Zarr from local files.
#   - The microscopy scheme is a viewer (tools: []). Annotators switch channels and contrast
#     and record the labels in the multiselect below. No regions or cells are drawn.
#   - One annotator labels each image. The original data mixes expert annotation, curated by a
#     second expert, with annotation by EVE Online gamers, curated by experts. Neither workflow
#     is reproduced.
#   - The model_training trainer reads the green (protein) channel as a PNG
#     (image_url, media/hpa_NNN_green.png), since Pillow cannot read a four-channel OME-TIFF.
#
# Model training (admin page /admin/training, admin key below):
#   hf-image-classification fine-tunes a vision transformer on the labelled green-channel
#   PNGs as a multi-label classifier over the 28 labels, and predicts labels for images
#   nobody has labelled, written back as prelabels to correct. It learns from the green
#   channel only and does not see the reference channels. Needs:
#   pip install 'potato-annotation[train-vision]'
#   sklearn-text, which classifies CLIP image embeddings, is the option with no extra install.
#   With ten synthetic images the demo shows the loop, not a useful model.
#
# Run (the microscopy display needs the optional readers):
#   pip install 'potato-annotation[microscopy]'
#   potato start config.yaml -p 8000

annotation_task_name: "HPA protein localization"

task_dir: "."
media_directory: media

data_files:
  - "sample-data.json"

item_properties:
  id_key: "id"
  text_key: "note"

output_annotation_dir: "annotation_output"
export_annotation_format: jsonl

user_config:
  allow_all_users: true
  users: []

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

annotation_instructions: |
  The green channel shows the protein of interest. The red, blue, and yellow channels show
  microtubules, the nucleus, and the endoplasmic reticulum, to place the protein inside the
  cell. Turn channels on and off and adjust contrast, then select every compartment where the
  protein sits. Most samples carry between two and six labels.

annotation_schemes:
  - annotation_type: microscopy
    name: cells
    description: "Inspect the four channels (protein, microtubules, nucleus, endoplasmic reticulum)."
    instructions: >-
      Turn channels on and off and set their contrast in the Channels panel. Compare the
      green protein channel against the three reference channels.
    image_key: image
    tools: []
    labels:
      - name: region
        color: "#e8590c"
    channels:
      - name: protein
        label: "Protein (green)"
        color: "#00ff00"
      - name: microtubules
        label: "Microtubules (red)"
        color: "#ff0000"
      - name: nucleus
        label: "Nucleus (blue)"
        color: "#0000ff"
      - name: ER
        label: "Endoplasmic reticulum (yellow)"
        color: "#ffff00"
    height: 520

  - annotation_type: multiselect
    name: localization
    description: "Which compartments does the protein localise to? Select every label that applies."
    labels:
      - "Nucleoplasm"
      - "Nuclear membrane"
      - "Nucleoli"
      - "Nucleoli fibrillar center"
      - "Nuclear speckles"
      - "Nuclear bodies"
      - "Endoplasmic reticulum"
      - "Golgi apparatus"
      - "Peroxisomes"
      - "Endosomes"
      - "Lysosomes"
      - "Intermediate filaments"
      - "Actin filaments"
      - "Focal adhesion sites"
      - "Microtubules"
      - "Microtubule ends"
      - "Cytokinetic bridge"
      - "Mitotic spindle"
      - "Microtubule organizing center"
      - "Centrosome"
      - "Lipid droplets"
      - "Plasma membrane"
      - "Cell junctions"
      - "Mitochondria"
      - "Aggresome"
      - "Cytosol"
      - "Cytoplasmic bodies"
      - "Rods & rings"
    display_config:
      num_columns: 3
    label_requirement:
      required: true

model_training:
  enabled: true
  writeback:
    schemas: ["localization"]
    include_unlabeled: true
    min_confidence: 0.5