hans / hans/dot-prediction

08 [task] Split-1 impl — index, segmentation & calibration on spiral_outward

Open
#19 0 comments 0 reactions 0 assignees View on GitHub
wayfinder:task
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.