formative-ds 2.2.2__tar.gz → 2.2.4__tar.gz

{formative_ds-2.2.2 → formative_ds-2.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: formative-ds
-Version: 2.2.2
+Version: 2.2.4
 Summary: A Python library for quantitative reasoning.
 Project-URL: Homepage, https://getformative.dev
 Project-URL: Documentation, https://docs.getformative.dev
@@ -9,7 +9,7 @@ Author: Max Pagels
 License: MIT
 License-File: LICENSE
 Keywords: DAG,causal estimation,causal inference,econometrics,statistics
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3

formative_ds-2.2.4/TODO.md

@@ -0,0 +1,30 @@
+# TODO
+
+## Relax DAG validation for policy-learning features
+
+`RCTResult.learn_policy()` currently validates candidate features with
+`_validate_modifier_dag` (shared with CATE effect modifiers), which requires
+each feature to be an **ancestor of the outcome**. That requirement is
+stricter than the statistics need:
+
+- In an RCT, treatment is independent of every pre-treatment variable, so the
+  doubly robust value estimate is honest for a policy conditioning on *any*
+  pre-treatment feature — causal, proxy, or noise.
+- Proxy features (e.g. `income → zip`, `income → outcome`: zip causes nothing
+  but predicts who benefits) are valid and useful targeting features, yet are
+  rejected when the DAG is specified honestly.
+- Noise features can't inflate the honest out-of-fold value, and the
+  placebo/random-modifier refutation checks already guard against them.
+
+The **mediator exclusion must stay**: a descendant of the treatment is not
+actionable at assignment time and conditioning on it creates selection bias.
+
+Plan:
+
+- Give policy learning its own validation: feature must be a DAG node and not
+  a descendant of the treatment; drop the ancestor-of-outcome requirement.
+- Keep the stricter check for CATE effect modifiers, where the output is an
+  interpretive claim ("the effect differs by X") rather than just a rule and
+  its value.
+- Update the corresponding passage in `docs/causal/decisions.rst` (~line 231)
+  and the `learn_policy` docstring in `formative/causal/estimators/rct.py`.

{formative_ds-2.2.2 → formative_ds-2.2.4}/docs/causal/benchmarks.rst

@@ -118,7 +118,9 @@ treatment/outcome relationship. The observational DAG declares this:
         obs_dag.assume(c).causes("treat", "re78")
     obs_dag.assume("treat").causes("re78")
 
-    result = OLSObservational(obs_dag, treatment="treat", outcome="re78").fit(observational)
+    result = OLSObservational(
+        obs_dag, treatment="treat", outcome="re78"
+    ).fit(observational)
     print(result.summary())
 
 .. code-block:: text
@@ -156,7 +158,9 @@ each treated person only with the most similar controls:
 
     from formative.causal import PropensityScoreMatching
 
-    result = PropensityScoreMatching(obs_dag, treatment="treat", outcome="re78").fit(observational)
+    result = PropensityScoreMatching(
+        obs_dag, treatment="treat", outcome="re78"
+    ).fit(observational)
     print(result.summary())
 
 .. code-block:: text
@@ -293,7 +297,10 @@ Table 3 reports four cell means; formative's DiD will be built from exactly thes
 
     for state, name in [(1, "NJ"), (0, "PA")]:
         sub = raw[raw.STATE == state]
-        print(f"{name}: before {sub.fte_before.mean():.2f}, after {sub.fte_after.mean():.2f}")
+        print(
+            f"{name}: before {sub.fte_before.mean():.2f}, "
+            f"after {sub.fte_after.mean():.2f}"
+        )
 
 .. code-block:: text
 
@@ -317,8 +324,18 @@ binary group and time indicators:
 
     long = pd.concat(
         [
-            pd.DataFrame({"store": raw.SHEET, "nj": raw.STATE, "after": 0, "fte": raw.fte_before}),
-            pd.DataFrame({"store": raw.SHEET, "nj": raw.STATE, "after": 1, "fte": raw.fte_after}),
+            pd.DataFrame({
+                "store": raw.SHEET,
+                "nj": raw.STATE,
+                "after": 0,
+                "fte": raw.fte_before,
+            }),
+            pd.DataFrame({
+                "store": raw.SHEET,
+                "nj": raw.STATE,
+                "after": 1,
+                "fte": raw.fte_after,
+            }),
         ],
         ignore_index=True,
     ).dropna(subset=["fte"])

{formative_ds-2.2.2 → formative_ds-2.2.4}/docs/causal/decisions.rst

@@ -52,7 +52,11 @@ earnings using OLS with a DAG that encodes family background as a confounder:
    training   = 0.6 * background + rng.normal(size=N)
    earnings   = 3.0 * training + 1.2 * background + rng.normal(size=N)
 
-   df  = pd.DataFrame({"background": background, "training": training, "earnings": earnings})
+   df = pd.DataFrame({
+       "background": background,
+       "training": training,
+       "earnings": earnings,
+   })
    dag = DAG()
    dag.assume("background").causes("training", "earnings")
    dag.assume("training").causes("earnings")
@@ -85,7 +89,7 @@ But how confident are we in that estimate? And is it robust to estimation error?
      Decision confidence          :    100.0%
      Robust to estimation error   : Yes — decision is stable across 95% CI
 
-Game-theoretic robustness
+Robustness
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``decide()`` uses expected value maximisation: it picks "treat" when
@@ -96,7 +100,7 @@ treats a certain $37 gain and a 50/50 gamble between $0 and $74 identically.
 The ``robust`` flag is a first step toward robustness: it checks whether
 the decision flips anywhere inside the 95% confidence interval. But it
 only returns ``True`` or ``False``, and it is implicitly using the most
-conservative possible standard (the CI bounds).
+conservative possible standard (the confidence interval bounds).
 
 For finer control, call ``to_outcomes()`` on the report and pass the result
 to any rule in ``formative.game``:
@@ -118,8 +122,8 @@ to any rule in ``formative.game``:
 
 By default, the three scenarios correspond to the 10th, 50th, and 90th
 percentiles of the net-benefit sampling distribution (assumed normal with
-the se derived from the 95% CI). The ``"don't treat"`` payoff is 0 in
-every scenario — the status quo baseline.
+the standard error derived from the 95% confidence interval). The ``"don't treat"`` payoff is 0 in
+every scenario.
 
 You can supply your own scenario names and quantiles:
 
@@ -129,17 +133,19 @@ You can supply your own scenario names and quantiles:
        scenarios={"bear": 0.05, "base": 0.50, "bull": 0.95}
    )
 
-**Relationship to** ``robust``. ``robust=True`` is equivalent to
-``maximin`` returning the same choice as ``optimal`` when the scenarios are
-set to the CI bounds (quantiles 0.025 and 0.975). ``to_outcomes()``
+How does this differ from using ``robust``? ``robust=True`` is equivalent to
+``maximin``, returning the same choice when the scenarios are
+set to the confidence interval 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=...)``.
 
 Should we treat each segment?
 -----------------------------
 
-An average effect can hide groups where the treatment is worthless — or where
-it pays for itself several times over. When an estimator was fitted with an
+An average effect can hide groups where the treatment is worthless, or where
+it pays for itself several times over. It will also cause you to scale up a treatment
+that is not worth it for everyone.
+When an estimator is fitted with an
 ``effect_modifier`` (see :doc:`estimands`), ``decide_by_group(cost, benefit)``
 runs the same cost-benefit analysis within each level of the modifier and
 returns a mapping of level → :class:`~formative.DecisionReport`, so different
@@ -161,19 +167,33 @@ and everyone else not at all:
    tenure    = rng.choice(["<2y", "2-5y", ">5y"], size=N)
    region    = rng.choice(["north", "south"], size=N)
    coaching  = rng.integers(0, 2, size=N)
-   retention = 6.0 * coaching * (tenure == "<2y") + 2.0 * (tenure == ">5y") + rng.normal(size=N)
+   retention = (
+       6.0 * coaching * (tenure == "<2y")
+       + 2.0 * (tenure == ">5y")
+       + rng.normal(size=N)
+   )
 
-   df = pd.DataFrame({"tenure": tenure, "region": region, "coaching": coaching, "retention": retention})
+   df = pd.DataFrame({
+       "tenure": tenure,
+       "region": region,
+       "coaching": coaching,
+       "retention": retention,
+   })
 
    dag = DAG()
    dag.assume("coaching").causes("retention")
    dag.assume("tenure").causes("retention")
    dag.assume("region").causes("retention")
 
-   result = RCT(dag, treatment="coaching", outcome="retention", effect_modifier="tenure").fit(df)
+   result = RCT(
+       dag, treatment="coaching", outcome="retention", effect_modifier="tenure"
+   ).fit(df)
    for level, decision in result.decide_by_group(cost=2.5, benefit=1.0).items():
        lo, hi = decision.net_benefit_ci
-       print(f"{level:>5}: {decision.optimal:<12} net benefit {decision.net_benefit:+.2f}  [{lo:+.2f}, {hi:+.2f}]")
+       print(
+           f"{level:>5}: {decision.optimal:<12} "
+           f"net benefit {decision.net_benefit:+.2f}  [{lo:+.2f}, {hi:+.2f}]"
+       )
 
 .. code-block:: text
 
@@ -203,10 +223,9 @@ one less thing to get wrong.
 How it works
 ~~~~~~~~~~~~
 
-``learn_policy()`` implements doubly robust policy learning in the style of
-Athey & Wager (2021):
+``learn_policy()`` implements doubly robust policy learning:
 
-1. **Score every unit.** Each unit gets a cross-fitted AIPW score — an
+1. **Score every unit.** Each unit gets a cross-fitted score — an
    unbiased estimate of its individual treatment effect. Outcome models are
    fit by OLS on the candidate features over four folds and evaluated on the
    fifth, so no unit is scored by a model that saw it.
@@ -225,7 +244,7 @@ Athey & Wager (2021):
 
 Because the tree may split on any level of any candidate feature, features
 must be discrete: bin continuous columns before passing them in. Candidate
-features face the same DAG validation as effect modifiers — each must cause
+features face the same DAG validation as effect modifiers; each must cause
 the outcome and must not be a descendant of the treatment (targeting on a
 mediator is not actionable at assignment time).
 
@@ -238,7 +257,13 @@ features instead of choosing a segmentation ourselves:
 .. code-block:: python
 
    result = RCT(dag, treatment="coaching", outcome="retention").fit(df)
-   policy = result.learn_policy(df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=2)
+   policy = result.learn_policy(
+      df,
+      modifiers=["tenure", "region"],
+      cost=2.5,
+      benefit=1.0,
+      max_depth=2
+   )
    print(policy.summary())
 
 .. code-block:: text
@@ -286,10 +311,17 @@ it only helps recent hires in the north:
    coaching  = rng.integers(0, 2, size=N)
    helped    = (tenure == "<2y") & (region == "north")
    retention = 7.0 * coaching * helped + 2.0 * (tenure == ">5y") + rng.normal(size=N)
-   df = pd.DataFrame({"tenure": tenure, "region": region, "coaching": coaching, "retention": retention})
+   df = pd.DataFrame({
+       "tenure": tenure,
+       "region": region,
+       "coaching": coaching,
+       "retention": retention,
+   })
 
    result = RCT(dag, treatment="coaching", outcome="retention").fit(df)
-   policy = result.learn_policy(df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=2)
+   policy = result.learn_policy(
+       df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=2
+   )
    print(policy.summary())
 
 .. code-block:: text
@@ -316,7 +348,9 @@ back to treating all recent hires and burns money on the southern half:
 
 .. code-block:: python
 
-   result.learn_policy(df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=1).value
+   result.learn_policy(
+       df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=1
+   ).value
    # +0.34 per unit — versus +0.75 at depth 2
 
 When the deeper policy's value is clearly higher (as here), ship it; when the
@@ -339,7 +373,12 @@ segment-2 employees in the north:
    training = rng.integers(0, 2, size=N)
    effect   = 4.0 * (segment == 0) + 5.0 * ((segment == 2) & (region == "north"))
    earnings = effect * training + 0.5 * segment + rng.normal(size=N)
-   df = pd.DataFrame({"segment": segment, "region": region, "training": training, "earnings": earnings})
+   df = pd.DataFrame({
+       "segment": segment,
+       "region": region,
+       "training": training,
+       "earnings": earnings,
+   })
 
    dag = DAG()
    dag.assume("training").causes("earnings")
@@ -347,7 +386,13 @@ segment-2 employees in the north:
    dag.assume("region").causes("earnings")
 
    result = RCT(dag, treatment="training", outcome="earnings").fit(df)
-   policy = result.learn_policy(df, modifiers=["segment", "region"], cost=1.0, benefit=1.0, max_depth=2)
+   policy = result.learn_policy(
+      df, 
+      modifiers=["segment", "region"],
+      cost=1.0,
+      benefit=1.0,
+      max_depth=2
+   )
    print(policy.summary())
 
 .. code-block:: text

{formative_ds-2.2.2 → formative_ds-2.2.4}/docs/causal/introduction.rst

@@ -49,7 +49,7 @@ you choose.
 
 After you have obtained the result object, you can print a summary of the estimate and
 its assumptions. The assumptions are marked as testable or untestable depending on whether
-formative can check them. Most assumptions in causal inference are untestable by nature —
+formative can check them. Most assumptions in causal inference are untestable by nature, i.e.
 things you must argue for based on domain knowledge and theory.
 
 .. code-block:: python
@@ -83,7 +83,7 @@ communicating with non-technical audiences.
 **3. Refute**
 
 Once you have a result, run statistical checks that probe whether its assumptions hold
-in the data. Each check returns a clear pass or fail — but no set of tests can guarantee
+in the data. Each check returns a clear pass or fail, but no set of tests can guarantee
 validity. Use them as diagnostics, not proof. Causal inference is a judgment call, not a
 mathematical certainty.
 
@@ -104,10 +104,10 @@ mathematical certainty.
 
 **4. Decide**
 
-An estimate is rarely the end goal — the question is whether to act on it. Pass the
+An estimate is rarely the end goal; the question is whether to act on it. Pass the
 cost per unit of treatment applied and the value of one unit of improvement in the
 outcome, and formative turns the estimate and its uncertainty into a treat/don't-treat
-call. Suppose a unit of education costs $8 and a unit of income is worth $15:
+decision. Suppose a unit of education costs $8 and a unit of income is worth $15:
 
 .. code-block:: python
 
@@ -128,7 +128,12 @@ call. Suppose a unit of education costs $8 and a unit of income is worth $15:
      Decision confidence          :     100.0%
      Robust to estimation error   : Yes — decision is stable across 95% CI
 
-Depending on the estimator, decisions can go beyond a single call for everyone:
+You may ask why a cost must be passed; is it not enough if the estimate is positive?
+The answer is that a positive estimate does not guarantee that the treatment is worth it.
+If the estimate gives an effect of +1.0, but the treatment costs $10 and the outcome is worth $1,
+then the treatment is not worth it. The decision layer makes this explicit.
+
+Depending on the estimator you choose, decisions can go beyond a single call for everyone:
 per-group decisions via an effect modifier, or a learned treatment rule that
 decides *whom* to treat. See :doc:`decisions` for the full decision layer.
 

{formative_ds-2.2.2 → formative_ds-2.2.4}/formative/causal/dag.py

@@ -34,7 +34,7 @@ class DAG:
     your data.
 
     Build the graph by calling ``assume().causes()`` for each causal relationship
-    you believe holds. Include latent variables freely — if a node is not in
+    you believe holds. Include latent variables — if a node is not in
     your data at ``fit()`` time, the estimator treats it as unobserved.
 
     Example::

{formative_ds-2.2.2 → formative_ds-2.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "formative-ds"
-version = "2.2.2"
+version = "2.2.4"
 description = "A Python library for quantitative reasoning."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -12,7 +12,7 @@ license = {text = "MIT"}
 authors = [{name = "Max Pagels"}]
 keywords = ["causal inference", "causal estimation", "econometrics", "statistics", "DAG"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Science/Research",
     "Topic :: Scientific/Engineering :: Mathematics",
     "License :: OSI Approved :: MIT License",
@@ -48,7 +48,7 @@ docs = ["sphinx>=7,<10", "sphinx-rtd-theme>=2,<4", "sphinx-copybutton>=0.5,<0.6"
 packages = ["formative"]
 
 [tool.bumpversion]
-current_version = "2.2.2"
+current_version = "2.2.4"
 commit = true
 tag = true
 tag_name = "v{new_version}"

{formative_ds-2.2.2 → formative_ds-2.2.4}/site/2.2/_sources/causal/benchmarks.rst.txt

@@ -118,7 +118,9 @@ treatment/outcome relationship. The observational DAG declares this:
         obs_dag.assume(c).causes("treat", "re78")
     obs_dag.assume("treat").causes("re78")
 
-    result = OLSObservational(obs_dag, treatment="treat", outcome="re78").fit(observational)
+    result = OLSObservational(
+        obs_dag, treatment="treat", outcome="re78"
+    ).fit(observational)
     print(result.summary())
 
 .. code-block:: text
@@ -156,7 +158,9 @@ each treated person only with the most similar controls:
 
     from formative.causal import PropensityScoreMatching
 
-    result = PropensityScoreMatching(obs_dag, treatment="treat", outcome="re78").fit(observational)
+    result = PropensityScoreMatching(
+        obs_dag, treatment="treat", outcome="re78"
+    ).fit(observational)
     print(result.summary())
 
 .. code-block:: text
@@ -293,7 +297,10 @@ Table 3 reports four cell means; formative's DiD will be built from exactly thes
 
     for state, name in [(1, "NJ"), (0, "PA")]:
         sub = raw[raw.STATE == state]
-        print(f"{name}: before {sub.fte_before.mean():.2f}, after {sub.fte_after.mean():.2f}")
+        print(
+            f"{name}: before {sub.fte_before.mean():.2f}, "
+            f"after {sub.fte_after.mean():.2f}"
+        )
 
 .. code-block:: text
 
@@ -317,8 +324,18 @@ binary group and time indicators:
 
     long = pd.concat(
         [
-            pd.DataFrame({"store": raw.SHEET, "nj": raw.STATE, "after": 0, "fte": raw.fte_before}),
-            pd.DataFrame({"store": raw.SHEET, "nj": raw.STATE, "after": 1, "fte": raw.fte_after}),
+            pd.DataFrame({
+                "store": raw.SHEET,
+                "nj": raw.STATE,
+                "after": 0,
+                "fte": raw.fte_before,
+            }),
+            pd.DataFrame({
+                "store": raw.SHEET,
+                "nj": raw.STATE,
+                "after": 1,
+                "fte": raw.fte_after,
+            }),
         ],
         ignore_index=True,
     ).dropna(subset=["fte"])

{formative_ds-2.2.2 → formative_ds-2.2.4}/site/2.2/_sources/causal/decisions.rst.txt

@@ -52,7 +52,11 @@ earnings using OLS with a DAG that encodes family background as a confounder:
    training   = 0.6 * background + rng.normal(size=N)
    earnings   = 3.0 * training + 1.2 * background + rng.normal(size=N)
 
-   df  = pd.DataFrame({"background": background, "training": training, "earnings": earnings})
+   df = pd.DataFrame({
+       "background": background,
+       "training": training,
+       "earnings": earnings,
+   })
    dag = DAG()
    dag.assume("background").causes("training", "earnings")
    dag.assume("training").causes("earnings")
@@ -85,7 +89,7 @@ But how confident are we in that estimate? And is it robust to estimation error?
      Decision confidence          :    100.0%
      Robust to estimation error   : Yes — decision is stable across 95% CI
 
-Game-theoretic robustness
+Robustness
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``decide()`` uses expected value maximisation: it picks "treat" when
@@ -96,7 +100,7 @@ treats a certain $37 gain and a 50/50 gamble between $0 and $74 identically.
 The ``robust`` flag is a first step toward robustness: it checks whether
 the decision flips anywhere inside the 95% confidence interval. But it
 only returns ``True`` or ``False``, and it is implicitly using the most
-conservative possible standard (the CI bounds).
+conservative possible standard (the confidence interval bounds).
 
 For finer control, call ``to_outcomes()`` on the report and pass the result
 to any rule in ``formative.game``:
@@ -118,8 +122,8 @@ to any rule in ``formative.game``:
 
 By default, the three scenarios correspond to the 10th, 50th, and 90th
 percentiles of the net-benefit sampling distribution (assumed normal with
-the se derived from the 95% CI). The ``"don't treat"`` payoff is 0 in
-every scenario — the status quo baseline.
+the standard error derived from the 95% confidence interval). The ``"don't treat"`` payoff is 0 in
+every scenario.
 
 You can supply your own scenario names and quantiles:
 
@@ -129,17 +133,19 @@ You can supply your own scenario names and quantiles:
        scenarios={"bear": 0.05, "base": 0.50, "bull": 0.95}
    )
 
-**Relationship to** ``robust``. ``robust=True`` is equivalent to
-``maximin`` returning the same choice as ``optimal`` when the scenarios are
-set to the CI bounds (quantiles 0.025 and 0.975). ``to_outcomes()``
+How does this differ from using ``robust``? ``robust=True`` is equivalent to
+``maximin``, returning the same choice when the scenarios are
+set to the confidence interval 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=...)``.
 
 Should we treat each segment?
 -----------------------------
 
-An average effect can hide groups where the treatment is worthless — or where
-it pays for itself several times over. When an estimator was fitted with an
+An average effect can hide groups where the treatment is worthless, or where
+it pays for itself several times over. It will also cause you to scale up a treatment
+that is not worth it for everyone.
+When an estimator is fitted with an
 ``effect_modifier`` (see :doc:`estimands`), ``decide_by_group(cost, benefit)``
 runs the same cost-benefit analysis within each level of the modifier and
 returns a mapping of level → :class:`~formative.DecisionReport`, so different
@@ -161,19 +167,33 @@ and everyone else not at all:
    tenure    = rng.choice(["<2y", "2-5y", ">5y"], size=N)
    region    = rng.choice(["north", "south"], size=N)
    coaching  = rng.integers(0, 2, size=N)
-   retention = 6.0 * coaching * (tenure == "<2y") + 2.0 * (tenure == ">5y") + rng.normal(size=N)
+   retention = (
+       6.0 * coaching * (tenure == "<2y")
+       + 2.0 * (tenure == ">5y")
+       + rng.normal(size=N)
+   )
 
-   df = pd.DataFrame({"tenure": tenure, "region": region, "coaching": coaching, "retention": retention})
+   df = pd.DataFrame({
+       "tenure": tenure,
+       "region": region,
+       "coaching": coaching,
+       "retention": retention,
+   })
 
    dag = DAG()
    dag.assume("coaching").causes("retention")
    dag.assume("tenure").causes("retention")
    dag.assume("region").causes("retention")
 
-   result = RCT(dag, treatment="coaching", outcome="retention", effect_modifier="tenure").fit(df)
+   result = RCT(
+       dag, treatment="coaching", outcome="retention", effect_modifier="tenure"
+   ).fit(df)
    for level, decision in result.decide_by_group(cost=2.5, benefit=1.0).items():
        lo, hi = decision.net_benefit_ci
-       print(f"{level:>5}: {decision.optimal:<12} net benefit {decision.net_benefit:+.2f}  [{lo:+.2f}, {hi:+.2f}]")
+       print(
+           f"{level:>5}: {decision.optimal:<12} "
+           f"net benefit {decision.net_benefit:+.2f}  [{lo:+.2f}, {hi:+.2f}]"
+       )
 
 .. code-block:: text
 
@@ -203,10 +223,9 @@ one less thing to get wrong.
 How it works
 ~~~~~~~~~~~~
 
-``learn_policy()`` implements doubly robust policy learning in the style of
-Athey & Wager (2021):
+``learn_policy()`` implements doubly robust policy learning:
 
-1. **Score every unit.** Each unit gets a cross-fitted AIPW score — an
+1. **Score every unit.** Each unit gets a cross-fitted score — an
    unbiased estimate of its individual treatment effect. Outcome models are
    fit by OLS on the candidate features over four folds and evaluated on the
    fifth, so no unit is scored by a model that saw it.
@@ -225,7 +244,7 @@ Athey & Wager (2021):
 
 Because the tree may split on any level of any candidate feature, features
 must be discrete: bin continuous columns before passing them in. Candidate
-features face the same DAG validation as effect modifiers — each must cause
+features face the same DAG validation as effect modifiers; each must cause
 the outcome and must not be a descendant of the treatment (targeting on a
 mediator is not actionable at assignment time).
 
@@ -238,7 +257,13 @@ features instead of choosing a segmentation ourselves:
 .. code-block:: python
 
    result = RCT(dag, treatment="coaching", outcome="retention").fit(df)
-   policy = result.learn_policy(df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=2)
+   policy = result.learn_policy(
+      df,
+      modifiers=["tenure", "region"],
+      cost=2.5,
+      benefit=1.0,
+      max_depth=2
+   )
    print(policy.summary())
 
 .. code-block:: text
@@ -286,10 +311,17 @@ it only helps recent hires in the north:
    coaching  = rng.integers(0, 2, size=N)
    helped    = (tenure == "<2y") & (region == "north")
    retention = 7.0 * coaching * helped + 2.0 * (tenure == ">5y") + rng.normal(size=N)
-   df = pd.DataFrame({"tenure": tenure, "region": region, "coaching": coaching, "retention": retention})
+   df = pd.DataFrame({
+       "tenure": tenure,
+       "region": region,
+       "coaching": coaching,
+       "retention": retention,
+   })
 
    result = RCT(dag, treatment="coaching", outcome="retention").fit(df)
-   policy = result.learn_policy(df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=2)
+   policy = result.learn_policy(
+       df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=2
+   )
    print(policy.summary())
 
 .. code-block:: text
@@ -316,7 +348,9 @@ back to treating all recent hires and burns money on the southern half:
 
 .. code-block:: python
 
-   result.learn_policy(df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=1).value
+   result.learn_policy(
+       df, modifiers=["tenure", "region"], cost=2.5, benefit=1.0, max_depth=1
+   ).value
    # +0.34 per unit — versus +0.75 at depth 2
 
 When the deeper policy's value is clearly higher (as here), ship it; when the
@@ -339,7 +373,12 @@ segment-2 employees in the north:
    training = rng.integers(0, 2, size=N)
    effect   = 4.0 * (segment == 0) + 5.0 * ((segment == 2) & (region == "north"))
    earnings = effect * training + 0.5 * segment + rng.normal(size=N)
-   df = pd.DataFrame({"segment": segment, "region": region, "training": training, "earnings": earnings})
+   df = pd.DataFrame({
+       "segment": segment,
+       "region": region,
+       "training": training,
+       "earnings": earnings,
+   })
 
    dag = DAG()
    dag.assume("training").causes("earnings")
@@ -347,7 +386,13 @@ segment-2 employees in the north:
    dag.assume("region").causes("earnings")
 
    result = RCT(dag, treatment="training", outcome="earnings").fit(df)
-   policy = result.learn_policy(df, modifiers=["segment", "region"], cost=1.0, benefit=1.0, max_depth=2)
+   policy = result.learn_policy(
+      df, 
+      modifiers=["segment", "region"],
+      cost=1.0,
+      benefit=1.0,
+      max_depth=2
+   )
    print(policy.summary())
 
 .. code-block:: text