Skip to content

tucoopy.solutions.owen

Owen value (a priori unions).

The Owen value extends the Shapley value to settings where players are partitioned into unions (blocks) that act as a priori coalitions.

OwenResult dataclass

Result container for the Owen value.

Attributes:

Name Type Description
x list[float]

Allocation vector (length n_players).
meta dict[str, object]

Diagnostic metadata about the computation, including: - number of unions, - configuration parameters.

owen_value 

owen_value(
    game, *, unions, max_players=16, require_complete=True
)

Compute the Owen value for a TU game with a priori unions (coalition structure).

The Owen value extends the Shapley value to games where players are partitioned into predefined groups (unions). It is defined by a two-level random process:

  1. The unions arrive in a random order (Shapley at the union level).
  2. Within each union, players arrive in a random order (Shapley inside the union).

Formally, this results in a weighted sum of marginal contributions where the weights reflect both the order of unions and the order of players within each union.

Parameters:

Name Type Description Default
game GameProtocol

TU game.

 required
unions Sequence[Iterable[int] | int]

Partition of players into disjoint non-empty unions. Each element may be either: - an iterable of player indices, or - a coalition mask. The unions must be disjoint and cover all players.

 required
max_players int

Safety bound. The algorithm is exponential in n_players.

 16
require_complete bool

If True, require the game to specify values for all \(2^n\) coalitions.

 True

Returns:

Type Description
OwenResult

Allocation vector and metadata.

Raises:

Type Description
InvalidParameterError

If: - unions are invalid (not disjoint or not covering all players),
NotSupportedError

If n_players > max_players.
InvalidGameError

If the game is incomplete when require_complete=True.
Notes
  • When there is a single union containing all players, the Owen value reduces to the Shapley value.
  • When each player is its own union, the Owen value also reduces to the Shapley value.
  • The Owen value is central in cooperative games with coalition structures and models situations where cooperation is constrained by pre-existing groups.

Examples:

>>> # Two unions: {0,1} and {2,3}
>>> res = owen_value(g, unions=[[0,1], [2,3]])
>>> res.x