docs(v1.5.0): sync README_CN, docs/index, 3 family-guide footers to 1.5.0

brycewang-stanford · claude · brycewang-stanford · commit 7502e6a406f7 · 2026-04-21T16:39:25.000-07:00
- README_CN.md: add v1.5.0 "NEW" block; demote v1.4.2 to "Previously in" - docs/index.md: Current release banner + release-highlights table top row bumped to v1.5.0; BibTeX version bump; drop stale migration link - docs/guides/{proximal,qte,causal_rl}_family.md: version footer "≥ 1.4.2" → "≥ 1.5.0" Companion to d1719bb which shipped the code, README, CHANGELOG, and the three new interference / conformal / MR guides but missed these downstream doc-sync files. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
diff --git a/README_CN.md b/README_CN.md
@@ -15,16 +15,27 @@ StatsPAI 是一个**面向 AI Agent** 的 Python 因果推断与应用计量经
 
 它将 R 的 [Causal Inference Task View](https://cran.r-project.org/web/views/CausalInference.html)（fixest、did、rdrobust、gsynth、DoubleML、MatchIt、CausalImpact、sfaR、lme4、oaxaca、ddecompose……）和 Stata 的核心计量命令（`frontier`、`xtfrontier`、`mixed`、`meglm`、`mixlogit`、`ivqreg`……），统一到一个一致的 Python API 中。
 
-**🎉 v1.4.2 新版本 — 正确性补丁 + Proximal / QTE / 因果 RL 家族指南**
+**🎉 v1.5.0 新版本 — Interference / Conformal / Mendelian 三家族合并升级**
 
-StatsPAI 1.4.2 是 patch 版本。无破坏性改动、无新增公开签名——只修了两个"悄悄算错"的 bug，补上三篇家族指南，关闭 v3 参考文档和公开文档之间的最后几处缺口。
+StatsPAI 1.5.0 是 minor 版本，一次性完成 interference、conformal 因果推断、Mendelian 随机化三个家族的三项联动升级：完整家族文档指南、与 `sp.synth` / `sp.decompose` / `sp.dml` 同构的统一 dispatcher，以及一次针对性的正确性审计修掉两处"悄悄算错"。
+
+- **三篇新家族指南**：`docs/guides/interference_family.md`（`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` 完整走查，含决策树 + 5 项 interference 分析必报诊断）；`docs/guides/conformal_family.md`（10 个 conformal 估计器按"边际覆盖保证的含义"重新组织，明确 marginal 与 conditional 的区别）；`docs/guides/mendelian_family.md`（17 个 MR 函数按 IV1 / IV2 / IV3 假设层级重新组织 + 每次 MR 分析必报的 4 项 sanity check + BMI → T2D 完整示例）。
+- **三个新统一 dispatcher**：`sp.mr(method=...)` 覆盖 33 个别名（IVW / Egger / median / mode / MVMR / mediation / BMA / PRESSO / radial / Steiger / F 统计量 / LOO / 多效性 / 异质性）；`sp.conformal(kind=...)` 覆盖 29 个别名（CATE / counterfactual / ITE / density / 多阶段 / debiased-ML / fair / continuous / interference）；`sp.interference(design=...)` 覆盖 29 个别名（partial / network-exposure / peer-effects / network-HTE / inward-outward / 4 种 cluster-RCT 变体）。kwargs 原样透传；每个 dispatcher 的输出与直调结果逐字节一致（30 个新测试守卫）。
+- **⚠️ 正确性修复 — `sp.mr_egger` slope 推断错用 Normal 而非 t(n−2)**。配套的 `sp.mr_pleiotropy_egger` 用的是 `t(n−2)`，但 `mr_egger` 的 slope p 值和 CI 临界值都用 `stats.norm`，两处口径不一致。小样本下反而过松——`n_snps = 5`、`t ≈ 1.5` 时 Normal 给 `p = 0.134`，正确的 `t(3)` 给 `p = 0.231`。修复后两处都用 `t(n − 2)`。`n_snps ≥ ~100` 时不可见。回归守卫：`tests/test_correctness_v150.py::TestMREggerUsesTDistribution`。
+- **⚠️ 正确性修复 — `sp.mr_presso` MC p 值可能等于 0**。全局检验和逐 SNP outlier p 值都用原始 `mean(null ≥ obs)`，当实测统计量大于所有模拟 null 时会塌缩为 `0.0`。MC 估计 p 值的真实下界是 `1 / (B + 1)`，不可能为零。修复改用标准 `(k + 1) / (B + 1)`（与 R 的 MR-PRESSO 一致）。下游影响：`log(p)` 和灵敏度变换不会再静默返回 `-inf`。回归守卫：`tests/test_correctness_v150.py::TestMRPressoMCPvalueConvention`。
+- **⚠️ 破坏性变更 — `sp.mr` 从模块别名变为函数**。v1.5.0 之前 `sp.mr` 是 `statspai.mendelian` 子模块的别名，所以 `sp.mr.mr_ivw(...)` 能走通。v1.5.0 把 `sp.mr` 重新指给新 dispatcher。迁移：用顶层 `sp.mr_ivw(...)`（历来就有）或新的 `sp.mr("ivw", ...)`。模块访问保留在 `sp.mendelian` 下。见 [MIGRATION.md](MIGRATION.md#v14x--v150)。
+- **Registry 覆盖修补**：5 个此前"sp 命名空间可见但 registry 没挂"的家族函数现已出现在 `sp.list_functions()` 并可通过 `sp.describe_function()` 拿到 agent 可读 schema：`network_exposure`、`peer_effects`、`weighted_conformal_prediction`、`conformal_counterfactual`、`conformal_ite_interval`。
+
+除了 `sp.mr` 模块→函数这一点，其他所有公开签名与 v1.4.2 逐字节一致。
+
+**v1.4.2 — 正确性补丁 + Proximal / QTE / 因果 RL 家族指南**
+
+StatsPAI 1.4.2 是 patch 版本，带两个"悄悄算错"的修复 + 三篇家族指南：
 
 - **⚠️ 正确性修复 — `sp.dml_model_averaging` 的 √n SE 尺度 bug**：候选间方差聚合器把"样本均值影响函数的外积"当成了 `Var(θ̂_avg)` 本身，漏掉了最后的 `/ n`。报告的 SE 因此比真值大 `√n` 倍；在典型 n=400 DGP 上，95% CI 宽度 4.20（理论 ≈ 0.21），实证覆盖率 100%（名义 95%）。修复后 CI 宽度 0.21，覆盖率回到名义水平。回归守卫加在 `tests/test_dml_model_averaging.py::test_se_on_correct_scale`。
 - **⚠️ 正确性修复 — `sp.gardner_did` event-study 参照组污染**：Stage-2 dummy 回归把"从未处理单元"和"处在 event-study 视野之外的已处理单元"合并成同一个基线，把每个 event-time 系数都往这个混合基线的均值拖。τ=2 且严格平行趋势的合成面板上，pre-trend ≈ -0.30（应为 0），post ≈ +1.72（应为 2.0）。Event-study 模式下改用 Borusyak-Jaravel-Spiess 风格的 (cohort × relative-time) 分箱直接聚合 imputed gap。修复后 pre-trend ≈ +0.01，post ≈ +2.02。非 event-study 的单 ATT 路径本来就对，保持不变。
-- **新增家族指南**：`docs/guides/proximal_family.md`（Proximal 因果推断家族完整走查，覆盖 `sp.proximal`、`sp.fortified_pci`、`sp.bidirectional_pci`、`sp.pci_mtp`、`sp.double_negative_control`、`sp.proximal_surrogate_index`、`sp.select_pci_proxies`，含决策树与 PCI 分析必报的 4 项诊断）；`docs/guides/qte_family.md`（均值 → 分位数 → 整分布三级粒度，配 cross-section / DiD / IV / 面板四条决策路径，覆盖 `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`（何时用 causal RL 而非经典因果推断，覆盖 `sp.causal_bandit`、`sp.causal_dqn`、`sp.offline_safe_policy`、`sp.counterfactual_policy_optimization`、`sp.structural_mdp`、`sp.causal_rl_benchmark`，附 4 项 causal-RL 专属 sanity check）。
-- **v1.4.1 cherry-pick 的正式发版**：`tests/test_bridge_full.py`（`sp.bridge(kind=...)` 桥梁定理的 10 个端到端测试）与 `docs/guides/bridging_theorems.md`。
-
-所有公开签名与 v1.4.1 逐字节一致。升级后唯一可见的变化：`dml_model_averaging` 的 CI 会变窄、`gardner_did` 的 event-study 系数会更干净。
+- **家族指南**：`docs/guides/proximal_family.md`（Proximal 家族）、`docs/guides/qte_family.md`（均值→分位数→分布）、`docs/guides/causal_rl_family.md`（因果 RL）。
+- **v1.4.1 cherry-pick 的正式发版**：`tests/test_bridge_full.py` + `docs/guides/bridging_theorems.md`。
 
 **v1.4.1 — v3 前沿 Sprint 3：AKM 冲击聚类 SE、Claude 扩展思考、对齐与集成测试套件、2 篇新指南**
 
@@ -386,7 +397,7 @@ pytest
   author={Wang, Biaoyue},
   year={2026},
   url={https://github.com/brycewang-stanford/statspai},
-  version={1.4.2}
+  version={1.5.0}
 }
 ```
 
diff --git a/docs/guides/causal_rl_family.md b/docs/guides/causal_rl_family.md
@@ -216,5 +216,5 @@ Benchmarking / compare algorithms:
 
 ---
 
-*Current for StatsPAI ≥ 1.4.2.  Full list via `sp.list_functions()` —
+*Current for StatsPAI ≥ 1.5.0.  Full list via `sp.list_functions()` —
 all causal-RL functions are tagged `rl` and `causal`.*
diff --git a/docs/guides/proximal_family.md b/docs/guides/proximal_family.md
@@ -255,5 +255,5 @@ Have a pile of candidate proxies, not sure which to use
 
 ---
 
-*This guide is current for StatsPAI ≥ 1.4.2.  All functions are stable
+*This guide is current for StatsPAI ≥ 1.5.0.  All functions are stable
 and registered in `sp.list_functions()`.*
diff --git a/docs/guides/qte_family.md b/docs/guides/qte_family.md
@@ -236,5 +236,5 @@ Panel with many controls:
 
 ---
 
-*Current for StatsPAI ≥ 1.4.2.  All functions are registered; inspect
+*Current for StatsPAI ≥ 1.5.0.  All functions are registered; inspect
 with `sp.describe_function("beyond_average_late")`, etc.*
diff --git a/docs/index.md b/docs/index.md
@@ -9,17 +9,17 @@ mixed-effects, modern ML causal inference, the full three-school
 modules (bridging theorems, fairness, surrogates, PCMCI, TMLE survival,
 etc.), and publication-ready output in Word / Excel / LaTeX / HTML.
 
-> **Current release: v1.4.1 (2026-04-21)** — v3-frontier Sprint 3.
-> Additive follow-up to v1.4.0: AKM shock-clustered SE for
-> `sp.shift_share_political_panel(cluster='shock')` (Park-Xu 2026 §4.2,
-> typically 3× tighter than unit-clustered SEs); Claude 4.5 / Opus 4.7
-> **extended-thinking** support via
-> `sp.causal_llm.anthropic_client(thinking_budget=N)`; a 10-check
-> assimilation parity suite plus an 11-test MAS integration suite with
-> 3 Claude thinking block-splitter tests; two new MkDocs guides
-> (`shift_share_political_panel`, `causal_mas`). All v1.4.0 APIs
-> stable; new surface is additive kwargs only. See the
-> [changelog](changelog.md) for detail.
+> **Current release: v1.5.0 (2026-04-21)** — Interference / Conformal /
+> Mendelian family consolidation. Three family guides
+> (`interference_family`, `conformal_family`, `mendelian_family`)
+> covering all 36 functions across the three families; three unified
+> dispatchers (`sp.mr(method=...)` / `sp.conformal(kind=...)` /
+> `sp.interference(design=...)`) mirroring the
+> `sp.synth` / `sp.decompose` / `sp.dml` pattern; two silent-wrong-numbers
+> fixes (`mr_egger` slope t(n−2) parity with `mr_pleiotropy_egger`;
+> `mr_presso` MC p-value floor at `1/(B+1)`). Breaking: `sp.mr` is now a
+> function, not a module alias — module access moved to `sp.mendelian`.
+> See the [changelog](changelog.md) for detail.
 
 ```python
 import statspai as sp
@@ -32,10 +32,12 @@ rpt = sp.cs_report(data, y='y', g='g', t='t', i='id',
 
 ## What's inside
 
-### Release highlights (v0.9.17 → v1.4.1)
+### Release highlights (v0.9.17 → v1.5.0)
 
 | Release | Focus | Headline |
 | --- | --- | --- |
+| **v1.5.0** | Interference / Conformal / Mendelian family consolidation | Three family guides (`interference_family`, `conformal_family`, `mendelian_family`) covering all 36 functions; three unified dispatchers `sp.mr(method=...)` / `sp.conformal(kind=...)` / `sp.interference(design=...)` with 91 aliases in total; two silent-wrong-numbers fixes — `mr_egger` slope t(n−2) parity with `mr_pleiotropy_egger` (anti-conservative CIs at small `n_snps` before fix) and `mr_presso` MC p-value floor at `1/(B+1)` (no more `p = 0`). Breaking: `sp.mr` is now a dispatcher function, not a module alias. Registry coverage fixes for 5 previously-unregistered family functions. |
+| **v1.4.2** | Correctness patches + Proximal / QTE / Causal-RL family guides | `sp.dml_model_averaging` √n SE scaling bug (CIs were √n × too wide) + `sp.gardner_did` event-study reference-category contamination (pre-trend bias ~0.3). Three family guides. No breaking changes. |
 | **v1.4.1** | v3-frontier Sprint 3 (AKM SE + Claude thinking + test suites + docs) | `sp.shift_share_political_panel(cluster='shock')` — panel-extended Adão-Kolesár-Morales (2019) shock-cluster variance (Park-Xu 2026 §4.2); `sp.causal_llm.anthropic_client(thinking_budget=N)` — Claude 4.5 / Opus 4.7 extended-thinking API; 10-check assimilation parity suite + 11-test MAS integration suite with 3 Claude thinking block-splitter tests; two new MkDocs guides (`shift_share_political_panel`, `causal_mas`). Strictly additive over v1.4.0. |
 | **v1.4.0** | v3-frontier Sprint 2 (extensions + LLM SDK + docs) | `shift_share_political_panel` (Park-Xu 2026 multi-period); real LLM adapters `openai_client` / `anthropic_client` / `echo_client` for Causal MAS; `particle_filter` backend for `assimilative_causal` (non-Gaussian / nonlinear); three new MkDocs guides (`synth_experimental`, `harvest_did`, `assimilative_ci`); 20 unused-import cleanups; CausalForest parity-test de-flake. |
 | **v1.3.0** | v3-frontier sprint (Sprint 1 of 知识地图 v3) | 11 frontier methods: Abadie-Zhao inverse synthetic experimental design, CJM RBC bootstrap for `rdrobust`, Kwak-Pleasants evidence-without-injustice fairness test, JAMA/BMJ TARGET manuscript renderer, Borusyak harvest-DiD, Zorzetto ordinal / factor-exposure BCF, multi-agent causal discovery (`causal_mas`), Park-Xu political shift-share IV, state-space `causal_kalman`. 35 new tests, 869 registered functions, zero regressions. `tabulate` promoted to core dep. |
@@ -166,7 +168,7 @@ method that returns the correct BibTeX entry) and this package:
   title   = {StatsPAI: A Unified, Agent-Native Python Toolkit for
              Causal Inference and Applied Econometrics},
   year    = {2026},
-  version = {1.4.1},
+  version = {1.5.0},
   url     = {https://github.com/brycewang-stanford/StatsPAI}
 }
 ```
