pyemmeans 0.1.0__tar.gz

pyemmeans-0.1.0/LICENSE

@@ -0,0 +1,20 @@
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+
+Copyright (C) 2026 pyemmeans contributors
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <https://www.gnu.org/licenses/>.
+
+SPDX-License-Identifier: GPL-3.0-or-later
+

pyemmeans-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: pyemmeans
+Version: 0.1.0
+Summary: Python rewrite of emmeans (estimated marginal means)
+Author-email: Tuo Zhao <tourzhao@gatech.edu>
+Maintainer-email: Tuo Zhao <tourzhao@gatech.edu>
+License-Expression: GPL-3.0-or-later
+Project-URL: Homepage, https://rvlenth.github.io/emmeans/
+Keywords: estimated marginal means,least-squares means,statistics,post-hoc,linear models
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: patsy>=0.5
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: matplotlib>=3.8
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Dynamic: license-file
+
+# pyemmeans
+
+`pyemmeans` is a Python rewrite of core `emmeans` workflows for estimated marginal means (EMMs), contrasts, trends, and post-hoc inference.
+
+## Install
+
+```bash
+pip install pyemmeans
+```
+
+## Quick Start
+
+```python
+from pyemmeans import emmeans, pairs, ref_grid
+
+# `fit` can be a supported statsmodels model result
+rg = ref_grid(fit)
+emm = emmeans(rg, "treatment")
+print(emm.summary())
+print(pairs(emm).summary(infer=(False, True)))
+```
+
+## Highlights
+
+- Core EMM APIs: `ref_grid`, `emmeans`, `contrast`, `pairs`, `summary`, `confint`, `test`
+- Trend and joint testing support: `emtrends`, `joint_tests`
+- Multiple weight modes in `emmeans(..., weights=...)`
+- Parity-oriented tests against R fixtures
+
+## Project Notes
+
+This package is a parity-oriented Python implementation inspired by the R `emmeans` ecosystem.
+
+## Authorship and Attribution
+
+- Python rewrite author: Tuo Zhao (`tourzhao@gatech.edu`)
+- Original R `emmeans` package: developed by its R authors and contributors
+- Full attribution details are included in `AUTHORS.md` in the source distribution.

pyemmeans-0.1.0/README.md

@@ -0,0 +1,72 @@
+# pyemmeans
+
+Python rewrite of `emmeans` for estimated marginal means, contrasts, trends, and inference.
+
+## Documentation
+
+- Python help docs (generated from all R Rd pages + vignettes): [`docs/README.md`](docs/README.md)
+- Reference index: [`docs/reference-index.md`](docs/reference-index.md)
+- Guide index: [`docs/guide-index.md`](docs/guide-index.md)
+
+## Authorship and attribution
+
+- Python rewrite author: Tuo Zhao (`tourzhao@gatech.edu`)
+- Original R `emmeans` package: developed by its R authors and contributors
+- Full attribution details: [`AUTHORS.md`](AUTHORS.md)
+
+## Quick start
+
+```python
+from pyemmeans import emmeans, ref_grid, pairs
+
+rg = ref_grid(model_result)
+emm = emmeans(rg, "treatment")
+print(emm.summary())
+print(pairs(emm).summary(infer=(False, True)))
+```
+
+## Implemented API (current)
+
+- `ref_grid()`
+- `emmeans()`, `lsmeans()`, `pmmeans()`
+- `contrast()`, `pairs()`, `coef()`
+- contrast families (`pairwise_emmc`, `tukey_emmc`, `trt_vs_ctrl_emmc`, ...)
+- `summary()`, `confint()`, `test()`, `predict()`
+- `regrid()`
+- `eff_size()`
+- `force_regular()`, `linfct()`
+- `emtrends()`
+- `joint_tests()`
+- `pwpm()`, `pwpp()`
+- `qdrg()`, `emmobj()`
+- `rbind_emm_grid()`
+- `emmip()`, `emmip_matplotlib()`
+- factor utilities: `comb_facs()`, `split_fac()`, `add_grouping()`, `permute_levels()`
+- wrapper aliases: `emm`, `lsmeans`, `lstrends`, `lsm`, `lsmobj`
+  `lsmip`
+- covariate reducers: `make_meanint`, `meanint`, `make_symmint`, `symmint`
+
+## Current model support
+
+- `statsmodels` formula-based OLS/GLM
+- `qdrg` custom wrapper models
+
+## Performance check
+
+- Run a reproducible local benchmark:
+  `python3 scripts/benchmark_emmeans.py`
+
+## PyPI release
+
+- Release checklist:
+  `docs/PYPI_RELEASE.md`
+- One-command release helper:
+  `scripts/release_pypi.sh`
+
+## Notes
+
+- `nuisance` handling in `ref_grid()` is implemented with R-aligned behavior for `wt_nuis="equal"` and non-`equal` modes (`prop`, `outer`, `flat`, `cells` all follow proportional observed-frequency nuisance averaging, matching R internals), and nuisance factors that interact with other predictors are ignored.
+- `counterfactuals` support is available in a baseline form (`actual_*` columns and `cf_grid` flow).
+- `emmeans(..., weights=)` modes (`equal`, `proportional`, `outer`, `flat`, `cells`) plus `show.levels`, numeric vector weights, and matrix weights are covered by R parity fixtures and tests.
+- The package is validated with smoke/integration tests in `tests/`.
+- R-side baseline fixtures can be regenerated with `Rscript python-package/scripts/generate_r_fixtures.R`.

pyemmeans-0.1.0/README_PYPI.md

@@ -0,0 +1,38 @@
+# pyemmeans
+
+`pyemmeans` is a Python rewrite of core `emmeans` workflows for estimated marginal means (EMMs), contrasts, trends, and post-hoc inference.
+
+## Install
+
+```bash
+pip install pyemmeans
+```
+
+## Quick Start
+
+```python
+from pyemmeans import emmeans, pairs, ref_grid
+
+# `fit` can be a supported statsmodels model result
+rg = ref_grid(fit)
+emm = emmeans(rg, "treatment")
+print(emm.summary())
+print(pairs(emm).summary(infer=(False, True)))
+```
+
+## Highlights
+
+- Core EMM APIs: `ref_grid`, `emmeans`, `contrast`, `pairs`, `summary`, `confint`, `test`
+- Trend and joint testing support: `emtrends`, `joint_tests`
+- Multiple weight modes in `emmeans(..., weights=...)`
+- Parity-oriented tests against R fixtures
+
+## Project Notes
+
+This package is a parity-oriented Python implementation inspired by the R `emmeans` ecosystem.
+
+## Authorship and Attribution
+
+- Python rewrite author: Tuo Zhao (`tourzhao@gatech.edu`)
+- Original R `emmeans` package: developed by its R authors and contributors
+- Full attribution details are included in `AUTHORS.md` in the source distribution.

pyemmeans-0.1.0/pyemmeans/__init__.py

@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from .contrast import coef, contrast, pairs, weights
+from .contrast_families import (
+    consec_emmc,
+    del_eff_emmc,
+    dunnett_emmc,
+    eff_emmc,
+    helmert_emmc,
+    identity_emmc,
+    mean_chg_emmc,
+    nrmlz_emmc,
+    opoly_emmc,
+    pairwise_emmc,
+    poly_emmc,
+    revpairwise_emmc,
+    trt_vs_ctrl1_emmc,
+    trt_vs_ctrl_emmc,
+    trt_vs_ctrlk_emmc,
+    tukey_emmc,
+    wtcon_emmc,
+)
+from .cov_reduce import inverse, make_meanint, make_symmint, meanint, symmint
+from .emmip import emmip, emmip_ggplot, emmip_lattice, emmip_matplotlib
+from .emmeans import emmeans, pmmeans
+from .emtrends import emtrends
+from .effect_size import eff_size
+from .extras import (
+    as_emm_list,
+    as_glht,
+    as_mcmc_emm_grid,
+    as_mcmc_emm_list,
+    as_mcmc_list_emm_grid,
+    as_mcmc_list_emm_list,
+    emm_example,
+    hpd_summary,
+    mvcontrast,
+    mvregrid,
+)
+from .factors import add_grouping, add_submodels, comb_facs, permute_levels, split_fac
+from .interface import emm_basis, recover_data
+from .internal_compat import (
+    all_vars,
+    aovlist_dffun,
+    cmpMM,
+    combine_terms,
+    diag,
+    emm_register,
+    emm_vignette,
+    get_excl,
+    get_offset,
+    hurdle_support,
+    my_vcov,
+    num_key,
+    std_link_labels,
+    zi_support,
+)
+from .joint import joint_tests, test_emm_grid
+from .methods import as_emm_grid, emm_defaults, force_regular, linfct, update_emm_grid, vcov_emm_grid
+from .options import emm_options, get_emm_option, with_emm_options
+from .qdrg import emmobj, qdrg
+from .pairwise_display import pwpm, pwpp
+from .rbind import add_emm_grid, rbind_emm_grid
+from .ref_grid import get_last_ref_grid, ref_grid
+from .regrid import regrid
+from .summary import confint_emm_grid, predict_emm_grid, summary_emm_grid
+from .transforms import Link, make_link, make_tran
+from .types import EmmBasisResult, EmmGrid, QDRGModel, RecoverDataResult
+from .wrappers import emm, get_lsm_option, lsm, lsm_options, lsmobj, lsmeans, lsmip, lstrends
+
+__version__ = "0.1.0"
+
+
+def summary(object: EmmGrid, **kwargs):
+    return summary_emm_grid(object, **kwargs)
+
+
+def confint(object: EmmGrid, **kwargs):
+    return confint_emm_grid(object, **kwargs)
+
+
+def test(object: EmmGrid, **kwargs):
+    return test_emm_grid(object, **kwargs)
+
+
+def predict(object: EmmGrid, **kwargs):
+    return predict_emm_grid(object, **kwargs)
+
+
+__all__ = [
+    "EmmGrid",
+    "RecoverDataResult",
+    "EmmBasisResult",
+    "QDRGModel",
+    "ref_grid",
+    "get_last_ref_grid",
+    "emmeans",
+    "emm",
+    "lsmeans",
+    "lstrends",
+    "lsm",
+    "lsmip",
+    "lsmobj",
+    "emmip",
+    "emmip_ggplot",
+    "emmip_lattice",
+    "emmip_matplotlib",
+    "pmmeans",
+    "emtrends",
+    "contrast",
+    "pairs",
+    "coef",
+    "weights",
+    "pairwise_emmc",
+    "revpairwise_emmc",
+    "consec_emmc",
+    "tukey_emmc",
+    "trt_vs_ctrl_emmc",
+    "trt_vs_ctrl1_emmc",
+    "trt_vs_ctrlk_emmc",
+    "dunnett_emmc",
+    "eff_emmc",
+    "mean_chg_emmc",
+    "del_eff_emmc",
+    "identity_emmc",
+    "poly_emmc",
+    "opoly_emmc",
+    "helmert_emmc",
+    "nrmlz_emmc",
+    "wtcon_emmc",
+    "regrid",
+    "force_regular",
+    "summary",
+    "confint",
+    "test",
+    "predict",
+    "summary_emm_grid",
+    "confint_emm_grid",
+    "predict_emm_grid",
+    "test_emm_grid",
+    "joint_tests",
+    "eff_size",
+    "pwpm",
+    "pwpp",
+    "mvcontrast",
+    "mvregrid",
+    "comb_facs",
+    "split_fac",
+    "add_grouping",
+    "add_submodels",
+    "permute_levels",
+    "rbind_emm_grid",
+    "add_emm_grid",
+    "qdrg",
+    "emmobj",
+    "as_emm_list",
+    "as_glht",
+    "as_mcmc_emm_grid",
+    "as_mcmc_emm_list",
+    "as_mcmc_list_emm_grid",
+    "as_mcmc_list_emm_list",
+    "hpd_summary",
+    "emm_example",
+    "recover_data",
+    "emm_basis",
+    "all_vars",
+    "aovlist_dffun",
+    "cmpMM",
+    "combine_terms",
+    "diag",
+    "emm_register",
+    "emm_vignette",
+    "get_excl",
+    "get_offset",
+    "hurdle_support",
+    "my_vcov",
+    "num_key",
+    "std_link_labels",
+    "zi_support",
+    "vcov_emm_grid",
+    "linfct",
+    "as_emm_grid",
+    "update_emm_grid",
+    "emm_defaults",
+    "emm_options",
+    "get_emm_option",
+    "lsm_options",
+    "get_lsm_option",
+    "with_emm_options",
+    "make_meanint",
+    "meanint",
+    "make_symmint",
+    "symmint",
+    "inverse",
+    "Link",
+    "make_link",
+    "make_tran",
+]
+
+# R-style compatibility aliases (dot names)
+_DOT_ALIASES = {
+    ".all.vars": all_vars,
+    ".aovlist.dffun": aovlist_dffun,
+    ".cmpMM": cmpMM,
+    ".combine.terms": combine_terms,
+    ".diag": diag,
+    ".emm_register": emm_register,
+    ".emm_vignette": emm_vignette,
+    ".get.excl": get_excl,
+    ".get.offset": get_offset,
+    ".hurdle.support": hurdle_support,
+    ".my.vcov": my_vcov,
+    ".num.key": num_key,
+    ".std.link.labels": std_link_labels,
+    ".zi.support": zi_support,
+    "get.lsm.option": get_lsm_option,
+    "lsm.options": lsm_options,
+    "make.meanint": make_meanint,
+    "make.symmint": make_symmint,
+    "make.tran": make_tran,
+    "as.emmGrid": as_emm_grid,
+    "as.emm_list": as_emm_list,
+    "as.glht": as_glht,
+    "as.mcmc.emmGrid": as_mcmc_emm_grid,
+    "as.mcmc.emm_list": as_mcmc_emm_list,
+    "as.mcmc.list.emmGrid": as_mcmc_list_emm_grid,
+    "as.mcmc.list.emm_list": as_mcmc_list_emm_list,
+    "hpd.summary": hpd_summary,
+    "pairwise.emmc": pairwise_emmc,
+    "revpairwise.emmc": revpairwise_emmc,
+    "consec.emmc": consec_emmc,
+    "tukey.emmc": tukey_emmc,
+    "trt.vs.ctrl.emmc": trt_vs_ctrl_emmc,
+    "trt.vs.ctrl1.emmc": trt_vs_ctrl1_emmc,
+    "trt.vs.ctrlk.emmc": trt_vs_ctrlk_emmc,
+    "dunnett.emmc": dunnett_emmc,
+    "eff.emmc": eff_emmc,
+    "mean_chg.emmc": mean_chg_emmc,
+    "del.eff.emmc": del_eff_emmc,
+    "identity.emmc": identity_emmc,
+    "poly.emmc": poly_emmc,
+    "opoly.emmc": opoly_emmc,
+    "helmert.emmc": helmert_emmc,
+    "nrmlz.emmc": nrmlz_emmc,
+    "wtcon.emmc": wtcon_emmc,
+}
+for _k, _v in _DOT_ALIASES.items():
+    globals()[_k] = _v

pyemmeans-0.1.0/pyemmeans/adapters/__init__.py

@@ -0,0 +1,11 @@
+from .base import EmmAdapter
+from .qdrg import emm_basis_qdrg, recover_data_qdrg
+from .statsmodels import emm_basis_statsmodels, recover_data_statsmodels
+
+__all__ = [
+    "EmmAdapter",
+    "recover_data_qdrg",
+    "emm_basis_qdrg",
+    "recover_data_statsmodels",
+    "emm_basis_statsmodels",
+]

pyemmeans-0.1.0/pyemmeans/adapters/base.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from typing import Any, Protocol
+
+from ..types import EmmBasisResult, RecoverDataResult
+
+
+class EmmAdapter(Protocol):
+    def recover_data(self, model: Any, **kwargs: Any) -> RecoverDataResult: ...
+
+    def emm_basis(self, model: Any, trms: str, xlev: dict[str, list[Any]], grid, **kwargs: Any) -> EmmBasisResult: ...

pyemmeans-0.1.0/pyemmeans/adapters/qdrg.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from patsy import dmatrix
+
+from ..transforms import make_link
+from ..types import EmmBasisResult, QDRGModel, RecoverDataResult
+
+
+def recover_data_qdrg(model: QDRGModel, **kwargs: Any) -> RecoverDataResult:
+    formula = model.formula
+    lhs, rhs = [x.strip() for x in formula.split("~", 1)]
+    predictors = [c for c in model.data.columns if c in rhs or c == lhs or True]
+    # keep all columns to allow transformed expressions and at= usage
+    return RecoverDataResult(
+        data=model.data.copy(),
+        terms=formula,
+        predictors=[c for c in model.data.columns if c != lhs],
+        responses=[lhs],
+        call=None,
+        misc={},
+    )
+
+
+def emm_basis_qdrg(model: QDRGModel, trms: str, xlev: dict[str, list[Any]], grid: pd.DataFrame, **kwargs: Any) -> EmmBasisResult:
+    lhs, rhs = [x.strip() for x in trms.split("~", 1)]
+    Xdf = dmatrix(rhs, data=grid, return_type="dataframe")
+    X = np.asarray(Xdf, dtype=float)
+
+    coef = np.asarray(model.coef, dtype=float)
+    if coef.ndim > 1:
+        coef = coef.ravel()
+    p = X.shape[1]
+    if coef.size != p:
+        raise ValueError(f"Non-conforming coef length ({coef.size}) vs model matrix columns ({p})")
+
+    V = np.asarray(model.vcov, dtype=float)
+    if V.shape != (p, p):
+        raise ValueError(f"Non-conforming vcov shape {V.shape}; expected {(p, p)}")
+
+    def dffun(k: np.ndarray, dfargs: dict[str, Any]) -> float:
+        return float(dfargs["df"])
+
+    misc: dict[str, Any] = {}
+    if model.link:
+        misc["tran"] = make_link(model.link)
+        misc["inv_lbl"] = "response"
+
+    post_beta = None
+    if model.mcmc is not None:
+        post_beta = np.asarray(model.mcmc, dtype=float)
+
+    return EmmBasisResult(
+        X=X,
+        bhat=coef,
+        nbasis=np.array([[np.nan]]),
+        V=V,
+        dffun=dffun,
+        dfargs={"df": float(model.df)},
+        misc=misc,
+        post_beta=post_beta,
+    )