feat: frame-spanning Event annotations (data model + Labels + SLP format 2.6) (#539)

[talmo]

Summary

Implements #539 in full — the frame-spanning Event annotation, end to end: data
model, Labels integration, SLP serialization, docs, and tests, in one PR. Event is
the first sleap-io annotation with a temporal extent (a (video, start_frame, end_frame, type) interval) — every existing annotation (Instance, Centroid,
BoundingBox, SegmentationMask, LabelImage, ROI) is strictly per-frame. Events
model anything with a duration: behavior bouts (HITL behavior-segmentation), stimulus
epochs, physiological events, feeding bouts, review flags.

Key changes

Data model — sleap_io/model/event.py

• EventType — lightweight, name-matched catalog entry (the "ethogram"), following
  the Track / Identity pattern (@define(eq=False), name / description /
  metadata, matches()).
• Event — abstract base carrying the interval, subject / target participants
  (Track | Identity | None), and metadata. Guards abstract instantiation, fills
  end_frame→start_frame when omitted, validates end_frame >= start_frame.
  Inclusive frame convention. Properties is_predicted / is_directed /
  is_instantaneous / n_frames / frames; methods contains() / overlaps().
• UserEvent / PredictedEvent — human-vs-model split. PredictedEvent adds two
  independent optional fields: scores (framewise (n_frames,) float32 trace) and
  score (scalar); neither is derived from the other.

Labels integration

• New top-level lists Labels.events and Labels.event_types (kw_only), siblings
  of videos / tracks / suggestions — not on LabeledFrame (events may cover
  unlabeled frames).
• Auto-collection: registers referenced EventTypes (deduped by name, canonicalizing
  each event's type), subject/target Track / Identity, and each event's video
  into the respective catalogs — at construction and at save time.
• Accessors: get_events(video, subject, type, frame_idx, predicted) (frame_idx
  matches events whose span covers the frame) and events_at(video, frame_idx, subject).
• copy() (eager + lazy) and merge() carry events across, remapping every
  reference onto the copied/merged catalogs; merge() dedupes event_types by name and
  never mutates the source.

SLP serialization — format 2.6 (additive, presence-guarded)

• /event_types — catalog group (name + optional description + EAV meta_*),
  mirroring /identity.
• /events — columnar struct-of-arrays (one dataset per field, like /bboxes):
  video, start_frame/end_frame (int64, inclusive), type, subject_kind/
  target_kind (int8: 0=none/self, 1=track, 2=identity), subject_idx/target_idx,
  is_predicted, score (float64, NaN=unset), name/source, per-event EAV metadata —
  plus a ragged CSR pair (scores flat float32 + score_offsets) for optional
  framewise traces. The scalar score column, both trace datasets, and the metadata
  table are each omitted when unused; the whole group is omitted when there are no events,
  so event-free files stay byte-identical.
• Wired into the eager and lazy read/write paths; registered in
  _KNOWN_TOPLEVEL_HDF5_NAMES; format_id bumped to 2.6 only when events are present;
  format-version-history docstring updated.

Docs

• docs/model/events.md — full model reference (frame convention, participants,
  overlap, Labels attachment, SLP persistence).
• docs/examples.md — a HITL behavior-segmentation example.
• docs/formats/slp.md — the /event_types + /events groups and format 2.6.

Example

import sleap_io as sio

labels = sio.load_slp("session.slp")
video, (m1, m2) = labels.videos[0], labels.tracks[:2]
attack = sio.EventType(name="attack", metadata={"color": "#e6194b"})

# Model proposal (framewise + scalar confidence, both optional/independent)
labels.events.append(sio.PredictedEvent(
    type=attack, video=video, start_frame=100, end_frame=140,   # inclusive
    subject=m1, target=m2, scores=[0.6]*41, score=0.74))
# Human ground truth (bare string auto-promotes; target=None => non-directed)
labels.events.append(sio.UserEvent(type="rear", video=video, start_frame=120, subject=m1))

labels.get_events(type="attack", predicted=True)   # proposals to review
labels.events_at(video, 130)                        # events covering frame 130
labels.save("scored.slp")                           # /event_types + /events (format 2.6)

Design decisions (per the issue's "leans")

Keep the EventType catalog (strings auto-promote) · union subject/target fields ·
inclusive [start_frame, end_frame] · defer from_predicted · field name type.

Testing

• Model (test_event.py): 32 tests, 100% line + branch coverage of event.py.
• Labels (test_labels.py): collection (name-dedup + rebind, participants, video),
  get_events / events_at, copy, merge, replace_videos remap.
• SLP (test_slp.py): round-trip (eager + lazy), framewise/scalar scores, presence
  guards, format 2.6, backward-compat (pre-2.6 → empty), the -1 = none type sentinel,
  event-only-video round-trip, and event.video surviving embed=True.
• Full tests/ suite green (4293 passed, 3 skipped); all doc code blocks execute; ruff
  clean.

An adversarial multi-agent review (SLP / merge-copy / compat lenses, each finding
independently verified) caught and this PR fixes two silent-data-loss bugs where
event.video was dropped to None — for event-only videos and on the embed=True /
apply_crops() path — both now covered by regression tests.

Closes #539.

🤖 Generated with Claude Code

https://claude.ai/code/session_011DiaqkmRcp1L9yD8dx4jLj

[codecov]

Codecov Report

❌ Patch coverage is 99.72527% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 93.45%. Comparing base (27191e2) to head (8ff748b).

Files with missing lines	Patch %	Lines
sleap_io/model/labels.py	98.76%	0 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #540      +/-   ##
==========================================
+ Coverage   93.34%   93.45%   +0.10%     
==========================================
  Files          55       56       +1     
  Lines       20868    21232     +364     
  Branches     4685     4757      +72     
==========================================
+ Hits        19479    19842     +363     
  Misses        663      663              
- Partials      726      727       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

Docs Preview

Preview URL	https://io.sleap.ai/pr/540/
Commit	8ff748b55cd6452600ad791b2a10753c437a5706

Changed pages:

• examples.md
• slp.md
• events.md

API changes detected - View API Reference

Configuration files changed - full rebuild performed.

This preview will be removed when the PR is closed.