cmhstats 0.1.0__py3-none-any.whl

cmhstats/__init__.py

@@ -0,0 +1,28 @@
+"""cmhstats: Cochran-Mantel-Haenszel statistics for Python, validated against SAS and R.
+
+>>> import numpy as np, cmhstats
+>>> migraine = np.array([[[16, 12], [11, 16]], [[5, 7], [20, 19]]])  # Treatment x Response x Gender
+>>> res = cmhstats.cmh_test(migraine)
+>>> round(res.general_association.statistic, 4)
+8.3052
+"""
+
+from ._api import CMHResult, CMHStatistic, MantelHaenszelResult, cmh_test, mantelhaen_test
+from ._input import StratifiedTable, as_stratified_table
+from ._twobytwo import Estimate, HomogeneityTest, breslow_day
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "CMHResult",
+    "CMHStatistic",
+    "Estimate",
+    "HomogeneityTest",
+    "MantelHaenszelResult",
+    "StratifiedTable",
+    "as_stratified_table",
+    "breslow_day",
+    "cmh_test",
+    "mantelhaen_test",
+    "__version__",
+]

cmhstats/_api.py

@@ -0,0 +1,338 @@
+"""Public entry points.
+
+* :func:`cmh_test` mirrors SAS ``PROC FREQ ... / CMH``.
+* :func:`mantelhaen_test` mirrors R's ``stats::mantelhaen.test`` (including its
+  default continuity correction for 2 x 2 x K tables), so results can be
+  checked against either reference without guessing at option differences.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+import numpy as np
+from scipy import stats
+
+from ._core import SAS_LABELS, STAT_ORDER, SCORE_TYPES, generalized_cmh
+from ._input import StratifiedTable, as_stratified_table
+from ._twobytwo import Estimate, HomogeneityTest, two_by_two_measures
+
+
+@dataclass(frozen=True)
+class CMHStatistic:
+    """One of the three CMH statistics."""
+
+    name: str
+    alternative: str
+    statistic: float
+    df: int
+    pvalue: float
+
+    def __post_init__(self):
+        object.__setattr__(self, "statistic", float(self.statistic))
+        object.__setattr__(self, "pvalue", float(self.pvalue))
+        object.__setattr__(self, "df", int(self.df))
+
+
+@dataclass(frozen=True)
+class CMHResult:
+    """Everything SAS PROC FREQ prints for the CMH option.
+
+    The 2 x 2 x K fields (odds ratios, relative risks, Breslow-Day) are None
+    unless the table has exactly two rows and two columns.
+    """
+
+    correlation: CMHStatistic
+    row_mean_scores: CMHStatistic
+    general_association: CMHStatistic
+    scores: str
+    n_total: float
+    row_levels: tuple
+    col_levels: tuple
+    strata_levels: tuple
+    strata_excluded: tuple
+    row_scores: np.ndarray
+    col_scores: np.ndarray
+    common_odds_ratio: tuple[Estimate, Estimate] | None = None
+    relative_risk_col1: tuple[Estimate, Estimate] | None = None
+    relative_risk_col2: tuple[Estimate, Estimate] | None = None
+    breslow_day: HomogeneityTest | None = None
+    breslow_day_tarone: HomogeneityTest | None = None
+    mantel_fleiss: float | None = None
+    notes: tuple[str, ...] = field(default=())
+
+    @property
+    def statistics(self) -> tuple[CMHStatistic, CMHStatistic, CMHStatistic]:
+        return (self.correlation, self.row_mean_scores, self.general_association)
+
+    def to_frame(self):
+        """The CMH statistics as a pandas DataFrame (SAS layout)."""
+        import pandas as pd
+
+        return pd.DataFrame(
+            [
+                {
+                    "Statistic": i + 1,
+                    "Alternative Hypothesis": s.alternative,
+                    "DF": s.df,
+                    "Value": s.statistic,
+                    "Prob": s.pvalue,
+                }
+                for i, s in enumerate(self.statistics)
+            ]
+        ).set_index("Statistic")
+
+    def estimates_frame(self):
+        """Common odds ratio and relative risks as a DataFrame (2 x 2 x K only)."""
+        import pandas as pd
+
+        if self.common_odds_ratio is None:
+            raise ValueError("common odds ratios and relative risks need a 2 x 2 x K table")
+        rows = []
+        for group in (self.common_odds_ratio, self.relative_risk_col1, self.relative_risk_col2):
+            for e in group:  # type: ignore[union-attr]
+                rows.append(
+                    {"Statistic": e.measure, "Method": e.method, "Value": e.value,
+                     f"{e.conf_level:.0%} Lower CL": e.lower, f"{e.conf_level:.0%} Upper CL": e.upper}
+                )
+        return pd.DataFrame(rows)
+
+    def summary(self, digits: int = 4) -> str:
+        """Plain-text output in the layout of SAS PROC FREQ."""
+        f = lambda v: "." if v is None or (isinstance(v, float) and math.isnan(v)) else f"{v:.{digits}f}"
+        p = lambda v: "." if math.isnan(v) else ("<.0001" if v < 1e-4 else f"{v:.4f}")
+        score_name = {"table": "Table", "rank": "Rank", "ridit": "Ridit", "modridit": "Modified Ridit"}
+        lines = [f"Cochran-Mantel-Haenszel Statistics (Based on {score_name[self.scores]} Scores)", ""]
+        lines.append(f"{'Statistic':<10}{'Alternative Hypothesis':<26}{'DF':>4}{'Value':>12}{'Prob':>10}")
+        lines.append("-" * 62)
+        for i, s in enumerate(self.statistics, 1):
+            lines.append(f"{i:<10}{s.alternative:<26}{s.df:>4}{f(s.statistic):>12}{p(s.pvalue):>10}")
+        if self.common_odds_ratio is not None:
+            cl = int(round(self.common_odds_ratio[0].conf_level * 100))
+            lines += ["", "Common Odds Ratio and Relative Risks", ""]
+            lines.append(f"{'Statistic':<26}{'Method':<17}{'Value':>9}{cl:>9}% CL")
+            lines.append("-" * 70)
+            for group in (self.common_odds_ratio, self.relative_risk_col1, self.relative_risk_col2):
+                for e in group:  # type: ignore[union-attr]
+                    lines.append(
+                        f"{e.measure:<26}{e.method:<17}{f(e.value):>9}{f(e.lower):>10}{f(e.upper):>10}"
+                    )
+            for test in (self.breslow_day, self.breslow_day_tarone):
+                if test is not None:
+                    lines += ["", f"{test.name} Test for Homogeneity of Odds Ratios",
+                              f"  Chi-Square  {f(test.statistic)}", f"  DF          {test.df}",
+                              f"  Pr > ChiSq  {p(test.pvalue)}"]
+        lines += ["", f"Total Sample Size = {self.n_total:g}"]
+        if self.strata_excluded:
+            lines.append(
+                f"Strata with fewer than 2 observations (no information): {len(self.strata_excluded)}"
+            )
+        if self.mantel_fleiss is not None and self.mantel_fleiss < 5:
+            lines.append(
+                f"WARNING: Mantel-Fleiss criterion = {self.mantel_fleiss:.4g} < 5; "
+                "the chi-square approximation may be poor."
+            )
+        for note in self.notes:
+            lines.append(f"Note: {note}")
+        return "\n".join(lines)
+
+    def __str__(self) -> str:
+        return self.summary()
+
+
+def cmh_test(
+    table: Any = None,
+    *,
+    data: Any = None,
+    x: str | None = None,
+    y: str | None = None,
+    strata: str | Sequence[str] | None = None,
+    weight: str | None = None,
+    scores: str = "table",
+    row_scores: Sequence[float] | None = None,
+    col_scores: Sequence[float] | None = None,
+    order: str = "internal",
+    conf_level: float = 0.95,
+) -> CMHResult:
+    """Cochran-Mantel-Haenszel statistics, matching SAS ``PROC FREQ / CMH``.
+
+    Parameters
+    ----------
+    table
+        Array of counts with shape ``(R, C, K)``: rows = X, columns = Y,
+        last axis = strata.  A 2-D array is treated as a single stratum.
+    data, x, y, strata, weight
+        Alternatively, a long-format DataFrame and column names.  ``strata``
+        may be a list of columns, whose combinations form the strata (as in
+        SAS ``tables A*B*X*Y``).  ``weight`` is SAS's WEIGHT variable.
+    scores
+        ``"table"`` (default), ``"rank"``, ``"ridit"`` or ``"modridit"``, as
+        the SAS ``SCORES=`` option.  Rank-type scores are computed within each
+        stratum; ``scores="modridit"`` with two rows gives van Elteren's test.
+    row_scores, col_scores
+        Custom table scores, one per level in level order.
+    order
+        ``"internal"`` (sorted values, SAS default) or ``"data"`` (order of
+        first appearance) for DataFrame input.
+    conf_level
+        Confidence level for the 2 x 2 x K estimates.
+
+    Returns
+    -------
+    CMHResult
+        ``.correlation``, ``.row_mean_scores`` and ``.general_association``,
+        plus odds ratios, relative risks and the Breslow-Day test for
+        2 x 2 x K tables.  ``print(result)`` gives SAS-style output.
+
+    Notes
+    -----
+    * Strata with a single observation carry no information and are skipped.
+    * If the covariance matrix of a statistic is singular, the statistic is
+      NaN and a warning is issued (SAS prints it as missing).
+    * No continuity correction is applied, as in SAS.  Use
+      :func:`mantelhaen_test` to reproduce R's corrected default.
+    """
+    if scores not in SCORE_TYPES:
+        raise ValueError(f"scores must be one of {SCORE_TYPES}, got {scores!r}")
+    if scores != "table" and (row_scores is not None or col_scores is not None):
+        raise ValueError("custom row_scores/col_scores can only be used with scores='table'")
+
+    st: StratifiedTable = as_stratified_table(
+        table, data=data, x=x, y=y, strata=strata, weight=weight, order=order,
+        row_scores=row_scores, col_scores=col_scores,
+    )
+    core = generalized_cmh(st.counts, st.row_table_scores, st.col_table_scores, scores)
+    stats_out = {
+        key: CMHStatistic(key, SAS_LABELS[key], *core[key]) for key in STAT_ORDER
+    }
+    extra: dict[str, Any] = {}
+    if st.counts.shape[:2] == (2, 2):
+        extra = two_by_two_measures(st.counts, conf_level)
+        if extra["mantel_fleiss"] < 5:
+            warnings.warn(
+                f"Mantel-Fleiss criterion is {extra['mantel_fleiss']:.4g} (< 5): "
+                "the chi-square approximation may not be valid",
+                stacklevel=2,
+            )
+
+    return CMHResult(
+        correlation=stats_out["correlation"],
+        row_mean_scores=stats_out["row_mean_scores"],
+        general_association=stats_out["general_association"],
+        scores=scores,
+        n_total=float(st.counts.sum()),
+        row_levels=st.row_levels,
+        col_levels=st.col_levels,
+        strata_levels=st.strata_levels,
+        strata_excluded=tuple(st.strata_levels[h] for h in core["_skipped"]),
+        row_scores=st.row_table_scores,
+        col_scores=st.col_table_scores,
+        notes=st.notes,
+        **extra,
+    )
+
+
+@dataclass(frozen=True)
+class MantelHaenszelResult:
+    """Result in the shape of R's ``htest`` object from ``mantelhaen.test``."""
+
+    statistic: float
+    df: int
+    pvalue: float
+    method: str
+    alternative: str
+    estimate: float | None = None
+    conf_int: tuple[float, float] | None = None
+    conf_level: float | None = None
+
+    def __str__(self) -> str:
+        lines = [self.method, "",
+                 f"Mantel-Haenszel X-squared = {self.statistic:.6g}, df = {self.df}, "
+                 f"p-value = {self.pvalue:.4g}"]
+        if self.estimate is not None and self.conf_int is not None:
+            lines.append(
+                f"{self.conf_level:.0%} confidence interval: "
+                f"{self.conf_int[0]:.6g} {self.conf_int[1]:.6g}"
+            )
+            lines.append(f"common odds ratio: {self.estimate:.6g}")
+        return "\n".join(lines)
+
+
+def mantelhaen_test(
+    table: Any,
+    *,
+    alternative: str = "two.sided",
+    correct: bool = True,
+    conf_level: float = 0.95,
+) -> MantelHaenszelResult:
+    """Port of R's ``stats::mantelhaen.test`` (asymptotic version).
+
+    Defaults match R: for 2 x 2 x K tables a continuity correction is applied
+    (``correct=True``) and the Mantel-Haenszel common odds ratio is returned
+    with Robins-Breslow-Greenland limits.  For larger tables the generalized
+    statistic (general association, no correction) is returned.
+
+    Like R, this raises an error when a stratum has fewer than two
+    observations; :func:`cmh_test` skips such strata instead.  ``exact=TRUE``
+    is not implemented.
+    """
+    arr = np.asarray(table, dtype=float)
+    if arr.ndim != 3:
+        raise ValueError("'table' must be a 3-dimensional array")
+    if np.any(arr < 0) or not np.all(np.isfinite(arr)):
+        raise ValueError("'table' must contain finite, non-negative counts")
+    I, J, K = arr.shape
+    if K < 2:
+        raise ValueError("'table' must be a 3-dimensional array with at least 2 strata (R requirement)")
+    if I < 2 or J < 2:
+        raise ValueError("each dimension in table must be >= 2")
+    n = arr.sum(axis=(0, 1))
+    if np.any(n < 2):
+        raise ValueError("sample size in each stratum must be > 1")
+    if alternative not in ("two.sided", "less", "greater"):
+        raise ValueError("alternative must be 'two.sided', 'less' or 'greater'")
+
+    if (I, J) == (2, 2):
+        s_x = arr.sum(axis=1)  # row totals, shape (2, K)
+        s_y = arr.sum(axis=0)  # column totals, shape (2, K)
+        delta = float((arr[0, 0, :] - s_x[0] * s_y[0] / n).sum())
+        yates = 0.5 if (correct and abs(delta) >= 0.5) else 0.0
+        var = (s_x[0] * s_x[1] * s_y[0] * s_y[1] / (n * n * (n - 1))).sum()
+        stat = (abs(delta) - yates) ** 2 / var if var > 0 else float("nan")  # R gives NaN
+        if math.isnan(stat):
+            pval = float("nan")
+        elif alternative == "two.sided":
+            pval = float(stats.chi2.sf(stat, 1))
+        else:
+            z = math.copysign(math.sqrt(stat), delta)
+            pval = float(stats.norm.cdf(z) if alternative == "less" else stats.norm.sf(z))
+        a, b, c, d = arr[0, 0, :], arr[0, 1, :], arr[1, 0, :], arr[1, 1, :]
+        s_diag = (a * d / n).sum()
+        s_offd = (b * c / n).sum()
+        est = s_diag / s_offd if s_offd > 0 else (float("inf") if s_diag > 0 else float("nan"))
+        sd = math.sqrt(
+            ((a + d) * a * d / n**2).sum() / (2 * s_diag**2)
+            + (((a + d) * b * c + (b + c) * a * d) / n**2).sum() / (2 * s_diag * s_offd)
+            + ((b + c) * b * c / n**2).sum() / (2 * s_offd**2)
+        ) if s_diag > 0 and s_offd > 0 else float("nan")
+        if alternative == "less":
+            ci = (0.0, est * math.exp(stats.norm.ppf(conf_level) * sd))
+        elif alternative == "greater":
+            ci = (est * math.exp(stats.norm.ppf(1 - conf_level) * sd), float("inf"))
+        else:
+            q = stats.norm.ppf((1 - conf_level) / 2)
+            ci = (est * math.exp(q * sd), est * math.exp(-q * sd))
+        method = "Mantel-Haenszel chi-squared test " + (
+            "with continuity correction" if yates else "without continuity correction"
+        )
+        return MantelHaenszelResult(float(stat), 1, pval, method, alternative, float(est),
+                                    (float(ci[0]), float(ci[1])), conf_level)
+
+    core = generalized_cmh(arr, np.arange(1, I + 1.0), np.arange(1, J + 1.0), "table")
+    stat, df, pval = core["general_association"]
+    if math.isnan(stat):
+        raise np.linalg.LinAlgError("covariance matrix is singular (R's qr.solve fails here too)")
+    return MantelHaenszelResult(stat, df, pval, "Cochran-Mantel-Haenszel test", "two.sided")

cmhstats/_core.py

@@ -0,0 +1,152 @@
+"""Generalized Cochran-Mantel-Haenszel statistics (Landis, Heyman & Koch, 1978).
+
+Notation follows the SAS PROC FREQ documentation.  For stratum h with an
+R x C table n_h and n_h observations:
+
+    G   = sum_h B_h (vec(n_h) - vec(m_h))
+    V_G = sum_h B_h Var(vec(n_h) | H0) B_h'
+    Q   = G' V_G^{-1} G          ~ chi-square(rank B_h) under H0
+
+with B_h = C_h (x) R_h and the multiple hypergeometric covariance
+
+    Var(vec(n_h) | H0) = n_h^2 / (n_h - 1) * (D_pc - pc pc') (x) (D_pr - pr pr')
+
+Rather than building the RC x RC Kronecker products we use the identities
+(C (x) R) vec(D) = vec(R D C')  and  (C (x) R)(A (x) B)(C (x) R)' = (CAC') (x) (RBR'),
+which give the same numbers with far less memory.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+from scipy import linalg, stats
+
+SCORE_TYPES = ("table", "rank", "ridit", "modridit")
+
+# rank tolerance used to decide that V_G is singular (SAS then reports missing)
+_SINGULAR_RTOL = 1e-10
+
+
+def stratum_scores(margin: np.ndarray, kind: str, table_scores: np.ndarray) -> np.ndarray:
+    """Scores for one margin of one stratum (SAS SCORES= option).
+
+    Rank-type scores are midranks computed from the stratum's own margin, so
+    tied observations share the midpoint of the ranks they occupy.  With
+    ``modridit`` and two rows, the row mean scores statistic is van Elteren's
+    stratified Wilcoxon test.
+    """
+    if kind == "table":
+        return table_scores
+    n = margin.sum()
+    before = np.cumsum(margin) - margin
+    rank = before + (margin + 1.0) / 2.0
+    if kind == "rank":
+        return rank
+    if kind == "ridit":
+        return rank / n
+    if kind == "modridit":
+        return rank / (n + 1.0)
+    raise ValueError(f"scores must be one of {SCORE_TYPES}, got {kind!r}")
+
+
+def _contrast(m: int) -> np.ndarray:
+    """SAS contrast matrix [I_{m-1}, -J_{m-1}]."""
+    return np.hstack([np.eye(m - 1), -np.ones((m - 1, 1))])
+
+
+def _centered_quadratic(M: np.ndarray, p: np.ndarray) -> np.ndarray:
+    """Compute M (D_p - p p') M' without the cancellation of the naive formula.
+
+    (D_p - p p') annihilates constant vectors, so each row of M can be centered
+    at its p-weighted mean first; the result is then an explicit weighted
+    cross-product and stays positive semi-definite in floating point.
+    """
+    Mc = M - (M @ p)[:, None]
+    return (Mc * p) @ Mc.T
+
+
+def _quadratic_form(G: np.ndarray, V: np.ndarray) -> float:
+    """Return G' V^{-1} G, or NaN if V is singular (SAS sets the statistic to missing)."""
+    V = (V + V.T) / 2.0
+    eig = np.linalg.eigvalsh(V)
+    top = eig[-1] if eig.size else 0.0
+    if top <= 0 or eig[0] <= _SINGULAR_RTOL * top:
+        return float("nan")
+    try:
+        cho = linalg.cho_factor(V)
+        return float(G @ linalg.cho_solve(cho, G))
+    except linalg.LinAlgError:  # pragma: no cover - guarded by the eigenvalue check
+        return float("nan")
+
+
+STAT_ORDER = ("correlation", "row_mean_scores", "general_association")
+SAS_LABELS = {
+    "correlation": "Nonzero Correlation",
+    "row_mean_scores": "Row Mean Scores Differ",
+    "general_association": "General Association",
+}
+
+
+def generalized_cmh(
+    counts: np.ndarray,
+    row_table_scores: np.ndarray,
+    col_table_scores: np.ndarray,
+    scores: str = "table",
+) -> dict:
+    """Compute the three CMH statistics for an R x C x K table of counts.
+
+    Strata with fewer than two observations are skipped: with a single
+    observation the observed table equals its expectation and the covariance
+    is zero, so the stratum carries no information (its covariance formula is
+    0 * n^2/(n-1), undefined at n = 1).
+    """
+    if scores not in SCORE_TYPES:
+        raise ValueError(f"scores must be one of {SCORE_TYPES}, got {scores!r}")
+    R, C, K = counts.shape
+    dfs = {"correlation": 1, "row_mean_scores": R - 1, "general_association": (R - 1) * (C - 1)}
+    G = {k: np.zeros(d) for k, d in dfs.items()}
+    V = {k: np.zeros((d, d)) for k, d in dfs.items()}
+    Rc, Cc = _contrast(R), _contrast(C)
+    used, skipped = [], []
+
+    for h in range(K):
+        n = counts[:, :, h]
+        N = n.sum()
+        if N < 2:
+            skipped.append(h)
+            continue
+        used.append(h)
+        rs, cs = n.sum(axis=1), n.sum(axis=0)
+        pr, pc = rs / N, cs / N
+        D = n - np.outer(rs, cs) / N
+        c = N * N / (N - 1.0)
+        a = stratum_scores(rs, scores, row_table_scores)[None, :]
+        b = stratum_scores(cs, scores, col_table_scores)[None, :]
+        mats = {
+            "correlation": (a, b),
+            "row_mean_scores": (Rc, b),
+            "general_association": (Rc, Cc),
+        }
+        for key, (Rh, Ch) in mats.items():
+            G[key] += (Rh @ D @ Ch.T).ravel(order="F")
+            V[key] += c * np.kron(_centered_quadratic(Ch, pc), _centered_quadratic(Rh, pr))
+
+    out = {}
+    singular = []
+    for key in STAT_ORDER:
+        q = _quadratic_form(G[key], V[key]) if used else float("nan")
+        if np.isnan(q):
+            singular.append(SAS_LABELS[key])
+        p = float(stats.chi2.sf(q, dfs[key])) if not np.isnan(q) else float("nan")
+        out[key] = (q, dfs[key], p)
+    if singular:
+        warnings.warn(
+            "covariance matrix is singular for: " + ", ".join(singular)
+            + "; statistic set to NaN (SAS reports it as missing)",
+            stacklevel=3,
+        )
+    out["_used"] = used
+    out["_skipped"] = skipped
+    return out

cmhstats/_input.py

@@ -0,0 +1,280 @@
+"""Turn user input (an array or a long-format DataFrame) into an R x C x K table.
+
+The conventions here follow SAS PROC FREQ, because SAS output is the usual
+reference point in clinical reporting:
+
+* ``tables K * X * Y`` in SAS means X defines the rows, Y the columns and K the
+  strata.  An array input therefore has shape ``(R, C, K)``, which is also the
+  layout R's ``mantelhaen.test`` expects.
+* Levels are ordered by their unformatted values (SAS ``ORDER=INTERNAL``):
+  numbers ascending, strings in code-point order.  ``order="data"`` keeps the
+  order of first appearance (SAS ``ORDER=DATA``).  An ordered pandas
+  ``Categorical`` keeps its category order.
+* Table scores are the numeric level values for numeric variables and the
+  positions 1, 2, 3, ... for character variables.
+* Observations with a missing value or a zero weight are excluded, as SAS does
+  by default.  Levels that never occur are dropped.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+from typing import Any, Sequence
+
+import numpy as np
+
+
+@dataclass(frozen=True)
+class StratifiedTable:
+    """An R x C x K table of counts plus the labels and table scores of its levels."""
+
+    counts: np.ndarray
+    row_levels: tuple
+    col_levels: tuple
+    strata_levels: tuple
+    row_table_scores: np.ndarray
+    col_table_scores: np.ndarray
+    notes: tuple[str, ...] = field(default=())
+
+    @property
+    def shape(self) -> tuple[int, int, int]:
+        return self.counts.shape  # type: ignore[return-value]
+
+
+def _is_numeric_kind(values: np.ndarray) -> bool:
+    return values.dtype.kind in "biuf"
+
+
+def _ordered_levels(series: Any, order: str) -> tuple[list, np.ndarray | None]:
+    """Return the observed levels of a pandas Series in the requested order,
+    and numeric table scores if the variable is numeric."""
+    import pandas as pd
+
+    if isinstance(series.dtype, pd.CategoricalDtype):
+        observed = set(series.dropna().unique().tolist())
+        levels = [c for c in series.cat.categories.tolist() if c in observed]
+        cats = np.asarray(series.cat.categories)
+        numeric = _is_numeric_kind(cats)
+    else:
+        uniques = pd.unique(series.dropna())
+        numeric = _is_numeric_kind(np.asarray(uniques))
+        if order == "data":
+            levels = list(uniques)
+        elif numeric:
+            levels = sorted(uniques.tolist())
+        else:
+            try:
+                levels = sorted(uniques.tolist())
+            except TypeError:  # mixed types: fall back to string order
+                levels = sorted(uniques.tolist(), key=str)
+    scores = np.asarray(levels, dtype=float) if numeric else None
+    return levels, scores
+
+
+def _from_dataframe(
+    data: Any,
+    x: str,
+    y: str,
+    strata: str | Sequence[str] | None,
+    weight: str | None,
+    order: str,
+) -> StratifiedTable:
+    import pandas as pd
+
+    if order not in ("internal", "data"):
+        raise ValueError("order must be 'internal' or 'data'")
+    strata_cols: list[str]
+    if strata is None:
+        strata_cols = []
+    elif isinstance(strata, str):
+        strata_cols = [strata]
+    else:
+        strata_cols = list(strata)
+    cols = [x, y, *strata_cols] + ([weight] if weight is not None else [])
+    missing_cols = [c for c in cols if c not in data.columns]
+    if missing_cols:
+        raise KeyError(f"columns not found in data: {missing_cols}")
+
+    df = data[cols]
+    notes: list[str] = []
+    keep = df.notna().all(axis=1)
+    n_missing = int((~keep).sum())
+    if n_missing:
+        notes.append(f"{n_missing} observation(s) with missing values excluded")
+    df = df[keep]
+
+    if weight is not None:
+        w = pd.to_numeric(df[weight], errors="raise").to_numpy(dtype=float)
+        if np.any(w < 0):
+            raise ValueError("weights must be non-negative")
+        if not np.all(np.isfinite(w)):
+            raise ValueError("weights must be finite")
+        nonzero = w > 0
+        if (~nonzero).any():
+            notes.append(f"{int((~nonzero).sum())} observation(s) with zero weight excluded")
+        df = df[nonzero]
+        w = w[nonzero]
+    else:
+        w = np.ones(len(df), dtype=float)
+
+    if len(df) == 0:
+        raise ValueError("no observations left after excluding missing values and zero weights")
+
+    row_levels, row_scores = _ordered_levels(df[x], order)
+    col_levels, col_scores = _ordered_levels(df[y], order)
+
+    row_index = {lvl: i for i, lvl in enumerate(row_levels)}
+    col_index = {lvl: j for j, lvl in enumerate(col_levels)}
+    ri = df[x].map(row_index).to_numpy(dtype=int)
+    ci = df[y].map(col_index).to_numpy(dtype=int)
+
+    if strata_cols:
+        per_col = [_ordered_levels(df[s], order)[0] for s in strata_cols]
+        codes = []
+        for s, lv in zip(strata_cols, per_col):
+            idx = {v: i for i, v in enumerate(lv)}
+            codes.append(df[s].map(idx).to_numpy(dtype=int))
+        keys = list(zip(*codes))
+        unique_keys = sorted(set(keys))
+        key_index = {k: h for h, k in enumerate(unique_keys)}
+        si = np.array([key_index[k] for k in keys], dtype=int)
+        if len(strata_cols) == 1:
+            strata_levels = tuple(per_col[0][k[0]] for k in unique_keys)
+        else:
+            strata_levels = tuple(
+                tuple(per_col[c][k[c]] for c in range(len(strata_cols))) for k in unique_keys
+            )
+    else:
+        si = np.zeros(len(df), dtype=int)
+        strata_levels = ("(all)",)
+
+    counts = np.zeros((len(row_levels), len(col_levels), len(strata_levels)), dtype=float)
+    np.add.at(counts, (ri, ci, si), w)
+
+    if row_scores is None:
+        row_scores = np.arange(1, len(row_levels) + 1, dtype=float)
+    if col_scores is None:
+        col_scores = np.arange(1, len(col_levels) + 1, dtype=float)
+
+    return StratifiedTable(
+        counts=counts,
+        row_levels=tuple(row_levels),
+        col_levels=tuple(col_levels),
+        strata_levels=strata_levels,
+        row_table_scores=row_scores,
+        col_table_scores=col_scores,
+        notes=tuple(notes),
+    )
+
+
+def _from_array(table: Any) -> StratifiedTable:
+    arr = np.asarray(table, dtype=float)
+    if arr.ndim == 2:
+        arr = arr[:, :, np.newaxis]
+    if arr.ndim != 3:
+        raise ValueError("table must be a 2-D (R x C) or 3-D (R x C x K) array of counts")
+    if not np.all(np.isfinite(arr)):
+        raise ValueError("table must contain only finite counts")
+    if np.any(arr < 0):
+        raise ValueError("table must not contain negative counts")
+    R, C, K = arr.shape
+    return StratifiedTable(
+        counts=arr.copy(),
+        row_levels=tuple(range(1, R + 1)),
+        col_levels=tuple(range(1, C + 1)),
+        strata_levels=tuple(range(1, K + 1)),
+        row_table_scores=np.arange(1, R + 1, dtype=float),
+        col_table_scores=np.arange(1, C + 1, dtype=float),
+    )
+
+
+def _drop_unused(st: StratifiedTable, warn: bool) -> StratifiedTable:
+    """Drop empty strata and levels with a zero total over the whole table.
+
+    SAS never sees such levels because it builds the table from the data.
+    Keeping them would make the covariance matrix singular.
+    """
+    counts = st.counts
+    notes = list(st.notes)
+    keep_k = counts.sum(axis=(0, 1)) > 0
+    keep_r = counts.sum(axis=(1, 2)) > 0
+    keep_c = counts.sum(axis=(0, 2)) > 0
+    if not keep_k.any():
+        raise ValueError("the table contains no observations")
+    dropped = []
+    if (~keep_k).any():
+        dropped.append(f"{int((~keep_k).sum())} empty stratum/strata")
+    if (~keep_r).any():
+        dropped.append(f"{int((~keep_r).sum())} row level(s) with zero total")
+    if (~keep_c).any():
+        dropped.append(f"{int((~keep_c).sum())} column level(s) with zero total")
+    if dropped:
+        msg = "dropped " + ", ".join(dropped)
+        notes.append(msg)
+        if warn and ((~keep_r).any() or (~keep_c).any()):
+            warnings.warn(msg + " (SAS never sees unobserved levels)", stacklevel=4)
+    counts = counts[np.ix_(keep_r, keep_c, keep_k)]
+    return StratifiedTable(
+        counts=counts,
+        row_levels=tuple(v for v, k in zip(st.row_levels, keep_r) if k),
+        col_levels=tuple(v for v, k in zip(st.col_levels, keep_c) if k),
+        strata_levels=tuple(v for v, k in zip(st.strata_levels, keep_k) if k),
+        row_table_scores=st.row_table_scores[keep_r],
+        col_table_scores=st.col_table_scores[keep_c],
+        notes=tuple(notes),
+    )
+
+
+def as_stratified_table(
+    table: Any = None,
+    *,
+    data: Any = None,
+    x: str | None = None,
+    y: str | None = None,
+    strata: str | Sequence[str] | None = None,
+    weight: str | None = None,
+    order: str = "internal",
+    row_scores: Sequence[float] | None = None,
+    col_scores: Sequence[float] | None = None,
+) -> StratifiedTable:
+    """Build a :class:`StratifiedTable` from an array or from a DataFrame."""
+    if (table is None) == (data is None):
+        raise ValueError("pass either `table` (array of counts) or `data` (DataFrame), not both")
+    if data is not None:
+        if x is None or y is None:
+            raise ValueError("`x` and `y` column names are required with `data`")
+        st = _from_dataframe(data, x, y, strata, weight, order)
+        from_array = False
+    else:
+        if any(v is not None for v in (x, y, strata, weight)):
+            raise ValueError("`x`, `y`, `strata` and `weight` only apply with `data`")
+        st = _from_array(table)
+        from_array = True
+
+    if row_scores is not None or col_scores is not None:
+        rs = st.row_table_scores if row_scores is None else np.asarray(row_scores, dtype=float)
+        cs = st.col_table_scores if col_scores is None else np.asarray(col_scores, dtype=float)
+        if rs.shape != (len(st.row_levels),):
+            raise ValueError(f"row_scores must have length {len(st.row_levels)}")
+        if cs.shape != (len(st.col_levels),):
+            raise ValueError(f"col_scores must have length {len(st.col_levels)}")
+        if not (np.all(np.isfinite(rs)) and np.all(np.isfinite(cs))):
+            raise ValueError("scores must be finite")
+        st = StratifiedTable(
+            counts=st.counts,
+            row_levels=st.row_levels,
+            col_levels=st.col_levels,
+            strata_levels=st.strata_levels,
+            row_table_scores=rs,
+            col_table_scores=cs,
+            notes=st.notes,
+        )
+
+    st = _drop_unused(st, warn=from_array)
+    R, C, _ = st.counts.shape
+    if R < 2 or C < 2:
+        raise ValueError(
+            f"need at least 2 observed row levels and 2 observed column levels, got {R} x {C}"
+        )
+    return st

cmhstats/_twobytwo.py

@@ -0,0 +1,243 @@
+"""Estimates and tests that only apply to 2 x 2 x K tables.
+
+These reproduce what SAS PROC FREQ prints with the CMH (and BDT) options:
+
+* Mantel-Haenszel common odds ratio, with Robins-Breslow-Greenland limits
+* logit (Woolf) common odds ratio
+* Mantel-Haenszel common relative risks for column 1 and column 2, with
+  Greenland-Robins limits
+* logit common relative risks for column 1 and column 2
+* Breslow-Day test for homogeneity of odds ratios, optionally with Tarone's
+  adjustment
+* the Mantel-Fleiss criterion for the chi-square approximation
+
+Row 1 is compared with row 2 throughout, as in SAS ("Row1/Row2").
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+from scipy import stats
+
+
+@dataclass(frozen=True)
+class Estimate:
+    """A point estimate with confidence limits."""
+
+    measure: str
+    method: str
+    value: float
+    lower: float
+    upper: float
+    conf_level: float
+
+    def __post_init__(self):
+        for name in ("value", "lower", "upper", "conf_level"):
+            object.__setattr__(self, name, float(getattr(self, name)))
+
+
+@dataclass(frozen=True)
+class HomogeneityTest:
+    """A chi-square test for homogeneity of odds ratios across strata."""
+
+    name: str
+    statistic: float
+    df: int
+    pvalue: float
+
+
+def _z(conf_level: float) -> float:
+    if not 0 < conf_level < 1:
+        raise ValueError("conf_level must be between 0 and 1")
+    return float(stats.norm.ppf(1 - (1 - conf_level) / 2))
+
+
+def _cells(counts: np.ndarray):
+    counts = np.asarray(counts, dtype=float)
+    counts = counts[:, :, counts.sum(axis=(0, 1)) > 0]  # empty strata carry nothing
+    a, b = counts[0, 0, :], counts[0, 1, :]
+    c, d = counts[1, 0, :], counts[1, 1, :]
+    return a, b, c, d, a + b + c + d
+
+
+def _safe_div(num: float, den: float) -> float:
+    if den == 0:
+        return float("nan") if num == 0 else float("inf")
+    return num / den
+
+
+def mh_odds_ratio(counts: np.ndarray, conf_level: float = 0.95) -> Estimate:
+    """Mantel-Haenszel common odds ratio with Robins-Breslow-Greenland limits."""
+    a, b, c, d, n = _cells(counts)
+    R = a * d / n
+    S = b * c / n
+    P = (a + d) / n
+    Q = (b + c) / n
+    sR, sS = R.sum(), S.sum()
+    est = _safe_div(sR, sS)
+    if sR > 0 and sS > 0:
+        var = (
+            (P * R).sum() / (2 * sR**2)
+            + (P * S + Q * R).sum() / (2 * sR * sS)
+            + (Q * S).sum() / (2 * sS**2)
+        )
+        z = _z(conf_level)
+        se = math.sqrt(var)
+        lo, hi = est * math.exp(-z * se), est * math.exp(z * se)
+    else:
+        lo = hi = float("nan")
+    return Estimate("Odds Ratio", "Mantel-Haenszel", est, lo, hi, conf_level)
+
+
+def _mh_relative_risk(counts: np.ndarray, column: int, conf_level: float) -> Estimate:
+    a, b, c, d, n = _cells(counts)
+    if column == 1:
+        x1, x2 = a, c  # events in column 1 for rows 1 and 2
+    else:
+        x1, x2 = b, d
+    n1, n2 = a + b, c + d
+    m = x1 + x2  # column total
+    num = (x1 * n2 / n).sum()
+    den = (x2 * n1 / n).sum()
+    est = _safe_div(num, den)
+    if num > 0 and den > 0:
+        var = ((n1 * n2 * m - x1 * x2 * n) / n**2).sum() / (num * den)
+        z = _z(conf_level)
+        se = math.sqrt(var)
+        lo, hi = est * math.exp(-z * se), est * math.exp(z * se)
+    else:
+        lo = hi = float("nan")
+    return Estimate(f"Relative Risk (Column {column})", "Mantel-Haenszel", est, lo, hi, conf_level)
+
+
+def _logit_pooled(log_est: np.ndarray, var: np.ndarray, measure: str, conf_level: float) -> Estimate:
+    z = _z(conf_level)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        w = 1.0 / var
+        sw = float(w.sum())
+        mean = float((w * log_est).sum() / sw)
+    if not (np.isfinite(mean) and np.isfinite(sw) and sw > 0):
+        # a stratum with zero variance (e.g. every observation in one outcome) makes
+        # the inverse-variance weights undefined
+        nan = float("nan")
+        return Estimate(measure, "Logit", nan, nan, nan, conf_level)
+    est = math.exp(mean)
+    half = z / math.sqrt(sw)
+    return Estimate(measure, "Logit", est, est * math.exp(-half), est * math.exp(half), conf_level)
+
+
+def logit_odds_ratio(counts: np.ndarray, conf_level: float = 0.95) -> Estimate:
+    """Logit (Woolf) common odds ratio.
+
+    As in SAS, 0.5 is added to every cell of a stratum that has a zero cell.
+    """
+    a, b, c, d, _ = (x.astype(float).copy() for x in _cells(counts))
+    zero = (a == 0) | (b == 0) | (c == 0) | (d == 0)
+    for arr in (a, b, c, d):
+        arr[zero] += 0.5
+    with np.errstate(divide="ignore", invalid="ignore"):
+        log_or = np.log(a * d / (b * c))
+        var = 1 / a + 1 / b + 1 / c + 1 / d
+    return _logit_pooled(log_or, var, "Odds Ratio", conf_level)
+
+
+def _logit_relative_risk(counts: np.ndarray, column: int, conf_level: float) -> Estimate:
+    a, b, c, d, _ = (x.astype(float).copy() for x in _cells(counts))
+    x1, x2 = (a, c) if column == 1 else (b, d)
+    zero = (x1 == 0) | (x2 == 0)
+    for arr in (a, b, c, d):
+        arr[zero] += 0.5
+    x1, x2 = (a, c) if column == 1 else (b, d)
+    n1, n2 = a + b, c + d
+    with np.errstate(divide="ignore", invalid="ignore"):
+        p1, p2 = x1 / n1, x2 / n2
+        log_rr = np.log(p1 / p2)
+        var = (1 - p1) / x1 + (1 - p2) / x2
+    return _logit_pooled(log_rr, var, f"Relative Risk (Column {column})", conf_level)
+
+
+def _expected_a(or_mh: float, n1: float, n2: float, m1: float) -> float:
+    """E(n11 | OR) for one stratum: the root of a(n2 - m1 + a) = OR (n1 - a)(m1 - a)
+    that lies inside the support of n11."""
+    lo, hi = max(0.0, m1 - n2), min(n1, m1)
+    A = 1.0 - or_mh
+    B = n2 - m1 + or_mh * (n1 + m1)
+    Cq = -or_mh * n1 * m1
+    if abs(A) < 1e-12:
+        return -Cq / B
+    disc = math.sqrt(max(B * B - 4 * A * Cq, 0.0))
+    # numerically stable pair of roots
+    q = -0.5 * (B + math.copysign(disc, B))
+    roots = [q / A, Cq / q] if q != 0 else [(-B + disc) / (2 * A), (-B - disc) / (2 * A)]
+    tol = 1e-9 * max(1.0, hi)
+    for r in roots:
+        if lo - tol <= r <= hi + tol:
+            return min(max(r, lo), hi)
+    raise RuntimeError("no admissible root for the Breslow-Day expected count")  # pragma: no cover
+
+
+def breslow_day(counts: np.ndarray, tarone: bool = False) -> HomogeneityTest | None:
+    """Breslow-Day test (optionally Breslow-Day-Tarone) for a 2 x 2 x K table.
+
+    Strata with a zero row or column are left out of the sum, as in SAS.
+    Returns None when the test is not defined (fewer than two usable strata,
+    or a zero / infinite Mantel-Haenszel odds ratio).
+    """
+    counts = np.asarray(counts, dtype=float)
+    if counts.ndim != 3 or counts.shape[:2] != (2, 2):
+        raise ValueError("Breslow-Day test needs a 2 x 2 x K table")
+    or_mh = mh_odds_ratio(counts).value
+    if not np.isfinite(or_mh) or or_mh <= 0:
+        return None
+    a, b, c, d, _ = _cells(counts)
+    n1, n2, m1, m2 = a + b, c + d, a + c, b + d
+    ok = (n1 > 0) & (n2 > 0) & (m1 > 0) & (m2 > 0)
+    if ok.sum() < 2:
+        return None
+    q = 0.0
+    dev_sum = 0.0
+    var_sum = 0.0
+    for h in np.flatnonzero(ok):
+        e = _expected_a(or_mh, n1[h], n2[h], m1[h])
+        cells = (e, n1[h] - e, m1[h] - e, n2[h] - m1[h] + e)
+        v = 1.0 / sum(1.0 / x for x in cells)
+        dev = a[h] - e
+        q += dev * dev / v
+        dev_sum += dev
+        var_sum += v
+    if tarone:
+        q -= dev_sum * dev_sum / var_sum
+    df = int(ok.sum()) - 1
+    name = "Breslow-Day-Tarone" if tarone else "Breslow-Day"
+    return HomogeneityTest(name, float(q), df, float(stats.chi2.sf(q, df)))
+
+
+def mantel_fleiss(counts: np.ndarray) -> float:
+    """Mantel-Fleiss criterion; SAS warns when it is below 5."""
+    a, b, c, d, n = _cells(counts)
+    n1, n2, m1 = a + b, c + d, a + c
+    m11 = n1 * m1 / n
+    lower = np.maximum(0.0, n1 - (b + d))
+    upper = np.minimum(m1, n1)
+    return float(min(m11.sum() - lower.sum(), upper.sum() - m11.sum()))
+
+
+def two_by_two_measures(counts: np.ndarray, conf_level: float = 0.95) -> dict:
+    """All of the 2 x 2 x K output of SAS's CMH option in one dictionary."""
+    return {
+        "common_odds_ratio": (mh_odds_ratio(counts, conf_level), logit_odds_ratio(counts, conf_level)),
+        "relative_risk_col1": (
+            _mh_relative_risk(counts, 1, conf_level),
+            _logit_relative_risk(counts, 1, conf_level),
+        ),
+        "relative_risk_col2": (
+            _mh_relative_risk(counts, 2, conf_level),
+            _logit_relative_risk(counts, 2, conf_level),
+        ),
+        "breslow_day": breslow_day(counts, tarone=False),
+        "breslow_day_tarone": breslow_day(counts, tarone=True),
+        "mantel_fleiss": mantel_fleiss(counts),
+    }

cmhstats-0.1.0.dist-info/METADATA

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: cmhstats
+Version: 0.1.0
+Summary: Cochran-Mantel-Haenszel statistics for Python, validated against SAS PROC FREQ and R
+Author: Isha Bhatia
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Isha0206/cmhstats
+Project-URL: Validation, https://github.com/Isha0206/cmhstats/blob/main/docs/validation.md
+Project-URL: Changelog, https://github.com/Isha0206/cmhstats/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Isha0206/cmhstats/issues
+Keywords: cochran-mantel-haenszel,cmh,clinical-trials,biostatistics,contingency-table,sas,van-elteren,breslow-day
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: scipy>=1.8
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == "pandas"
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Requires-Dist: pandas>=1.5; extra == "test"
+Requires-Dist: statsmodels>=0.14; extra == "test"
+Dynamic: license-file
+
+# cmhstats
+
+[![PyPI](https://img.shields.io/pypi/v/cmhstats)](https://pypi.org/project/cmhstats/)
+[![Python](https://img.shields.io/pypi/pyversions/cmhstats)](https://pypi.org/project/cmhstats/)
+[![tests](https://github.com/Isha0206/cmhstats/actions/workflows/tests.yml/badge.svg)](https://github.com/Isha0206/cmhstats/actions/workflows/tests.yml)
+
+Cochran-Mantel-Haenszel (CMH) statistics for Python that reproduce SAS `PROC FREQ / CMH` and R's `mantelhaen.test`, with the equivalence tests to show it.
+
+Python's existing options cover parts of this. `statsmodels.stats.contingency_tables.StratifiedTable` handles 2 x 2 x K tables well. What was missing is the generalized R x C x K analysis that clinical efficacy tables use: the three SAS statistics (nonzero correlation, row mean scores, general association) with table, rank, ridit or modified ridit scores, plus the full set of 2 x 2 x K estimates in one place. The [PHUSE CAMIS](https://psiaims.github.io/CAMIS/) comparison project documents CMH for R and SAS but has no Python entry.
+
+## What it does
+
+```python
+import cmhstats
+
+# long-format data, as you would give PROC FREQ: tables SITEID * TRTP * AVAL / cmh;
+res = cmhstats.cmh_test(data=adcibc, x="TRTP", y="AVAL", strata="SITEID")
+print(res)
+```
+
+```
+Cochran-Mantel-Haenszel Statistics (Based on Table Scores)
+
+Statistic Alternative Hypothesis      DF       Value      Prob
+--------------------------------------------------------------
+1         Nonzero Correlation          1      0.0854    0.7701
+2         Row Mean Scores Differ       2      2.4763    0.2899
+3         General Association          8      7.0339    0.5330
+
+Total Sample Size = 231
+Strata with fewer than 2 observations (no information): 1
+```
+
+These are the SAS numbers for CAMIS scenario 9, the sparse 17-site case that `vcdExtra::CMHtest` cannot compute.
+
+| Feature | SAS `PROC FREQ` option | `cmhstats` |
+|---|---|---|
+| Correlation, row mean scores, general association statistics | `CMH` | `cmh_test()` |
+| Table, rank, ridit, modified ridit scores (within strata) | `SCORES=` | `scores=` |
+| Van Elteren test | `CMH2 SCORES=MODRIDIT` | `scores="modridit"`, `.row_mean_scores` |
+| Mantel-Haenszel and logit common odds ratio, with CIs | `CMH` (2 x 2 x K) | `.common_odds_ratio` |
+| Mantel-Haenszel and logit relative risks, columns 1 and 2 | `CMH` (2 x 2 x K) | `.relative_risk_col1`, `.relative_risk_col2` |
+| Breslow-Day test, Tarone adjustment | `CMH`, `BDT` | `.breslow_day`, `.breslow_day_tarone` |
+| Mantel-Fleiss criterion warning | `CMH` | warning + `.mantel_fleiss` |
+| WEIGHT variable, multiple strata variables | `WEIGHT`, `tables A*B*X*Y` | `weight=`, `strata=[...]` |
+| R's `mantelhaen.test`, including its default continuity correction | — | `mantelhaen_test()` |
+
+## Install
+
+```bash
+pip install cmhstats
+pip install "cmhstats[pandas]"   # with DataFrame support
+```
+
+Requires Python 3.9+ (tested on 3.9 and 3.13), NumPy and SciPy. pandas is needed only for DataFrame input.
+
+## Usage
+
+**Array input.** Shape `(R, C, K)`: rows are X, columns are Y, the last axis is the strata. This is SAS's `tables K*X*Y` and R's `mantelhaen.test(x)` layout.
+
+```python
+import numpy as np, cmhstats
+
+# SAS documentation example: Treatment x Response, stratified by Gender
+migraine = np.zeros((2, 2, 2))
+migraine[:, :, 0] = [[16, 11], [5, 20]]   # female
+migraine[:, :, 1] = [[12, 16], [7, 19]]   # male
+
+res = cmhstats.cmh_test(migraine)
+res.general_association        # CMHStatistic(statistic=8.3052..., df=1, pvalue=0.00395...)
+res.common_odds_ratio[0]       # Mantel-Haenszel 3.3132 (1.4456, 7.5934)
+res.breslow_day                # 1.4929, df 1, p 0.2218
+res.to_frame()                 # SAS-layout DataFrame
+```
+
+**DataFrame input.** Level ordering and table scores follow SAS: levels are sorted by value (`ORDER=INTERNAL`), numeric variables use their values as table scores, and character variables use positions 1, 2, 3, ... Observations with missing values or zero weight are excluded.
+
+```python
+res = cmhstats.cmh_test(data=df, x="TRTP", y="AVAL", strata=["SITEGR1", "SEX"],
+                        weight="COUNT", scores="modridit")
+```
+
+**Matching R instead of SAS.** `mantelhaen_test()` is a port of `stats::mantelhaen.test`. For 2 x 2 x K tables it applies R's continuity correction by default, which SAS does not.
+
+```python
+cmhstats.mantelhaen_test(migraine)                  # R default: corrected, 7.1983
+cmhstats.mantelhaen_test(migraine, correct=False)   # = SAS: 8.3052
+```
+
+## Validation
+
+All 1,178 tests run without R or SAS. The R reference results are committed under `tests/fixtures/`, and `validation/generate_r_reference.R` regenerates them. To run them from a clone:
+
+```bash
+pip install -e ".[test]"
+pytest
+```
+
+* **SAS:** every number in the published output for three sources agrees at the 4 decimals SAS prints: the SAS documentation's Migraine example (CMH statistics, all six common odds ratio and relative risk estimates with CIs, Breslow-Day), the SexualFun 4 x 4 example, and all six CAMIS scenarios on the CDISC pilot ADCIBC data.
+* **R:** 142 tables in 25 shapes, from 2 x 2 x 2 to 6 x 2 x 10, including sparse ones and ones with single-observation strata. All three statistics agree with vcdExtra's formulas for all four score types, and with `mantelhaen.test`, `vcdExtra::CMHtest` and `coin::cmh_test` wherever those run, to a relative tolerance of 1e-8. The 2 x 2 x K estimates and Breslow-Day test agree with `epiR::epi.2by2` to 1e-7.
+* **Independent identities:** Pearson chi-square, Spearman correlation and Kruskal-Wallis (single stratum), van Elteren's test written from its definition, and `statsmodels` for 2 x 2 x K.
+
+See [docs/validation.md](https://github.com/Isha0206/cmhstats/blob/main/docs/validation.md) for the full report, including what is *not* yet confirmed against SAS directly.
+
+## Findings along the way
+
+* **`vcdExtra::CMHtest` fails on sparse data because of per-stratum tests, not because the pooled statistic is singular.** It inverts each stratum's own covariance before pooling, so one site that lacks a treatment arm stops the analysis. In CAMIS scenario 9, sites 706 and 707 trigger this, and removing the single-subject site 702 does not help. Using vcdExtra's own formulas without the per-stratum step reproduces SAS exactly. vcdExtra failed on 46 of the 142 reference tables.
+* **The `cmh` package on PyPI (1.0.1) returns wrong values for tables larger than 2 x 2.** It flattens the observed-minus-expected vector in row-major order but builds the covariance for column-major order. On the `Satisfaction` example from R's documentation it reports 12.53 instead of 10.20.
+* **CAMIS lists df = 1 for the row mean scores and general association statistics in scenario 2.** The p-value printed alongside (0.2891) is the chi-square(2) tail of 2.4820, so df = 2 is correct.
+* **SAS and R sort character levels differently.** SAS puts `"65-80"` before `"<65"`, while R's locale-aware sort does the opposite. With table scores, this changes the correlation and row mean scores statistics.
+
+## Scope and limitations
+
+Not implemented yet: exact tests (R's `exact=TRUE`, SAS's Zelen and exact common odds ratio limits), common risk differences (`COMMONRISKDIFF`), and SAS's formatted-value ordering (`ORDER=FORMATTED`). This is an independent open-source implementation that has not been qualified for regulated use. A risk-based assessment would still be needed before using it in a submission.
+
+## License
+
+MIT

cmhstats-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+cmhstats/__init__.py,sha256=_ZEyeP8_49Dju7XUT2x11N_ULIFpUbLWPX4HAJKJVpM,801
+cmhstats/_api.py,sha256=N83hjRNnQMHjkA3WOofePbOlzRPYgQzsvjeFxveAEdU,14214
+cmhstats/_core.py,sha256=Ak6JaKNkR8zQWAE0T9QBvfBSRxu_hXZAsy6P-oa8r20,5426
+cmhstats/_input.py,sha256=-16PVkyGQHE3xySDxe8oY3lrpBML5gFXhWwDA8D5Z4E,10591
+cmhstats/_twobytwo.py,sha256=0zA5H4zQ7mzbqlyqPVx6aW_SNtiW76ATAnm2vUShjQk,8689
+cmhstats-0.1.0.dist-info/licenses/LICENSE,sha256=0YjPLFsGI9wD-42fvIal2X2jEs3Dws09DUTx-6txTAE,1068
+cmhstats-0.1.0.dist-info/METADATA,sha256=C1wfhuGA6UN5SG8INAdIzZ-w75NbSL5EaeSi5tNZq0c,8985
+cmhstats-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+cmhstats-0.1.0.dist-info/top_level.txt,sha256=gkSTguhK_6Wc8iqmc6Ttv56_vVd5G00RZgOlZJq_Tt0,9
+cmhstats-0.1.0.dist-info/RECORD,,

cmhstats-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

cmhstats-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Isha Bhatia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cmhstats-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+cmhstats