bossanova 0.1.0.dev14__tar.gz → 0.1.0.dev16__tar.gz

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev16}/PKG-INFO

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

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev16}/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.dev14 → bossanova-0.1.0.dev16}/bossanova/internal/containers/builders/state.py

@@ -197,6 +197,7 @@ def build_mee_state(
     mee_type: str,
     *,
     units: str = "link",
+    weights: str = "equal",
     L_matrix: np.ndarray | None = None,
     contrast_method: str | None = None,
     n_contrast_levels: int | None = None,
@@ -219,10 +220,13 @@ def build_mee_state(
         focal_var: The primary variable being explored.
         mee_type: Type of effect ("means", "slopes", "contrasts").
         units: Scale of the estimates: "link" (linear predictor) or "data" (response).
+        weights: Averaging philosophy: ``"equal"`` (balanced reference grid,
+            emmeans-style) or ``"observed"`` (g-computation over observed data).
         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.
@@ -257,6 +261,7 @@ def build_mee_state(
         focal_var=focal_var,
         type=mee_type,
         units=units,
+        weights=weights,
         L_matrix=L_matrix,
         contrast_method=contrast_method,
         n_contrast_levels=n_contrast_levels,

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev16}/bossanova/internal/containers/structs/explore.py

@@ -4,29 +4,93 @@ 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
-    or a method for generating values.
+    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
@@ -38,10 +102,16 @@ class ExploreFormula:
 
     Attributes:
         focal_var: The variable to compute marginal effects for.
-        contrast_type: Type of contrast (pairwise, revpairwise, sequential, poly)
-            or None for simple EMMs.
+        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.
@@ -54,6 +124,8 @@ class ExploreFormula:
     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)
@@ -82,14 +154,24 @@ class ExploreFormula:
 
     @property
     def has_contrast(self) -> bool:
-        """Return True if a contrast function is specified."""
-        return self.contrast_type is not None
+        """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.

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev16}/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,9 @@ 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 +272,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.dev14 → bossanova-0.1.0.dev16}/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.dev14 → bossanova-0.1.0.dev16}/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.
 

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev16}/bossanova/internal/maths/design/reference.py

@@ -9,6 +9,7 @@ from bossanova.internal.maths.design.names import (
 
 __all__ = [
     "build_continuous_reference_matrix",
+    "build_counterfactual_design_matrices",
     "build_reference_design_matrix",
     "build_reference_row",
 ]
@@ -248,6 +249,98 @@ def build_continuous_reference_matrix(
     return X_ref
 
 
+def build_counterfactual_design_matrices(
+    X: np.ndarray,
+    X_names: tuple[str, ...] | list[str],
+    focal_var: str,
+    levels: list[str],
+) -> list[np.ndarray]:
+    """Build counterfactual design matrices for g-computation.
+
+    For each focal level, creates a modified copy of the full design matrix
+    ``X`` where the focal variable's indicator columns are set to match that
+    level and interaction columns involving the focal variable are recomputed
+    from component values.  Non-focal columns are left unchanged, preserving
+    the observed covariate distribution.
+
+    This is the core building block for ``weights="observed"``
+    (g-computation / counterfactual prediction).  Each returned matrix answers:
+    "What would the design matrix look like if every observation were assigned
+    to this focal level?"
+
+    Args:
+        X: Original design matrix, shape ``(N, p)``.
+        X_names: Column names from the design matrix, in order.
+        focal_var: Name of the categorical focal variable.
+        levels: List of levels to compute counterfactuals for.
+
+    Returns:
+        List of counterfactual design matrices (one per level), each shape
+        ``(N, p)``.  Order matches ``levels``.
+
+    Examples:
+        For a model ``y ~ treatment + x + treatment:x`` with
+        ``X_names = ("Intercept", "x", "treatment[B]", "x:treatment[B]")``::
+
+            mats = build_counterfactual_design_matrices(X, X_names, "treatment", ["ref", "B"])
+            # mats[0]: treatment set to ref for all rows (treatment[B]=0, x:treatment[B]=0)
+            # mats[1]: treatment set to B for all rows (treatment[B]=1, x:treatment[B]=x_i)
+    """
+    X_names_list = list(X_names)
+    N, p = X.shape
+
+    # Pre-parse column metadata once
+    col_infos = [parse_design_column_name(name) for name in X_names_list]
+
+    # Identify focal dummy columns and their levels
+    focal_col_indices: list[int] = []
+    focal_col_levels: list[str | None] = []
+    for j, info in enumerate(col_infos):
+        if info.column_type == "categorical" and info.base_term == focal_var:
+            focal_col_indices.append(j)
+            focal_col_levels.append(info.level)
+
+    # Identify interaction columns involving the focal variable
+    interaction_cols: list[int] = []
+    for j, info in enumerate(col_infos):
+        if info.is_interaction:
+            parts = X_names_list[j].split(":")
+            if any(
+                parse_design_column_name(part).base_term == focal_var for part in parts
+            ):
+                interaction_cols.append(j)
+
+    result: list[np.ndarray] = []
+    for level in levels:
+        X_cf = X.copy()
+
+        # Set focal dummy columns
+        for j, lvl in zip(focal_col_indices, focal_col_levels):
+            X_cf[:, j] = 1.0 if lvl == level else 0.0
+
+        # Recompute interaction columns involving the focal variable
+        for j in interaction_cols:
+            parts = X_names_list[j].split(":")
+            col_product = np.ones(N, dtype=np.float64)
+            for part in parts:
+                pinfo = parse_design_column_name(part)
+                if pinfo.base_term == focal_var:
+                    # Focal component: use counterfactual indicator
+                    if pinfo.column_type == "categorical":
+                        col_product *= 1.0 if pinfo.level == level else 0.0
+                    elif part in X_names_list:
+                        # Continuous focal in interaction (rare but possible)
+                        col_product *= X[:, X_names_list.index(part)]
+                elif part in X_names_list:
+                    # Non-focal component: use original observed values
+                    col_product *= X[:, X_names_list.index(part)]
+            X_cf[:, j] = col_product
+
+        result.append(X_cf)
+
+    return result
+
+
 # ---------------------------------------------------------------------------
 # Internal helpers
 # ---------------------------------------------------------------------------

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev16}/bossanova/internal/maths/inference/contrasts.py

@@ -7,9 +7,11 @@ import numpy as np
 __all__ = [
     "build_all_pairwise_contrast",
     "build_contrast_matrix",
+    "build_helmert_contrast",
     "build_pairwise_contrast",
     "build_sequential_contrast",
     "build_sum_to_zero_contrast",
+    "build_treatment_contrast",
     "compose_contrast",
     "get_contrast_labels",
 ]
@@ -224,6 +226,98 @@ def build_sum_to_zero_contrast(n_levels: int) -> np.ndarray:
     return C
 
 
+def build_treatment_contrast(n_levels: int, ref_idx: int = 0) -> np.ndarray:
+    """Build treatment (Dunnett-style) contrasts against a reference level.
+
+    Creates n_levels - 1 contrasts, each comparing one non-reference level
+    to the specified reference level.
+
+    Args:
+        n_levels: Number of EMM levels (factor levels).
+        ref_idx: Index of the reference level (0-based).
+
+    Returns:
+        Contrast matrix of shape (n_levels - 1, n_levels).
+        Row i compares non-reference level i to the reference.
+
+    Raises:
+        ValueError: If n_levels < 1 or ref_idx out of range.
+
+    Examples:
+        >>> C = build_treatment_contrast(3, ref_idx=0)
+        >>> C
+        array([[-1.,  1.,  0.],
+               [-1.,  0.,  1.]])
+
+        >>> C = build_treatment_contrast(3, ref_idx=2)
+        >>> C
+        array([[ 1.,  0., -1.],
+               [ 0.,  1., -1.]])
+    """
+    if n_levels < 1:
+        raise ValueError(f"n_levels must be >= 1, got {n_levels}")
+    if ref_idx < 0 or ref_idx >= n_levels:
+        raise ValueError(f"ref_idx must be in [0, {n_levels - 1}], got {ref_idx}")
+
+    if n_levels == 1:
+        return np.zeros((0, 1))
+
+    C = np.zeros((n_levels - 1, n_levels))
+    row = 0
+    for i in range(n_levels):
+        if i == ref_idx:
+            continue
+        C[row, ref_idx] = -1
+        C[row, i] = 1
+        row += 1
+
+    return C
+
+
+def build_helmert_contrast(n_levels: int) -> np.ndarray:
+    """Build Helmert contrasts (each level vs mean of previous levels).
+
+    Creates n_levels - 1 contrasts where level k is compared to
+    the mean of levels 0, 1, ..., k-1. Useful for ordered factors
+    where you want to test if each successive level differs from
+    the average of all prior levels.
+
+    Args:
+        n_levels: Number of EMM levels (factor levels).
+
+    Returns:
+        Contrast matrix of shape (n_levels - 1, n_levels).
+
+    Raises:
+        ValueError: If n_levels < 1.
+
+    Examples:
+        >>> C = build_helmert_contrast(3)
+        >>> C
+        array([[-1. ,  1. ,  0. ],
+               [-0.5, -0.5,  1. ]])
+
+        >>> C = build_helmert_contrast(4)
+        >>> C
+        array([[-1.        ,  1.        ,  0.        ,  0.        ],
+               [-0.5       , -0.5       ,  1.        ,  0.        ],
+               [-0.33333333, -0.33333333, -0.33333333,  1.        ]])
+    """
+    if n_levels < 1:
+        raise ValueError(f"n_levels must be >= 1, got {n_levels}")
+
+    if n_levels == 1:
+        return np.zeros((0, 1))
+
+    C = np.zeros((n_levels - 1, n_levels))
+    for k in range(1, n_levels):
+        # Level k vs mean of levels 0..k-1
+        C[k - 1, :k] = -1.0 / k
+        C[k - 1, k] = 1.0
+
+    return C
+
+
 def build_contrast_matrix(
     contrast_type: str | dict,
     levels: list,
@@ -237,9 +331,10 @@ def build_contrast_matrix(
     Args:
         contrast_type: Type of contrast:
             - "pairwise": All pairwise comparisons (k(k-1)/2 contrasts)
-            - "revpairwise": Reversed pairwise comparisons
             - "trt.vs.ctrl" or "treatment": Compare each level to first level
             - "sequential": Successive differences (level[i+1] - level[i])
+            - "sum": Each level vs grand mean (deviation coding)
+            - "helmert": Each level vs mean of previous levels
             - dict: Custom contrasts with names as keys and weights as values
         levels: List of factor levels.
         normalize: If True, normalize custom contrasts to sum to 1/-1.
@@ -281,10 +376,6 @@ def build_contrast_matrix(
         # All pairwise comparisons: B-A, C-A, C-B, ...
         return build_all_pairwise_contrast(n_levels)
 
-    elif contrast_type == "revpairwise":
-        # Reversed pairwise: A-B, A-C, B-C, ...
-        return -build_all_pairwise_contrast(n_levels)
-
     elif contrast_type in ("trt.vs.ctrl", "treatment"):
         # Each level vs first level
         return build_pairwise_contrast(n_levels)
@@ -293,14 +384,23 @@ def build_contrast_matrix(
         # Successive differences: B-A, C-B, D-C, ...
         return build_sequential_contrast(n_levels)
 
+    elif contrast_type == "sum":
+        # Each level vs grand mean (deviation coding)
+        return build_sum_to_zero_contrast(n_levels)
+
+    elif contrast_type == "helmert":
+        # Each level vs mean of previous levels
+        return build_helmert_contrast(n_levels)
+
     else:
         raise ValueError(
             f"Unknown contrast type: {contrast_type!r}\n\n"
             "Supported types:\n"
             "  - 'pairwise': All pairwise comparisons\n"
-            "  - 'revpairwise': Reversed pairwise\n"
             "  - 'sequential': Successive differences (level[i+1] - level[i])\n"
-            "  - 'trt.vs.ctrl': Each level vs first level\n"
+            "  - 'trt.vs.ctrl' / 'treatment': Each level vs first level\n"
+            "  - 'sum': Each level vs grand mean\n"
+            "  - 'helmert': Each level vs mean of previous levels\n"
             "  - dict: Custom contrasts {name: weights}"
         )
 

{bossanova-0.1.0.dev14 → bossanova-0.1.0.dev16}/bossanova/internal/maths/inference/multiplicity.py

@@ -3,8 +3,9 @@
 Provides critical value computation for multiplicity-adjusted CIs,
 matching R's emmeans defaults:
 
-- Tukey HSD for pairwise/revpairwise contrasts (studentized range).
-- Multivariate-t (MVT) for sequential contrasts (Genz-Bretz CDF + root-finding).
+- Tukey HSD for pairwise contrasts (studentized range).
+- Multivariate-t (MVT) for sequential, treatment, sum, helmert contrasts
+  (Genz-Bretz CDF + root-finding).
 - No adjustment for polynomial contrasts.
 
 Internal exports: