`tucoopy.viz.mpl3`¶

Matplotlib helpers for 3-player games (ternary plots).¶

This module provides a static ternary (simplex) plot for \(n=3\) TU games:

draws the imputation simplex as the background triangle,
overlays core and other set-valued objects as polygons/segments,
overlays point solutions and custom points.

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_spec_ternary ¶

plot_spec_ternary(
    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=3\) as a static ternary (simplex) plot.

Reads sets/solutions from spec.analysis when available and enabled, and can compute missing objects for small \(n\). The imputation simplex is rendered as the background triangle.

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. `"imputation"` controls whether the background simplex is drawn.	`('imputation', 'core')`
`solutions`	`Sequence[str]`	Solution labels to plot as points.	`('shapley',)`
`series_id`	`str \| None`	Frame selection parameters for plotting a highlighted "frame" allocation.	`None`
`frame_index`	`str \| None`	Frame selection parameters for plotting a highlighted "frame" allocation.	`None`
`t`	`str \| None`	Frame selection parameters for plotting a highlighted "frame" allocation.	`None`
`use_analysis`	`bool`	If True, try using `spec.analysis` entries for sets/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).	`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=3`.

Warnings

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

plot_ternary ¶

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

Plot a 3-player TU game on a ternary (simplex) diagram.

The imputation set is drawn as the background triangle (after the standard affine normalization using individual lower bounds). Other sets are drawn either as polygons (>=3 vertices), segments (2 vertices), or points.

Parameters:

Name	Type	Description	Default
`game`	`GameProtocol`	TU game with n_players=3.	required
`points`	`Sequence[Sequence[float]] \| None`	Optional allocations to overlay as points.	`None`
`points_by_label`	`Mapping[str, Sequence[float]] \| None`	Optional mapping {label: allocation} to overlay labeled points.	`None`
`point_sets`	`Mapping[str, Sequence[Sequence[float]]] \| None`	Optional mapping {label: allocations} to overlay point clouds.	`None`
`sets_vertices`	`Mapping[str, Sequence[Sequence[float]]] \| None`	Optional mapping {label: vertices} for set polygons/segments in R^3.	`None`
`show_imputation`	`bool`	If True, draw the imputation triangle (when feasible).	`True`
`show_core`	`bool`	If True, compute and draw the core polygon (if non-empty).	`True`
`ax`		Optional Matplotlib Axes; if omitted, a new figure/axes is created.	`None`

Returns:

Type	Description
`(fig, ax)`	The Matplotlib Figure and Axes used for the plot.

Raises:

Type	Description
`InvalidParameterError`	If game.n_players != 3.

Warnings

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

tucoopy.viz.mpl3¶

Matplotlib helpers for 3-player games (ternary plots).¶

plot_spec_ternary ¶

plot_ternary ¶

`tucoopy.viz.mpl3`¶