Skip to content
voiage

voiage.methods.perspective.value_of_perspective

value_of_perspective

Section titled “value_of_perspective”
value_of_perspective([positional or keyword] net_benefits: ValueArray | np.ndarray = None, [positional or keyword] perspectives: PerspectiveSet | Sequence[Perspective | str] | 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] | Mapping[str, float] | None = None, [positional or keyword] reference_perspective: str | int | None = None, [positional or keyword] tie_policy: str = 'first', [positional or keyword] tie_tolerance: float = 1e-12) -> ValueOfPerspectiveResult

Compare decision value across multiple perspectives.

Parameters

Section titled “Parameters”

net_benefits : ValueArray or numpy.ndarray Net-benefit samples with shape (n_samples, n_strategies, n_perspectives). perspectives : PerspectiveSet or sequence, optional Ordered perspective metadata. Plain strings are interpreted as perspective ids. strategy_names : sequence of str, optional Strategy labels. perspective_names : sequence of str, optional Perspective labels used when perspectives is omitted. perspective_weights : sequence or mapping, optional Non-negative normative stakeholder-importance weights used for consensus and weighted switching value. They are not probabilities over which perspective is true. Mappings must be keyed by perspective id. reference_perspective : str or int, optional Perspective whose optimal strategy is used as the reference decision rule. Defaults to the first perspective.

Returns

Section titled “Returns”

ValueOfPerspectiveResult Perspective-specific optima, regret matrix, switching values, consensus and robust strategies, and Pareto strategy set.

Notes

Section titled “Notes”

The perspective-specific optimum is

.. math::

d^*p = \arg\max_d E[NB{d,p}].

The reported switching value compares the reference perspective’s optimal strategy with each perspective’s own optimum, and the returned value is the weighted average of those switching values.

tie_policy="split" is a reporting diagnostic: tied optimal strategies are averaged to summarize regret and does not claim that an executable randomized policy was deployed. The returned normal 1.96 intervals are exploratory plug-in intervals and require finite-sample/model assumptions before scientific interpretation.

References

Section titled “References”

Voiage contributors. Value of Perspective frontier contract and analysis notes, including the proof-of-concept preprint linked from the project documentation. Keeney, R. L., & Raiffa, H. (1993). Decisions with Multiple Objectives.

Examples

Section titled “Examples”

>>> import numpy as np >>> from voiage.analysis import DecisionAnalysis >>> from voiage.schema import ValueArray >>> values = np.array( … [ … [[10.0, 7.0], [8.0, 11.0]], … [[11.0, 8.0], [9.0, 10.0]], … ] … ) >>> result = DecisionAnalysis( … ValueArray.from_numpy_perspectives( … values, … strategy_names=[“A”, “B”], … perspective_names=[“payer”, “societal”], … ) … ).value_of_perspective() >>> result.reference_perspective_id ‘payer’

Parameters:

  • net_benefits ValueArray | np.ndarray
  • perspectives PerspectiveSet | Sequence[Perspective | str] | None (default: None)
  • strategy_names Sequence[str] | None (default: None)
  • perspective_names Sequence[str] | None (default: None)
  • perspective_weights Sequence[float] | Mapping[str, float] | None (default: None)
  • reference_perspective str | int | None (default: None)
  • tie_policy str (default: 'first')
  • tie_tolerance float (default: 1e-12)

Returns: ValueOfPerspectiveResult