Skip to content
voiage

voiage.methods.preference.value_of_preference

value_of_preference

Section titled “value_of_preference”
value_of_preference([positional or keyword] net_benefits: ValueArray | np.ndarray = None, [positional or keyword] preference_profiles: PreferenceProfileSet | Sequence[PreferenceProfile | str] | 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] | Mapping[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) -> PreferenceHeterogeneityResult

Compare decision value across multiple preference profiles.

Parameters

Section titled “Parameters”

net_benefits : ValueArray or numpy.ndarray Net-benefit samples with shape (n_samples, n_strategies, n_preference_profiles). preference_profiles : PreferenceProfileSet or sequence, optional Ordered preference-profile metadata. Plain strings are interpreted as preference-profile ids. strategy_names : sequence of str, optional Strategy labels. preference_profile_names : sequence of str, optional Preference-profile labels used when preference_profiles is omitted. preference_profile_weights : sequence or mapping, optional Non-negative weights used for consensus and weighted switching value. Mappings must be keyed by profile id. reference_preference_profile : str or int, optional Preference profile whose optimal strategy is used as the reference decision rule. Defaults to the first profile.

Returns

Section titled “Returns”

PreferenceHeterogeneityResult Profile-specific optima, regret matrix, switching values, consensus and robust strategies, Pareto strategy set, and individualized-care summary.

Notes

Section titled “Notes”

The profile-specific optimum is

.. math::

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

The reported switching value compares the reference profile’s optimal strategy with each profile’s own optimum, and the returned value is the weighted average of those switching values. The individualized-care value compares the same profile-specific optima with a single consensus strategy.

Examples

Section titled “Examples”

>>> import numpy as np >>> from voiage.analysis import DecisionAnalysis >>> values = np.array( … [ … [[10.0, 7.0], [8.0, 11.0], [5.0, 9.0]], … [[10.0, 7.0], [8.0, 11.0], [5.0, 9.0]], … ] … ) >>> result = DecisionAnalysis(values).value_of_preference( … preference_profile_names=[“access_first”, “outcomes_first”], … strategy_names=[“A”, “B”, “C”], … ) >>> result.reference_preference_profile ‘access_first’

Parameters:

  • net_benefits ValueArray | np.ndarray
  • preference_profiles PreferenceProfileSet | Sequence[PreferenceProfile | str] | None (default: None)
  • strategy_names Sequence[str] | None (default: None)
  • preference_profile_names Sequence[str] | None (default: None)
  • preference_profile_weights Sequence[float] | Mapping[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: PreferenceHeterogeneityResult