added ML data acquisition

README.md

@@ -89,6 +89,43 @@ median or smoothing filter is applied, and every received sample that meets the
 the target, gaze coordinates, pixel error, and whether gaze was on target. During
 every color trial, green is the target and red is the distractor.
 
+### Data collection for ML-based adaptive filtering
+
+Each run writes `results/gaze_exercises_<timestamp>.csv` plus a sidecar
+`..._meta.json` recording subject, session, screen, and distance metadata. Tag
+every recording with `--subject-id` and, when varying setup, `--session-tag`:
+
+```powershell
+python gaze_exercises.py --subject-id you --session-tag laptop_50cm --screen-diagonal 15.6 --viewing-distance 50
+python gaze_exercises.py --subject-id you --session-tag monitor_90cm --screen-diagonal 27 --viewing-distance 90
+```
+
+`--screen-diagonal` (inches) and `--viewing-distance` (cm) must match the
+physical setup for that recording — they drive the pixel-to-degree conversion
+used for both the logged error and velocity columns, so an incorrect value
+silently skews every derived feature in that session.
+
+CSV columns beyond the basic error metrics:
+
+- `confidence` — Pupil Capture's per-sample confidence (already thresholded
+  by `--confidence`, but the value itself is kept for weighting/filtering).
+- `velocity_px_s`, `velocity_deg_s` — instantaneous gaze speed between
+  consecutive samples; blank when the gap since the previous sample exceeds
+  0.5s (block/trial boundaries).
+- `accel_px_s2` — change in `velocity_px_s` between consecutive samples.
+- `dispersion_px` — spread (bounding-box width + height) of the last 5 raw
+  samples; low during fixation/pursuit, spikes during saccades.
+- `event_label` — coarse ground truth derived from task design: `saccade`
+  until gaze first lands within the hit radius of the trial's target, then
+  `fixation` (or always `pursuit` during the pursuit block). This is a block
+  design label, not a precise per-sample velocity-threshold classification —
+  refine saccade on/offset from `velocity_deg_s` during post-processing if
+  the paper needs tighter boundaries.
+
+`subject_id` and `session_id` (subject + recording timestamp) are included on
+every row so CSVs from different subjects, screens, and distances can be
+concatenated directly for training/evaluation.
+
 Visualize the newest result file with:
 
 ```powershell