anydyce.viz package reference

Experimental

This package is an attempt to explore conveniences for integration with Matplotlib. It is an explicit departure from RFC 1925, § 2.2 and should be considered experimental. Be warned that future release may introduce incompatibilities or remove this package altogether. Feedback, suggestions, and contributions are welcome and appreciated.

HLikeT = Union[H, HableT] module-attribute

ImageType

Bases: str, Enum

Source code in anydyce/viz.py

class ImageType(str, Enum):
    PNG = "PNG"
    SVG = "SVG"

PNG = 'PNG' class-attribute instance-attribute

SVG = 'SVG' class-attribute instance-attribute

TraditionalPlotType

Bases: str, Enum

Source code in anydyce/viz.py

class TraditionalPlotType(str, Enum):
    NORMAL = "Normal"
    AT_MOST = "At Most"
    AT_LEAST = "At Least"

AT_LEAST = 'At Least' class-attribute instance-attribute

AT_MOST = 'At Most' class-attribute instance-attribute

NORMAL = 'Normal' class-attribute instance-attribute

HPlotter

Experimental

This class should be considered experimental and may change or disappear in future versions.

A plotter responsible for laying out control widgets and visualizing data provided by primary and optional secondary histograms. (See the plot method.)

Source code in anydyce/viz.py

class HPlotter:
    r"""
    !!! warning "Experimental"

        This class should be considered experimental and may change or disappear in
        future versions.

    A plotter responsible for laying out control widgets and visualizing data provided
    by primary and optional secondary histograms. (See the
    [*plot* method][anydyce.viz.HPlotter.plot].)
    """

    @abstractproperty
    def NAME(self) -> str:
        r"""
        The display name of the plotter.
        """
        raise NotImplementedError

    @beartype
    def layout(self, plot_widgets: PlotWidgets) -> widgets.Widget:
        r"""
        Takes a set of widgets (*plot_widgets*) and returns a container (layout) widget
        selecting those needed by the plotter.
        """
        return widgets.VBox(
            [
                plot_widgets.enable_cutoff,
                plot_widgets.cutoff,
                plot_widgets.img_type,
                plot_widgets.resolution,
            ]
        )

    @abstractmethod
    def plot(
        self,
        hs: Sequence[tuple[str, H, Optional[H]]],
        settings: SettingsDict,
    ):
        r"""
        Creates and displays a visualization of the provided histograms. *fig* is the
        [``#!python
        matplotlib.figure.Figure``](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure)
        in which the visualization should be constructed. *hs* is a sequence of
        three-tuples, a name, a primary histogram, and an optional secondary histogram
        (``#!python None`` if omitted). Plotters should implement this function to
        display at least the primary histogram and visually associate it with the name.
        """
        raise NotImplementedError

    @beartype
    def transparent(self, requested: bool) -> bool:
        r"""
        Returns whether this plotter produces plots which support transparency if
        *requested*. The default implementation always returns ``#!python False``.
        """
        return False

NAME() -> str

The display name of the plotter.

Source code in anydyce/viz.py

@abstractproperty
def NAME(self) -> str:
    r"""
    The display name of the plotter.
    """
    raise NotImplementedError

layout(plot_widgets: PlotWidgets) -> widgets.Widget

Takes a set of widgets (plot_widgets) and returns a container (layout) widget selecting those needed by the plotter.

Source code in anydyce/viz.py

@beartype
def layout(self, plot_widgets: PlotWidgets) -> widgets.Widget:
    r"""
    Takes a set of widgets (*plot_widgets*) and returns a container (layout) widget
    selecting those needed by the plotter.
    """
    return widgets.VBox(
        [
            plot_widgets.enable_cutoff,
            plot_widgets.cutoff,
            plot_widgets.img_type,
            plot_widgets.resolution,
        ]
    )

plot(hs: Sequence[tuple[str, H, Optional[H]]], settings: SettingsDict) abstractmethod

Creates and displays a visualization of the provided histograms. fig is the matplotlib.figure.Figure in which the visualization should be constructed. hs is a sequence of three-tuples, a name, a primary histogram, and an optional secondary histogram (None if omitted). Plotters should implement this function to display at least the primary histogram and visually associate it with the name.

Source code in anydyce/viz.py

@abstractmethod
def plot(
    self,
    hs: Sequence[tuple[str, H, Optional[H]]],
    settings: SettingsDict,
):
    r"""
    Creates and displays a visualization of the provided histograms. *fig* is the
    [``#!python
    matplotlib.figure.Figure``](https://matplotlib.org/stable/api/figure_api.html#matplotlib.figure.Figure)
    in which the visualization should be constructed. *hs* is a sequence of
    three-tuples, a name, a primary histogram, and an optional secondary histogram
    (``#!python None`` if omitted). Plotters should implement this function to
    display at least the primary histogram and visually associate it with the name.
    """
    raise NotImplementedError

transparent(requested: bool) -> bool

Returns whether this plotter produces plots which support transparency if requested. The default implementation always returns False.

Source code in anydyce/viz.py

@beartype
def transparent(self, requested: bool) -> bool:
    r"""
    Returns whether this plotter produces plots which support transparency if
    *requested*. The default implementation always returns ``#!python False``.
    """
    return False

BarHPlotter

Bases: HPlotter

Experimental

This class should be considered experimental and may change or disappear in future versions.

A plotter for creating a single vertical bar plot visualizing all primary histograms. Secondary histograms are ignored.

Source code in anydyce/viz.py

class BarHPlotter(HPlotter):
    r"""
    !!! warning "Experimental"

        This class should be considered experimental and may change or disappear in
        future versions.

    A plotter for creating a single vertical bar plot visualizing all primary
    histograms. Secondary histograms are ignored.
    """

    NAME = "Bar Plot"

    @beartype
    def layout(self, plot_widgets: PlotWidgets) -> widgets.Widget:
        cutoff_layout_widget = super().layout(plot_widgets)

        return widgets.VBox(
            [
                widgets.HBox(
                    [
                        cutoff_layout_widget,
                        plot_widgets.graph_type,
                        widgets.VBox(
                            [
                                plot_widgets.alpha,
                                plot_widgets.plot_style,
                                plot_widgets.show_shadow,
                            ]
                        ),
                    ]
                ),
            ]
        )

    @beartype
    def plot(
        self,
        hs: Sequence[tuple[str, H, Optional[H]]],
        settings: SettingsDict,
    ) -> None:
        _, ax = matplotlib.pyplot.subplots(
            figsize=(
                settings["resolution"],
                settings["resolution"] / 16 * 9,
            )
        )

        plot_bar(
            ax,
            tuple((label, h) for label, h, _ in hs),
            alpha=settings["alpha"],
            graph_type=settings["graph_type"],
            shadow=settings["show_shadow"],
        )

        with warnings.catch_warnings():
            warnings.simplefilter("ignore")
            ax.legend()

NAME = 'Bar Plot' class-attribute instance-attribute

layout(plot_widgets: PlotWidgets) -> widgets.Widget

Source code in anydyce/viz.py

@beartype
def layout(self, plot_widgets: PlotWidgets) -> widgets.Widget:
    cutoff_layout_widget = super().layout(plot_widgets)

    return widgets.VBox(
        [
            widgets.HBox(
                [
                    cutoff_layout_widget,
                    plot_widgets.graph_type,
                    widgets.VBox(
                        [
                            plot_widgets.alpha,
                            plot_widgets.plot_style,
                            plot_widgets.show_shadow,
                        ]
                    ),
                ]
            ),
        ]
    )

plot(hs: Sequence[tuple[str, H, Optional[H]]], settings: SettingsDict) -> None

Source code in anydyce/viz.py

@beartype
def plot(
    self,
    hs: Sequence[tuple[str, H, Optional[H]]],
    settings: SettingsDict,
) -> None:
    _, ax = matplotlib.pyplot.subplots(
        figsize=(
            settings["resolution"],
            settings["resolution"] / 16 * 9,
        )
    )

    plot_bar(
        ax,
        tuple((label, h) for label, h, _ in hs),
        alpha=settings["alpha"],
        graph_type=settings["graph_type"],
        shadow=settings["show_shadow"],
    )

    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        ax.legend()

BurstHPlotter

Bases: HPlotter

Experimental

This class should be considered experimental and may change or disappear in future versions.

A plotter for creating one burst plot per primary histogram. If provided, associated secondary histograms are used for the outer rings.

Source code in anydyce/viz.py

class BurstHPlotter(HPlotter):
    r"""
    !!! warning "Experimental"

        This class should be considered experimental and may change or disappear in
        future versions.

    A plotter for creating one burst plot per primary histogram. If provided, associated
    secondary histograms are used for the outer rings.
    """

    NAME = "Burst Plots"

    @beartype
    def layout(self, plot_widgets: PlotWidgets) -> widgets.Widget:
        cutoff_layout_widget = super().layout(plot_widgets)

        return widgets.VBox(
            [
                widgets.HBox(
                    [
                        widgets.VBox(
                            [
                                cutoff_layout_widget,
                            ]
                        ),
                        widgets.VBox(
                            [
                                plot_widgets.burst_swap,
                                plot_widgets.burst_zero_fill_normalize,
                                plot_widgets.burst_cmap_inner,
                                plot_widgets.burst_cmap_outer,
                                plot_widgets.burst_cmap_link,
                            ]
                        ),
                        widgets.VBox(
                            [
                                plot_widgets.alpha,
                                plot_widgets.burst_color_text,
                                plot_widgets.burst_color_bg,
                                plot_widgets.burst_color_bg_trnsp,
                                plot_widgets.burst_columns,
                            ]
                        ),
                    ]
                ),
            ]
        )

    @beartype
    def plot(
        self,
        hs: Sequence[tuple[str, H, Optional[H]]],
        settings: SettingsDict,
    ) -> None:
        cols = settings["burst_columns"]
        assert cols > 0
        logical_rows = len(hs) // cols + (len(hs) % cols != 0)
        # Height of row gaps in relation to height of figs
        gap_size_ratio = Fraction(1, 5)
        total_gaps = max(0, logical_rows - 1)
        figsize = (
            settings["resolution"],
            float(
                settings["resolution"]
                * (logical_rows + total_gaps * gap_size_ratio)
                / cols
            ),
        )
        matplotlib.pyplot.figure(facecolor=settings["burst_color_bg"], figsize=figsize)
        actual_rows_per_fig = gap_size_ratio.denominator
        actual_rows_per_gap = gap_size_ratio.numerator
        total_actual_rows = (
            logical_rows * actual_rows_per_fig + total_gaps * actual_rows_per_gap
        )

        def _zero_fill_normalize():
            unique_outcomes: set[RealLike] = set()

            for i, (_, first_h, second_h) in enumerate(hs):
                unique_outcomes.update(first_h)

                if second_h:
                    unique_outcomes.update(second_h)

            for i, (label, first_h, second_h) in enumerate(hs):
                yield (
                    label,
                    first_h.zero_fill(unique_outcomes),
                    None if second_h is None else second_h.zero_fill(unique_outcomes),
                )

        if settings["burst_zero_fill_normalize"]:
            hs = tuple(_zero_fill_normalize())

        for i, (label, h_inner, h_outer) in enumerate(hs):
            plot_burst_kw: dict[str, Any] = dict(
                title=label,
                inner_cmap=settings["burst_cmap_inner"],
                outer_cmap=(
                    settings["burst_cmap_outer"]
                    if not settings["burst_cmap_link"]
                    else settings["burst_cmap_inner"]
                ),
                text_color=settings["burst_color_text"],
                alpha=settings["alpha"],
            )

            if h_outer is not None:
                if settings["burst_swap"]:
                    h_inner, h_outer = h_outer, h_inner

            logical_row = i // cols
            actual_row_start = logical_row * (actual_rows_per_gap + actual_rows_per_fig)
            ax = matplotlib.pyplot.subplot2grid(
                (total_actual_rows, cols),
                (actual_row_start, i % cols),
                rowspan=actual_rows_per_fig,
            )
            plot_burst(
                ax,
                h_inner,
                h_outer,
                **plot_burst_kw,
            )

    @beartype
    def transparent(self, requested: bool) -> bool:
        return requested

NAME = 'Burst Plots' class-attribute instance-attribute

layout(plot_widgets: PlotWidgets) -> widgets.Widget

Source code in anydyce/viz.py

@beartype
def layout(self, plot_widgets: PlotWidgets) -> widgets.Widget:
    cutoff_layout_widget = super().layout(plot_widgets)

    return widgets.VBox(
        [
            widgets.HBox(
                [
                    widgets.VBox(
                        [
                            cutoff_layout_widget,
                        ]
                    ),
                    widgets.VBox(
                        [
                            plot_widgets.burst_swap,
                            plot_widgets.burst_zero_fill_normalize,
                            plot_widgets.burst_cmap_inner,
                            plot_widgets.burst_cmap_outer,
                            plot_widgets.burst_cmap_link,
                        ]
                    ),
                    widgets.VBox(
                        [
                            plot_widgets.alpha,
                            plot_widgets.burst_color_text,
                            plot_widgets.burst_color_bg,
                            plot_widgets.burst_color_bg_trnsp,
                            plot_widgets.burst_columns,
                        ]
                    ),
                ]
            ),
        ]
    )

plot(hs: Sequence[tuple[str, H, Optional[H]]], settings: SettingsDict) -> None

Source code in anydyce/viz.py

@beartype
def plot(
    self,
    hs: Sequence[tuple[str, H, Optional[H]]],
    settings: SettingsDict,
) -> None:
    cols = settings["burst_columns"]
    assert cols > 0
    logical_rows = len(hs) // cols + (len(hs) % cols != 0)
    # Height of row gaps in relation to height of figs
    gap_size_ratio = Fraction(1, 5)
    total_gaps = max(0, logical_rows - 1)
    figsize = (
        settings["resolution"],
        float(
            settings["resolution"]
            * (logical_rows + total_gaps * gap_size_ratio)
            / cols
        ),
    )
    matplotlib.pyplot.figure(facecolor=settings["burst_color_bg"], figsize=figsize)
    actual_rows_per_fig = gap_size_ratio.denominator
    actual_rows_per_gap = gap_size_ratio.numerator
    total_actual_rows = (
        logical_rows * actual_rows_per_fig + total_gaps * actual_rows_per_gap
    )

    def _zero_fill_normalize():
        unique_outcomes: set[RealLike] = set()

        for i, (_, first_h, second_h) in enumerate(hs):
            unique_outcomes.update(first_h)

            if second_h:
                unique_outcomes.update(second_h)

        for i, (label, first_h, second_h) in enumerate(hs):
            yield (
                label,
                first_h.zero_fill(unique_outcomes),
                None if second_h is None else second_h.zero_fill(unique_outcomes),
            )

    if settings["burst_zero_fill_normalize"]:
        hs = tuple(_zero_fill_normalize())

    for i, (label, h_inner, h_outer) in enumerate(hs):
        plot_burst_kw: dict[str, Any] = dict(
            title=label,
            inner_cmap=settings["burst_cmap_inner"],
            outer_cmap=(
                settings["burst_cmap_outer"]
                if not settings["burst_cmap_link"]
                else settings["burst_cmap_inner"]
            ),
            text_color=settings["burst_color_text"],
            alpha=settings["alpha"],
        )

        if h_outer is not None:
            if settings["burst_swap"]:
                h_inner, h_outer = h_outer, h_inner

        logical_row = i // cols
        actual_row_start = logical_row * (actual_rows_per_gap + actual_rows_per_fig)
        ax = matplotlib.pyplot.subplot2grid(
            (total_actual_rows, cols),
            (actual_row_start, i % cols),
            rowspan=actual_rows_per_fig,
        )
        plot_burst(
            ax,
            h_inner,
            h_outer,
            **plot_burst_kw,
        )

transparent(requested: bool) -> bool

Source code in anydyce/viz.py

@beartype
def transparent(self, requested: bool) -> bool:
    return requested

HorizontalBarHPlotter

Bases: BarHPlotter

Experimental

This class should be considered experimental and may change or disappear in future versions.

A plotter for creating one horizontal bar plot per primary histogram. Secondary histograms are ignored.

Source code in anydyce/viz.py

class HorizontalBarHPlotter(BarHPlotter):
    r"""
    !!! warning "Experimental"

        This class should be considered experimental and may change or disappear in
        future versions.

    A plotter for creating one horizontal bar plot per primary histogram. Secondary
    histograms are ignored.
    """

    NAME = "Horizontal Bar Plots"

    @beartype
    def plot(
        self,
        hs: Sequence[tuple[str, H, Optional[H]]],
        settings: SettingsDict,
    ) -> None:
        total_outcomes = sum(
            1 for _ in chain.from_iterable(h.outcomes() for _, h, _ in hs)
        )
        total_height = total_outcomes + 1  # one extra to accommodate the axis
        inches_per_height_unit = settings["resolution"] / 64
        figsize = (
            settings["resolution"],
            total_height * inches_per_height_unit,
        )
        matplotlib.pyplot.figure(figsize=figsize)
        barh_kw: dict[str, Any] = dict(alpha=settings["alpha"])

        if settings["show_shadow"]:
            barh_kw.update(
                dict(
                    path_effects=[
                        matplotlib.patheffects.withSimplePatchShadow(),
                        matplotlib.patheffects.Normal(),
                    ]
                )
            )

        plot_style = settings["plot_style"]

        if (
            plot_style in matplotlib.style.library
            and "axes.prop_cycle" in matplotlib.style.library[plot_style]
            and "color" in matplotlib.style.library[plot_style]["axes.prop_cycle"]
        ):
            # Our current style has a cycler with colors, so use it
            cycler = matplotlib.style.library[plot_style]["axes.prop_cycle"]
        else:
            # Revert to the global default
            cycler = matplotlib.rcParams["axes.prop_cycle"]

        color_iter = cycle(cycler.by_key().get("color", (None,)))
        row_start = 0
        first_ax = ax = None

        for i, (label, h, _) in enumerate(hs):
            if not h:
                continue

            outcomes, values = values_xy_for_graph_type(h, settings["graph_type"])
            rowspan = len(outcomes)

            if first_ax is None:
                first_ax = ax = matplotlib.pyplot.subplot2grid(
                    (total_height, 1), (row_start, 0), rowspan=rowspan
                )
            else:
                ax = matplotlib.pyplot.subplot2grid(
                    (total_height, 1), (row_start, 0), rowspan=rowspan, sharex=first_ax
                )

            ax.set_yticks(outcomes)  # type: ignore [arg-type]
            ax.tick_params(labelbottom=False)
            ax.set_ylim((max(outcomes) + 0.5, min(outcomes) - 0.5))
            ax.barh(outcomes, values, color=next(color_iter), label=label, **barh_kw)  # type: ignore [arg-type]
            ax.legend(loc="upper right")
            row_start += rowspan

        if ax is not None:
            ax.tick_params(labelbottom=True)
            ax.xaxis.set_major_formatter(matplotlib.ticker.PercentFormatter(xmax=1))

NAME = 'Horizontal Bar Plots' class-attribute instance-attribute

plot(hs: Sequence[tuple[str, H, Optional[H]]], settings: SettingsDict) -> None

Source code in anydyce/viz.py

@beartype
def plot(
    self,
    hs: Sequence[tuple[str, H, Optional[H]]],
    settings: SettingsDict,
) -> None:
    total_outcomes = sum(
        1 for _ in chain.from_iterable(h.outcomes() for _, h, _ in hs)
    )
    total_height = total_outcomes + 1  # one extra to accommodate the axis
    inches_per_height_unit = settings["resolution"] / 64
    figsize = (
        settings["resolution"],
        total_height * inches_per_height_unit,
    )
    matplotlib.pyplot.figure(figsize=figsize)
    barh_kw: dict[str, Any] = dict(alpha=settings["alpha"])

    if settings["show_shadow"]:
        barh_kw.update(
            dict(
                path_effects=[
                    matplotlib.patheffects.withSimplePatchShadow(),
                    matplotlib.patheffects.Normal(),
                ]
            )
        )

    plot_style = settings["plot_style"]

    if (
        plot_style in matplotlib.style.library
        and "axes.prop_cycle" in matplotlib.style.library[plot_style]
        and "color" in matplotlib.style.library[plot_style]["axes.prop_cycle"]
    ):
        # Our current style has a cycler with colors, so use it
        cycler = matplotlib.style.library[plot_style]["axes.prop_cycle"]
    else:
        # Revert to the global default
        cycler = matplotlib.rcParams["axes.prop_cycle"]

    color_iter = cycle(cycler.by_key().get("color", (None,)))
    row_start = 0
    first_ax = ax = None

    for i, (label, h, _) in enumerate(hs):
        if not h:
            continue

        outcomes, values = values_xy_for_graph_type(h, settings["graph_type"])
        rowspan = len(outcomes)

        if first_ax is None:
            first_ax = ax = matplotlib.pyplot.subplot2grid(
                (total_height, 1), (row_start, 0), rowspan=rowspan
            )
        else:
            ax = matplotlib.pyplot.subplot2grid(
                (total_height, 1), (row_start, 0), rowspan=rowspan, sharex=first_ax
            )

        ax.set_yticks(outcomes)  # type: ignore [arg-type]
        ax.tick_params(labelbottom=False)
        ax.set_ylim((max(outcomes) + 0.5, min(outcomes) - 0.5))
        ax.barh(outcomes, values, color=next(color_iter), label=label, **barh_kw)  # type: ignore [arg-type]
        ax.legend(loc="upper right")
        row_start += rowspan

    if ax is not None:
        ax.tick_params(labelbottom=True)
        ax.xaxis.set_major_formatter(matplotlib.ticker.PercentFormatter(xmax=1))

LineHPlotter

Bases: HPlotter

Experimental

This class should be considered experimental and may change or disappear in future versions.

A plotter for creating a single line plot visualizing all primary histograms. Secondary histograms are ignored.

Source code in anydyce/viz.py

class LineHPlotter(HPlotter):
    r"""
    !!! warning "Experimental"

        This class should be considered experimental and may change or disappear in
        future versions.

    A plotter for creating a single line plot visualizing all primary histograms.
    Secondary histograms are ignored.
    """

    NAME = "Line Plot"

    @beartype
    def layout(self, plot_widgets: PlotWidgets) -> widgets.Widget:
        cutoff_layout_widget = super().layout(plot_widgets)

        return widgets.VBox(
            [
                widgets.HBox(
                    [
                        cutoff_layout_widget,
                        plot_widgets.graph_type,
                        widgets.VBox(
                            [
                                plot_widgets.alpha,
                                plot_widgets.plot_style,
                                plot_widgets.show_shadow,
                                plot_widgets.markers,
                            ]
                        ),
                    ]
                ),
            ]
        )

    @beartype
    def plot(
        self,
        hs: Sequence[tuple[str, H, Optional[H]]],
        settings: SettingsDict,
    ) -> None:
        _, ax = matplotlib.pyplot.subplots(
            figsize=(
                settings["resolution"],
                settings["resolution"] / 16 * 9,
            )
        )

        plot_line(
            ax,
            tuple((label, h) for label, h, _ in hs),
            alpha=settings["alpha"],
            graph_type=settings["graph_type"],
            markers=settings["markers"],
            shadow=settings["show_shadow"],
        )

        with warnings.catch_warnings():
            warnings.simplefilter("ignore")
            ax.legend()

NAME = 'Line Plot' class-attribute instance-attribute

layout(plot_widgets: PlotWidgets) -> widgets.Widget

Source code in anydyce/viz.py

@beartype
def layout(self, plot_widgets: PlotWidgets) -> widgets.Widget:
    cutoff_layout_widget = super().layout(plot_widgets)

    return widgets.VBox(
        [
            widgets.HBox(
                [
                    cutoff_layout_widget,
                    plot_widgets.graph_type,
                    widgets.VBox(
                        [
                            plot_widgets.alpha,
                            plot_widgets.plot_style,
                            plot_widgets.show_shadow,
                            plot_widgets.markers,
                        ]
                    ),
                ]
            ),
        ]
    )

plot(hs: Sequence[tuple[str, H, Optional[H]]], settings: SettingsDict) -> None

Source code in anydyce/viz.py

@beartype
def plot(
    self,
    hs: Sequence[tuple[str, H, Optional[H]]],
    settings: SettingsDict,
) -> None:
    _, ax = matplotlib.pyplot.subplots(
        figsize=(
            settings["resolution"],
            settings["resolution"] / 16 * 9,
        )
    )

    plot_line(
        ax,
        tuple((label, h) for label, h, _ in hs),
        alpha=settings["alpha"],
        graph_type=settings["graph_type"],
        markers=settings["markers"],
        shadow=settings["show_shadow"],
    )

    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        ax.legend()

ScatterHPlotter

Bases: LineHPlotter

Experimental

This class should be considered experimental and may change or disappear in future versions.

A plotter for creating a single scatter plot visualizing all primary histograms. Secondary histograms are ignored.

Source code in anydyce/viz.py

class ScatterHPlotter(LineHPlotter):
    r"""
    !!! warning "Experimental"

        This class should be considered experimental and may change or disappear in
        future versions.

    A plotter for creating a single scatter plot visualizing all primary histograms.
    Secondary histograms are ignored.
    """

    NAME = "Scatter Plot"

    @beartype
    def plot(
        self,
        hs: Sequence[tuple[str, H, Optional[H]]],
        settings: SettingsDict,
    ) -> None:
        _, ax = matplotlib.pyplot.subplots(
            figsize=(
                settings["resolution"],
                settings["resolution"] / 16 * 9,
            )
        )

        plot_scatter(
            ax,
            tuple((label, h) for label, h, _ in hs),
            alpha=settings["alpha"],
            graph_type=settings["graph_type"],
            markers=settings["markers"],
            shadow=settings["show_shadow"],
        )

        with warnings.catch_warnings():
            warnings.simplefilter("ignore")
            ax.legend()

NAME = 'Scatter Plot' class-attribute instance-attribute

plot(hs: Sequence[tuple[str, H, Optional[H]]], settings: SettingsDict) -> None

Source code in anydyce/viz.py

@beartype
def plot(
    self,
    hs: Sequence[tuple[str, H, Optional[H]]],
    settings: SettingsDict,
) -> None:
    _, ax = matplotlib.pyplot.subplots(
        figsize=(
            settings["resolution"],
            settings["resolution"] / 16 * 9,
        )
    )

    plot_scatter(
        ax,
        tuple((label, h) for label, h, _ in hs),
        alpha=settings["alpha"],
        graph_type=settings["graph_type"],
        markers=settings["markers"],
        shadow=settings["show_shadow"],
    )

    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        ax.legend()

PlotWidgets

Bases: _PlotWidgetsDataclass

Experimental

This class should be considered experimental and may change or disappear in future versions.

Class to encapsulate interactive plot control widgets. All parameters for the initializer are optional.

• initial_alpha is the starting alpha value for graphs (defaults to 0.75).

• initial_burst_cmap_inner is the initially selected color map for inner burst graphs (defaults to "RdYlGn_r").

• initial_burst_cmap_link is the starting value for linking the color maps for inner and outer burst graphs (defaults to True).

• initial_burst_cmap_outer is the initially selected color map for outer burst graphs (defaults to "RdYlBu_r").

• initial_burst_color_bg is the initially selected background color for burst graphs (defaults to "white").

• initial_burst_color_bg_trnsp is the initially selected background transparency color burst graphs (defaults to False).

• initial_burst_color_text is the initially selected text color for burst graphs (defaults to "black").

• initial_burst_columns is the initially selected number of columns for displaying burst graphs (defaults to 3).

• initial_burst_swap is whether the inner and outer burst graphs should be swapped at first (defaults to False).

• initial_burst_zero_fill_normalize is whether all burst graphs should share a scale at first (i.e., so similar values share similar colors across burst graphs) (defaults to False).

• initial_enable_cutoff is whether small values should be omitted from graphs at first (defaults to True).

• initial_graph_type is the type of graph first shown (defaults to TraditionalPlotType.NORMAL).

• initial_img_type is the initially selected image type (defaults to ImageType.PNG).

• initial_markers are the starting set of markers for line and scatter plots (defaults to "oX^v><dP").

• initial_plot_style is the starting color style for non-burst graphs (defaults to "bmh").

• initial_show_shadow is whether shadows should be shown for non-burst graphs at first (defaults to False).

• initial_resolution is the starting value for the graph resolution (defaults to 12).

Source code in anydyce/viz.py

class PlotWidgets(_PlotWidgetsDataclass):
    r"""
    !!! warning "Experimental"

        This class should be considered experimental and may change or disappear in
        future versions.

    Class to encapsulate interactive plot control widgets. All parameters for the
    [initializer][anydyce.viz.PlotWidgets.__init__] are optional.

    - *initial_alpha* is the starting alpha value for graphs (defaults to ``#!python
       0.75``).

    - *initial_burst_cmap_inner* is the initially selected color map for inner burst
       graphs (defaults to ``#!python "RdYlGn_r"``).

    - *initial_burst_cmap_link* is the starting value for linking the color maps for
       inner and outer burst graphs (defaults to ``#!python True``).

    - *initial_burst_cmap_outer* is the initially selected color map for outer burst
       graphs (defaults to ``#!python "RdYlBu_r"``).

    - *initial_burst_color_bg* is the initially selected background color for burst
       graphs (defaults to ``#!python "white"``).

    - *initial_burst_color_bg_trnsp* is the initially selected background transparency
       color burst graphs (defaults to ``#!python False``).

    - *initial_burst_color_text* is the initially selected text color for burst graphs
       (defaults to ``#!python "black"``).

    - *initial_burst_columns* is the initially selected number of columns for displaying
       burst graphs (defaults to ``#!python 3``).

    - *initial_burst_swap* is whether the inner and outer burst graphs should be swapped
       at first (defaults to ``#!python False``).

    - *initial_burst_zero_fill_normalize* is whether all burst graphs should share a
       scale at first (i.e., so similar values share similar colors across burst graphs)
       (defaults to ``#!python False``).

    - *initial_enable_cutoff* is whether small values should be omitted from graphs at
       first (defaults to ``#!python True``).

    - *initial_graph_type* is the type of graph first shown (defaults to
       [``TraditionalPlotType.NORMAL``][anydyce.viz.TraditionalPlotType.NORMAL]).

    - *initial_img_type* is the initially selected image type (defaults to
       [``ImageType.PNG``][anydyce.viz.ImageType.PNG]).

    - *initial_markers* are the starting set of markers for line and scatter plots
       (defaults to ``#!python "oX^v><dP"``).

    - *initial_plot_style* is the starting color style for non-burst graphs (defaults to
       ``#!python "bmh"``).

    - *initial_show_shadow* is whether shadows should be shown for non-burst graphs at
       first (defaults to ``#!python False``).

    - *initial_resolution* is the starting value for the graph resolution (defaults to
      ``#!python 12``).
    """

    @beartype
    def __init__(
        self,
        *,
        initial_alpha: float = DEFAULT_ALPHA,
        initial_burst_cmap_inner: str = DEFAULT_CMAP_BURST_INNER,
        initial_burst_cmap_link: bool = True,
        initial_burst_cmap_outer: str = DEFAULT_CMAP_BURST_OUTER,
        initial_burst_color_bg: str = DEFAULT_COLOR_BG,
        initial_burst_color_bg_trnsp: bool = False,
        initial_burst_color_text: str = DEFAULT_COLOR_TEXT,
        initial_burst_columns: int = DEFAULT_COLS_BURST,
        initial_burst_swap: bool = False,
        initial_burst_zero_fill_normalize: bool = False,
        initial_enable_cutoff: bool = True,
        initial_graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL,
        initial_img_type: ImageType = ImageType.PNG,
        initial_markers: str = DEFAULT_MARKERS,
        initial_plot_style: str = DEFAULT_PLOT_STYLE,
        initial_resolution: int = DEFAULT_RESOLUTION,
        initial_show_shadow: bool = False,
    ):
        super().__init__()

        if initial_plot_style not in matplotlib.style.available:
            warnings.warn(
                f"unrecognized plot style {initial_plot_style!r}; reverting to 'default'",
                category=RuntimeWarning,
            )
            initial_plot_style = "default"

        self.alpha.value = initial_alpha
        self.burst_cmap_inner.value = initial_burst_cmap_inner
        self.burst_cmap_link.value = initial_burst_cmap_link
        self.burst_cmap_outer.disabled = initial_burst_cmap_link
        self.burst_cmap_outer.value = initial_burst_cmap_outer
        self.burst_color_bg.value = initial_burst_color_bg
        self.burst_color_bg_trnsp.value = initial_burst_color_bg_trnsp
        self.burst_color_text.value = initial_burst_color_text
        self.burst_columns.value = initial_burst_columns
        self.burst_swap.value = initial_burst_swap
        self.burst_zero_fill_normalize.value = initial_burst_zero_fill_normalize
        self.cutoff.disabled = not initial_enable_cutoff
        self.enable_cutoff.value = initial_enable_cutoff
        self.graph_type.value = initial_graph_type
        self.img_type.value = initial_img_type
        self.markers.value = initial_markers
        self.plot_style.value = initial_plot_style
        self.resolution.value = initial_resolution
        self.show_shadow.value = initial_show_shadow

        def _handle_burst_cmap_link(change) -> None:
            self.burst_cmap_outer.disabled = change["new"]

        self.burst_cmap_link.observe(_handle_burst_cmap_link, names="value")

        def _handle_burst_color_bg_trnsp(change) -> None:
            self.burst_color_bg.disabled = change["new"]

        self.burst_color_bg_trnsp.observe(_handle_burst_color_bg_trnsp, names="value")

        def _handle_cutoff(change) -> None:
            self.cutoff.disabled = not change["new"]

        self.enable_cutoff.observe(_handle_cutoff, names="value")

    @beartype
    def asdict(self) -> dict[str, Any]:
        return dict((field.name, getattr(self, field.name)) for field in fields(self))

__init__(*, initial_alpha: float = DEFAULT_ALPHA, initial_burst_cmap_inner: str = DEFAULT_CMAP_BURST_INNER, initial_burst_cmap_link: bool = True, initial_burst_cmap_outer: str = DEFAULT_CMAP_BURST_OUTER, initial_burst_color_bg: str = DEFAULT_COLOR_BG, initial_burst_color_bg_trnsp: bool = False, initial_burst_color_text: str = DEFAULT_COLOR_TEXT, initial_burst_columns: int = DEFAULT_COLS_BURST, initial_burst_swap: bool = False, initial_burst_zero_fill_normalize: bool = False, initial_enable_cutoff: bool = True, initial_graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL, initial_img_type: ImageType = ImageType.PNG, initial_markers: str = DEFAULT_MARKERS, initial_plot_style: str = DEFAULT_PLOT_STYLE, initial_resolution: int = DEFAULT_RESOLUTION, initial_show_shadow: bool = False)

Source code in anydyce/viz.py

@beartype
def __init__(
    self,
    *,
    initial_alpha: float = DEFAULT_ALPHA,
    initial_burst_cmap_inner: str = DEFAULT_CMAP_BURST_INNER,
    initial_burst_cmap_link: bool = True,
    initial_burst_cmap_outer: str = DEFAULT_CMAP_BURST_OUTER,
    initial_burst_color_bg: str = DEFAULT_COLOR_BG,
    initial_burst_color_bg_trnsp: bool = False,
    initial_burst_color_text: str = DEFAULT_COLOR_TEXT,
    initial_burst_columns: int = DEFAULT_COLS_BURST,
    initial_burst_swap: bool = False,
    initial_burst_zero_fill_normalize: bool = False,
    initial_enable_cutoff: bool = True,
    initial_graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL,
    initial_img_type: ImageType = ImageType.PNG,
    initial_markers: str = DEFAULT_MARKERS,
    initial_plot_style: str = DEFAULT_PLOT_STYLE,
    initial_resolution: int = DEFAULT_RESOLUTION,
    initial_show_shadow: bool = False,
):
    super().__init__()

    if initial_plot_style not in matplotlib.style.available:
        warnings.warn(
            f"unrecognized plot style {initial_plot_style!r}; reverting to 'default'",
            category=RuntimeWarning,
        )
        initial_plot_style = "default"

    self.alpha.value = initial_alpha
    self.burst_cmap_inner.value = initial_burst_cmap_inner
    self.burst_cmap_link.value = initial_burst_cmap_link
    self.burst_cmap_outer.disabled = initial_burst_cmap_link
    self.burst_cmap_outer.value = initial_burst_cmap_outer
    self.burst_color_bg.value = initial_burst_color_bg
    self.burst_color_bg_trnsp.value = initial_burst_color_bg_trnsp
    self.burst_color_text.value = initial_burst_color_text
    self.burst_columns.value = initial_burst_columns
    self.burst_swap.value = initial_burst_swap
    self.burst_zero_fill_normalize.value = initial_burst_zero_fill_normalize
    self.cutoff.disabled = not initial_enable_cutoff
    self.enable_cutoff.value = initial_enable_cutoff
    self.graph_type.value = initial_graph_type
    self.img_type.value = initial_img_type
    self.markers.value = initial_markers
    self.plot_style.value = initial_plot_style
    self.resolution.value = initial_resolution
    self.show_shadow.value = initial_show_shadow

    def _handle_burst_cmap_link(change) -> None:
        self.burst_cmap_outer.disabled = change["new"]

    self.burst_cmap_link.observe(_handle_burst_cmap_link, names="value")

    def _handle_burst_color_bg_trnsp(change) -> None:
        self.burst_color_bg.disabled = change["new"]

    self.burst_color_bg_trnsp.observe(_handle_burst_color_bg_trnsp, names="value")

    def _handle_cutoff(change) -> None:
        self.cutoff.disabled = not change["new"]

    self.enable_cutoff.observe(_handle_cutoff, names="value")

asdict() -> dict[str, Any]

Source code in anydyce/viz.py

@beartype
def asdict(self) -> dict[str, Any]:
    return dict((field.name, getattr(self, field.name)) for field in fields(self))

cumulative_probability_formatter(outcome: RealLike, probability: Fraction, h: H) -> str

Experimental

This function should be considered experimental and may change or disappear in future versions.

Formatter for use with plot_burst to inefficiently (i.e., \(O \left( {n} ^ {2} \right)\)) calculate and format cumulative probability pairs for outcome in h.

Source code in anydyce/viz.py

@experimental
@beartype
def cumulative_probability_formatter(
    outcome: RealLike,
    probability: Fraction,
    h: H,
) -> str:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Formatter for use with [``plot_burst``][anydyce.viz.plot_burst] to inefficiently
    (i.e., $O \left( {n} ^ {2} \right)$) calculate and format cumulative probability
    pairs for *outcome* in *h*.
    """
    le_total, ge_total = Fraction(0), Fraction(1)

    for h_outcome, h_probability in h.distribution():
        le_total += h_probability

        if math.isclose(h_outcome, outcome):
            return f"{outcome} {float(probability):.2%}; ≥{float(le_total):.2%}; ≤{float(ge_total):.2%}"

        ge_total -= h_probability

    return f"{outcome} {float(probability):.2%}"

outcome_name_formatter(outcome: RealLike, _, __) -> str

Experimental

This function should be considered experimental and may change or disappear in future versions.

Formatter for use with plot_burst to format each outcome. If outcome has a name attribute (e.g., as with an Enum), that is used. Otherwise outcome is passed to str and the result is used.

Source code in anydyce/viz.py

@experimental
@beartype
def outcome_name_formatter(outcome: RealLike, _, __) -> str:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Formatter for use with [``plot_burst``][anydyce.viz.plot_burst] to format each
    *outcome*. If *outcome* has a *name* attribute (e.g., as with an ``#!python Enum``),
    that is used. Otherwise *outcome* is passed to ``#!pythonn str`` and the result is
    used.
    """
    if hasattr(outcome, "name"):
        return f"{outcome.name}"
    else:
        return f"{str(outcome)}"

outcome_name_probability_formatter(outcome: RealLike, probability: Fraction, __) -> str

Experimental

This function should be considered experimental and may change or disappear in future versions.

Formatter for use with plot_burst to display each outcome and probability (separated by a newline). If outcome has a name attribute (e.g., as with an Enum), that is used. Otherwise outcome is passed to str and the result is used. probability is passed to float and formatted to two decimal places.

Source code in anydyce/viz.py

@experimental
@beartype
def outcome_name_probability_formatter(
    outcome: RealLike, probability: Fraction, __
) -> str:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Formatter for use with [``plot_burst``][anydyce.viz.plot_burst] to display each
    outcome and probability (separated by a newline). If *outcome* has a *name*
    attribute (e.g., as with an ``#!python Enum``), that is used. Otherwise *outcome* is
    passed to ``#!pythonn str`` and the result is used. *probability* is passed to
    ``#!python float`` and formatted to two decimal places.
    """
    if hasattr(outcome, "name"):
        return f"{outcome.name}\n{float(probability):.2%}"
    else:
        return f"{str(outcome)}\n{float(probability):.2%}"

limit_for_display(h: H, cutoff) -> H

Experimental

This function should be considered experimental and may change or disappear in future versions.

Discards outcomes in h, starting with the smallest counts as long as the total discarded in proportion to h.total does not exceed cutoff. This can be useful in speeding up plots where there are large number of negligible probabilities.

>>> from anydyce.viz import limit_for_display
>>> from dyce import H
>>> from fractions import Fraction
>>> h = H({1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 6})
>>> h.total
21
>>> limit_for_display(h, cutoff=Fraction(5, 21))
H({3: 3, 4: 4, 5: 5, 6: 6})
>>> limit_for_display(h, cutoff=Fraction(6, 21))
H({4: 4, 5: 5, 6: 6})

Source code in anydyce/viz.py

@experimental
@beartype
def limit_for_display(h: H, cutoff) -> H:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Discards outcomes in *h*, starting with the smallest counts as long as the total
    discarded in proportion to ``#!python h.total`` does not exceed *cutoff*. This can
    be useful in speeding up plots where there are large number of negligible
    probabilities.

    ``` python
    >>> from anydyce.viz import limit_for_display
    >>> from dyce import H
    >>> from fractions import Fraction
    >>> h = H({1: 1, 2: 2, 3: 3, 4: 4, 5: 5, 6: 6})
    >>> h.total
    21
    >>> limit_for_display(h, cutoff=Fraction(5, 21))
    H({3: 3, 4: 4, 5: 5, 6: 6})
    >>> limit_for_display(h, cutoff=Fraction(6, 21))
    H({4: 4, 5: 5, 6: 6})

    ```
    """
    if cutoff < 0 or cutoff > 1:
        raise ValueError(f"cutoff ({cutoff}) must be between zero and one, inclusive")

    cutoff_count = int(cutoff * h.total)

    if cutoff_count == 0:
        return h

    def _cull() -> Iterator[tuple[RealLike, int]]:
        so_far = 0

        for outcome, count in sorted(h.items(), key=itemgetter(1)):
            so_far += count

            if so_far > cutoff_count:
                yield outcome, count

    return H(_cull())

probability_formatter(_, probability: Fraction, __) -> str

Experimental

This function should be considered experimental and may change or disappear in future versions.

Formatter for use with plot_burst to display the probability for each outcome (but not the outcome itself). probability is passed to float and formatted to two decimal places.

Source code in anydyce/viz.py

@experimental
@beartype
def probability_formatter(_, probability: Fraction, __) -> str:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Formatter for use with [``plot_burst``][anydyce.viz.plot_burst] to display the
    probability for each outcome (but not the outcome itself). *probability* is passed
    to ``#!python float`` and formatted to two decimal places.
    """
    return f"{float(probability):.2%}"

values_xy_for_graph_type(h: H, graph_type: TraditionalPlotType) -> tuple[tuple[RealLike, ...], tuple[float, ...]]

Source code in anydyce/viz.py

@experimental
@beartype
def values_xy_for_graph_type(
    h: H,
    graph_type: TraditionalPlotType,
) -> tuple[tuple[RealLike, ...], tuple[float, ...]]:
    outcomes, probabilities = h.distribution_xy() if h else ((), ())

    if graph_type is TraditionalPlotType.AT_LEAST:
        probabilities = tuple(accumulate(probabilities, __sub__, initial=1.0))[:-1]
    elif graph_type is TraditionalPlotType.AT_MOST:
        probabilities = tuple(accumulate(probabilities, __add__, initial=0.0))[1:]
    elif graph_type is TraditionalPlotType.NORMAL:
        pass
    else:
        assert False, f"unrecognized graph type {graph_type}"

    return outcomes, probabilities

plot_bar(ax: Axes, hs: Sequence[tuple[str, H]], graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL, alpha: float = DEFAULT_ALPHA, shadow: bool = False) -> None

Experimental

This function should be considered experimental and may change or disappear in future versions.

Plots a bar graph of hs using ax with alpha and shadow. hs is a sequence of two-tuples (pairs) of strings (labels) and H objects. Bars are interleaved and non-overlapping, so this is best suited to plots where hs contains a small number of histograms.

Source code in anydyce/viz.py

@experimental
@beartype
def plot_bar(
    ax: Axes,
    hs: Sequence[tuple[str, H]],
    graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL,
    alpha: float = DEFAULT_ALPHA,
    shadow: bool = False,
) -> None:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Plots a bar graph of *hs* using
    [*ax*](https://matplotlib.org/stable/api/axes_api.html#the-axes-class) with *alpha*
    and *shadow*. *hs* is a sequence of two-tuples (pairs) of strings (labels) and ``H``
    objects. Bars are interleaved and non-overlapping, so this is best suited to plots
    where *hs* contains a small number of histograms.
    """
    ax.yaxis.set_major_formatter(matplotlib.ticker.PercentFormatter(xmax=1))
    width = 0.8
    bar_kw: dict[str, Any] = dict(alpha=alpha)

    if hs:
        bar_kw.update(dict(width=width / len(hs)))

    if shadow:
        bar_kw.update(
            dict(
                path_effects=[
                    matplotlib.patheffects.withSimplePatchShadow(),
                    matplotlib.patheffects.Normal(),
                ]
            )
        )

    unique_outcomes = sorted(set(chain.from_iterable(h.outcomes() for _, h in hs)))

    if hs:
        ax.set_xticks(unique_outcomes)  # type: ignore [arg-type]
        ax.set_xlim(
            (
                min(unique_outcomes, default=0) - 1.0,
                max(unique_outcomes, default=0) + 1.0,
            )
        )

    for i, (label, h) in enumerate(hs):
        # Orient to the middle of each bar ((i + 0.5) ... ) whose width is an even share
        # of the total width (... * width / len(hs) ...) and center the whole cluster of
        # bars around the data point (... - width / 2)
        adj = (i + 0.5) * width / len(hs) - width / 2
        outcomes, values = values_xy_for_graph_type(h, graph_type)
        ax.bar(
            [outcome + adj for outcome in outcomes],
            values,
            label=label,
            **bar_kw,
        )

plot_line(ax: Axes, hs: Sequence[tuple[str, H]], graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL, alpha: float = DEFAULT_ALPHA, shadow: bool = False, markers: str = 'o') -> None

Experimental

This function should be considered experimental and may change or disappear in future versions.

Plots a line graph of hs using ax with alpha and shadow. hs is a sequence of two-tuples (pairs) of strings (labels) and dyce.H objects. markers is cycled through when creating each line. For example, if markers is "o+", the first histogram in hs will be plotted with a circle, the second will be plotted with a plus, the third will be plotted with a circle, the fourth will be plotted with a plus, and so on.

Source code in anydyce/viz.py

@experimental
@beartype
def plot_line(
    ax: Axes,
    hs: Sequence[tuple[str, H]],
    graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL,
    alpha: float = DEFAULT_ALPHA,
    shadow: bool = False,
    markers: str = "o",
) -> None:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Plots a line graph of *hs* using
    [*ax*](https://matplotlib.org/stable/api/axes_api.html#the-axes-class) with *alpha*
    and *shadow*. *hs* is a sequence of two-tuples (pairs) of strings (labels) and
    ``#!python dyce.H`` objects. *markers* is cycled through when creating each line.
    For example, if *markers* is ``#!python "o+"``, the first histogram in *hs* will be
    plotted with a circle, the second will be plotted with a plus, the third will be
    plotted with a circle, the fourth will be plotted with a plus, and so on.
    """
    ax.yaxis.set_major_formatter(matplotlib.ticker.PercentFormatter(xmax=1))
    plot_kw: dict[str, Any] = dict(alpha=alpha)

    if shadow:
        plot_kw.update(
            dict(
                path_effects=[
                    matplotlib.patheffects.SimpleLineShadow(),
                    matplotlib.patheffects.Normal(),
                ]
            )
        )

    unique_outcomes = sorted(set(chain.from_iterable(h.outcomes() for _, h in hs)))

    if hs:
        ax.set_xticks(unique_outcomes)  # type: ignore [arg-type]
        ax.set_xlim(
            (
                min(unique_outcomes, default=0) - 0.5,
                max(unique_outcomes, default=0) + 0.5,
            )
        )

    for (label, h), marker in zip(hs, cycle(markers if markers else " ")):
        outcomes, values = values_xy_for_graph_type(h, graph_type)
        ax.plot(outcomes, values, label=label, marker=marker, **plot_kw)  # type: ignore [arg-type]

plot_scatter(ax: Axes, hs: Sequence[tuple[str, H]], graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL, alpha: float = DEFAULT_ALPHA, shadow: bool = False, markers: str = '<>v^dPXo') -> None

Experimental

This function should be considered experimental and may change or disappear in future versions.

Plots a scatter graph of hs using ax with alpha and shadow. hs is a sequence of two-tuples (pairs) of strings (labels) and dyce.H objects. markers is cycled through when creating each line. For example, if markers is "o+", the first histogram in hs will be plotted with a circle, the second will be plotted with a plus, the third will be plotted with a circle, the fourth will be plotted with a plus, and so on.

Source code in anydyce/viz.py

@experimental
@beartype
def plot_scatter(
    ax: Axes,
    hs: Sequence[tuple[str, H]],
    graph_type: TraditionalPlotType = TraditionalPlotType.NORMAL,
    alpha: float = DEFAULT_ALPHA,
    shadow: bool = False,
    markers: str = "<>v^dPXo",
) -> None:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Plots a scatter graph of *hs* using
    [*ax*](https://matplotlib.org/stable/api/axes_api.html#the-axes-class) with *alpha*
    and *shadow*. *hs* is a sequence of two-tuples (pairs) of strings (labels) and
    ``dyce.H`` objects. *markers* is cycled through when creating each line. For
    example, if *markers* is ``#!python "o+"``, the first histogram in *hs* will be
    plotted with a circle, the second will be plotted with a plus, the third will be
    plotted with a circle, the fourth will be plotted with a plus, and so on.
    """
    ax.yaxis.set_major_formatter(matplotlib.ticker.PercentFormatter(xmax=1))
    scatter_kw: dict[str, Any] = dict(alpha=alpha)

    if shadow:
        scatter_kw.update(
            dict(
                path_effects=[
                    matplotlib.patheffects.SimpleLineShadow(),
                    matplotlib.patheffects.Normal(),
                ]
            )
        )

    unique_outcomes = sorted(set(chain.from_iterable(h.outcomes() for _, h in hs)))

    if hs:
        ax.set_xticks(unique_outcomes)  # type: ignore [arg-type]
        ax.set_xlim(
            (
                min(unique_outcomes, default=0) - 0.5,
                max(unique_outcomes, default=0) + 0.5,
            )
        )

    for (label, h), marker in zip(hs, cycle(markers if markers else " ")):
        outcomes, values = values_xy_for_graph_type(h, graph_type)
        ax.scatter(outcomes, values, label=label, marker=marker, **scatter_kw)  # type: ignore [arg-type]

plot_burst(ax: Axes, h_inner: H, h_outer: Optional[H] = None, title: Optional[str] = None, inner_formatter: HFormatterT = outcome_name_formatter, inner_cmap: Union[str, matplotlib.colors.Colormap] = DEFAULT_CMAP_BURST_INNER, outer_formatter: Optional[HFormatterT] = None, outer_cmap: Union[str, matplotlib.colors.Colormap, None] = None, text_color: str = DEFAULT_COLOR_TEXT, alpha: float = DEFAULT_ALPHA) -> None

Experimental

This function should be considered experimental and may change or disappear in future versions.

Creates a dual, overlapping, cocentric pie chart in ax, which can be useful for visualizing relative probability distributions. Examples can be found in Additional interfaces.

Source code in anydyce/viz.py

@experimental
@beartype
def plot_burst(
    ax: Axes,
    h_inner: H,
    h_outer: Optional[H] = None,
    title: Optional[str] = None,
    inner_formatter: HFormatterT = outcome_name_formatter,
    inner_cmap: Union[str, matplotlib.colors.Colormap] = DEFAULT_CMAP_BURST_INNER,
    outer_formatter: Optional[HFormatterT] = None,
    outer_cmap: Union[str, matplotlib.colors.Colormap, None] = None,
    text_color: str = DEFAULT_COLOR_TEXT,
    alpha: float = DEFAULT_ALPHA,
) -> None:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Creates a dual, overlapping, cocentric pie chart in
    [*ax*](https://matplotlib.org/stable/api/axes_api.html#the-axes-class), which can be
    useful for visualizing relative probability distributions. Examples can be found in
    [Additional interfaces](index.md#additional-interfaces).
    """
    h_outer = h_inner if h_outer is None else h_outer

    if outer_formatter is None:
        if h_outer == h_inner:
            outer_formatter = probability_formatter
        else:
            outer_formatter = inner_formatter

    outer_cmap = inner_cmap if outer_cmap is None else outer_cmap

    inner = (
        (
            (
                inner_formatter(outcome, probability, h_inner)
                if probability >= _LABEL_LIM
                else ""
            ),
            probability,
        )
        for outcome, probability in h_inner.distribution()
    )

    inner_labels, inner_values = tuple(zip(*inner)) if h_inner else ((), ())
    inner_colors = graph_colors(inner_cmap, inner_values, alpha)

    outer = (
        (
            (
                outer_formatter(outcome, probability, h_outer)
                if probability >= _LABEL_LIM
                else ""
            ),
            probability,
        )
        for outcome, probability in h_outer.distribution()
    )

    outer_labels, outer_values = tuple(zip(*outer)) if h_outer else ((), ())
    outer_colors = graph_colors(outer_cmap, outer_values, alpha)

    if title:
        ax.set_title(
            title,
            fontdict={"fontweight": "bold", "color": text_color},
            pad=24.0,
        )

    ax.pie(
        outer_values,
        labels=outer_labels,
        radius=1.0,
        labeldistance=1.15,
        startangle=90,
        colors=outer_colors,
        textprops=dict(color=text_color),
        wedgeprops=dict(width=0.8, edgecolor=text_color),
    )
    ax.pie(
        inner_values,
        labels=inner_labels,
        radius=0.85,
        labeldistance=0.7,
        startangle=90,
        colors=inner_colors,
        textprops=dict(color=text_color),
        wedgeprops=dict(width=0.5, edgecolor=text_color),
    )
    ax.set(aspect="equal")

plot_burst_subplot(h_inner: H, h_outer: Optional[H] = None, title: Optional[str] = None, inner_formatter: HFormatterT = outcome_name_formatter, inner_cmap: Union[str, matplotlib.colors.Colormap] = DEFAULT_CMAP_BURST_INNER, outer_formatter: Optional[HFormatterT] = None, outer_cmap: Union[str, matplotlib.colors.Colormap, None] = None, text_color: str = DEFAULT_COLOR_TEXT, alpha: float = DEFAULT_ALPHA) -> tuple[Figure, Axes]

Experimental

This function should be considered experimental and may change or disappear in future versions.

Wrapper around plot_burst that creates a figure, axis pair, calls matplotlib.pyplot.tight_layout, and returns the pair.

Source code in anydyce/viz.py

@experimental
@beartype
def plot_burst_subplot(
    h_inner: H,
    h_outer: Optional[H] = None,
    title: Optional[str] = None,
    inner_formatter: HFormatterT = outcome_name_formatter,
    inner_cmap: Union[str, matplotlib.colors.Colormap] = DEFAULT_CMAP_BURST_INNER,
    outer_formatter: Optional[HFormatterT] = None,
    outer_cmap: Union[str, matplotlib.colors.Colormap, None] = None,
    text_color: str = DEFAULT_COLOR_TEXT,
    alpha: float = DEFAULT_ALPHA,
) -> tuple[Figure, Axes]:
    r"""
    !!! warning "Experimental"

        This function should be considered experimental and may change or disappear in
        future versions.

    Wrapper around [``plot_burst``][anydyce.viz.plot_burst] that creates a figure, axis
    pair, calls
    [``matplotlib.pyplot.tight_layout``](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.tight_layout.html),
    and returns the pair.
    """
    fig, ax = matplotlib.pyplot.subplots()
    plot_burst(
        ax,
        h_inner,
        h_outer,
        title,
        inner_formatter,
        inner_cmap,
        outer_formatter,
        outer_cmap,
        text_color,
        alpha,
    )

    with warnings.catch_warnings():
        warnings.simplefilter("ignore")
        matplotlib.pyplot.tight_layout()

    return fig, ax