release: v1.5.0 — MR/conformal/interference family consolidation

- Unified family dispatchers: sp.mr(method=...), sp.conformal(kind=...),
  sp.interference(design=...) mirroring sp.synth / sp.decompose / sp.dml
- ⚠️ Breaking: sp.mr is now a dispatcher function, not a module alias
  (use sp.mendelian for module-level access; sp.mr_* top-level helpers
  unchanged)
- ⚠️ Correctness: mr_egger slope inference now uses t(n−2) instead of
  Normal (anti-conservative at small n_snps); mr_presso MC p-values now
  use (k+1)/(B+1) convention (no more exact-zero p-values)
- Fixed: dead var= line in network_exposure._ht_estimate (SE unchanged)
- Registry coverage: network_exposure, peer_effects,
  weighted_conformal_prediction, conformal_counterfactual,
  conformal_ite_interval now surface in sp.list_functions()
- Docs: three new family guides (interference / conformal / MR)
- Tests: +44 tests (30 dispatcher parity + 14 correctness guards)

Author: brycewang-stanford

CHANGELOG.md

@@ -2,6 +2,146 @@
 
 All notable changes to StatsPAI will be documented in this file.
 
+## [1.5.0] — 2026-04-21 — Interference / Conformal / Mendelian family consolidation
+
+Minor release.  Three concurrent improvements to the interference,
+conformal causal inference, and Mendelian Randomization families:
+full-family documentation guides, unified dispatchers matching the
+`sp.synth` / `sp.decompose` / `sp.dml` pattern, and a targeted
+correctness audit that surfaced and fixed two silent-wrong-numbers
+issues.
+
+### Added — three new family guides (interference / conformal / MR)
+
+- `docs/guides/interference_family.md` — complete walkthrough of
+  `sp.spillover`, `sp.network_exposure`, `sp.peer_effects`,
+  `sp.network_hte`, `sp.inward_outward_spillover`,
+  `sp.cluster_matched_pair`, `sp.cluster_cross_interference`,
+  `sp.cluster_staggered_rollout`, `sp.dnc_gnn_did`.  Decision tree
+  covering partial / network / cluster-RCT designs with the 5
+  diagnostics every interference analysis should report (exposure
+  balance, identification check for peer_effects, overlap for
+  network_hte, parallel trends for staggered-cluster, sensitivity to
+  exposure function).
+- `docs/guides/conformal_family.md` — complete walkthrough of
+  `sp.conformal_cate`, `sp.weighted_conformal_prediction`,
+  `sp.conformal_counterfactual`, `sp.conformal_ite_interval`,
+  `sp.conformal_density_ite`, `sp.conformal_ite_multidp`,
+  `sp.conformal_debiased_ml`, `sp.conformal_fair_ite`,
+  `sp.conformal_continuous`, `sp.conformal_interference`.  Clarifies
+  the distinction between marginal and conditional coverage, with
+  per-tool "when to use it" + how-to-read-disagreement guidance.
+- `docs/guides/mendelian_family.md` — complete walkthrough of all 17
+  MR functions (4 point estimators + 6 diagnostics + 3 multi-exposure
+  extensions + instrument-strength F + 2 plots), organised around the
+  IV1 / IV2 / IV3 assumption hierarchy.  Ships the 4 sanity checks every
+  MR analysis should report and a worked BMI → T2D example.
+
+Each guide is linked from `mkdocs.yml` under Guides and surfaces via
+`sp.search_functions()`.
+
+### Added — unified family dispatchers
+
+Three new top-level dispatchers mirroring the style of `sp.synth` /
+`sp.decompose` / `sp.dml`:
+
+- **`sp.mr(method=..., ...)`** — single entry point for the 17-function
+  Mendelian Randomization family.  Supports
+  `method ∈ {"ivw", "egger", "median", "penalized_median", "mode",
+  "simple_mode", "all", "mvmr", "mediation", "bma", "presso", "radial",
+  "leave_one_out", "steiger", "heterogeneity", "pleiotropy_egger",
+  "f_statistic", ...}` with aliases.  kwargs pass through to the target
+  function.  `sp.mr_available_methods()` lists all aliases.
+
+- **`sp.conformal(kind=..., ...)`** — single entry point for the
+  10-function conformal causal inference family.  Supports
+  `kind ∈ {"cate", "counterfactual", "ite", "weighted", "density",
+  "multidp", "debiased", "fair", "continuous", "interference", ...}`.
+  `sp.conformal_available_kinds()` lists all aliases.
+
+- **`sp.interference(design=..., ...)`** — single entry point for the
+  9-function interference / spillover family.  Supports
+  `design ∈ {"partial", "network_exposure", "peer_effects",
+  "network_hte", "inward_outward", "cluster_matched_pair",
+  "cluster_cross", "cluster_staggered", "dnc_gnn", ...}`.
+  `sp.interference_available_designs()` lists all aliases.
+
+All three dispatchers are registered with hand-written schemas so
+`sp.describe_function("mr")` / `"conformal"` / `"interference"` return
+agent-readable descriptions.  30 new tests in
+`tests/test_dispatchers_v150.py` guarantee the dispatcher path and the
+direct-call path produce byte-for-byte identical results.
+
+### ⚠️ Breaking — `sp.mr` is now a function, not a module alias
+
+Prior to v1.5.0 `sp.mr` was a reference to the `statspai.mendelian`
+submodule (`from . import mendelian as mr`), so `sp.mr.mr_ivw(...)`
+worked.  v1.5.0 replaces this with the new **dispatcher function**
+`sp.mr(method=..., ...)`.
+
+**Migration**: code that previously wrote `sp.mr.mr_ivw(bx, by, sx, sy)`
+should use the top-level `sp.mr_ivw(bx, by, sx, sy)` (already exported
+in every prior version) or the new `sp.mr("ivw", beta_exposure=bx, ...)`
+dispatcher.  The module is still accessible as `sp.mendelian` for users
+who were doing submodule-level introspection.
+
+Updated references: the only in-repo consumer of the old
+`sp.mr.mr_ivw` form was `tests/reference_parity/test_mr_parity.py`,
+which has been migrated to top-level calls.  All external user code
+that already uses `sp.mr_ivw` / `sp.mendelian_randomization` / etc
+continues to work unchanged.
+
+### Fixed — silent wrong numbers (correctness audit)
+
+- **`sp.mr_egger` — slope inference used Normal, not t(n−2).**  The
+  companion `sp.mr_pleiotropy_egger` correctly used `t(n−2)` for the
+  Egger intercept p-value, but `mr_egger` itself used `stats.norm.cdf`
+  for both the slope p-value and the slope CI's critical value.  This
+  was anti-conservative at small `n_snps`: e.g. for `n_snps = 5` and a
+  t-stat of 1.5, the Normal-based two-sided p is 0.134 whereas the
+  correct t(3)-based p is 0.231.  `mendelian_randomization(..., methods=["egger"])`
+  inherited the bug through its internal call.  The fix switches both the
+  p-value and the CI critical value to `t(n−2)`.  Regression guard in
+  `tests/test_correctness_v150.py::TestMREggerUsesTDistribution`.
+  For `n_snps ≥ 100` the change is numerically invisible (< 1e-3 in p).
+
+- **`sp.mr_presso` — MC p-value could equal exactly 0.**  Both the
+  global test p-value and the per-SNP outlier p-values used the raw
+  `mean(null >= obs)` form, which collapses to `0.0` when the observed
+  statistic exceeds every simulated null.  An MC-estimated p-value
+  cannot be zero — its true lower bound is `1 / (B + 1)`.  The fix
+  switches to the standard `(k + 1) / (B + 1)` convention (matching
+  R's `MR-PRESSO` package).  Downstream effect: reported p-values are
+  now always strictly positive and in `[1/(B+1), 1]`, which prevents
+  log-transforms and sensitivity analyses from silently producing
+  `-inf`.  Regression guard in
+  `tests/test_correctness_v150.py::TestMRPressoMCPvalueConvention`.
+
+### Fixed — dead code
+
+- **`sp.network_exposure._ht_estimate`** contained a dimensionally
+  inconsistent `var = ...` expression that was immediately overwritten
+  by the conservative Aronow-Samii Theorem 1 bound `var_as = ...`.  The
+  dead line is removed; the reported SE is unchanged.
+
+### Fixed — registry coverage
+
+Five previously-exposed-but-unregistered family functions now surface
+in `sp.list_functions()` and have agent-readable schemas via
+`sp.describe_function()`:
+
+- `sp.network_exposure` (Aronow-Samii HT)
+- `sp.peer_effects` (Bramoullé-Djebbari-Fortin 2SLS)
+- `sp.weighted_conformal_prediction` (TBCR 2019 primitive)
+- `sp.conformal_counterfactual` (Lei-Candès Theorem 1)
+- `sp.conformal_ite_interval` (Lei-Candès Eq. 3.4 nested bound)
+
+### No other API changes
+
+Every other public signature is byte-for-byte identical to v1.4.2.
+Existing user code keeps working; upgrades reveal slightly wider Egger
+CIs at small `n_snps` and strictly positive `mr_presso` p-values.
+
 ## [1.4.2] — 2026-04-21 — correctness patches + family guides
 
 Patch release.  No breaking changes; two silent-wrong-numbers bug

MIGRATION.md

@@ -1,4 +1,58 @@
-# Migrating from PyStataR to StatsPAI
+# Migrating between StatsPAI versions + from PyStataR
+
+Internal version-to-version migrations are at the top; the long-form
+`PyStataR → StatsPAI` migration follows below.
+
+---
+
+## v1.4.x → v1.5.0
+
+Minor release.  Only one change requires any migration:
+
+### `sp.mr` is now a dispatcher function, not a module alias
+
+Before v1.5.0, `sp.mr` was a reference to the `statspai.mendelian`
+submodule, and `sp.mr.mr_ivw(...)` worked as attribute access on the
+module.
+
+In v1.5.0, `sp.mr` is the new **unified dispatcher** for the MR family,
+matching the pattern of `sp.synth` / `sp.decompose` / `sp.dml`:
+
+```python
+sp.mr("ivw",   beta_exposure=bx, beta_outcome=by,
+       se_exposure=sx, se_outcome=sy)
+sp.mr("egger", beta_exposure=bx, beta_outcome=by,
+       se_exposure=sx, se_outcome=sy)
+sp.mr("mvmr",  snp_associations=snp_df,
+       outcome="beta_y", outcome_se="se_y",
+       exposures=["beta_bmi", "beta_ldl"])
+```
+
+| Old (<= v1.4.2) | New (>= v1.5.0) |
+| --- | --- |
+| `sp.mr.mr_ivw(...)` | `sp.mr_ivw(...)` (already available since v0.9) or `sp.mr("ivw", ...)` |
+| `sp.mr.mr_egger(...)` | `sp.mr_egger(...)` or `sp.mr("egger", ...)` |
+| `sp.mr.mr_presso(...)` | `sp.mr_presso(...)` or `sp.mr("presso", ...)` |
+| `sp.mr` (as module alias) | `sp.mendelian` (module access preserved under this name) |
+
+**Rule of thumb:** if your code uses `sp.mr_*` (underscore form) it
+already works unchanged in v1.5.0.  Only the uncommon
+`sp.mr.<attribute>` pattern needs rewriting.
+
+### Output numerical differences you may notice after upgrading
+
+- `sp.mr_egger` / `sp.mendelian_randomization(..., methods=["egger"])`
+  slope p-values and CIs now use `t(n − 2)` rather than `Normal`, matching
+  `sp.mr_pleiotropy_egger` and R's `MendelianRandomization` package.
+  Effect is invisible for `n_snps ≥ ~100`.  For very small `n_snps` (say
+  5 or 6) CIs widen by ~1.6×.
+- `sp.mr_presso` p-values now use the `(k + 1) / (B + 1)` MC convention,
+  so they are strictly positive (floor `1 / (B + 1)`).  No change for
+  non-extreme cases; fixes `-inf` propagation through `log(p)` downstream.
+
+---
+
+## From PyStataR to StatsPAI
 
 `PyStataR` is deprecated. All of its functionality is now available in
 [StatsPAI](https://github.com/brycewang-stanford/StatsPAI), under a

README.md

@@ -15,17 +15,28 @@ StatsPAI is the **agent-native** Python package for causal inference and applied
 
 It brings R's [Causal Inference Task View](https://cran.r-project.org/web/views/CausalInference.html) (fixest, did, rdrobust, gsynth, DoubleML, MatchIt, CausalImpact, ...) and Stata's core econometrics commands into a single, consistent Python API.
 
-**🎉 NEW in v1.4.2 — correctness patches + Proximal / QTE / Causal-RL family guides**
+**🎉 NEW in v1.5.0 — Interference / Conformal / Mendelian family consolidation**
 
-StatsPAI 1.4.2 is a patch release.  No breaking changes, no new public signatures — just two silent-wrong-numbers fixes and three family guides closing the last gaps between the v3 reference and the published documentation.
+StatsPAI 1.5.0 is a minor release bundling three concurrent improvements to the interference, conformal causal inference, and Mendelian Randomization families: full-family documentation guides, unified dispatchers matching the `sp.synth` / `sp.decompose` / `sp.dml` pattern, and a targeted correctness audit that fixed two silent-wrong-numbers issues.
+
+- **Three new family guides** — `docs/guides/interference_family.md` (complete walkthrough of `sp.spillover`, `sp.network_exposure`, `sp.peer_effects`, `sp.network_hte`, `sp.inward_outward_spillover`, `sp.cluster_matched_pair`, `sp.cluster_cross_interference`, `sp.cluster_staggered_rollout`, `sp.dnc_gnn_did` with decision tree + 5 diagnostics every interference analysis should report), `docs/guides/conformal_family.md` (all 10 conformal estimators organised around what the marginal-coverage guarantee actually buys you), `docs/guides/mendelian_family.md` (all 17 MR functions structured around the IV1 / IV2 / IV3 assumption hierarchy + 4 sanity checks every MR analysis should report + a worked BMI → T2D example).
+- **Three new unified dispatchers** — `sp.mr(method=...)` (33 aliases covering IVW / Egger / median / mode / MVMR / mediation / BMA / PRESSO / radial / Steiger / F-stat / LOO / pleiotropy / heterogeneity), `sp.conformal(kind=...)` (29 aliases across CATE / counterfactual / ITE / density / multi-DP / debiased-ML / fair / continuous / interference), `sp.interference(design=...)` (29 aliases across partial / network-exposure / peer-effects / network-HTE / inward-outward / 4× cluster-RCT variants). Kwargs pass through unchanged; each dispatcher's output is byte-for-byte identical to the direct call (30 new tests guarantee this).
+- **⚠️ correctness fix — `sp.mr_egger` slope inference used Normal, not t(n−2).** The companion `sp.mr_pleiotropy_egger` correctly used `t(n−2)` for the Egger intercept p-value, but `mr_egger` itself used `stats.norm` for both the slope p-value and CI critical value. Anti-conservative at small `n_snps` — e.g. `n_snps = 5` and `t ≈ 1.5` gave `p = 0.134` instead of the correct `p = 0.231`. The fix switches both to `t(n − 2)`. For `n_snps ≥ ~100` the change is numerically invisible. Regression guard: `tests/test_correctness_v150.py::TestMREggerUsesTDistribution`.
+- **⚠️ correctness fix — `sp.mr_presso` MC p-value could equal 0.** Both the global test and the per-SNP outlier p-values used the raw `mean(null ≥ obs)` form, which collapses to `0.0` when the observed statistic exceeds every simulated null. An MC-estimated p-value cannot be zero — its true lower bound is `1 / (B + 1)`. Fix switches to the standard `(k + 1) / (B + 1)` convention (matching R's MR-PRESSO). Downstream effect: `log(p)` and sensitivity transforms no longer silently produce `-inf`. Regression guard: `tests/test_correctness_v150.py::TestMRPressoMCPvalueConvention`.
+- **⚠️ breaking — `sp.mr` is now a function, not a module alias.** Prior to v1.5.0 `sp.mr` was a module alias so `sp.mr.mr_ivw(...)` worked. v1.5.0 repurposes `sp.mr` as the new dispatcher. Migration: use the top-level `sp.mr_ivw(...)` (already exported in every prior version) or the new `sp.mr("ivw", ...)` dispatcher. Module access preserved under `sp.mendelian`. See [MIGRATION.md](MIGRATION.md#v14x--v150).
+- **Registry coverage fixes** — 5 previously-exposed-but-unregistered family functions now surface in `sp.list_functions()` and have agent-readable schemas via `sp.describe_function()`: `network_exposure`, `peer_effects`, `weighted_conformal_prediction`, `conformal_counterfactual`, `conformal_ite_interval`.
+
+Every public signature other than the `sp.mr` module-to-function change is byte-for-byte identical to v1.4.2.
+
+**Previously in v1.4.2 — correctness patches + Proximal / QTE / Causal-RL family guides**
+
+StatsPAI 1.4.2 was a patch release with two silent-wrong-numbers fixes and three family guides:
 
 - **⚠️ correctness fix — `sp.dml_model_averaging` √n SE scaling bug.** The cross-candidate variance aggregator treated the sample-mean influence-function outer product as `Var(θ̂_avg)` directly, missing a final `/ n`. Reported SEs were `√n` times too large; on the canonical n=400 DGP the 95% CI width was 4.20 (nominal ≈ 0.21) and empirical coverage was 100%. After the fix, CI width is 0.21 and coverage is ≈ nominal. Regression guard: `tests/test_dml_model_averaging.py::test_se_on_correct_scale`.
 - **⚠️ correctness fix — `sp.gardner_did` event-study reference-category contamination.** Stage-2 dummy regression pooled never-treated units *and* treated units outside the event-study horizon into a single baseline, dragging every event-time coefficient toward the mean of that pool. On a synthetic panel with true τ=2 and strict parallel trends, pre-trends came out ≈ -0.30 (should be 0) and post ≈ +1.72 (should be 2.0). Replaced the Stage-2 regression in event-study mode with direct Borusyak-Jaravel-Spiess-style within-(cohort × relative-time) averaging of the imputed gap. After the fix: pre-trends ≈ +0.01, post ≈ +2.02. Non-event-study single-ATT path was already correct and is unchanged.
-- **New family guides** — `docs/guides/proximal_family.md` (full Proximal Causal Inference walkthrough covering `sp.proximal`, `sp.fortified_pci`, `sp.bidirectional_pci`, `sp.pci_mtp`, `sp.double_negative_control`, `sp.proximal_surrogate_index`, `sp.select_pci_proxies` with a decision tree + 4 diagnostics every PCI analysis should report), `docs/guides/qte_family.md` (mean → quantile → distribution with cross-section / DiD / IV / panel decision paths across `sp.qte`, `sp.qdid`, `sp.cic`, `sp.distributional_te`, `sp.dist_iv`, `sp.kan_dlate`, `sp.beyond_average_late`, `sp.qte_hd_panel`), `docs/guides/causal_rl_family.md` (when to use causal RL vs classical CI, covering `sp.causal_bandit`, `sp.causal_dqn`, `sp.offline_safe_policy`, `sp.counterfactual_policy_optimization`, `sp.structural_mdp`, `sp.causal_rl_benchmark` + 4 causal-RL-specific sanity checks).
+- **Family guides** — `docs/guides/proximal_family.md` (full Proximal Causal Inference walkthrough), `docs/guides/qte_family.md` (mean → quantile → distribution), `docs/guides/causal_rl_family.md` (causal RL vs classical CI).
 - **Formally shipped from v1.4.1 cherry-picks** — `tests/test_bridge_full.py` (10 end-to-end tests for `sp.bridge(kind=...)` bridging theorems) and `docs/guides/bridging_theorems.md`.
 
-Every public signature is byte-for-byte identical to v1.4.1.  Upgrading reveals narrower CIs for `dml_model_averaging` and cleaner event-study coefficients for `gardner_did`.
-
 **Previously in v1.4.1 — v3-frontier Sprint 3: AKM shock-clustered SE, Claude extended thinking, parity + integration suites, 2 new guides**
 
 StatsPAI 1.4.1 is an additive follow-up to 1.4.0 that closes the Sprint 3 items:
@@ -992,7 +1003,7 @@ pytest
   author={Wang, Biaoyue},
   year={2026},
   url={https://github.com/brycewang-stanford/statspai},
-  version={1.4.2}
+  version={1.5.0}
 }
 ```