voiage.analysis module

A module for the core decision analysis interface.

class voiage.analysis.RegressionModelProtocol(*args, **kwargs)[source]

Bases: Protocol

Minimal regression model contract used by EVPPI helpers.

fit(x: ndarray, y: ndarray) → object[source]

Fit the model.

predict(x: ndarray) → ndarray[source]

Predict outputs for the given design matrix.

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

Stateful decision-analysis interface for VOI calculations.

The class wraps a net-benefit surface and optional parameter samples, then exposes the core EVPI/EVPPI/EVSI and downstream analysis methods through a single object. It also manages backend selection, caching, and streaming updates for callers that accumulate data over time.

Parameters:

  • nb_array (numpy.ndarray or ValueArray) – Net-benefit samples with shape (n_samples, n_strategies).

  • parameter_samples (numpy.ndarray, ParameterSet, dict[str, numpy.ndarray], optional) – Optional parameter samples used by EVPPI, EVSI, and related methods.

  • backend (str, optional) – Backend name to use. If omitted, the backend is auto-detected.

  • use_jit (bool, default=False) – Enable JAX JIT compilation where available.

  • streaming_window_size (int, optional) – If provided, enable rolling-window buffering for incremental updates.

  • enable_caching (bool, default=False) – Cache intermediate results when repeated calculations are expected.

nb_array

Normalized net-benefit container used by the analysis methods.

Type:

ValueArray

parameter_samples

Normalized parameter samples, or None if the analysis is net-benefit only.

Type:

ParameterSet or None

backend

Selected computational backend implementation.

Type:

object

use_jit

Whether JAX JIT compilation is enabled.

Type:

bool

streaming_window_size

Size of the streaming buffer, if enabled.

Type:

int or None

enable_caching

Whether the instance cache is active.

Type:

bool

Examples

>>> import numpy as np
>>> from voiage.analysis import DecisionAnalysis
>>> analysis = DecisionAnalysis(np.array([[10.0, 12.0], [11.0, 9.5]]))
>>> round(analysis.evpi(), 2)
1.0
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]

Yield EVPI repeatedly for the current data state.

Yields:

float – EVPI value calculated from the current buffered data.

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

Yield EVPPI repeatedly for the current data state.

Yields:

float – EVPPI value calculated from the current buffered data.

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

Calculate expected value of perfect information.

Parameters:

  • population (float, optional) – Population size for population-scaled EVPI.

  • time_horizon (float, optional) – Time horizon in years for population scaling.

  • discount_rate (float, optional) – Annual discount rate used for population scaling.

  • chunk_size (int, optional) – Optional chunk size for incremental computation.

Returns:

Per-decision EVPI unless population scaling is requested.

Return type:

float

Notes

EVPI is computed as \(E[\\max_d NB_d] - \\max_d E[NB_d]\).

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

Compatibility wrapper around evpi().

Parameters:

  • population (float, optional) – Population size for population scaling.

  • time_horizon (float, optional) – Time horizon in years for population scaling.

  • discount_rate (float, optional) – Annual discount rate used for population scaling.

  • chunk_size (int, optional) – Optional chunk size for incremental computation.

Returns:

EVPI value returned by evpi().

Return type:

float

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

Calculate expected value of partial perfect information.

Parameters:

  • parameters_of_interest (list[str], optional) – Parameter names to analyze. Defaults to all parameters.

  • population (float, optional) – Population size for population scaling.

  • time_horizon (float, optional) – Time horizon in years for population scaling.

  • discount_rate (float, optional) – Annual discount rate used for population scaling.

  • n_regression_samples (int, optional) – Number of samples used to fit the regression approximation.

  • regression_model (RegressionModelProtocol or type, optional) – Optional scikit-learn-compatible regression model.

  • chunk_size (int, optional) – Optional chunk size for incremental computation of the baseline term.

Returns:

Per-decision EVPPI unless population scaling is requested.

Return type:

float

Notes

EVPPI is computed by regressing net benefit on the parameters of interest and comparing the conditional and unconditional maxima.

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 expected net benefit of sampling.

Parameters:

  • research_cost (float) – Total cost of the proposed research study.

  • strategy_of_interest (int or str, optional) – Optional strategy selector for downstream decision reporting.

  • population (float, optional) – Population size for population scaling.

  • time_horizon (float, optional) – Time horizon in years for population scaling.

  • discount_rate (float, optional) – Annual discount rate used for population scaling.

Returns:

ENBS value, clipped at zero, unless population scaling is requested.

Return type:

float

ceaf(wtp_thresholds: Sequence[float], strategy_names: Sequence[str] | None = None, confidence_level: float = 0.95) → Any[source]

Calculate the cost-effectiveness acceptability frontier.

Parameters:

  • wtp_thresholds (sequence of float) – Willingness-to-pay thresholds to evaluate.

  • strategy_names (sequence of str, optional) – Optional strategy labels.

  • confidence_level (float, default=0.95) – Confidence level used to build the probability band.

Returns:

CEAF result from voiage.methods.ceaf.calculate_ceaf().

Return type:

object

dominance(costs: Sequence[float], effects: Sequence[float], strategy_names: Sequence[str] | None = None) → Any[source]

Calculate strong and extended dominance for cost/effect pairs.

Parameters:

  • costs (sequence of float) – Strategy costs.

  • effects (sequence of float) – Strategy effects.

  • strategy_names (sequence of str, optional) – Optional strategy labels.

Returns:

Dominance result from voiage.methods.dominance.calculate_dominance().

Return type:

object

value_of_heterogeneity(subgroups: Sequence[object], strategy_names: Sequence[str] | None = None, n_bins: int | None = None) → Any[source]

Calculate the value of subgroup-specific decisions.

Parameters:

  • subgroups (sequence of object) – Subgroup label for each sample.

  • strategy_names (sequence of str, optional) – Optional strategy labels.

  • n_bins (int, optional) – Quantile bin count for numeric subgroup values.

Returns:

Heterogeneity result from voiage.methods.heterogeneity.value_of_heterogeneity().

Return type:

object

value_of_distributional_equity(subgroups: Sequence[object], strategy_names: Sequence[str] | None = None, equity_weights: Sequence[float] | dict[str, float] | None = None, n_bins: int | None = None) → Any[source]

Calculate the value of distributional and equity-weighted decision tailoring.

value_of_implementation(uptake: float = 1.0, adherence: float = 1.0, coverage: float = 1.0, implementation_delay: float = 0.0, implementation_uncertainty: float = 0.0, discount_rate: float = 0.0, time_horizon: float | None = None, population: float | None = None, strategy_names: Sequence[str] | None = None) → Any[source]

Calculate implementation-adjusted VOI summaries.

value_of_perspective(perspectives: Any | None = None, strategy_names: Sequence[str] | None = None, perspective_names: Sequence[str] | None = None, perspective_weights: Sequence[float] | dict[str, float] | None = None, reference_perspective: str | int | None = None) → Any[source]

Compare decision value across multiple perspectives.

Parameters:

  • perspectives (PerspectiveSet or sequence, optional) – Ordered perspective metadata or perspective identifiers.

  • strategy_names (sequence of str, optional) – Optional strategy labels.

  • perspective_names (sequence of str, optional) – Optional perspective labels when full metadata is not provided.

  • perspective_weights (sequence or dict, optional) – Non-negative weights used for consensus and switching-value summaries.

  • reference_perspective (str or int, optional) – Reference perspective used for switching-value summaries.

Returns:

Result from voiage.methods.perspective.value_of_perspective().

Return type:

object

value_of_preference(preference_profiles: Any | None = None, strategy_names: Sequence[str] | None = None, preference_profile_names: Sequence[str] | None = None, preference_profile_weights: Sequence[float] | dict[str, float] | None = None, reference_preference_profile: str | int | None = None, analysis_id: str | None = None, decision_problem_id: str | None = None, decision_context: str | None = None) → Any[source]

Compare decision value across multiple preference profiles.

value_of_model_validation(validation_profiles: Any | None = None, strategy_names: Sequence[str] | None = None, validation_profile_names: Sequence[str] | None = None, validation_profile_weights: Sequence[float] | dict[str, float] | None = None, reference_validation_profile: str | int | None = None, analysis_id: str | None = None, decision_problem_id: str | None = None, decision_context: str | None = None) → Any[source]

Compare decision value across multiple validation profiles.

value_of_threshold_information(threshold_profiles: Any | None = None, strategy_names: Sequence[str] | None = None, threshold_profile_names: Sequence[str] | None = None, threshold_profile_weights: Sequence[float] | dict[str, float] | None = None, reference_threshold_profile: str | int | None = None, analysis_id: str | None = None, decision_problem_id: str | None = None, decision_context: str | None = None) → Any[source]

Compare decision value across multiple threshold profiles.

portfolio_voi(portfolio_specification: PortfolioSpec, study_value_calculator: Callable[[PortfolioStudy], float], optimization_method: str = 'greedy', **kwargs: object) → dict[str, object][source]

Optimize a research portfolio from the analysis surface.

Parameters:

  • portfolio_specification (PortfolioSpec) – Portfolio definition to optimize.

  • study_value_calculator (callable) – Study value function used for ranking.

  • optimization_method (str, default="greedy") – Portfolio optimization algorithm.

  • **kwargs (object) – Additional algorithm-specific options.

Returns:

Portfolio optimization result.

Return type:

dict[str, object]

get_decision_recommendations() → list[dict[str, Any]][source]

Summarize the strategies with the highest expected net benefit.

Returns:

Ranked strategy recommendations with mean net benefit and rank.

Return type:

list[dict[str, Any]]