heormodel 0.6.0__tar.gz

heormodel-0.6.0/PKG-INFO

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: heormodel
+Version: 0.6.0
+Summary: Health economic evaluation in Python: PSA parameters, swappable model 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
+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: 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: 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: simpy>=4.0; extra == "docs"
+
+# 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/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Health economic evaluation in Python: parameter specification and probabilistic sampling, simulation across model types, cost-effectiveness analysis (CEA), and value-of-information (VoI) analysis for model-based HEOR and HTA work.
+
+Every model engine returns costs and effects in one standardized structure, so CEA and VoI run the same on outputs from any source. You do not need a built-in engine to start: a PSA table from a spreadsheet or a legacy simulator enters the pipeline through one call.
+
+Documentation: [pedroliman.github.io/heormodel](https://pedroliman.github.io/heormodel/)
+
+## Install
+
+```bash
+pip install heormodel
+```
+
+The `calibration` extra adds ABC-SMC calibration: `pip install "heormodel[calibration]"`. Development uses [`uv`](https://docs.astral.sh/uv/); see [Development](#development).
+
+## Quickstart
+
+Load a costs/effects PSA table with `as_outcomes`, then run incremental analysis and value of information from the same object:
+
+```python
+import numpy as np
+import pandas as pd
+from heormodel.run import as_outcomes
+from heormodel.cea import icer_table
+from heormodel.voi import evpi
+
+rng = np.random.default_rng(7)
+n = 2_000
+df = pd.concat(
+    pd.DataFrame({
+        "strategy": name, "iteration": range(n),
+        "cost": rng.normal(cost, 2_000, n), "qaly": rng.normal(q, 0.4, n),
+    })
+    for name, cost, q in [("Standard care", 40_000, 8.0), ("New drug", 52_000, 8.6)]
+)
+
+outcomes = as_outcomes(df)   # accepts a DataFrame or a CSV path
+icer_table(outcomes).round(1)
+#                   cost  effect  inc_cost  inc_effect     icer status
+# strategy
+# Standard care  39920.1     8.0       NaN         NaN      NaN     ND
+# New drug       51985.1     8.6   12065.0         0.6  20606.0     ND
+
+round(evpi(outcomes, wtp=30_000), 1)
+# 4339.3
+```
+
+[`examples/byoo_example.py`](examples/byoo_example.py) runs the same wedge end to end: an external table through CEA, VoI, plots, and a run report, plus the full pipeline (`ParameterSet` sampling, `SeedManager`, `run_psa`).
+
+The `examples/mdm_*.py` scripts replicate three published Sick-Sicker cost-effectiveness tutorials and match their deterministic results: a cohort state-transition model (`mdm_cohort.py`), its time-dependent version with age-varying mortality (`mdm_cohort_timedep.py`), and a microsimulation (`mdm_microsim.py`). Each has a companion page in the [replication gallery](https://pedroliman.github.io/heormodel/tutorials/replication-gallery.html).
+
+[`examples/microsim.py`](examples/microsim.py) builds an individual-level model with `MicrosimModel`: frailty heterogeneity and a mortality risk that rises with time spent sick, two features a cohort average cannot carry, then runs it through CEA and VoI. Run it with `uv run python examples/microsim.py`.
+
+[`examples/markov_vs_microsim.py`](examples/markov_vs_microsim.py) builds one Sick-Sicker-style model as both a `MarkovModel` cohort trace and a `MicrosimModel` individual simulation from the same rates. The homogeneous microsimulation converges to the cohort trace (a cross-engine cross-validation), then a mean-1 frailty raises the microsimulation QALYs about 8% above the cohort on unchanged mean rates, the heterogeneity a cohort averages away. Run it with `uv run python examples/markov_vs_microsim.py`.
+
+[`examples/des.py`](examples/des.py) builds a resource-constrained clinic with `DESModel`, a thin SimPy wrapper: patients queue for a scarce specialist, so added capacity buys QALYs by cutting waiting time, a coupling a cohort model cannot carry. Run it with `uv run python examples/des.py` after installing the `des` extra.
+
+[`examples/calibration_workflow.py`](examples/calibration_workflow.py) mixes parameter sources: a natural-history model's transition rates are calibrated to observed prevalence with `abc_calibrate`, utilities and costs come from the literature, and `mix_draws` joins the two into one PSA that flows through CEA and VoI. Run it with `uv run python examples/calibration_workflow.py` after installing the `calibration` extra.
+
+[`examples/parameter_inputs.py`](examples/parameter_inputs.py) shows the three ways parameters enter the run loop besides distribution sampling: `single_draw` (and `ParameterSet.at_means`) for a base-case run, `read_draws` for a draw matrix from a CSV or DataFrame, and `resample_posterior` for a weighted posterior resampled with replacement. Run it with `uv run python examples/parameter_inputs.py`.
+
+## Package layout
+
+| Subpackage | Status | Contents |
+|---|---|---|
+| `heormodel.params` | done | Distribution specs with mean/SE constructors; correlated sampling; draw matrices from point values, CSVs, and weighted posteriors |
+| `heormodel.models` | done | `Outcomes` schema, `ModelEngine` protocol; cohort state-transition, microsimulation, and discrete-event engines built |
+| `heormodel.run` | done | `SeedManager`, `run_psa`, `as_outcomes`, running-mean diagnostics |
+| `heormodel.cea` | done | ICERs, dominance, extended dominance, frontier, NMB/NHB, CEAC/CEAF |
+| `heormodel.dsa` | done | One-way, one-at-a-time, and full-factorial grid deterministic sensitivity designs |
+| `heormodel.voi` | done | EVPI; EVPPI (spline/GP metamodels); EVSI (regression; others stubbed) |
+| `heormodel.calibrate` | done, optional | ABC-SMC via `pyabc`; posterior as an iteration-indexed draw matrix |
+| `heormodel.report` | done | CE plane, CEAC/CEAF, frontier, tornado plots; provenance, run report |
+
+Full docs are at [pedroliman.github.io/heormodel](https://pedroliman.github.io/heormodel/). Next steps are prioritized in [`roadmap/`](roadmap/README.md); shipped changes are in [CHANGELOG.md](CHANGELOG.md); the release process is in [RELEASING.md](RELEASING.md). Prose follows [`guidance/writing_style.md`](guidance/writing_style.md).
+
+## Development
+
+Requires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uv venv && uv pip install -e ".[dev]"   # extras: calibration (pyabc), des (simpy), dev
+uv run pytest                            # suite incl. validation checks
+uv run pytest --doctest-modules src      # every docstring example runs
+uv run ruff check . && uv run mypy
+```
+
+Two validation checks anchor the suite: a hand-verified five-strategy dominance and ICER example (`tests/test_cea.py`), and analytic Gaussian EVPI/EVPPI/EVSI recovered within Monte Carlo error at 80,000 iterations (`tests/test_voi.py`).
+
+The documentation site lives in `docs/` and builds with [Quarto](https://quarto.org) and [quartodoc](https://machow.github.io/quartodoc/); tutorials execute at render time, so the build doubles as a test. With Quarto installed and the `docs` extra synced (`uv sync --extra docs`):
+
+```bash
+uv run quartodoc build --config docs/_quarto.yml   # generate the API reference
+quarto preview docs                                 # or: quarto render docs
+```
+
+CI (`.github/workflows/docs.yml`) rebuilds and publishes the site to GitHub Pages on every push to `main`.
+
+## Design notes
+
+- VoI metamodeling uses scikit-learn; `method=` leaves room for other backends.
+- `heormodel.calibrate` is a seventh subpackage beyond the original six; calibrated draws re-enter the pipeline as a standard draw matrix.
+- Mean/SE constructors turn published estimates into sampling distributions; direct parameterisation remains available.
+- Dirichlet vectors sample as normalised independent Gammas; leave their correlation targets at zero.
+- Tornado diagrams are PSA-based (linear fits at outer percentiles); phase 1 has no deterministic engine to re-run.

heormodel-0.6.0/README.md

@@ -0,0 +1,111 @@
+# 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/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Health economic evaluation in Python: parameter specification and probabilistic sampling, simulation across model types, cost-effectiveness analysis (CEA), and value-of-information (VoI) analysis for model-based HEOR and HTA work.
+
+Every model engine returns costs and effects in one standardized structure, so CEA and VoI run the same on outputs from any source. You do not need a built-in engine to start: a PSA table from a spreadsheet or a legacy simulator enters the pipeline through one call.
+
+Documentation: [pedroliman.github.io/heormodel](https://pedroliman.github.io/heormodel/)
+
+## Install
+
+```bash
+pip install heormodel
+```
+
+The `calibration` extra adds ABC-SMC calibration: `pip install "heormodel[calibration]"`. Development uses [`uv`](https://docs.astral.sh/uv/); see [Development](#development).
+
+## Quickstart
+
+Load a costs/effects PSA table with `as_outcomes`, then run incremental analysis and value of information from the same object:
+
+```python
+import numpy as np
+import pandas as pd
+from heormodel.run import as_outcomes
+from heormodel.cea import icer_table
+from heormodel.voi import evpi
+
+rng = np.random.default_rng(7)
+n = 2_000
+df = pd.concat(
+    pd.DataFrame({
+        "strategy": name, "iteration": range(n),
+        "cost": rng.normal(cost, 2_000, n), "qaly": rng.normal(q, 0.4, n),
+    })
+    for name, cost, q in [("Standard care", 40_000, 8.0), ("New drug", 52_000, 8.6)]
+)
+
+outcomes = as_outcomes(df)   # accepts a DataFrame or a CSV path
+icer_table(outcomes).round(1)
+#                   cost  effect  inc_cost  inc_effect     icer status
+# strategy
+# Standard care  39920.1     8.0       NaN         NaN      NaN     ND
+# New drug       51985.1     8.6   12065.0         0.6  20606.0     ND
+
+round(evpi(outcomes, wtp=30_000), 1)
+# 4339.3
+```
+
+[`examples/byoo_example.py`](examples/byoo_example.py) runs the same wedge end to end: an external table through CEA, VoI, plots, and a run report, plus the full pipeline (`ParameterSet` sampling, `SeedManager`, `run_psa`).
+
+The `examples/mdm_*.py` scripts replicate three published Sick-Sicker cost-effectiveness tutorials and match their deterministic results: a cohort state-transition model (`mdm_cohort.py`), its time-dependent version with age-varying mortality (`mdm_cohort_timedep.py`), and a microsimulation (`mdm_microsim.py`). Each has a companion page in the [replication gallery](https://pedroliman.github.io/heormodel/tutorials/replication-gallery.html).
+
+[`examples/microsim.py`](examples/microsim.py) builds an individual-level model with `MicrosimModel`: frailty heterogeneity and a mortality risk that rises with time spent sick, two features a cohort average cannot carry, then runs it through CEA and VoI. Run it with `uv run python examples/microsim.py`.
+
+[`examples/markov_vs_microsim.py`](examples/markov_vs_microsim.py) builds one Sick-Sicker-style model as both a `MarkovModel` cohort trace and a `MicrosimModel` individual simulation from the same rates. The homogeneous microsimulation converges to the cohort trace (a cross-engine cross-validation), then a mean-1 frailty raises the microsimulation QALYs about 8% above the cohort on unchanged mean rates, the heterogeneity a cohort averages away. Run it with `uv run python examples/markov_vs_microsim.py`.
+
+[`examples/des.py`](examples/des.py) builds a resource-constrained clinic with `DESModel`, a thin SimPy wrapper: patients queue for a scarce specialist, so added capacity buys QALYs by cutting waiting time, a coupling a cohort model cannot carry. Run it with `uv run python examples/des.py` after installing the `des` extra.
+
+[`examples/calibration_workflow.py`](examples/calibration_workflow.py) mixes parameter sources: a natural-history model's transition rates are calibrated to observed prevalence with `abc_calibrate`, utilities and costs come from the literature, and `mix_draws` joins the two into one PSA that flows through CEA and VoI. Run it with `uv run python examples/calibration_workflow.py` after installing the `calibration` extra.
+
+[`examples/parameter_inputs.py`](examples/parameter_inputs.py) shows the three ways parameters enter the run loop besides distribution sampling: `single_draw` (and `ParameterSet.at_means`) for a base-case run, `read_draws` for a draw matrix from a CSV or DataFrame, and `resample_posterior` for a weighted posterior resampled with replacement. Run it with `uv run python examples/parameter_inputs.py`.
+
+## Package layout
+
+| Subpackage | Status | Contents |
+|---|---|---|
+| `heormodel.params` | done | Distribution specs with mean/SE constructors; correlated sampling; draw matrices from point values, CSVs, and weighted posteriors |
+| `heormodel.models` | done | `Outcomes` schema, `ModelEngine` protocol; cohort state-transition, microsimulation, and discrete-event engines built |
+| `heormodel.run` | done | `SeedManager`, `run_psa`, `as_outcomes`, running-mean diagnostics |
+| `heormodel.cea` | done | ICERs, dominance, extended dominance, frontier, NMB/NHB, CEAC/CEAF |
+| `heormodel.dsa` | done | One-way, one-at-a-time, and full-factorial grid deterministic sensitivity designs |
+| `heormodel.voi` | done | EVPI; EVPPI (spline/GP metamodels); EVSI (regression; others stubbed) |
+| `heormodel.calibrate` | done, optional | ABC-SMC via `pyabc`; posterior as an iteration-indexed draw matrix |
+| `heormodel.report` | done | CE plane, CEAC/CEAF, frontier, tornado plots; provenance, run report |
+
+Full docs are at [pedroliman.github.io/heormodel](https://pedroliman.github.io/heormodel/). Next steps are prioritized in [`roadmap/`](roadmap/README.md); shipped changes are in [CHANGELOG.md](CHANGELOG.md); the release process is in [RELEASING.md](RELEASING.md). Prose follows [`guidance/writing_style.md`](guidance/writing_style.md).
+
+## Development
+
+Requires Python 3.11+ and [`uv`](https://docs.astral.sh/uv/):
+
+```bash
+uv venv && uv pip install -e ".[dev]"   # extras: calibration (pyabc), des (simpy), dev
+uv run pytest                            # suite incl. validation checks
+uv run pytest --doctest-modules src      # every docstring example runs
+uv run ruff check . && uv run mypy
+```
+
+Two validation checks anchor the suite: a hand-verified five-strategy dominance and ICER example (`tests/test_cea.py`), and analytic Gaussian EVPI/EVPPI/EVSI recovered within Monte Carlo error at 80,000 iterations (`tests/test_voi.py`).
+
+The documentation site lives in `docs/` and builds with [Quarto](https://quarto.org) and [quartodoc](https://machow.github.io/quartodoc/); tutorials execute at render time, so the build doubles as a test. With Quarto installed and the `docs` extra synced (`uv sync --extra docs`):
+
+```bash
+uv run quartodoc build --config docs/_quarto.yml   # generate the API reference
+quarto preview docs                                 # or: quarto render docs
+```
+
+CI (`.github/workflows/docs.yml`) rebuilds and publishes the site to GitHub Pages on every push to `main`.
+
+## Design notes
+
+- VoI metamodeling uses scikit-learn; `method=` leaves room for other backends.
+- `heormodel.calibrate` is a seventh subpackage beyond the original six; calibrated draws re-enter the pipeline as a standard draw matrix.
+- Mean/SE constructors turn published estimates into sampling distributions; direct parameterisation remains available.
+- Dirichlet vectors sample as normalised independent Gammas; leave their correlation targets at zero.
+- Tornado diagrams are PSA-based (linear fits at outer percentiles); phase 1 has no deterministic engine to re-run.

heormodel-0.6.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "heormodel"
+version = "0.6.0"
+description = "Health economic evaluation in Python: PSA parameters, swappable model engines, cost-effectiveness analysis, and value of information"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Pedro Nascimento de Lima" }]
+keywords = ["health economics", "HEOR", "HTA", "cost-effectiveness", "value of information", "PSA"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+]
+dependencies = [
+    "numpy>=1.26",
+    "scipy>=1.11",
+    "pandas>=2.1",
+    "joblib>=1.3",
+    "matplotlib>=3.8",
+    "scikit-learn>=1.3",
+]
+
+[project.urls]
+Documentation = "https://pedroliman.github.io/heormodel/"
+Repository = "https://github.com/pedroliman/heormodel"
+Changelog = "https://github.com/pedroliman/heormodel/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+calibration = ["pyabc>=0.12"]
+des = ["simpy>=4.0"]
+dev = ["pytest>=8", "pytest-cov>=5", "ruff>=0.5", "mypy>=1.10", "pyabc>=0.12", "simpy>=4.0"]
+docs = ["quartodoc>=0.11", "ipykernel>=6.29,<7", "nbclient>=0.10", "nbformat>=5.10", "pyyaml>=6", "pyabc>=0.12", "simpy>=4.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+heormodel = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "NPY"]
+
+[tool.mypy]
+ignore_missing_imports = true
+disallow_untyped_defs = true
+warn_unused_ignores = false
+files = ["src/heormodel"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.coverage.run]
+source = ["src/heormodel"]
+
+[tool.coverage.report]
+exclude_lines = ["pragma: no cover"]

heormodel-0.6.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

heormodel-0.6.0/src/heormodel/__init__.py

@@ -0,0 +1,43 @@
+"""heval: health economic evaluation in Python.
+
+One parameter draw matrix flows through swappable model engines into a
+shared analysis layer. Engines differ internally but share a contract on
+their outputs, the `Outcomes` schema indexed by
+``(strategy, iteration)``, which makes cost-effectiveness and
+value-of-information analysis engine-agnostic. Outputs from any external
+model enter the same pipeline via `as_outcomes`.
+
+Subpackages:
+    - `heval.params`: distributions and correlated PSA sampling
+    - `heval.models`: engines behind the output contract
+    - `heval.run`: seeds, run loop, bring-your-own-outputs ingestion
+    - `heval.cea`: incremental analysis, frontier, NMB/NHB, CEAC/CEAF
+    - `heval.dsa`: one-way, one-at-a-time, and grid deterministic sensitivity designs
+    - `heval.voi`: EVPI, EVPPI, EVSI
+    - `heval.calibrate`: ABC calibration (optional ``pyabc`` extra)
+    - `heval.report`: plots and reproducibility scaffolding
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+from heormodel.models import ModelEngine, ModelFn, Outcomes
+from heormodel.params import ParameterSet, mix_draws
+from heormodel.run import SeedManager, as_outcomes, run_psa
+
+try:
+    __version__ = _version("heval")
+except PackageNotFoundError:  # pragma: no cover - not installed, e.g. running from source
+    __version__ = "0.0.0"
+
+__all__ = [
+    "ModelEngine",
+    "ModelFn",
+    "Outcomes",
+    "ParameterSet",
+    "SeedManager",
+    "__version__",
+    "as_outcomes",
+    "mix_draws",
+    "run_psa",
+]

heormodel-0.6.0/src/heormodel/calibrate/__init__.py

@@ -0,0 +1,16 @@
+"""Model calibration (`heval.calibrate`).
+
+Approximate Bayesian computation via ``pyabc`` (optional dependency):
+translate ``heval`` priors, calibrate a simulator to observed targets, and
+get back a posterior parameter draw matrix that flows into the standard
+PSA pipeline through the shared iteration index.
+"""
+
+from heormodel.calibrate.abc import (
+    CalibrationResult,
+    TargetSimulator,
+    abc_calibrate,
+    to_pyabc_prior,
+)
+
+__all__ = ["CalibrationResult", "TargetSimulator", "abc_calibrate", "to_pyabc_prior"]

heormodel-0.6.0/src/heormodel/calibrate/abc.py

@@ -0,0 +1,182 @@
+"""Model calibration via approximate Bayesian computation (pyabc).
+
+Bridges ``heval`` parameter specs to ``pyabc`` priors, runs ABC-SMC against
+observed calibration targets, and returns the posterior as an
+equally-weighted parameter draw matrix carrying the standard ``iteration``
+index, so calibrated draws flow through `heval.run.run_psa` and the
+analysis layer exactly like draws from `heval.params.ParameterSet.sample`.
+
+``pyabc`` is an optional dependency: install with ``uv pip install
+'heval[calibration]'``.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+
+from heormodel.params.distributions import (
+    Beta,
+    Dirichlet,
+    Distribution,
+    Gamma,
+    LogNormal,
+    Normal,
+    Uniform,
+)
+
+#: A calibration simulator: parameter values -> simulated calibration targets.
+TargetSimulator = Callable[[dict[str, float]], dict[str, float]]
+
+
+def _require_pyabc() -> Any:
+    try:
+        import pyabc
+    except ImportError as err:  # pragma: no cover
+        raise ImportError(
+            "Calibration requires pyabc; install it with uv pip install 'heval[calibration]'."
+        ) from err
+    return pyabc
+
+
+def to_pyabc_prior(distributions: Mapping[str, Distribution | Dirichlet]) -> Any:
+    """Translate ``heval`` distribution specs into a ``pyabc`` prior.
+
+    Supported: `Beta`, `Gamma`, `LogNormal`,
+    `Normal`, `Uniform`. Dirichlet and Fixed parameters cannot
+    be calibrated directly; hold them constant inside the simulator instead.
+
+    Example:
+        >>> from heormodel.calibrate import to_pyabc_prior  # doctest: +SKIP
+        >>> from heormodel.params import Beta
+        >>> prior = to_pyabc_prior({"p": Beta(2, 8)})  # doctest: +SKIP
+    """
+    pyabc = _require_pyabc()
+    rvs: dict[str, Any] = {}
+    for name, dist in distributions.items():
+        if isinstance(dist, Beta):
+            rvs[name] = pyabc.RV("beta", dist.alpha, dist.beta)
+        elif isinstance(dist, Gamma):
+            rvs[name] = pyabc.RV("gamma", dist.shape, scale=dist.scale)
+        elif isinstance(dist, LogNormal):
+            rvs[name] = pyabc.RV("lognorm", dist.sigma, scale=float(np.exp(dist.mu)))
+        elif isinstance(dist, Normal):
+            rvs[name] = pyabc.RV("norm", dist.mean_, dist.sd_)
+        elif isinstance(dist, Uniform):
+            rvs[name] = pyabc.RV("uniform", dist.low, dist.high - dist.low)
+        else:
+            raise TypeError(
+                f"Parameter {name!r}: {type(dist).__name__} priors are not supported "
+                "for ABC calibration; hold it constant inside the simulator."
+            )
+    return pyabc.Distribution(**rvs)
+
+
+@dataclass
+class CalibrationResult:
+    """Posterior draws and diagnostics from an ABC-SMC calibration.
+
+    Attributes:
+        posterior: Equally-weighted posterior draw matrix with a
+            ``RangeIndex`` named ``iteration``, ready for
+            `heval.run.run_psa`.
+        weighted: The raw weighted particle population (columns = parameters,
+            plus a ``weight`` column).
+        n_populations: Number of ABC-SMC populations run.
+        final_epsilon: Acceptance threshold of the final population.
+    """
+
+    posterior: pd.DataFrame
+    weighted: pd.DataFrame
+    n_populations: int
+    final_epsilon: float
+
+
+def abc_calibrate(
+    simulator: TargetSimulator,
+    priors: Mapping[str, Distribution | Dirichlet],
+    observed: Mapping[str, float],
+    *,
+    population_size: int = 200,
+    max_populations: int = 8,
+    min_epsilon: float = 0.0,
+    n_posterior: int | None = None,
+    seed: int | None = None,
+    db_path: str | Path | None = None,
+) -> CalibrationResult:
+    """Calibrate model parameters to observed targets with ABC-SMC.
+
+    Args:
+        simulator: Maps a parameter dict to simulated calibration targets
+            (same keys as ``observed``).
+        priors: Parameter priors as ``heval`` distribution specs.
+        observed: Observed calibration target values.
+        population_size: Particles per ABC-SMC population.
+        max_populations: Maximum number of populations.
+        min_epsilon: Stop once the acceptance threshold reaches this value.
+        n_posterior: Rows in the returned equally-weighted posterior matrix
+            (default: the final population size).
+        seed: Seed for the weighted-to-equal resampling step. (The ABC run
+            itself uses pyabc's internal randomness.)
+        db_path: Where to store pyabc's bookkeeping database (default: a
+            temporary file).
+
+    Returns:
+        A `CalibrationResult` whose ``posterior`` plugs directly into
+        the PSA pipeline.
+
+    Example:
+        >>> from heormodel.calibrate import abc_calibrate  # doctest: +SKIP
+        >>> from heormodel.params import Uniform
+        >>> result = abc_calibrate(  # doctest: +SKIP
+        ...     simulator=lambda p: {"prevalence": p["risk"] * 0.5},
+        ...     priors={"risk": Uniform(0.0, 1.0)},
+        ...     observed={"prevalence": 0.15},
+        ... )
+    """
+    pyabc = _require_pyabc()
+    from pyabc.sampler import SingleCoreSampler
+
+    prior = to_pyabc_prior(priors)
+    keys = sorted(observed)
+
+    def model(parameter: Mapping[str, float]) -> dict[str, float]:
+        return dict(simulator(dict(parameter)))
+
+    distance = pyabc.PNormDistance(p=2)
+    abc = pyabc.ABCSMC(
+        model,
+        prior,
+        distance,
+        population_size=population_size,
+        sampler=SingleCoreSampler(),
+    )
+    if db_path is None:
+        db_file = Path(tempfile.mkdtemp()) / "heval_abc.db"
+    else:
+        db_file = Path(db_path)
+    abc.new("sqlite:///" + str(db_file), {k: float(observed[k]) for k in keys})
+    history = abc.run(minimum_epsilon=min_epsilon, max_nr_populations=max_populations)
+
+    particles, weights = history.get_distribution()
+    weighted = particles.copy()
+    weighted["weight"] = weights
+    rng = np.random.default_rng(seed)
+    n_out = n_posterior or len(particles)
+    picks = rng.choice(len(particles), size=n_out, p=np.asarray(weights) / np.sum(weights))
+    posterior = particles.iloc[picks].reset_index(drop=True)
+    posterior.index = pd.RangeIndex(n_out, name="iteration")
+    posterior.columns.name = None
+    epsilons = history.get_all_populations()["epsilon"]
+    return CalibrationResult(
+        posterior=posterior,
+        weighted=weighted,
+        n_populations=history.max_t + 1,
+        final_epsilon=float(epsilons.iloc[-1]),
+    )

heormodel-0.6.0/src/heormodel/cea/__init__.py

@@ -0,0 +1,25 @@
+"""Cost-effectiveness analysis (`heval.cea`).
+
+Engine-agnostic decision analysis on the standard outcome schema:
+incremental analysis with dominance and extended dominance, the efficiency
+frontier, net monetary/health benefit, acceptability curves (CEAC), the
+acceptability frontier (CEAF), and cost-effectiveness-plane data.
+"""
+
+from heormodel.cea.ceac import ce_plane, ceac, ceaf
+from heormodel.cea.frontier import STATUS_D, STATUS_ED, STATUS_ND, frontier, icer_table
+from heormodel.cea.nb import expected_nmb, nhb, nmb
+
+__all__ = [
+    "STATUS_D",
+    "STATUS_ED",
+    "STATUS_ND",
+    "ce_plane",
+    "ceac",
+    "ceaf",
+    "expected_nmb",
+    "frontier",
+    "icer_table",
+    "nhb",
+    "nmb",
+]