heormodel 0.6.0__py3-none-any.whl

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/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/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/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",
+]

heormodel/cea/ceac.py

@@ -0,0 +1,130 @@
+"""Cost-effectiveness acceptability curves, frontier, and CE-plane data."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import numpy as np
+import pandas as pd
+from numpy.typing import ArrayLike
+
+from heormodel.models.outcomes import Outcomes
+
+
+def ceac(
+    outcomes: Outcomes, wtp: ArrayLike | Sequence[float], *, effect: str | None = None
+) -> pd.DataFrame:
+    """Cost-effectiveness acceptability curve for every strategy.
+
+    For each willingness-to-pay value, the probability (share of PSA
+    iterations) that each strategy has the highest net monetary benefit.
+
+    Args:
+        outcomes: Standard PSA outcomes.
+        wtp: Grid of willingness-to-pay values.
+        effect: Effect column (default: the primary effect).
+
+    Returns:
+        DataFrame indexed by ``wtp`` with one probability column per
+        strategy; rows sum to 1.
+
+    Example:
+        >>> import pandas as pd
+        >>> from heormodel.models import Outcomes
+        >>> from heormodel.cea import ceac
+        >>> c = pd.DataFrame({"A": [0.0, 0.0], "B": [10.0, 10.0]})
+        >>> e = pd.DataFrame({"A": [0.0, 0.0], "B": [1.0, -1.0]})
+        >>> float(ceac(Outcomes.from_wide(c, e), wtp=[100.0]).loc[100.0, "B"])
+        0.5
+    """
+    wtp_grid = np.atleast_1d(np.asarray(wtp, dtype=np.float64))
+    costs = outcomes.costs_wide().to_numpy(dtype=np.float64)
+    effects = outcomes.effects_wide(effect).to_numpy(dtype=np.float64)
+    n, d = costs.shape
+    probs = np.empty((len(wtp_grid), d), dtype=np.float64)
+    for i, lam in enumerate(wtp_grid):
+        winners = np.argmax(lam * effects - costs, axis=1)
+        probs[i] = np.bincount(winners, minlength=d) / n
+    return pd.DataFrame(probs, index=pd.Index(wtp_grid, name="wtp"), columns=outcomes.strategies)
+
+
+def ceaf(
+    outcomes: Outcomes, wtp: ArrayLike | Sequence[float], *, effect: str | None = None
+) -> pd.DataFrame:
+    """Cost-effectiveness acceptability frontier.
+
+    At each willingness-to-pay value, identifies the strategy with the
+    highest **expected** NMB (the optimal choice for a risk-neutral decision
+    maker) and reports its acceptability-curve probability.
+
+    Returns:
+        DataFrame indexed by ``wtp`` with columns ``strategy`` (the optimal
+        strategy) and ``prob`` (its probability of being cost-effective).
+
+    Example:
+        >>> import pandas as pd
+        >>> from heormodel.models import Outcomes
+        >>> from heormodel.cea import ceaf
+        >>> c = pd.DataFrame({"A": [0.0, 0.0], "B": [10.0, 10.0]})
+        >>> e = pd.DataFrame({"A": [0.0, 0.0], "B": [1.0, 1.0]})
+        >>> ceaf(Outcomes.from_wide(c, e), wtp=[100.0]).loc[100.0, "strategy"]
+        'B'
+    """
+    wtp_grid = np.atleast_1d(np.asarray(wtp, dtype=np.float64))
+    curve = ceac(outcomes, wtp_grid, effect=effect)
+    costs = outcomes.costs_wide().to_numpy(dtype=np.float64)
+    effects = outcomes.effects_wide(effect).to_numpy(dtype=np.float64)
+    mean_cost = costs.mean(axis=0)
+    mean_eff = effects.mean(axis=0)
+    strategies = np.asarray(outcomes.strategies, dtype=object)
+    optimal = [strategies[int(np.argmax(lam * mean_eff - mean_cost))] for lam in wtp_grid]
+    prob = [curve.iloc[i][opt] for i, opt in enumerate(optimal)]
+    return pd.DataFrame({"strategy": optimal, "prob": prob}, index=pd.Index(wtp_grid, name="wtp"))
+
+
+def ce_plane(
+    outcomes: Outcomes, *, comparator: str | None = None, effect: str | None = None
+) -> pd.DataFrame:
+    """Incremental cost and effect per iteration versus a comparator.
+
+    Args:
+        outcomes: Standard PSA outcomes.
+        comparator: Reference strategy (default: the first strategy).
+        effect: Effect column (default: the primary effect).
+
+    Returns:
+        Tidy DataFrame with columns ``strategy``, ``iteration``,
+        ``inc_cost`` and ``inc_effect`` for every non-comparator strategy,
+        ready to scatter on the cost-effectiveness plane.
+
+    Example:
+        >>> import pandas as pd
+        >>> from heormodel.models import Outcomes
+        >>> from heormodel.cea import ce_plane
+        >>> c = pd.DataFrame({"A": [0.0], "B": [10.0]})
+        >>> e = pd.DataFrame({"A": [0.0], "B": [0.5]})
+        >>> float(ce_plane(Outcomes.from_wide(c, e))["inc_cost"][0])
+        10.0
+    """
+    ref = comparator or outcomes.strategies[0]
+    if ref not in outcomes.strategies:
+        raise KeyError(f"Unknown comparator strategy: {ref!r}.")
+    costs = outcomes.costs_wide()
+    effects = outcomes.effects_wide(effect)
+    frames = []
+    for s in outcomes.strategies:
+        if s == ref:
+            continue
+        frames.append(
+            pd.DataFrame(
+                {
+                    "strategy": s,
+                    "iteration": costs.index,
+                    "inc_cost": (costs[s] - costs[ref]).to_numpy(),
+                    "inc_effect": (effects[s] - effects[ref]).to_numpy(),
+                }
+            )
+        )
+    if not frames:
+        raise ValueError("ce_plane needs at least two strategies.")
+    return pd.concat(frames, ignore_index=True)

heormodel/cea/frontier.py

@@ -0,0 +1,134 @@
+"""Incremental cost-effectiveness analysis on the efficiency frontier.
+
+Implements the standard decision-analytic algorithm: order strategies by
+cost, remove strongly dominated strategies (more costly and no more
+effective than another), then iteratively remove extendedly dominated
+strategies (whose ICER exceeds that of the next more effective strategy)
+until ICERs increase monotonically along the frontier.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from heormodel.models.outcomes import Outcomes
+
+#: Status labels: not dominated (on the frontier), dominated, extendedly dominated.
+STATUS_ND = "ND"
+STATUS_D = "D"
+STATUS_ED = "ED"
+
+
+def _mean_table(source: Outcomes | pd.DataFrame, effect: str | None) -> pd.DataFrame:
+    if isinstance(source, Outcomes):
+        eff = effect or source.effect
+        summary = source.summary()
+        return pd.DataFrame({"cost": summary["cost"], "effect": summary[eff]})
+    df = source.copy()
+    eff = effect or ("effect" if "effect" in df.columns else "qaly")
+    missing = [c for c in ("cost", eff) if c not in df.columns]
+    if missing:
+        raise ValueError(f"Mean outcome table is missing columns: {missing}.")
+    return pd.DataFrame({"cost": df["cost"], "effect": df[eff]})
+
+
+def icer_table(source: Outcomes | pd.DataFrame, *, effect: str | None = None) -> pd.DataFrame:
+    """Full incremental analysis: dominance, extended dominance, and ICERs.
+
+    Args:
+        source: PSA `Outcomes` (means are taken per strategy) or a
+            per-strategy mean table indexed by strategy with columns
+            ``cost`` and the effect column.
+        effect: Effect column name (defaults to the outcomes' primary
+            effect, or ``"effect"`` for plain tables).
+
+    Returns:
+        DataFrame indexed by strategy, sorted by cost, with columns
+        ``cost``, ``effect``, ``inc_cost``, ``inc_effect``, ``icer`` and
+        ``status`` (``"ND"`` on the frontier, ``"D"`` strongly dominated,
+        ``"ED"`` extendedly dominated). ICERs are computed between adjacent
+        frontier strategies; the cheapest frontier strategy has no ICER.
+
+    Example:
+        >>> import pandas as pd
+        >>> from heormodel.cea import icer_table
+        >>> means = pd.DataFrame(
+        ...     {"cost": [0.0, 100.0, 400.0], "effect": [0.0, 0.5, 1.0]},
+        ...     index=["A", "B", "D"],
+        ... )
+        >>> t = icer_table(means)
+        >>> float(t.loc["D", "icer"])
+        600.0
+    """
+    means = _mean_table(source, effect)
+    means = means.sort_values(["cost", "effect"], ascending=[True, False])
+    cost = means["cost"].to_numpy(dtype=np.float64)
+    eff = means["effect"].to_numpy(dtype=np.float64)
+    n = len(means)
+    status = np.array([STATUS_ND] * n, dtype=object)
+
+    # strong dominance: another strategy is no more costly and no less
+    # effective, strictly better on at least one axis; exact duplicates keep
+    # only the first occurrence in cost order
+    for i in range(n):
+        for j in range(n):
+            if i == j:
+                continue
+            weak = cost[j] <= cost[i] and eff[j] >= eff[i]
+            strict = cost[j] < cost[i] or eff[j] > eff[i]
+            duplicate = j < i and cost[j] == cost[i] and eff[j] == eff[i]
+            if (weak and strict) or duplicate:
+                status[i] = STATUS_D
+                break
+
+    # extended dominance: remove strategies until ICERs are monotone
+    while True:
+        nd = [i for i in range(n) if status[i] == STATUS_ND]
+        if len(nd) < 3:
+            break
+        icers = [
+            (cost[nd[k]] - cost[nd[k - 1]]) / (eff[nd[k]] - eff[nd[k - 1]])
+            for k in range(1, len(nd))
+        ]
+        for k in range(len(icers) - 1):
+            if icers[k] > icers[k + 1]:
+                status[nd[k + 1]] = STATUS_ED
+                break
+        else:
+            break
+
+    inc_cost = np.full(n, np.nan)
+    inc_eff = np.full(n, np.nan)
+    icer = np.full(n, np.nan)
+    nd = [i for i in range(n) if status[i] == STATUS_ND]
+    for k in range(1, len(nd)):
+        prev, cur = nd[k - 1], nd[k]
+        inc_cost[cur] = cost[cur] - cost[prev]
+        inc_eff[cur] = eff[cur] - eff[prev]
+        icer[cur] = inc_cost[cur] / inc_eff[cur]
+
+    result = means.copy()
+    result["inc_cost"] = inc_cost
+    result["inc_effect"] = inc_eff
+    result["icer"] = icer
+    result["status"] = status
+    result.index.name = "strategy"
+    return result
+
+
+def frontier(source: Outcomes | pd.DataFrame, *, effect: str | None = None) -> list[str]:
+    """Strategies on the cost-effectiveness efficiency frontier, cheapest first.
+
+    Example:
+        >>> import pandas as pd
+        >>> from heormodel.cea import frontier
+        >>> means = pd.DataFrame(
+        ...     {"cost": [0.0, 10.0, 5.0], "effect": [0.0, 1.0, -1.0]},
+        ...     index=["A", "B", "C"],
+        ... )
+        >>> frontier(means)
+        ['A', 'B']
+    """
+    table = icer_table(source, effect=effect)
+    return [str(s) for s in table.index[table["status"] == STATUS_ND]]

heormodel/cea/nb.py

@@ -0,0 +1,62 @@
+"""Net monetary and net health benefit."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from heormodel.models.outcomes import Outcomes
+
+
+def nmb(outcomes: Outcomes, wtp: float, *, effect: str | None = None) -> pd.DataFrame:
+    """Net monetary benefit per iteration and strategy: ``wtp * effect - cost``.
+
+    Args:
+        outcomes: Standard PSA outcomes.
+        wtp: Willingness to pay per unit of effect.
+        effect: Effect column (default: the primary effect).
+
+    Returns:
+        DataFrame (iterations x strategies) of NMB values.
+
+    Example:
+        >>> import pandas as pd
+        >>> from heormodel.models import Outcomes
+        >>> from heormodel.cea import nmb
+        >>> c = pd.DataFrame({"A": [100.0]})
+        >>> e = pd.DataFrame({"A": [0.01]})
+        >>> float(nmb(Outcomes.from_wide(c, e), wtp=50_000)["A"][0])
+        400.0
+    """
+    return wtp * outcomes.effects_wide(effect) - outcomes.costs_wide()
+
+
+def nhb(outcomes: Outcomes, wtp: float, *, effect: str | None = None) -> pd.DataFrame:
+    """Net health benefit per iteration and strategy: ``effect - cost / wtp``.
+
+    Example:
+        >>> import pandas as pd
+        >>> from heormodel.models import Outcomes
+        >>> from heormodel.cea import nhb
+        >>> c = pd.DataFrame({"A": [100.0]})
+        >>> e = pd.DataFrame({"A": [0.01]})
+        >>> float(nhb(Outcomes.from_wide(c, e), wtp=50_000)["A"][0])
+        0.008
+    """
+    if wtp <= 0:
+        raise ValueError("wtp must be positive for net health benefit.")
+    return outcomes.effects_wide(effect) - outcomes.costs_wide() / wtp
+
+
+def expected_nmb(outcomes: Outcomes, wtp: float, *, effect: str | None = None) -> pd.Series:
+    """Expected (mean over iterations) NMB per strategy.
+
+    Example:
+        >>> import pandas as pd
+        >>> from heormodel.models import Outcomes
+        >>> from heormodel.cea import expected_nmb
+        >>> c = pd.DataFrame({"A": [100.0, 200.0]})
+        >>> e = pd.DataFrame({"A": [0.01, 0.01]})
+        >>> float(expected_nmb(Outcomes.from_wide(c, e), wtp=50_000)["A"])
+        350.0
+    """
+    return nmb(outcomes, wtp, effect=effect).mean(axis=0)

heormodel/dsa/__init__.py

@@ -0,0 +1,18 @@
+"""Deterministic sensitivity analysis (`heval.dsa`).
+
+Where probabilistic analysis answers how uncertain a decision is,
+deterministic sensitivity analysis (DSA) answers which parameters move the
+result and by how much. Both read the same model. This module builds
+scenario designs that run through `heval.run.run_psa` unchanged: a design is
+a draw matrix whose rows are scenarios instead of random draws, paired with a
+descriptor table that names what each scenario varied.
+
+Three builders cover the standard forms. `one_way` sweeps a single parameter
+across a set of values. `one_at_a_time` sweeps each parameter in turn, the
+union of one-way sweeps that feeds a tornado diagram. `grid` takes the full
+factorial of two or more parameters, which feeds a two-way heatmap.
+"""
+
+from heormodel.dsa.design import Design, grid, one_at_a_time, one_way
+
+__all__ = ["Design", "grid", "one_at_a_time", "one_way"]