csv-stats 0.2.1__tar.gz → 0.4.2__tar.gz

csv_stats-0.4.2/.gitignore

@@ -0,0 +1,8 @@
+/dist
+/build
+*.pyc
+/src/csv_stats.egg-info
+.DS_Store
+
+# scratch input for tests/reference/check_lmm_optimum.R
+tests/reference/scenarios/ours_check.json

{csv_stats-0.2.1 → csv_stats-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: csv-stats
-Version: 0.2.1
+Version: 0.4.2
 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,58 @@ 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.1)
+`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). REML, sum-to-zero coding. The random effects default to an
+intercept per subject. `random=` takes any lme4-style structure:
+- random slopes, correlated or uncorrelated (`||`)
+- crossed groupings, e.g. subject + item
+- nested and interaction groupings, e.g. `site:subject`
+
+Numeric `covariates=` are crossed with the factors. Term tests are type III,
+as in lmerTest and SAS. So a factor crossed with a covariate is tested at
+covariate = 0, and a `type3_at_covariate_zero` warning says so. Centre the
+covariate to test the factor at the covariate's mean.
+
+`csvstats.lmm_formula` reads and writes the lme4 spelling of these models
+(`parse("y ~ group * time * x + (1 + x | subject)")`, `render(...)`), with
+errors that point at the offending character. It accepts what `lmm` can fit:
+the fixed part is ONE crossing (`a * b * x`, or `1`), and random terms are
+`(… | g)`, `(… || g)`, `a:b` and `a/b`. A model with no more observations
+than random effects is refused before fitting, as lme4 does.
+
+`lmm_pairwise` takes the same `covariates=` and compares levels with each
+covariate at its mean (emmeans' reference grid), or at the value you give
+in `covariates_at={"age": 65}`. The record's `details["covariates_at"]`
+states the value used. So with a covariate, `lmm`'s F for a factor (at 0)
+and `lmm_pairwise`'s contrasts (at the mean) answer different questions,
+exactly as lmerTest's anova and emmeans do in R.
+
+The fit is checked against lme4 on 225 sampled scenarios over 9
+random-effect structures (tests/reference/scenarios). That covers the
+criterion itself at fixed θ, the estimates, θ and the Satterthwaite df.
+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)
+
+# Random slopes and crossed effects: y ~ cond * x + (1 + x | subject) + (1 | item)
+lmm(df, "rt", within=["cond"], subject="subject", covariates=["x"],
+    random=[{"group": "subject", "terms": ["(Intercept)", "x"]},
+            {"group": "item"}])
+```
+
 ## Examples
 All code examples below use the following constants:
 ```python

{csv_stats-0.2.1 → csv_stats-0.4.2}/README.md

@@ -20,6 +20,58 @@ 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.1)
+`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). REML, sum-to-zero coding. The random effects default to an
+intercept per subject. `random=` takes any lme4-style structure:
+- random slopes, correlated or uncorrelated (`||`)
+- crossed groupings, e.g. subject + item
+- nested and interaction groupings, e.g. `site:subject`
+
+Numeric `covariates=` are crossed with the factors. Term tests are type III,
+as in lmerTest and SAS. So a factor crossed with a covariate is tested at
+covariate = 0, and a `type3_at_covariate_zero` warning says so. Centre the
+covariate to test the factor at the covariate's mean.
+
+`csvstats.lmm_formula` reads and writes the lme4 spelling of these models
+(`parse("y ~ group * time * x + (1 + x | subject)")`, `render(...)`), with
+errors that point at the offending character. It accepts what `lmm` can fit:
+the fixed part is ONE crossing (`a * b * x`, or `1`), and random terms are
+`(… | g)`, `(… || g)`, `a:b` and `a/b`. A model with no more observations
+than random effects is refused before fitting, as lme4 does.
+
+`lmm_pairwise` takes the same `covariates=` and compares levels with each
+covariate at its mean (emmeans' reference grid), or at the value you give
+in `covariates_at={"age": 65}`. The record's `details["covariates_at"]`
+states the value used. So with a covariate, `lmm`'s F for a factor (at 0)
+and `lmm_pairwise`'s contrasts (at the mean) answer different questions,
+exactly as lmerTest's anova and emmeans do in R.
+
+The fit is checked against lme4 on 225 sampled scenarios over 9
+random-effect structures (tests/reference/scenarios). That covers the
+criterion itself at fixed θ, the estimates, θ and the Satterthwaite df.
+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)
+
+# Random slopes and crossed effects: y ~ cond * x + (1 + x | subject) + (1 | item)
+lmm(df, "rt", within=["cond"], subject="subject", covariates=["x"],
+    random=[{"group": "subject", "terms": ["(Intercept)", "x"]},
+            {"group": "item"}])
+```
+
 ## Examples
 All code examples below use the following constants:
 ```python

{csv_stats-0.2.1 → csv_stats-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "csv-stats"
-version = "0.2.1"
+version = "0.4.2"
 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",
@@ -60,4 +61,10 @@ packages = ["src/csvstats"]
 only-include = ["src/csvstats", "tests", "README.md"]
 
 [tool.hatch.build]
-ignore-vcs = true
+ignore-vcs = true
+
+# Collect only tests/. A bare `pytest` also walked src/, where the library
+# module utils/test_assumptions.py (functions named test_*) was collected as
+# tests and errored for missing fixtures.
+[tool.pytest.ini_options]
+testpaths = ["tests"]

csv_stats-0.4.2/src/csvstats/__init__.py

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

{csv_stats-0.2.1 → csv_stats-0.4.2}/src/csvstats/core.py

@@ -166,10 +166,17 @@ class _Prepared:
         factors: list[str],
         subject: str | None,
         levels: dict[str, list[Any]] | None,
+        extra: Sequence[str] = (),
     ) -> None:
+        """``extra``: further columns a test reads (an LMM's covariates,
+        random-effect groups and slopes), carried along; a row missing one
+        is dropped like a row missing the dv."""
         if not isinstance(data, pd.DataFrame):
             raise ValueError(f"data must be a pandas DataFrame, got {type(data).__name__}")
         needed = [dv, *factors, *([subject] if subject else [])]
+        # dict.fromkeys: a column named twice (a covariate that is also a
+        # random slope) must be selected once, or frame[c] is a DataFrame
+        needed += [c for c in dict.fromkeys(extra) if c not in needed]
         missing = [c for c in needed if c not in data.columns]
         if missing:
             raise ValueError(f"column(s) {missing!r} are not in the data")
@@ -182,9 +189,13 @@ class _Prepared:
         bad = frame[dv].isna() | frame[factors].isna().any(axis=1)
         if subject:
             bad |= frame[subject].isna()
+        carried = [c for c in dict.fromkeys(extra) if c not in (dv, subject, *factors)]
+        if carried:
+            bad |= frame[carried].isna().any(axis=1)
         if bad.any():
             self.excluded_detail.append(
-                {"rows": int(bad.sum()), "reason": f"missing {dv} or a factor/subject value"}
+                {"rows": int(bad.sum()), "reason": f"missing {dv} or a factor/subject value"
+                                                  + (f" or one of {carried}" if carried else "")}
             )
             self.warnings.append(
                 {"code": "rows_dropped_missing", "message": f"{int(bad.sum())} row(s) with a missing value dropped"}
@@ -334,6 +345,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"):

{csv_stats-0.2.1 → csv_stats-0.4.2}/src/csvstats/descriptive.py

@@ -6,9 +6,13 @@ shape statistic gets it from here. That includes csv-stats' own test results
 (StatStudio descriptives). So an error bar on a figure and the number in a
 table cannot disagree.
 
-Light on purpose: this module imports numpy, pandas and scipy only (never
+Light on purpose: importing this module loads numpy and pandas only (never
 pingouin, statsmodels, matplotlib or reportlab), so a plotting package can
-depend on it cheaply. ``tests/test_descriptive.py`` guards that.
+depend on it cheaply. scipy is imported inside the two functions that need
+it (:func:`t_critical`, :func:`summarize`): ``scipy.stats`` alone cost 2 s of
+scistackplot's 4 s first import on Windows (2026-10-20), paid on every Plot
+Studio open even when no figure draws an interval. ``tests/test_descriptive.py``
+guards both.
 
 Conventions (each one is a decision, stated once):
 
@@ -34,7 +38,6 @@ from typing import Any, Literal
 
 import numpy as np
 import pandas as pd
-from scipy import stats
 
 #: Divisor offset of the sample SD (and variance): ``n - SD_DDOF``.
 SD_DDOF = 1
@@ -61,6 +64,8 @@ def t_critical(n: Any, level: float = CI_LEVEL) -> Any:
     NaN where ``n < 2``. Accepts a scalar, numpy array or pandas Series
     (index kept) and returns the same kind.
     """
+    from scipy import stats  # lazy: see the module docstring
+
     counts = np.asarray(n, dtype=float)
     upper = 1.0 - (1.0 - level) / 2.0
     with np.errstate(invalid="ignore"):
@@ -126,6 +131,8 @@ def summarize(values: Any, level: float = CI_LEVEL) -> dict[str, float]:
     ``cv`` (SD / mean) is NaN when the mean is 0. Skewness needs 3 values and
     kurtosis 4; with fewer they are NaN.
     """
+    from scipy import stats  # lazy: see the module docstring
+
     raw = pd.Series(values, dtype=float)
     clean = raw.dropna()
     n = int(len(clean))