v0.9.17: three-school completion + clinical/MR depth + preregistration + review-fix pass

Three-school completion driven by the "Causal Inference Knowledge Map"
article (Econometrics / Epidemiology / ML), adds the entry-level
primitives, DSL, and QA layer that closed the last gaps vs. Stata / R.

New subpackages
- sp.epi           — OR / RR / RD / AF / IRR / NNT / PR, Mantel-Haenszel
                     (+ Tarone-corrected Breslow-Day), direct + indirect
                     standardization, Bradford-Hill rubric, and the
                     clinical-diagnostics toolkit (sensitivity/
                     specificity, ROC + Hanley-McNeil SE, Cohen's kappa).
- sp.longitudinal  — unified What-If Layer-4 dispatcher (IPW / MSM /
                     parametric g-formula ICE) plus a safe AST-walked
                     dynamic-treatment-regime DSL (no eval). contrast()
                     gives delta-method SE for two-regime comparisons.
- sp.question      — estimand-first causal_question() DSL with
                     identify() -> estimate() -> report() flow and an
                     auto-design picker (IV / RD / DiD / longitudinal /
                     selection-on-observables).

MR full suite (sp.mr / sp.mendelian extended)
- Cochran Q / Ruecker Q', MR-Egger intercept test (t(n-2)),
  leave-one-out, Steiger directionality, MR-PRESSO with per-SNP
  outlier + distortion tests, Radial MR, weighted/simple mode
  estimator (Hartwig ZEMPA), F-statistic instrument-strength panel,
  funnel + scatter plot helpers.

Target Trial Emulation flagship
- TargetTrialResult.to_paper(fmt=markdown/latex/text) renders
  STROBE-compatible Methods + Results blocks tracking the JAMA 2022
  7-component TTE spec.
- fmt='target' adds the JAMA/BMJ Sep-2025 TARGET Statement 21-item
  checklist with AUTO-filled fields from the protocol + result.

DAG UX
- DAG.recommend_estimator() with priority backdoor -> IV -> frontdoor
  -> not-identifiable, plain-English identification story, and a
  mediator detector.

Unified sensitivity dashboard
- result.sensitivity() method on CausalResult + EconometricResults;
  single call runs E-value + Oster delta + Rosenbaum Gamma + Sensemakr
  + a CI-based breakdown-frontier estimate.

Pre-registration
- sp.preregister() / sp.load_preregister() + CausalQuestion.save() /
  .load() / .to_yaml() produce OSF/AEA-style PAP files with a
  timestamp + statspai-version metadata block, zero-dep YAML fallback.

Registry
- 20+ hand-written rich FunctionSpec entries for the new APIs; total
  public callables registered now 729+, including first-class entries
  for every new sp.epi / sp.mr / sp.longitudinal / sp.question name.

Independent review fixes (2 Critical + 5 High + 4 Medium)
- Critical: Katz RR SE formula corrected for Haldane-corrected cells.
- Critical: Mantel-Haenszel homogeneity Q replaced with the correct
  inverse-variance weighted chi^2(K-1) form (previously fabricated).
- Regime AST walker now rejects non-numeric values from history
  (blocks callable/string leakage via user-controlled dicts).
- NNT CI ordering fixed when RD CI is entirely negative.
- unified_sensitivity no longer fabricates beta_uncontrolled for
  Oster delta; requires explicit input or skips with a warning.
- unified_sensitivity breakdown bias_to_flip now derives from the CI
  bound closer to the null, not abs(estimate).
- unified_sensitivity exceptions now emit warnings.warn instead of
  silently returning NaN.
- MR-Egger intercept p-value uses t(n-2) (matches R packages).
- mr_radial requires >= 2 SNPs; mr_f_statistic now reports per-SNP F.
- Longitudinal g-formula warns when pivot fills missing panel cells.
- YAML serializer partitions on ": " so colons in values round-trip.

Tests
- 129 new tests across 11 new test files; 0 regressions across the
  2158-test existing suite.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: brycewang-stanford

.gitignore

@@ -178,4 +178,4 @@ test-notebooks/demo_causal_inference.ipynb
 
 # Claude Code session state (local only)
 .claude/
-
+CLAUDE.md

CHANGELOG.md

@@ -2,16 +2,18 @@
 
 All notable changes to StatsPAI will be documented in this file.
 
-## [0.9.17] - 2026-04-21 — Modern-weighting + MC g-formula + weakrobust panel + end-to-end workflow
-
-Surgical release targeting four of the most-requested gaps identified
-in the v1.0 gap-analysis pass: a Stata-style unified weak-IV-robust
-diagnostic panel, the Zubizarreta (2015) stable-balancing-weights
-estimator, the Robins (1986) Monte-Carlo g-formula (complementing the
-existing Bang-Robins ICE), and a truly end-to-end `sp.causal()`
-orchestrator that auto-runs multi-estimator comparison + sensitivity
-triad + CATE heterogeneity on top of the existing diagnose/recommend/
-estimate/robustness stages.
+## [0.9.17] - 2026-04-21 — Modern-weighting + MC g-formula + weakrobust panel + three-school completion
+
+Two-pronged release. First, a surgical pass targeting four of the most-
+requested gaps from the v1.0 gap-analysis: a Stata-style unified
+weak-IV-robust diagnostic panel, the Zubizarreta (2015) stable-balancing-
+weights estimator, the Robins (1986) Monte-Carlo g-formula (complementing
+the existing Bang-Robins ICE), and a truly end-to-end `sp.causal()`
+orchestrator. Second, a three-school completion pass mapping the
+*Econometrics ↔ Epidemiology ↔ ML* knowledge-map article onto StatsPAI:
+epidemiology primitives, MR full suite, longitudinal dispatcher, DAG-to-
+estimator recommender, estimand-first DSL, and a unified sensitivity
+dashboard attached to every `Result` object.
 
 ### Added
 
@@ -75,6 +77,106 @@ time-series causal discovery, Partial-ID + ML bounds, and the
 Agent-MCP server integration. Each is substantial enough to warrant
 its own focused sprint rather than being shipped half-finished here.
 
+### Added — three-school completion (2026-04-21 sub-release)
+
+Driven by a cross-reference audit against the article
+"Causal Inference Knowledge Map — Econometrics, Epidemiology, ML",
+which pinpointed Layer-4 (*What If* longitudinal), epidemiology
+entry-level primitives, Mendelian randomization diagnostic depth,
+DAG-to-estimator UX, and estimand-first workflow as the remaining
+gaps vs. Stata / R dominance.
+
+**Epidemiology primitives (`sp.epi`) — NEW subpackage**
+
+- `odds_ratio`, `relative_risk`, `risk_difference`,
+  `attributable_risk` (Levin PAF), `incidence_rate_ratio` (exact
+  Poisson CI via Clopper-Pearson), `number_needed_to_treat`,
+  `prevalence_ratio` — Woolf / Fisher-exact / Katz / Wald / Newcombe
+  intervals; Haldane-Anscombe correction for zero cells.
+- `mantel_haenszel` (OR / RR with Robins-Breslow-Greenland variance),
+  `breslow_day_test` (homogeneity of OR with Tarone correction).
+- `direct_standardize`, `indirect_standardize` — direct-standardized
+  rates + SMR with Garwood exact Poisson CI.
+- `bradford_hill` — structured 9-viewpoint causal-assessment rubric
+  with prerequisite check (no causality claim without temporality).
+
+**Mendelian randomization full suite (`sp.mr` / `sp.mendelian`)**
+
+- `mr_heterogeneity` — Cochran's Q (IVW) or Rücker's Q' (Egger) + I².
+- `mr_pleiotropy_egger` — formal MR-Egger intercept test for
+  directional horizontal pleiotropy (Bowden 2015).
+- `mr_leave_one_out` — per-SNP drop-one IVW sensitivity.
+- `mr_steiger` — Hemani (2017) directionality test using Fisher-z of
+  per-trait R² contributions.
+- `mr_presso` — Verbanck (2018) global outlier test + per-SNP outlier
+  detection + distortion test for raw-vs-corrected comparison.
+- `mr_radial` — Bowden (2018) radial reparameterization + Bonferroni-
+  thresholded outlier flagging.
+
+**Target trial emulation — publication-ready report**
+
+- `TargetTrialResult.to_paper(fmt=...)` / `sp.target_trial.to_paper` —
+  render STROBE-compatible Methods + Results block in Markdown /
+  LaTeX / plain-text for direct inclusion in manuscripts.  Table
+  structure tracks the JAMA 2022 7-component TTE spec exactly.
+
+**Longitudinal causal dispatcher (`sp.longitudinal`) — NEW subpackage**
+
+- `sp.longitudinal.analyze` — unified entry point that auto-routes
+  to IPW (no time-varying confounders) / MSM (dynamic regime with
+  time-varying confounders) / parametric g-formula ICE (static
+  regime) based on data shape and the supplied regime object.
+- `sp.longitudinal.contrast` — plug-in estimator of
+  `E[Y(regime_a)] - E[Y(regime_b)]` with delta-method SE.
+- `sp.regime`, `sp.always_treat`, `sp.never_treat` — dynamic-treatment-
+  regime DSL supporting static sequences, callables, and a safe
+  `"if cd4 < 200 then 1 else 0"` string DSL. The string DSL is parsed
+  into a whitelisted AST and interpreted by a tiny tree-walker — no
+  dynamic code execution is ever invoked, and disallowed constructs
+  are rejected at regime-construction time.
+
+**Estimand-first causal-question DSL (`sp.causal_question`) — NEW subpackage**
+
+- `sp.causal_question(treatment=, outcome=, estimand=, design=, ...)`
+  declares a causal question up front.  `.identify()` picks an
+  estimator + lists the identifying assumptions the user must defend;
+  `.estimate()` runs the analysis; `.report()` produces a Markdown
+  Methods + Results paragraph.
+- Auto-design selects IV when instruments are present, RD when running
+  variable + cutoff given, DiD when panel + time, longitudinal when
+  repeated measures, else selection-on-observables.
+- Dispatches internally to `sp.regress` / `sp.aipw` / `sp.iv` /
+  `sp.did` / `sp.rdrobust` / `sp.synth` / `sp.longitudinal.analyze` /
+  `sp.event_study`.
+
+**DAG → estimator recommender (`sp.dag.recommend_estimator`)**
+
+- `DAG.recommend_estimator(exposure, outcome)` — inspects the declared
+  graph and suggests a StatsPAI estimator with a plain-English
+  identification story. Priority order: backdoor adjustment (OLS /
+  IPW / matching) → IV (heuristic relevance + exclusion check) →
+  frontdoor → not-identifiable (with sensitivity-analysis fallbacks).
+- Detects mediators on the causal path automatically.
+
+**Unified sensitivity dashboard (`sp.unified_sensitivity`)**
+
+- `result.sensitivity()` — method added to both `CausalResult` and
+  `EconometricResults`. Single call runs E-value (always), Oster δ
+  (when R² inputs supplied), Rosenbaum Γ (when a matched structure is
+  exposed), Sensemakr (regression models), and a breakdown-frontier
+  bias estimate.
+
+### Changed (three-school completion)
+
+- `__init__.py`: 40+ new names exposed at top level including `sp.epi`,
+  `sp.longitudinal`, `sp.question`, `sp.tte` / `sp.mr` short aliases.
+
+### Fixed (three-school completion)
+
+- Regime DSL: AST validation moved from evaluate-time to compile-time
+  so unsafe expressions are rejected immediately at `sp.regime(...)`
+  construction, before any history is supplied.
+
 ## [0.9.16] - 2026-04-20 — v1.0 breadth expansion + Bayesian family polish + Rust Phase-2 CI
 
 The largest release since the v1.0 breadth pass. Maps StatsPAI onto

src/statspai/__init__.py

@@ -40,6 +40,8 @@
     bacon_decomposition, honest_did, breakdown_m, event_study,
     did_analysis, DIDAnalysis, did_multiplegt, did_imputation, stacked_did, cic,
     wooldridge_did, etwfe, etwfe_emfx, drdid, twfe_decomposition,
+    did_bcf, cohort_anchored_event_study, design_robust_event_study,
+    did_misclassified,
     did_summary, did_summary_to_markdown, did_summary_to_latex, did_report,
     pretrends_test, pretrends_power, sensitivity_rr, SensitivityResult, pretrends_summary,
     parallel_trends_plot, bacon_plot, group_time_plot, did_plot,
@@ -73,6 +75,7 @@
     synthdid_placebo, synthdid_plot, synthdid_units_plot, synthdid_rmse_plot,
     california_prop99,
 )
+from .synth.sequential_sdid import sequential_sdid, SequentialSDIDResult
 from .matching import (
     match, MatchEstimator, ebalance, balanceplot, psplot,
     propensity_score, overlap_plot, trimming, love_plot,
@@ -115,6 +118,8 @@
     negative_control_outcome, negative_control_exposure,
     double_negative_control, NegativeControlResult,
     proximal_regression, ProximalRegResult,
+    fortified_pci, bidirectional_pci, pci_mtp,
+    select_pci_proxies, ProxyScoreResult,
 )
 from .principal_strat import (
     principal_strat, PrincipalStratResult, survivor_average_causal_effect,
@@ -168,15 +173,24 @@
 from .regression.count import poisson, nbreg, ppmlhdfe
 from .neural_causal import tarnet, cfrnet, dragonnet, TARNet, CFRNet, DragonNet, gnn_causal, GNNCausalResult
 from .neural_causal.cevae import cevae, CEVAE, CEVAEResult
-from .causal_discovery import notears, NOTEARS, pc_algorithm, PCAlgorithm, lingam, LiNGAMResult, ges, GESResult, fci, FCIResult, icp, nonlinear_icp, ICPResult
-from .tmle import tmle, TMLE, super_learner, SuperLearner, ltmle, LTMLEResult
+from .causal_discovery import notears, NOTEARS, pc_algorithm, PCAlgorithm, lingam, LiNGAMResult, ges, GESResult, fci, FCIResult, icp, nonlinear_icp, ICPResult, pcmci, PCMCIResult, partial_corr_pvalue, lpcmci, LPCMCIResult, dynotears, DYNOTEARSResult
+from .tmle import tmle, TMLE, super_learner, SuperLearner, ltmle, LTMLEResult, ltmle_survival, LTMLESurvivalResult
 from .policy_learning import policy_tree, PolicyTree, policy_value, direct_method, ips, snips, doubly_robust, OPEResult
-from .conformal_causal import conformal_cate, ConformalCATE
-from .bcf import bcf, BayesianCausalForest
+from .conformal_causal import (
+    conformal_cate, ConformalCATE,
+    weighted_conformal_prediction,
+    conformal_counterfactual, ConformalCounterfactualResult,
+    conformal_ite_interval, ConformalITEResult,
+    conformal_density_ite, ConformalDensityResult,
+    conformal_ite_multidp, MultiDPConformalResult,
+    conformal_debiased_ml, DebiasedConformalResult,
+    conformal_fair_ite, FairConformalResult,
+)
+from .bcf import bcf, BayesianCausalForest, bcf_longitudinal, BCFLongResult
 from .bunching import bunching, BunchingEstimator, notch, NotchResult
 from .matrix_completion import mc_panel, MCPanel
 from .dose_response import dose_response, DoseResponse, vcnet, scigan, VCNetResult
-from .bounds import lee_bounds, manski_bounds, BoundsResult, horowitz_manski, iv_bounds, oster_delta, selection_bounds, breakdown_frontier, balke_pearl, BalkePearlResult
+from .bounds import lee_bounds, manski_bounds, BoundsResult, horowitz_manski, iv_bounds, oster_delta, selection_bounds, breakdown_frontier, balke_pearl, BalkePearlResult, ml_bounds, MLBoundsResult
 from .interference import spillover, SpilloverEstimator, network_exposure, NetworkExposureResult, peer_effects, PeerEffectsResult
 from .dtr import g_estimation, GEstimation, q_learning, QLearningResult, a_learning, ALearningResult, snmm, SNMMResult
 from .multi_treatment import multi_treatment, MultiTreatment
@@ -191,6 +205,25 @@
     llm_dag, LLMDAGResult,
 )
 
+# === Bridging theorems (DiD≡SC, EWM≡CATE, CB≡IPW, Kink≡RDD,
+#     DR-Calib, Surrogate≡PCI) ===
+from .bridge import bridge, BridgeResult
+
+# === Long-term effects via surrogate indices ===
+from . import surrogate
+from .surrogate import (
+    surrogate_index, long_term_from_short, proximal_surrogate_index,
+    SurrogateResult,
+)
+
+# === Counterfactual fairness / algorithmic-bias diagnostics ===
+from . import fairness
+from .fairness import (
+    counterfactual_fairness, orthogonal_to_bias,
+    demographic_parity, equalized_odds, fairness_audit,
+    FairnessResult, FairnessAudit,
+)
+
 # === Transportability (Pearl-Bareinboim + Dahabreh-Stuart) ===
 from . import transport
 from .transport import (
@@ -216,6 +249,8 @@
     protocol as target_trial_protocol,
     emulate as target_trial_emulate,
     to_paper as target_trial_report,
+    target_checklist as target_trial_checklist,
+    TARGET_ITEMS,
     clone_censor_weight,
     immortal_time_check,
     TargetTrialProtocol,
@@ -234,6 +269,9 @@
     mantel_haenszel, breslow_day_test,
     direct_standardize, indirect_standardize,
     bradford_hill,
+    diagnostic_test, sensitivity_specificity,
+    roc_curve, auc, cohen_kappa,
+    DiagnosticTestResult, ROCResult, KappaResult,
 )
 
 # === Longitudinal causal inference (What If Layer 4) ===
@@ -250,6 +288,7 @@
 from .question import (
     causal_question, CausalQuestion,
     IdentificationPlan, EstimationResult,
+    preregister, load_preregister,
 )
 
 # === Unified sensitivity dashboard ===
@@ -349,6 +388,8 @@
     mr_steiger, mr_presso, mr_radial,
     HeterogeneityResult, PleiotropyResult, LeaveOneOutResult,
     SteigerResult, MRPressoResult, RadialResult,
+    mr_mode, mr_f_statistic, mr_funnel_plot, mr_scatter_plot,
+    ModeBasedResult, FStatisticResult,
 )
 # Expose recommend_estimator at top level too
 from .dag import recommend_estimator as dag_recommend_estimator
@@ -372,6 +413,11 @@
 from .regression.selection import biprobit, etregress
 # Distributional Treatment Effects
 from .qte import distributional_te, DTEResult
+from .qte import (
+    dist_iv, kan_dlate, DistIVResult,
+    qte_hd_panel, HDPanelQTEResult,
+    beyond_average_late, BeyondAverageResult,
+)
 # Structural Estimation (BLP)
 from .structural import blp, BLPResult
 
@@ -1039,19 +1085,27 @@
     "number_needed_to_treat", "prevalence_ratio",
     "mantel_haenszel", "breslow_day_test",
     "direct_standardize", "indirect_standardize", "bradford_hill",
+    # v0.9.17 additions (epi clinical diagnostics)
+    "diagnostic_test", "sensitivity_specificity",
+    "roc_curve", "auc", "cohen_kappa",
+    "DiagnosticTestResult", "ROCResult", "KappaResult",
     # v0.9.17 additions (MR full suite)
     "mr", "mendelian",
     "mr_heterogeneity", "mr_pleiotropy_egger", "mr_leave_one_out",
     "mr_steiger", "mr_presso", "mr_radial",
     "HeterogeneityResult", "PleiotropyResult", "LeaveOneOutResult",
     "SteigerResult", "MRPressoResult", "RadialResult",
+    # v0.9.17 additions (MR deepening)
+    "mr_mode", "mr_f_statistic", "mr_funnel_plot", "mr_scatter_plot",
+    "ModeBasedResult", "FStatisticResult",
     # v0.9.17 additions (longitudinal unified)
     "longitudinal", "longitudinal_analyze", "longitudinal_contrast",
     "regime", "always_treat", "never_treat",
     "LongitudinalResult", "Regime",
-    # v0.9.17 additions (causal-question DSL)
+    # v0.9.17 additions (causal-question DSL + pre-registration)
     "question", "causal_question", "CausalQuestion",
     "IdentificationPlan", "EstimationResult",
+    "preregister", "load_preregister",
     # v0.9.17 additions (unified sensitivity)
     "unified_sensitivity", "SensitivityDashboard",
     # v0.9.17 additions (DAG UX)

src/statspai/agent/__init__.py

@@ -47,11 +47,23 @@
 """
 from .tools import tool_manifest, execute_tool, TOOL_REGISTRY
 from .remediation import remediate, REMEDIATIONS
+from .mcp_server import (
+    serve_stdio as mcp_serve_stdio,
+    handle_request as mcp_handle_request,
+    SERVER_NAME as MCP_SERVER_NAME,
+    SERVER_VERSION as MCP_SERVER_VERSION,
+    MCP_PROTOCOL_VERSION,
+)
 
 __all__ = [
     'tool_manifest',
     'execute_tool',
     'TOOL_REGISTRY',
     'remediate',
     'REMEDIATIONS',
+    'mcp_serve_stdio',
+    'mcp_handle_request',
+    'MCP_SERVER_NAME',
+    'MCP_SERVER_VERSION',
+    'MCP_PROTOCOL_VERSION',
 ]