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.

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.

Inefficiently (i.e., \(O \left( {n} ^ {2} \right)\)) calculates cumulative probability pairs for outcome in h. This can be useful for passing as the outer_formatter value to plot_burst.

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.

    Inefficiently (i.e., $O \left( {n} ^ {2} \right)$) calculates cumulative probability
    pairs for *outcome* in *h*. This can be useful for passing as the *outer_formatter*
    value to [``plot_burst``][anydyce.viz.plot_burst].
    """
    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%}"

limit_for_display(h: H, cutoff: Fraction = _CUTOFF_LIM) -> 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: Fraction = _CUTOFF_LIM) -> 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())

values_xy_for_graph_type(h: H, graph_type: GraphType) -> Tuple[Tuple[RealLike, ...], Tuple[float, ...]]

Source code in anydyce/viz.py

@experimental
@beartype
def values_xy_for_graph_type(
    h: H, graph_type: GraphType
) -> Tuple[Tuple[RealLike, ...], Tuple[float, ...]]:
    outcomes, probabilities = h.distribution_xy()

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

    return outcomes, probabilities

plot_bar(ax: AxesT, hs: Sequence[Tuple[str, H]], graph_type: GraphType = GraphType.NORMAL, alpha: float = DEFAULT_GRAPH_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: AxesT,
    hs: Sequence[Tuple[str, H]],
    graph_type: GraphType = GraphType.NORMAL,
    alpha: float = DEFAULT_GRAPH_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, width=width / len(hs))

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

    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: AxesT, hs: Sequence[Tuple[str, H]], graph_type: GraphType = GraphType.NORMAL, alpha: float = DEFAULT_GRAPH_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: AxesT,
    hs: Sequence[Tuple[str, H]],
    graph_type: GraphType = GraphType.NORMAL,
    alpha: float = DEFAULT_GRAPH_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(),
                ]
            )
        )

    for (label, h), marker in zip(hs, cycle(markers)):
        outcomes, values = values_xy_for_graph_type(h, graph_type)
        ax.plot(outcomes, values, label=label, marker=marker, **plot_kw)

plot_scatter(ax: AxesT, hs: Sequence[Tuple[str, H]], graph_type: GraphType = GraphType.NORMAL, alpha: float = DEFAULT_GRAPH_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: AxesT,
    hs: Sequence[Tuple[str, H]],
    graph_type: GraphType = GraphType.NORMAL,
    alpha: float = DEFAULT_GRAPH_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(),
                ]
            )
        )

    for (label, h), marker in zip(hs, cycle(markers)):
        outcomes, values = values_xy_for_graph_type(h, graph_type)
        ax.scatter(outcomes, values, label=label, marker=marker, **scatter_kw)

plot_burst(ax: AxesT, h_inner: H, h_outer: Optional[H] = None, title: Optional[str] = None, inner_formatter: HFormatterT = _outcome_name_formatter, inner_color: str = DEFAULT_GRAPH_COLOR, outer_formatter: Optional[HFormatterT] = None, outer_color: Optional[str] = None, text_color: str = DEFAULT_TEXT_COLOR, alpha: float = DEFAULT_BURST_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: AxesT,
    h_inner: H,
    h_outer: Optional[H] = None,
    title: Optional[str] = None,
    inner_formatter: HFormatterT = _outcome_name_formatter,
    inner_color: str = DEFAULT_GRAPH_COLOR,
    outer_formatter: Optional[HFormatterT] = None,
    outer_color: Optional[str] = None,
    text_color: str = DEFAULT_TEXT_COLOR,
    alpha: float = DEFAULT_BURST_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_color = inner_color if outer_color is None else outer_color

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

    inner_labels, inner_values = list(zip(*inner))
    inner_colors = graph_colors(inner_color, 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 = list(zip(*outer))
    outer_colors = graph_colors(outer_color, 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_color: str = DEFAULT_GRAPH_COLOR, outer_formatter: Optional[HFormatterT] = None, outer_color: Optional[str] = None, text_color: str = DEFAULT_TEXT_COLOR, alpha: float = DEFAULT_BURST_ALPHA) -> Tuple[FigureT, AxesT]

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_color: str = DEFAULT_GRAPH_COLOR,
    outer_formatter: Optional[HFormatterT] = None,
    outer_color: Optional[str] = None,
    text_color: str = DEFAULT_TEXT_COLOR,
    alpha: float = DEFAULT_BURST_ALPHA,
) -> Tuple[FigureT, AxesT]:
    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_color,
        outer_formatter,
        outer_color,
        text_color,
        alpha,
    )

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

    return fig, ax