feat: add action_rate check and Cohort statistics docs - #40
Conversation
kstonekuan
left a comment
There was a problem hiding this comment.
Thanks @Sagar-024! This delivers the design from #24 exactly as agreed: raw action_rate_hz evidence in the check, cohort math as a documented DuckDB window pattern, and the corpus-relative caveat stated. The note that STDDEV over a single-row cohort returns NULL 'which is the correct answer' is a genuinely useful addition we did not ask for. Validated locally: quality gate, full suite (296 tests), and the docs link check all pass.
One semantic worth recording for posterity, not blocking: with multiple topics the check records the summed rate over the union span rather than a per-topic mean. That is the right aggregate for 'how fast is this rig acting overall', and the docstring plus PR description state the formula, so future readers will not be surprised. Merging.
Summary
Adds the
action_ratebuilt-in check and a "Cohort statistics" section in docs/CATALOG.md, per the design agreed in Discussion #24. That discussion is the design doc.The check records the raw per-episode message rate of the given action topics as
action_rate_hz. Evidence only, no verdict: n timestamps define n - 1 intervals, so the rate is intervals divided by the span across the selected topics.The docs section records the DuckDB window-function pattern for cohort math (z-score via
(value - AVG(value) OVER ()) / STDDEV(value) OVER (), plusPERCENT_RANK()), with the corpus-relative caveat: compute the window over the same filtered cohort you intend to cut.Validation
Checklist