PyHEOR

Python tools for health economic modeling and cost-effectiveness analysis.

中文 · Français

Example results

Figures generated by the synthetic examples in this repository. Click an image to view it at full size.

Survival modeling	Parameter uncertainty
Compare fitted PFS and OS curves.	Explore incremental costs and QALYs across PSA draws.
Cost-effectiveness acceptability (CEAC)	Multi-strategy decision analysis (CEAF)
See how cost-effectiveness probabilities vary with WTP.	Track the recommended strategy and its cost-effectiveness probability.

Reproduce these figures with the PSM oncology and multi-strategy comparison examples. CEAC/CEAF show labeled display smoothing; analysis and exports retain raw probabilities.

Install

pip install pyheor

Requires Python 3.9+, NumPy, SciPy, pandas, matplotlib and openpyxl.

Models

Base-case analysis, sensitivity analysis, strategy comparisons, CE planes, CEACs, traces and report exports are available. DES retains base-case and PSA support.

Quick start

State costs and QALYs are per cycle. Discount rates are effective rates per cycle, and the first cycle is undiscounted. Utility weights require an explicit conversion to QALYs.

import pyheor as ph

cycle = ph.Cycle(1, "month")
model = ph.MarkovModel(
    states=["Alive", "Dead"], strategies=["SOC", "TRT"],
    n_cycles=120, cycle=cycle, method="life-table",
    dr_cost=ph.rescale_discount_rate(.03, ph.Cycle(1, "year"), cycle),
    dr_qaly=ph.rescale_discount_rate(.03, ph.Cycle(1, "year"), cycle),
)
model.add_param("u_alive", base=.8, dist=ph.Beta(mean=.8, sd=.05))
model.set_transitions("SOC", [[.98, .02], [0, 1]])
model.set_transitions("TRT", [[.985, .015], [0, 1]])
model.set_state_cost("care", {
    "SOC": {"Alive": 1000}, "TRT": {"Alive": 1500},
})
model.set_state_qaly("health", {
    "Alive": lambda p, k: ph.qaly(p["u_alive"], cycle),
})
model.set_starting_cost("test", 200)
model.set_state_cost("loading", {"Alive": 500}, cycles=1)
model.set_transition_cost("terminal", "Alive", "Dead", 10000)

base = model.run_base_case()
print(base.summary())
print(base.icer())
psa = model.run_psa(n_sim=100, seed=42)

Reward APIs

Costs and QALYs have parallel state, starting, entry, transition and custom interfaces. State rewards accept cycles=1 or a list of cycle numbers. Callbacks receive parameters and optionally a 1-based cycle index and patient attributes. Starting rewards are unweighted time-zero amounts; first-cycle state rewards are weighted by occupancy.

method is beginning, end, or life-table (default). State counts and event flows follow heemod conventions. PSM cannot identify pairwise transition flows, so entry/transition reward registration is unavailable there; use an explicit Terminal state for the documented end-of-life accounting rule.

PSM uses the order in survival_endpoints as the nesting order (e.g. ["PFS", "PFS2", "OS"]). At each time, it preserves the final curve and works backward: S[j] = min(S[j], S[j+1]), using the already corrected next curve. State occupancy, plots and Excel exports use the corrected curves. Base-case and PSA calculations follow the same rule; PSA keeps every sampled parameter set. Individual curves must still be finite, within [0, 1], and nonincreasing. This adjustment changes state time and rewards where curves cross; inspect substantial crossovers when selecting extrapolations.

Practical tools

Use these tools through import pyheor as ph. Model engines require explicit units; the helpers perform the conversions you request.

import pyheor as ph

month = ph.Cycle(1, "month")
year = ph.Cycle(1, "year")
monthly_qaly = ph.qaly(.8, month)                    # 0.066667 QALY
monthly_cost = 12000 * month.years                  # Annual cost → monthly: 1000
monthly_dr = ph.rescale_discount_rate(.03, year, month)
three_month_qaly = ph.qaly(.8, 3, unit="month")      # 0.2 QALY
month_boundaries = month.time([0, 1, 12], unit="year")

# Fitted in years; after conversion t=1 means one month.
curve = ph.from_flexsurv("weibull", shape=1.3, scale=1.5)
monthly_curve = ph.rescale_survival(
    curve, from_unit="year", to_period=month,
)
treated_curve = ph.ProportionalHazards(monthly_curve, hr=.75)

Supported from_flexsurv() inputs:

GeneralizedGamma (including from_flexsurv("gengamma", ...)) uses the log-normal limit with meanlog=mu and sdlog=sigma when abs(Q) < 1e-5, to avoid numerical precision loss. This is exact at Q=0 and an approximation for nonzero Q. Excel export uses the same threshold; its positive-Q Gamma upper tails use 1-CDF, which can round very small probabilities to zero.

Parameters follow the respective R distribution definitions; names are not interchangeable across distributions. In particular, weibullPH uses a PH coefficient named scale, which the adapter converts to PyHEOR's Weibull scale.

Duration conventions are 12 months, 52 weeks or 365 days per year, rather than calendar date arithmetic. Multiply annual state cost rates by cycle years; enter one-time costs at their occurrence amounts. Put parameter-dependent QALY, discount-rate and survival conversions inside PSA/OWSA callbacks so they are recomputed for each draw.

Plots

Plots return Matplotlib Figure objects for customization and export:

fig = psa.plot_ceac(wtp_range=(0, 100000))
fig.savefig("ceac.png", dpi=150, bbox_inches="tight")

cea = ph.CEAnalysis.from_psa(psa)
cea.plot_ceaf(wtp_range=(0, 100000))

Display smoothing does not change analysis or exported values; empirical survival curves retain steps.

Results and export

base.summary() and base.icer() report totals and incremental analysis. reward_components provides cost/QALY components; cycle_rewards and state_occupancy provide cycle detail. DES also provides event logs and time in state; metadata records units and calculation conventions.

Use ph.export_to_excel(base, "results.xlsx") for result tables, ph.export_excel_model(base, "model.xlsx") for Markov/PSM formula workbooks, and ph.generate_report(model, "report.md") for an analysis report.

Examples

Runnable examples cover Markov, PSM, MicroSim and strategy comparisons. See CHANGELOG for version history.

Development

See development and versioning rules.

pip install -e '.[dev]'
pytest

License: AGPL-3.0-or-later.