csv-stats 0.2.0__tar.gz → 0.4.0__tar.gz

{csv_stats-0.2.0 → csv_stats-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: csv-stats
-Version: 0.2.0
+Version: 0.4.0
 Summary: A Python package for the life sciences to conduct hypothesis testing from CSV files.
 Project-URL: Homepage, https://github.com/mtillman14/csv-stats
 Project-URL: Documentation, https://github.com/mtillman14/csv-stats
@@ -20,6 +20,7 @@ Requires-Dist: pandas>=1.5
 Requires-Dist: scipy>=1.7
 Provides-Extra: dev
 Requires-Dist: matplotlib>=3.6; extra == 'dev'
+Requires-Dist: patsy>=0.5; extra == 'dev'
 Requires-Dist: pingouin>=0.6.0; extra == 'dev'
 Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: reportlab>=4.4.4; extra == 'dev'
@@ -27,6 +28,7 @@ Requires-Dist: seaborn>=0.13; extra == 'dev'
 Requires-Dist: statsmodels>=0.14.5; extra == 'dev'
 Provides-Extra: full
 Requires-Dist: matplotlib>=3.6; extra == 'full'
+Requires-Dist: patsy>=0.5; extra == 'full'
 Requires-Dist: pingouin>=0.6.0; extra == 'full'
 Requires-Dist: reportlab>=4.4.4; extra == 'full'
 Requires-Dist: seaborn>=0.13; extra == 'full'
@@ -55,6 +57,26 @@ ci_interval([4.1, 5.0, 6.2])       # (low, high); also a seaborn errorbar= calla
 ci_half_width(sd=1.2, n=5)         # t(0.975, 4) * 1.2 / sqrt(5)
 ```
 
+## Linear mixed models (0.4.0)
+`csvstats.lmm` uses every observation: a subject missing some within-subject
+levels is kept, not dropped (a repeated-measures ANOVA or paired t-test would
+have to drop it). Random intercept per subject, REML, sum-to-zero coding.
+Tests use **Satterthwaite** degrees of freedom, as R's lmerTest does: t(df) per
+coefficient, a type-III F(q, ddf) per term, and t(df) per pairwise contrast. The
+pairwise contrasts come from the full model (emmeans-style). Everything is checked
+against lme4 / lmerTest / emmeans on 75 reference datasets (tests/reference).
+If a df cannot be computed, the Wald test is reported, labelled `df_method: "wald"`.
+
+```python
+from csvstats.lmm import lmm, lmm_pairwise
+from csvstats.core import assumption_checks
+
+lmm(df, "step_length", within=["session", "speed"], subject="subject")       # one F(q, ddf) per term
+lmm_pairwise(df, "step_length", within=["session", "speed"], subject="subject", factor="session",
+             levels={"session": ["post", "pre"]})   # post − pre within each speed, t(df)
+assumption_checks(df, "step_length", within=["session"], subject="subject")  # Shapiro–Wilk on residuals (+ Levene)
+```
+
 ## Examples
 All code examples below use the following constants:
 ```python

{csv_stats-0.2.0 → csv_stats-0.4.0}/README.md

@@ -20,6 +20,26 @@ ci_interval([4.1, 5.0, 6.2])       # (low, high); also a seaborn errorbar= calla
 ci_half_width(sd=1.2, n=5)         # t(0.975, 4) * 1.2 / sqrt(5)
 ```
 
+## Linear mixed models (0.4.0)
+`csvstats.lmm` uses every observation: a subject missing some within-subject
+levels is kept, not dropped (a repeated-measures ANOVA or paired t-test would
+have to drop it). Random intercept per subject, REML, sum-to-zero coding.
+Tests use **Satterthwaite** degrees of freedom, as R's lmerTest does: t(df) per
+coefficient, a type-III F(q, ddf) per term, and t(df) per pairwise contrast. The
+pairwise contrasts come from the full model (emmeans-style). Everything is checked
+against lme4 / lmerTest / emmeans on 75 reference datasets (tests/reference).
+If a df cannot be computed, the Wald test is reported, labelled `df_method: "wald"`.
+
+```python
+from csvstats.lmm import lmm, lmm_pairwise
+from csvstats.core import assumption_checks
+
+lmm(df, "step_length", within=["session", "speed"], subject="subject")       # one F(q, ddf) per term
+lmm_pairwise(df, "step_length", within=["session", "speed"], subject="subject", factor="session",
+             levels={"session": ["post", "pre"]})   # post − pre within each speed, t(df)
+assumption_checks(df, "step_length", within=["session"], subject="subject")  # Shapiro–Wilk on residuals (+ Levene)
+```
+
 ## Examples
 All code examples below use the following constants:
 ```python

{csv_stats-0.2.0 → csv_stats-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "csv-stats"
-version = "0.2.0"
+version = "0.4.0"
 description = "A Python package for the life sciences to conduct hypothesis testing from CSV files."
 readme = "README.md"
 requires-python = ">=3.8"
@@ -35,6 +35,7 @@ dependencies = [
 full = [
     "pingouin>=0.6.0",
     "statsmodels>=0.14.5",
+    "patsy>=0.5",  # csvstats.lmm builds its design matrices with patsy
     "reportlab>=4.4.4",
     "matplotlib>=3.6",
     "seaborn>=0.13",
@@ -53,5 +54,11 @@ Issues = "https://github.com/mtillman14/csv-stats/issues"
 [tool.hatch.build.targets.wheel]
 packages = ["src/csvstats"]
 
+# The sdist keeps the src/ layout: the wheel is built FROM the sdist, and
+# looks for src/csvstats. `packages` here re-rooted it to csvstats/, so the
+# 0.2.0 wheel came out empty (metadata only).
 [tool.hatch.build.targets.sdist]
-packages = ["src/csvstats"]
+only-include = ["src/csvstats", "tests", "README.md"]
+
+[tool.hatch.build]
+ignore-vcs = true

csv_stats-0.4.0/src/csvstats/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{csv_stats-0.2.0 → csv_stats-0.4.0/src}/csvstats/core.py

@@ -334,6 +334,43 @@ def _levene(groups: list[np.ndarray], alpha: float) -> dict[str, Any]:
     return {"name": "homogeneity_of_variance", "test": "levene", "scope": "groups", "statistic": _num(w), "p": _num(p), "violated": bool(p < alpha)}
 
 
+def assumption_checks(
+    data: pd.DataFrame,
+    dv: str,
+    *,
+    between: Sequence[str] = (),
+    within: Sequence[str] = (),
+    subject: str | None = None,
+    levels: dict[str, list[Any]] | None = None,
+    alpha: float = 0.05,
+) -> dict[str, Any]:
+    """The checks a caller uses to RECOMMEND a test, before running one.
+
+    Normality (Shapiro–Wilk) of the residuals the parametric model would have:
+    ``y − cell mean`` for between-only designs, and additionally centred on
+    each subject's mean when there is a within factor (every observation is
+    used; nobody is dropped). Homogeneity of variance (Levene, median-centred)
+    across the between cells, when there are any.
+
+    Returns ``{"assumptions": [...], "n": ...}``. Pre-testing assumptions to
+    choose a test is debated; callers should show this as evidence for a
+    recommendation the user can override, never as a silent switch.
+    """
+    between, within = list(between), list(within)
+    factors = [*between, *within]
+    prep = _Prepared(data, dv, factors, subject if within else None, levels)
+    frame = prep.frame
+    y = frame[dv].astype(float)
+    resid = y - (frame.groupby(factors)[dv].transform("mean") if factors else y.mean())
+    if within and subject:
+        resid = resid - frame.groupby(subject)[dv].transform("mean") + y.mean()
+    checks = [_shapiro(resid.to_numpy(float), "residuals", alpha)]
+    if between:
+        groups = [g[dv].to_numpy(float) for _, g in frame.groupby(between)]
+        checks.append(_levene(groups, alpha))
+    return {"assumptions": checks, "n": prep.n_record()}
+
+
 def _flag_violations(assumptions: list[dict], warnings: list[dict]) -> None:
     for a in assumptions:
         if a.get("violated"):