bossanova 0.1.0.dev13__tar.gz → 0.1.0.dev14__tar.gz

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev14}/.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.dev14}/PKG-INFO

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

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev14}/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.dev14}/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.dev14}/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.dev13 → bossanova-0.1.0.dev14}/bossanova/internal/containers/structs/explore.py

@@ -44,14 +44,41 @@ class ExploreFormula:
             means use n_levels - 1, i.e., maximum degree).
         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.
+            (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)
     conditions: tuple[Condition, ...] = field(factory=tuple, converter=tuple)
-    focal_at_values: tuple[float, ...] | None = field(default=None)
+    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:

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev14}/bossanova/internal/operations/bundle.py

@@ -71,6 +71,17 @@ def build_bundle_from_data(
     if response_var not in data.columns:
         raise ValueError(f"Response variable '{response_var}' not found in data")
 
+    # Auto-encode string/categorical response for binomial family
+    response_levels: tuple[str, ...] | None = None
+    if spec.family == "binomial":
+        import polars as pl
+
+        response_dtype = data[response_var].dtype
+        if response_dtype in (pl.String, pl.Categorical) or isinstance(
+            response_dtype, pl.Enum
+        ):
+            data, response_levels = _encode_binary_response(data, response_var)
+
     # Functional formula API: parse -> build -> return learned spec
     formula_spec = parse_formula(
         formula,
@@ -150,6 +161,7 @@ def build_bundle_from_data(
         re_metadata=re_metadata,
         factor_levels={k: list(v) for k, v in formula_spec.factors.items()},
         contrast_types=dict(formula_spec.contrast_types),
+        response_levels=response_levels,
         rank_info=rank_info,
     )
 
@@ -352,6 +364,48 @@ def _raise_missing_detail(
     )
 
 
+def _encode_binary_response(
+    data: pl.DataFrame,
+    response_var: str,
+) -> tuple[pl.DataFrame, tuple[str, ...]]:
+    """Auto-encode a string/categorical response for binomial models.
+
+    Sorts unique levels alphabetically (matching R's ``factor()`` ordering)
+    and maps the first level to 0 and the second to 1.
+
+    Args:
+        data: Input DataFrame with a string/categorical response column.
+        response_var: Name of the response column.
+
+    Returns:
+        Tuple of (modified DataFrame with numeric response, level mapping).
+        The level mapping is ``(level_for_0, level_for_1)``.
+
+    Raises:
+        ValueError: If the response column does not have exactly 2 unique levels.
+    """
+    import polars as pl
+
+    col = data[response_var]
+    levels = sorted(col.cast(pl.String).unique().drop_nulls().to_list())
+    if len(levels) != 2:
+        raise ValueError(
+            f"Binomial family with string response requires exactly 2 levels, "
+            f"but '{response_var}' has {len(levels)}: {levels}. "
+            f"Use a numeric 0/1 response or a two-level factor."
+        )
+
+    # Encode: first alphabetically → 0, second → 1
+    encoded = (
+        pl.when(pl.col(response_var).cast(pl.String) == levels[1])
+        .then(1.0)
+        .otherwise(0.0)
+        .alias(response_var)
+    )
+    data = data.with_columns(encoded)
+    return data, tuple(levels)
+
+
 def _validate_response(family: str, y: np.ndarray, response_var: str) -> None:
     """Family-specific response variable validation.
 
@@ -373,6 +427,15 @@ def _validate_response(family: str, y: np.ndarray, response_var: str) -> None:
             f"Check your data or use a different family (e.g., gaussian)."
         )
 
+    if family == "binomial":
+        if np.any(y < 0) or np.any(y > 1):
+            warnings.warn(
+                f"Binomial family expects response values in [0, 1], "
+                f"but '{response_var}' has values outside this range. "
+                f"This matches R's behavior (non-integer successes warning).",
+                stacklevel=4,
+            )
+
 
 def _reindex_groups_after_na_drop(
     *,
@@ -514,6 +577,20 @@ def _build_random_effects(
         build_random_effects_from_spec,
     )
 
+    # Ensure String columns known as factors are Enum before RE construction.
+    # build_design_matrices handles this for the FE path, but the RE path
+    # receives the original DataFrame.  Without this, factor() calls in RE
+    # terms (e.g. "(factor(x)|group)") crash in encode_categorical.
+    import polars as pl
+
+    if formula_spec.factors:
+        casts = []
+        for col_name, levels in formula_spec.factors.items():
+            if col_name in data.columns and data[col_name].dtype == pl.String:
+                casts.append(pl.col(col_name).cast(pl.Enum(levels)))
+        if casts:
+            data = data.with_columns(casts)
+
     re_info = build_random_effects_from_spec(formula_spec, data)
     if re_info is None:
         return None, None

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev14}/bossanova/internal/operations/common/formula_utils.py

@@ -4,6 +4,7 @@ import re
 
 __all__ = [
     "build_ablated_formula",
+    "parse_value",
     "remove_predictor_from_formula",
 ]
 
@@ -55,6 +56,48 @@ def build_ablated_formula(
     return f"{response_var} ~ {' + '.join(rhs_parts)}"
 
 
+def parse_value(s: str) -> float | str:
+    """Parse a single value as float or string.
+
+    Tries to parse as float first; falls back to unquoted or quoted string.
+
+    Args:
+        s: String to parse.
+
+    Returns:
+        Parsed value as float or string.
+
+    Raises:
+        ValueError: If the string is empty.
+
+    Examples:
+        >>> parse_value("3.14")
+        3.14
+        >>> parse_value("hello")
+        'hello'
+        >>> parse_value("'quoted'")
+        'quoted'
+    """
+    s = s.strip()
+    if not s:
+        raise ValueError("Empty value")
+
+    # Try to parse as number
+    try:
+        return float(s)
+    except ValueError:
+        pass
+
+    # Remove quotes if present
+    if (s.startswith('"') and s.endswith('"')) or (
+        s.startswith("'") and s.endswith("'")
+    ):
+        return s[1:-1]
+
+    # Return as-is (unquoted string, e.g., factor level)
+    return s
+
+
 def remove_predictor_from_formula(formula: str, predictor: str) -> str:
     """Remove a predictor term from a formula string.
 

{bossanova-0.1.0.dev13 → bossanova-0.1.0.dev14}/bossanova/internal/operations/formula/parse.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import re
 from typing import TYPE_CHECKING
 
+from attrs import frozen
+
 from bossanova.internal.operations.formula.parser import Parser, Scanner
 from bossanova.internal.operations.formula.parser.expr import (
     Binary,
@@ -28,8 +30,10 @@ if TYPE_CHECKING:
 
 __all__ = [
     "FormulaError",
+    "FormulaStructure",
     "expand_double_verts",
     "expand_nested_syntax",
+    "extract_formula_structure",
     "parse_formula",
 ]
 
@@ -235,6 +239,129 @@ def extract_rhs_terms(
     return rhs_terms, re_terms, has_intercept
 
 
+@frozen
+class FormulaStructure:
+    """Data-free formula structure extracted from an AST.
+
+    Contains the same structural information as a full ``parse_formula()``
+    call but without requiring data for categorical detection.  Used by
+    ``build_model_spec_from_formula()`` to replace regex-based extraction.
+
+    Attributes:
+        response_var: Response variable name, or None for RHS-only formulas.
+        response_transform: Tuple of LHS transforms (innermost-first),
+            or None if no transforms.
+        fixed_term_names: Human-readable fixed-effect term names
+            (e.g. ``["Intercept", "x", "group"]``).
+        has_intercept: Whether the formula includes an intercept.
+        has_random_effects: Whether the formula contains ``|`` terms.
+        random_terms_raw: Raw string representations of RE terms
+            (e.g. ``["(1|subject)"]``).
+    """
+
+    response_var: str | None
+    response_transform: tuple[str, ...] | None
+    fixed_term_names: tuple[str, ...]
+    has_intercept: bool
+    has_random_effects: bool
+    random_terms_raw: tuple[str, ...]
+
+
+def extract_formula_structure(formula: str) -> FormulaStructure:
+    """Extract formula structure from a formula string without data.
+
+    Parses the formula into an AST and walks it to extract response
+    variable, fixed-effect term names, intercept presence, and
+    random-effect term strings.  Does not require data (no categorical
+    detection).
+
+    Args:
+        formula: R-style formula string (e.g. ``"y ~ x + (1|group)"``).
+
+    Returns:
+        FormulaStructure with extracted information.
+
+    Raises:
+        FormulaError: If formula syntax is invalid.
+    """
+    # Known transforms that can appear on the LHS
+    _KNOWN_RESPONSE_TRANSFORMS = set(STATEFUL_TRANSFORMS) | {"log", "log10", "sqrt"}
+
+    # Pre-process: expand || and / syntax
+    expanded, _ = expand_double_verts(formula)
+    expanded, _ = expand_nested_syntax(expanded)
+
+    # Tokenize and parse
+    tokens = Scanner(expanded).scan(add_intercept=False)
+    ast = Parser(tokens, expanded).parse()
+
+    response_var: str | None = None
+    response_transform: tuple[str, ...] | None = None
+
+    if isinstance(ast, Binary) and ast.operator.kind == "TILDE":
+        # Extract response from LHS
+        if isinstance(ast.left, Call) and isinstance(ast.left.callee, Variable):
+            chain: list[str] = []
+            node = ast.left
+            while isinstance(node, Call) and isinstance(node.callee, Variable):
+                func_name = node.callee.name.lexeme
+                if func_name not in _KNOWN_RESPONSE_TRANSFORMS:
+                    raise FormulaError(
+                        f"Unknown response transform '{func_name}'. "
+                        f"Supported: {sorted(_KNOWN_RESPONSE_TRANSFORMS)}",
+                        formula=formula,
+                    )
+                if not node.args:
+                    raise FormulaError(
+                        f"{func_name}() requires an argument",
+                        formula=formula,
+                    )
+                chain.append(func_name)
+                node = node.args[0]
+            var_name = extract_name(node)
+            if var_name is None:
+                raise FormulaError(
+                    f"{chain[-1]}() argument must be a variable name",
+                    formula=formula,
+                )
+            response_var = var_name
+            response_transform = tuple(reversed(chain))
+        else:
+            response_var = extract_name(ast.left)
+        rhs_terms, re_terms, has_intercept = extract_rhs_terms(ast.right)
+    else:
+        rhs_terms, re_terms, has_intercept = extract_rhs_terms(ast)
+
+    # Extract human-readable fixed term names from AST nodes
+    fixed_names: list[str] = []
+    if has_intercept:
+        fixed_names.append("Intercept")
+    for term in rhs_terms:
+        name = extract_name(term)
+        # For Call nodes like factor(x), extract the argument name
+        if name is None and isinstance(term, Call) and term.args:
+            name = extract_name(term.args[0])
+        if name is not None and name not in ("0", "1", "-1"):
+            fixed_names.append(name)
+
+    # Extract RE term strings from the original expanded formula
+    re_pattern = r"\([^)]*\|[^)]*\)"
+    _, expanded_rhs = expanded.split("~", 1) if "~" in expanded else ("", expanded)
+    random_terms_raw = tuple(re.findall(re_pattern, expanded_rhs))
+
+    if not fixed_names:
+        fixed_names = ["Intercept"]
+
+    return FormulaStructure(
+        response_var=response_var,
+        response_transform=response_transform,
+        fixed_term_names=tuple(fixed_names),
+        has_intercept=has_intercept,
+        has_random_effects=len(re_terms) > 0,
+        random_terms_raw=random_terms_raw,
+    )
+
+
 # =============================================================================
 # Formula pre-processing (|| and / syntax expansion)
 # =============================================================================