BBBC038 2018 Data Science Bowl Outlines of Every Nucleus

# 2018 Data Science Bowl nuclei (BBBC038): outline every nucleus
#
# Dataset: BBBC038v1, Kaggle 2018 Data Science Bowl, Broad Bioimage Benchmark Collection
# URL: https://bbbc.broadinstitute.org/BBBC038
# Licence: CC0 (images and Broad Imaging Platform annotations)
# Paper: Caicedo, J. C., Goodman, A., Karhohs, K. W., Cimini, B. A., Ackerman, J.,
#   Haghighi, M., Heng, C., Becker, T., Doan, M., McQuin, C., Rohban, M., Singh, S.,
#   and Carpenter, A. E. (2019). Nucleus segmentation across imaging experiments:
#   the 2018 Data Science Bowl. Nature Methods 16(12), 1247-1253.
#   @article{Caicedo_2019, title={Nucleus segmentation across imaging experiments: the 2018 Data Science Bowl},
#     volume={16}, DOI={10.1038/s41592-019-0612-7}, number={12}, journal={Nature Methods},
#     year={2019}, pages={1247-1253}}
# DOI: 10.1038/s41592-019-0612-7
#
# Protocol quotes (BBBC038 page, "Description" and "Ground truth"):
#   "Each mask contains one nucleus. Masks are not allowed to overlap (no pixel
#   belongs to two masks)."
#   "The ground truth and annotations were originally created by the Broad Imaging
#   Platform using a combination of GIMP and a web-based annotation tool created
#   internally."
# Paper, Methods: annotators "manually delineated each object in the images" with
#   an assisted superpixel tool or with GIMP, "coloring individual pixels outlining
#   each nucleus".
# Label: one class, nucleus. One outline per nucleus, no overlaps.
#
# Sample items: ten real images from stage1_train (CC0), shipped in media/ with
# their ImageIds in media/LICENSE-media.txt. No masks are included.
#
# Adaptations:
#   - Annotators draw polygons in the browser. The original masks were per-pixel
#     (GIMP) or superpixel-assisted (internal tool), not polygons.
#   - The Potato polygon tool replaces both original tools. The task is one label
#     (nucleus) instead of a pixel mask per nucleus.
#   - Images were re-saved as 8-bit RGB PNG; pixel values are unchanged.
#
# Model training (admin page /admin/training, admin key below):
#   cellpose (primary) fine-tunes Cellpose on the polygons annotators drew
#   (each image's outlines become an instance label image) and predicts
#   nucleus polygons for images nobody has outlined. It reads local image
#   files only, which is why the images are in media/. Cellpose's pretrained
#   weights come with the Cellpose authors' own terms. Needs: pip install cellpose
#   sam-finetune is the second option. It fine-tunes only SAM's mask decoder,
#   to turn boxes into outlines, and outlines the boxes an earlier detection
#   run wrote back. It does not touch SAM's image encoder and does not detect
#   nuclei by itself. Needs: pip install 'potato-annotation[train-vision]'
#   Predictions come back as prelabels annotators correct.
#
# Run:
#   potato start config.yaml -p 8000

annotation_task_name: "BBBC038 nucleus outlines"

task_dir: "."
media_directory: media

data_files:
  - "sample-data.json"

item_properties:
  id_key: "id"
  text_key: "image_url"

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: |
  Outline every nucleus in the image with the polygon tool. Draw one polygon per
  nucleus and do not let two polygons overlap. Zoom in for small or crowded
  nuclei, and pan with the hand tool or by dragging.

annotation_schemes:
  - annotation_type: image_annotation
    name: nuclei
    description: "Outline each nucleus with one polygon. Outlines must not overlap."
    source_field: image_url
    tools:
      - polygon
    labels:
      - name: nucleus
        color: "#E6194B"
        key_value: "1"
    min_annotations: 1
    zoom_enabled: true
    pan_enabled: true

model_training:
  enabled: true
  writeback:
    schemas: ["nuclei"]
    include_unlabeled: true
    min_confidence: 0.5
  trainer_params:
    cellpose:
      base_model: nuclei
      epochs: 50