Skip to content

tucoopy.viz.mpl2

Matplotlib helpers for 2-player games (2D segment plots).

This module provides a small, static visualization for \(n=2\) TU games in the allocation plane \((x_1, x_2)\):

  • draws the imputation set and the core as line segments,
  • overlays point solutions (e.g. Shapley, Banzhaf, tau) and custom points,
  • can read either a tucoopy.base.game.Game directly or a spec-like dict (compatible with the JSON contract used by the JS demo).
Warnings
  • This module depends on Matplotlib at runtime. Install it with pip install "tucoopy[viz]".
  • If Matplotlib is not installed, calling any plotting function will raise a MissingOptionalDependencyError.

plot_segment 

plot_segment(
    game,
    *,
    points=None,
    points_by_label=None,
    point_sets=None,
    sets_vertices=None,
    show_imputation=True,
    show_core=True,
    ax=None,
)

Plot the 2-player (\(n=2\)) imputation set and core as line segments in \((x_1,x_2)\).

Parameters:

Name Type Description Default
game GameProtocol

TU game with n_players=2.

 required
points Sequence[Sequence[float]] | None

Optional list of allocations to plot on top.

 None
points_by_label Mapping[str, Sequence[float]] | None

Optional mapping {label: allocation}.

 None
point_sets Mapping[str, Sequence[Sequence[float]]] | None

Optional mapping {label: allocations} to plot as point clouds.

 None
sets_vertices Mapping[str, Sequence[Sequence[float]]] | None

Optional mapping {label: vertices} for sets drawn as segments.

 None
show_imputation bool

If True, draw the imputation segment.

 True
show_core bool

If True, draw the core segment (if non-empty).

 True
ax

Optional Matplotlib Axes; if omitted, a new figure/axes is created.

 None
Warnings

This function requires Matplotlib at runtime (install with pip install "tucoopy[viz]").

plot_spec_segment 

plot_spec_segment(
    spec,
    *,
    sets=("imputation", "core"),
    solutions=("shapley",),
    series_id=None,
    frame_index=0,
    t=None,
    use_analysis=True,
    compute_missing=True,
    epsilon=None,
    n_samples=200,
    seed=None,
    ax=None,
)

Plot an AnimationSpec-like object for \(n=2\) as a static segment plot.

This is a convenience wrapper that:

  1. builds a Game from spec.game,
  2. reads precomputed sets/solutions from spec.analysis (if enabled), and
  3. optionally computes missing objects for small \(n\).

Parameters:

Name Type Description Default
spec Any

A spec object (dict-like or attribute-like) with fields: game and optionally analysis and series.

 required
sets Sequence[str]

Set labels to plot (e.g. ("imputation", "core", "epsilon_core")). Some sets may be drawn from vertices; others may be drawn as point clouds.

 ('imputation', 'core')
solutions Sequence[str]

Solution labels to plot as points (e.g. ("shapley", "tau")).

 ('shapley',)
series_id str | None

Frame selection parameters for plotting a highlighted "frame" allocation from spec.series (if present).

 None
frame_index str | None

Frame selection parameters for plotting a highlighted "frame" allocation from spec.series (if present).

 None
t str | None

Frame selection parameters for plotting a highlighted "frame" allocation from spec.series (if present).

 None
use_analysis bool

If True, try using spec.analysis.sets and spec.analysis.solutions.

 True
compute_missing bool

If True, compute sets/solutions that are not present in analysis.

 True
epsilon float | None

Epsilon value used when computing epsilon_core (if needed). If omitted, tries to read it from analysis when available.

 None
n_samples int

Sample size for sampling-based sets (kernel/prekernel/bargaining).

 200
seed int | None

Random seed for sampling-based sets.

 None
ax

Optional Matplotlib Axes.

 None

Returns:

Type Description
(fig, ax)

The Matplotlib Figure and Axes used for the plot.

Raises:

Type Description
InvalidParameterError

If the game in spec does not have n_players=2.
Warnings

This function requires Matplotlib at runtime (install with pip install "tucoopy[viz]").