cmhstats 0.1.0__tar.gz

cmhstats-0.1.0/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/MANIFEST.in

@@ -0,0 +1,4 @@
+graft tests
+graft validation
+graft docs
+global-exclude __pycache__ *.py[cod]

cmhstats-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,118 @@
+# 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/docs/camis/python_cmh.qmd

@@ -0,0 +1,89 @@
+---
+title: "CMH Test in Python"
+---
+
+# Cochran-Mantel-Haenszel Test
+
+<!-- Draft contribution for the PHUSE CAMIS repository (python/cmh.qmd).
+     It uses the same ADCIBC data and scenarios as R/cmh.qmd and SAS/cmh.qmd. -->
+
+The CMH procedure tests for conditional independence in stratified contingency tables. SAS PROC FREQ reports three statistics: nonzero correlation, row mean scores differ, and general association. For 2 x 2 x K tables it also reports common odds ratios, relative risks and the Breslow-Day test.
+
+## Available Python packages
+
+| Package | General Association | Row Means Differ | Nonzero Correlation | M-H Odds Ratio | Homogeneity Test | Note |
+|---|---|---|---|---|---|---|
+| `statsmodels` (`StratifiedTable`) | 2x2xK only | ❌ | ❌ | ✅ | ✅ | Breslow-Day with optional Tarone adjustment. No CI for the pooled relative risk. |
+| `cmh` (PyPI 1.0.1) | ⚠️ | ❌ | ❌ | ❌ | ❌ | Wrong for tables larger than 2x2: on R's `Satisfaction` example it gives 12.53 instead of 10.20. |
+| `cmhstats` | ✅ | ✅ | ✅ | ✅ | ✅ | Table, rank, ridit and modridit scores; MH and logit OR/RR; Breslow-Day and Tarone. |
+
+## Data used
+
+```{python}
+import pandas as pd
+adcibc = pd.read_csv("../data/adcibc.csv")
+```
+
+## Example code
+
+### 2 x 2 x 2: X = treatment (placebo vs high dose), Y = sex, K = age group
+
+```{python}
+import cmhstats
+
+data2 = adcibc[(adcibc.TRTPN != 54) & (adcibc.AGEGR1 != ">80")]
+res = cmhstats.cmh_test(data=data2, x="TRTP", y="SEX", strata="AGEGR1")
+print(res)
+```
+
+`res.common_odds_ratio`, `res.relative_risk_col1` and `res.breslow_day` hold the 2 x 2 x K estimates.
+
+### 3 x 5 x 17: X = treatment, Y = CIBIC score, K = site (sparse)
+
+```{python}
+res9 = cmhstats.cmh_test(data=adcibc, x="TRTP", y="AVAL", strata="SITEID")
+print(res9)
+```
+
+Site 702 has one subject and is skipped, since it carries no information. Sites 706 and 707 each lack a treatment arm or a score level. This is what stops `vcdExtra::CMHtest` in R, which tests each stratum before pooling. The pooled statistic is well defined.
+
+### Matching R's `mantelhaen.test`
+
+R applies a continuity correction to 2 x 2 x K tables by default, and SAS does not. `cmhstats.mantelhaen_test()` follows R, including `correct=True`.
+
+```{python}
+import numpy as np
+tab = pd.crosstab([data2.TRTP, data2.SEX], data2.AGEGR1).to_numpy().reshape(2, 2, 2)
+cmhstats.mantelhaen_test(tab)                 # = stats::mantelhaen.test(...)
+cmhstats.mantelhaen_test(tab, correct=False)  # = SAS
+```
+
+## Comparison with SAS
+
+`cmhstats` reproduces all 18 SAS statistics of the R vs SAS comparison at the 4 decimals SAS prints, including scenario 9.
+
+| Scenario | Test | SAS | Python (`cmhstats`) |
+|---|---|---|---|
+| 1 | Correlation / Row Means / General | 0.2166 / 0.2166 / 0.2166 | 0.2166 / 0.2166 / 0.2166 |
+| 2 | Correlation / Row Means / General | 0.0009 / 2.4820 / 2.4820 | 0.0009 / 2.4820 / 2.4820 |
+| 3 | Correlation / Row Means / General | 0.0028 / 2.3861 / 2.3861 | 0.0028 / 2.3861 / 2.3861 |
+| 6 | Correlation / Row Means / General | 1.7487 / 1.7487 / 8.0534 | 1.7487 / 1.7487 / 8.0534 |
+| 9 | Correlation / Row Means / General | 0.0854 / 2.4763 / 7.0339 | 0.0854 / 2.4763 / 7.0339 |
+| 10 | Correlation / Row Means / General | 1.6621 / 2.2980 / 5.7305 | 1.6621 / 2.2980 / 5.7305 |
+
+Two notes for the R vs SAS page:
+
+* In scenario 2 the SAS df for row means and general association should read 2, not 1. The listed p-value, 0.2891, is the chi-square(2) tail.
+* Scenario 9 runs in R once vcdExtra's per-stratum tests are skipped. `mantelhaen.test` on the table without site 702 also gives the SAS general association value, 7.0339.
+
+## Points to watch
+
+* **Level order.** SAS sorts character levels by code point (`"65-80"` before `"<65"`), and R's default locale sort does not. With table scores, this changes the correlation and row mean scores statistics.
+* **Table scores.** SAS uses the values of numeric variables as scores and positions for character variables. Recoding a numeric response as text changes the correlation and row mean scores results.
+* **Continuity correction.** This differs between R's default and SAS for 2 x 2 x K tables (see above).
+
+# References
+
+SAS documentation, PROC FREQ, Cochran-Mantel-Haenszel Statistics.
+
+Landis, Heyman & Koch (1978). Average partial association in three-way contingency tables. *International Statistical Review* 46, 237–254.

cmhstats-0.1.0/docs/validation.md

@@ -0,0 +1,68 @@
+# Validation report — cmhstats 0.1.0
+
+Generated 31 October 2026. Python 3.13, NumPy 2.5, SciPy 1.18. R 4.3.3 with vcdExtra 0.8.5, coin 1.4.3, epiR 2.0.67.
+
+## Summary
+
+| Reference | What is compared | Cases | Agreement |
+|---|---|---|---|
+| Published SAS output | CMH statistics, odds ratios, relative risks, Breslow-Day | 3 sources, 8 analyses | All printed digits (4 decimals) |
+| `vcdExtra` formulas in R | 3 statistics x 4 score types | 142 tables | Relative 1e-8 |
+| `vcdExtra::CMHtest` | 3 statistics, table and modridit scores | 96 tables it can compute | Relative 1e-8 |
+| `stats::mantelhaen.test` | General association; 2x2xK MH OR + CI; correction; one-sided | 131 tables | Relative 1e-8 |
+| `coin::cmh_test` | General association | 139 tables | Relative 1e-8 |
+| `epiR::epi.2by2` | MH OR, MH RR (both columns) + CIs, Breslow-Day | 21 tables | Relative 1e-7 |
+| Hand-written R (from SAS formulas) | Logit OR and RR + CIs, Breslow-Day, Tarone | 30 tables | Relative 1e-7 |
+| SciPy / statsmodels / definitions | Pearson, Spearman, Kruskal-Wallis, van Elteren, `StratifiedTable` | Random tables | Relative 1e-10 |
+
+The test suite has 1,178 tests: 1,175 pass and 3 are skipped by design (see "Known differences").
+
+## 1. SAS
+
+Each value is compared with SAS's printed output after rounding to 4 decimals. p-values are compared the same way.
+
+**Migraine** (SAS/STAT documentation, "Cochran-Mantel-Haenszel Statistics" example). All three CMH statistics (8.3052, p = 0.0040), the Mantel-Haenszel and logit odds ratios, the column 1 and column 2 relative risks with 95% limits, and the Breslow-Day test (1.4929, p = 0.2218) agree.
+
+**SexualFun**, a 4 x 4 single-stratum table (SAS output posted to R-help by M. Friendly, 2009). Correlation 10.0142, row mean scores 12.5681, general association 16.7689, with their p-values, agree.
+
+**CAMIS scenarios 1, 2, 3, 6, 9 and 10** on CDISC pilot ADCIBC (SAS 9.04.01M7, from the CAMIS repository). All 18 statistics agree, with their df and p-values. This includes scenario 9 (3 x 5 x 17, by site), for which CAMIS reports no R result.
+
+## 2. R
+
+`validation/generate_r_reference.R` creates the reference tables with a fixed seed:
+
+* 126 random tables: 14 shapes x 3 sparsity levels (Poisson means 0.8, 3, 15) x 3 replicates. Each stratum has at least 2 observations, so every R function can run.
+* 12 tables with one single-observation stratum. R refuses these (`mantelhaen.test`) or returns NaN (`vcdExtra`). The reference is computed on the table without that stratum. `cmhstats` receives the full table and must give the same answer.
+* 4 textbook tables: `UCBAdmissions`, `Satisfaction` and the penicillin `Rabbits` data from R's documentation, and `Arthritis` from vcd.
+
+`vcdExtra::CMHtest` returned an error for 46 of the 142 tables, including 38 of the 126 random ones. To cover all of them, the script also evaluates vcdExtra's own formulas pooled across strata, without the per-stratum step that fails (`pooled_cmh_r`). Rank and ridit scores, which vcdExtra does not offer, are computed through the same code. Section 4 explains the failure.
+
+## 3. Independent checks
+
+* One stratum: general association = Pearson X² · (n−1)/n, correlation = (n−1)·r² (Pearson for table scores, Spearman for rank-type scores), and rank row mean scores = Kruskal-Wallis H with tie correction. These are the identities stated in the SAS documentation, checked against `scipy.stats`.
+* Van Elteren's test, coded from its definition (within-stratum midranks, weights 1/(n_h+1), tie-corrected variance), equals the row mean scores statistic with modified ridit scores.
+* For 2 x 2 x K tables, `statsmodels` `StratifiedTable` agrees on the CMH statistic (with and without correction), MH odds ratio and limits, MH relative risk, and Breslow-Day with and without Tarone's adjustment.
+* Invariances: strata order, row/column transposition (general association), affine changes of table scores, and permutation of nominal rows all leave the relevant statistics unchanged.
+
+## 4. Findings
+
+**Why `vcdExtra` fails on sparse tables.** `CMHtest` computes a test for every stratum before pooling, and each one calls `solve()` on that stratum's covariance matrix. A stratum missing a row or column level makes its own matrix singular, and the error ends the whole call even though the pooled matrix is fine. In CAMIS scenario 9 this happens at sites 706 and 707. Site 702 has a single subject, but dropping it does not fix the error. The CAMIS page suggests replacing `solve()` with `MASS::ginv`. Skipping the per-stratum tests is enough, and the pooled result then equals SAS. `mantelhaen.test` also gives the SAS general association value (7.0339) once site 702 is removed.
+
+**PyPI `cmh` 1.0.1.** Its `CMH_numpy` flattens the observed-minus-expected vector in row-major order (`reshape(-1)`) but builds the covariance with `kron(columns, rows)`, which assumes column-major order. The two agree only when both dimensions are 2. On R's `Satisfaction` example (4 x 4 x 2) it returns 12.531 where R, Stata and SAS give 10.200. With column-major flattening it gives 10.200.
+
+**CAMIS scenario 2 degrees of freedom.** The SAS table on the CAMIS page lists df = 1 for row mean scores and general association. The p-value 0.2891 is the chi-square(2) tail of 2.4820 (the chi-square(1) tail is 0.1152), so this is a transcription error.
+
+## 5. Known differences and open questions
+
+* **Singular covariance.** `cmhstats` returns NaN with a warning, as SAS reports a missing value. `coin` uses a generalized inverse with reduced df, and `mantelhaen.test` raises an error. The 3 skipped tests are these cases.
+* **Single-observation strata.** These are skipped for the CMH statistics, where they contribute exactly zero. This agrees with SAS on scenarios 3 and 9. For the logit estimators, `cmhstats` follows the SAS rule as documented (add 0.5 to each cell of a stratum with a zero cell), so such strata are included. This edge case has not been confirmed against SAS output.
+* **Rank-type scores are computed within each stratum.** This follows SAS's stratum-indexed score matrices and the van Elteren equivalence, and it agrees with vcdExtra's `"midrank"` scores and the van Elteren definition. It has not been confirmed against SAS output with `SCORES=RANK` or `RIDIT` on multi-stratum data. That would be the most useful next check for anyone with SAS access.
+* **Breslow-Day with zero margins.** Strata with a zero row or column are excluded, as the SAS documentation states. Cases where the MH odds ratio is 0 or infinite return `None` (SAS does not compute the test).
+
+## Reproducing
+
+```bash
+pip install -e ".[test]"
+pytest                                   # uses committed fixtures, no R needed
+Rscript validation/generate_r_reference.R  # optional: needs R with vcdExtra, coin, epiR, jsonlite
+```

cmhstats-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cmhstats"
+version = "0.1.0"
+description = "Cochran-Mantel-Haenszel statistics for Python, validated against SAS PROC FREQ and R"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Isha Bhatia" }]
+requires-python = ">=3.9"
+dependencies = ["numpy>=1.22", "scipy>=1.8"]
+keywords = ["cochran-mantel-haenszel", "cmh", "clinical-trials", "biostatistics", "contingency-table", "sas", "van-elteren", "breslow-day"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.5"]
+test = ["pytest>=7", "pandas>=1.5", "statsmodels>=0.14"]
+
+[project.urls]
+Homepage = "https://github.com/Isha0206/cmhstats"
+Validation = "https://github.com/Isha0206/cmhstats/blob/main/docs/validation.md"
+Changelog = "https://github.com/Isha0206/cmhstats/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Isha0206/cmhstats/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

cmhstats-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

cmhstats-0.1.0/src/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__",
+]