Skip to content

tucoopy.diagnostics.imputation_diagnostics

Imputation and pre-imputation diagnostics.

This module provides checks for whether a payoff vector is:

  • efficient (pre-imputation), and
  • individually rational (imputation).

It is used both directly and as a building block for higher-level set diagnostics.

Examples:

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.imputation_diagnostics import imputation_diagnostics
>>> g = Game.from_coalitions(n_players=2, values={0: 0, 3: 1})
>>> imputation_diagnostics(g, [0.5, 0.5]).in_set
True

ImputationDiagnostics dataclass

Diagnostics for membership in the imputation set.

Examples:

>>> from tucoopy.diagnostics.bounds import BoundViolation
>>> d = ImputationDiagnostics(
...     n_players=2,
...     vN=1.0,
...     sum_x=1.0,
...     efficient=True,
...     in_set=True,
...     lower_bounds=[0.0, 0.0],
...     violations=[],
... )
>>> d.in_set
True

to_dict 

to_dict()

Convert diagnostics to a JSON-serializable dictionary.

Examples:

>>> d = ImputationDiagnostics(
...     n_players=2,
...     vN=1.0,
...     sum_x=1.0,
...     efficient=True,
...     in_set=True,
...     lower_bounds=[0.0, 0.0],
...     violations=[],
... )
>>> d.to_dict()["sum_x"]
1.0

imputation_diagnostics 

imputation_diagnostics(
    game, x, *, tol=DEFAULT_GEOMETRY_TOL
)

Check whether \(x\) is an imputation (efficient + individually rational).

Parameters:

Name Type Description Default
game GameProtocol

TU game.

 required
x list[float]

Allocation vector of length game.n_players.

 required
tol float

Numerical tolerance used for the efficiency check and the individual rationality comparisons.

 DEFAULT_GEOMETRY_TOL

Returns:

Type Description
ImputationDiagnostics

Diagnostics object including in_set and any lower-bound violations.

Raises:

Type Description
InvalidParameterError

If x does not have length game.n_players.

Examples:

A minimal 3-player example (only the grand coalition has value 1):

>>> from tucoopy import Game
>>> from tucoopy.diagnostics.imputation_diagnostics import imputation_diagnostics
>>> g = Game.from_coalitions(n_players=3, values={
...     0:0, 1:0, 2:0, 4:0,
...     3:0, 5:0, 6:0,
...     7:1,
... })
>>> d = imputation_diagnostics(g, [1/3, 1/3, 1/3])
>>> d.in_set
True