bossanova 0.1.0.dev0__tar.gz

bossanova-0.1.0.dev0/.gitignore

@@ -0,0 +1,69 @@
+__pycache__/
+.ruff*
+.pytest_cache/
+sdist/
+*.egg-info/
+*.egg
+.venv/
+dev
+*.DS*
+research/
+plans/
+archive/
+.private-journal
+
+_build/
+docs/_build/
+docs/performance/
+profile*.py
+benchmarks/
+examples/
+papers/
+paper-summaries/
+prompts/
+experiments/
+!experiments/banded_ridge_lmer_mvp.py
+ideas/
+bambi/
+burntends/tests/*.csv
+lmer-refactor-notes/
+scripts/
+*.txt
+*.json
+!tests/pyodide/package.json
+*.png
+
+# Node.js (for Pyodide tests)
+node_modules/
+
+# Parity testing traces
+tests/parity/traces/
+
+# Coverage reports
+coverage_reports/
+.coverage
+htmlcov/
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+tests/**/*.csv
+bossanova-docs/_site/
+bossanova-docs/_freeze/
+bossanova-docs/.jupyter_cache/
+bossanova-docs/**/.jupyter_cache/
+claude-logs/
+.beads/
+benchmarking
+
+# Build artifacts
+build/
+dist/
+
+# Logs
+*.log
+bossanova-docs/reference/
+
+# Refs
+MixedModels.jl/
+lme4/
+.env*

bossanova-0.1.0.dev0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Eshin Jolly, SciMinds Research Studio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bossanova-0.1.0.dev0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: bossanova
+Version: 0.1.0.dev0
+Summary: Bridging statistical cultures with some jazz
+Author: Eshin Jolly
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analysis,multi-level-modeling,regression,statistics
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.11
+Requires-Dist: jax>=0.8.0
+Requires-Dist: joblib>=1.3.0
+Requires-Dist: nlopt>=2.9.0
+Requires-Dist: numpy>=2.3.4
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: polars>=1.0.0
+Requires-Dist: pyarrow>=14.0.0
+Requires-Dist: scikit-sparse>=0.4.16
+Requires-Dist: scipy>=1.14.0
+Requires-Dist: tqdm>=4.66.0
+Description-Content-Type: text/markdown
+
+# Bossanova
+
+Bridging statistical cultures with some jazz.

bossanova-0.1.0.dev0/README.md

@@ -0,0 +1,3 @@
+# Bossanova
+
+Bridging statistical cultures with some jazz.

bossanova-0.1.0.dev0/bossanova/__init__.py

@@ -0,0 +1,86 @@
+"""bossanova - Clean Python implementation of R's formula-based statistical models.
+
+A modern Python library providing formula-based model fitting for:
+
+- lm: Linear models (OLS regression)
+- glm: Generalized linear models (logistic, Poisson, etc.)
+- lmer: Linear mixed-effects models
+- glmer: Generalized linear mixed-effects models
+
+Examples:
+    >>> from bossanova import lm
+    >>> model = lm("mpg ~ wt + hp", data=mtcars)
+    >>> model.fit()
+    >>> model.summary()
+
+Backend Selection:
+    By default, bossanova uses JAX for optimal performance. You can switch
+    to NumPy before fitting any models:
+
+    >>> import bossanova
+    >>> bossanova.set_backend("numpy")
+    >>> model = bossanova.lm("y ~ x", data=df).fit()
+"""
+
+# Backend API (must be imported first, before any JAX usage)
+from bossanova._backend import backend, get_backend, set_backend
+
+# Configure JAX x64 eagerly if JAX is available
+# This MUST happen before any JAX arrays are created anywhere in the codebase.
+# We cannot defer this to lazy loading because submodules (e.g., lmer_core.py)
+# import JAX at module level and would create float32 arrays otherwise.
+try:
+    import jax
+
+    jax.config.update("jax_enable_x64", True)
+except ImportError:
+    pass  # JAX not available, will use numpy backend
+
+# Configuration
+from bossanova._config import (  # noqa: E402
+    get_singular_tolerance,
+    set_singular_tolerance,
+)
+
+# Data loading
+from bossanova.data import (  # noqa: E402
+    load_dataset,
+    show_datasets,
+)
+
+# Models
+from bossanova.models import glm, glmer, lm, lmer, ridge  # noqa: E402
+
+# Statistics
+from bossanova.stats import compare, lrt  # noqa: E402
+
+# Visualization
+from bossanova import viz  # noqa: E402
+
+__all__ = [
+    # Backend
+    "get_backend",
+    "set_backend",
+    "backend",
+    # Models
+    "lm",
+    "glm",
+    "lmer",
+    "glmer",
+    "ridge",
+    # Model comparison
+    "compare",
+    "lrt",
+    # Data loading
+    "load_dataset",
+    "show_datasets",
+    # Configuration
+    "get_singular_tolerance",
+    "set_singular_tolerance",
+    # Visualization
+    "viz",
+]
+
+from importlib.metadata import version as _get_version
+
+__version__ = _get_version("bossanova")

bossanova-0.1.0.dev0/bossanova/_backend.py

@@ -0,0 +1,183 @@
+"""Backend detection and switching for bossanova.
+
+This module provides the infrastructure for switching between JAX and NumPy
+backends at runtime. The backend is auto-detected on first use but can be
+explicitly set before any model fitting occurs.
+
+Examples:
+    >>> import bossanova
+    >>> bossanova.get_backend()
+    'jax'
+    >>> bossanova.set_backend("numpy")
+    >>> bossanova.get_backend()
+    'numpy'
+"""
+
+import sys
+from contextlib import contextmanager
+from typing import Literal
+
+BackendName = Literal["jax", "numpy"]
+
+# Global state
+_backend: BackendName | None = None
+_backend_locked: bool = False
+
+
+def _detect_backend() -> BackendName:
+    """Auto-detect the best available backend.
+
+    Detection order:
+    1. If running in Pyodide (emscripten), use numpy (JAX not available)
+    2. Try to import JAX - if successful, use jax
+    3. Fall back to numpy
+
+    Returns:
+        The detected backend name.
+    """
+    # Pyodide detection
+    if sys.platform == "emscripten":
+        return "numpy"
+
+    # Try JAX
+    try:
+        import jax
+
+        # Enable float64 precision - must be done before any array creation
+        jax.config.update("jax_enable_x64", True)
+        return "jax"
+    except ImportError:
+        return "numpy"
+
+
+def get_backend() -> BackendName:
+    """Get the current backend name.
+
+    If no backend has been explicitly set, auto-detects the best available
+    backend on first call.
+
+    Returns:
+        The current backend name ('jax' or 'numpy').
+
+    Examples:
+        >>> import bossanova
+        >>> bossanova.get_backend()
+        'jax'
+    """
+    global _backend
+    if _backend is None:
+        _backend = _detect_backend()
+    return _backend
+
+
+def set_backend(name: BackendName) -> None:
+    """Set the backend to use for computations.
+
+    Must be called before any model fitting occurs. Once a model has been
+    fitted, the backend is locked and cannot be changed.
+
+    Args:
+        name: Backend name, either 'jax' or 'numpy'.
+
+    Raises:
+        RuntimeError: If called after a model has been fitted.
+        ValueError: If name is not 'jax' or 'numpy'.
+        ImportError: If 'jax' is requested but JAX is not installed.
+
+    Examples:
+        >>> import bossanova
+        >>> bossanova.set_backend("numpy")
+        >>> bossanova.get_backend()
+        'numpy'
+    """
+    global _backend, _backend_locked
+    if _backend_locked:
+        raise RuntimeError(
+            "Cannot change backend after models have been fitted. "
+            "Call set_backend() before any model fitting."
+        )
+    if name not in ("jax", "numpy"):
+        raise ValueError(f"Unknown backend: {name}. Use 'jax' or 'numpy'.")
+
+    # Validate JAX availability early if requested
+    if name == "jax":
+        try:
+            import jax
+
+            jax.config.update("jax_enable_x64", True)
+        except ImportError as e:
+            raise ImportError(
+                "JAX is not installed. Install it with 'pip install jax jaxlib' "
+                "or use set_backend('numpy')."
+            ) from e
+
+    _backend = name
+
+
+def _lock_backend() -> None:
+    """Lock the backend to prevent switching after model fitting.
+
+    This is called internally when models are fitted to ensure consistent
+    behavior throughout a session.
+    """
+    global _backend, _backend_locked
+    # Ensure backend is initialized before locking
+    if _backend is None:
+        _backend = _detect_backend()
+    _backend_locked = True
+
+
+def _is_backend_locked() -> bool:
+    """Check if the backend is locked.
+
+    Returns:
+        True if backend is locked, False otherwise.
+    """
+    return _backend_locked
+
+
+def _reset_backend() -> None:
+    """Reset backend state (for testing only).
+
+    Warning:
+        This should only be used in tests. Using it in production code
+        can lead to inconsistent behavior.
+    """
+    global _backend, _backend_locked
+    _backend = None
+    _backend_locked = False
+
+
+@contextmanager
+def backend(name: BackendName):
+    """Context manager for temporary backend switching.
+
+    This is primarily intended for testing. It temporarily switches the
+    backend and restores the previous state on exit.
+
+    Args:
+        name: Backend name to use within the context.
+
+    Yields:
+        None
+
+    Examples:
+        >>> import bossanova
+        >>> with bossanova.backend("numpy"):
+        ...     print(bossanova.get_backend())
+        'numpy'
+    """
+    global _backend, _backend_locked
+    old_backend = _backend
+    old_locked = _backend_locked
+
+    # Temporarily switch
+    _backend = name
+    _backend_locked = False
+
+    try:
+        yield
+    finally:
+        # Restore previous state
+        _backend = old_backend
+        _backend_locked = old_locked

bossanova-0.1.0.dev0/bossanova/_config.py

@@ -0,0 +1,48 @@
+"""Global configuration for bossanova.
+
+This module provides package-wide configuration settings that can be modified
+at runtime. Currently manages singular tolerance for mixed models.
+"""
+
+# Default singular tolerance matches lme4's default (utilities.R:924-928)
+_SINGULAR_TOLERANCE: float = 1e-4
+
+
+def get_singular_tolerance() -> float:
+    """Get the current singular tolerance for mixed models.
+
+    The singular tolerance is used by `isSingular()` to determine if a mixed
+    model fit is singular (has variance components at or near zero).
+
+    Returns:
+        The current singular tolerance threshold.
+
+    Examples:
+        >>> from bossanova import get_singular_tolerance
+        >>> get_singular_tolerance()
+        0.0001
+    """
+    return _SINGULAR_TOLERANCE
+
+
+def set_singular_tolerance(tol: float) -> None:
+    """Set the global singular tolerance for mixed models.
+
+    The singular tolerance is used by `isSingular()` to determine if a mixed
+    model fit is singular. Values below this threshold are considered
+    effectively zero.
+
+    Args:
+        tol: New tolerance threshold. Must be positive.
+
+    Raises:
+        ValueError: If tol is not positive.
+
+    Examples:
+        >>> from bossanova import set_singular_tolerance
+        >>> set_singular_tolerance(1e-6)  # More strict threshold
+    """
+    global _SINGULAR_TOLERANCE
+    if tol <= 0:
+        raise ValueError(f"Tolerance must be positive, got {tol}")
+    _SINGULAR_TOLERANCE = tol

bossanova-0.1.0.dev0/bossanova/_parser/__init__.py

@@ -0,0 +1,53 @@
+"""Formula parsing infrastructure.
+
+This module provides a recursive descent parser for statistical formula strings
+(e.g., "y ~ x1 + x2 * group"). It is vendored from the formulae library.
+
+Public API:
+    Scanner: Tokenize formula strings into Token objects.
+    Parser: Parse Token sequences into AST nodes.
+    ScanError: Raised when scanning fails.
+    ParseError: Raised when parsing fails.
+
+AST Node Types:
+    Variable: Variable reference (e.g., "x")
+    Literal: Literal value (numbers, strings)
+    Binary: Binary operation (e.g., "x + y", "x ~ y")
+    Unary: Unary operation (e.g., "-x")
+    Call: Function call (e.g., "C(x)", "center(y)")
+    Grouping: Parenthesized expression
+    QuotedName: Back-quoted name (e.g., "`weird name`")
+    Assign: Assignment expression (e.g., "reference='A'")
+    Token: Single token from scanner.
+
+Examples:
+    >>> from bossanova._parser import Scanner, Parser
+    >>> tokens = Scanner("y ~ x1 + x2").scan()
+    >>> ast = Parser(tokens).parse()
+    >>> ast
+    Binary(left=Literal(value=1), op='~', right=...)
+"""
+
+from .expr import Assign, Binary, Call, Grouping, Literal, QuotedName, Unary, Variable
+from .parser import ParseError, Parser
+from .scanner import ScanError, Scanner
+from .token import Token
+
+__all__ = [
+    # Scanner/Parser
+    "Scanner",
+    "Parser",
+    "ScanError",
+    "ParseError",
+    # Token
+    "Token",
+    # AST Nodes
+    "Assign",
+    "Binary",
+    "Call",
+    "Grouping",
+    "Literal",
+    "QuotedName",
+    "Unary",
+    "Variable",
+]

bossanova-0.1.0.dev0/bossanova/_parser/expr.py

@@ -0,0 +1,148 @@
+"""AST expression node types for formula parsing.
+
+Vendored from formulae library (https://github.com/bambinos/formulae).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .token import Token
+
+
+class Assign:
+    """Expression for assignments (e.g., x=value in function calls)."""
+
+    def __init__(self, name: Variable, value: object) -> None:
+        self.name = name
+        self.value = value
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Assign):
+            return NotImplemented
+        return self.name == other.name and self.value == other.value
+
+    def __repr__(self) -> str:
+        return f"Assign(name={self.name}, value={self.value})"
+
+
+class Grouping:
+    """Expression for parenthesized groups."""
+
+    def __init__(self, expression: object) -> None:
+        self.expression = expression
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Grouping):
+            return NotImplemented
+        return self.expression == other.expression
+
+    def __repr__(self) -> str:
+        return f"Grouping({self.expression})"
+
+
+class Binary:
+    """Expression for binary operations (e.g., x + y, x ~ y)."""
+
+    def __init__(self, left: object, operator: Token, right: object) -> None:
+        self.left = left
+        self.operator = operator
+        self.right = right
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Binary):
+            return NotImplemented
+        return (
+            self.left == other.left
+            and self.operator == other.operator
+            and self.right == other.right
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"Binary(left={self.left}, op={self.operator.lexeme!r}, right={self.right})"
+        )
+
+
+class Unary:
+    """Expression for unary operations (e.g., -x, +x)."""
+
+    def __init__(self, operator: Token, right: object) -> None:
+        self.operator = operator
+        self.right = right
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Unary):
+            return NotImplemented
+        return self.operator == other.operator and self.right == other.right
+
+    def __repr__(self) -> str:
+        return f"Unary(op={self.operator.lexeme!r}, right={self.right})"
+
+
+class Call:
+    """Expression for function calls (e.g., C(x), center(y))."""
+
+    def __init__(self, callee: object, args: list) -> None:
+        self.callee = callee
+        self.args = args
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Call):
+            return NotImplemented
+        return self.callee == other.callee and self.args == other.args
+
+    def __repr__(self) -> str:
+        return f"Call(callee={self.callee}, args={self.args})"
+
+
+class Variable:
+    """Expression for variable references."""
+
+    def __init__(self, name: Token, level: Literal | None = None) -> None:
+        self.name = name
+        self.level = level
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Variable):
+            return NotImplemented
+        return self.name == other.name and self.level == other.level
+
+    def __repr__(self) -> str:
+        if self.level is not None:
+            return f"Variable(name={self.name.lexeme!r}, level={self.level.value!r})"
+        return f"Variable(name={self.name.lexeme!r})"
+
+
+class QuotedName:
+    """Expression for back-quoted names (e.g., `weird column name!`)."""
+
+    def __init__(self, expression: Token) -> None:
+        self.expression = expression
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, QuotedName):
+            return NotImplemented
+        return self.expression == other.expression
+
+    def __repr__(self) -> str:
+        return f"QuotedName({self.expression.lexeme!r})"
+
+
+class Literal:
+    """Expression for literal values (numbers, strings, etc.)."""
+
+    def __init__(self, value: object, lexeme: str | None = None) -> None:
+        self.value = value
+        self.lexeme = lexeme
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, Literal):
+            return NotImplemented
+        return self.value == other.value and self.lexeme == other.lexeme
+
+    def __repr__(self) -> str:
+        if self.lexeme is not None:
+            return f"Literal(value={self.value!r}, lexeme={self.lexeme!r})"
+        return f"Literal(value={self.value!r})"