quantized-lab 0.8.0__py3-none-any.whl

quantized/calc/stats_survival.py

@@ -0,0 +1,261 @@
+"""Survival analysis: Kaplan-Meier, log-rank test, Cox PH model.
+
+GAP_PLAN #30 (stats extra) — survival methods via lifelines (MIT). Requires
+``pip install quantized[stats]``. Rows with any non-finite time/event are
+dropped (listwise deletion).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+__all__ = ["kaplan_meier", "logrank_test", "cox_proportional_hazards"]
+
+
+def _check_lifelines() -> None:
+    """Raise a clear error if lifelines is not installed."""
+    try:
+        import lifelines  # noqa: F401
+    except ImportError as exc:
+        raise RuntimeError(
+            "Survival methods require lifelines. Install with: pip install quantized[stats]"
+        ) from exc
+
+
+def kaplan_meier(
+    time: NDArray[np.float64],
+    event: NDArray[np.float64],
+) -> dict[str, Any]:
+    """Kaplan-Meier survival curve with Greenwood confidence intervals.
+
+    ``time`` is the follow-up duration (must be ≥ 0). ``event`` is the binary
+    event indicator (0 = censored, 1 = event). Returns the survival curve at
+    each unique event time, Greenwood CIs, the number at risk and events at
+    each time, and the median survival time (1st time where S(t) ≤ 0.5).
+    Rows with any non-finite values are dropped (listwise deletion).
+
+    Reference: Kaplan-Meier estimator via lifelines ``KaplanMeierFitter``.
+    """
+    _check_lifelines()
+    from lifelines import KaplanMeierFitter
+
+    tv = np.asarray(time, dtype=float).ravel()
+    ev = np.asarray(event, dtype=float).ravel()
+
+    if tv.size != ev.size:
+        raise ValueError(f"time length {tv.size} != event length {ev.size}")
+
+    # Listwise NaN deletion
+    keep = np.isfinite(tv) & np.isfinite(ev)
+    tv, ev = tv[keep], ev[keep]
+    n = tv.size
+
+    if n < 2:
+        raise ValueError("need at least 2 complete rows")
+
+    # Check time ≥ 0, event ∈ {0, 1}
+    if np.any(tv < 0.0):
+        raise ValueError("time must be non-negative")
+    if not np.all((ev == 0.0) | (ev == 1.0)):
+        raise ValueError("event must be binary (0/1)")
+
+    # Fit KM
+    kmf = KaplanMeierFitter()
+    kmf.fit(tv, ev, label="KM")
+
+    # Extract results at unique event times
+    survival_func = kmf.survival_function_
+    times = np.asarray(survival_func.index, dtype=float)
+    surv = np.asarray(survival_func.iloc[:, 0], dtype=float)
+
+    # Confidence intervals (lifelines computes 95% by default)
+    ci_lower = np.asarray(kmf.confidence_interval_survival_function_.iloc[:, 0], dtype=float)
+    ci_upper = np.asarray(kmf.confidence_interval_survival_function_.iloc[:, 1], dtype=float)
+
+    # Number at risk and events at each time
+    at_risk = np.asarray(kmf.event_table["at_risk"].values, dtype=float)
+    events = np.asarray(kmf.event_table["observed"].values, dtype=float)
+
+    # Median survival: 1st time where S(t) ≤ 0.5
+    median_time = float(kmf.median_survival_time_)
+    if np.isnan(median_time):
+        median_time = float("nan")
+
+    return {
+        "times": times,
+        "survival": surv,
+        "ciLow": ci_lower,
+        "ciHigh": ci_upper,
+        "atRisk": at_risk,
+        "events": events,
+        "medianSurvival": median_time,
+        "N": n,
+    }
+
+
+def logrank_test(
+    time1: NDArray[np.float64],
+    event1: NDArray[np.float64],
+    time2: NDArray[np.float64],
+    event2: NDArray[np.float64],
+) -> dict[str, Any]:
+    """Log-rank test comparing two survival curves.
+
+    Groups are indexed 1 (``time1``, ``event1``) and 2 (``time2``, ``event2``).
+    Returns the test statistic, chi-squared distribution with 1 dof, the
+    p-value, and the observed/expected events in each group. Rows with any
+    non-finite values are dropped (listwise deletion).
+
+    Reference: log-rank test via lifelines ``logrank_test``.
+    """
+    _check_lifelines()
+    from lifelines.statistics import logrank_test as logrank_test_fn
+
+    t1v = np.asarray(time1, dtype=float).ravel()
+    e1v = np.asarray(event1, dtype=float).ravel()
+    t2v = np.asarray(time2, dtype=float).ravel()
+    e2v = np.asarray(event2, dtype=float).ravel()
+
+    if t1v.size != e1v.size:
+        raise ValueError(f"group 1: time length {t1v.size} != event length {e1v.size}")
+    if t2v.size != e2v.size:
+        raise ValueError(f"group 2: time length {t2v.size} != event length {e2v.size}")
+
+    # Listwise NaN deletion per group
+    keep1 = np.isfinite(t1v) & np.isfinite(e1v)
+    keep2 = np.isfinite(t2v) & np.isfinite(e2v)
+    t1v, e1v = t1v[keep1], e1v[keep1]
+    t2v, e2v = t2v[keep2], e2v[keep2]
+
+    if t1v.size < 2 or t2v.size < 2:
+        raise ValueError("each group needs at least 2 complete rows")
+
+    # Check constraints
+    if np.any(t1v < 0.0) or np.any(t2v < 0.0):
+        raise ValueError("time must be non-negative")
+    if not (np.all((e1v == 0.0) | (e1v == 1.0)) and np.all((e2v == 0.0) | (e2v == 1.0))):
+        raise ValueError("event must be binary (0/1)")
+
+    # Fit
+    result = logrank_test_fn(t1v, t2v, e1v, e2v)
+
+    # Extract results
+    stat = float(result.test_statistic)
+    p_value = float(result.p_value)
+    obs1 = float(np.sum(e1v))
+    obs2 = float(np.sum(e2v))
+
+    return {
+        "statistic": stat,
+        "pValue": p_value,
+        "dof": 1.0,
+        "observedGroup1": obs1,
+        "observedGroup2": obs2,
+        "N1": t1v.size,
+        "N2": t2v.size,
+    }
+
+
+def cox_proportional_hazards(
+    time: NDArray[np.float64],
+    event: NDArray[np.float64],
+    predictors: list[NDArray[np.float64]] | NDArray[np.float64],
+) -> dict[str, Any]:
+    """Cox proportional-hazards model with inference.
+
+    ``time`` is follow-up duration, ``event`` is the binary event indicator.
+    ``predictors`` is a list of k same-length columns (or an (n, k) matrix).
+    Returns regression coefficients, standard errors, z-stats/p-values, 95%
+    CIs, concordance index, log-likelihood, and AIC. Rows with any non-finite
+    values are dropped (listwise deletion).
+
+    Requires lifelines (MIT).
+
+    Reference: Cox PH via lifelines ``CoxPHFitter``.
+    """
+    _check_lifelines()
+    import pandas as pd
+    from lifelines import CoxPHFitter
+
+    tv = np.asarray(time, dtype=float).ravel()
+    ev = np.asarray(event, dtype=float).ravel()
+
+    if tv.size != ev.size:
+        raise ValueError(f"time length {tv.size} != event length {ev.size}")
+
+    # Parse predictors
+    if isinstance(predictors, np.ndarray) and predictors.ndim == 2:
+        xmat = np.asarray(predictors, dtype=float)
+    else:
+        cols = [np.asarray(c, dtype=float).ravel() for c in predictors]
+        if len(cols) < 1:
+            raise ValueError("need at least one predictor")
+        if tv.size != cols[0].size:
+            raise ValueError(f"predictor column length {cols[0].size} != time length {tv.size}")
+        xmat = np.column_stack(cols)
+
+    n, k = xmat.shape
+
+    if k < 1:
+        raise ValueError("need at least 1 predictor")
+
+    # Listwise NaN deletion
+    keep = np.isfinite(tv) & np.isfinite(ev) & np.all(np.isfinite(xmat), axis=1)
+    tv, ev, xmat = tv[keep], ev[keep], xmat[keep]
+    n_clean = tv.size
+
+    if n_clean < k + 2:
+        raise ValueError(f"need at least {k + 2} complete rows for {k} predictors")
+
+    # Check constraints
+    if np.any(tv < 0.0):
+        raise ValueError("time must be non-negative")
+    if not np.all((ev == 0.0) | (ev == 1.0)):
+        raise ValueError("event must be binary (0/1)")
+
+    # Build DataFrame (lifelines wants column names)
+    cols_dict = {f"x{i}": xmat[:, i] for i in range(k)}
+    cols_dict["T"] = tv
+    cols_dict["E"] = ev
+    df = pd.DataFrame(cols_dict)
+
+    # Fit Cox model
+    cph = CoxPHFitter()
+    cph.fit(df, duration_col="T", event_col="E")
+
+    # Extract results. cph.params_/standard_errors_ are pandas Series (not
+    # ndarrays), so .values is safe here — unlike statsmodels' discrete-choice
+    # results (see stats_glm.py), which return bare ndarrays and broke on
+    # .values. cph.summary already carries correctly-computed z and two-sided
+    # p (verified against the lifelines rossi.csv reference: p=0.0474 for
+    # z=-1.983 etc.) — read them directly rather than recomputing/transforming.
+    coeffs = np.asarray(cph.params_.values, dtype=float)
+    se = np.asarray(cph.standard_errors_.values, dtype=float)
+    z_stats = np.asarray(cph.summary["z"].values, dtype=float)
+    p_values = np.asarray(cph.summary["p"].values, dtype=float)
+
+    # CIs on the linear (log-hazard / coefficient) scale — lifelines' summary
+    # already carries these directly ("coef lower/upper 95%"); no need to
+    # round-trip through the exponentiated hazard-ratio columns.
+    ci_low = np.asarray(cph.summary["coef lower 95%"].values, dtype=float)
+    ci_high = np.asarray(cph.summary["coef upper 95%"].values, dtype=float)
+
+    concordance = float(cph.concordance_index_)
+
+    return {
+        "coeffs": coeffs,
+        "se": se,
+        "zStats": z_stats,
+        "pValues": p_values,
+        "ciLow": ci_low,
+        "ciHigh": ci_high,
+        "concordanceIndex": concordance,
+        "logLikelihood": float(cph.log_likelihood_),
+        # CoxPHFitter is semi-parametric — .AIC_ raises StatError ("does not
+        # exist... you probably want .AIC_partial_"); use the partial AIC.
+        "AIC": float(cph.AIC_partial_),
+        "N": n_clean,
+    }

quantized/calc/stats_tests.py

@@ -0,0 +1,380 @@
+"""Nonparametric hypothesis tests + normality/variance assumption checks.
+
+Thin, typed wrappers around ``scipy.stats`` (BSD) returning uniform result
+dicts, in the style of ``calc.stats``. New capability beyond MATLAB parity
+(ORIGIN_GAP_PLAN #25 + the wrapper half of #26); validated against
+hand-derivable exact small-sample values in ``tests/test_calc_stats_tests.py``.
+
+All functions are pure: ndarrays in, plain dicts out. No FastAPI imports.
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+from scipy import stats as sps
+
+_ALTERNATIVES = ("two-sided", "less", "greater")
+
+
+def _check_alternative(alternative: str) -> str:
+    if alternative not in _ALTERNATIVES:
+        raise ValueError(f"alternative must be one of {_ALTERNATIVES}, got {alternative!r}")
+    return alternative
+
+
+def _clean(x: NDArray[np.float64]) -> NDArray[np.float64]:
+    x = np.asarray(x, dtype=float).ravel()
+    return x[np.isfinite(x)]
+
+
+def mann_whitney(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    alternative: str = "two-sided",
+) -> dict[str, Any]:
+    """Mann-Whitney U test (independent two-sample rank test).
+
+    Exact p-value for small samples without ties, normal approximation
+    otherwise (scipy ``method='auto'``). Reference: Conover, *Practical
+    Nonparametric Statistics*, 3rd ed., ch. 5.
+    """
+    x, y = _clean(x), _clean(y)
+    _check_alternative(alternative)
+    if x.size < 1 or y.size < 1:
+        raise ValueError("mann_whitney needs at least one observation per group")
+    res = sps.mannwhitneyu(x, y, alternative=alternative, method="auto")
+    return {
+        "U": float(res.statistic),
+        "p": float(res.pvalue),
+        "n1": int(x.size),
+        "n2": int(y.size),
+        "alternative": alternative,
+        "method": "Mann-Whitney U",
+    }
+
+
+def wilcoxon_signed_rank(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64] | None = None,
+    mu: float = 0.0,
+    alternative: str = "two-sided",
+) -> dict[str, Any]:
+    """Wilcoxon signed-rank test (paired two-sample, or one-sample vs ``mu``).
+
+    Zero differences are dropped (Wilcoxon's original treatment). Exact
+    p-value for small samples without ties. Reference: Conover ch. 5.7.
+    """
+    x = _clean(x)
+    _check_alternative(alternative)
+    if y is not None:
+        y = np.asarray(y, dtype=float).ravel()
+        if y.size != x.size:
+            raise ValueError("wilcoxon_signed_rank: x and y must be the same length")
+        d = x - y
+    else:
+        d = x - mu
+    d = d[np.isfinite(d)]
+    if not np.any(d != 0.0):
+        raise ValueError("wilcoxon_signed_rank: all differences are zero")
+    res = sps.wilcoxon(d, alternative=alternative, zero_method="wilcox", method="auto")
+    return {
+        "W": float(res.statistic),
+        "p": float(res.pvalue),
+        "n": int(np.count_nonzero(d)),
+        "alternative": alternative,
+        "method": "Wilcoxon signed-rank",
+    }
+
+
+def kruskal_wallis(groups: list[NDArray[np.float64]]) -> dict[str, Any]:
+    """Kruskal-Wallis H test (one-way ANOVA on ranks, k independent groups).
+
+    H is chi-squared distributed with k-1 degrees of freedom under H0.
+    Reference: Kruskal & Wallis, JASA 47 (1952) 583.
+    """
+    cleaned = [_clean(g) for g in groups]
+    if len(cleaned) < 2:
+        raise ValueError("kruskal_wallis needs at least 2 groups")
+    if any(g.size < 1 for g in cleaned):
+        raise ValueError("kruskal_wallis: every group needs at least one observation")
+    res = sps.kruskal(*cleaned)
+    return {
+        "H": float(res.statistic),
+        "p": float(res.pvalue),
+        "df": len(cleaned) - 1,
+        "n_groups": len(cleaned),
+        "N": int(sum(g.size for g in cleaned)),
+        "method": "Kruskal-Wallis H",
+    }
+
+
+def friedman(groups: list[NDArray[np.float64]]) -> dict[str, Any]:
+    """Friedman test (repeated measures on ranks; k treatments x n blocks).
+
+    Each entry of ``groups`` is one treatment measured over the same n
+    blocks (equal lengths required). Reference: Friedman, JASA 32 (1937) 675.
+    """
+    arrs = [np.asarray(g, dtype=float).ravel() for g in groups]
+    if len(arrs) < 3:
+        raise ValueError("friedman needs at least 3 treatments (scipy restriction)")
+    n = arrs[0].size
+    if n < 2 or any(a.size != n for a in arrs):
+        raise ValueError("friedman: all treatments need the same number (>=2) of blocks")
+    res = sps.friedmanchisquare(*arrs)
+    return {
+        "chi2": float(res.statistic),
+        "p": float(res.pvalue),
+        "df": len(arrs) - 1,
+        "n_treatments": len(arrs),
+        "n_blocks": n,
+        "method": "Friedman chi-square",
+    }
+
+
+def sign_test(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64] | None = None,
+    mu: float = 0.0,
+    alternative: str = "two-sided",
+) -> dict[str, Any]:
+    """Sign test (paired or one-sample vs ``mu``) via exact binomial test.
+
+    Ignores zero differences; p from Binomial(n_pos + n_neg, 1/2).
+    ``alternative='greater'`` tests median > mu (i.e. an excess of positive
+    differences). Reference: Conover ch. 3.4.
+    """
+    x = _clean(x)
+    _check_alternative(alternative)
+    if y is not None:
+        y = np.asarray(y, dtype=float).ravel()
+        if y.size != x.size:
+            raise ValueError("sign_test: x and y must be the same length")
+        d = x - y
+    else:
+        d = x - mu
+    d = d[np.isfinite(d) & (d != 0.0)]
+    if d.size == 0:
+        raise ValueError("sign_test: no nonzero differences")
+    n_pos = int(np.count_nonzero(d > 0))
+    n = int(d.size)
+    res = sps.binomtest(n_pos, n, 0.5, alternative=alternative)
+    return {
+        "n_pos": n_pos,
+        "n_neg": n - n_pos,
+        "n": n,
+        "p": float(res.pvalue),
+        "alternative": alternative,
+        "method": "sign test (exact binomial)",
+    }
+
+
+def shapiro_wilk(x: NDArray[np.float64]) -> dict[str, Any]:
+    """Shapiro-Wilk normality test. Valid for 3 <= n <= 5000.
+
+    Reference: Shapiro & Wilk, Biometrika 52 (1965) 591.
+    """
+    x = _clean(x)
+    if x.size < 3:
+        raise ValueError("shapiro_wilk needs at least 3 observations")
+    if x.size > 5000:
+        raise ValueError("shapiro_wilk p-value unreliable above n=5000; subsample first")
+    res = sps.shapiro(x)
+    return {
+        "W": float(res.statistic),
+        "p": float(res.pvalue),
+        "N": int(x.size),
+        "method": "Shapiro-Wilk",
+    }
+
+
+def anderson_darling(x: NDArray[np.float64]) -> dict[str, Any]:
+    """Anderson-Darling normality test (parameters estimated from the data).
+
+    Returns the A^2 statistic with critical values at fixed significance
+    levels instead of a p-value (Stephens' tabulation, as in scipy).
+    Reference: Stephens, JASA 69 (1974) 730.
+    """
+    x = _clean(x)
+    if x.size < 3:
+        raise ValueError("anderson_darling needs at least 3 observations")
+    # keep the classic critical-value-table behavior (scipy >= 1.17 warns
+    # pending a p-value API migration; revisit when we require that API)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", FutureWarning)
+        res = sps.anderson(x, dist="norm")
+    crit = np.asarray(res.critical_values, dtype=float)
+    sig = np.asarray(res.significance_level, dtype=float)
+    a2 = float(res.statistic)
+    return {
+        "A2": a2,
+        "critical_values": crit.tolist(),
+        "significance_levels_pct": sig.tolist(),
+        "reject_at_5pct": bool(a2 > crit[sig == 5.0][0]) if np.any(sig == 5.0) else None,
+        "N": int(x.size),
+        "method": "Anderson-Darling (normal)",
+    }
+
+
+def levene(groups: list[NDArray[np.float64]], center: str = "median") -> dict[str, Any]:
+    """Levene test for equal variances across k groups.
+
+    ``center='median'`` is the robust Brown-Forsythe variant (default);
+    ``'mean'`` is the classic Levene test. Reference: Brown & Forsythe,
+    JASA 69 (1974) 364.
+    """
+    if center not in ("median", "mean", "trimmed"):
+        raise ValueError("center must be 'median', 'mean', or 'trimmed'")
+    cleaned = [_clean(g) for g in groups]
+    if len(cleaned) < 2 or any(g.size < 2 for g in cleaned):
+        raise ValueError("levene needs >=2 groups with >=2 observations each")
+    res = sps.levene(*cleaned, center=center)
+    return {
+        "W": float(res.statistic),
+        "p": float(res.pvalue),
+        "center": center,
+        "n_groups": len(cleaned),
+        "method": "Brown-Forsythe" if center == "median" else "Levene",
+    }
+
+
+def ks_normal(
+    x: NDArray[np.float64],
+    loc: float | None = None,
+    scale: float | None = None,
+) -> dict[str, Any]:
+    """One-sample Kolmogorov-Smirnov test against a normal distribution.
+
+    When ``loc``/``scale`` are omitted they are estimated from the sample
+    (mean, ddof=1 std); the p-value is then only approximate (Lilliefors
+    situation) and flagged via ``params_estimated``. Prefer Shapiro-Wilk
+    for pure normality checks; use this when loc/scale are known a priori.
+    """
+    x = _clean(x)
+    if x.size < 3:
+        raise ValueError("ks_normal needs at least 3 observations")
+    estimated = loc is None or scale is None
+    loc_v = float(np.mean(x)) if loc is None else float(loc)
+    scale_v = float(np.std(x, ddof=1)) if scale is None else float(scale)
+    if scale_v <= 0:
+        raise ValueError("ks_normal: scale must be positive")
+    # frozen-cdf form: the string form ("norm" + args) trips a broken
+    # ndtr fast path in some scipy releases
+    res = sps.kstest(x, sps.norm(loc=loc_v, scale=scale_v).cdf)
+    return {
+        "D": float(res.statistic),
+        "p": float(res.pvalue),
+        "loc": loc_v,
+        "scale": scale_v,
+        "params_estimated": estimated,
+        "N": int(x.size),
+        "method": "Kolmogorov-Smirnov (normal)",
+    }
+
+
+def ks_two_sample(
+    x: NDArray[np.float64],
+    y: NDArray[np.float64],
+    alternative: str = "two-sided",
+) -> dict[str, Any]:
+    """Two-sample Kolmogorov-Smirnov test (same-distribution null)."""
+    x, y = _clean(x), _clean(y)
+    _check_alternative(alternative)
+    if x.size < 1 or y.size < 1:
+        raise ValueError("ks_two_sample needs at least one observation per sample")
+    res = sps.ks_2samp(x, y, alternative=alternative)
+    return {
+        "D": float(res.statistic),
+        "p": float(res.pvalue),
+        "n1": int(x.size),
+        "n2": int(y.size),
+        "alternative": alternative,
+        "method": "Kolmogorov-Smirnov (two-sample)",
+    }
+
+
+def recommend_test(
+    groups: list[NDArray[np.float64]],
+    *,
+    paired: bool = False,
+    alpha: float = 0.05,
+) -> dict[str, Any]:
+    """The "which test?" decision tree (ORIGIN_GAP_PLAN #26 chooser logic).
+
+    Checks per-group normality (Shapiro-Wilk) and, for >= 2 groups, equal
+    variances (Brown-Forsythe), then recommends the parametric test when the
+    assumptions hold and the nonparametric analogue otherwise. Returns the
+    recommendation (name + /api/stats endpoint), the checks it ran, and
+    plain-language reasons — so a UI can show its work.
+    """
+    if not groups:
+        raise ValueError("recommend_test needs at least one group")
+    cleaned = [_clean(g) for g in groups]
+    if any(g.size < 3 for g in cleaned):
+        raise ValueError("every group needs at least 3 observations")
+    if paired:
+        if len(cleaned) != 2:
+            raise ValueError("paired analysis needs exactly 2 groups")
+        if cleaned[0].size != cleaned[1].size:
+            raise ValueError("paired groups must have the same length")
+
+    reasons: list[str] = []
+    checks: dict[str, Any] = {"alpha": alpha}
+
+    # Normality: for a paired design the DIFFERENCES are what must be normal.
+    if paired:
+        targets = [cleaned[0] - cleaned[1]]
+        labels = ["differences"]
+    else:
+        targets = cleaned
+        labels = [f"group {i}" for i in range(len(cleaned))]
+    norm_ps: list[float] = []
+    for lab, t in zip(labels, targets, strict=True):
+        p = shapiro_wilk(t)["p"] if t.size <= 5000 else float("nan")
+        norm_ps.append(p)
+        if np.isnan(p):
+            reasons.append(f"{lab}: n>5000, Shapiro skipped (assumed normal by CLT)")
+    checks["shapiro_p"] = norm_ps
+    all_normal = all(np.isnan(p) or p >= alpha for p in norm_ps)
+    if not all_normal:
+        bad = [labels[i] for i, p in enumerate(norm_ps) if not np.isnan(p) and p < alpha]
+        reasons.append(f"non-normal at alpha={alpha}: {', '.join(bad)}")
+    else:
+        reasons.append("normality not rejected for any group (Shapiro-Wilk)")
+
+    equal_var = True
+    if not paired and len(cleaned) >= 2:
+        lev = levene(cleaned)
+        checks["levene_p"] = lev["p"]
+        equal_var = lev["p"] >= alpha
+        reasons.append(
+            f"equal variances {'not rejected' if equal_var else 'REJECTED'} "
+            f"(Brown-Forsythe p={lev['p']:.3g})"
+        )
+
+    k = len(cleaned)
+    if k == 1:
+        rec = ("one-sample t-test", "/api/stats/ttest") if all_normal else (
+            "Wilcoxon signed-rank (one-sample)", "/api/stats/wilcoxon")
+    elif paired:
+        rec = ("paired t-test", "/api/stats/ttest") if all_normal else (
+            "Wilcoxon signed-rank (paired)", "/api/stats/wilcoxon")
+    elif k == 2:
+        rec = ("Welch two-sample t-test", "/api/stats/ttest") if all_normal else (
+            "Mann-Whitney U", "/api/stats/mann-whitney")
+    else:
+        rec = ("one-way ANOVA (+ Tukey HSD post-hoc)", "/api/stats/anova") if (
+            all_normal and equal_var) else ("Kruskal-Wallis H", "/api/stats/kruskal")
+
+    return {
+        "recommendation": rec[0],
+        "endpoint": rec[1],
+        "parametric": all_normal and (equal_var or paired or k == 1 or k == 2),
+        "n_groups": k,
+        "paired": paired,
+        "checks": checks,
+        "reasons": reasons,
+    }