Gravity Spy LIGO Glitch Classification

# Gravity Spy: classify LIGO detector glitches (22 classes)
#
# Dataset: Updated Gravity Spy Data Set (training set v1.1), Coughlin (2018).
# Volunteers and a convolutional network sort Omega-scan spectrograms of
# transient noise ("glitches") in the Advanced LIGO detectors into
# morphological classes. The class names below are the 22 values of the
# `label` column of trainingset_v1d1_metadata.csv in the Zenodo record
# (7,966 rows), written exactly as the dataset spells them.
#
# Paper:  Zevin et al., Gravity Spy: integrating advanced LIGO detector
#         characterization, machine learning, and citizen science.
#         Classical and Quantum Gravity 34(6), 064003, 2017.
# DOI:    10.1088/1361-6382/aa5cea
# BibTeX (Crossref):
#   @article{Zevin_2017,
#     title   = {Gravity Spy: integrating advanced LIGO detector characterization, machine learning, and citizen science},
#     volume  = {34},
#     ISSN    = {1361-6382},
#     url     = {http://dx.doi.org/10.1088/1361-6382/aa5cea},
#     DOI     = {10.1088/1361-6382/aa5cea},
#     number  = {6},
#     journal = {Classical and Quantum Gravity},
#     publisher = {IOP Publishing},
#     author  = {Zevin, M and Coughlin, S and Bahaadini, S and Besler, E and Rohani, N and Allen, S and Cabero, M and Crowston, K and Katsaggelos, A K and Larson, S L and Lee, T K and Lintott, C and Littenberg, T B and Lundgren, A and {\O}sterlund, C and Smith, J R and Trouille, L and Kalogera, V},
#     year    = {2017},
#     month   = feb,
#     pages   = {064003}
#   }
# Data:   https://zenodo.org/records/1476551
#         Dataset DOI 10.5281/zenodo.1476551, "Updated Gravity Spy Data Set",
#         Creative Commons Attribution 4.0 International.
# Images: the eight spectrograms in media/ are real Gravity Spy training-set
#         images (CC BY 4.0), the 1.0 second view of each glitch, copied
#         unmodified from the Zenodo archive. Source files and attribution are
#         in media/LICENSE-media.txt. The dataset's own label for each image is
#         kept in the `dataset_label` field of sample-data.json, which is listed in
#         item_properties.private_keys so Potato does not send it to the
#         annotator's page.
#
# Glossary. The paper describes two classes in its Figure 1 caption, and
# Section 3.2.1 names None_of_the_Above. The dataset record defines no others,
# so none are paraphrased here.
#   Blip      "short glitches that usually appear in LIGO's gravitational-wave
#             channel with a symmetric 'teardrop' shape in time-frequency"
#   Whistle   "also known as radio frequency beat notes, usually appear in
#             time-frequency plots with a characteristic 'W' or 'V' shape"
#   None_of_the_Above   "If a glitch does not fit into any of the predefined
#             categories, a user can classify it as 'None of the Above'."
#             (Section 3.2.1)
#
# Adaptations (this design differs from the original protocol here):
#   - The paper reports a 20-class training set (7,718 glitches). The Zenodo
#     v1.1 record carries 22 classes (7,966 glitches), and this design uses
#     the 22 from the record.
#   - Gravity Spy moved volunteers through workflows with a growing class set,
#     starting from two classes plus None of the Above. This design offers all
#     22 classes in one flat radio scheme.
#   - Volunteers could cycle through four durations (0.5, 1, 2 and 4 s) of each
#     glitch. This design shows the 1.0 s view only.
#   - The "None of the Above" follow-up questions on duration, frequency and
#     time evolution, the field guide with example images, and gold-standard
#     feedback are not reproduced.
#   - Eight images are shipped, from eight different classes, not ten.
#
# Model training. The trainer is hf-image-classification (needs
# pip install 'potato-annotation[train-vision]'). It fine-tunes a vision
# transformer on the spectrograms and the radio labels, and writes its
# predictions back as prelabels for glitches nobody has labelled. It does not
# serve or deploy a model, and it is not the convolutional network of the paper.
# It reads images from disk, which is why the spectrograms ship in media/. By
# default it needs at least 20 images in its training split and this sample has
# eight, so add images from the Zenodo archive before training (the archive is
# TrainingSet/<label>/<ifo>_<id>_spectrogram_<duration>.png). Open
# /admin/training with the admin key below, pick the trainer and the
# glitch_class scheme, and click Train now.
#
# Run from this folder:
#   potato start config.yaml -p 8000

annotation_task_name: "Gravity Spy LIGO glitch classification"
task_dir: "."
media_directory: media

data_files:
  - "sample-data.json"

item_properties:
  id_key: id
  text_key: image
  private_keys: [dataset_label]

instance_display:
  fields:
    - key: image
      type: image
      label: "Omega scan, 1.0 second view"
      display_options:
        alt_text: "Omega-scan spectrogram of a transient noise glitch in a LIGO detector, time on the horizontal axis and frequency on the vertical axis"
        max_width: 640

output_annotation_dir: "annotation_output"
export_annotation_format: jsonl

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

user_config:
  allow_all_users: true

model_training:
  enabled: true
  writeback:
    schemas: ["glitch_class"]
    include_unlabeled: true
    min_confidence: 0.6

annotation_instructions: |
  Each image is a time-frequency picture (an Omega scan) of a short burst of
  noise recorded by a LIGO gravitational-wave detector. Choose the morphological
  class that best matches the shape. If the glitch fits none of the classes,
  choose None_of_the_Above.

annotation_schemes:
  - annotation_type: radio
    humanize_labels: false
    name: glitch_class
    description: "Which morphological class does this glitch belong to?"
    labels:
      - "1080Lines"
      - "1400Ripples"
      - "Air_Compressor"
      - "Blip"
      - "Chirp"
      - "Extremely_Loud"
      - "Helix"
      - "Koi_Fish"
      - "Light_Modulation"
      - "Low_Frequency_Burst"
      - "Low_Frequency_Lines"
      - "No_Glitch"
      - "None_of_the_Above"
      - "Paired_Doves"
      - "Power_Line"
      - "Repeating_Blips"
      - "Scattered_Light"
      - "Scratchy"
      - "Tomte"
      - "Violin_Mode"
      - "Wandering_Line"
      - "Whistle"
    label_requirement:
      required: true