Metadata-Version: 2.4
Name: heormodel
Version: 0.7.4
Summary: Decision-analytic modeling for health economic evaluation and health technology assessment: probabilistic parameters, cohort and individual-level simulation engines, cost-effectiveness analysis, and value of information
Author: Pedro Nascimento de Lima
License: MIT
Project-URL: Documentation, https://pedroliman.github.io/heormodel/
Project-URL: Repository, https://github.com/pedroliman/heormodel
Project-URL: Changelog, https://github.com/pedroliman/heormodel/blob/main/CHANGELOG.md
Keywords: health economics,HEOR,HTA,cost-effectiveness,value of information,PSA
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.11
Requires-Dist: pandas>=2.1
Requires-Dist: joblib>=1.3
Requires-Dist: matplotlib>=3.8
Requires-Dist: scikit-learn>=1.3
Provides-Extra: calibration
Requires-Dist: pyabc>=0.12; extra == "calibration"
Provides-Extra: surrogate
Requires-Dist: sbi>=0.24; extra == "surrogate"
Provides-Extra: des
Requires-Dist: simpy>=4.0; extra == "des"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.5; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pyabc>=0.12; extra == "dev"
Requires-Dist: sbi>=0.24; extra == "dev"
Requires-Dist: simpy>=4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: quartodoc>=0.11; extra == "docs"
Requires-Dist: ipykernel<7,>=6.29; extra == "docs"
Requires-Dist: nbclient>=0.10; extra == "docs"
Requires-Dist: nbformat>=5.10; extra == "docs"
Requires-Dist: pyyaml>=6; extra == "docs"
Requires-Dist: pyabc>=0.12; extra == "docs"
Requires-Dist: sbi>=0.24; extra == "docs"
Requires-Dist: simpy>=4.0; extra == "docs"
Dynamic: license-file

# heormodel

[![CI](https://github.com/pedroliman/heormodel/actions/workflows/ci.yml/badge.svg)](https://github.com/pedroliman/heormodel/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/pedroliman/heormodel/branch/main/graph/badge.svg)](https://codecov.io/gh/pedroliman/heormodel)
[![PyPI](https://img.shields.io/pypi/v/heormodel.svg)](https://pypi.org/project/heormodel/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21314037.svg)](https://doi.org/10.5281/zenodo.21314037)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

`heormodel` is a Python decision-analytic modeling framework for health economic evaluation and health technology assessment.

`heormodel` covers the full cost-effectiveness analysis workflow in one package. It supports probabilistic parameter specification for a range of models: Markov cohort state-transition models, microsimulation models, and discrete-event simulation models. It builds the incremental cost-effectiveness ratio (ICER) table and runs value-of-information analysis. If you are not ready to port your model to Python, you can also bring your existing model results directly into the package.

Read more in the documentation: [pedroliman.github.io/heormodel](https://pedroliman.github.io/heormodel/)

## Install

If you are new to Python, I recommend installing it with [uv](https://docs.astral.sh/uv/guides/install-python/). Once you have a working Python installation, run this from your terminal within your project's folder:

```bash
pip install heormodel
# or using uv, which I prefer:
# (run uv init once)
uv init
uv add heormodel
```

## Quickstart

This example compares treatment with standard care in a three-state Markov cohort state-transition model, evaluated by probabilistic sensitivity analysis. The code builds the model, runs it, and reports the ICER table and the expected value of perfect information.

```python
import numpy as np
import pandas as pd
from heormodel.models import CohortSpec, MarkovModel
from heormodel.params import Beta, Gamma, ParameterSet
from heormodel.run import SeedManager, run_psa
from heormodel.cea import icer_table
from heormodel.voi import evpi

# define your model.
def model(p, intervention):
    p_progress = p["p_progress"] * (p["rr_treat"] if intervention == "Treatment" else 1.0)
    # Transition matrix. Rows: Current state. Columns: Next state.
    P = np.array([
        [1 - p_progress - p["p_die"], p_progress, p["p_die"]],
        [0.0, 1 - p["p_die_sick"], p["p_die_sick"]],
        [0.0, 0.0, 1.0],
    ])
    cost = np.array([0.0, p["c_sick"], 0.0])
    if intervention == "Treatment":
        cost[:2] += p["c_treat"]
    return CohortSpec(P, cost, np.array([1.0, p["u_sick"], 0.0]))

# create the MarkovModel engine.
engine = MarkovModel(states=("Healthy", "Sick", "Dead"),
                     interventions=("Standard care", "Treatment"),
                     transitions_and_rewards=model, n_cycles=40)

# Define your parameters:
params = ParameterSet({
    "p_progress": Beta(20, 180), "rr_treat": Beta(60, 40),
    "p_die": Beta(5, 995), "p_die_sick": Beta(50, 450),
    "c_sick": Gamma(100, 250.0), "c_treat": Gamma(100, 80.0),
    "u_sick": Beta(150, 50),
})

# sample your parameters:
draws = params.sample(1000, seed=SeedManager(1).generator())

# run your model over your parameters.
outcomes = run_psa(engine, draws).outcomes

# Get the ICER table.
icer_table(outcomes).round(1)
#                    cost  effect  inc_cost  inc_effect     icer status
# intervention
# Standard care  142910.9    11.2       NaN         NaN      NaN     ND
# Treatment      233676.2    13.4   90765.3         2.2  41130.9     ND

# And from here your EVPI
round(evpi(outcomes, wtp=50_000), 1)
# 2738.7
```

Beyond this workflow, the package supports microsimulations, discrete-event simulation models, and compartmental transmission models written as ordinary differential equations (the `ODEModel` engine, with a susceptible-exposed-infectious-recovered vaccination example). A calibration function calibrates some parameters, takes others from the literature, then runs a full probabilistic sensitivity analysis. When the model is expensive to run, a surrogate-accelerated calibration tutorial trains a Gaussian process on a small design and calibrates through it with the `sbi` package, reaching the same posterior with about a hundred times fewer model runs.

## Development

Developer documentation lives in [`devdocs/`](devdocs/README.md). See the [CHANGELOG.md](CHANGELOG.md) for recent changes and follow the release process: [RELEASING.md](RELEASING.md).

Requires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/):

```bash
uv venv && uv pip install -e ".[dev]"
uv run pytest
uv run pytest --doctest-modules src
uv run ruff check . && uv run mypy
```

The site in `docs/` builds with [Quarto](https://quarto.org) and [quartodoc](https://machow.github.io/quartodoc/); tutorials execute at render time. With Quarto installed and `uv sync --extra docs`:

```bash
uv run quartodoc build --config docs/_quarto.yml
quarto preview docs
```

Each tutorial also carries an "Open in Colab" badge backed by a runnable notebook under `docs/_notebooks/`. Regenerate the badges and notebooks after editing a tutorial; continuous integration checks they stay in sync:

```bash
uv run python docs/build_colab_notebooks.py
```
