CHB-MIT Seizure Onset and End Marking in Scalp EEG

# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json
#
# CHB-MIT Scalp EEG Database: marking the onset and end of seizures in
# scalp EEG.
#
# Dataset: CHB-MIT Scalp EEG Database (PhysioNet, version 1.0.0)
# Dataset citation (DataCite record for the dataset DOI):
#   @misc{shoeb_2010_chbmit,
#     doi       = {10.13026/C2K01R},
#     url       = {https://physionet.org/content/chbmit/},
#     author    = {Shoeb, Ali},
#     title     = {CHB-MIT Scalp EEG Database},
#     publisher = {physionet.org},
#     year      = {2010}
#   }
# Paper: Shoeb, A. and Guttag, J. "Application of Machine Learning To
#   Epileptic Seizure Detection." 27th International Conference on Machine
#   Learning (ICML), Haifa, 2010. The paper has no DOI.
#   https://icml.cc/Conferences/2010/papers/493.pdf
# DOI: none for the paper. Dataset DOI: 10.13026/C2K01R
# Dataset URL: https://physionet.org/content/chbmit/1.0.0/
# Licence: Open Data Commons Attribution License v1.0. The ten excerpts in
# media/ are cut from recordings in case chb01; see media/LICENSE-media.txt.
#
# Protocol, quoted from the sources:
#   Paper, Section 4.1: "the patients experienced 173 events that were
#   judged to be clinical seizures by experts. For each clinical seizure, an
#   expert indicated the earliest EEG change associated with the seizure."
#   PhysioNet page: "the beginning ( [ ) and end ( ] ) of each seizure is
#   annotated in the .seizure annotation files", and the chbnn-summary.txt
#   files give "the elapsed time in seconds from the beginning of each .edf
#   file to the beginning and end of each seizure contained in it".
#
# Seizure counts differ by source and scope. The paper counts 173 test
# seizures in 916 hours from 23 pediatric patients plus one adult patient at
# another hospital. The PhysioNet page says "the onsets and ends of 182
# seizures are annotated" in the original 23 cases, and 198 seizures
# including case chb24, which was added in December 2010.
#
# Label: "seizure", one interval from onset to end, as in the summary files.
#
# Adaptations:
#   - Each item is a 60 to 141 second excerpt of one hourly recording from
#     case chb01, not a whole file. Seven excerpts span one annotated
#     seizure with 20 seconds of EEG on each side, and three come from files
#     the summary lists with no seizure. Annotators mark intervals from
#     scratch. The reference onset and end times are in
#     media/reference-seizures.csv, for checking afterward.
#   - Each excerpt keeps 5 of the 23 bipolar channels (F7-T7, T7-P7, P7-O1,
#     F8-T8, T8-P8), the temporal chains of both hemispheres. A seizure that
#     shows mainly on a dropped channel can look subtle on the kept ones.
#   - The paper's expert marked the earliest EEG change; the end times come
#     from the dataset's summary files. The design offers one onset and end
#     per seizure and does not model the paper's seizure-versus-nonseizure
#     detector.
#   - All ten excerpts come from one subject. They show the interface and
#     are not a sample of the dataset.
#
# Model-assisted marking (signal-cnn, free mode). Open /admin/training, pick
# signal-cnn for the "seizure" scheme, and train. In free mode it labels the
# recording sample by sample, trained on random 30-second crops of the
# annotated excerpts, and merges runs of the "seizure" label into intervals.
# With writeback on, it proposes seizure intervals on excerpts nobody has
# finished, shown dashed as pre-annotations. Seizures are rare in a
# recording, so the trainer's balanced weighting (default on) matters; set
# min_duration under trainer_params to drop very short predicted runs. It
# needs at least 3 annotated recordings in its training split
# (min_instances) and the extras from
# `pip install "potato-annotation[train-vision,signals]"`. It does not score
# against media/reference-seizures.csv, does not serve or deploy a model, and
# is not a clinical detector. Ten excerpts from one patient exercise the
# loop and do not teach a detector that generalizes across patients.
#
# Run: potato start config.yaml -p 8000

port: 8000
annotation_task_name: "CHB-MIT: mark seizure onset and end in scalp EEG"
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

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

user_config:
  allow_all_users: true

instance_display:
  fields:
    - key: note
      type: text
      label: "Recording"
    - key: signal
      type: time_series
      label: "Scalp EEG excerpt (bipolar montage, 256 Hz)"
      display_options:
        window: 30
        amplitude: window
        channels:
          - name: "F7-T7"
          - name: "T7-P7"
          - name: "P7-O1"
          - name: "F8-T8"
          - name: "T8-P8"

annotation_schemes:
  - annotation_type: interval_label
    name: seizure
    description: "Mark each seizure from its onset (the earliest EEG change associated with it) to its end. Pick the label, then drag across the plot. Leave an excerpt with no seizure unmarked."
    signal_field: signal
    mode: free
    allow_overlap: false
    labels:
      - {name: "seizure", key_value: "s", tooltip: "Seizure, from onset to end"}

model_training:
  enabled: true
  writeback:
    # Show the seizure scheme's predictions to annotators as pre-annotations.
    schemas: ["seizure"]
    include_unlabeled: true
    min_confidence: 0.6

annotation_instructions: |
  Each item is a short excerpt of scalp EEG from one hourly recording of a
  child with epilepsy (CHB-MIT Scalp EEG Database), shown 30 seconds at a
  time with five bipolar channels. Mark every seizure as one interval that
  starts at the earliest EEG change associated with the seizure and ends
  where the seizure activity ends. Some excerpts contain no seizure. Leave
  those without a label. The arrow keys and [ ] move one window.