negmas.plots

Module for plotting functionality using plotly.

negmas.plots.default_colorizer(t: TraceElement)

Computes opacity based on the fraction of negotiators accepting the offer.

Parameters:

t – The trace element containing offer and response information.

negmas.plots.opacity_colorizer(t: TraceElement, alpha: float = 1.0)

Returns a constant opacity value, ignoring the trace element.

Parameters:

• t – The trace element (unused).

• alpha – The constant opacity value to return (0.0 to 1.0).

negmas.plots.plot_2dutils(trace: list[TraceElement], plotting_ufuns: list[UtilityFunction] | tuple[UtilityFunction, ...], plotting_negotiators: list[str] | tuple[str, ...], offering_negotiators: list[str] | tuple[str, ...] | None = None, agreement: tuple | None = None, outcome_space: OutcomeSpace | None = None, issues: list[Issue] | tuple[Issue, ...] | None = None, outcomes: list[tuple] | tuple[tuple, ...] | None = None, with_lines: bool = True, show_annotations: bool = True, show_agreement: bool = False, show_pareto_distance: bool = True, show_nash_distance: bool = True, show_kalai_distance: bool = True, show_ks_distance: bool = True, show_max_welfare_distance: bool = True, mark_pareto_points: bool = True, mark_all_outcomes: bool = True, mark_nash_points: bool = True, mark_kalai_points: bool = True, mark_ks_points: bool = True, mark_max_welfare_points: bool = True, show_max_relative_welfare_distance: bool = True, show_reserved: bool = True, show_total_time: bool = True, show_relative_time: bool = True, show_n_steps: bool = True, end_reason: str | None = None, extra_annotation: str | None = None, name_map: dict[str, str] | Callable[[str], str] | None = None, colors: list | None = None, markers: list[str] | None = None, colormap: str = 'Jet', fig: Figure | None = None, row: int = 1, col: int = 1, colorizer: Callable[[TraceElement], float] | None = None, fast: bool = False, backend: str = 'plotly')

Plots negotiation trace in 2D utility space for two negotiators.

Parameters:

• trace – List of trace elements recording all offers made during negotiation.

• plotting_ufuns – The two utility functions for the x and y axes.

• plotting_negotiators – IDs of the two negotiators being plotted.

• offering_negotiators – IDs of all negotiators who made offers to display.

• agreement – The final agreement outcome, if any.

• outcome_space – The space of possible outcomes.

• issues – List of negotiation issues (alternative to outcome_space).

• outcomes – Explicit list of outcomes (alternative to outcome_space).

• with_lines – Whether to connect consecutive offers with lines.

• show_annotations – Whether to show text labels on special points.

• show_agreement – Whether to include agreement details in annotation.

• show_pareto_distance – Whether to show distance from agreement to Pareto frontier.

• show_nash_distance – Whether to show distance from agreement to Nash point.

• show_kalai_distance – Whether to show distance from agreement to Kalai point.

• show_ks_distance – Whether to show distance from agreement to Kalai-Smorodinsky point.

• show_max_welfare_distance – Whether to show distance to max welfare point.

• mark_pareto_points – Whether to mark Pareto optimal outcomes.

• mark_all_outcomes – Whether to mark all possible outcomes.

• mark_nash_points – Whether to mark Nash bargaining solution.

• mark_kalai_points – Whether to mark Kalai proportional solution.

• mark_ks_points – Whether to mark Kalai-Smorodinsky solution.

• mark_max_welfare_points – Whether to mark maximum welfare points.

• show_max_relative_welfare_distance – Whether to show distance to max relative welfare.

• show_reserved – Whether to shade regions below reserved values.

• show_total_time – Whether to show total negotiation time in annotation.

• show_relative_time – Whether to show relative time (0-1) in annotation.

• show_n_steps – Whether to show number of steps in annotation.

• end_reason – Text describing why negotiation ended.

• extra_annotation – Additional text to include in annotation.

• name_map – Mapping from negotiator IDs to display names.

• colors – List of colors for each negotiator’s markers.

• markers – List of marker symbols for each negotiator.

• colormap – Colormap name for auto-generating colors.

• fig – Existing figure to add traces to, or None to create new (type depends on backend).

• row – Row index in subplot grid (1-indexed) - only used for plotly backend.

• col – Column index in subplot grid (1-indexed) - only used for plotly backend.

• colorizer – Function to compute opacity for each trace element.

• fast – Whether to skip expensive calculations (Pareto, Nash, etc.).

• backend – Plotting backend to use. Either “matplotlib” or “plotly”. Default is “plotly”.

Returns:

A matplotlib Figure object if backend=”matplotlib”, or a plotly Figure object if backend=”plotly”.

Raises:

ValueError – If backend is not “matplotlib” or “plotly”.

negmas.plots.plot_mechanism_run(mechanism: PlottableMechanism, *, negotiators: tuple[int, int] | tuple[str, str] | None = (0, 1), save_fig: bool = False, path: str | None = None, fig_name: str | None = None, image_format: str = 'webp', ignore_none_offers: bool = True, with_lines: bool = True, show_agreement: bool = False, show_pareto_distance: bool = True, show_nash_distance: bool = True, show_kalai_distance: bool = True, show_ks_distance: bool = True, show_max_welfare_distance: bool = True, show_max_relative_welfare_distance: bool = False, show_end_reason: bool = True, show_annotations: bool = False, show_reserved: bool = True, show_total_time: bool = True, show_relative_time: bool = True, show_n_steps: bool = True, colors: list | None = None, markers: list[str] | None = None, colormap: str = 'Jet', ylimits: tuple[float, float] | None = None, common_legend: bool = True, extra_annotation: str = '', xdim: str = 'relative_time', colorizer: Callable[[TraceElement], float] | None = None, only2d: bool = False, no2d: bool = False, fast: bool = False, simple_offers_view: bool = False, mark_offers_view: bool = True, mark_pareto_points: bool = True, mark_all_outcomes: bool = True, mark_nash_points: bool = True, mark_kalai_points: bool = True, mark_ks_points: bool = True, mark_max_welfare_points: bool = True, show: bool = True)

Plots a complete visualization of a negotiation mechanism run.

This is a convenience wrapper around plot_offline_run that extracts the necessary data from a live mechanism object.

Parameters:

mechanism – The mechanism object containing negotiation state and history.

negmas.plots.plot_offer_utilities(trace: list[TraceElement], negotiator: str, plotting_ufuns: list[BaseUtilityFunction | None], plotting_negotiators: list[str], ignore_none_offers: bool = True, name_map: dict[str, str] | Callable[[str], str] | None = None, colors: list | None = None, markers: list | None = None, colormap: str = 'Jet', fig: Figure | None = None, row: int = 1, col: int = 1, sharey: bool = False, xdim: str = 'relative_time', ylimits: tuple[float, float] | None = None, show_legend: bool = True, show_x_label: bool = True, ignore_markers_limit: int = 200, show_reserved: bool = True, colorizer: Callable[[TraceElement], float] | None = None, first_color_index: int = 0, mark_offers_view: bool = True)

Plots utility values of offers over time for a specific negotiator.

Parameters:

• trace – List of trace elements recording all offers made during negotiation.

• negotiator – ID of the negotiator whose offers to plot on x-axis.

• plotting_ufuns – Utility functions to evaluate offers against.

• plotting_negotiators – IDs of negotiators corresponding to each utility function.

• ignore_none_offers – Whether to skip None offers in the plot.

• name_map – Mapping from negotiator IDs to display names.

• colors – List of colors for each negotiator’s line.

• markers – List of marker symbols for each negotiator.

• colormap – Colormap name for auto-generating colors.

• fig – Existing Plotly figure to add traces to, or None to create new.

• row – Row index in subplot grid (1-indexed).

• col – Column index in subplot grid (1-indexed).

• sharey – Whether this subplot shares y-axis with others.

• xdim – X-axis dimension (‘relative_time’, ‘step’, or ‘time’).

• ylimits – Optional (min, max) limits for y-axis.

• show_legend – Whether to display legend entries.

• show_x_label – Whether to show x-axis label.

• ignore_markers_limit – Hide markers if trace has more elements than this.

• show_reserved – Whether to show reserved value lines.

• colorizer – Function to compute opacity for each trace element.

• first_color_index – Index offset for color assignment.

• mark_offers_view – Whether to mark special states (errors, agreement, timeout).

negmas.plots.plot_offline_run(trace: list[TraceElement], ids: list[str], ufuns: list[BaseUtilityFunction] | tuple[BaseUtilityFunction, ...], agreement: tuple | None, timedout: bool = False, broken: bool = False, has_error: bool = False, errstr: str = '', names: list[str] | None = None, outcomes: list[tuple] | None = None, outcome_space: OutcomeSpace | None = None, end_reason: str | None = None, *, negotiators: tuple[int, int] | tuple[str, str] | None = (0, 1), save_fig: bool = False, path: str | None = None, fig_name: str | None = None, image_format: str = 'webp', ignore_none_offers: bool = True, with_lines: bool = True, show_agreement: bool = False, show_pareto_distance: bool = True, show_nash_distance: bool = True, show_kalai_distance: bool = True, show_ks_distance: bool = True, show_max_welfare_distance: bool = True, show_max_relative_welfare_distance: bool = False, show_end_reason: bool = True, show_annotations: bool = False, show_reserved: bool = True, show_total_time: bool = True, show_relative_time: bool = True, show_n_steps: bool = True, colors: list | None = None, markers: list[str] | None = None, colormap: str = 'Jet', ylimits: tuple[float, float] | None = None, common_legend: bool = True, extra_annotation: str = '', xdim: str = 'relative_time', colorizer: Callable[[TraceElement], float] | None = None, only2d: bool = False, no2d: bool = False, fast: bool = False, simple_offers_view: bool = False, mark_offers_view: bool = True, mark_pareto_points: bool = True, mark_all_outcomes: bool = True, mark_nash_points: bool = True, mark_kalai_points: bool = True, mark_ks_points: bool = True, mark_max_welfare_points: bool = True, show: bool = True)

Plots a negotiation run from saved trace data (without a live mechanism).

Parameters:

• trace – List of trace elements recording all offers made during negotiation.

• ids – List of negotiator IDs in the order they participated.

• ufuns – List of utility functions corresponding to each negotiator.

• agreement – The final agreement outcome, or None if no agreement.

• timedout – Whether the negotiation ended due to timeout.

• broken – Whether the negotiation was broken/terminated early.

• has_error – Whether an error occurred during negotiation.

• errstr – Error message string if has_error is True.

• names – Display names for negotiators (defaults to IDs if None).

• outcomes – List of outcomes to plot. If None, derived from outcome_space or ufuns[0].

• outcome_space – The outcome space for the negotiation. If None, uses ufuns[0].outcome_space.

• end_reason – Pre-formatted end reason string. If provided, overrides the automatic reason generation from timedout/broken/has_error/errstr.

• save_fig – If True, save the figure to disk.

• path – Directory path where to save the figure (if save_fig is True).

• fig_name – Filename for the saved figure. If provided with an extension (e.g., “plot.png”), that extension is used. If provided without an extension or None, the image_format parameter determines the extension.

• image_format – Image format to use when auto-generating filenames (default: webp). Supported formats: webp, png, jpg, jpeg, svg, pdf. Only used if fig_name is None or doesn’t have an extension.