SSM-JTK – Data & Calibration — Event detectors (reference) (2.8)

Purpose
Reference definitions for event-aware metrics used in training and reporting. These do not alter the deterministic evaluator; they provide audit-ready measurements.

Prereqs (utilities)
Use the same helpers across metrics:
wrap360(x) = x - 360*floor(x/360)
wrap180(d) = ((d + 180) % 360) - 180
unwrap(y) → make y continuous by adding/subtracting 360 as needed.
cusp_dist_deg(x) = min( (x % 30) , 30 - (x % 30) )
rasi(x) = floor( wrap360(x) / 30 ) (range 0..11)

Degree error (pointwise, then aggregate)
For daily sidereal angles (actual vs model):
err_deg[i] = | wrap180( L_model[i] - L_actual[i] ) |
Report: MAE_deg, P90_deg, MAX_deg, and (optionally) misclass_rate where a misclass is rasi(model) != rasi(actual).

Rāśi misclassification (day-level)
misclass[i] = 1{ rasi( L_model[i] ) != rasi( L_actual[i] ) }
Aggregate as a fraction over the TEST slice.

Cusp distance (degree proximity to 30° grid)
Compute daily distances to the nearest cusp and compare:
cusp_model[i] = cusp_dist_deg( L_model[i] )
cusp_actual[i] = cusp_dist_deg( L_actual[i] )
Report: cusp_dist_MAE_deg = mean( |cusp_model - cusp_actual| ).

30° crossings (timing; days)

  1. Work on unwrapped series y_model, y_actual.
  2. Find times where each series crosses multiples of 30° via linear interpolation.
  3. Pair predicted vs actual crossing times by nearest neighbor within ±60 days.
  4. For matched pairs, compute | t_cross_model - t_cross_actual |.
    Report: rasi_cross_MAE_days as the mean absolute timing error. If matched pairs = 0, report NaN.

Stations (timing; days)

  1. Compute speeds from unwrapped series via central differences (daily grid):
    v[i] = ( y[i+1] - y[i-1] ) / 2 (deg/day).
  2. Detect candidate stations as local minima of |v|; deduplicate within 2 days.
  3. Pair predicted vs actual station dates by nearest neighbor within ±90 days.
    Report: station_date_MAE_days as the mean absolute timing error (use NaN if no pairs).

Reporting conventions

  • Units: degrees for angle metrics; days for timing metrics.
  • Caps: crossings ±60 d, stations ±90 d.
  • Sparse events: if few/no events in a short window (e.g., slow outers), prefer longer spans or rely on cusp/station metrics.
  • NaN handling: use NaN for undefined aggregates (no matched pairs).

Navigation
Back: SSM-JTK – Data & Calibration — Calibration pseudocode (end-to-end) (2.7A)
Next: SSM-JTK – Data & Calibration — Outputs and manifest (2.9)