PAMAP2 Activity Interval Labels on Wearable Sensor Signals

# yaml-language-server: $schema=https://potatoannotator.readthedocs.io/en/latest/schemas/potato-config.schema.json
#
# PAMAP2 Physical Activity Monitoring: label activity intervals on wearable
# IMU and heart-rate signals.
#
# Dataset: PAMAP2 Physical Activity Monitoring (UCI Machine Learning Repository)
# Paper:
#   @inproceedings{Reiss_2012,
#     title     = {Introducing a New Benchmarked Dataset for Activity Monitoring},
#     url       = {http://dx.doi.org/10.1109/ISWC.2012.13},
#     DOI       = {10.1109/iswc.2012.13},
#     booktitle = {2012 16th International Symposium on Wearable Computers},
#     publisher = {IEEE},
#     author    = {Reiss, Attila and Stricker, Didier},
#     year      = {2012},
#     month     = {June},
#     pages     = {108--109}
#   }
# DOI: 10.1109/ISWC.2012.13
# Dataset DOI: 10.24432/C5NW2H
# Dataset URL: https://archive.ics.uci.edu/dataset/231/pamap2+physical+activity+monitoring
# Licence: CC BY 4.0. The ten excerpts in media/ are cut from the Protocol
# recordings of subjects 101, 102, 104, 105, 106, 107 and 108; see
# media/LICENSE-media.txt.
#
# Setup, quoted from the dataset page and readme.pdf (section I):
#   "3 Colibri wireless inertial measurement units (IMU): sampling frequency:
#   100Hz; position of the sensors: 1 IMU over the wrist on the dominant arm,
#   1 IMU on the chest, 1 IMU on the dominant side's ankle. HR-monitor:
#   sampling frequency: ~9Hz."
#   "Each of the subjects had to follow a protocol, containing 12 different
#   activities."
#   "Labeling the different performed activities was done via a GUI running
#   on the Viliv" (the readme's companion unit, a Viliv S5 UMPC).
#
# Activity IDs and names, quoted from readme.pdf, section II.2:
#    1 lying                      11 car driving
#    2 sitting                    12 ascending stairs
#    3 standing                   13 descending stairs
#    4 walking                    16 vacuum cleaning
#    5 running                    17 ironing
#    6 cycling                    18 folding laundry
#    7 Nordic walking             19 house cleaning
#    9 watching TV                20 playing soccer
#   10 computer work              24 rope jumping
#    0 other (transient activities)
#   readme.pdf: "data labeled with activityID=0 should be discarded in any
#   kind of analysis. This data mainly covers transient activities between
#   performing different activities".
#
# What this design is. PAMAP2's labels were not produced in an annotation tool
# by annotators who inspected the signals. The subjects followed a scripted
# protocol, and the activity labels were entered through a GUI on the
# companion unit as the session went on. This design therefore re-labels, it does not reproduce an
# annotation protocol. Each item is a 150 second excerpt of a wearable
# recording, shown 30 seconds at a time, with the dataset's own labels loaded
# as pre-annotations. An annotator reviews and corrects where each activity
# starts and ends from the wrist motion and heart rate. This is wearable IMU
# activity labelling, a different task from the clinical ECG, EEG and
# polysomnography designs in this folder.
#
# Adaptations:
#   - Excerpts, not whole recordings. Each item is 150 seconds of one subject's
#     Protocol file. Ten excerpts come from seven of the nine subjects.
#   - Only seven of the 52 sensor columns are shown: heart rate, and the hand
#     IMU's 3D acceleration (the +-16 g accelerometer, which readme.pdf
#     recommends) and 3D gyroscope. The chest and ankle IMUs, the +-6 g
#     accelerometer, the magnetometer and the temperature channel are left out.
#   - The 100 Hz data is averaged (4 rows to 1) to 25 Hz, and heart rate (about 9 Hz in the
#     source) repeats its last value between readings.
#   - The dataset's own activityID column is the reference. It loads as
#     pre-annotations from each item's events file, with activityID 0 shown as
#     "other (transient activities)". The scheme offers all 19 IDs of the
#     readme. The excerpts use 13 of them: lying, sitting, standing, walking,
#     running, cycling, Nordic walking, ascending stairs, descending stairs,
#     vacuum cleaning, ironing, rope jumping and "other". Watching TV,
#     computer work, car driving, folding laundry, house cleaning and playing
#     soccer are never used by a reference label here.
#   - Labels are applied to all channels. The recording is one wrist's IMU plus
#     heart rate, so a per-channel interval has no meaning for an activity.
#
# Model-assisted labeling (signal-cnn). The model_training block turns on
# training and writeback. The trainer is not named here. Open /admin/training,
# pick signal-cnn for the "activity" scheme, and train. In free mode it labels
# each recording sample by sample from all seven channels, resampled to 100 Hz,
# trains on random 30-second crops, and merges runs of one label into
# intervals. It trains on saved labels only. The reference labels count as
# training labels after an annotator saves them (press "Keep these" or edit).
# Potato never writes a prediction onto an item the model trained on.
# Writeback is limited here: the time_series display shows a model's intervals
# only for a recording whose events file and item supply none of their own
# (signal_routes.signal_preannotations). Every excerpt in this design carries an
# events file, so no dashed model proposal appears. To see one, remove the
# "events" entry from an item in sample-data.json. The trainer 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
# serve or deploy a model. Ten short excerpts from seven subjects exercise the
# loop. They do not train an activity recognizer that generalizes to new
# people.
#
# Run: potato start config.yaml -p 8000

port: 8000
annotation_task_name: "PAMAP2: label activity intervals on wearable signals"
task_dir: "."
media_directory: media

data_files:
  - sample-data.json

item_properties:
  id_key: id
  text_key: note
  # The reference intervals stay on the server. The scheme reads them from the
  # item as preannotation_field, so hiding the field keeps them out of the
  # page data and does not stop them loading as pre-annotations.
  private_keys: [events]

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: "Excerpt"
    - key: signal
      type: time_series
      label: "Hand IMU and heart rate (25 Hz)"
      display_options:
        window: 30
        lane_height: 70

annotation_schemes:
  - annotation_type: interval_label
    name: activity
    description: "Activity intervals. Pick an activity, then drag across the plot to mark where it starts and ends. Loaded intervals are the dataset's own labels; adjust them."
    signal_field: signal
    mode: free
    allow_overlap: false
    channel_scope: all
    preannotation_field: events
    labels:
      - {name: "lying", key_value: "1"}
      - {name: "sitting", key_value: "2"}
      - {name: "standing", key_value: "3"}
      - {name: "walking", key_value: "4"}
      - {name: "running", key_value: "5"}
      - {name: "cycling", key_value: "6"}
      - {name: "Nordic walking", key_value: "7"}
      - {name: "watching TV", key_value: "8"}
      - {name: "computer work", key_value: "9"}
      - {name: "car driving", key_value: "0"}
      - {name: "ascending stairs", key_value: "q"}
      - {name: "descending stairs", key_value: "w"}
      - {name: "vacuum cleaning", key_value: "e"}
      - {name: "ironing", key_value: "r"}
      - {name: "folding laundry", key_value: "t"}
      - {name: "house cleaning", key_value: "y"}
      - {name: "playing soccer", key_value: "u"}
      - {name: "rope jumping", key_value: "i"}
      - {name: "other (transient activities)", key_value: "o"}

model_training:
  enabled: true
  writeback:
    # Store the activity scheme's predictions on items the model did not train
    # on. The display shows them only where an item has no events of its own.
    schemas: ["activity"]
    include_unlabeled: true
    min_confidence: 0.6

annotation_instructions: |
  Each item is a 150 second excerpt of a wearable recording from the PAMAP2
  dataset, shown 30 seconds at a time. The top lane is heart rate. The next
  three lanes are the wrist accelerometer and the last three are the wrist
  gyroscope. The dataset's own activity labels load as a starting point.
  Move each boundary to where you see the movement change, add what is
  missing, and press "Keep these" to save the labels. The label
  "other (transient activities)" covers going from one location to the next
  activity's location, or waiting for equipment to be prepared. The dataset
  says to leave it out of any analysis.