ergodic 0.3.0__tar.gz → 0.3.2__tar.gz

{ergodic-0.3.0 → ergodic-0.3.2}/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.2] - 2026-10-24
+
+### Fixed
+- Linear and GCM use `erfc` for normal tails: e.g. z=9 now gives approximately
+  2.26e-19 instead of zero. Values below binary64 range still underflow (z=40);
+  they are not floored or presented as accurately representable probabilities.
+  PCMCI can change its test count: the documented time-series fixture retains
+  all five links, while its unconstrained CI queries change from 49 to 47
+  (the knowledge-constrained run remains at 37).
+- `GraphSamples.top(k)` groups numerical weight ties at relative tolerance 1e-12,
+  then log-target ties at absolute tolerance 1e-9, anchored at each group's largest
+  value, and sorts final ties by named directed-edge tuples. Weights are unchanged.
+- MMPC forward associations within absolute p-value distance 1e-15 now tie by
+  variable name; alpha decisions keep unrounded p-values. This stabilizes greedy
+  admission when tiny tails split, without claiming invariance to variable renaming.
+  On 150 registered seven-node worlds, the tie change alone changed no skeletons
+  (137 total skeleton errors before and after); PC/FCI/RFCI were also unchanged.
+
+### Documentation
+- GCM's default KNN remains uncalibrated. A registered direct-CI study (200 paired
+  seeds per family/sample size) found 7.5–12% null rejection at nominal 5%.
+  OLS failed on nonlinear conditional means, so neither qualified as a general
+  default. Discover and graph-testing guides now disclose the measured limits.
+
+## [0.3.1] - 2026-10-20
+
+Correctness and inference safeguards from the pre-release audit (API-179 through
+API-182). No new model families or hosted capabilities are added.
+
+### Fixed
+- Fitted CATE predictors reuse their training category vocabulary. Reordering
+  categorical metadata no longer swaps predictions; unknown categories and
+  incompatible prediction schemas fail explicitly.
+- `estimate_effect(strategy="t_learner")` selects separate treatment-arm models,
+  consistently with `cate(method="t_learner")`. Contradictory alias settings fail.
+- GCM refuses constant endpoints, interpolating nuisance fits and degenerate
+  residual products rather than returning a misleading independence p-value.
+- Failed cross-fitted heterogeneity rankings no longer fall back to in-sample
+  rankings for inferential summaries or CATE model selection.
+  DML has no honest out-of-fold ranking proxy, so its GATES, CLAN, RATE and
+  calibration summaries now refuse too; BLP and descriptive effects remain available.
+
+### Changed
+- Frequentist AIPW uses cross-fitting by default. Explicit in-sample mode remains
+  available; Bayesian nuisance fits retain their documented in-sample posterior
+  path. Results report the resolved mode and propensity diagnostics.
+- Poor estimated overlap triggers diagnostics and warnings; severely degenerate
+  propensity fits fail by default. An explicit override does not certify valid
+  inference, and no rows are silently trimmed.
+- Generic instrumental-variable estimates are labeled `linear_iv`. A binary
+  complier `late` interpretation requires explicit assumptions and the supported
+  treatment/instrument configuration. Scalar results retain identification.
+
+### Migration
+
+Point estimates and intervals can change because of corrected fitting and method
+selection. Set seeds explicitly when comparing runs. To request the old parametric
+AIPW recipe, use `mode="in_sample"`; this does not make arbitrary interpolating
+learners valid. Inspect overlap diagnostics rather than suppressing failures.
+Existing code that reads the IV target string must accept `linear_iv` for generic
+IV coefficients. See the effect-estimation and heterogeneous-effect guides for
+precise modes, assumptions and failure behavior.
+
 ## [0.3.0] - 2026-10-17
 
 To be released together with welt-client 0.14 (API-164): decoding with domain knowledge
@@ -943,7 +1006,9 @@ inference, discovery, process, SCM, and forecast pillars.
   silently with single-graph semantics; it now dispatches on the face, and
   mixed graphs raise instead of being misread.
 
-[Unreleased]: https://github.com/ergodic-ai/ergodic/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/ergodic-ai/ergodic/compare/v0.3.2...HEAD
+[0.3.2]: https://github.com/ergodic-ai/ergodic/compare/v0.3.1...v0.3.2
+[0.3.1]: https://github.com/ergodic-ai/ergodic/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/ergodic-ai/ergodic/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/ergodic-ai/ergodic/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/ergodic-ai/ergodic/compare/v0.1.1...v0.2.0

{ergodic-0.3.0 → ergodic-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ergodic
-Version: 0.3.0
+Version: 0.3.2
 Summary: Causal AI: causal discovery, causal inference, and process intelligence.
 Project-URL: Homepage, https://docs.ergodic.dev
 Project-URL: Documentation, https://docs.ergodic.dev
@@ -89,7 +89,7 @@ Alarm --> MaryCalls
 Alarm <-- Burglary
 Alarm <-- Earthquake
 Identification(adjustment: P(JohnCalls | do(Burglary)) = sum_z P(JohnCalls | Burglary, z) P(z), with z = {Earthquake})
-EffectEstimate(aipw, analytic: ate=0.7982, se=0.0333, 95% CI [0.733, 0.863], n=10000)
+EffectEstimate(aipw, analytic: ate=0.7997, se=0.0337, 95% CI [0.734, 0.866], n=10000)
 ```
 
 The true effect, from the network's own tables, is 0.793: inside the interval. The

{ergodic-0.3.0 → ergodic-0.3.2}/README.md

@@ -43,7 +43,7 @@ Alarm --> MaryCalls
 Alarm <-- Burglary
 Alarm <-- Earthquake
 Identification(adjustment: P(JohnCalls | do(Burglary)) = sum_z P(JohnCalls | Burglary, z) P(z), with z = {Earthquake})
-EffectEstimate(aipw, analytic: ate=0.7982, se=0.0333, 95% CI [0.733, 0.863], n=10000)
+EffectEstimate(aipw, analytic: ate=0.7997, se=0.0337, 95% CI [0.734, 0.866], n=10000)
 ```
 
 The true effect, from the network's own tables, is 0.793: inside the interval. The

{ergodic-0.3.0 → ergodic-0.3.2}/docs/case-studies/01-birthweight.py

@@ -170,10 +170,10 @@ adjusted
 # [estimating effects](../learn/03-estimating-effects.py); this page trusts the default and
 # reads the number.
 #
-# The number is about -222 g, with a 95 percent interval that runs roughly -273 to -172. So
-# closing the back door moved the estimate by some 50 g, from -275 toward zero. That 50 g was
+# The number is about -220 g, with a 95 percent interval that runs roughly -271 to -168. So
+# closing the back door moved the estimate by some 56 g, from -275 toward zero. That 56 g was
 # the imbalance from the balance table: the part of the raw gap that was really the mothers
-# differing, not the smoking. What's left, -222 g, is the effect of smoking with those
+# differing, not the smoking. What's left, -220 g, is the effect of smoking with those
 # differences held fixed.
 
 # %%
@@ -190,8 +190,8 @@ summary.round(1)
 # %% [markdown]
 # The published adjusted figure on this same extract is about -231 g: the doubly robust (AIPW)
 # estimate in the Stata treatment-effects manual, with a standard error of 26 g. Our
-# adjustment lands at -222 g, well inside that interval. We started 44 g away from the
-# published number and ended 9 g away, having moved in the right direction for the right
+# adjustment lands at -220 g, well inside that interval. We started 44 g away from the
+# published number and ended 12 g away, having moved in the right direction for the right
 # reason. The remaining gap is down to which confounders enter and how each model is fit (the
 # manual's own estimators range from about -210 to -240 g), and the published interval and
 # ours overlap heavily. This is what a closed back door looks like on real data: not the
@@ -200,7 +200,7 @@ summary.round(1)
 #
 # ## What we had to assume
 #
-# Be exact about the claim. The -222 g holds if the 17 measured confounders close every back
+# Be exact about the claim. The -220 g holds if the 17 measured confounders close every back
 # door between smoking and birthweight. That is an assumption about the world, and no amount
 # of data inside this table can prove it. If something we didn't measure moves both smoking
 # and birthweight, say a genetic factor, or diet, or stress, then a path is still open and
@@ -234,7 +234,7 @@ print(f"placebo estimate: {ref.refuted_value:+.1f} g  (mean over 20 scrambles)")
 print(f"verdict: {'passed' if ref.passed else 'FAILED'}")
 
 # %% [markdown]
-# The real estimate is -222 g; the placebo, averaged over 20 random shuffles, is about +3 g,
+# The real estimate is -220 g; the placebo, averaged over 20 random shuffles, is about +2 g,
 # a rounding error next to the real effect. The pipeline finds nothing when there's nothing
 # to find. That's a green light, and it's worth being clear about what color of green. It
 # rules out one failure mode, a bug or a quirk manufacturing an effect from noise. It says
@@ -243,7 +243,7 @@ print(f"verdict: {'passed' if ref.passed else 'FAILED'}")
 # fire inspection.
 #
 # That's the case, end to end. A balance table that showed the bias before any model ran, a
-# naive -275 g that the imbalance inflated, an adjusted -222 g that landed on the published
+# naive -275 g that the imbalance inflated, an adjusted -220 g that landed on the published
 # neighborhood, and a placebo check that came back clean. The one input the data couldn't
 # supply was the graph: the arrows that said which 17 variables to adjust for and which arrow
 # to measure. Here we knew them from how the records are collected. When you don't, you can

{ergodic-0.3.0 → ergodic-0.3.2}/docs/case-studies/03-pension401k.py

@@ -121,7 +121,7 @@ naive = estimate_effect(dag([f"{ds.treatment} -> {ds.outcome}"]), ds.data, ds.tr
 print(f"naive gap: ${naive.value:,.0f}")
 
 # %% [markdown]
-# About $19,559, the headline. The balance table already told us why it's too big. Higher
+# About $19,560, the headline. The balance table already told us why it's too big. Higher
 # earners are both more often eligible and wealthier, so the contrast sweeps the income gap
 # into the effect and reports the sum. The single arrow is a claim, that nothing else moves
 # both eligibility and wealth, and the table is nine counts against it. Income alone, an SMD

{ergodic-0.3.0 → ergodic-0.3.2}/docs/case-studies/06-clv.py

@@ -168,9 +168,10 @@ lo, hi = ate.interval()
 print(f"adjusted effect: ${ate.value:.2f}   CI [{lo:.1f}, {hi:.1f}]   truth ${tau.mean():.2f}")
 
 # %% [markdown]
-# The adjusted effect lands at 23.65 dollars, interval 22.4 to 24.9, right on the planted 23.39. The
-# confounding is gone, and the honest read of the average perk is now in front of us: it costs 25
-# and returns 23, so rolled out to everyone it loses a little money on every customer. A team that
+# The adjusted effect lands at 23.87 dollars, interval 22.4 to 25.3, close to the planted 23.39.
+# It costs 25 and returns about 24: the point estimate suggests a small average loss, but the
+# interval includes break-even. Under the graph assumptions, adjustment removes the measured
+# confounding; it does not prove the assumptions. A team that
 # stopped here would kill the program. That would be a mistake, and the reason is the second error.
 #
 # ## Predicted value is not movable value
@@ -345,7 +346,7 @@ print(f"real effect    : ${ref.estimand_value:.2f}")
 print(f"placebo (mean) : ${ref.refuted_value:.2f}   p = {ref.p_value:.3f}   passed: {ref.passed}")
 
 # %% [markdown]
-# Scrambled, the effect collapses to roughly zero, far from the real 23.65, and the placebo runs
+# Scrambled, the effect collapses to roughly zero, far from the real 23.87, and the placebo runs
 # almost never reach it. That rules out a leak firing on noise. It says nothing about an unmeasured
 # trait, some loyalty the columns don't capture, that pushes a customer toward both the perk and a
 # fat balance.

{ergodic-0.3.0 → ergodic-0.3.2}/docs/case-studies/07-churn.py

@@ -186,11 +186,15 @@ print(f"adjusted effect  : {est.value:+.3f}   CI [{lo:.3f}, {hi:.3f}]")
 print(f"truth            : {true_effect:+.3f}")
 
 # %% [markdown]
-# The sign flips. The naive plus 22 points becomes minus 11, interval minus 12.4 to minus 10.2,
+# The sign flips. The naive plus 22 points becomes minus 13.1, interval minus 15.6 to minus 10.6,
 # straddling the planted minus 12.2. Once the comparison holds risk fixed, the offer cuts churn by
-# about 11 points, close to the truth. The program the quarterly numbers condemned is preventing
+# about 13 points, close to the truth. The program the quarterly numbers condemned is preventing
 # real departures, not causing them. The naive table had it exactly backwards.
 #
+# The fit also warns about limited overlap: 28.4% of propensity estimates are in the
+# tails outside [0.01, 0.99], and 1.9% require clipping. Treat the estimate cautiously;
+# adjustment does not create comparisons where the data provides little support.
+#
 # ## Where the data runs out
 #
 # Adjustment worked, but it leans on having low-risk and high-risk customers in both groups to
@@ -361,7 +365,7 @@ print(f"placebo (mean) : {ref.refuted_value:+.3f}   p = {ref.p_value:.3f}   pass
 # tests the pipeline, not the assumption.
 #
 # Two readings of the same quarter. The naive table said the save program triples churn and should
-# die. Holding risk fixed, the program cuts churn by about 11 points and should grow, aimed at the
+# die. Holding risk fixed, the program cuts churn by about 13 points and should grow, aimed at the
 # customers it can move rather than the ones most likely to leave. The companion
 # [lifetime-value study](06-clv.py) tells the mirror-image story on a continuous outcome, where the
 # trap is targeting the valuable instead of the movable. For the methods, see

{ergodic-0.3.0 → ergodic-0.3.2}/docs/learn/09-process-intelligence.py

@@ -193,7 +193,7 @@ lo_d, hi_d = disc.interval()
 print(f"discovered graph: {disc.value:+.2f} h   95% CI [{lo_d:+.2f}, {hi_d:+.2f}]")
 
 # %% [markdown]
-# Both routes print +4.89 with an interval covering the planted five, a long way from the
+# Both routes print +4.87 with an interval covering the planted five, a long way from the
 # variant table's 10.2. They agree to the printed digit because both graphs close the same
 # back door, adjusting for complexity; the hand graph adjusts for workload too, which is
 # unrelated to the review decision here and moves nothing visible. Discovery found the

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/assumptions.md

@@ -46,15 +46,15 @@ print(identify_effect(hidden, smoking, weight))
 ```
 
 ```output from="assumptions_demo.py"
-17 confounders: EffectEstimate(aipw, analytic: ate=-222.3, se=25.8, 95% CI [-273, -172], n=4642)
+17 confounders: EffectEstimate(aipw, analytic: ate=-219.5, se=26.3, 95% CI [-271, -168], n=4642)
 no confounders: EffectEstimate(aipw, analytic: ate=-275.3, se=21.2, 95% CI [-317, -234], n=4642)
 Identification(not identifiable, ['mbsmoke'] -> ['bweight'])
 ```
 
 - **Step 2.** With all 17 confounders in the graph, smoking lowers birthweight by
-  about 222 g.
+  about 220 g.
 - **Step 3.** With none, the estimate is the raw difference, about 275 g. Nothing in
-  the data says which graph is right; the 53 g gap is your assumption at work.
+  the data says which graph is right; the 56 g gap is your assumption at work.
 - **Step 4.** With an unmeasured cause `U` of both smoking and birthweight, and no
   mediator or instrument to route around it, the effect is not identifiable. ergodic
   says so instead of returning a number.

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/choose-a-method.md

@@ -124,10 +124,15 @@ heuristic except A*, and GES returns the mode's equivalence class as a CPDAG.
 
 ## Give GCM a learner
 
-`GCM` turns any regression model into a test. `learner=` takes an alias (`"ols"`,
+`GCM` uses a regression model to form a residual covariance test. `learner=` takes an alias (`"ols"`,
 `"knn"`) or any scikit-learn regressor, such as
 `RandomForestRegressor(min_samples_leaf=20)`. The default is the built-in
-nearest-neighbours regressor.
+nearest-neighbours regressor. Fits and residuals use the same rows. A learner
+that interpolates its training targets, such as an unrestricted decision tree,
+leaves no residual variation and raises `ValueError`. Constant endpoints and
+constant residual products also raise: GCM cannot form a valid p-value in these
+cases. Use a less flexible learner when a fit removes all residual variation.
+Nonzero residual variation alone does not establish a learner's calibration.
 
 Give the data in one place. Inside `discover`, build the test without data, as in
 step 5:
@@ -166,3 +171,17 @@ and restrict the search to the screen (see
 - [Python reference](reference-discovery.md): every method, test and score.
 
 </div>
+
+!!! caution "GCM learner calibration"
+    The default GCM learner remains KNN; it is not a generally calibrated CI test.
+    A paired 200-seed direct-CI diagnostic at alpha 0.05 found null rejection rates
+    of 9.5%/7.5% (linear), 12%/10% (quadratic), and 10%/9% (sine), at n=200/1000.
+    OLS gave 7.5%/5%, 100%/100%, and 99%/100%, respectively: replacing KNN with
+    OLS would fail badly for these nonlinear conditional means. Neither qualified
+    across all cells of the registered 2–8% investigation band, so the default
+    is unchanged. All cells used 200 trials with zero refusals; 95% Wilson intervals
+    for the KNN rates span roughly 4.6–17.2%. These are direct-CI results, distinct
+    from the earlier ~30% rejection of true graphs by Fisher's combined test.
+    Learner choice must match the conditional mean; these diagnostics do not
+    establish calibration for arbitrary data or guarantee detection of dependence.
+    The reproducible protocol is in `scripts/audits/qualify_gcm.py`.

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/discover-a-graph.md

@@ -150,3 +150,17 @@ decodes the model's edge probabilities locally. See
 - [Python reference](reference-discovery.md): every method and its options.
 
 </div>
+
+!!! caution "GCM learner calibration"
+    The default GCM learner remains KNN; it is not a generally calibrated CI test.
+    A paired 200-seed direct-CI diagnostic at alpha 0.05 found null rejection rates
+    of 9.5%/7.5% (linear), 12%/10% (quadratic), and 10%/9% (sine), at n=200/1000.
+    OLS gave 7.5%/5%, 100%/100%, and 99%/100%, respectively: replacing KNN with
+    OLS would fail badly for these nonlinear conditional means. Neither qualified
+    across all cells of the registered 2–8% investigation band, so the default
+    is unchanged. All cells used 200 trials with zero refusals; 95% Wilson intervals
+    for the KNN rates span roughly 4.6–17.2%. These are direct-CI results, distinct
+    from the earlier ~30% rejection of true graphs by Fisher's combined test.
+    Learner choice must match the conditional mean; these diagnostics do not
+    establish calibration for arbitrary data or guarantee detection of dependence.
+    The reproducible protocol is in `scripts/audits/qualify_gcm.py`.

ergodic-0.3.2/docsite/pages/estimate-average-effect.md

@@ -0,0 +1,168 @@
+# Estimate an average effect
+
+Write down which variables confound a treatment and an outcome, then estimate the
+average effect with an interval. The example measures what smoking during pregnancy
+does to birthweight.
+
+!!! need "You'll need"
+    - ergodic, installed with `pip install "ergodic"`.
+    - A list of confounders: variables that affect both the treatment and the outcome.
+
+## Run the program
+
+The bundled birthweight data is the extract of US natality records used by Cattaneo
+(2010): 4,642 singleton births in Pennsylvania, with the mother's smoking, the baby's
+weight in grams and 17 background variables.
+
+```python file="average_effect.py"
+from ergodic import dag, estimate_effect
+from ergodic.datasets import load_birthweight
+
+# 1. Load 4,642 births: the mother's smoking, the birthweight and 17 confounders.
+births = load_birthweight()
+smoking, weight = births.treatment, births.outcome
+print(smoking, "->", weight, "with", len(births.confounders), "confounders")
+
+# 2. Draw the graph: each confounder affects both smoking and birthweight.
+edges = [f"{c} -> {smoking}" for c in births.confounders]
+edges += [f"{c} -> {weight}" for c in births.confounders]
+graph = dag([*edges, f"{smoking} -> {weight}"])
+
+# 3. Compare the raw difference in mean birthweight.
+rows = births.data.to_pandas()
+means = rows.groupby(smoking, observed=True)[weight].mean()
+print(f"raw difference: {means['smoker'] - means['nonsmoker']:.1f} g")
+
+# 4. Estimate the average effect, adjusting for the confounders.
+estimate = estimate_effect(
+    graph, births.data, smoking, weight, treated=births.treated, random_state=0
+)
+print(estimate)
+low, high = estimate.interval()
+print(f"95% interval: {low:.0f} g to {high:.0f} g")
+```
+
+```output from="average_effect.py"
+mbsmoke -> bweight with 17 confounders
+raw difference: -275.3 g
+EffectEstimate(aipw, analytic: ate=-219.5, se=26.3, 95% CI [-271, -168], n=4642)
+95% interval: -271 g to -168 g
+```
+
+- Babies of smokers weigh 275 g less on average. Part of that gap comes from the
+  confounders, not from smoking.
+- Adjusted for the confounders, smoking lowers birthweight by about 220 g. The 95%
+  interval runs from 271 g to 168 g lower. The Stata treatment-effects manual's
+  doubly robust estimate on the same extract is −231 g (standard error 26 g), well
+  inside that interval; `births.target` records it with its source.
+- `aipw` is the augmented inverse-probability-weighted estimator. It combines an
+  outcome model and a propensity model, and stays consistent if either one is right.
+
+## Draw the graph
+
+The graph is your assumption about the world. Each confounder points at both the
+treatment and the outcome:
+
+```python
+edges = [f"{c} -> {smoking}" for c in births.confounders]
+edges += [f"{c} -> {weight}" for c in births.confounders]
+graph = dag([*edges, f"{smoking} -> {weight}"])
+```
+
+`estimate_effect` reads the adjustment set from this graph. You never pass the
+confounders to it directly.
+
+## Choose the treated level
+
+`treated=` names the level that counts as treatment. Here the `mbsmoke` column holds
+`"smoker"` and `"nonsmoker"`, and `births.treated` is `"smoker"`. The estimate is
+the mean outcome if everyone were treated minus the mean if no one were.
+
+!!! caution "The estimate is only as good as the graph"
+    It assumes no confounder is missing from the list. A variable that affects both
+    smoking and birthweight, but is not in the data, biases the result. No
+    check on this page can detect such a variable.
+
+By default the propensity model is logistic regression. The outcome model is
+ordinary least squares for a continuous outcome, as here, and logistic regression
+for a binary one. Pass `learner=` (an alias, a learner, or a mapping from slot to
+learner) to use other models.
+
+## Cross-fitting and overlap
+
+AIPW now defaults to `mode="auto"`: frequentist nuisances use held-out predictions
+from five shuffled, treatment-stratified folds. Set `n_folds=` and `random_state=`
+explicitly for a recorded protocol. If no seed is supplied, AIPW uses seed 0 for
+the split. Diagnostics report `n_folds_requested`, the number of nonempty folds
+actually used as `n_folds`, and `crossfit_seed`. Both arms need at least two rows;
+fold counts must be integers from 2 through the number of rows.
+
+Cross-fitting prevents evaluating nuisance residuals on their own fitting rows.
+It does not make every learner safe: valid ATE intervals also need overlap,
+suitable nuisance convergence rates and independent observations. An unrestricted
+decision-tree propensity model can predict only 0 and 1 even on held-out rows;
+the default guard refuses that fit. This remains AIPW, with its counterfactual
+outcome regressions and propensity residual corrections, rather than a partially
+linear DML model. See [Chernozhukov et al.](https://arxiv.org/abs/1608.00060).
+
+`mode="in_sample"` selects the old parametric fitting path explicitly. Its
+influence-score interval needs appropriate parametric or empirical-process
+conditions; unrestricted interpolating learners are not qualified. With any
+Bayesian nuisance, `auto` preserves the in-sample posterior or posterior-mean
+fallback without repeatedly fitting a sampler. `cross_fitted=0` and
+`bayesian_in_sample=1` report that choice. Explicit `mode="cross_fitted"` refuses
+Bayesian slots because cross-fitted posterior inference is not implemented.
+
+Inspect `estimate.diagnostics`: `propensity_min`, `propensity_max`, and the
+`propensity_q01`, `q05`, `median`, `q95` and `q99` entries use raw predictions,
+before clipping. `propensity_clipped_fraction` records clipping;
+`treated_effective_n`, `control_effective_n`, and each arm's `weight_max` and
+`weight_q99` describe the clipped ATE inverse weights. `att_control_effective_n`
+and `att_control_weight_max` describe ATT odds weights. For a Bayesian posterior,
+these summaries use the posterior mean propensity; `posterior_draw_clipped_fraction`
+and `posterior_draw_tail_fraction` separately summarize all propensity draw cells.
+
+AIPW, IPW and stratification accept `overlap="warn"` (default), `"raise"`, or
+`"ignore"`, plus `overlap_threshold=0.01` and `clip=0.001`. The default warns when
+at least 10% of raw predictions lie outside `[0.01, 0.99]`, or an arm's effective
+size falls below 10% of its observed count. It refuses when at least 50% require
+clipping. `raise` also refuses moderate warnings; `ignore` explicitly overrides
+these diagnostic guards, but invalid probabilities always fail. These thresholds
+are diagnostic choices, not a test of population positivity. A result below the
+thresholds is not a certificate of valid inference. Clipping cannot restore
+missing support. No rows are trimmed; stratification refuses an occupied stratum
+with a missing arm instead of dropping it and changing the estimand.
+
+## Instrumental-variable targets
+
+Instrument estimators now default to `target="linear_iv"`, including continuous
+treatment and PLIV. This replaces the old automatic `late` label. The numerical
+coefficient is unchanged; consumers checking `EffectTarget.LATE` should migrate to
+`EffectTarget.LINEAR_IV` when they mean the generic linear IV coefficient.
+
+A complier LATE requires additional assumptions. For one unconditional binary
+instrument and a binary treatment, 2SLS or Wald accepts `target="late"` only with
+`late_assumptions=True`. This asserts exogeneity, exclusion, relevance,
+monotonicity, consistency and no interference; it does not verify them. Adjusted
+or multivariate instruments and PLIV retain the generic linear IV target.
+See [Angrist, Imbens and Rubin](https://doi.org/10.1080/01621459.1996.10476902).
+
+Scalar results retain `identification`; IV results also state `assumptions`.
+Their `first_stage_partial_r2`, `first_stage_f` and degrees of freedom describe
+first-stage strength. PLIV computes them on its cross-fitted residuals, marked by
+`first_stage_residualized=1`. The classical F statistic is descriptive, assumes a
+homoskedastic linear first stage for its usual interpretation, and does not test
+exclusion or exogeneity. Values below 10 warn; larger values do not establish
+instrument validity. Ordinary normal IV intervals can be unreliable with weak
+instruments; weak-IV robust intervals are not implemented here.
+
+## Next steps
+
+<div class="cards" markdown="1">
+
+- [Refute an estimate](refute-an-estimate.md): stress-test this estimate with placebo and subset checks.
+- [Average an effect over the graphs](evaluate-a-graph.md#average-an-effect-over-the-graphs): estimate across a posterior over DAGs.
+- [Estimate heterogeneous effects](heterogeneous-effects.md): find who gains more or less from the treatment.
+- [Python reference](reference-inference.md): every option of `estimate_effect`.
+
+</div>

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/evaluate-a-graph.md

@@ -440,10 +440,10 @@ print(round(result.zero_effect_mass, 3), result.unidentified_mass, result.trunca
 0.811
 0.404
        adjustment_set   mass  n_dags  estimate  std_error
-0                   c  0.757       3     1.969      0.066
+0                   c  0.757       3     1.970      0.066
 1             (empty)  0.156       6     3.563      0.072
 2  (no directed path)  0.087      16     0.000      0.000
-2.046 0.857
+2.047 0.857
 0.087 0.0 0.0
 ```
 
@@ -525,3 +525,10 @@ Nothing touches numpy's global random state, and the same `seed` gives the same
 - [Python reference](reference-discovery.md): `graph_posterior`, `evaluate_graph`, `GraphSamples`.
 
 </div>
+
+`GraphSamples.top(k)` lists the heaviest DAGs first. Weight ties within 1e-12
+relative to the group's maximum are ordered by log target; log-target ties
+within absolute 1e-9 are ordered by sorted named directed edges. Groups are
+anchored at their maximum, not chained through approximate pairwise equality.
+This removes floating-point noise from equivalent-graph ordering without
+rounding returned masses or changing the posterior.

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/heterogeneous-effects.md

@@ -101,6 +101,9 @@ Demirer, Duflo and Fernández-Val, 2025; Yadlowsky and others, 2024).
 `method=` picks the learner. The default `"dr_learner"` is doubly robust. Other
 names: `"r_learner"`, `"x_learner"`, `"t_learner"`, `"s_learner"`, `"dml"` and
 `"causal_forest"`. `learner=` fills the nuisance models, as in `estimate_effect`.
+The same S/T names work with `estimate_effect(strategy=...)`: `t_learner` fits
+separate outcome models for each arm, and `s_learner` fits one pooled model.
+Passing a contradictory `per_arm=` flag raises an error in either facade.
 
 - The uncertainty depends on the method. The DR-learner with its default linear
   final model has analytic standard errors. `"causal_forest"` (Athey, Tibshirani
@@ -126,6 +129,17 @@ names: `"r_learner"`, `"x_learner"`, `"t_learner"`, `"s_learner"`, `"dml"` and
 - `explain()` describes the units the model was fit on. To score new rows, fit an
   estimator such as `DRLearner` with `fit(identification, data)`, then call its
   `cate(new_rows)`. That result has no scores, so its `explain()` raises.
+- New rows use the covariate types and category vocabulary saved during `fit`.
+  Column order and categorical metadata order can change, and a batch can omit
+  known category levels. Unknown values, missing required columns, changed
+  covariate types and missing covariate values raise an error. Treatment and
+  outcome columns are unnecessary when scoring new rows.
+- If a fold fails while building the out-of-fold effect proxy, `explain().blp()`
+  still projects the cross-fit scores on covariates. GATES, CLAN, RATE and calibration
+  refuse to return intervals or p-values and report the ranking failure. They
+  never substitute the fitted in-sample effects. `select_cate` also refuses a
+  candidate without an out-of-fold proxy. DML supplies constant effects with no
+  out-of-fold CATE ranking, so it also refuses these summaries while retaining BLP.
 - `effects.ate()` returns the average effect. With the DR-learner it is the mean of
   the doubly robust scores, whose standard error is valid (the per-unit standard
   errors share one fitted model, so they are never combined as if independent); for

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/install.md

@@ -72,7 +72,7 @@ for module, use in optional.items():
 ```
 
 ```output from="install_check.py" lines="1"
-ergodic 0.3.0 writes ergodic.graph/1
+ergodic 0.3.2 writes ergodic.graph/1
 ```
 
 - **Step 1.** The version, and `ergodic.graph/1`: the format `MixedGraph.to_dict()`

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/refute-an-estimate.md

@@ -54,18 +54,18 @@ print(check)
 ```
 
 ```output from="refute_effect.py"
-EffectEstimate(aipw, analytic: ate=-222.3, se=25.8, 95% CI [-273, -172], n=4642)
-Refutation(placebo_treatment: estimate=-222.3, under perturbation=4.981, p=0.0099, passed, n=100)
-  spread of the perturbed estimates: 21.7 g
-Refutation(random_common_cause: estimate=-222.3, under perturbation=-222.1, passed, n=100)
-  spread of the perturbed estimates: 0.8 g
-Refutation(data_subset: estimate=-222.3, under perturbation=-219, passed, n=100)
-  spread of the perturbed estimates: 13.8 g
-Refutation(placebo_treatment: estimate=-275.3, under perturbation=4.529, p=0.0099, passed, n=100)
+EffectEstimate(aipw, analytic: ate=-219.5, se=26.3, 95% CI [-271, -168], n=4642)
+Refutation(placebo_treatment: estimate=-219.5, under perturbation=4.747, p=0.0099, passed, n=100)
+  spread of the perturbed estimates: 21.5 g
+Refutation(random_common_cause: estimate=-219.5, under perturbation=-219.3, passed, n=100)
+  spread of the perturbed estimates: 1.0 g
+Refutation(data_subset: estimate=-219.5, under perturbation=-218.7, passed, n=100)
+  spread of the perturbed estimates: 14.2 g
+Refutation(placebo_treatment: estimate=-275.3, under perturbation=4.526, p=0.0099, passed, n=100)
 ```
 
 - **Placebo treatment.** With the smoking column shuffled, the effect drops from
-  −222 g to a few grams. In none of the 100 shuffles was the placebo effect as large
+  −220 g to a few grams. In none of the 100 shuffles was the placebo effect as large
   in size as the real one, so `p` is the smallest value 100 runs can give: 1/101.
 - **Random common cause.** Adding an independent random confounder to the graph
   leaves the estimate where it was, within a gram.

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/start.md

@@ -50,7 +50,7 @@ Alarm --> MaryCalls
 Alarm <-- Burglary
 Alarm <-- Earthquake
 Identification(adjustment: P(JohnCalls | do(Burglary)) = sum_z P(JohnCalls | Burglary, z) P(z), with z = {Earthquake})
-EffectEstimate(aipw, analytic: ate=0.7982, se=0.0333, 95% CI [0.733, 0.863], n=10000)
+EffectEstimate(aipw, analytic: ate=0.7997, se=0.0337, 95% CI [0.734, 0.866], n=10000)
 ```
 
 - **Step 1.** Five yes/no columns. Burglaries are rare: about 1 row in 100.

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/test-a-graph.md

@@ -210,3 +210,23 @@ own variables, and they hold in the margin over those variables.
 - [Python reference](reference-discovery.md): `test_graph` and `GraphTest` in full.
 
 </div>
+
+!!! caution "GCM learner calibration"
+    The default GCM learner remains KNN; it is not a generally calibrated CI test.
+    A paired 200-seed direct-CI diagnostic at alpha 0.05 found null rejection rates
+    of 9.5%/7.5% (linear), 12%/10% (quadratic), and 10%/9% (sine), at n=200/1000.
+    OLS gave 7.5%/5%, 100%/100%, and 99%/100%, respectively: replacing KNN with
+    OLS would fail badly for these nonlinear conditional means. Neither qualified
+    across all cells of the registered 2–8% investigation band, so the default
+    is unchanged. All cells used 200 trials with zero refusals; 95% Wilson intervals
+    for the KNN rates span roughly 4.6–17.2%. These are direct-CI results, distinct
+    from the earlier ~30% rejection of true graphs by Fisher's combined test.
+    Learner choice must match the conditional mean; these diagnostics do not
+    establish calibration for arbitrary data or guarantee detection of dependence.
+    The reproducible protocol is in `scripts/audits/qualify_gcm.py`.
+
+Linear and GCM compute two-sided normal tails with `erfc`, so strong statistics
+such as z=9 retain their nonzero p-values (about 2.26e-19). Tails below binary64's
+representable range still become zero, for example z=40. Graph-test aggregation
+retains its existing safeguards for zero tails; no finite float can represent
+those smaller probabilities accurately.

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/pages/time-series-discovery.md

@@ -54,14 +54,14 @@ print(f"{pruned} links pruned; {tests[0]} tests instead of {tests[1]}")
 
 ```output from="time_series.py"
 TimeSeriesDiscoveryResult(pcmci/linear: dag on 9 window nodes, max_lag=2, 5 lagged links, 0 contemporaneous, alpha=0.05, n=496)
-ads[t-1] -> ads[t]  p=0
-ads[t-1] -> visits[t]  p=0
-sales[t-1] -> sales[t]  p=0
-visits[t-2] -> sales[t]  p=4.4e-15
-visits[t-1] -> visits[t]  p=0
+ads[t-1] -> ads[t]  p=1.9e-38
+ads[t-1] -> visits[t]  p=6.1e-35
+sales[t-1] -> sales[t]  p=6.1e-34
+visits[t-2] -> sales[t]  p=4.5e-15
+visits[t-1] -> visits[t]  p=1.5e-26
 granger: [('ads', 'visits'), ('visits', 'sales')]
 True
-9 links pruned; 37 tests instead of 49
+9 links pruned; 37 tests instead of 47
 ```
 
 - **Step 2.** The result holds a window graph over nodes such as `ads[t-1]`. With

{ergodic-0.3.0 → ergodic-0.3.2}/docsite/site.toml

@@ -31,7 +31,7 @@ commands = [
 
 [versions]
 # Published versions older than this build that stay in the picker (v<version>/), oldest first.
-previous = ["0.2.0", "0.2.1"]
+previous = ["0.2.0", "0.2.1", "0.3.0", "0.3.1"]
 
 [[products]]
 name = "ergodic"