Promote the survival machinery to heormodel.survival (item 18, phase 2)

[pedroliman]

Problem

Phase 1 (#58) proved the survival-to-engine path with bespoke, Weibull-only helpers inside an example. They are not reusable and are tied to one distribution and one hand-rolled maximum-likelihood fit.

Goal

Promote the machinery into a public heormodel.survival module with a clean, functional, composition-first interface that ingests a model fit from lifelines (any of its parametric families) and supports the curve operations a health economist needs. Phase 2 changes no acceptance number; it re-expresses the passing replication through the extracted layer.

Acceptance criteria

• SurvivalCurve is one composed value object (a cumulative-hazard function of time); the families, curve algebra, and adapter are functions returning curves, with no class hierarchy.
• Public surface: SurvivalCurve; families exponential, weibull, gompertz; adapter from_lifelines, sample_params; curve algebra apply_hazard_ratio, apply_acceleration_factor, mix, splice; and to_transition_matrix.
• The adapter is duck-typed, so the module imports without lifelines; the fitting package installs with a new survival extra.
• The two engines and the parameter recovery reproduce the item-18 acceptance values through the public interface: reference table (5.64394 / 4.92709 / 4.18803), both engines recover the discounted life expectancy, closed forms for a constant hazard and a hazard ratio hold, and the fitted-model and probabilistic discounted life expectancies converge to 4.92709 as the sample grows.
• Ship examples/survival_models.py, a website tutorial, an API reference section, changelog and roadmap updates, and doctest, closed-form, and convergence tests.

Follows #58.

[pedroliman]

Done on claude/roadmap-item-18-u6j1ak (commit 7c012ce).

Design notes worth recording:

• One composed value object. SurvivalCurve holds a cumulative-hazard function; survival, hazard, conditional probabilities, sampling, and per-cycle transition probabilities all derive from it. Families and curve algebra are plain functions returning new curves, so there is no distribution class hierarchy.
• One adapter covers every lifelines family. The adapter is duck-typed against params_, variance_matrix_, and _cumulative_hazard(values, times) / _hazard(values, times), which every lifelines parametric univariate fitter shares, so Weibull, log-normal, log-logistic, generalized gamma, and the rest work without reimplementing their math. Because it never imports lifelines, heormodel.survival imports fine without the extra installed.
• Sampling with no special cases. Families carry a closed-form quantile; mixtures, splices, and adapted fits invert the cumulative hazard by vectorized bisection (machine precision), so sample_time works for any curve.
• Transitions via the matrix exponential. to_transition_matrix builds each cycle's intensity matrix from cumulative-hazard increments and exponentiates it, which is exact (1 - S(k+1)/S(k)) for a single decrement and standard for competing risks.

Acceptance holds through the public interface: reference table 5.64394 / 4.92709 / 4.18803, both engines recover the discounted life expectancy, the constant-hazard and hazard-ratio closed forms are exact, and the fitted-model and probabilistic discounted life expectancies converge to 4.92709. Full suite plus doctests: 383 passed; ruff and mypy clean. The phase-1 survival_bridge example, tutorial, notebook, and test are replaced by survival_models on the public module. No pull request opened.

---

Generated by Claude Code

[pedroliman]

Holding off on this one rather than starting it silently.

devdocs/roadmap/18-survival-analysis-bridge.md states the sequencing rule explicitly: "This ordering applies across items 18, 19, and 20: reproduce all three reference models with bespoke code, confirm the numbers, then design the shared abstractions once, knowing what they have to carry." devdocs/roadmap/README.md lists item 18's phase 2 as "pending, after items 19 and 20 replicate."

Neither item 19 (partitioned survival engine) nor item 20 (multi-state/semi-Markov) has a phase-1 replication yet — no examples/ module for either exists. Extracting heormodel.survival now would shape the public API from a single worked example (item 18 only), which is the exact outcome the sequencing rule is designed to avoid.

Leaving this open and unstarted until items 19 and 20 replicate, per the documented ordering. If the sequencing should be revisited, that's a maintainer call.

---

Generated by Claude Code