see evppi() for setup; ranking returns a sorted Series

evppi

voi.evppi

Expected value of partial perfect information via metamodeling.

Uses the nonparametric-regression estimator: regress each intervention’s net benefit on the parameter subset of interest with a flexible metamodel; the fitted values estimate the conditional expected NB given those parameters, and EVPPI is E[max_d g_d(x)] - max_d E[g_d(x)] (Strong, Oakley & Brennan, 2014, Medical Decision Making 34:311-326).

This is where the shared iteration index earns its keep: the regression pairs each outcome row with the parameter draw that produced it.

Functions

Name	Description
evppi	EVPPI for a parameter (or parameter group) at one willingness to pay.
evppi_ranking	Single-parameter EVPPI for each parameter, sorted descending.

evppi

voi.evppi.evppi(
    outcomes,
    draws,
    params,
    wtp,
    *,
    effect=None,
    method='spline',
    n_knots=5,
    degree=3,
    seed=None,
)

EVPPI for a parameter (or parameter group) at one willingness to pay.

Parameters

Name	Type	Description	Default
outcomes	Outcomes	Outcomes from a probabilistic sensitivity analysis.	required
draws	pd.DataFrame	Parameter draw matrix whose index equals the outcomes’ iteration index (the shared-index contract).	required
params	str | Sequence[str]	Column name(s) in draws to value jointly.	required
wtp	float	Willingness to pay per unit of effect.	required
effect	str | None	Effect column (default: the primary effect).	None
method	str	"spline" (default) or "gp" metamodel; see heormodel.voi._metamodel.fitted_conditional_means.	'spline'
n_knots	int	Spline knot count.	5
degree	int	Spline degree.	3
seed	int | None	Subsample seed for the GP method.	None

Returns

Name	Type	Description
	float	The EVPPI estimate (same monetary units as NMB), clipped at zero.

Example

import numpy as np, pandas as pd from heormodel.models import Outcomes from heormodel.voi import evppi rng = np.random.default_rng(0) e_b = rng.normal(0.0, 1.0, 4000) draws = pd.DataFrame({“e_b”: e_b}, … index=pd.RangeIndex(4000, name=“iteration”)) costs = pd.DataFrame({“A”: np.zeros(4000), “B”: np.zeros(4000)}) effects = pd.DataFrame({“A”: np.zeros(4000), “B”: e_b}) out = Outcomes.from_wide(costs, effects) v = evppi(out, draws, “e_b”, wtp=1.0) abs(v - 0.399) < 0.05 # analytic value is 1/sqrt(2*pi) True

evppi_ranking

voi.evppi.evppi_ranking(
    outcomes,
    draws,
    wtp,
    *,
    params=None,
    effect=None,
    method='spline',
    **kwargs,
)

Single-parameter EVPPI for each parameter, sorted descending.

A convenience sweep for prioritising research targets.

Example

evppi_ranking(out, draws, wtp=1.0).index[0]