feat(review): groups, time bins, keypoint distances and a statistics engine

src/glider/analysis/epochs.py

@@ -29,6 +29,7 @@
     "summarize",
     "threshold_text",
     "tidy_frame",
+    "time_bins",
     "wide_frame",
 ]
 
@@ -232,6 +233,35 @@ def tidy_frame(
     return pd.DataFrame.from_records(records, columns=columns)
 
 
+def _bin_edge(seconds: float, unit: float) -> str:
+    """``90`` s as ``1.5`` in minutes: whole numbers without a trailing ``.0``."""
+    return f"{seconds / unit:g}"
+
+
+def time_bins(start_s: float, end_s: float, bin_s: float) -> list[Epoch]:
+    """``[start_s, end_s)`` cut into consecutive bins of ``bin_s``, as epochs.
+
+    Bin edges sit on whole multiples of ``bin_s`` from zero (flow start, or the
+    first video frame), so minute 3 is the same stretch in every export
+    whatever span was asked for. The last bin is clipped to ``end_s`` and named
+    for what it covers. Labelled in minutes when the bin is a whole number of
+    them, in seconds otherwise.
+    """
+    if not bin_s > 0 or not end_s > start_s:
+        return []
+    unit, suffix = (60.0, "min") if float(bin_s) % 60 == 0 else (1.0, "s")
+    first = math.floor(start_s / bin_s + 1e-9)
+    bins = []
+    k = first
+    while k * bin_s < end_s - 1e-9:
+        lo, hi = max(k * bin_s, start_s), min((k + 1) * bin_s, end_s)
+        # A plain hyphen: an en dash reads as "–" in a CSV opened by Excel.
+        name = f"{_bin_edge(lo, unit)}-{_bin_edge(hi, unit)} {suffix}"
+        bins.append(Epoch(f"bin_{k - first + 1}", name, lo, hi))
+        k += 1
+    return bins
+
+
 def wide_frame(tidy: pd.DataFrame, metrics: list[str]) -> pd.DataFrame:
     """One row per session: ``session, group, <range>__<metric>…``.
 

src/glider/analysis/stats/__init__.py

@@ -0,0 +1,89 @@
+"""Statistics on the cohort's own numbers: the tests a paper needs. Qt-free.
+
+The input is the epoch table's tidy frame (:func:`glider.analysis.epochs.tidy_frame`):
+one row per animal per epoch, ``session, group, range, <metric>…``. The animal is
+always the unit -- one value per animal per cell, never frames.
+
+Every test returns a :class:`TestResult` that carries what a reader needs to
+trust it: the statistic and its degrees of freedom, the exact p, an effect size
+with a 95% CI, n per cell, the assumption checks, which animals were left out
+and why, and -- when the test was picked automatically -- the reason it was.
+
+* :func:`compare_groups` -- between subjects, one epoch: two groups or several.
+* :func:`compare_epochs` -- within subjects: the same animals in two or more epochs.
+* :func:`compare_mixed` -- group x epoch: the mixed (split-plot) ANOVA.
+* :func:`compare_trend` -- change across time bins: slopes, contrasts, first vs last.
+* :func:`run_between` / :func:`run_paired` -- the same on plain arrays.
+* :mod:`.corrections` -- Bonferroni, Holm and Benjamini-Hochberg.
+"""
+
+from glider.analysis.stats.compare import (
+    BETWEEN_TESTS,
+    ONE_SAMPLE_TESTS,
+    PAIRED_TESTS,
+    compare_epochs,
+    compare_groups,
+    dunn,
+    games_howell,
+    run_between,
+    run_one_sample,
+    run_paired,
+    tukey,
+)
+from glider.analysis.stats.corrections import adjust
+from glider.analysis.stats.frames import UNGROUPED, Dropped, between_cells, within_matrix
+from glider.analysis.stats.repeated import (
+    REPEATED_TESTS,
+    MixedResult,
+    Sphericity,
+    compare_mixed,
+    pairwise_within,
+    run_mixed,
+    run_repeated,
+    sphericity,
+)
+from glider.analysis.stats.result import TestResult
+from glider.analysis.stats.trend import (
+    GroupTrend,
+    TrendResult,
+    animal_slopes,
+    compare_trend,
+    polynomial_contrasts,
+    run_trend,
+    trend_contrasts,
+)
+
+__all__ = [
+    "BETWEEN_TESTS",
+    "ONE_SAMPLE_TESTS",
+    "PAIRED_TESTS",
+    "REPEATED_TESTS",
+    "MixedResult",
+    "Sphericity",
+    "UNGROUPED",
+    "Dropped",
+    "GroupTrend",
+    "TestResult",
+    "TrendResult",
+    "adjust",
+    "animal_slopes",
+    "between_cells",
+    "compare_epochs",
+    "compare_groups",
+    "compare_mixed",
+    "compare_trend",
+    "dunn",
+    "games_howell",
+    "pairwise_within",
+    "polynomial_contrasts",
+    "run_between",
+    "run_mixed",
+    "run_one_sample",
+    "run_paired",
+    "run_repeated",
+    "run_trend",
+    "sphericity",
+    "trend_contrasts",
+    "tukey",
+    "within_matrix",
+]