feat(review): Session Review as a Resolve-style editor, with markers and an epoch table

[gbradham]

Session Review has been a stack of cards: a header of seven buttons, a canvas, a 46 px bar and a tab of tables. It had no zoom (one pixel of a 45,000-frame session is tens of frames), and it could only open an ethogram CSV. A live rig recording with video, tracking and hardware events but no classifier run could not be opened at all.

This PR rebuilds it as an editor modelled on DaVinci Resolve's Edit page. Each track is a behaviour source or a hardware device instead of an audio or video track. You scrub the video, drag a range, and read what happened in it. It carries phases 1 and 2:

• Phase 1: the editor itself — layout, timeline, navigator, and opening live recordings.
• Phase 2: markers (point notes and named ranges, per session or shared across a cohort) and the epoch table, which measures every animal over the cohort's ranges, with mean and SEM per group.

Hardware-driven selection ("select all ON periods") is phase 3, and is not here.

What you get

Layout (chosen from browser mockups):

• Top row: sessions list | viewer | inspector, with the side panels collapsible.
• Below it, a full-width timeline with a whole-session navigator strip. Drag its box to pan, drag its edges to zoom, click outside to jump.
• Three top-bar menus (Open, Zones, Export) replace the seven buttons. A status bar shows fps, rows, poses, video, hardware lanes, event/tracking counts and markers.

Timeline:

• A 212 px header column shows each track's value at the playhead: ON, ON · 10 Hz, 90°, the current behaviour.
• A timecode ruler (HH:MM:SS:FF, flow-relative) with the pre-flow period hatched.
• Behaviour becomes labelled clips once bouts are ≥ 2 px wide, and stays the per-pixel majority below that.
• Pulse trains draw individually when zoomed in and at their duty fraction when zoomed out, so a 10 Hz 50 % train no longer looks like a lamp held on.
• Lanes are coloured by role: outputs cyan, servo/PWM violet, inputs green.

Mouse and keys:

• Drag across the tracks to select. Snapping pulls ends to bout edges, hardware switches and marker edges within 8 px.
• Drag an In/Out edge to trim. ⌘/Ctrl-scroll or pinch zooms about the cursor; scroll pans.
• Right-click opens the range menu: Set In/Out here, Select bout, Select whole session, Save range as marker, Add marker here, Zoom to range, Loop range, Export range stats, Copy timecode, Clear.
• Keys: I, O, X, Z, ⇧Z, Esc, J/K/L shuttle up to 8×, ⌘/Ctrl+A, and M, ⇧M, ↑/↓ for markers. The existing ←/→, Home/End and [ ] are unchanged.

Viewer:

• A HUD names the behaviour on this frame and every hardware output currently driven.
• A transport bar with Video, Poses, Trail, Heatmap, Zones and HUD toggles.

Inspector:

• The Range tab has an In/Out card (naming the range markers the selection falls inside, with Save as range marker), then Movement (cm travelled, mean and peak cm/s), Behaviour, Hardware in range (20.0 s on · 200 pulses, 1× at 2:25.0, 90° → 180° at 2:30.0) and Zones.
• The Session tab has provenance and the fix-its.
• The Markers tab lists ranges then points, filterable, and clicking one seeks to it.

Opening:

• Open recording folder… opens a live recording directly.
• Open folder as cohort… finds every ethogram and recording under a folder. Each ethogram claims the recording it came from, so no animal appears twice. Sessions are grouped by the group in glider_project.json.

Phase 2: markers and the epoch table

Markers:

• M drops a point marker at the playhead ("door stuck here"); ⇧M keeps the In/Out range as a named range marker. Toolbar buttons do the same.
• A small editor opens under the marker: name, one of nine colours, a note, scope (This session or Whole cohort), and Extend to In/Out to turn a point into a range. Double-click a marker to edit it again.
• The 28 px marker row draws ranges as bars (stacking when they overlap) and points as flags, with a faint rule through the lanes. Drag a point to move it, or a range edge to trim it; snapping applies. ↑/↓ step between markers, and the navigator shows the ranges.

Epoch table (replaces the Cohort tab beside the timeline):

• Columns are the cohort's range markers in time order — Baseline, Stim, Post — plus the Current range, each switchable with a chip.
• Metrics come from a Metrics ▾ menu: distance, speed, each behaviour in seconds and as a percentage of the range, zone time/entries/latency, time on per device, and the thresholds each session was scored with. Defaults: distance, speed, freezing %, and the first zone's time.
• Rows are animals, grouped by treatment, each group closed by a mean and a SEM row. Cells carry a faint bar scaled to the column's largest value, and — with a tooltip saying why where an animal can't answer (no calibration, no zones, range outside the session).
• Click a row to show that animal in the viewer; double-click to jump to its timeline.
• Export ▾ adds Epoch table, tidy (CSV), Epoch table, wide (CSV) and Markers (CSV).

Behaviour changes (also in CHANGELOG)

• A plain drag in the timeline now selects. It used to scrub. Scrub on the ruler or the navigator instead.
• Right-drag no longer selects. Right-click opens the range menu.
• A range is measured from each animal's own zero. The current range, a cohort range marker and the Range stats export all mean the same seconds after each animal's flow start (or first video frame). Phase 1 applied the shown animal's frame window to everyone, which is a different stretch of protocol for any animal whose rig ran longer before flow start or recorded at another rate. Numbers change only for those animals. Exports gain start_s, end_s and t0.

Design decisions

• Qt-free models, widgets that only draw. This follows the pattern session_view.py already set.
  • analysis/timeline.py gains value_at, rate_at, hardware_in_range and describe_*.
  • analysis/cohort.py (new) handles discovery and session ids.
  • analysis/markers.py (new) holds the time rule, the Marker model, and the marker files.
  • analysis/epochs.py (new) holds the metric catalog, mean and SEM, and the tidy and wide frames.
  • gui/review/viewport.py holds the zoom, pan, snap and timecode arithmetic.
  • The widgets live in a new gui/review/ package. analysis_window.py is now the shell that wires them.
• selection_changed still emits frames. segment_stats and zone_rows are untouched.
• One time rule. A marker's seconds are what the ruler shows: flow-relative when the session has a flow start, video-relative otherwise. seconds_at / frame_at / frames_in do every conversion — markers, snapping, the current range, cohort ranges and exports — so they cannot disagree about where a second falls. The current range is held in seconds: set when you select, never re-derived from the animal on screen, so a 15.59 fps animal (which cannot show 1.033 s exactly) cannot quietly move it.
• Markers live beside the data. review_markers.json sits in the session's folder and cohort_markers.json in the folder opened as a cohort — not in glider_project.json (which would couple to its schema and need a manifest), and not in QSettings (not portable). Writes are atomic (temp file, then os.replace) and keep the file's existing permissions, so a cohort file on a shared lab drive stays readable to the rest of the lab. A file that cannot be read, or that a newer GLIDER wrote, is never overwritten: its markers turn read-only, the tools say why, and the error is shown once.
• A live recording opens as a SessionView (SessionView.from_recording), so the canvas, trail, heatmap, zones and range statistics work unchanged. Three details decided this:
  • Frame offset. The tracking logger numbers frames from 1 and a video decodes from 0. first_video_frame makes the viewer read video frame n − 1; without it every frame shows its neighbour.
  • Calibration comes from the tracking CSV's # Pixels/mm header, scaled to the viewing resolution. It is never taken as distance_px / distance_mm: an uncalibrated logger writes the same number into both, which would claim 1.00 px/mm.
  • fps comes from the frame span over the elapsed_ms span. Session.frame_rate takes the median of millisecond-rounded timestamps and reads 30.30 for a 30 fps rig, which would skew every per-second number by 1 %.
• One animal across tracker id changes. The live tracker assigns a new object_id after a detection loss. A recording is split into subjects only when two ids ≥ 0 share a frame; otherwise one animal would be silently truncated at the first id change.
• Nothing a lab file contains may abort GLIDER. A non-UTF-8 CSV or a misshapen glider_project.json under a cohort folder used to raise out of a menu action and kill the process. Both are handled at the shared roots (_io._classify_csv, Project.load), and a bad manifest only costs the grouping, with a warning.
• The session's layout and hidden lanes persist in QSettings. Hidden lanes are keyed per session folder, because session ids repeat across cohorts. Tests point the settings at a temp file.
• Every new colour is a token in colors.py. A test checks that every hex in the Session Review stylesheet matches one. Markers use nine named swatches, saved by name, so retuning a colour recolours old markers too.

Fixes found along the way

• The video no longer slides sideways as the playhead moves. The transport's bout read-out was a plain label whose text width fed the viewer panel's minimum width, so each new behaviour name pushed the splitter. It now elides, and the clock and frame counter are fixed to their widest text. The HUD's behaviour chip is sized once per session, so it no longer twitches with every digit.
• The top-bar menus are one size, with their arrows centred. The shared width is measured from the widest label in the platform's own font — a fixed minimum had held only on macOS, and CI caught the buttons uneven again on Windows.
• Seeking is fast. ExactFrameReader reached any earlier frame by decoding forward from frame 0, so one step back at frame 40,000 decoded 40,000 frames, and turning the video back on after scrubbing walked from wherever it had stopped. It now seeks just before its target and reads the landed frame's own timestamp to know exactly where it is, falling back to counting from 0 the moment a file's timestamps disagree with its frames. Frames are identical to the old reader's. On a 20-minute lab camera recording, a step back at frame 14,025 took 23 ms, where the old reader decoded 14,025 frames to get there.
• An apply-run ethogram paired with its recording is no longer a frame off its hardware — the first of phase 1's known follow-ups. The ethogram counts frames from 0 and the logger from 1; the timeline now states every frame in the view's numbering.
• A session read at the wrong frame rate when its poses were out of reach. SessionView.load fell back to 30 fps whenever the pose CSV could not be found, so a 15.59 fps recording read every duration and speed at nearly twice its rate. It now reads the rate from the run manifest; a reachable pose CSV still wins.

Tests

5389 → 5700 passed (4 skipped, 5 deselected); ruff and black clean. CI green on Windows, Ubuntu and macOS.

• New suites: tests/unit/gui/review/ (timeline, navigator, viewer, inspector, pool, marker editor, epoch table), tests/unit/analysis/test_cohort.py, test_markers.py, test_epochs.py, and the recording, keys, menu, loop, HUD, hardware-stats, time-rule, marker and epoch-table classes in test_analysis_window.py.
• Migrated: the 112 window tests moved to the new widget names without weakening an assertion. test_timeline_bar.py was retired, and its cases live in test_timeline_view.py. The Cohort-tab tests became epoch-table tests.
• Checked against real data: phase 2 was run read-only against two sessions of a lab cohort (camera recordings at 15.59 and 30 fps): markers saved beside local copies, the epoch table filled for both, and one cohort range gave each animal different frames for the same seconds. That run found the frame-rate bug above.
• Opt-in real-data smoke test: tests/integration/test_review_real_recording.py (marker real_recording) is skipped unless GLIDER_REVIEW_RECORDING points at a rig recording folder. It checks that real tracking frames line up with the real video, and that a real rig's events become lanes. It has not been run against a rig recording yet.

Each task in both phases (13 in phase 1, 12 in phase 2) was reviewed for spec and quality, and so was each whole branch; findings were fixed in-branch.

Known follow-ups (not in this PR)

1. build_timeline still draws one "Live state" lane per tracker id, so a recording whose id changed shows several lanes while the statistics treat it as one animal.
2. Session.frame_rate reads 30.30 fps for a 30 fps rig, as above. from_recording works around it; other callers still see it.
3. The exact-seek reader has one blind spot: a frame dropped in a stretch of a variable-rate file the reader has never walked through cannot be seen, and a seek past it would land one frame off. A whole-file check of one lab camera recording found no drops; the upgrade path (index timestamps in one pass on open) is written in the docstring.
4. Minor:
   • The first fill of the epoch table on a large cohort runs on the GUI thread without a wait cursor (cached afterwards).
   • M saves the marker before its editor opens, so Cancel keeps an unnamed marker; delete it from the editor.
   • The epoch grid lacks the alternating-row styling the other result tables have.
   • Session duration in the list counts rows, so recordings with gaps under-report.
   • Menu items no longer carry the old buttons' tooltips.

Not in this PR

• Hardware-driven selection (phase 3): select one ON period, all ON periods, compare ON vs OFF.
• Multi-camera support and session-folder unification (the earlier P2/P3).