bossanova 0.1.0.dev19__tar.gz → 0.1.0.dev21__tar.gz

{bossanova-0.1.0.dev19 → bossanova-0.1.0.dev21}/.gitignore

@@ -17,7 +17,7 @@ docs/_build/
 docs/performance/
 profile_*.py
 benchmarks/
-!bossanova-docs/engineering/benchmarks/
+!bossanova-docs/benchmarking/
 examples/
 papers/
 paper-summaries/
@@ -42,6 +42,7 @@ tests/parity/traces/
 # Coverage reports
 coverage_reports/
 .coverage
+.coverage.*
 htmlcov/
 # pixi environments
 .pixi/*
@@ -84,3 +85,4 @@ bossanova-docs/wip/
 research.md
 201b-ghct-05-models/
 emmeans/
+walkthrough.md

{bossanova-0.1.0.dev19 → bossanova-0.1.0.dev21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: bossanova
-Version: 0.1.0.dev19
+Version: 0.1.0.dev21
 Summary: Bridging statistical cultures with some jazz
 Author: Eshin Jolly
 License-Expression: MIT

bossanova-0.1.0.dev21/bossanova/distributions/__init__.py

@@ -0,0 +1,63 @@
+"""Distribution factories for simulation and probability queries.
+
+Users get rich Distribution objects with plotting, algebra, and probability::
+
+    d = normal(0, 1)
+    d               # In notebooks: renders PDF plot
+    d + normal(3, 2)  # Convolution -> Normal(3, sqrt(5))
+    d > 1.96        # P(X > 1.96) = 0.025
+    d.pdf(0)        # 0.3989
+"""
+
+from bossanova.distributions.continuous import (
+    Distribution,
+    exponential,
+    gamma,
+    normal,
+    t,
+    t_dist,
+    uniform,
+)
+from bossanova.distributions.discrete import (
+    Categorical,
+    binomial,
+    categorical,
+    poisson,
+)
+from bossanova.distributions.varying import Varying, varying
+
+# Rich internal types also available
+from bossanova.internal.maths.distributions import (
+    ConvolvedDistribution,
+    f_dist,
+    FoldedDistribution,
+    Probability,
+    TransformedDistribution,
+    TruncatedDistribution,
+    beta,
+    chi2,
+)
+
+__all__ = [
+    "Categorical",
+    "ConvolvedDistribution",
+    "Distribution",
+    "FoldedDistribution",
+    "Probability",
+    "TransformedDistribution",
+    "TruncatedDistribution",
+    "Varying",
+    "beta",
+    "binomial",
+    "categorical",
+    "chi2",
+    "exponential",
+    "f_dist",
+    "gamma",
+    "normal",
+    "poisson",
+    "t",
+    "t_dist",
+    "uniform",
+    "varying",
+]

bossanova-0.1.0.dev21/bossanova/distributions/continuous.py

@@ -0,0 +1,45 @@
+"""Continuous distribution factories — thin facade over internal/maths/distributions/.
+
+Re-exports internal Distribution factories with user-facing parameterization.
+Users get rich Distribution objects with plotting, algebra, and probability queries.
+"""
+
+from bossanova.internal.maths.distributions.base import Distribution
+from bossanova.internal.maths.distributions.factories import (
+    exponential,
+    gamma as _internal_gamma,
+    normal,
+    t,
+    t_dist,
+    uniform,
+)
+
+
+def gamma(shape: float, scale: float = 1.0) -> Distribution:
+    """Create a gamma distribution (scale parameterization only).
+
+    Args:
+        shape: Shape parameter (must be positive).
+        scale: Scale parameter (must be positive). Default is 1.0.
+
+    Returns:
+        Distribution object.
+
+    Examples:
+        ```python
+        g = gamma(shape=2.0)  # Gamma(2, 1), mean = 2
+        g = gamma(shape=2.0, scale=0.5)  # Gamma(2, 0.5), mean = 1
+        ```
+    """
+    return _internal_gamma(shape=shape, scale=scale)
+
+
+__all__ = [
+    "Distribution",
+    "exponential",
+    "gamma",
+    "normal",
+    "t",
+    "t_dist",
+    "uniform",
+]

bossanova-0.1.0.dev21/bossanova/distributions/discrete.py

@@ -0,0 +1,217 @@
+"""Discrete distribution factories — thin facade.
+
+Categorical stays as a native attrs struct (no internal counterpart).
+Poisson and Binomial delegate to internal Distribution objects.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from attrs import frozen, field
+from scipy import stats
+
+from bossanova.internal.maths.distributions.base import Distribution
+
+
+@frozen
+class Categorical:
+    """Categorical distribution for simulation.
+
+    Generates categorical values from specified levels with optional probabilities.
+
+    Args:
+        levels: Category names. Either provide explicit levels or use k= for auto-naming.
+        p: Probabilities for each level. Must sum to 1. If None, uniform distribution.
+        k: Number of levels for auto-naming (level_1, level_2, ...).
+            Ignored if levels is provided.
+
+    Raises:
+        ValueError: If neither levels nor k is provided.
+        ValueError: If both levels and k are provided.
+        ValueError: If p is provided without levels.
+        ValueError: If the length of p does not match the length of levels.
+        ValueError: If p does not sum to 1.
+
+    Examples:
+        ```python
+        from bossanova.distributions import categorical
+
+        cat = categorical(levels=["A", "B", "C"])
+        rng = np.random.default_rng(42)
+        samples = cat.sample(5, rng)  # shape (5,)
+
+        cat = categorical(levels=["A", "B"], p=[0.8, 0.2])  # mostly "A"
+
+        cat = categorical(k=4)  # level_1, level_2, level_3, level_4
+        ```
+    """
+
+    levels: tuple[str, ...] | None = field(
+        default=None, converter=lambda x: tuple(x) if x is not None else None
+    )
+    p: tuple[float, ...] | None = field(
+        default=None, converter=lambda x: tuple(x) if x is not None else None
+    )
+    k: int | None = field(default=None)
+
+    def __attrs_post_init__(self) -> None:
+        """Validate that levels/k and p are consistent."""
+        # Must have either levels or k
+        if self.levels is None and self.k is None:
+            msg = "Must specify either levels or k"
+            raise ValueError(msg)
+        if self.levels is not None and self.k is not None:
+            msg = "Specify either levels or k, not both"
+            raise ValueError(msg)
+
+        # Validate p if provided
+        if self.p is not None:
+            if self.levels is None:
+                msg = "p requires levels to be specified"
+                raise ValueError(msg)
+            if len(self.p) != len(self.levels):
+                msg = f"p length ({len(self.p)}) must match levels length ({len(self.levels)})"
+                raise ValueError(msg)
+            if not np.isclose(sum(self.p), 1.0):
+                msg = f"p must sum to 1.0, got {sum(self.p)}"
+                raise ValueError(msg)
+
+    @property
+    def actual_levels(self) -> tuple[str, ...]:
+        """Return the actual level names (resolving k if needed)."""
+        if self.levels is not None:
+            return self.levels
+        return tuple(f"level_{i + 1}" for i in range(self.k))  # type: ignore[arg-type]
+
+    @property
+    def n_levels(self) -> int:
+        """Return the number of levels."""
+        return len(self.actual_levels)
+
+    def sample(self, n: int, rng: np.random.Generator) -> np.ndarray:
+        """Sample n categorical values.
+
+        Args:
+            n: Number of samples to draw.
+            rng: NumPy random number generator.
+
+        Returns:
+            Array of n categorical values as strings.
+        """
+        levels = self.actual_levels
+        probs = self.p if self.p is not None else None
+        indices = rng.choice(len(levels), size=n, p=probs)
+        return np.array([levels[i] for i in indices])
+
+
+# =============================================================================
+# Factory functions
+# =============================================================================
+
+
+def categorical(
+    levels: list[str] | None = None,
+    *,
+    p: list[float] | None = None,
+    k: int | None = None,
+) -> Categorical:
+    """Create a categorical distribution.
+
+    Args:
+        levels: Category names. Either provide explicit levels or use k= for
+            auto-naming (level_1, level_2, ...). Mutually exclusive with k.
+        p: Probabilities for each level. Must sum to 1. Length must match
+            levels. If None, a uniform distribution over levels is used.
+            Requires levels to be specified.
+        k: Number of levels for auto-naming (level_1, level_2, ...).
+            Mutually exclusive with levels.
+
+    Returns:
+        Categorical distribution object.
+
+    Raises:
+        ValueError: If neither levels nor k is provided.
+        ValueError: If both levels and k are provided.
+        ValueError: If p is provided without levels.
+        ValueError: If the length of p does not match the length of levels.
+        ValueError: If p does not sum to 1.
+
+    Examples:
+        ```python
+        categorical(["A", "B", "C"])
+        # Categorical(levels=('A', 'B', 'C'), p=None, k=None)
+
+        categorical(["A", "B"], p=[0.7, 0.3])
+        # Categorical(levels=('A', 'B'), p=(0.7, 0.3), k=None)
+
+        categorical(k=4)  # level_1, level_2, level_3, level_4
+        # Categorical(levels=None, p=None, k=4)
+        ```
+    """
+    return Categorical(levels=levels, p=p, k=k)
+
+
+def poisson(rate: float = 1.0) -> Distribution:
+    """Create a Poisson distribution.
+
+    Args:
+        rate: Rate parameter (lambda). Must be > 0. Default is 1.0.
+
+    Returns:
+        Distribution object.
+
+    Raises:
+        ValueError: If rate is not positive.
+
+    Examples:
+        ```python
+        dist = poisson()           # Poisson(1)
+        dist = poisson(rate=5.0)   # Poisson(5), mean = 5
+        ```
+    """
+    if rate <= 0:
+        raise ValueError("rate must be > 0")
+    return Distribution(
+        dist=stats.poisson(mu=rate),
+        name="Poisson",
+        params={"rate": rate},
+    )
+
+
+def binomial(n: int = 1, p: float = 0.5) -> Distribution:
+    """Create a binomial distribution.
+
+    Args:
+        n: Number of trials. Must be >= 1. Default is 1 (Bernoulli).
+        p: Probability of success. Must be in [0, 1]. Default is 0.5.
+
+    Returns:
+        Distribution object.
+
+    Raises:
+        ValueError: If n is not an integer >= 1 or p is not in [0, 1].
+
+    Examples:
+        ```python
+        dist = binomial()              # Bernoulli(0.5)
+        dist = binomial(n=10, p=0.3)   # Binomial(10, 0.3), mean = 3
+        ```
+    """
+    if not isinstance(n, int) or n < 1:
+        raise ValueError("n must be an integer >= 1")
+    if not 0 <= p <= 1:
+        raise ValueError(f"p ({p}) must be in [0, 1]")
+    return Distribution(
+        dist=stats.binom(n=n, p=p),
+        name="Binomial",
+        params={"n": n, "p": p},
+    )
+
+
+__all__ = [
+    "Categorical",
+    "Distribution",
+    "binomial",
+    "categorical",
+    "poisson",
+]

{bossanova-0.1.0.dev19 → bossanova-0.1.0.dev21}/bossanova/distributions/varying.py

@@ -3,6 +3,8 @@
 from attrs import frozen, field, validators
 import numpy as np
 
+__all__ = ["Varying", "varying"]
+
 
 @frozen
 class Varying:
@@ -15,27 +17,22 @@ class Varying:
         sd (float): Standard deviation for random intercept. Default 1.0.
         intercept_sd (float | None): Alias for sd (for clarity with random slopes).
         slope_sds (dict[str, float]): Dict mapping term names to their random slope SDs.
-        corr (float | dict[tuple[str, str], float]): Correlation between intercept
-            and slope(s). Single value or dict.
+        corr (float): Correlation between intercept and slope(s). Applied
+            uniformly across all term pairs. Default 0.0.
         n_per (int | None): For nested effects, number of sub-groups per parent group.
 
     Examples:
-        Random intercept only: (1|subject)::
-
-            >>> varying(n=50, sd=0.3)
-            Varying(n=50, sd=0.3, ...)
-
-        Random intercept + slope: (1 + time|subject)::
-
-            >>> varying(n=50, intercept_sd=0.3, slope_sds={"time": 0.1}, corr=0.2)
-            Varying(n=50, intercept_sd=0.3, slope_sds={'time': 0.1}, corr=0.2, ...)
+        ```python
+        # Random intercept only: (1|subject)
+        varying(n=50, sd=0.3)
 
-        Nested effects: (1|school/class) - 3 classes per school::
+        # Random intercept + slope: (1 + time|subject)
+        varying(n=50, intercept_sd=0.3, slope_sds={"time": 0.1}, corr=0.2)
 
-            >>> varying(n=10, sd=0.4)  # schools
-            Varying(n=10, sd=0.4, ...)
-            >>> varying(n_per=3, sd=0.2)  # classes nested in schools
-            Varying(n_per=3, sd=0.2, ...)
+        # Nested effects: (1|school/class) - 3 classes per school
+        varying(n=10, sd=0.4)     # schools
+        varying(n_per=3, sd=0.2)  # classes nested in schools
+        ```
     """
 
     n: int | None = field(default=None)
@@ -44,7 +41,7 @@ class Varying:
     # For random slopes
     intercept_sd: float | None = field(default=None)
     slope_sds: dict[str, float] = field(factory=dict)
-    corr: float | dict[tuple[str, str], float] = field(default=0.0)
+    corr: float = field(default=0.0)
 
     # For nested effects
     n_per: int | None = field(default=None)
@@ -72,15 +69,15 @@ class Varying:
                 raise ValueError(msg)
 
         # Validate correlation
-        if isinstance(self.corr, (int, float)):
-            if not -1 <= self.corr <= 1:
-                msg = f"corr must be in [-1, 1], got {self.corr}"
-                raise ValueError(msg)
-        elif isinstance(self.corr, dict):
-            for key, val in self.corr.items():
-                if not -1 <= val <= 1:
-                    msg = f"corr[{key}] must be in [-1, 1], got {val}"
-                    raise ValueError(msg)
+        if isinstance(self.corr, dict):
+            msg = (
+                "Dict-form corr is not yet supported. "
+                "Use a single scalar value for uniform correlation across all pairs."
+            )
+            raise NotImplementedError(msg)
+        if not -1 <= self.corr <= 1:
+            msg = f"corr must be in [-1, 1], got {self.corr}"
+            raise ValueError(msg)
 
     @property
     def effective_intercept_sd(self) -> float:
@@ -160,15 +157,8 @@ class Varying:
             self.slope_sds[t] for t in sorted(self.slope_sds)
         ]
 
-        if isinstance(self.corr, (int, float)):
-            # Single correlation for all pairs
-            corr_matrix = np.full((n_terms, n_terms), self.corr)
-            np.fill_diagonal(corr_matrix, 1.0)
-        else:
-            # Build from dict - default to 0 for unspecified pairs
-            corr_matrix = np.eye(n_terms)
-            # Note: dict-based correlation not fully implemented for simplicity
-            # Users should use single corr value for now
+        corr_matrix = np.full((n_terms, n_terms), self.corr)
+        np.fill_diagonal(corr_matrix, 1.0)
 
         # Convert correlation to covariance: Cov = D @ Corr @ D
         D = np.diag(sds)
@@ -183,7 +173,7 @@ def varying(
     sd: float = 1.0,
     intercept_sd: float | None = None,
     slope_sds: dict[str, float] | None = None,
-    corr: float | dict[tuple[str, str], float] = 0.0,
+    corr: float = 0.0,
     n_per: int | None = None,
 ) -> Varying:
     """Create a varying (random effect) distribution specification.
@@ -197,37 +187,28 @@ def varying(
         intercept_sd (float | None): Alias for sd (for clarity with random slopes).
         slope_sds (dict[str, float] | None): Dict mapping term names to their
             random slope SDs.
-        corr (float | dict[tuple[str, str], float]): Correlation between intercept
-            and slope(s). Single value or dict.
+        corr (float): Correlation between intercept and slope(s). Applied
+            uniformly across all term pairs. Default 0.0.
         n_per (int | None): For nested effects, number of sub-groups per parent group.
 
     Returns:
         Varying specification for use in model.simulate().
 
     Examples:
-        Random intercept only: (1|subject)::
-
-            >>> from bossanova.distributions import varying
-            >>> v = varying(n=50, sd=0.3)
-            >>> v.n
-            50
-            >>> v.sd
-            0.3
-
-        Random intercept + slope: (1 + time|subject)::
+        ```python
+        from bossanova.distributions import varying
 
-            >>> v = varying(n=50, intercept_sd=0.3, slope_sds={"time": 0.1}, corr=0.2)
-            >>> v.has_random_slopes
-            True
-            >>> v.n_terms
-            2
+        # Random intercept only: (1|subject)
+        v = varying(n=50, sd=0.3)  # v.n == 50, v.sd == 0.3
 
-        Nested effects: (1|school/class) - 3 classes per school::
+        # Random intercept + slope: (1 + time|subject)
+        v = varying(n=50, intercept_sd=0.3, slope_sds={"time": 0.1}, corr=0.2)
+        # v.has_random_slopes == True, v.n_terms == 2
 
-            >>> schools = varying(n=10, sd=0.4)  # schools
-            >>> classes = varying(n_per=3, sd=0.2)  # classes nested in schools
-            >>> classes.is_nested
-            True
+        # Nested effects: (1|school/class) - 3 classes per school
+        schools = varying(n=10, sd=0.4)
+        classes = varying(n_per=3, sd=0.2)  # classes.is_nested == True
+        ```
     """
     return Varying(
         n=n,

{bossanova-0.1.0.dev19 → bossanova-0.1.0.dev21}/bossanova/internal/__init__.py

@@ -1 +1,3 @@
 """Internal implementation modules — not part of the public API."""
+
+__all__: list[str] = []

{bossanova-0.1.0.dev19 → bossanova-0.1.0.dev21}/bossanova/internal/compare/compare.py

@@ -82,7 +82,7 @@ def compare(
             - "aic": AIC comparison with delta-AIC and Akaike weights
             - "bic": BIC comparison with delta-BIC and Schwarz weights
         sort: If True, sort models by complexity before comparing.
-            This ensures proper nesting order.
+            This ensures proper nesting order. Default True.
         refit: If True and models are lmer/glmer with REML estimation,
             automatically refit with ML for valid LRT comparison.
             Original models are not mutated. Default False.
@@ -157,34 +157,38 @@ def compare(
 
     Examples:
         ```python
+        from bossanova import model, compare, load_dataset
+        mtcars = load_dataset("mtcars")
+        sleepstudy = load_dataset("sleepstudy")
+
         # Models are auto-fitted if needed (calls .fit() with defaults)
-        compare(lm("mpg ~ 1", data=mtcars), lm("mpg ~ wt", data=mtcars))
+        compare(model("mpg ~ 1", mtcars), model("mpg ~ wt", mtcars))
 
         # Equivalent to explicit .fit() calls:
-        compare(lm("mpg ~ 1", data=mtcars).fit(), lm("mpg ~ wt", data=mtcars).fit())
+        compare(model("mpg ~ 1", mtcars).fit(), model("mpg ~ wt", mtcars).fit())
 
         # Model objects are fitted in-place, so they're usable after compare()
-        compact = lm("mpg ~ 1", data=mtcars)
-        full = lm("mpg ~ wt", data=mtcars)
+        compact = model("mpg ~ 1", mtcars)
+        full = model("mpg ~ wt", mtcars)
         compare(compact, full)
-        full.coef_  # Works - model was auto-fitted
+        full.params  # Works - model was auto-fitted
 
         # glm example (deviance test)
         compare(
-            glm("am ~ 1", data=mtcars, family="binomial"),
-            glm("am ~ wt", data=mtcars, family="binomial"),
+            model("am ~ 1", mtcars, family="binomial"),
+            model("am ~ wt", mtcars, family="binomial"),
         )
 
         # lmer example (likelihood ratio test)
         compare(
-            lmer("Reaction ~ Days + (1|Subject)", data=sleepstudy),
-            lmer("Reaction ~ Days + (Days|Subject)", data=sleepstudy),
+            model("Reaction ~ Days + (1|Subject)", sleepstudy).fit(method="ML"),
+            model("Reaction ~ Days + (Days|Subject)", sleepstudy).fit(method="ML"),
         )
 
         # CV example (Nadeau-Bengio corrected)
         compare(
-            lm("mpg ~ 1", data=mtcars),
-            lm("mpg ~ wt", data=mtcars),
+            model("mpg ~ 1", mtcars),
+            model("mpg ~ wt", mtcars),
             method="cv", cv=5, seed=42,
         )
         ```
@@ -218,7 +222,6 @@ def compare(
 
     See Also:
         - lrt: Likelihood ratio test for mixed models
-        - anova: Type I/II/III ANOVA tables
     """
     # Validate and auto-fit models (pass method and refit for REML check)
     models = validate_models(models, method=method, refit=refit)

{bossanova-0.1.0.dev19 → bossanova-0.1.0.dev21}/bossanova/internal/compare/cv.py

@@ -66,7 +66,7 @@ def compute_cv_fold_score(
 
     # Predict on test data
     new_model.predict(newdata=test_data)
-    y_pred = new_model.predictions["fitted"].to_numpy()
+    y_pred = new_model.predictions[Col.FITTED].to_numpy()
 
     # Get actual test values
     y_true = test_data[model._spec.response_var].to_numpy()
@@ -104,13 +104,13 @@ def compare_cv(
     Returns:
         DataFrame with columns:
         - model: Formula string
+        - PRE: Proportional reduction in error
+        - t_stat: Nadeau-Bengio corrected t-statistic
         - cv_score: Mean CV score (error)
         - cv_se: Standard error of CV score
         - diff: Difference from reference model (first model)
         - diff_se: Corrected standard error of difference
-        - t_stat: Nadeau-Bengio corrected t-statistic
         - p_value: Two-sided p-value
-        - PRE: Proportional reduction in error
 
     Notes:
         The Nadeau-Bengio correction accounts for the fact that k-fold CV

{bossanova-0.1.0.dev19 → bossanova-0.1.0.dev21}/bossanova/internal/compare/deviance.py

@@ -51,14 +51,23 @@ def compare_deviance(models: list[Any], test: str = "chisq") -> pl.DataFrame:
         test: Test type: "chisq" for chi-squared test (default), "f" for F-test.
 
     Returns:
-        DataFrame with columns:
+        DataFrame with columns (test="chisq"):
         - model: Formula string
-        - df_resid: Residual degrees of freedom
+        - chi2: Chi-squared statistic (deviance difference)
+        - dev_diff: Deviance difference (reduction)
         - deviance: Residual deviance
         - df: Degrees of freedom for this comparison
+        - df_resid: Residual degrees of freedom
+        - p_value: p-value from chi-squared distribution
+
+        DataFrame with columns (test="f"):
+        - model: Formula string
+        - F: F-statistic
         - dev_diff: Deviance difference (reduction)
-        - statistic: Chi-squared or F statistic
-        - p_value: p-value from chi-squared or F distribution
+        - deviance: Residual deviance
+        - df: Degrees of freedom for this comparison
+        - df_resid: Residual degrees of freedom
+        - p_value: p-value from F distribution
 
     Notes:
         The deviance difference follows a chi-squared distribution with df degrees

{bossanova-0.1.0.dev19 → bossanova-0.1.0.dev21}/bossanova/internal/compare/helpers.py

@@ -6,11 +6,7 @@ used across all comparison strategies (F-test, deviance, LRT, CV).
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Any
-
-
-if TYPE_CHECKING:
-    pass
+from typing import Any
 
 __all__ = [
     "check_nested",
@@ -154,13 +150,12 @@ def sort_models_by_complexity(models: tuple[Any, ...]) -> list[Any]:
 def resolve_method(model: Any) -> str:
     """Infer the appropriate comparison method for a model type.
 
-    Uses :func:`classify_model_type` to canonically determine the model type
-    from its family and random-effects structure, then maps to the
-    corresponding comparison method.
+    Reads ``model._model_type`` to determine the model type and maps it
+    to the corresponding comparison method.
 
     Args:
-        model: A fitted model object with a ``_spec`` attribute containing
-            ``family`` and ``has_random_effects``.
+        model: A fitted model object with a ``_model_type`` attribute
+            (one of ``"lm"``, ``"glm"``, ``"lmer"``, ``"glmer"``).
 
     Returns:
         Comparison method: ``"f"`` for lm, ``"lrt"`` for lmer/glmer,