bossanova 0.1.0.dev16__tar.gz → 0.1.0.dev17__tar.gz

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

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

{bossanova-0.1.0.dev16 → bossanova-0.1.0.dev17}/bossanova/internal/containers/builders/state.py

@@ -196,8 +196,8 @@ def build_mee_state(
     focal_var: str,
     mee_type: str,
     *,
-    units: str = "link",
-    weights: str = "equal",
+    how: str = "mem",
+    effect_scale: str = "link",
     L_matrix: np.ndarray | None = None,
     contrast_method: str | None = None,
     n_contrast_levels: int | None = None,
@@ -219,9 +219,11 @@ def build_mee_state(
         explore_formula: The explore formula string.
         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).
+        how: Averaging method: ``"mem"`` (Marginal Estimated Mean,
+            balanced reference grid) or ``"ame"`` (Average Marginal
+            Effect, g-computation over observed data).
+        effect_scale: Scale of estimates: ``"link"`` (linear predictor)
+            or ``"response"`` (inverse-link / data scale).
         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
@@ -260,8 +262,8 @@ def build_mee_state(
         explore_formula=explore_formula,
         focal_var=focal_var,
         type=mee_type,
-        units=units,
-        weights=weights,
+        how=how,
+        effect_scale=effect_scale,
         L_matrix=L_matrix,
         contrast_method=contrast_method,
         n_contrast_levels=n_contrast_levels,

{bossanova-0.1.0.dev16 → bossanova-0.1.0.dev17}/bossanova/internal/containers/structs/state.py

@@ -219,18 +219,21 @@ 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).
+        how: Averaging method: ``"mem"`` (Marginal Estimated Mean, balanced
+            reference grid, emmeans-style) or ``"ame"`` (Average Marginal
+            Effect, g-computation over observed data).
+        effect_scale: Scale of estimates: ``"link"`` (linear predictor) or
+            ``"response"`` (inverse-link / data scale).
         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", "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"
-            and weights="equal").
-        L_matrix_link: Link-scale L_matrix for CI back-transformation (set when units="data"
-            and weights="equal").
+        link: Link function name for response-scale back-transformation (set when
+            effect_scale="response" and how="mem").
+        L_matrix_link: Link-scale L_matrix for CI back-transformation (set when
+            effect_scale="response" and how="mem").
         inference_method: Inference method used (``"asymp"``, ``"boot"``,
             ``"perm"``, or ``None``). Controls which columns appear in
             the ``.effects`` DataFrame.
@@ -257,9 +260,9 @@ class MeeState:
     explore_formula: str = field(validator=validators.instance_of(str))
     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"))
+    how: str = field(default="mem", validator=validators.in_(("mem", "ame")))
+    effect_scale: str = field(
+        default="link", validator=validators.in_(("link", "response"))
     )
 
     # Design matrix for delta method inference (optional)
@@ -287,7 +290,7 @@ class MeeState:
     )
     n_contrast_levels: int | None = field(default=None)
 
-    # Response-scale back-transformation (set when units="data" for GLM/GLMER)
+    # Response-scale back-transformation (set when effect_scale="response" for GLM/GLMER)
     link: str | None = field(default=None)
     L_matrix_link: np.ndarray | None = field(
         default=None, repr=False, validator=is_optional_ndarray

{bossanova-0.1.0.dev16 → bossanova-0.1.0.dev17}/bossanova/internal/operations/marginal/bracket_contrasts.py

@@ -304,7 +304,7 @@ def compute_compound_bracket_contrasts(
     *,
     data: pl.DataFrame,
     spec: object | None = None,
-    units: str = "link",
+    effect_scale: str = "link",
     resolved: object | None = None,
 ) -> MeeState:
     """Compute bracket contrasts for a compound focal variable.
@@ -324,7 +324,7 @@ def compute_compound_bracket_contrasts(
         contrast_expr: ContrastExpr from the parser.
         data: Model data DataFrame.
         spec: ModelSpec with link/family info.
-        units: Scale of estimates.
+        effect_scale: Scale of estimates: ``"link"`` or ``"response"``.
         resolved: ResolvedConditions for additional conditioning.
 
     Returns:
@@ -396,7 +396,7 @@ def compute_compound_bracket_contrasts(
     # Handle response-scale transformation
     L_matrix: np.ndarray = X_ref
     link_name: str | None = None
-    if units == "data" and spec is not None:
+    if effect_scale == "response" and spec is not None:
         _link = getattr(spec, "link", "identity")
         if _link != "identity":
             from bossanova.internal.maths.family.links import (
@@ -421,7 +421,7 @@ def compute_compound_bracket_contrasts(
         focal_var=focal_var,
         mee_type="means",
         L_matrix=L_matrix,
-        units=units,
+        effect_scale=effect_scale,
         link=link_name,
     )
 

{bossanova-0.1.0.dev16 → bossanova-0.1.0.dev17}/bossanova/internal/operations/marginal/compute.py

@@ -2,7 +2,8 @@
 
 Routes parsed explore formulas to the appropriate computation: EMMs for
 categorical focal variables, slopes for continuous, or contrasts.
-Supports ``units=`` (link/data scale) and ``varying=`` (marginal/conditional).
+Supports ``effect_scale=`` (link/response scale), ``how=`` (mem/ame),
+and ``varying=`` (marginal/conditional).
 """
 
 from __future__ import annotations
@@ -70,7 +71,7 @@ def dispatch_marginal_computation(
     Validates the focal variable, determines whether it is categorical or
     continuous, and dispatches to the correct computation function.
 
-    Supports ``units=`` and ``varying=`` kwargs for scale transforms and
+    Supports ``effect_scale=`` and ``varying=`` kwargs for scale transforms and
     conditional (group-specific) effects in mixed models.  When RHS conditions
     contain bracket contrasts (e.g., ``Drug[A - B] ~ Dose[High - Low]``),
     applies them as a post-processing step after the main computation.
@@ -80,11 +81,14 @@ def dispatch_marginal_computation(
         bundle: DataBundle with model data and metadata.
         fit: FitState with fitted coefficients.
         data: The model's data DataFrame (for variable lookup and type detection).
-        spec: ModelSpec with link/family info (needed for units="data").
+        spec: ModelSpec with link/family info (needed for effect_scale="response").
         formula_spec: FormulaSpec with learned encoding (needed for finite-diff slopes).
         varying_offsets: VaryingState with BLUPs (needed for conditional effects).
         **kwargs: Additional computation options. Recognized keys:
-            - ``units``: ``"link"`` (default) or ``"data"`` (response scale).
+            - ``how``: ``"auto"`` (default), ``"mem"`` (emmeans-style), or
+              ``"ame"`` (g-computation / average marginal effect).
+            - ``effect_scale``: ``"link"`` (default) or ``"response"``
+              (inverse-link / data scale).
             - ``varying``: ``"exclude"`` (default) or ``"include"`` (conditional).
             - ``by``: Grouping variable for faceted effects.
             - ``inverse_transforms``: ``True`` (default) to auto-resolve raw
@@ -160,7 +164,7 @@ def _dispatch_marginal_core(
             compute_compound_bracket_contrasts,
         )
 
-        units = str(kwargs.pop("units", "link"))
+        effect_scale = str(kwargs.pop("effect_scale", "link"))
         resolved = _resolve_all_conditions(parsed, bundle, data, kwargs, None, True)
         return compute_compound_bracket_contrasts(
             bundle,
@@ -169,7 +173,7 @@ def _dispatch_marginal_core(
             parsed.contrast_expr,
             data=data,
             spec=spec,
-            units=units,
+            effect_scale=effect_scale,
             resolved=resolved,
         )
 
@@ -180,27 +184,30 @@ def _dispatch_marginal_core(
     # Validate focal variable is not the response
     validate_focal_var(bundle, focal_var)
 
-    # Extract units= and varying= from kwargs
-    units = str(kwargs.pop("units", "link"))
-    if units not in ("link", "data"):
-        raise ValueError(f"units must be 'link' or 'data', got {units!r}")
+    # Extract effect_scale= and varying= from kwargs
+    effect_scale = str(kwargs.pop("effect_scale", "link"))
+    if effect_scale not in ("link", "response"):
+        raise ValueError(
+            f"effect_scale must be 'link' or 'response', got {effect_scale!r}"
+        )
 
     varying = str(kwargs.pop("varying", "exclude"))
     if varying not in ("exclude", "include"):
         raise ValueError(f"varying must be 'exclude' or 'include', got {varying!r}")
 
-    # Extract weights= kwarg with smart default
-    weights_raw = kwargs.pop("weights", None)
-    if weights_raw is not None:
-        weights = str(weights_raw)
-        if weights not in ("equal", "observed"):
-            raise ValueError(f"weights must be 'equal' or 'observed', got {weights!r}")
-    else:
-        # Smart default: "observed" for GLMs (non-identity link), "equal" otherwise
+    # Extract how= kwarg with smart default
+    how_raw = kwargs.pop("how", "auto")
+    how_str = str(how_raw)
+    if how_str not in ("auto", "mem", "ame"):
+        raise ValueError(f"how must be 'auto', 'mem', or 'ame', got {how_str!r}")
+    if how_str == "auto":
+        # Smart default: "ame" for GLMs (non-identity link), "mem" otherwise
         if spec is not None and spec.link != "identity":
-            weights = "observed"
+            how = "ame"
         else:
-            weights = "equal"
+            how = "mem"
+    else:
+        how = how_str
 
     # Extract inverse_transforms= kwarg (default True)
     inverse_transforms = bool(kwargs.pop("inverse_transforms", True))
@@ -265,8 +272,8 @@ def _dispatch_marginal_core(
             parsed.contrast_expr,
             data=data,
             spec=spec,
-            units=units,
-            weights=weights,
+            effect_scale=effect_scale,
+            how=how,
             resolved=resolved,
         )
 
@@ -280,8 +287,8 @@ def _dispatch_marginal_core(
             parsed.contrast_degree,
             data,
             spec=spec,
-            units=units,
-            weights=weights,
+            effect_scale=effect_scale,
+            how=how,
             resolved=resolved,
             focal_at_values=parsed.focal_at_values,
             contrast_ref=parsed.contrast_ref,
@@ -304,8 +311,8 @@ def _dispatch_marginal_core(
                 at_overrides=at_overrides,
                 set_categoricals=resolved.set_categoricals or None,
                 spec=spec,
-                units=units,
-                weights=weights,
+                effect_scale=effect_scale,
+                how=how,
             )
         # Continuous at-values (e.g. "Days@[0, 3, 6, 9]"): EMMs at
         # specific values.  Forward-transform the at-values through the
@@ -334,7 +341,7 @@ def _dispatch_marginal_core(
                 focal_var,
                 resolved=resolved,
                 spec=spec,
-                units=units,
+                effect_scale=effect_scale,
             )
         if is_conditional and grouping_var is not None and varying_offsets is not None:
             return compute_conditional_emm(
@@ -345,7 +352,7 @@ def _dispatch_marginal_core(
                 spec=spec,
                 varying_offsets=varying_offsets,
                 grouping_var=grouping_var,
-                units=units,
+                effect_scale=effect_scale,
                 at_overrides=at_overrides,
                 set_categoricals=resolved.set_categoricals or None,
             )
@@ -356,8 +363,8 @@ def _dispatch_marginal_core(
             at_overrides=at_overrides,
             set_categoricals=resolved.set_categoricals or None,
             spec=spec,
-            units=units,
-            weights=weights,
+            effect_scale=effect_scale,
+            how=how,
         )
 
     # Continuous focal variable → slopes
@@ -370,7 +377,7 @@ def _dispatch_marginal_core(
             spec=spec,
             varying_offsets=varying_offsets,
             grouping_var=grouping_var,
-            units=units,
+            effect_scale=effect_scale,
         )
 
     # Crossed / conditioned slopes: conditions on RHS
@@ -395,7 +402,7 @@ def _dispatch_marginal_core(
             data=data,
             spec=spec,
             formula_spec=fspec,
-            units=units,
+            effect_scale=effect_scale,
         )
 
     return _compute_marginal_slope(
@@ -406,8 +413,8 @@ def _dispatch_marginal_core(
         data=data,
         spec=spec,
         formula_spec=fspec,
-        units=units,
-        weights=weights,
+        effect_scale=effect_scale,
+        how=how,
     )
 
 
@@ -566,8 +573,8 @@ def _compute_emm_categorical(
     at_overrides: dict[str, float] | None = None,
     set_categoricals: dict[str, str] | None = None,
     spec: ModelSpec | None = None,
-    units: str = "link",
-    weights: str = "equal",
+    effect_scale: str = "link",
+    how: str = "mem",
 ) -> MeeState:
     """Compute EMMs for a categorical focal variable.
 
@@ -580,9 +587,9 @@ def _compute_emm_categorical(
         at_overrides: Optional covariate overrides for conditioning.
         set_categoricals: Optional dict pinning non-focal categoricals to
             specific levels (e.g. ``{"Ethnicity": "Asian"}``).
-        spec: ModelSpec with link info (for units="data").
-        units: Scale of estimates.
-        weights: Averaging philosophy: ``"equal"`` or ``"observed"``.
+        spec: ModelSpec with link info (for effect_scale="response").
+        effect_scale: Scale of estimates: ``"link"`` or ``"response"``.
+        how: Averaging method: ``"mem"`` or ``"ame"``.
 
     Returns:
         MeeState with grid of levels and their estimated means.
@@ -596,8 +603,8 @@ def _compute_emm_categorical(
         at_overrides=at_overrides,
         set_categoricals=set_categoricals,
         spec=spec,
-        units=units,
-        weights=weights,
+        effect_scale=effect_scale,
+        how=how,
     )
 
 
@@ -608,7 +615,7 @@ def _compute_emm_crossed(
     *,
     resolved: ResolvedConditions,
     spec: ModelSpec | None = None,
-    units: str = "link",
+    effect_scale: str = "link",
 ) -> MeeState:
     """Compute crossed EMMs over focal levels x condition grid.
 
@@ -620,8 +627,8 @@ def _compute_emm_crossed(
         fit: FitState with fitted coefficients.
         focal_var: Name of the categorical focal variable.
         resolved: ResolvedConditions with grid and scalar conditions.
-        spec: ModelSpec with link info (for units="data").
-        units: Scale of estimates.
+        spec: ModelSpec with link info (for effect_scale="response").
+        effect_scale: Scale of estimates: ``"link"`` or ``"response"``.
 
     Returns:
         MeeState with ``n_focal x n_grid`` rows and condition columns.
@@ -702,7 +709,7 @@ def _compute_emm_crossed(
     estimates, L_matrix = estimates_link, X_ref
     link_name: str | None = None
     L_matrix_link: np.ndarray | None = None
-    if units == "data" and spec is not None and spec.link != "identity":
+    if effect_scale == "response" and spec is not None and spec.link != "identity":
         from bossanova.internal.maths.family.links import (
             apply_link_inverse,
             apply_link_inverse_deriv,
@@ -726,7 +733,8 @@ def _compute_emm_crossed(
         explore_formula=f"{focal_var}{cond_str}",
         focal_var=focal_var,
         mee_type="means",
-        units=units,
+        effect_scale=effect_scale,
+        how="mem",
         L_matrix=L_matrix,
         link=link_name,
         L_matrix_link=L_matrix_link,
@@ -799,8 +807,8 @@ def _compute_marginal_slope(
     data: pl.DataFrame,
     spec: ModelSpec | None = None,
     formula_spec: FormulaSpec | None = None,
-    units: str = "link",
-    weights: str = "equal",
+    effect_scale: str = "link",
+    how: str = "mem",
 ) -> MeeState:
     """Compute marginal slope for a continuous focal variable.
 
@@ -818,8 +826,8 @@ def _compute_marginal_slope(
         data: Raw model data DataFrame.
         spec: ModelSpec with family/link info.
         formula_spec: FormulaSpec with learned encoding (for finite-diff).
-        units: Scale of estimates: ``"link"`` or ``"data"``.
-        weights: Averaging philosophy: ``"equal"`` or ``"observed"``.
+        effect_scale: Scale of estimates: ``"link"`` or ``"response"``.
+        how: Averaging method: ``"mem"`` or ``"ame"``.
 
     Returns:
         MeeState with marginal slope estimate.
@@ -847,8 +855,8 @@ def _compute_marginal_slope(
             spec=spec,
             formula_spec=formula_spec,
             data=data,
-            units=units,
-            weights=weights,
+            effect_scale=effect_scale,
+            how=how,
         )
 
     # Fast path: coefficient extraction — use resolved name
@@ -858,7 +866,7 @@ def _compute_marginal_slope(
         focal_var=coef_var,
         explore_formula=focal_var,
         spec=spec,
-        units=units,
+        effect_scale=effect_scale,
     )
 
 
@@ -1044,8 +1052,8 @@ def _compute_contrasts(
     data: pl.DataFrame,
     *,
     spec: ModelSpec | None = None,
-    units: str = "link",
-    weights: str = "equal",
+    effect_scale: str = "link",
+    how: str = "mem",
     resolved: ResolvedConditions | None = None,
     focal_at_values: tuple[float | str, ...] | None = None,
     contrast_ref: str | None = None,
@@ -1066,9 +1074,9 @@ def _compute_contrasts(
             sum, helmert).
         contrast_degree: Degree for polynomial contrasts (None = max).
         data: Model data for level extraction.
-        spec: ModelSpec with link info (for units="data").
-        units: Scale of estimates.
-        weights: Averaging philosophy: ``"equal"`` or ``"observed"``.
+        spec: ModelSpec with link info (for effect_scale="response").
+        effect_scale: Scale of estimates: ``"link"`` or ``"response"``.
+        how: Averaging method: ``"mem"`` or ``"ame"``.
         resolved: Resolved conditions for conditioning.
         focal_at_values: Optional subset of levels from at-spec syntax
             (e.g. ``pairwise(cyl@[4, 8])``).
@@ -1114,7 +1122,7 @@ def _compute_contrasts(
             focal_var,
             resolved=resolved,
             spec=spec,
-            units=units,
+            effect_scale=effect_scale,
         )
         if contrast_ref is not None:
             ref_idx = _resolve_ref_idx(emm_state.grid)
@@ -1138,8 +1146,8 @@ def _compute_contrasts(
         at_overrides=at_overrides,
         set_categoricals=set_cats,
         spec=spec,
-        units=units,
-        weights=weights,
+        effect_scale=effect_scale,
+        how=how,
     )
     if contrast_ref is not None:
         ref_idx = _resolve_ref_idx(emm_state.grid)
@@ -1156,8 +1164,8 @@ def _compute_bracket_contrasts(
     *,
     data: pl.DataFrame,
     spec: ModelSpec | None = None,
-    units: str = "link",
-    weights: str = "equal",
+    effect_scale: str = "link",
+    how: str = "mem",
     resolved: ResolvedConditions | None = None,
 ) -> MeeState:
     """Compute bracket contrast expression for a categorical focal variable.
@@ -1172,9 +1180,9 @@ def _compute_bracket_contrasts(
         focal_var: Name of the categorical variable.
         contrast_expr: ContrastExpr AST from the parser.
         data: Model data DataFrame.
-        spec: ModelSpec with link info (for units="data").
-        units: Scale of estimates.
-        weights: Averaging philosophy: ``"equal"`` or ``"observed"``.
+        spec: ModelSpec with link info (for effect_scale="response").
+        effect_scale: Scale of estimates: ``"link"`` or ``"response"``.
+        how: Averaging method: ``"mem"`` or ``"ame"``.
         resolved: Resolved conditions for conditioning.
 
     Returns:
@@ -1192,7 +1200,7 @@ def _compute_bracket_contrasts(
             focal_var,
             resolved=resolved,
             spec=spec,
-            units=units,
+            effect_scale=effect_scale,
         )
         return apply_bracket_contrasts_grouped(emm_state, contrast_expr)
 
@@ -1207,7 +1215,7 @@ def _compute_bracket_contrasts(
         at_overrides=at_overrides,
         set_categoricals=set_cats,
         spec=spec,
-        units=units,
-        weights=weights,
+        effect_scale=effect_scale,
+        how=how,
     )
     return apply_bracket_contrasts(emm_state, contrast_expr)