08 [task] Split-1 impl — index, segmentation & calibration on spiral_outward
- Dominant language
- Python
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
Part of #11
**Blocked by:** #18 (needs the per-cycle tidy tables) _(native GitHub dependency is canonical; this line is a backup)_
Spec is fully decided in #14 — this ticket **implements and calibrates** it. No design decisions should be reopened here; if one is forced, say so rather than deciding it silently.
## Question
Implement the Split-1 index and segmentation per the #14 resolution, then calibrate the provisional knobs by eye on the reference trial.
**Implement** (on `cycle_gaze` / `cycle_meta` / `cycle_dots` from #18):
- `C_rev` = centroid(tpt 0..k-1), `P_lead` = dot at tpt k-1, both canvas.
- `u = (COM - C_rev)·(P_lead - C_rev) / |P_lead - C_rev|²`; `resid` = perpendicular distance, separate column.
- COM = trailing mean of `gx_canvas`/`gy_canvas` over `ma_window`, masked to `em_type=='Fixation' & gaze_valid & homography_valid & on_screen`; NaN when `< min_samples_in_window`.
- Degenerate-axis guard: `|P_lead - C_rev| / mean_radius(revealed) < axis_min_ratio` → `u = NaN` for the cycle, counted.
- Ternary labels `u < u_lo` → backward, `u > u_hi` → forward, else neutral; drop regions `< min_region_duration`.
**Calibrate** provisional defaults (`ma_window` ~150ms, `min_samples_in_window` ~30%, `u_lo`/`u_hi` 0.5/1.1, `min_region_duration` ~150ms) against:
- **`spiral_outward` (trial 6)** — primary, by-eye calibration.
- **`line` (trial 7)** — correctness check; `u` is 1-D there, so odd behaviour = bug, not mistuning.
`axis_min_ratio` = 0.25 is firm; expect exactly **1 of 240** cycles to trip it (`plus`, trial 9, k=13).
**Diagnostics to produce**: regions/cycle; region-duration distribution; fraction forward/backward/**neutral** (three-way denominator); `degenerate_axis_cycles` count; NaN-COM fraction; index + gaze overlay on both reference trials.
**Watch for**: `u_noise` ≈ 0.179 on `spiral_outward` (from ~1° gaze error over a 279px axis) must stay comfortably inside the neutral band — if the calibrated band narrows toward that, the segmentation is riding on noise and #14 needs revisiting.
**Resolution:** calibrated knob values + diagnostics + overlays on both reference trials, committed and runnable.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading the #14 resolution and the per-cycle tidy tables from #18, using cycle_gaze, cycle_meta, and cycle_dots as the implementation inputs. Run the reference trials spiral_outward (trial 6) and line (trial 7) while calibrating the stated knobs, then verify the required diagnostics, overlays, and the single degenerate-axis cycle on plus (trial 9, k=13). Done means calibrated values and diagnostics are committed and runnable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- data
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100