voiage.analysis module

A module for the core decision analysis interface.

class voiage.analysis.DecisionAnalysis(nb_array: ndarray | ValueArray, parameter_samples: ndarray | ParameterSet | Dict[str, ndarray] | None = None, backend: str | None = None, use_jit: bool = False, streaming_window_size: int | None = None, enable_caching: bool = False)[source]

Bases: object

A class to represent a decision analysis problem.

update_with_new_data(new_nb_data: ndarray | ValueArray, new_parameter_samples: ndarray | ParameterSet | Dict[str, ndarray] | None = None) → None[source]

Update the decision analysis with new data for streaming VOI calculations.

Parameters:

  • new_nb_data – New net benefit data to add

  • new_parameter_samples – New parameter samples corresponding to the net benefit data

streaming_evpi() → Generator[float, None, None][source]

Calculate EVPI continuously as new data arrives.

Yields:

float (EVPI value calculated with current data)

streaming_evppi() → Generator[float, None, None][source]

Calculate EVPPI continuously as new data arrives.

Yields:

float (EVPPI value calculated with current data)

evpi(population: float | None = None, time_horizon: float | None = None, discount_rate: float | None = None, chunk_size: int | None = None) → float[source]

Calculate the Expected Value of Perfect Information (EVPI).

EVPI = E[max(NB)] - max(E[NB]) where E is the expectation over the PSA samples.

Parameters:

  • population (Optional[float]) – The relevant population size. If provided along with time_horizon, EVPI will be scaled to population level.

  • time_horizon (Optional[float]) – The relevant time horizon in years. If provided along with population, EVPI will be scaled.

  • discount_rate (Optional[float]) – The annual discount rate (e.g., 0.03 for 3%). Used for population scaling. Defaults to 0 if population and time_horizon are provided but discount_rate is not.

  • chunk_size (Optional[int]) – Size of chunks for incremental computation. If provided, data will be processed in chunks to reduce memory usage. Useful for large datasets.

Returns:

float – returns population-adjusted EVPI, otherwise per-decision EVPI.

Return type:

The calculated EVPI. If population parameters are provided,

Raises:

  • InputError – If inputs are invalid (e.g., wrong types, shapes, values).:

  • DimensionMismatchError – If nb_array does not have 2 dimensions.:

  • CalculationError – For issues during calculation.:

evppi(parameters_of_interest: list[str], population: float | None = None, time_horizon: float | None = None, discount_rate: float | None = None, n_regression_samples: int | None = None, regression_model: Any | None = None, chunk_size: int | None = None) → float[source]

Calculate the Expected Value of Partial Perfect Information (EVPPI).

EVPPI quantifies the value of learning the true value of a specific subset of model parameters. It is typically calculated using a regression-based approach (e.g., Strong & Oakley).

EVPPI = E_p [max_d E[NB_d|p]] - max_d E[NB_d] where E_p is the expectation over the parameter(s) of interest, and E[NB_d|p] is the expected net benefit of strategy d conditional on the parameter(s) p, usually estimated via regression.

Parameters:

  • parameters_of_interest (list[str]) – List of parameter names to analyze.

  • population (Optional[float]) – Population size for scaling.

  • time_horizon (Optional[float]) – Time horizon for scaling.

  • discount_rate (Optional[float]) – Discount rate for scaling.

  • n_regression_samples (Optional[int]) – Number of samples to use for fitting the regression model. If None, all samples are used. Useful for large datasets to speed up computation, at the cost of precision.

  • regression_model (Optional[Any]) – An unfitted scikit-learn compatible regression model. If None, defaults to sklearn.linear_model.LinearRegression.

  • chunk_size (Optional[int]) – Size of chunks for incremental computation of the second term (max_d E[NB_d]). If provided, data will be processed in chunks to reduce memory usage. Useful for large datasets.

Returns:

float

Return type:

The calculated EVPPI. Scaled if population args are provided.

Raises:

  • InputError – For invalid inputs.:

  • DimensionMismatchError – If array dimensions are inconsistent.:

  • OptionalDependencyError – If scikit-learn is not installed.:

  • CalculationError – For issues during calculation.:

enbs(research_cost: float, strategy_of_interest: int | str | None = None, population: float | None = None, time_horizon: float | None = None, discount_rate: float | None = None) → float[source]

Calculate the Expected Net Benefit of Sampling (ENBS).

ENBS represents the expected benefit of conducting a new study to reduce uncertainty before making a decision. It is calculated as the difference between the Expected Value of Sample Information (EVSI) and the cost of conducting the research.

ENBS = EVSI - research_cost ENBS = max(0, ENBS) # Cannot be negative (won’t conduct research if it costs more than it’s worth)

Parameters:

  • research_cost (float) – Cost of conducting the research study.

  • strategy_of_interest (Optional[Union[int, str]]) – Specific strategy to analyze. If int, uses that strategy index. If str, uses strategy name. If None, uses the strategy with maximum expected net benefit.

  • population (Optional[float]) – Population size for scaling.

  • time_horizon (Optional[float]) – Time horizon for scaling.

  • discount_rate (Optional[float]) – Discount rate for scaling.

Returns:

float – Scaled if population arguments are provided.

Return type:

The calculated ENBS. Returns 0 if ENBS would be negative.

Raises:

  • InputError – For invalid inputs.:

  • DimensionMismatchError – If array dimensions are inconsistent.:

  • CalculationError – For issues during calculation.: