dyce.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.

display_burst(ax: Axes, h_inner: H, outer: Optional[Union[H, Iterable[LabelT]]] = None, desc: Optional[str] = None, inner_color: str = 'RdYlGn_r', outer_color: Optional[str] = None, text_color: str = 'black', alpha: float = 0.5) -> None

Experimental

This method 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. See the visualization tutorial for examples.

Source code in dyce/viz.py

@experimental
@beartype
def display_burst(
    ax: Axes,
    h_inner: H,
    outer: Optional[Union[H, Iterable[LabelT]]] = None,
    desc: Optional[str] = None,
    inner_color: str = DEFAULT_GRAPH_COLOR,
    outer_color: Optional[str] = None,
    text_color: str = DEFAULT_TEXT_COLOR,
    alpha: float = DEFAULT_GRAPH_ALPHA,
) -> None:
    r"""
    !!! warning "Experimental"

        This method 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. See the
    [visualization tutorial](countin.md#visualization) for examples.
    """
    assert matplotlib
    inner_colors = graph_colors(inner_color, h_inner, alpha)

    if outer is None:
        outer = (
            (f"{float(v):.2%}" if v >= _HIDE_LIM else "", v)
            for _, v in h_inner.distribution()
        )
    elif isinstance(outer, H):
        outer = ((str(outcome), count) for outcome, count in outer.distribution())

    outer_labels, outer_values = list(zip(*outer))
    outer_colors = graph_colors(
        inner_color if outer_color is None else outer_color,
        outer_values,
        alpha,
    )

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

    ax.pie(
        outer_values,
        labels=outer_labels,
        radius=1.0,
        labeldistance=1.1,
        startangle=90,
        colors=outer_colors,
        wedgeprops=dict(width=0.8, edgecolor=text_color),
    )
    ax.pie(
        h_inner.values(),
        labels=h_inner,
        radius=0.9,
        labeldistance=0.8,
        startangle=90,
        colors=inner_colors,
        textprops=dict(color=text_color),
        wedgeprops=dict(width=0.6, edgecolor=text_color),
    )
    ax.set(aspect="equal")

labels_cumulative(h: H) -> Iterator[LabelT]

Experimental

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

Enumerates label, probability pairs for each outcome in h where each label contains several percentages. This can be useful for passing as the outer value to either display_burst or plot_burst.

Source code in dyce/viz.py

@experimental
@beartype
def labels_cumulative(
    h: H,
) -> Iterator[LabelT]:
    r"""
    !!! warning "Experimental"

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

    Enumerates label, probability pairs for each outcome in *h* where each label
    contains several percentages. This can be useful for passing as the *outer* value to
    either [``display_burst``][dyce.viz.display_burst] or
    [``plot_burst``][dyce.viz.plot_burst].
    """
    le_total, ge_total = 0.0, 1.0
    for outcome, probability in h.distribution():
        le_total += probability
        label = f"{outcome} {float(probability):.2%}; ≥{le_total:.2%}; ≤{ge_total:.2%}"
        ge_total -= probability
        yield (label, probability)

plot_burst(h_inner: H, outer: Optional[Union[H, Iterable[LabelT]]] = None, desc: Optional[str] = None, inner_color: str = 'RdYlGn_r', outer_color: Optional[str] = None, text_color: str = 'black', alpha: float = 0.5) -> Tuple[Figure, Axes]

Experimental

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

Wrapper around display_burst that creates a figure, axis pair and calls matplotlib.pyplot.tight_layout on the result.

Source code in dyce/viz.py

@experimental
@beartype
def plot_burst(
    h_inner: H,
    outer: Optional[Union[H, Iterable[LabelT]]] = None,
    desc: Optional[str] = None,
    inner_color: str = DEFAULT_GRAPH_COLOR,
    outer_color: Optional[str] = None,
    text_color: str = DEFAULT_TEXT_COLOR,
    alpha: float = DEFAULT_GRAPH_ALPHA,
) -> Tuple[Figure, Axes]:
    r"""
    !!! warning "Experimental"

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

    Wrapper around [``display_burst``][dyce.viz.display_burst] that creates a figure,
    axis pair and calls
    [``matplotlib.pyplot.tight_layout``](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.tight_layout.html)
    on the result.
    """
    assert matplotlib
    fig, ax = matplotlib.pyplot.subplots()
    display_burst(ax, h_inner, outer, desc, inner_color, outer_color, text_color, alpha)
    matplotlib.pyplot.tight_layout()

    return fig, ax