formative-ds 1.2.2__tar.gz → 2.0.0__tar.gz

{formative_ds-1.2.2 → formative_ds-2.0.0}/CLAUDE.md

@@ -43,17 +43,24 @@ Called as `result.refute(df)` — always pass the same `df` used for `fit()`. Re
 **Refutation seeds** — isolated to avoid collisions with test data (seeded at 42):
 - `_RCC_SEED = 54321` — random common cause column
 - `_PLACEBO_SEED = 99999` — treatment permutation in matching
+- `_PLACEBO_TIME_SEED = 22222` — time permutation in DiD
+- `_PLACEBO_MODIFIER_SEED = 77777` — modifier permutation in CATE checks
+- `_RANDOM_MODIFIER_SEED = 31313` — noise modifier column in CATE checks
 - `_BOOTSTRAP_SEED = 42` — safe to reuse in matching's bootstrap (samples row indices, not independent values)
 
 Do not change `_RCC_SEED` or `_PLACEBO_SEED` to 42 — the generated noise collides with instrument/treatment data and produces a singular matrix in IV.
 
+**Heterogeneous effects (CATE)** — `OLSObservational` and `RCT` accept `effect_modifier=` (a discrete, pre-treatment column). `fit()` then returns `OLSCATEResult`/`RCTCATEResult` with `effect_by_group`, a homogeneity F-test, and `decide_by_group()`. The headline `effect` is the sample-share-weighted average of group effects (the raw treatment coefficient under interaction coding is only the reference group's effect). Shared machinery lives in `estimators/_cate.py`; DAG validation rejects modifiers that are descendants of the treatment (mediators) or not ancestors of the outcome.
+
 **Package layout:**
 - `formative/causal/dag.py` — `DAG`, `_Node`
 - `formative/causal/_exceptions.py` — `IdentificationError`, `GraphError`
-- `formative/causal/estimators/ols.py` — `OLSObservational`, `OLSResult`
+- `formative/causal/estimators/_base.py` — `_BaseResult`, `_StatsmodelsResult` (shared result plumbing: effect stats via `_param`, `decide()`, assumptions footer)
+- `formative/causal/estimators/_cate.py` — `GroupEffect`, `_fit_cate`, `_CATEResultMixin`, modifier validation (shared by OLS/RCT and the CATE refutations)
+- `formative/causal/estimators/ols.py` — `OLSObservational`, `OLSResult`, `OLSCATEResult`
 - `formative/causal/estimators/iv.py` — `IV2SLS`, `IVResult`
 - `formative/causal/estimators/matching.py` — `PropensityScoreMatching`, `MatchingResult`; exports `_propensity_scores`, `_att_from_ps` for use by refutations
-- `formative/causal/estimators/rct.py` — `RCT`, `RCTResult`
+- `formative/causal/estimators/rct.py` — `RCT`, `RCTResult`, `RCTCATEResult`
 - `formative/causal/estimators/did.py` — `DiD`, `DiDResult`
 - `formative/causal/estimators/rdd.py` — `RDD`, `RDDResult`
 - `formative/causal/refutations/_check.py` — `Assumption`, `RefutationCheck`, `RefutationReport`
@@ -61,6 +68,7 @@ Do not change `_RCC_SEED` or `_PLACEBO_SEED` to 42 — the generated noise colli
 - `formative/causal/refutations/iv.py` — `IVRefutationReport`, `_check_first_stage_f`, `_check_random_common_cause`
 - `formative/causal/refutations/matching.py` — `MatchingRefutationReport`, `_check_placebo_treatment`, `_check_random_common_cause`
 - `formative/causal/refutations/rct.py` — `RCTRefutationReport`, `_check_random_common_cause`
+- `formative/causal/refutations/cate.py` — `_check_placebo_modifier`, `_check_random_modifier`, `_check_random_common_cause` (used by `OLSCATEResult`/`RCTCATEResult`; reports reuse the OLS/RCT report classes)
 - `formative/causal/refutations/did.py` — `DiDRefutationReport`, `_check_placebo_group`, `_check_random_common_cause`
 - `formative/causal/refutations/rdd.py` — `RDDRefutationReport`, `_check_placebo_cutoff`, `_check_random_common_cause`
 - `formative/causal/_explain.py` — narrative rendering for all estimators
@@ -91,7 +99,7 @@ result = maximin({
 **Package layout:**
 - `formative/game/maximin.py` — `maximin`, `Maximin`, `MaximinResult`
 - `formative/game/maximax.py` — `maximax`, `Maximax`, `MaximaxResult`
-- `formative/game/minimax_regret.py` — `minimax_regret`, `MinimaxRegret`, `MinimaxRegretResult`
+- `formative/game/minimax.py` — `minimax`, `Minimax`, `MinimaxResult`
 - `formative/game/hurwicz.py` — `hurwicz`, `Hurwicz`, `HurwiczResult`
 - `formative/game/laplace.py` — `laplace`, `Laplace`, `LaplaceResult`
 - `formative/game/expected_value.py` — `expected_value`, `ExpectedValue`, `ExpectedValueResult`

{formative_ds-1.2.2 → formative_ds-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: formative-ds
-Version: 1.2.2
+Version: 2.0.0
 Summary: A Python library for quantitative reasoning.
 Project-URL: Homepage, https://getformative.dev
 Project-URL: Documentation, https://docs.getformative.dev
@@ -68,7 +68,7 @@ Confounders declared in the DAG are controlled for automatically. If a confounde
 ### Decision rules
 
 ```python
-from formative.game import maximin, maximax, hurwicz, laplace, minimax_regret
+from formative.game import maximin, maximax, hurwicz, laplace, minimax
 
 outcomes = {
     "stocks": {"recession": -20, "stagnation":  5, "growth": 30},
@@ -80,7 +80,7 @@ maximin(outcomes).solve()        # safest choice (best worst case)
 maximax(outcomes).solve()        # most optimistic (best best case)
 hurwicz(outcomes, alpha=0.5).solve()  # blend of optimism and pessimism
 laplace(outcomes).solve()        # highest average payoff
-minimax_regret(outcomes).solve() # lowest worst-case regret
+minimax(outcomes).solve()        # lowest worst-case regret
 ```
 
 See online documentation at [docs.getformative.dev](https://docs.getformative.dev) for more examples and details.

{formative_ds-1.2.2 → formative_ds-2.0.0}/README.md

@@ -41,7 +41,7 @@ Confounders declared in the DAG are controlled for automatically. If a confounde
 ### Decision rules
 
 ```python
-from formative.game import maximin, maximax, hurwicz, laplace, minimax_regret
+from formative.game import maximin, maximax, hurwicz, laplace, minimax
 
 outcomes = {
     "stocks": {"recession": -20, "stagnation":  5, "growth": 30},
@@ -53,7 +53,7 @@ maximin(outcomes).solve()        # safest choice (best worst case)
 maximax(outcomes).solve()        # most optimistic (best best case)
 hurwicz(outcomes, alpha=0.5).solve()  # blend of optimism and pessimism
 laplace(outcomes).solve()        # highest average payoff
-minimax_regret(outcomes).solve() # lowest worst-case regret
+minimax(outcomes).solve()        # lowest worst-case regret
 ```
 
 See online documentation at [docs.getformative.dev](https://docs.getformative.dev) for more examples and details.

{formative_ds-1.2.2 → formative_ds-2.0.0}/docs/causal/decisions.rst

@@ -36,7 +36,7 @@ earnings using OLS with a DAG that encodes family background as a confounder:
 
    import numpy as np
    import pandas as pd
-   from formative import DAG, OLSObservational
+   from formative.causal import DAG, OLSObservational
 
    rng = np.random.default_rng(0)
    N = 2_000
@@ -95,7 +95,7 @@ to any rule in ``formative.game``:
 
 .. code-block:: python
 
-   from formative.game import maximin, minimax_regret, hurwicz
+   from formative.game import maximin, minimax, hurwicz
 
    decision = result.decide(cost=8, benefit=15)
    outcomes = decision.to_outcomes()
@@ -105,7 +105,7 @@ to any rule in ``formative.game``:
    # }
 
    maximin(outcomes).solve()            # best worst-case
-   minimax_regret(outcomes).solve()     # minimise maximum regret
+   minimax(outcomes).solve()            # minimise maximum regret
    hurwicz(outcomes, alpha=0.3).solve() # weighted pessimism–optimism
 
 By default, the three scenarios correspond to the 10th, 50th, and 90th
@@ -127,27 +127,6 @@ set to the CI bounds (quantiles 0.025 and 0.975). ``to_outcomes()``
 generalises that check: different rules express different risk attitudes, and
 you can dial in your own pessimism level via ``hurwicz(alpha=...)``.
 
-Value of information
---------------------
-
-When a decision is *not* already highly confident, it is useful to know how much
-more data would be needed to reach a target confidence level. Call
-``value_of_information()`` on the report:
-
-.. code-block:: python
-
-   print(decision.value_of_information(target_confidence=0.99))
-
-If the decision is already at or above the target confidence, formative reports
-that no additional data is needed. Otherwise, it reports:
-
-* how much the standard error on net benefit would need to shrink, and
-* approximately how many times larger the sample would need to be.
-
-This frames the cost of uncertainty concretely: collecting more data has a price,
-and the value of information tells you whether that price is worth paying before
-you commit to a decision.
-
 Philosophy
 ----------
 

{formative_ds-1.2.2 → formative_ds-2.0.0}/docs/causal/estimands.rst

@@ -2,7 +2,7 @@ Estimands: ATE, ATT, LATE etc.
 ==============================
 
 Every causal estimator targets a specific *estimand*. Choosing the wrong estimator for your question gives a valid answer to the wrong
-question. The four estimands formative works with are ATE, ATT, LATE, and LATE at the cutoff. One method can only target one estimand.
+question. The five estimands formative works with are ATE, ATT, LATE, LATE at the cutoff, and CATE. One method can only target one estimand.
 
 .. list-table::
    :header-rows: 1
@@ -14,6 +14,9 @@ question. The four estimands formative works with are ATE, ATT, LATE, and LATE a
    * - **ATE**
      - Average Treatment Effect
      - :class:`~formative.OLSObservational`, :class:`~formative.RCT`
+   * - **CATE**
+     - Conditional Average Treatment Effect
+     - :class:`~formative.OLSObservational`, :class:`~formative.RCT` (with ``effect_modifier``)
    * - **ATT**
      - Average Treatment Effect on the Treated
      - :class:`~formative.PropensityScoreMatching`, :class:`~formative.DiD`
@@ -191,3 +194,48 @@ assumption is more defensible but the estimate has higher variance.
 - **RDD** — fits a local linear regression on both sides of the cutoff. The coefficient on
   the treatment indicator gives the jump in outcome at the threshold, controlling for the
   slope of the running variable separately on each side.
+
+----
+
+CATE: Conditional Average Treatment Effect
+------------------------------------------
+
+**What it answers:** *For whom* does the treatment work? An average effect answers "does the
+intervention work?"; the CATE answers how the effect differs across known subgroups — should
+a discount go to new customers or loyal ones, does the training help juniors more than
+seniors?
+
+.. math::
+
+   \text{CATE}(x) = \mathbb{E}[Y(1) - Y(0) \mid X = x]
+
+:math:`X` is an *effect modifier*: a pre-treatment variable whose levels the effect is
+allowed to differ across. Instead of one number, the estimand is a per-group effect —
+one for each level of :math:`X`.
+
+**When it makes sense:** When the decision is not "treat everyone or no one" but "who should
+receive the treatment" — targeting, personalisation, prioritising a limited budget. Estimating
+per-group effects also comes with a **homogeneity test** answering whether the group
+differences are real or noise; without it, eyeballing subgroup estimates invites false
+discoveries.
+
+In formative, pass ``effect_modifier=`` to :class:`~formative.OLSObservational` or
+:class:`~formative.RCT`. The fitted model becomes
+``outcome ~ treatment * C(modifier) + controls``, and the result exposes per-group effects
+(``effect_by_group``), the homogeneity test, and a cost-benefit decision per group
+(``decide_by_group``). The modifier must be measured pre-treatment: segmenting by a variable
+the treatment itself affects (a mediator) manufactures artificial heterogeneity, and the DAG
+validation rejects modifiers that are descendants of the treatment.
+
+**Methods that estimate CATE:**
+
+- **OLS Observational** (with ``effect_modifier``) — interacts the treatment with the
+  modifier while adjusting for confounders identified via the backdoor criterion.
+- **RCT** (with ``effect_modifier``) — randomisation makes each subgroup's simple contrast
+  unbiased; the interaction model estimates all subgroups jointly.
+
+**CATE vs ATE:** The ATE is the average of the CATEs, weighted by each group's share of the
+population — formative reports exactly this weighted average as the headline effect when an
+effect modifier is used. A homogeneous effect means CATE(x) = ATE for every group; the wider
+the CATEs spread around the ATE, the more value there is in targeting rather than treating
+uniformly.

{formative_ds-1.2.2 → formative_ds-2.0.0}/docs/causal/estimators.rst

@@ -14,6 +14,13 @@ OLSResult
    :members:
    :inherited-members:
 
+OLSCATEResult
+-------------
+
+.. autoclass:: formative.causal.OLSCATEResult
+   :members:
+   :inherited-members:
+
 IV2SLS
 ------
 
@@ -53,6 +60,13 @@ RCTResult
    :members:
    :inherited-members:
 
+RCTCATEResult
+-------------
+
+.. autoclass:: formative.causal.RCTCATEResult
+   :members:
+   :inherited-members:
+
 DiD
 ---
 
@@ -78,3 +92,9 @@ RDDResult
 .. autoclass:: formative.causal.RDDResult
    :members:
    :inherited-members:
+
+GroupEffect
+-----------
+
+.. autoclass:: formative.causal.GroupEffect
+   :members:

{formative_ds-1.2.2 → formative_ds-2.0.0}/docs/game/decision_rules.rst

@@ -74,8 +74,8 @@ downside.
 .. autoclass:: formative.game.MaximaxResult
    :members:
 
-Minimax Regret
---------------
+Minimax
+-------
 
 *Which choice do you regret the least in hindsight?*
 
@@ -115,14 +115,14 @@ Then compute regret for every combination — how much you miss out on versus th
 
 .. code-block:: python
 
-   from formative.game import minimax_regret
+   from formative.game import minimax
 
-   result = minimax_regret(outcomes).solve()
+   result = minimax(outcomes).solve()
    print(result)
 
 .. code-block:: text
 
-   MinimaxRegretResult(
+   MinimaxResult(
      stocks  max regret: +25
      bonds   max regret: +23  ← chosen
      cash    max regret: +28
@@ -133,10 +133,10 @@ score zero in recession and stagnation, but 23 in growth where stocks outperform
 Cash never comes close to the best option in any scenario, giving it the highest max
 regret of 28. Bonds minimise the worst-case regret.
 
-.. autoclass:: formative.game.MinimaxRegret
+.. autoclass:: formative.game.Minimax
    :members:
 
-.. autoclass:: formative.game.MinimaxRegretResult
+.. autoclass:: formative.game.MinimaxResult
    :members:
 
 Hurwicz Criterion

{formative_ds-1.2.2 → formative_ds-2.0.0}/formative/causal/__init__.py

@@ -1,10 +1,11 @@
 from .dag import DAG
 from .decision import DecisionReport
+from .estimators._cate import GroupEffect
 from .estimators.did import DiD, DiDResult
 from .estimators.iv import IV2SLS, IVResult
 from .estimators.matching import MatchingResult, PropensityScoreMatching
-from .estimators.ols import OLSObservational, OLSResult
-from .estimators.rct import RCT, RCTResult
+from .estimators.ols import OLSCATEResult, OLSObservational, OLSResult
+from .estimators.rct import RCT, RCTCATEResult, RCTResult
 from .estimators.rdd import RDD, RDDResult
 from .refutations import (
     DiDRefutationReport,
@@ -22,12 +23,15 @@ __all__ = [
     "DAG",
     "OLSObservational",
     "OLSResult",
+    "OLSCATEResult",
+    "GroupEffect",
     "IV2SLS",
     "IVResult",
     "PropensityScoreMatching",
     "MatchingResult",
     "RCT",
     "RCTResult",
+    "RCTCATEResult",
     "DiD",
     "DiDResult",
     "RDD",

{formative_ds-1.2.2 → formative_ds-2.0.0}/formative/causal/_explain.py

@@ -82,6 +82,46 @@ def _dag_section(dag, treatment: str, outcome: str, adjustment_set: set[str]) ->
     return "\n".join(lines)
 
 
+def _heterogeneity_section(result) -> str | None:
+    """HETEROGENEITY block for results fitted with an effect modifier, else None."""
+    modifier = getattr(result, "_modifier", None)
+    if modifier is None:
+        return None
+
+    groups = result.effect_by_group
+    p = result.homogeneity_pvalue
+    largest = max(groups, key=lambda g: g.effect)
+    smallest = min(groups, key=lambda g: g.effect)
+
+    if p < 0.05:
+        verdict = (
+            f"A formal test rejects the hypothesis that the effect is the same across "
+            f"{modifier} groups ({_fmt_p(p)}): the treatment effect genuinely differs by {modifier}."
+        )
+    else:
+        verdict = (
+            f"A formal test does not reject the hypothesis that the effect is the same "
+            f"across {modifier} groups ({_fmt_p(p)}); the differences below may be noise."
+        )
+
+    lines = [
+        "HETEROGENEITY",
+        f"The effect was allowed to differ across levels of {modifier}. {verdict}",
+        "",
+    ]
+    for g in groups:
+        lo, hi = g.conf_int
+        lines.append(f"  • {modifier} = {g.level}: effect = {g.effect:.4f}  (95% CI: {_fmt_ci(lo, hi)}, n = {g.n:,})")
+    lines += [
+        "",
+        f"The largest estimated effect is for {modifier} = {largest.level} ({largest.effect:.4f}) "
+        f"and the smallest for {modifier} = {smallest.level} ({smallest.effect:.4f}). Group "
+        f"estimates are less precise than the overall average, and with many groups some "
+        f"extreme-looking effects are expected by chance.",
+    ]
+    return "\n".join(lines)
+
+
 def _assumptions_section(assumptions: list) -> str:
     n = len(assumptions)
     n_u = sum(1 for a in assumptions if not a.testable)
@@ -115,6 +155,7 @@ def explain_ols(result) -> str:
     adj = sorted(result._adjustment_set)
     lo, hi = result.conf_int
     bias = result.unadjusted_effect - result.effect
+    heterogeneity = _heterogeneity_section(result)
 
     bias_lines = []
     if adj:
@@ -161,6 +202,7 @@ def explain_ols(result) -> str:
                 *bias_lines,
             ]
         ),
+        *([heterogeneity] if heterogeneity else []),
         "\n".join(
             [
                 "CAVEATS",
@@ -247,6 +289,7 @@ def explain_iv(result) -> str:
 def explain_rct(result) -> str:
     T, Y = result._treatment, result._outcome
     lo, hi = result.conf_int
+    heterogeneity = _heterogeneity_section(result)
 
     blocks = [
         "\n".join(
@@ -277,6 +320,7 @@ def explain_rct(result) -> str:
                 f"SE = {result.std_err:.4f}, {_fmt_p(result.pvalue)}).",
             ]
         ),
+        *([heterogeneity] if heterogeneity else []),
         "\n".join(
             [
                 "CAVEATS",

{formative_ds-1.2.2 → formative_ds-2.0.0}/formative/causal/decision.py

@@ -46,51 +46,6 @@ class DecisionReport:
     robust: bool
     p_beneficial: float
 
-    def value_of_information(self, target_confidence: float = 0.95) -> str:
-        """
-        Estimate how much the standard error would need to shrink — and
-        approximately how many times larger the sample would need to be — to
-        reach ``target_confidence`` that the optimal decision is correct.
-
-        If the decision is already at or above ``target_confidence``, reports
-        that no additional data is needed.
-
-        Parameters
-        ----------
-        target_confidence : float
-            Desired probability that net benefit > 0 (default 0.95).
-
-        Returns
-        -------
-        str
-            A human-readable description of the value of information.
-        """
-        if self.p_beneficial >= target_confidence:
-            return (
-                f"Decision confidence is already {self.p_beneficial:.1%}, "
-                f"at or above the target of {target_confidence:.1%}. "
-                f"No additional data is needed to be confident in this decision."
-            )
-
-        # net_benefit / (se_net * z_target) = 1  →  se_net_required = net_benefit / z_target
-        # se_net = std_err_ate * benefit  →  std_err_required = se_net_required / benefit
-        z_target = norm.ppf(target_confidence)
-        se_net_current = abs(self.net_benefit_ci[1] - self.net_benefit_ci[0]) / (2 * 1.96)
-        if se_net_current == 0:
-            return "Cannot compute value of information: standard error is zero."
-
-        se_net_required = abs(self.net_benefit) / z_target
-        se_ratio = se_net_current / se_net_required
-        n_multiplier = se_ratio**2
-
-        return (
-            f"Current decision confidence: {self.p_beneficial:.1%} "
-            f"(target: {target_confidence:.1%}).\n"
-            f"The standard error on net benefit would need to shrink by "
-            f"{(1 - 1 / se_ratio):.1%} to reach the target.\n"
-            f"This requires approximately {n_multiplier:.1f}x the current sample size."
-        )
-
     def to_outcomes(
         self,
         scenarios: dict[str, float] | None = None,
@@ -110,7 +65,7 @@ class DecisionReport:
         -------
         dict[str, dict[str, float]]
             A ``{choice: {scenario: payoff}}`` structure accepted by any
-            ``formative.game`` rule (``maximin``, ``minimax_regret``,
+            ``formative.game`` rule (``maximin``, ``minimax``,
             ``hurwicz``, etc.). The ``"don't treat"`` payoff is 0 in every
             scenario — the status quo baseline.
 

{formative_ds-1.2.2 → formative_ds-2.0.0}/formative/causal/estimators/_base.py

@@ -29,6 +29,10 @@ class _BaseResult:
         lines.append("")
         return lines
 
+    def _extra_summary_lines(self) -> list[str]:
+        """Hook for subclasses to insert extra blocks before the assumptions footer."""
+        return []
+
     def decide(self, cost: float, benefit: float):
         """
         Compute a cost-benefit decision analysis from this causal estimate.