csv-stats 0.4.0__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.4.0 → csv_stats-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: csv-stats
-Version: 0.4.0
+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
@@ -57,10 +57,37 @@ 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)
+## 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). Random intercept per subject, REML, sum-to-zero coding.
+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
@@ -75,6 +102,11 @@ lmm(df, "step_length", within=["session", "speed"], subject="subject")       # o
 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

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

@@ -20,10 +20,37 @@ 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)
+## 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). Random intercept per subject, REML, sum-to-zero coding.
+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
@@ -38,6 +65,11 @@ lmm(df, "step_length", within=["session", "speed"], subject="subject")       # o
 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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "csv-stats"
-version = "0.4.0"
+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"
@@ -61,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.4.0 → 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"}

{csv_stats-0.4.0 → 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))