myplotlib 1.7.0__py3-none-any.whl

myplotlib/plots.py

@@ -0,0 +1,658 @@
+"""
+`myplotlib.plots`
+
+a collection of handy plotting functions bound around `matplotlib` with lots of nice perks.
+
+* dataPlot .................. : plot generic x & y 1d data (pass an `ax` method)
+* scatter ................... : scatter plot (`dataPlot` with `ax.scatter`)
+* plot ...................... : regular plot (`dataPlot` with `ax.plot`)
+* plot2d .................... : 2d plot using `imshow`
+* plotVectorField ........... : 2d plot with vector field
+
+docstrings are available for all of the functions. type, e.g., `dataPlot?` to read about the arguments passed.
+"""
+
+from typing import TypeAlias, Any, TypedDict, Callable
+import numpy as np
+import matplotlib.colors as mcolors
+from matplotlib.axes._axes import Axes as pltAxes
+
+LimTypeWithNone: TypeAlias = tuple[float | None, float | None] | None
+LimType: TypeAlias = tuple[float, float]
+
+
+def __stretch(
+    left: float,
+    right: float,
+    pad: float,
+) -> LimType:
+    """stretch the limits by a padding factor"""
+    c = 0.5 * (left + right)
+    d = 0.5 * (right - left)
+    return (c - d * pad, c + d * pad)
+
+
+def __setMinMax(
+    lims: LimTypeWithNone,
+    data: np.ndarray,
+) -> LimType:
+    """set the limits of the axis according to the data and the passed limits"""
+    if lims is None:
+        return (np.nanmin(data), np.nanmax(data))
+    assert (
+        isinstance(lims, tuple) and len(lims) == 2
+    ), "lims must be a tuple of length 2"
+    if lims[0] is None and lims[1] is None:
+        return (np.nanmin(data), np.nanmax(data))
+    if lims[0] is None and lims[1] is not None:
+        return (np.nanmin(data), lims[1])
+    if lims[1] is None and lims[0] is not None:
+        return (lims[0], np.nanmax(data))
+    assert lims[0] is not None and lims[1] is not None, "lims must not be None"
+    return (lims[0], lims[1])
+
+
+def __setAxLims(
+    ax: pltAxes,
+    coords,
+    log: bool,
+    pad: float,
+    lims: LimTypeWithNone,
+    spines: str,
+):
+    """set the limits of the axis according to the data and the passed limits"""
+    lim = __setMinMax(lims, coords)
+    # TODO: fix negative when log specified
+    if pad > 0:
+        ax.spines[spines].set_bounds(*lim)
+    if spines == "bottom":
+        func_setscale = ax.set_xscale
+        func_setlim = ax.set_xlim
+    elif spines == "left":
+        func_setscale = ax.set_yscale
+        func_setlim = ax.set_ylim
+    else:
+        raise ValueError(f"invalid `spines` value: {spines}")
+    if log:
+        func_setscale("log")
+        p1, p2 = lim
+        func_setlim(
+            *list(
+                map(lambda p: 10**p, __stretch(np.log10(p1), np.log10(p2), 1.0 + pad))
+            )
+        )
+    else:
+        p1, p2 = lim
+        func_setlim(*__stretch(p1, p2, 1.0 + pad))
+
+
+def __checkDimensions2d(
+    x: np.ndarray,
+    y: np.ndarray,
+    zz: np.ndarray,
+) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """check the dimensions of the passed 2d arrays and return them as 1d arrays"""
+    x, y, zz = (
+        np.array(np.squeeze(x)),
+        np.array(np.squeeze(y)),
+        np.array(np.squeeze(zz)),
+    )
+    readShapes = f"`x.shape={x.shape}`, `y.shape={y.shape}`, `zz.shape={zz.shape}`"
+    assert len(x.shape) == len(
+        y.shape
+    ), f"Shapes of `x` and `y` must be of the same dimension: {readShapes}."
+    if len(x.shape) > 1:
+        x = x[0, ...]
+    if len(y.shape) > 1:
+        y = y[..., 0]
+    assert (len(zz.shape) == 2) or (
+        len(zz.shape) == 3 and ((zz.shape[-1] == 3) or (zz.shape[-1] == 4))
+    ), f"`zz` must have exactly 2 non-trivial axes: {readShapes}."
+    assert (
+        zz.shape[1] == x.shape[0]
+    ), f"incompatible dimensions between `x` and `zz`: {readShapes}."
+    assert (
+        zz.shape[0] == y.shape[0]
+    ), f"incompatible dimensions between `y` and `zz`: {readShapes}."
+    return (x, y, zz)
+
+
+def __findExtent(
+    x: np.ndarray,
+    y: np.ndarray,
+    centering: str,
+) -> tuple[float, float, float, float]:
+    if centering == "edge":
+        dx = x[1] - x[0]
+        dy = y[1] - y[0]
+        extent = (x.min(), x.max() + dx, y.min(), y.max() + dy)
+    elif centering == "center":
+        dx = x[1] - x[0]
+        dy = y[1] - y[0]
+        extent = (
+            x.min() - dx * 0.5,
+            x.max() + dx * 0.5,
+            y.min() - dy * 0.5,
+            y.max() + dy * 0.5,
+        )
+    else:
+        raise ValueError
+    return extent
+
+
+def dataPlot(
+    function: Callable,
+    ax: pltAxes,
+    x: np.ndarray,
+    y: np.ndarray,
+    xlog: bool = False,
+    ylog: bool = False,
+    xlim: LimTypeWithNone = None,
+    ylim: LimTypeWithNone = None,
+    padx: float = 0.0,
+    pady: float = 0.0,
+    **kwargs,
+):
+    """Add a plot according to a passed function
+
+    Args
+    ----
+    function : Callable
+        The function to call on the axis (e.g., `ax.plot`, `ax.scatter`).
+    ax : pltAxes
+        The matplotlib axis object.
+    x, y : np.ndarray
+        The data to plot.
+    xlog : bool, optional
+        Use logarithmic scale for x-axis (default is False).
+    ylog : bool, optional
+        Use logarithmic scale for y-axis (default is False).
+    xlim : tuple[float | None, float | None] | None, optional
+        Tuple of x limits (None = determine from data) (default is None).
+    ylim : tuple[float | None, float | None] | None, optional
+        Tuple of y limits (None = determine from data) (default is None).
+    padx : float, optional
+        Add whitespace to axes in each direction (0 = no additional space) (default is 0.0).
+    pady : float, optional
+        Add whitespace to axes in each direction (0 = no additional space) (default is 0.0).
+    **kwargs : dict, optional
+        Standard matplotlib kwargs passed to `function`.
+    """
+    if padx != 0:
+        ax.spines["top"].set_visible(False)
+    if pady != 0:
+        ax.spines["right"].set_visible(False)
+    function(x, y, **kwargs)
+    __setAxLims(ax, x, xlog, padx, xlim, "bottom")
+    __setAxLims(ax, y, ylog, pady, ylim, "left")
+    return None
+
+
+def scatter(
+    ax: pltAxes,
+    x: np.ndarray,
+    y: np.ndarray,
+    xlog: bool = False,
+    ylog: bool = False,
+    xlim: LimTypeWithNone = None,
+    ylim: LimTypeWithNone = None,
+    padx: float = 0.0,
+    pady: float = 0.0,
+    **kwargs,
+):
+    """Add a scatter plot to a given axis
+
+    Args
+    ----
+    ax : pltAxes
+        The matplotlib axis object.
+    x, y : np.ndarray
+        The data to plot.
+    xlog : bool, optional
+        Use logarithmic scale for x-axis (default is False).
+    ylog : bool, optional
+        Use logarithmic scale for y-axis (default is False).
+    xlim : LimTypeWithNone, optional
+        Tuple of x limits (None = determine from data) (default is None).
+    ylim : LimTypeWithNone, optional
+        Tuple of y limits (None = determine from data) (default is None).
+    padx : float, optional
+        Add whitespace to axes in each direction (0 = no additional space) (default is 0.0).
+    pady : float, optional
+        Add whitespace to axes in each direction (0 = no additional space) (default is 0.0).
+    **kwargs : dict, optional
+        Standard matplotlib kwargs passed to `ax.scatter`.
+    """
+    return dataPlot(ax.scatter, ax, x, y, xlog, ylog, xlim, ylim, padx, pady, **kwargs)
+
+
+def plot(
+    ax: pltAxes,
+    x: np.ndarray,
+    y: np.ndarray,
+    xlog: bool = False,
+    ylog: bool = False,
+    xlim: LimTypeWithNone = None,
+    ylim: LimTypeWithNone = None,
+    padx: float = 0.0,
+    pady: float = 0.0,
+    **kwargs,
+):
+    """Add a plot to a given axis (same as `dataPlot(ax.plot, ...)`)
+
+    Args
+    ----
+    ax : pltAxes
+        The matplotlib axis object.
+    x, y : np.ndarray
+        The data to plot.
+    xlog : bool, optional
+        Use logarithmic scale for x-axis (default is False).
+    ylog : bool, optional
+        Use logarithmic scale for y-axis (default is False).
+    xlim : LimTypeWithNone, optional
+        Tuple of x limits (None = determine from data) (default is None).
+    ylim : LimTypeWithNone, optional
+        Tuple of y limits (None = determine from data) (default is None).
+    padx : float, optional
+        Add whitespace to axes in each direction (0 = no additional space) (default is 0.0).
+    pady : float, optional
+        Add whitespace to axes in each direction (0 = no additional space) (default is 0.0).
+    **kwargs : dict, optional
+        Standard matplotlib kwargs passed to `function`.
+    """
+    dataPlot(ax.plot, ax, x, y, xlog, ylog, xlim, ylim, padx, pady, **kwargs)
+
+
+def plot2d(
+    ax: pltAxes,
+    x: np.ndarray,
+    y: np.ndarray,
+    zz: np.ndarray,
+    force_aspect: bool = True,
+    centering: str = "edge",
+    xlim: LimTypeWithNone = None,
+    ylim: LimTypeWithNone = None,
+    zlog: bool = False,
+    zlim: LimTypeWithNone = None,
+    padx: float = 0.0,
+    pady: float = 0.0,
+    cbar: str | None = "5%",
+    cbar_pad: float = 0.05,
+    cbar_pos: str = "right",
+    **kwargs,
+):
+    """Add a 2d plot to a given axis
+
+    Args
+    ----
+    ax : matplotlib axis object
+        The axis to plot on.
+    x, y : 1d or 2d arrays of coordinates
+        The coordinates of the data to plot.
+    force_aspect : bool, optional
+        Force equal aspect ratio according to axes (default is True).
+    centering : str, optional
+        Centering of x & y nodes for the data ('edge', 'center') (default is 'edge').
+    xlim : tuple of float, optional
+        Tuple of x limits (None = determine from x) (default is None).
+    ylim : tuple of float, optional
+        Tuple of y limits (None = determine from y) (default is None).
+    zlog : bool, optional
+        Use log in z ('True', 'False') (default is False).
+    zlim : tuple of float, optional
+        Tuple of z limits (None = determine from z) (default is None).
+    padx : float, optional
+        Add whitespace to axes in each direction (0 = no additional space) (default is 0.0).
+    pady : float, optional
+        Add whitespace to axes in each direction (0 = no additional space) (default is 0.0).
+    cbar : str or None, optional
+        Size of the colorbar in percent of x-axis (None = no colorbar) (default is '5%').
+    cbar_pad : float, optional
+        Padding of the colorbar (default is 0.05).
+    cbar_pos : str, optional
+        Position of the colorbar ('left', 'right', 'top', 'bottom') (default is 'right').
+    **kwargs : dict, optional
+        Standard matplotlib kwargs passed to `ax.imshow`.
+
+    Returns
+    -------
+    None or colorbar handle
+        Returns `None` if `cbar` is `None`, otherwise returns the colorbar handle.
+
+    Raises
+    ------
+    AssertionError
+        If `centering` is not 'edge' or 'center', or if `cbar_pos` is not one of 'left', 'right', 'top', or 'bottom'.
+
+    """
+    from mpl_toolkits.axes_grid1 import make_axes_locatable
+    import matplotlib.pyplot as plt
+
+    assert centering in ["edge", "center"], "invalid `centering`"
+    assert cbar_pos in ["left", "right", "top", "bottom"], "invalid `cbar_pos`"
+
+    x, y, zz = __checkDimensions2d(x, y, zz)
+    ax.grid(False)
+    extent = __findExtent(x, y, centering)
+    aspect = "auto" if not force_aspect else None
+    if not ("norm" in kwargs):
+        zminQ = np.quantile(zz[~np.isnan(zz) & ~np.isinf(zz)], 0.05)
+        zmaxQ = np.quantile(zz[~np.isnan(zz) & ~np.isinf(zz)], 0.95)
+        if zlim is not None:
+            if zlim[0] is None:
+                vmin = zminQ
+            else:
+                vmin = zlim[0]
+            if zlim[1] is None:
+                vmax = zmaxQ
+            else:
+                vmax = zlim[1]
+        else:
+            vmin, vmax = zminQ, zmaxQ
+        if zlog:
+            norm = mcolors.LogNorm(vmin=float(vmin), vmax=float(vmax))
+        else:
+            norm = mcolors.Normalize(vmin=float(vmin), vmax=float(vmax))
+    else:
+        norm = kwargs.get("norm")
+        kwargs.pop("norm")
+    ax.imshow(zz, origin="lower", extent=extent, aspect=aspect, norm=norm, **kwargs)
+    __setAxLims(ax, np.linspace(extent[0], extent[1]), False, padx, xlim, "bottom")
+    __setAxLims(ax, np.linspace(extent[2], extent[3]), False, pady, ylim, "left")
+    if cbar is not None:
+        divider = make_axes_locatable(ax)
+        cax = divider.append_axes(cbar_pos, size=cbar, pad=cbar_pad)
+        colorbar = plt.colorbar(
+            ax.get_images()[0],
+            cax=cax,
+            orientation="vertical" if cbar_pos in ["left", "right"] else "horizontal",
+        )
+        if cbar_pos == "left":
+            cax.yaxis.set_ticks_position("left")
+            cax.yaxis.set_label_position("left")
+            ax.yaxis.set_ticks_position("right")
+            ax.yaxis.set_label_position("right")
+        if cbar_pos == "top":
+            cax.xaxis.set_ticks_position("top")
+            cax.xaxis.set_label_position("top")
+        if cbar_pos == "bottom":
+            ax.xaxis.set_ticks_position("top")
+            ax.xaxis.set_label_position("top")
+        return colorbar
+    else:
+        return None
+
+
+def plotVectorField(
+    ax: pltAxes,
+    x: np.ndarray,
+    y: np.ndarray,
+    fx: np.ndarray,
+    fy: np.ndarray,
+    background: np.ndarray | None = None,
+    texture_seed: int | None = None,
+    kernel_len: int = 31,
+    kernel_pow: int = 1,
+    lic_alphamin: float = 0.5,
+    lic_alphamax: float = 0.75,
+    lic_contrast: float = 0.33,
+    lic_opacity: float = 0.75,
+    lic_cmap: str = "binary_r",
+    force_aspect: bool = True,
+    centering: str = "edge",
+    xlim: tuple[float, float] | None = None,
+    ylim: tuple[float, float] | None = None,
+    padx: float = 0.0,
+    pady: float = 0.0,
+    cbar: str | None = "5%",
+    cbar_pad: float = 0.05,
+    **kwargs,
+):
+    """Add a 2D plot with a vector-field overplotted
+    
+    Args
+    ----
+    ax : pltAxes
+        The matplotlib axis object.
+    x, y : np.ndarray
+        1D or 2D arrays of coordinates.
+    fx, fy : np.ndarray
+        2D arrays of the vector field components.
+    background : np.ndarray | None, optional
+        2D array of the image background (None = `sqrt(fx^2 + fy^2)`).
+    
+    texture_seed : int | None, optional
+        Specify a random seed to generate textures, useful when rendering movies (None = random).
+    kernel_len : int, optional
+        Kernel resolution for the LIC algorithm (default is 31).
+    kernel_pow : int, optional
+        Kernel sharpness for the LIC algorithm (default is 1).
+    lic_alphamin : float, optional
+            
+    """
+    
+    """
+    add a 2d plot with a vector-field overplotted
+
+    args
+    ----------
+    ax .......................... : matplotlib axis object
+    x, y ........................ : 1d or 2d arrays of coordinates
+    fx, fy ...................... : 2d arrays of the vector field components
+    background [None] ........... : 2d array of the image background (None = `sqrt(fx^2 + fy^2)`)
+
+    line integral convolution (lic) parameters
+    ---------
+    texture_seed [None] ......... : specify a random seed to generate textures, useful when rendering movies (None = random)
+    kernel_len [31] ............. : kernel resolution for the lic algorithm
+    kernel_pow [1] .............. : kernel sharpness for the lic algorithm
+    lic_alphamin [0.5] .......... : lic parameter for min transparency
+    lic_alphamax [0.75] ......... : lic parameter for max transparency
+    lic_contrast [0.33] ......... : lic parameter for the contrast
+    lic_opacity [0.75] .......... : lic parameter for the absolute opacity of the field plot
+    lic_cmap ['binary_r'] ....... : colormap used for the lic texture
+
+    the rest of the args are the same as for the `plot2d`
+    ----------
+    force_aspect [True] ......... : force equal aspect ratio according to axes
+    centering ['edge'] .......... : centering of x & y nodes for the data ('edge', 'center')
+    xlim [None], ylim [None] .... : tuples of x and y limits (None = determine from x & y)
+    padx [0], pady [0] .......... : add whitespace to axes in each direction (0 = no additional space)
+    cbar ['5%'] ................. : size of the colorbar in percent of x-axis (None = no colorbar)
+    cbar_pad [0.05] ............. : padding of the colorbar
+    **kwargs .................... : standard matplotlib kwargs passed to `ax.imshow`
+    """
+    import myplotlib.tools.lic as lic
+    import matplotlib
+    import matplotlib.pyplot as plt
+
+    kernel = lic.generate_kernel(kernel_len) ** kernel_pow
+    x, y, fx = __checkDimensions2d(x, y, fx)
+    x, y, fy = __checkDimensions2d(x, y, fy)
+    if background is None:
+        background = np.sqrt(fx**2 + fy**2)
+    # line integral convolution doesn't like zeros
+    fmin = (np.abs(fx).min() + np.abs(fy).min()) / 1e10
+    fx = (1.0 * (fx >= 0) - 1.0 * (fx < 0)) * (np.abs(fx) + fmin)
+    fy = (1.0 * (fy >= 0) - 1.0 * (fy < 0)) * (np.abs(fy) + fmin)
+
+    x, y, background = __checkDimensions2d(x, y, background)
+    texture = lic.generate_texture(background.shape, texture_seed)
+    img1 = lic.line_integral_convolution(fx, fy, texture, kernel)
+    img2 = lic.line_integral_convolution(-fx, -fy, texture, kernel)
+    img = 0.5 * (img1 + img2)
+
+    weights = img
+    _ = np.sign(weights - np.average(weights)) * np.sqrt(
+        np.abs(weights - np.average(weights))
+    )
+    alphas = mcolors.Normalize(None, None, clip=True)(_)
+    alphas[alphas < lic_alphamin] = 0
+    alphas[alphas > lic_alphamax] = 1
+    _ = (
+        np.sign(weights - np.average(weights))
+        * np.abs(weights - np.average(weights)) ** lic_contrast
+    )
+    colors = mcolors.Normalize(None, None)(_)
+    colors = matplotlib.colormaps[lic_cmap](colors)
+    colors[..., -1] = alphas
+
+    colorbar = plot2d(
+        ax,
+        x,
+        y,
+        background,
+        force_aspect=force_aspect,
+        centering=centering,
+        xlim=xlim,
+        ylim=ylim,
+        padx=padx,
+        pady=pady,
+        cbar=cbar,
+        cbar_pad=cbar_pad,
+        **kwargs,
+    )
+    plot2d(
+        ax,
+        x,
+        y,
+        colors,
+        force_aspect=force_aspect,
+        centering=centering,
+        xlim=xlim,
+        ylim=ylim,
+        padx=padx,
+        pady=pady,
+        cbar=cbar,
+        cbar_pad=cbar_pad,
+        alpha=lic_opacity,
+    )
+    return colorbar
+
+
+class PanelDict(TypedDict):
+    label: str | None
+    field: Callable | None
+    cmap: str | None
+    norm: mcolors.Normalize | None
+
+
+def plot2dGrid(
+    x: np.ndarray,
+    y: np.ndarray,
+    fields: dict[str, np.ndarray],
+    panels: list[list[PanelDict]],
+    label_pos: str = "title",
+    label_args: dict[str, Any] = {},
+    width: float = 10,
+    dpi: int = 150,
+    wspace: float = 0.05,
+    hspace: float = 0.05,
+    **kwargs,
+):
+    """
+    add a grid of 2d plots with shared axes
+
+    args
+    ----------
+    x, y ........................ : 1d or 2d arrays of coordinates
+    fields ...................... : dictionary of all the fields
+    panels ...................... : array of array of dictionaries indicating the panels to plot (see note below)
+    label_pos ['title'] ......... : position of the label ('title', 'cbar', 'text', None)
+    label_args [{}] ............. : arguments for the label (color, fontsize, etc; passed to `ax.set_title`, )
+
+    arguments for the figure
+    ----------
+    width [10] .................. : width of the figure in inches
+    dpi [150] ................... : resolution of the figure [dots per inch]
+    wspace [0.05] ............... : width space between the panels (as fraction of the panel width)
+    hspace [0.05] ............... : height space between the panels (as fraction of the panel height)
+
+    the rest of the args are the same as for the `plot2d`
+    ----------
+    force_aspect [True] ......... : force equal aspect ratio according to axes
+    centering ['edge'] .......... : centering of x & y nodes for the data ('edge', 'center')
+    xlim [None], ylim [None] .... : tuples of x and y limits (None = determine from x & y)
+    padx [0], pady [0] .......... : add whitespace to axes in each direction (0 = no additional space)
+    cbar ['5%'] ................. : size of the colorbar in percent of x-axis (None = no colorbar)
+    cbar_pad [0.05] ............. : padding of the colorbar
+    **kwargs .................... : standard matplotlib kwargs passed to `ax.imshow`
+
+    note
+    ----------
+    the `panels` is an `n x m` array, where `n` is the number of rows and `m` is the number of columns.
+    each element of the array is a dictionary with the following keys:
+        - 'label' ............... : label for the field
+        - 'field' ............... : lambda function which takes the `fields` dictionary and returns the quantity to plot
+        - 'cmap' ................ : colormap of the panel
+        - 'norm' ................ : normalization object
+    """
+    import matplotlib.pyplot as plt
+
+    assert len(panels) > 0, "no panels to plot"
+    assert len(panels[0]) > 0, "no panels to plot"
+    assert all(
+        [len(row) == len(panels[0]) for row in panels]
+    ), "all rows must have the same number of panels"
+    assert label_pos in ["title", "cbar", "text", None], "invalid label position"
+
+    ncols = len(panels[0])
+    nrows = len(panels)
+
+    xlims = kwargs.get("xlim", (x.min(), x.max()))
+    ylims = kwargs.get("ylim", (y.min(), y.max()))
+    aspect = (xlims[1] - xlims[0]) / (ylims[1] - ylims[0])
+    height = (
+        width
+        * ((nrows + hspace * (nrows - 1)) / (ncols + wspace * (ncols - 1)))
+        / aspect
+    )
+
+    fig = plt.figure(figsize=(width, height), dpi=dpi)
+
+    gs = fig.add_gridspec(nrows, ncols, wspace=wspace, hspace=hspace)
+    axs = [[fig.add_subplot(gs[i, j]) for j in range(ncols)] for i in range(nrows)]
+
+    label_coords = label_args.pop("position", (0.05, 0.95))
+
+    for i in range(nrows):
+        for j in range(ncols):
+            ax = axs[i][j]
+            panel = panels[i][j]
+            assert "field" in panel, "panel must have a 'field' key"
+            field_func = panel["field"]
+            assert field_func is not None, "field must be a callable function"
+            cbar = plot2d(
+                ax,
+                x,
+                y,
+                field_func(fields),
+                norm=panel["norm"],
+                cmap=panel["cmap"],
+                **kwargs,
+            )
+
+            if j != 0:
+                ax.set(ylabel=None, yticklabels=[])
+            if i != nrows - 1:
+                ax.set(xlabel=None, xticklabels=[])
+
+            if label_pos == "title":
+                assert "label" in panel, "panel must have a 'label' key"
+                if panel["label"] is not None:
+                    ax.set_title(panel["label"], **label_args)
+            elif label_pos == "cbar":
+                if cbar is not None:
+                    assert "label" in panel, "panel must have a 'label' key"
+                    if panel["label"] is not None:
+                        cbar.set_label(panel["label"], **label_args)
+            elif label_pos == "text":
+                assert "label" in panel, "panel must have a 'label' key"
+                if panel["label"] is not None:
+                    ax.text(
+                        *label_coords,
+                        s=panel["label"],
+                        transform=ax.transAxes,
+                        **label_args,
+                    )