Docs P2/P3: choosing-an-estimator, IHDP tutorial, FAQ, uncertainty catalog

[jeongyoonlee]

The P2 and P3 items from the docs roadmap, as one PR. Four new pages and two upgraded ones:

New pages (P2)

• Choosing an Estimator — a data-situation decision path (randomized? compliance? confounders measured? instrument?) plus a capability matrix over the estimators (outcome/treatment types, observational support, uncertainty, extras). Replaces the Decision Guide image removed in Docs phase 2: correctness pass over the published pages, and a five-section structure #1018 with reviewable rst; every cell checked against live class signatures. Modeled on EconML's flowchart + comparison table.
• Estimating and Validating Heterogeneous Treatment Effects — an end-to-end walkthrough on IHDP via fetch_ihdp() (Benchmark datasets, ground-truth metrics and a leaderboard (v1.0 M3) #1015), the standard HTE testbed: confounded assignment makes the overlap check real, simulated potential outcomes give per-unit ground truth. It opens with an explicit identification statement (unconfoundedness given the covariates — true by construction on IHDP, untestable on real data), trains one estimator per family (X-learner, R-learner, honest CausalRandomForestRegressor, jax DragonNet), and walks the evaluation toolkit with built-in lessons: the R-learner's ATE interval is the narrowest and the only one excluding the truth; DragonNet wins ground-truth PEHE (0.455) while the R-learner fails (2.13); the blind validation losses recover that verdict without seeing the truth; at 75 validation rows RATE's only significant p-value lands on the worst model (a multiple-testing accident, taught as such) while at 374 rows the real X-learner signal appears; gain/TOC curves show why AUUC favors DragonNet's broad margin and RATE the X-learner's early concentration; sensitivity analysis and the across-replications protocol close it out (DragonNet uniquely stable at 0.599 ± 0.054 over 10 reps), with the caution that the CEVAE/DragonNet papers aggregate over the 1,000-replication release while causalml ships 100. A final Summary recaps the workflow and per-model verdicts. Every output is from one seeded run executed in page order; figures are pre-rendered so the docs build stays offline. Modeled on DoubleML's workflow page.
• FAQ — nine questions seeded from the real support surface: macOS OpenMP, CA-cert download failures, the honesty=True default change, the n_jobs default change, negative Qini, overlap violations, Twins 9999 encoding, IHDP replication alignment, when the neural extras are needed.
• Uncertainty Quantification — what CI/SE each estimator family and metric reports and how to request it (analytic vs bootstrap ATE CIs, bootstrap CATE CIs, forestci infinitesimal-jackknife forest variance, metric return_ci semantics), consolidating an API surface spread across the classes. Modeled on EconML's Inference chapter.

Upgraded pages (P3)

• Methodology — each family section now opens with a Relevant classes lead, and the intro routes method selection to the new choosing page. This is the roadmap's in-place alternative to splitting the page, which would break every methodology:* label and external deep link; a future split can follow behind sphinx-reredirects without losing this.
• Intro — a 200-replication simulation on the package's own synthetic data showing the difference in means biased +0.40 on a true ATE of 0.5 while a T-learner centers at +0.09, with pre-rendered figure.

Getting Started gains tutorial and faq; the User Guide gains choosing_an_estimator (first) and inference. Docs-only; sphinx -W exit 0 on html, epub and latex; toctree-reachability test passes.

🤖 Generated with Claude Code