bossanova 0.1.0.dev13__tar.gz → 0.1.0.dev15__tar.gz

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/.gitignore

@@ -83,3 +83,4 @@ bossanova-docs/wip/
 .hypothesis/
 research.md
 201b-ghct-05-models/
+emmeans/

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/PKG-INFO

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

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/bossanova/__init__.py

@@ -15,7 +15,9 @@ except (ImportError, AttributeError):
 
 # Configuration
 from bossanova.internal.maths.config import (  # noqa: E402
+    get_display_digits,
     get_singular_tolerance,
+    set_display_digits,
     set_singular_tolerance,
 )
 
@@ -42,11 +44,13 @@ __all__ = [
     "compare",
     "expressions",
     "get_backend",
+    "get_display_digits",
     "get_singular_tolerance",
     "load_dataset",
     "lrt",
     "model",
     "set_backend",
+    "set_display_digits",
     "set_singular_tolerance",
     "show_datasets",
     "viz",

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/bossanova/internal/containers/builders/specs.py

@@ -145,9 +145,9 @@ def build_model_spec_from_formula(
 ) -> ModelSpec:
     """Build ModelSpec by parsing a formula string and resolving defaults.
 
-    Lightweight formula parser that extracts response variable, fixed terms,
+    Parses the formula into an AST to extract response variable, fixed terms,
     and random effect terms without requiring data. Validates formula syntax
-    via Scanner/Parser and resolves estimation method from family and RE.
+    and resolves estimation method from family and RE presence.
 
     Args:
         formula: R-style model formula (e.g., ``"y ~ x + (1|group)"``).
@@ -173,67 +173,27 @@ def build_model_spec_from_formula(
     if "~" not in formula:
         raise ValueError(f"Invalid formula: {formula!r}. Formula must contain '~'.")
 
-    lhs, rhs = formula.split("~", 1)
-    response = strip_backticks(lhs.strip())
-
-    # Handle LHS transforms like rank(y), log(y), zscore(rank(y)) — unwrap all layers
-    while True:
-        lhs_func_match = re.match(r"^([a-zA-Z_]\w*)\((.+)\)$", response)
-        if not lhs_func_match:
-            break
-        response = strip_backticks(lhs_func_match.group(2).strip())
-
-    if not response:
-        raise ValueError(
-            f"Invalid formula: {formula!r}. No response variable specified."
-        )
-
-    # Expand || and / syntax before validation (these are valid lme4 syntax
-    # that the Scanner/Parser doesn't handle directly)
-    from bossanova.internal.operations.formula.parse import (
-        expand_double_verts,
-        expand_nested_syntax,
-    )
-
-    expanded, _ = expand_double_verts(formula)
-    expanded, _ = expand_nested_syntax(expanded)
-
-    # Validate expanded formula syntax via the real parser
-    from bossanova.internal.operations.formula.parser import Parser, Scanner
+    from bossanova.internal.operations.formula.parse import extract_formula_structure
 
     try:
-        tokens = Scanner(expanded).scan(add_intercept=False)
-        Parser(tokens).parse()
+        structure = extract_formula_structure(formula)
     except Exception as exc:
         raise ValueError(f"Invalid formula: {formula!r}. {exc}") from exc
 
-    # Use expanded RHS for RE detection and fixed term extraction
-    _, expanded_rhs = expanded.split("~", 1)
-
-    # Extract random effect terms: patterns like (1|group), (1+x|group), etc.
-    re_pattern = r"\([^)]*\|[^)]*\)"
-    random_terms = tuple(re.findall(re_pattern, expanded_rhs))
-    has_re = len(random_terms) > 0
-
-    # Extract fixed terms by removing random effects from RHS
-    fixed_rhs = re.sub(re_pattern, "", expanded_rhs)
-    raw_terms = [strip_backticks(t.strip()) for t in fixed_rhs.split("+") if t.strip()]
-
-    # Build fixed terms list (add Intercept unless suppressed with 0 or -1)
-    has_intercept = not any(t in ("0", "-1") for t in raw_terms)
-    fixed_terms: list[str] = ["Intercept"] if has_intercept else []
-    fixed_terms.extend(t for t in raw_terms if t not in ("0", "-1", "1"))
-    fixed_terms_tuple = tuple(fixed_terms) if fixed_terms else ("Intercept",)
+    if structure.response_var is None:
+        raise ValueError(
+            f"Invalid formula: {formula!r}. No response variable specified."
+        )
 
     return build_model_spec(
         formula=formula,
         family=family,
         link=link,
         method=method,
-        has_random_effects=has_re,
-        response_var=response,
-        fixed_terms=fixed_terms_tuple,
-        random_terms=random_terms,
+        has_random_effects=structure.has_random_effects,
+        response_var=strip_backticks(structure.response_var),
+        fixed_terms=structure.fixed_term_names,
+        random_terms=structure.random_terms_raw,
     )
 
 

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/bossanova/internal/containers/builders/state.py

@@ -222,7 +222,8 @@ def build_mee_state(
         L_matrix: Design matrix for delta method inference (optional).
             Shape (n_estimates, n_coef). For EMMs this is X_ref.
         contrast_method: Original contrast type for multiplicity adjustment
-            ("pairwise", "revpairwise", "sequential", "poly", or None).
+            ("pairwise", "sequential", "poly", "treatment", "sum",
+            "helmert", or None).
         n_contrast_levels: Number of EMM levels before contrasting (family size).
         link: Link function name for response-scale CI back-transformation.
         L_matrix_link: Link-scale L_matrix for CI back-transformation.

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/bossanova/internal/containers/schemas.py

@@ -34,6 +34,7 @@ __all__ = [
     "ParamsBoot",
     "ParamsCv",
     "ParamsPerm",
+    "PowerSummaryCols",
     "PredictionsAsymp",
     "PredictionsBase",
     "PredictionsCv",
@@ -164,6 +165,20 @@ class Col:
     SIM_MEAN: str = "sim_mean"
     SIM_SD: str = "sim_sd"
 
+    # -- Power analysis --
+    POWER: str = "power"
+    POWER_CI_LOWER: str = "power_ci_lower"
+    POWER_CI_UPPER: str = "power_ci_upper"
+    TRUE_VALUE: str = "true_value"
+    COVERAGE: str = "coverage"
+    BIAS: str = "bias"
+    RMSE: str = "rmse"
+    MEAN_SE: str = "mean_se"
+    EMPIRICAL_SE: str = "empirical_se"
+    N_SIMS: str = "n_sims"
+    N_FAILED: str = "n_failed"
+    N: str = "n"
+
     # -- CV diagnostics --
     CV_RMSE: str = "cv_rmse"
     CV_MAE: str = "cv_mae"
@@ -277,6 +292,27 @@ AugmentedDataCols = (Col.FITTED, Col.RESID, Col.HAT, Col.STD_RESID, Col.COOKSD)
 SimulationsInferCols = (Col.SIM_MEAN, Col.SIM_SD, "sim_q025", "sim_q975")
 
 
+# =============================================================================
+# Power analysis columns (rows = grid points × terms)
+# =============================================================================
+
+# Note: Grid columns (n, sigma, coef values) are dynamic — only metric columns are fixed
+PowerSummaryCols = (
+    Col.TERM,
+    Col.TRUE_VALUE,
+    Col.POWER,
+    Col.POWER_CI_LOWER,
+    Col.POWER_CI_UPPER,
+    Col.COVERAGE,
+    Col.BIAS,
+    Col.RMSE,
+    Col.MEAN_SE,
+    Col.EMPIRICAL_SE,
+    Col.N_SIMS,
+    Col.N_FAILED,
+)
+
+
 # =============================================================================
 # .effects Schemas (rows = grid points for EMM/marginal effects)
 # =============================================================================

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/bossanova/internal/containers/structs/data.py

@@ -196,6 +196,9 @@ class DataBundle:
     # Random effects metadata
     re_metadata: REMetadata | None = field(default=None)
 
+    # Binary response level mapping (e.g. ("No", "Yes") means No→0, Yes→1)
+    response_levels: tuple[str, ...] | None = field(default=None)
+
     # Rank deficiency info (None means full rank or not yet checked)
     rank_info: RankInfo | None = field(default=None)
 

bossanova-0.1.0.dev15/bossanova/internal/containers/structs/explore.py

@@ -0,0 +1,205 @@
+"""Parsing result containers for explore formulas."""
+
+from attrs import field, frozen, validators
+
+__all__ = [
+    "Condition",
+    "ContrastExpr",
+    "ContrastItem",
+    "ContrastOperand",
+    "ExploreFormula",
+    "ExploreFormulaError",
+]
+
+
+# =====================================================================
+# Bracket contrast expression containers
+# =====================================================================
+
+
+@frozen
+class ContrastOperand:
+    """One side of a bracket contrast item.
+
+    Represents a single operand in a contrast like ``A - B`` or
+    ``(A + B) - C``.
+
+    Attributes:
+        levels: Level names for this operand. Empty tuple for wildcard.
+            Multiple levels indicate a grouped mean (e.g., ``(A + B)``
+            produces ``levels=("A", "B")``).
+        is_wildcard: True for the ``*`` operator, which expands to all
+            levels not mentioned on the other side.
+    """
+
+    levels: tuple[str, ...] = field(factory=tuple, converter=tuple)
+    is_wildcard: bool = field(default=False, validator=validators.instance_of(bool))
+
+
+@frozen
+class ContrastItem:
+    """A single contrast: left operand minus right operand.
+
+    Represents one ``left - right`` comparison in a bracket contrast
+    expression like ``Drug[Active - Placebo]``.
+
+    Attributes:
+        left: Left operand (positive side).
+        right: Right operand (negative side).
+    """
+
+    left: ContrastOperand = field(validator=validators.instance_of(ContrastOperand))
+    right: ContrastOperand = field(validator=validators.instance_of(ContrastOperand))
+
+
+@frozen
+class ContrastExpr:
+    """Bracket contrast expression: ``Drug[A - B, C - D]``.
+
+    Represents a complete bracket contrast specification parsed from
+    explore formula syntax.
+
+    Attributes:
+        var: Variable name (e.g., ``"Drug"``).
+        items: Tuple of contrast items to compute.
+    """
+
+    var: str = field(validator=validators.instance_of(str))
+    items: tuple[ContrastItem, ...] = field(converter=tuple)
+
+
+@frozen
+class Condition:
+    """A conditioning specification in explore formula.
+
+    Represents a variable to condition on, optionally with specific values,
+    a method for generating values, or a bracket contrast expression.
+
+    Attributes:
+        var: Variable name to condition on.
+        at_values: Specific values to evaluate at (e.g., (50.0,) or ("A", "B")).
+        at_range: Number of evenly-spaced values across the variable's range.
+        at_quantile: Number of quantile values to use.
+        contrast_expr: Bracket contrast expression on this condition variable
+            (e.g., from ``Dose[High - Low]`` on the RHS). When set, the
+            variable is treated as a grid categorical during condition
+            resolution, and the contrast is applied as a post-processing step.
+    """
+
+    var: str = field(validator=validators.instance_of(str))
+    at_values: tuple | None = field(default=None)
+    at_range: int | None = field(default=None)
+    at_quantile: int | None = field(default=None)
+    contrast_expr: ContrastExpr | None = field(default=None)
+
+
+@frozen
+class ExploreFormula:
+    """Parsed explore formula.
+
+    Represents a parsed explore formula with focal variable, optional contrast
+    type, and conditioning specifications.
+
+    Attributes:
+        focal_var: The variable to compute marginal effects for.
+        contrast_type: Type of contrast (pairwise, sequential, poly, treatment,
+            sum, helmert, custom) or None for simple EMMs. Set to ``"custom"``
+            for bracket contrast expressions.
+        contrast_degree: Degree parameter for polynomial contrasts (default None
+            means use n_levels - 1, i.e., maximum degree).
+        contrast_ref: Reference level for treatment/dummy contrasts
+            (e.g., ``"Placebo"`` from ``treatment(Drug, ref=Placebo)``).
+        contrast_expr: Bracket contrast expression AST (e.g., from
+            ``Drug[Active - Placebo]`` syntax). None for named contrast
+            functions or simple EMMs.
+        conditions: Tuple of Condition objects specifying conditioning variables.
+        focal_at_values: Specific values to evaluate the focal variable at
+            (e.g., from ``Days@[0, 3, 6, 9]`` syntax). None means use all levels.
+        focal_at_range: Number of evenly-spaced values across the focal variable's
+            range (e.g., from ``Days@range(5)`` syntax). None means not set.
+        focal_at_quantile: Number of quantile values for the focal variable
+            (e.g., from ``Days@quantile(3)`` syntax). None means not set.
+    """
+
+    focal_var: str = field(validator=validators.instance_of(str))
+    contrast_type: str | None = field(default=None)
+    contrast_degree: int | None = field(default=None)
+    contrast_ref: str | None = field(default=None)
+    contrast_expr: ContrastExpr | None = field(default=None)
+    conditions: tuple[Condition, ...] = field(factory=tuple, converter=tuple)
+    focal_at_values: tuple[float | str, ...] | None = field(default=None)
+    focal_at_range: int | None = field(default=None)
+    focal_at_quantile: int | None = field(default=None)
+
+    def __attrs_post_init__(self) -> None:
+        """Validate at most one focal at-spec is set."""
+        n_set = sum(
+            x is not None
+            for x in (self.focal_at_values, self.focal_at_range, self.focal_at_quantile)
+        )
+        if n_set > 1:
+            raise ValueError(
+                "At most one of focal_at_values, focal_at_range, focal_at_quantile "
+                "may be set."
+            )
+
+    @property
+    def has_focal_at(self) -> bool:
+        """Return True if any focal at-spec is set."""
+        return (
+            self.focal_at_values is not None
+            or self.focal_at_range is not None
+            or self.focal_at_quantile is not None
+        )
+
+    @property
+    def has_contrast(self) -> bool:
+        """Return True if any contrast is specified (named function or bracket expr)."""
+        return self.contrast_type is not None or self.contrast_expr is not None
+
+    @property
+    def has_contrast_expr(self) -> bool:
+        """Return True if a bracket contrast expression is specified."""
+        return self.contrast_expr is not None
+
+    @property
+    def has_conditions(self) -> bool:
+        """Return True if conditioning variables are specified."""
+        return len(self.conditions) > 0
+
+    @property
+    def has_rhs_contrasts(self) -> bool:
+        """Return True if any RHS condition has a bracket contrast expression."""
+        return any(c.contrast_expr is not None for c in self.conditions)
+
+
+class ExploreFormulaError(ValueError):
+    """Error in explore formula syntax.
+
+    Provides helpful error messages with position indicators for syntax errors.
+
+    Args:
+        message: Error description.
+        formula: The formula that caused the error.
+        position: Character position of the error (optional).
+    """
+
+    def __init__(
+        self,
+        message: str,
+        formula: str,
+        position: int | None = None,
+    ) -> None:
+        """Initialize ExploreFormulaError.
+
+        Args:
+            message: Error description.
+            formula: The formula that caused the error.
+            position: Character position of the error.
+        """
+        self.formula = formula
+        self.position = position
+        if position is not None:
+            pointer = " " * position + "^"
+            message = f"{message}\n  {formula}\n  {pointer}"
+        super().__init__(message)

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/bossanova/internal/containers/structs/state.py

@@ -219,13 +219,18 @@ class MeeState:
         explore_formula: The explore formula string that generated this result.
         focal_var: The primary variable being explored.
         type: Type of marginal effect ("means", "slopes", "contrasts").
+        weights: Averaging philosophy used: ``"equal"`` (balanced reference grid,
+            emmeans-style) or ``"observed"`` (g-computation over observed data).
         L_matrix: Design matrix for delta method inference. Shape (n_estimates, n_coef).
             For EMMs, this is X_ref; for slopes, a coefficient selector row.
         contrast_method: Original contrast type for multiplicity adjustment
-            ("pairwise", "revpairwise", "sequential", "poly", or None).
+            ("pairwise", "sequential", "poly", "treatment", "sum",
+            "helmert", or None).
         n_contrast_levels: Number of EMM levels before contrasting (family size for Tukey).
-        link: Link function name for response-scale back-transformation (set when units="data").
-        L_matrix_link: Link-scale L_matrix for CI back-transformation (set when units="data").
+        link: Link function name for response-scale back-transformation (set when units="data"
+            and weights="equal").
+        L_matrix_link: Link-scale L_matrix for CI back-transformation (set when units="data"
+            and weights="equal").
         inference_method: Inference method used (``"asymp"``, ``"boot"``,
             ``"perm"``, or ``None``). Controls which columns appear in
             the ``.effects`` DataFrame.
@@ -253,6 +258,7 @@ class MeeState:
     focal_var: str = field(validator=validators.instance_of(str))
     type: str = field(validator=validators.in_(("means", "slopes", "contrasts")))
     units: str = field(default="link", validator=validators.in_(("link", "data")))
+    weights: str = field(default="equal", validator=validators.in_(("equal", "observed")))
 
     # Design matrix for delta method inference (optional)
     # Shape: (n_estimates, n_coef). For EMMs, this is X_ref; for slopes, a selector row.
@@ -264,7 +270,17 @@ class MeeState:
     contrast_method: str | None = field(
         default=None,
         validator=validators.optional(
-            validators.in_(("pairwise", "revpairwise", "sequential", "poly"))
+            validators.in_(
+                (
+                    "pairwise",
+                    "sequential",
+                    "poly",
+                    "treatment",
+                    "sum",
+                    "helmert",
+                    "custom",
+                )
+            )
         ),
     )
     n_contrast_levels: int | None = field(default=None)

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/bossanova/internal/maths/__init__.py

@@ -28,6 +28,7 @@ from bossanova.internal.maths.batching import (
     get_available_memory_gb,
 )
 from bossanova.internal.maths.config import is_singular
+from bossanova.internal.maths.rounding import round_float_columns, round_sigfigs
 from bossanova.internal.maths.inference import (
     Chi2TestResult,
     FTestResult,
@@ -240,6 +241,8 @@ __all__ = [
     "poly_numeric",
     "poly_numeric_labels",
     "qr_solve",
+    "round_float_columns",
+    "round_sigfigs",
     "sequential_contrast",
     "sequential_labels",
     "sum_contrast",

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev15}/bossanova/internal/maths/config.py

@@ -12,15 +12,71 @@ if TYPE_CHECKING:
     import numpy as np
 
 __all__ = [
+    "get_display_digits",
     "get_singular_tolerance",
     "is_singular",
+    "set_display_digits",
     "set_singular_tolerance",
 ]
 
+# Default significant figures for DataFrame display output.
+# Matches R's summary() convention of 4 significant digits.
+_DISPLAY_DIGITS: int = 4
+
 # Default singular tolerance matches lme4's default (utilities.R:924-928)
 _SINGULAR_TOLERANCE: float = 1e-4
 
 
+def get_display_digits() -> int:
+    """Get the number of significant figures for DataFrame display output.
+
+    Controls how many significant figures are shown in user-facing
+    DataFrames returned by model properties (``.params``, ``.effects``,
+    ``.diagnostics``, etc.) and ``compare()``.  Matches R's ``signif()``
+    convention.
+
+    Returns:
+        Current display digits setting (default 4).
+
+    Examples:
+        ```python
+        from bossanova import get_display_digits
+        get_display_digits()
+        # 4
+        ```
+    """
+    return _DISPLAY_DIGITS
+
+
+def set_display_digits(digits: int) -> None:
+    """Set the number of significant figures for DataFrame display output.
+
+    Controls how many significant figures are shown in user-facing
+    DataFrames returned by model properties (``.params``, ``.effects``,
+    ``.diagnostics``, etc.) and ``compare()``.  Matches R's ``signif()``
+    convention.
+
+    The ``summary()`` method has its own ``digits`` parameter and is
+    unaffected by this setting.
+
+    Args:
+        digits: Number of significant figures.  Must be >= 1.
+
+    Raises:
+        ValueError: If digits is less than 1.
+
+    Examples:
+        ```python
+        from bossanova import set_display_digits
+        set_display_digits(6)  # Show 6 significant figures
+        ```
+    """
+    global _DISPLAY_DIGITS
+    if digits < 1:
+        raise ValueError(f"digits must be >= 1, got {digits}")
+    _DISPLAY_DIGITS = digits
+
+
 def get_singular_tolerance() -> float:
     """Get the current singular tolerance for mixed models.