Powdermill Bird Soundscape Species Boxes on Spectrograms

# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json
# Powdermill bird soundscapes: species boxes on a spectrogram.
#
# Dataset: "An annotated set of audio recordings of Eastern North American
#   birds containing frequency, time, and species information"
#   (Chronister, Rhinehart, Place, and Kitzes; 16,052 boxes, 48 species,
#   385 minutes of dawn chorus recorded at Powdermill Nature Reserve, PA).
# Paper:   Ecology 102(6), e03329, 2021. DOI: 10.1002/ecy.3329
#   @article{Chronister_2021,
#     title   = {An annotated set of audio recordings of Eastern North American
#                birds containing frequency, time, and species information},
#     volume  = {102}, number = {6}, journal = {Ecology}, publisher = {Wiley},
#     author  = {Chronister, Lauren M. and Rhinehart, Tessa A. and Place, Aidan
#                and Kitzes, Justin},
#     year    = {2021}, month = may, DOI = {10.1002/ecy.3329}}
# Data:    https://zenodo.org/records/4656848
#   (Dryad DOI 10.5061/dryad.d2547d81z), CC0 1.0. The 10-second MP3 excerpts
#   in media/ are cut from the dataset's own MP3 files and are real.
#
# Protocol, quoted from the dataset README:
#   "Annotation involved drawing boxes on spectrograms to obtain the time and
#   frequency intervals of each bird sound and then identifying the species."
#   "Aidan Place was then given the boxed spectrograms without species identity
#   and directed to make independent identifications and flag any time/frequency
#   box issues."
#   "Last, Tessa Rhinehart was given the annotations by LC and AP to settle
#   discrepancies."
#   "All vocalizations that were not short "chips" and could be identified were
#   annotated."
# Each box carries Begin Time (s), End Time (s), Low Freq (Hz), High Freq (Hz)
# and a Species column in standard banding alpha code format.
#
# Label glossary (alpha code, common name, from the README):
#   EATO Eastern towhee, WOTH Wood thrush, BCCH Black-capped chickadee,
#   BTNW Black-throated green warbler, TUTI Tufted titmouse,
#   NOCA Northern cardinal, REVI Red-eyed vireo, AMCR American crow.
#
# Adaptations:
#   - The original set has 48 species. This design keeps the eight with the
#     most boxes in the full tables (EATO 5,238; WOTH 1,826; BCCH 1,262;
#     BTNW 1,058; TUTI 885; NOCA 884; REVI 592; AMCR 534). Boxes of the other
#     40 species are left out of the sample data.
#   - Items are ten 10-second excerpts of five-minute segments from Recordings
#     1, 2 and 4, each re-encoded as 64 kbps mono MP3. Box times are shifted to
#     the excerpt start. Boxes that cross an excerpt edge are dropped.
#   - The dataset's final boxes are loaded as pre-annotations, so annotators
#     check and correct them. The original workflow was three passes (draw and
#     identify, blind re-identification, adjudication) in Raven Pro.
#
# Run from this folder:
#   potato start config.yaml -p 8000
#
# Training (optional). The torchvision-detect trainer fine-tunes a Faster R-CNN
# on spectrogram boxes (needs `pip install 'potato-annotation[train-vision]'`).
# It learns box positions and species labels from the boxes annotators have
# confirmed. Potato writes predictions only onto items outside the training
# split, into the item's "predictions" field. The dataset's boxes are loaded
# into that same field for every excerpt, so on an excerpt the model did not
# train on, a prediction at or above min_confidence replaces the loaded boxes
# for the calls scheme. Excerpts the model trained on keep no model boxes.
# It does not serve or deploy the model. Open /admin/training with the key
# below, pick torchvision-detect and the calls scheme, and click Train now.
# Ten excerpts are a demonstration, not enough to train a useful detector.
port: 8000
annotation_task_name: "Powdermill bird soundscapes: species boxes"
task_dir: "."
output_annotation_dir: "annotation_output"
export_annotation_format: raven
data_files:
  - "sample-data.json"
item_properties:
  id_key: id
  text_key: recording

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

user_config:
  allow_all_users: true
  users: []

instance_display:
  fields:
    - key: recording
      type: text
      label: Excerpt

pre_annotation:
  enabled: true
  field: predictions
  allow_modification: true

annotation_schemes:
  - annotation_type: spectrogram_annotation
    name: calls
    description: "Check the boxes loaded from the dataset's Raven selection tables. Move, resize, relabel or delete them, and draw any call that was missed."
    source_field: audio_url
    labels:
      - name: EATO
        color: "#2563eb"
      - name: WOTH
        color: "#dc2626"
      - name: BCCH
        color: "#16a34a"
      - name: BTNW
        color: "#d97706"
      - name: TUTI
        color: "#9333ea"
      - name: NOCA
        color: "#0891b2"
      - name: REVI
        color: "#db2777"
      - name: AMCR
        color: "#65a30d"
    instructions: "Drag on the spectrogram to draw a box around one bird sound, covering its time and frequency span. Drag a box to move it and its corners to resize it. Pick the species alpha code with the buttons or keys 1-8 (EATO Eastern towhee, WOTH Wood thrush, BCCH Black-capped chickadee, BTNW Black-throated green warbler, TUTI Tufted titmouse, NOCA Northern cardinal, REVI Red-eyed vireo, AMCR American crow). Short chips are not boxed."

annotation_instructions: "Review each ten-second dawn-chorus excerpt. Each box marks the time and frequency span of one bird sound and carries the species code. Fix wrong boxes and labels, and add any missed sound from the eight listed species."

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