voiage.analysis.DecisionAnalysis

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.

Attributes

nb_array : ValueArray Normalized net-benefit container used by the analysis methods. parameter_samples : ParameterSet or None Normalized parameter samples, or None if the analysis is net-benefit only. backend : object Selected computational backend implementation. use_jit : bool Whether JAX JIT compilation is enabled. streaming_window_size : int or None Size of the streaming buffer, if enabled. enable_caching : bool Whether the instance cache is active.

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

Methods

update_with_new_data

update_with_new_data([positional or keyword] self: None = None, [positional or keyword] new_nb_data: np.ndarray | ValueArray = None, [positional or keyword] new_parameter_samples: np.ndarray | ParameterSet | dict[str, np.ndarray] | None = None) -> None

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

Args: new_nb_data: New net benefit data to add new_parameter_samples: New parameter samples corresponding to the net benefit data

Parameters:

• self
• new_nb_data np.ndarray | ValueArray
• new_parameter_samples np.ndarray | ParameterSet | dict[str, np.ndarray] | None (default: None)

Returns: None

expected_utility_information

expected_utility_information([positional or keyword] self: None = None, [positional or keyword] request: Mapping[str, object] = None) -> dict[str, object]

Run the experimental Rust expected-utility information contract.

The request must identify finite states and probabilities explicitly; rows in the analysis PSA array are not silently reinterpreted as a decision-maker’s state distribution.

Parameters:

• self
• request Mapping[str, object]

Returns: dict[str, object]

streaming_evpi

streaming_evpi([positional or keyword] self: None = None) -> Generator[float, None, None]

Yield EVPI repeatedly for the current data state.

Yields

float EVPI value calculated from the current buffered data.

Parameters:

• self

Returns: Generator[float, None, None]

streaming_evppi

streaming_evppi([positional or keyword] self: None = None) -> Generator[float, None, None]

Yield EVPPI repeatedly for the current data state.

Yields

float EVPPI value calculated from the current buffered data.

Parameters:

• self

Returns: Generator[float, None, None]

evpi

evpi([positional or keyword] self: None = None, [positional or keyword] population: float | None = None, [positional or keyword] time_horizon: float | None = None, [positional or keyword] discount_rate: float | None = None, [positional or keyword] chunk_size: int | None = None) -> float

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

float Per-decision EVPI unless population scaling is requested.

Notes

EVPI is computed as :math:E[\\max_d NB_d] - \\max_d E[NB_d].

Parameters:

• self
• population float | None (default: None)
• time_horizon float | None (default: None)
• discount_rate float | None (default: None)
• chunk_size int | None (default: None)

Returns: float

calculate_evpi

calculate_evpi([positional or keyword] self: None = None, [positional or keyword] population: float | None = None, [positional or keyword] time_horizon: float | None = None, [positional or keyword] discount_rate: float | None = None, [positional or keyword] chunk_size: int | None = None) -> float

Compatibility wrapper around :meth: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

float EVPI value returned by :meth:evpi.

Parameters:

• self
• population float | None (default: None)
• time_horizon float | None (default: None)
• discount_rate float | None (default: None)
• chunk_size int | None (default: None)

Returns: float

evppi

evppi([positional or keyword] self: None = None, [positional or keyword] parameters_of_interest: list[str] | None = None, [positional or keyword] population: float | None = None, [positional or keyword] time_horizon: float | None = None, [positional or keyword] discount_rate: float | None = None, [positional or keyword] n_regression_samples: int | None = None, [positional or keyword] regression_model: RegressionModelProtocol | type[RegressionModelProtocol] | None = None, [positional or keyword] chunk_size: int | None = None) -> float

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

float Per-decision EVPPI unless population scaling is requested.

Notes

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

Parameters:

• self
• parameters_of_interest list[str] | None (default: None)
• population float | None (default: None)
• time_horizon float | None (default: None)
• discount_rate float | None (default: None)
• n_regression_samples int | None (default: None)
• regression_model RegressionModelProtocol | type[RegressionModelProtocol] | None (default: None)
• chunk_size int | None (default: None)

Returns: float

enbs

enbs([positional or keyword] self: None = None, [positional or keyword] evsi_result: float = None, [positional or keyword] research_cost: float = None, [positional or keyword] population: float | None = None, [positional or keyword] time_horizon: float | None = None, [positional or keyword] discount_rate: float | None = None) -> float

Calculate expected net benefit of sampling.

Parameters

evsi_result : float Expected value of sample information for the proposed study, per decision and per period when population scaling is requested. research_cost : float Total cost of the proposed research study. population : float, optional Recurring population or decision opportunities per period. time_horizon : float, optional Time horizon in years for population scaling. discount_rate : float, optional Annual discount rate used for population scaling.

Returns

float Signed ENBS. A negative result means the proposed study costs more than its expected information value.

Notes

Population scaling is applied to EVSI before the total research cost is subtracted. The method therefore implements scaled EVSI - total research cost rather than scaling study cost.

Parameters:

• self
• evsi_result float
• research_cost float
• population float | None (default: None)
• time_horizon float | None (default: None)
• discount_rate float | None (default: None)

Returns: float

ceaf

ceaf([positional or keyword] self: None = None, [positional or keyword] wtp_thresholds: Sequence[float] = None, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] confidence_level: float = 0.95) -> Any

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

object CEAF result from :func:voiage.methods.ceaf.calculate_ceaf.

Parameters:

• self
• wtp_thresholds Sequence[float]
• strategy_names Sequence[str] | None (default: None)
• confidence_level float (default: 0.95)

Returns: Any

dominance

dominance([positional or keyword] self: None = None, [positional or keyword] costs: Sequence[float] = None, [positional or keyword] effects: Sequence[float] = None, [positional or keyword] strategy_names: Sequence[str] | None = None) -> Any

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

object Dominance result from :func:voiage.methods.dominance.calculate_dominance.

Parameters:

• self
• costs Sequence[float]
• effects Sequence[float]
• strategy_names Sequence[str] | None (default: None)

Returns: Any

value_of_heterogeneity

value_of_heterogeneity([positional or keyword] self: None = None, [positional or keyword] subgroups: Sequence[object] = None, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] n_bins: int | None = None) -> Any

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

object Heterogeneity result from :func:voiage.methods.heterogeneity.value_of_heterogeneity.

Parameters:

• self
• subgroups Sequence[object]
• strategy_names Sequence[str] | None (default: None)
• n_bins int | None (default: None)

Returns: Any

value_of_distributional_equity

value_of_distributional_equity([positional or keyword] self: None = None, [positional or keyword] subgroups: Sequence[object] = None, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] equity_weights: Sequence[float] | dict[str, float] | None = None, [positional or keyword] n_bins: int | None = None) -> Any

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

Parameters:

• self
• subgroups Sequence[object]
• strategy_names Sequence[str] | None (default: None)
• equity_weights Sequence[float] | dict[str, float] | None (default: None)
• n_bins int | None (default: None)

Returns: Any

value_of_ambiguity_distribution_shift

value_of_ambiguity_distribution_shift([positional or keyword] self: None = None, [positional or keyword] shift_weights: Sequence[Sequence[float]] = None, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] scenario_names: Sequence[str] | None = None, [positional or keyword] scenario_probabilities: Sequence[float] | None = None, [positional or keyword] ambiguity_radius: float = 0.0, [positional or keyword] information_cost: float = 0.0) -> Any

Calculate robust VOI under ambiguity and distribution shift.

Parameters:

• self
• shift_weights Sequence[Sequence[float]]
• strategy_names Sequence[str] | None (default: None)
• scenario_names Sequence[str] | None (default: None)
• scenario_probabilities Sequence[float] | None (default: None)
• ambiguity_radius float (default: 0.0)
• information_cost float (default: 0.0)

Returns: Any

value_of_adaptive_learning_bandit

value_of_adaptive_learning_bandit([positional or keyword] self: None = None, [positional or keyword] policy: str = 'ucb', [positional or keyword] horizon: int | None = None, [positional or keyword] exploration_cost: float = 0.0, [positional or keyword] epsilon: float = 0.1, [positional or keyword] confidence: float = 2.0, [positional or keyword] stop_regret: float | None = None, [positional or keyword] arm_names: Sequence[str] | None = None, [positional or keyword] seed: int = 0) -> Any

Calculate fixture-backed value of adaptive bandit learning.

Parameters:

• self
• policy str (default: 'ucb')
• horizon int | None (default: None)
• exploration_cost float (default: 0.0)
• epsilon float (default: 0.1)
• confidence float (default: 2.0)
• stop_regret float | None (default: None)
• arm_names Sequence[str] | None (default: None)
• seed int (default: 0)

Returns: Any

value_of_capacity_budget_constrained

value_of_capacity_budget_constrained([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate value of information under resource constraints.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_ai_assisted_evidence_triage

value_of_ai_assisted_evidence_triage([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate the decision value of human-in-the-loop evidence triage.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_federated_privacy_preserving

value_of_federated_privacy_preserving([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate site-local evidence under privacy-preserving aggregation.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_explainability_transparency

value_of_explainability_transparency([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate adoption and governance value of transparent explanations.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_interoperability_standardization

value_of_interoperability_standardization([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate harmonization and cross-site evidence reuse value.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_regulatory_market_access

value_of_regulatory_market_access([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate regulatory approval, reimbursement, and access value.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_replication_reproducibility

value_of_replication_reproducibility([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate replication and reproducibility information value.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_evidence_obsolescence_refresh

value_of_evidence_obsolescence_refresh([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate evidence obsolescence and refresh information value.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_strategic_behavior

value_of_strategic_behavior([positional or keyword] self: None = None, [variadic keyword] kwargs: object = {}) -> object

Evaluate strategic behavior and game-theoretic information value.

Parameters:

• self
• kwargs object (default: {})

Returns: object

value_of_equity_information

value_of_equity_information([positional or keyword] self: None = None, [positional or keyword] subgroups: Sequence[object] = None, [positional or keyword] equity_weights: Sequence[float] = None, [positional or keyword] resolved_equity_weights: Sequence[Sequence[float]] = None, [positional or keyword] scenario_probabilities: Sequence[float] | None = None, [positional or keyword] information_cost: float = 0.0, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] policy_strata: Sequence[str] | None = None) -> Any

Calculate the value of resolving equity-relevant uncertainty.

Parameters:

• self
• subgroups Sequence[object]
• equity_weights Sequence[float]
• resolved_equity_weights Sequence[Sequence[float]]
• scenario_probabilities Sequence[float] | None (default: None)
• information_cost float (default: 0.0)
• strategy_names Sequence[str] | None (default: None)
• policy_strata Sequence[str] | None (default: None)

Returns: Any

value_of_implementation

value_of_implementation([positional or keyword] self: None = None, [positional or keyword] uptake: float = 1.0, [positional or keyword] adherence: float = 1.0, [positional or keyword] coverage: float = 1.0, [positional or keyword] implementation_delay: float = 0.0, [positional or keyword] implementation_uncertainty: float = 0.0, [positional or keyword] discount_rate: float = 0.0, [positional or keyword] time_horizon: float | None = None, [positional or keyword] population: float | None = None, [positional or keyword] strategy_names: Sequence[str] | None = None) -> Any

Calculate implementation-adjusted VOI summaries.

Parameters:

• self
• uptake float (default: 1.0)
• adherence float (default: 1.0)
• coverage float (default: 1.0)
• implementation_delay float (default: 0.0)
• implementation_uncertainty float (default: 0.0)
• discount_rate float (default: 0.0)
• time_horizon float | None (default: None)
• population float | None (default: None)
• strategy_names Sequence[str] | None (default: None)

Returns: Any

value_of_perspective

value_of_perspective([positional or keyword] self: None = None, [positional or keyword] perspectives: Any | None = None, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] perspective_names: Sequence[str] | None = None, [positional or keyword] perspective_weights: Sequence[float] | dict[str, float] | None = None, [positional or keyword] reference_perspective: str | int | None = None) -> Any

Compare decision value across multiple perspectives.

Parameters

perspectives : :class:~voiage.methods.perspective.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

object Result from :func:voiage.methods.perspective.value_of_perspective.

Parameters:

• self
• perspectives Any | None (default: None)
• strategy_names Sequence[str] | None (default: None)
• perspective_names Sequence[str] | None (default: None)
• perspective_weights Sequence[float] | dict[str, float] | None (default: None)
• reference_perspective str | int | None (default: None)

Returns: Any

value_of_preference

value_of_preference([positional or keyword] self: None = None, [positional or keyword] preference_profiles: Any | None = None, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] preference_profile_names: Sequence[str] | None = None, [positional or keyword] preference_profile_weights: Sequence[float] | dict[str, float] | None = None, [positional or keyword] reference_preference_profile: str | int | None = None, [positional or keyword] analysis_id: str | None = None, [positional or keyword] decision_problem_id: str | None = None, [positional or keyword] decision_context: str | None = None) -> Any

Compare decision value across multiple preference profiles.

Parameters:

• self
• preference_profiles Any | None (default: None)
• strategy_names Sequence[str] | None (default: None)
• preference_profile_names Sequence[str] | None (default: None)
• preference_profile_weights Sequence[float] | dict[str, float] | None (default: None)
• reference_preference_profile str | int | None (default: None)
• analysis_id str | None (default: None)
• decision_problem_id str | None (default: None)
• decision_context str | None (default: None)

Returns: Any

value_of_model_validation

value_of_model_validation([positional or keyword] self: None = None, [positional or keyword] validation_profiles: Any | None = None, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] validation_profile_names: Sequence[str] | None = None, [positional or keyword] validation_profile_weights: Sequence[float] | dict[str, float] | None = None, [positional or keyword] reference_validation_profile: str | int | None = None, [positional or keyword] analysis_id: str | None = None, [positional or keyword] decision_problem_id: str | None = None, [positional or keyword] decision_context: str | None = None) -> Any

Compare decision value across multiple validation profiles.

Parameters:

• self
• validation_profiles Any | None (default: None)
• strategy_names Sequence[str] | None (default: None)
• validation_profile_names Sequence[str] | None (default: None)
• validation_profile_weights Sequence[float] | dict[str, float] | None (default: None)
• reference_validation_profile str | int | None (default: None)
• analysis_id str | None (default: None)
• decision_problem_id str | None (default: None)
• decision_context str | None (default: None)

Returns: Any

value_of_threshold_information

value_of_threshold_information([positional or keyword] self: None = None, [positional or keyword] threshold_profiles: Any | None = None, [positional or keyword] strategy_names: Sequence[str] | None = None, [positional or keyword] threshold_profile_names: Sequence[str] | None = None, [positional or keyword] threshold_profile_weights: Sequence[float] | dict[str, float] | None = None, [positional or keyword] reference_threshold_profile: str | int | None = None, [positional or keyword] analysis_id: str | None = None, [positional or keyword] decision_problem_id: str | None = None, [positional or keyword] decision_context: str | None = None) -> Any

Compare decision value across multiple threshold profiles.

Parameters:

• self
• threshold_profiles Any | None (default: None)
• strategy_names Sequence[str] | None (default: None)
• threshold_profile_names Sequence[str] | None (default: None)
• threshold_profile_weights Sequence[float] | dict[str, float] | None (default: None)
• reference_threshold_profile str | int | None (default: None)
• analysis_id str | None (default: None)
• decision_problem_id str | None (default: None)
• decision_context str | None (default: None)

Returns: Any

portfolio_voi

portfolio_voi([positional or keyword] self: None = None, [positional or keyword] portfolio_specification: PortfolioSpec = None, [positional or keyword] study_value_calculator: Callable[[PortfolioStudy], float] = None, [positional or keyword] optimization_method: str = 'greedy', [variadic keyword] kwargs: object = {}) -> dict[str, object]

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

dict[str, object] Portfolio optimization result.

Parameters:

• self
• portfolio_specification PortfolioSpec
• study_value_calculator Callable[[PortfolioStudy], float]
• optimization_method str (default: 'greedy')
• kwargs object (default: {})

Returns: dict[str, object]

get_decision_recommendations

get_decision_recommendations([positional or keyword] self: None = None) -> list[dict[str, Any]]

Summarize the strategies with the highest expected net benefit.

Returns

list[dict[str, Any]] Ranked strategy recommendations with mean net benefit and rank.

Parameters:

• self

Returns: list[dict[str, Any]]