"""
==========================================================
:mod:`polyphys.viz.helpers`
==========================================================
The :mod:`polyphys.viz.helpers` module holds the matplotlib helpers the
studies' multi-panel figures use: a rule for placing an axis's ticks, proxy
legend handles, a legend moved into chosen panels, and a band shaded under
each line. It needs matplotlib, which the ``viz`` extra installs, and raises
:exc:`ImportError` with that hint when it is missing.
Ticks
=====
:func:`set_xticks` and :func:`set_yticks` place the major ticks of one axis
by one rule. Given `lower`, `upper`, and `step`:
- the ticks are :math:`t_k = \\mathrm{lower} + k \\, \\mathrm{step}` for
:math:`k = 0, 1, \\dots, \\lfloor (\\mathrm{upper} - \\mathrm{lower}) /
\\mathrm{step} \\rfloor`, so the last tick is `upper` when `step` divides
the span;
- the *tolerance* is ``step / 10`` rounded down to its first non-zero
digit, by :func:`polyphys.manage.utils.round_down_first_non_zero`; a tick
closer to zero than the tolerance is written as exactly ``0.0``, so
``-5.6e-17`` never appears as a label;
- the axis limits are ``(lower - tolerance, upper + tolerance)``, a frame
that keeps the first and last ticks off the axes' edges;
- the labels are the ticks rounded to `decimals` places, or hidden.
The ticks are not rounded to multiples of a power of ten; the caller
chooses `lower`, `upper`, and `step` with that in mind.
Legends
=======
- :func:`color_handles` and :func:`line_handles` make *proxy* handles,
artists that draw nothing on the axes and exist only to sit in a legend,
so a figure can carry one legend for its colors and another for its line
styles or markers, whatever the plotting call produced.
- :func:`move_legend_to_axes` takes an existing legend, such as the figure
legend a facet grid draws outside its panels, and re-creates it inside
chosen panels.
- :func:`band_under_lines` shades a band, such as a confidence interval,
under each line already drawn on an axes, in that line's color.
Examples
========
>>> import matplotlib
>>> matplotlib.use("Agg")
>>> import matplotlib.pyplot as plt
>>> from polyphys.viz.helpers import color_handles, set_xticks
>>> fig, ax = plt.subplots()
>>> set_xticks(ax, 0.0, 1.0, 0.25)
array([0. , 0.25, 0.5 , 0.75, 1. ])
>>> [float(limit) for limit in ax.get_xlim()]
[-0.02, 1.02]
>>> handles = color_handles(["bug", "crowder"], ["#4477AA", "#EE6677"])
>>> [text.get_text() for text in ax.legend(handles=handles).get_texts()]
['bug', 'crowder']
>>> plt.close(fig)
"""
import numbers
from typing import Any, Literal, Optional, Sequence, Union
import numpy as np
from ..manage.utils import round_down_first_non_zero
try:
import matplotlib # noqa: F401
except ImportError as error: # pragma: no cover - depends on the install
raise ImportError(
"polyphys.viz.helpers needs matplotlib; install it with "
"python -m pip install 'polyphys[viz]'.") from error
from matplotlib.axes import Axes
from matplotlib.collections import PolyCollection
from matplotlib.legend import Legend
from matplotlib.lines import Line2D
from matplotlib.patches import Patch
__all__ = ["band_under_lines", "color_handles", "line_handles",
"move_legend_to_axes", "set_xticks", "set_yticks"]
def _ticks(lower: float, upper: float, step: float) -> tuple[Any, float]:
"""Return the tick positions and the tolerance of the ticks rule."""
if not lower < upper:
raise ValueError(
f"lower must be below upper, got lower={lower} and "
f"upper={upper}.")
span = upper - lower
if step <= 0 or step >= span:
raise ValueError(
f"step must be positive and smaller than the span "
f"upper - lower = {span}, got step={step}.")
tolerance = round_down_first_non_zero(step / 10)
# The 1e-9 absorbs the float error of a span that step divides exactly.
count = int(np.floor(span / step + 1e-9)) + 1
ticks = lower + step * np.arange(count)
ticks = np.where(np.abs(ticks) < tolerance, 0.0, ticks)
return ticks, tolerance
def _set_ticks(
ax: Axes,
which: Literal["x", "y"],
lower: float,
upper: float,
step: float,
labels: bool,
decimals: int,
text_kwargs: dict[str, Any],
) -> Any:
"""Apply the ticks rule to the x or y axis of `ax`."""
ticks, tolerance = _ticks(lower, upper, step)
texts = ([str(v) for v in np.around(ticks, decimals)] if labels
else [""] * len(ticks))
if which == "x":
ax.set_xlim(lower - tolerance, upper + tolerance)
ax.set_xticks(ticks)
ax.set_xticklabels(texts, **text_kwargs)
else:
ax.set_ylim(lower - tolerance, upper + tolerance)
ax.set_yticks(ticks)
ax.set_yticklabels(texts, **text_kwargs)
return ticks
[docs]
def set_xticks(
ax: Axes,
lower: float,
upper: float,
step: float,
*,
labels: bool = True,
decimals: int = 3,
**text_kwargs: Any,
) -> Any:
"""
Place the major x ticks of `ax` every `step` from `lower` to `upper`.
The ticks, the tolerance that frames them, and the labels follow the
rule in the module docstring. Time and space are :math:`O(n)` in the
number of ticks.
Parameters
----------
ax : matplotlib.axes.Axes
The axes whose x axis is set.
lower, upper : float
The first tick and the largest tick value, in data units;
``lower < upper``.
step : float
The distance between ticks, positive and smaller than
``upper - lower``.
labels : bool, default True
Whether the ticks are labeled; ``False`` hides every label.
decimals : int, default 3
The number of decimals the labels are rounded to.
**text_kwargs
Passed to :meth:`matplotlib.axes.Axes.set_xticklabels`, such as
``fontsize``.
Returns
-------
numpy.ndarray
The tick positions, shape ``(n_ticks,)``.
Raises
------
ValueError
If ``lower >= upper``, or `step` is not positive and smaller than
``upper - lower``.
Examples
--------
>>> import matplotlib
>>> matplotlib.use("Agg")
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> set_xticks(ax, -0.2, 0.2, 0.1, decimals=1)
array([-0.2, -0.1, 0. , 0.1, 0.2])
>>> [label.get_text() for label in ax.get_xticklabels()]
['-0.2', '-0.1', '0.0', '0.1', '0.2']
>>> plt.close(fig)
"""
return _set_ticks(ax, "x", lower, upper, step, labels, decimals,
text_kwargs)
[docs]
def set_yticks(
ax: Axes,
lower: float,
upper: float,
step: float,
*,
labels: bool = True,
decimals: int = 3,
**text_kwargs: Any,
) -> Any:
"""
Place the major y ticks of `ax` every `step` from `lower` to `upper`.
The y-axis twin of :func:`set_xticks`, with the same rule, parameters,
return value, and errors; `text_kwargs` go to
:meth:`matplotlib.axes.Axes.set_yticklabels`.
Parameters
----------
ax : matplotlib.axes.Axes
The axes whose y axis is set.
lower, upper : float
The first tick and the largest tick value; ``lower < upper``.
step : float
The distance between ticks, positive and smaller than
``upper - lower``.
labels : bool, default True
Whether the ticks are labeled.
decimals : int, default 3
The number of decimals the labels are rounded to.
**text_kwargs
Passed to :meth:`matplotlib.axes.Axes.set_yticklabels`.
Returns
-------
numpy.ndarray
The tick positions, shape ``(n_ticks,)``.
Examples
--------
>>> import matplotlib
>>> matplotlib.use("Agg")
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> set_yticks(ax, 0.0, 1.0, 0.5, labels=False)
array([0. , 0.5, 1. ])
>>> [float(limit) for limit in ax.get_ylim()]
[-0.05, 1.05]
>>> plt.close(fig)
"""
return _set_ticks(ax, "y", lower, upper, step, labels, decimals,
text_kwargs)
def _per_label(
name: str,
values: Union[None, str, float, Sequence[Any]],
n_labels: int,
) -> list[Any]:
"""Return one value per label: one value repeated, or a matching list.
One value is None, a string, a real number (NumPy scalars included), a
tuple of real numbers such as an RGB or RGBA color, or a dash tuple
``(offset, (on, off, ...))``. Anything else is a sequence with one entry
per label.
"""
if _is_one_value(values):
return [values] * n_labels
values = list(values)
if len(values) != n_labels:
raise ValueError(
f"{name} has {len(values)} entries for {n_labels} labels.")
return values
def _is_one_value(value: Any) -> bool:
"""Return True if `value` is one style, not one per label."""
if value is None or isinstance(value, (str, numbers.Real)):
return True
if not isinstance(value, tuple):
return False
if all(isinstance(item, numbers.Real) for item in value):
return True
return (len(value) == 2 and isinstance(value[0], numbers.Real)
and isinstance(value[1], (tuple, list))
and all(isinstance(item, numbers.Real) for item in value[1]))
[docs]
def color_handles(
labels: Sequence[str],
colors: Any,
**patch_kwargs: Any,
) -> list[Patch]:
"""
Make one filled :class:`~matplotlib.patches.Patch` per label.
The patches are proxy handles for a legend keyed by color. Time and
space are :math:`O(n)` in the number of labels.
Parameters
----------
labels : sequence of str
The legend entries.
colors : matplotlib color or sequence of matplotlib colors
One color for every label, a name or a tuple of numbers such as the
RGB triple ``(0.1, 0.2, 0.3)``; or a list, or another sequence, with
one color per label, in the same order.
**patch_kwargs
Passed to every :class:`~matplotlib.patches.Patch`, such as
``alpha``.
Returns
-------
list of matplotlib.patches.Patch
The handles, one per label, for the ``handles`` argument of
:meth:`matplotlib.axes.Axes.legend`.
Raises
------
ValueError
If `colors` is a sequence of colors whose length differs from that
of `labels`.
Examples
--------
>>> patches = color_handles(["low", "high"], ["#4477AA", "#EE6677"],
... alpha=0.5)
>>> [patch.get_label() for patch in patches]
['low', 'high']
>>> patches[0].get_alpha()
0.5
One RGB tuple colors every label:
>>> patches = color_handles(["a", "b"], (0.0, 0.5, 1.0))
>>> [patch.get_facecolor()[:3] for patch in patches]
[(0.0, 0.5, 1.0), (0.0, 0.5, 1.0)]
"""
colors = _per_label("colors", colors, len(labels))
return [Patch(label=label, color=color, **patch_kwargs)
for label, color in zip(labels, colors)]
[docs]
def line_handles(
labels: Sequence[str],
*,
linestyles: Union[None, str, Sequence[Any]] = None,
linewidths: Union[None, float, Sequence[float]] = None,
markers: Union[None, str, Sequence[Any]] = None,
color: Any = "black",
**line_kwargs: Any,
) -> list[Line2D]:
"""
Make one empty :class:`~matplotlib.lines.Line2D` per label.
The lines are proxy handles for a legend keyed by line style, width,
or marker. Each of `linestyles`, `linewidths`, and `markers` is either
one value, used for every label, a sequence with one entry per label,
or ``None``, which leaves that attribute at matplotlib's default. One
value is a string, a number, or a dash tuple such as ``(0, (5, 2))``;
a list, or a tuple of other items, is one entry per label. Time
and space are :math:`O(n)` in the number of labels.
Parameters
----------
labels : sequence of str
The legend entries.
linestyles : str or sequence, optional
The line style of each handle, such as ``'-'`` or ``'--'``.
linewidths : float or sequence of float, optional
The line width of each handle, in points.
markers : str or sequence, optional
The marker of each handle, such as ``'o'`` or ``'^'``.
color : matplotlib color, default 'black'
The color of every handle.
**line_kwargs
Passed to every :class:`~matplotlib.lines.Line2D`, such as
``markersize``.
Returns
-------
list of matplotlib.lines.Line2D
The handles, one per label.
Raises
------
ValueError
If a sequence among `linestyles`, `linewidths`, and `markers` does
not have one entry per label.
Examples
--------
>>> lines = line_handles(["ring", "linear"], linestyles=["-", "--"],
... markers="o", linewidths=2)
>>> [(line.get_label(), line.get_linestyle(), line.get_marker())
... for line in lines]
[('ring', '-', 'o'), ('linear', '--', 'o')]
"""
n_labels = len(labels)
styles = _per_label("linestyles", linestyles, n_labels)
widths = _per_label("linewidths", linewidths, n_labels)
marks = _per_label("markers", markers, n_labels)
handles = []
for label, style, width, mark in zip(labels, styles, widths, marks):
kwargs = {"linestyle": style, "linewidth": width, "marker": mark}
kwargs = {k: v for k, v in kwargs.items() if v is not None}
handles.append(
Line2D([], [], label=label, color=color, **kwargs,
**line_kwargs))
return handles
[docs]
def move_legend_to_axes(
legend: Legend,
axes: Sequence[Axes],
locs: Sequence[Any],
*,
title: Optional[str] = None,
**legend_kwargs: Any,
) -> list[Legend]:
"""
Remove `legend` and re-create it inside each of `axes`.
The new legends carry the handles, labels, and title of `legend`; each
replaces the legend its axes had. This moves, for instance, the legend
a seaborn facet grid draws beside its panels into one or more panels.
Time and space are :math:`O(n_\\mathrm{axes} \\, n_\\mathrm{entries})`.
Parameters
----------
legend : matplotlib.legend.Legend
The legend to move; it is removed from its figure or axes.
axes : sequence of matplotlib.axes.Axes
The axes that receive a copy each.
locs : sequence
One legend location per axes, as the ``loc`` argument of
:meth:`matplotlib.axes.Axes.legend` takes it.
title : str, optional
A new title; by default the title of `legend` is kept.
**legend_kwargs
Passed to every :meth:`matplotlib.axes.Axes.legend` call, such as
``frameon``.
Returns
-------
list of matplotlib.legend.Legend
The new legends, in the order of `axes`.
Raises
------
ValueError
If `axes` and `locs` differ in length.
Examples
--------
>>> import matplotlib
>>> matplotlib.use("Agg")
>>> import matplotlib.pyplot as plt
>>> fig, (left, right) = plt.subplots(ncols=2)
>>> _ = left.plot([0, 1], [0, 1], label="rise")
>>> outer = fig.legend(title="curves")
>>> inner = move_legend_to_axes(outer, [right], ["upper left"])
>>> fig.legends
[]
>>> [text.get_text() for text in right.get_legend().get_texts()]
['rise']
>>> right.get_legend().get_title().get_text()
'curves'
>>> plt.close(fig)
"""
if len(axes) != len(locs):
raise ValueError(
f"locs has {len(locs)} entries for {len(axes)} axes.")
entries = [(handle, text.get_text())
for handle, text in zip(legend.legend_handles,
legend.get_texts())
if handle is not None]
handles = [handle for handle, _ in entries]
labels = [label for _, label in entries]
new_title = legend.get_title().get_text() if title is None else title
legend.remove()
return [ax.legend(handles, labels, loc=loc, title=new_title,
**legend_kwargs)
for ax, loc in zip(axes, locs)]
[docs]
def band_under_lines(
ax: Axes,
bands: Sequence[tuple[Any, Any]],
*,
alpha: float = 0.25,
**fill_kwargs: Any,
) -> list[PolyCollection]:
"""
Shade one band under each line of `ax`, in that line's color.
``bands[i]`` is the pair ``(lower, upper)`` of the band under
``ax.lines[i]``, each an array over that line's x data; the band is
drawn with :meth:`matplotlib.axes.Axes.fill_between`. Lines beyond
``len(bands)`` get no band. Time and space are :math:`O(n_\\mathrm{lines}
\\, n_\\mathrm{points})`.
Parameters
----------
ax : matplotlib.axes.Axes
The axes whose lines are shaded, in drawing order.
bands : sequence of pairs of array_like
The lower and upper edge of each band, shape ``(n_points,)`` each,
matching the x data of the line.
alpha : float, default 0.25
The opacity of every band.
**fill_kwargs
Passed to every :meth:`matplotlib.axes.Axes.fill_between` call,
such as ``linewidth``.
Returns
-------
list of matplotlib.collections.PolyCollection
The bands, in the order of the lines.
Raises
------
ValueError
If there are more bands than lines, or a band edge's length differs
from its line's number of points.
Examples
--------
>>> import matplotlib
>>> matplotlib.use("Agg")
>>> import matplotlib.pyplot as plt
>>> fig, ax = plt.subplots()
>>> _ = ax.plot([0, 1, 2], [1, 1, 1], color="#4477AA")
>>> bands = band_under_lines(ax, [([0.5, 0.5, 0.5], [1.5, 1.5, 1.5])])
>>> len(bands)
1
>>> bands[0].get_facecolor()[0].round(2).tolist()
[0.27, 0.47, 0.67, 0.25]
>>> plt.close(fig)
"""
lines = list(ax.lines)
if len(bands) > len(lines):
raise ValueError(
f"{len(bands)} bands were given for {len(lines)} lines.")
collections: list[PolyCollection] = []
for line, (lower, upper) in zip(lines, bands):
x = np.asarray(line.get_xdata(), dtype=float)
lower = np.asarray(lower, dtype=float)
upper = np.asarray(upper, dtype=float)
if lower.shape != x.shape or upper.shape != x.shape:
raise ValueError(
f"a band has edges of shape {lower.shape} and "
f"{upper.shape} for a line of {x.shape[0]} points.")
collections.append(
ax.fill_between(x, lower, upper, color=line.get_color(),
alpha=alpha, **fill_kwargs))
return collections