bossanova 0.1.0.dev26__tar.gz → 0.1.0.dev27__tar.gz

{bossanova-0.1.0.dev26 → bossanova-0.1.0.dev27}/PKG-INFO

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

{bossanova-0.1.0.dev26 → bossanova-0.1.0.dev27}/bossanova/internal/marginal/compute.py

@@ -179,6 +179,16 @@ def _dispatch_marginal_core(
     """
     focal_var = parsed.focal_var
 
+    # Resolve effect_scale="auto" early so all branches see a concrete value.
+    if effect_scale == "auto":
+        _is_ame = how == "ame" or (
+            how == "auto" and spec is not None and spec.link != "identity"
+        )
+        if _is_ame and spec is not None and spec.link != "identity":
+            effect_scale = "response"
+        else:
+            effect_scale = "link"
+
     # Compound focal variable: Drug:Dose[Active:High - Placebo:Low]
     if ":" in focal_var and parsed.has_contrast_expr:
         from bossanova.internal.marginal.bracket_contrasts import (
@@ -197,8 +207,8 @@ def _dispatch_marginal_core(
             resolved=resolved,
         )
 
-    # Validate inputs and resolve how=auto
-    how = _validate_dispatch_inputs(
+    # Validate inputs and resolve how=auto, effect_scale=auto
+    how, effect_scale = _validate_dispatch_inputs(
         focal_var, data, bundle, formula_spec, effect_scale, varying, how, spec, by
     )
 
@@ -331,22 +341,22 @@ def _validate_dispatch_inputs(
     how: str,
     spec: ModelSpec | None,
     by: str | None,
-) -> str:
-    """Validate dispatch inputs and resolve ``how='auto'``.
+) -> tuple[str, str]:
+    """Validate dispatch inputs and resolve ``how='auto'`` and ``effect_scale='auto'``.
 
     Args:
         focal_var: Name of the focal variable.
         data: The model's data DataFrame.
         bundle: DataBundle with model data and metadata.
         formula_spec: FormulaSpec with learned encoding.
-        effect_scale: ``"link"`` or ``"response"``.
+        effect_scale: ``"auto"``, ``"link"``, or ``"response"``.
         varying: ``"exclude"`` or ``"include"``.
         how: ``"auto"``, ``"mem"``, or ``"ame"``.
         spec: ModelSpec with link/family info.
         by: Grouping variable for faceted effects.
 
     Returns:
-        Resolved ``how`` value (``"mem"`` or ``"ame"``).
+        Tuple of (resolved_how, resolved_effect_scale).
 
     Raises:
         ValueError: If any input is invalid.
@@ -373,9 +383,9 @@ def _validate_dispatch_inputs(
         )
         raise ValueError(msg)
 
-    if effect_scale not in ("link", "response"):
+    if effect_scale not in ("auto", "link", "response"):
         raise ValueError(
-            f"effect_scale must be 'link' or 'response', got {effect_scale!r}"
+            f"effect_scale must be 'auto', 'link', or 'response', got {effect_scale!r}"
         )
 
     if varying not in ("exclude", "include"):
@@ -386,6 +396,16 @@ def _validate_dispatch_inputs(
     if how == "auto":
         how = "ame" if spec is not None and spec.link != "identity" else "mem"
 
+    # Resolve effect_scale="auto": response for AME on non-identity link,
+    # link otherwise.  AME only meaningfully differs from MEM on the response
+    # scale (Jensen's inequality), so auto-upgrading avoids the confusing case
+    # where how="ame" silently gives identical results to how="mem".
+    if effect_scale == "auto":
+        if how == "ame" and spec is not None and spec.link != "identity":
+            effect_scale = "response"
+        else:
+            effect_scale = "link"
+
     if by is not None:
         by_vars: list[str] = (
             [by] if isinstance(by, str) else list(by)  # type: ignore[arg-type]
@@ -398,7 +418,7 @@ def _validate_dispatch_inputs(
                     f"Available columns: {sorted(data_cols)}"
                 )
 
-    return how
+    return how, effect_scale
 
 
 def _dispatch_categorical(

{bossanova-0.1.0.dev26 → bossanova-0.1.0.dev27}/bossanova/model/core.py

@@ -1096,7 +1096,7 @@ class model:
         formula: str,
         *,
         inverse_transforms: bool = True,
-        effect_scale: Literal["link", "response"] = "link",
+        effect_scale: Literal["auto", "link", "response"] = "auto",
         varying: Literal["exclude", "include"] = "exclude",
         how: Literal["auto", "mem", "ame"] = "auto",
         by: str | None = None,
@@ -1129,8 +1129,10 @@ class model:
                 learned formula transforms (e.g. ``center``, ``zscore``,
                 ``scale``). Set to False to use transformed-scale
                 names/values directly.
-            effect_scale: ``"link"`` (default) or ``"response"``
-                (inverse-link / data scale).
+            effect_scale: ``"auto"`` (default), ``"link"``, or
+                ``"response"`` (inverse-link / data scale). ``"auto"``
+                resolves to ``"response"`` when ``how="ame"`` with a
+                non-identity link (GLMs), ``"link"`` otherwise.
             varying: ``"exclude"`` (default) or ``"include"`` random effects.
             how: ``"auto"`` (default), ``"mem"`` for emmeans-style balanced
                 reference grid (Marginal Estimated Mean), or ``"ame"`` for
@@ -1208,7 +1210,7 @@ class model:
 
             | Kwarg | Values | Effect |
             |-------|--------|--------|
-            | ``effect_scale`` | ``"link"`` (default), ``"response"`` | Linear predictor vs response scale (GLMs) |
+            | ``effect_scale`` | ``"auto"`` (default), ``"link"``, ``"response"`` | ``"auto"`` = response for AME/GLM, else link |
             | ``varying`` | ``"exclude"`` (default), ``"include"`` | Population vs group-specific (mixed models) |
             | ``inverse_transforms`` | ``True`` (default), ``False`` | Auto-resolve ``center(x)`` / ``zscore(x)`` |
         """

{bossanova-0.1.0.dev26 → bossanova-0.1.0.dev27}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "bossanova"
 requires-python = ">=3.11"
-version = "0.1.0.dev26"
+version = "0.1.0.dev27"
 authors = [
     {name = "Eshin Jolly"},
 ]