ultraplot 0.99.3__py3-none-any.whl

ultraplot/axes/polar.py

@@ -0,0 +1,381 @@
+#!/usr/bin/env python3
+"""
+Polar axes using azimuth and radius instead of *x* and *y*.
+"""
+import inspect
+
+import matplotlib.projections.polar as mpolar
+import numpy as np
+
+from .. import constructor
+from .. import ticker as pticker
+from ..config import rc
+from ..internals import ic  # noqa: F401
+from ..internals import _not_none, _pop_rc, docstring
+from . import plot, shared
+
+__all__ = ["PolarAxes"]
+
+
+# Format docstring
+_format_docstring = """
+r0 : float, default: 0
+    The radial origin.
+theta0 : {'N', 'NW', 'W', 'SW', 'S', 'SE', 'E', 'NE'}, optional
+    The zero azimuth location.
+thetadir : {1, -1, 'anticlockwise', 'counterclockwise', 'clockwise'}, optional
+    The positive azimuth direction. Clockwise corresponds to
+    ``-1`` and anticlockwise corresponds to ``1``.
+thetamin, thetamax : float, optional
+    The lower and upper azimuthal bounds in degrees. If
+    ``thetamax != thetamin + 360``, this produces a sector plot.
+thetalim : 2-tuple of float or None, optional
+    Specifies `thetamin` and `thetamax` at once.
+rmin, rmax : float, optional
+    The inner and outer radial limits. If ``r0 != rmin``, this
+    produces an annular plot.
+rlim : 2-tuple of float or None, optional
+    Specifies `rmin` and `rmax` at once.
+rborder : bool, optional
+    Whether to draw the polar axes border. Visibility of the "inner"
+    radial spine and "start" and "end" azimuthal spines is controlled
+    automatically by matplotlib.
+thetagrid, rgrid, grid : bool, optional
+    Whether to draw major gridlines for the azimuthal and radial axis.
+    Use the keyword `grid` to toggle both.
+thetagridminor, rgridminor, gridminor : bool, optional
+    Whether to draw minor gridlines for the azimuthal and radial axis.
+    Use the keyword `gridminor` to toggle both.
+thetagridcolor, rgridcolor, gridcolor : color-spec, optional
+    Color for the major and minor azimuthal and radial gridlines.
+    Use the keyword `gridcolor` to set both at once.
+thetalocator, rlocator : locator-spec, optional
+    Used to determine the azimuthal and radial gridline positions.
+    Passed to the `~ultraplot.constructor.Locator` constructor. Can be
+    float, list of float, string, or `matplotlib.ticker.Locator` instance.
+thetalines, rlines
+    Aliases for `thetalocator`, `rlocator`.
+thetalocator_kw, rlocator_kw : dict-like, optional
+    The azimuthal and radial locator settings. Passed to
+    `~ultraplot.constructor.Locator`.
+thetaminorlocator, rminorlocator : optional
+    As for `thetalocator`, `rlocator`, but for the minor gridlines.
+thetaminorticks, rminorticks : optional
+    Aliases for `thetaminorlocator`, `rminorlocator`.
+thetaminorlocator_kw, rminorlocator_kw
+    As for `thetalocator_kw`, `rlocator_kw`, but for the minor locator.
+rlabelpos : float, optional
+    The azimuth at which radial coordinates are labeled.
+thetaformatter, rformatter : formatter-spec, optional
+    Used to determine the azimuthal and radial label format.
+    Passed to the `~ultraplot.constructor.Formatter` constructor.
+    Can be string, list of string, or `matplotlib.ticker.Formatter`
+    instance. Use ``[]``, ``'null'``, or ``'none'`` for no labels.
+thetalabels, rlabels : optional
+    Aliases for `thetaformatter`, `rformatter`.
+thetaformatter_kw, rformatter_kw : dict-like, optional
+    The azimuthal and radial label formatter settings. Passed to
+    `~ultraplot.constructor.Formatter`.
+color : color-spec, default: :rc:`meta.color`
+    Color for the axes edge. Propagates to `labelcolor` unless specified
+    otherwise (similar to `ultraplot.axes.CartesianAxes.format`).
+labelcolor, gridlabelcolor : color-spec, default: `color` or :rc:`grid.labelcolor`
+    Color for the gridline labels.
+labelpad, gridlabelpad : unit-spec, default: :rc:`grid.labelpad`
+    The padding between the axes edge and the radial and azimuthal labels.
+    %(units.pt)s
+labelsize, gridlabelsize : unit-spec or str, default: :rc:`grid.labelsize`
+    Font size for the gridline labels.
+    %(units.pt)s
+labelweight, gridlabelweight : str, default: :rc:`grid.labelweight`
+    Font weight for the gridline labels.
+"""
+docstring._snippet_manager["polar.format"] = _format_docstring
+
+
+class PolarAxes(shared._SharedAxes, plot.PlotAxes, mpolar.PolarAxes):
+    """
+    Axes subclass for plotting in polar coordinates. Adds the `~PolarAxes.format`
+    method and overrides several existing methods.
+
+    Important
+    ---------
+    This axes subclass can be used by passing ``proj='polar'``
+    to axes-creation commands like `~ultraplot.figure.Figure.add_axes`,
+    `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`.
+    """
+
+    _name = "polar"
+
+    @docstring._snippet_manager
+    def __init__(self, *args, **kwargs):
+        """
+        Parameters
+        ----------
+        *args
+            Passed to `matplotlib.axes.Axes`.
+        %(polar.format)s
+
+        Other parameters
+        ----------------
+        %(axes.format)s
+        %(rc.init)s
+
+        See also
+        --------
+        PolarAxes.format
+        ultraplot.axes.Axes
+        ultraplot.axes.PlotAxes
+        matplotlib.projections.PolarAxes
+        ultraplot.figure.Figure.subplot
+        ultraplot.figure.Figure.add_subplot
+        """
+        # Set tick length to zero so azimuthal labels are not too offset
+        # Change default radial axis formatter but keep default theta one
+        super().__init__(*args, **kwargs)
+        self.yaxis.set_major_formatter(pticker.AutoFormatter())
+        self.yaxis.isDefault_majfmt = True
+        for axis in (self.xaxis, self.yaxis):
+            axis.set_tick_params(which="both", size=0)
+
+    def _update_formatter(self, x, *, formatter=None, formatter_kw=None):
+        """
+        Update the gridline label formatter.
+        """
+        # Tick formatter and toggling
+        axis = getattr(self, x + "axis")
+        formatter_kw = formatter_kw or {}
+        if formatter is not None:
+            formatter = constructor.Formatter(formatter, **formatter_kw)  # noqa: E501
+            axis.set_major_formatter(formatter)
+
+    def _update_limits(self, x, *, min_=None, max_=None, lim=None):
+        """
+        Update the limits.
+        """
+        # Try to use public API where possible
+        r = "theta" if x == "x" else "r"
+        min_, max_ = self._min_max_lim(r, min_, max_, lim)
+        if min_ is not None:
+            getattr(self, f"set_{r}min")(min_)
+        if max_ is not None:
+            getattr(self, f"set_{r}max")(max_)
+
+    def _update_locators(
+        self,
+        x,
+        *,
+        locator=None,
+        locator_kw=None,
+        minorlocator=None,
+        minorlocator_kw=None,
+    ):
+        """
+        Update the gridline locator.
+        """
+        # TODO: Add minor tick 'toggling' as with cartesian axes?
+        # NOTE: Must convert theta locator input to radians, then back to deg.
+        r = "theta" if x == "x" else "r"
+        axis = getattr(self, x + "axis")
+        min_ = getattr(self, f"get_{r}min")()
+        max_ = getattr(self, f"get_{r}max")()
+        for i, (loc, loc_kw) in enumerate(
+            zip((locator, minorlocator), (locator_kw, minorlocator_kw))
+        ):
+            if loc is None:
+                continue
+            # Get locator
+            loc_kw = loc_kw or {}
+            loc = constructor.Locator(loc, **loc_kw)
+            # Sanitize values
+            array = loc.tick_values(min_, max_)
+            array = array[(array >= min_) & (array <= max_)]
+            if x == "x":
+                array = np.deg2rad(array)
+                if np.isclose(array[-1], min_ + 2 * np.pi):  # exclusive if 360 deg
+                    array = array[:-1]
+            # Assign fixed location
+            loc = constructor.Locator(array)  # convert to FixedLocator
+            if i == 0:
+                axis.set_major_locator(loc)
+            else:
+                axis.set_minor_locator(loc)
+
+    @docstring._snippet_manager
+    def format(
+        self,
+        *,
+        r0=None,
+        theta0=None,
+        thetadir=None,
+        thetamin=None,
+        thetamax=None,
+        thetalim=None,
+        rmin=None,
+        rmax=None,
+        rlim=None,
+        thetagrid=None,
+        rgrid=None,
+        thetagridminor=None,
+        rgridminor=None,
+        thetagridcolor=None,
+        rgridcolor=None,
+        rlabelpos=None,
+        rscale=None,
+        rborder=None,
+        thetalocator=None,
+        rlocator=None,
+        thetalines=None,
+        rlines=None,
+        thetalocator_kw=None,
+        rlocator_kw=None,
+        thetaminorlocator=None,
+        rminorlocator=None,
+        thetaminorlines=None,
+        rminorlines=None,  # noqa: E501
+        thetaminorlocator_kw=None,
+        rminorlocator_kw=None,
+        thetaformatter=None,
+        rformatter=None,
+        thetalabels=None,
+        rlabels=None,
+        thetaformatter_kw=None,
+        rformatter_kw=None,
+        labelpad=None,
+        labelsize=None,
+        labelcolor=None,
+        labelweight=None,
+        **kwargs,
+    ):
+        """
+        Modify axes limits, radial and azimuthal gridlines, and more. Note that
+        all of the ``theta`` arguments are specified in degrees, not radians.
+
+        Parameters
+        ----------
+        %(polar.format)s
+
+        Other parameters
+        ----------------
+        %(axes.format)s
+        %(figure.format)s
+        %(rc.format)s
+
+        See also
+        --------
+        ultraplot.axes.Axes.format
+        ultraplot.config.Configurator.context
+        """
+        # NOTE: Here we capture 'label.pad' rc argument normally used for
+        # x and y axis labels as shorthand for 'tick.labelpad'.
+        rc_kw, rc_mode = _pop_rc(kwargs)
+        labelcolor = _not_none(labelcolor, kwargs.get("color", None))
+        with rc.context(rc_kw, mode=rc_mode):
+            # Not mutable default args
+            thetalocator_kw = thetalocator_kw or {}
+            thetaminorlocator_kw = thetaminorlocator_kw or {}
+            thetaformatter_kw = thetaformatter_kw or {}
+            rlocator_kw = rlocator_kw or {}
+            rminorlocator_kw = rminorlocator_kw or {}
+            rformatter_kw = rformatter_kw or {}
+
+            # Flexible input
+            thetalocator = _not_none(thetalines=thetalines, thetalocator=thetalocator)
+            thetaformatter = _not_none(
+                thetalabels=thetalabels, thetaformatter=thetaformatter
+            )  # noqa: E501
+            thetaminorlocator = _not_none(
+                thetaminorlines=thetaminorlines, thetaminorlocator=thetaminorlocator
+            )  # noqa: E501
+            rlocator = _not_none(rlines=rlines, rlocator=rlocator)
+            rformatter = _not_none(rlabels=rlabels, rformatter=rformatter)
+            rminorlocator = _not_none(
+                rminorlines=rminorlines, rminorlocator=rminorlocator
+            )  # noqa: E501
+
+            # Special radius settings
+            if r0 is not None:
+                self.set_rorigin(r0)
+            if rlabelpos is not None:
+                self.set_rlabel_position(rlabelpos)
+            if rscale is not None:
+                self.set_rscale(rscale)
+            if rborder is not None:
+                self.spines["polar"].set_visible(bool(rborder))
+
+            # Special azimuth settings
+            if theta0 is not None:
+                self.set_theta_zero_location(theta0)
+            if thetadir is not None:
+                self.set_theta_direction(thetadir)
+
+            # Loop over axes
+            for (
+                x,
+                min_,
+                max_,
+                lim,
+                grid,
+                gridminor,
+                gridcolor,
+                locator,
+                locator_kw,
+                formatter,
+                formatter_kw,
+                minorlocator,
+                minorlocator_kw,
+            ) in zip(
+                ("x", "y"),
+                (thetamin, rmin),
+                (thetamax, rmax),
+                (thetalim, rlim),
+                (thetagrid, rgrid),
+                (thetagridminor, rgridminor),
+                (thetagridcolor, rgridcolor),
+                (thetalocator, rlocator),
+                (thetalocator_kw, rlocator_kw),
+                (thetaformatter, rformatter),
+                (thetaformatter_kw, rformatter_kw),
+                (thetaminorlocator, rminorlocator),
+                (thetaminorlocator_kw, rminorlocator_kw),
+            ):
+                # Axis limits
+                self._update_limits(x, min_=min_, max_=max_, lim=lim)
+
+                # Axis tick settings
+                # NOTE: Here use 'grid.labelpad' instead of 'tick.labelpad'. Default
+                # offset for grid labels is larger than for tick labels.
+                self._update_ticks(
+                    x,
+                    grid=grid,
+                    gridminor=gridminor,
+                    gridcolor=gridcolor,
+                    gridpad=True,
+                    labelpad=labelpad,
+                    labelcolor=labelcolor,
+                    labelsize=labelsize,
+                    labelweight=labelweight,
+                )
+
+                # Axis locator
+                self._update_locators(
+                    x,
+                    locator=locator,
+                    locator_kw=locator_kw,
+                    minorlocator=minorlocator,
+                    minorlocator_kw=minorlocator_kw,
+                )
+
+                # Axis formatter
+                self._update_formatter(
+                    x, formatter=formatter, formatter_kw=formatter_kw
+                )
+
+        # Parent format method
+        super().format(rc_kw=rc_kw, rc_mode=rc_mode, **kwargs)
+
+
+# Apply signature obfuscation after storing previous signature
+# NOTE: This is needed for __init__
+PolarAxes._format_signatures[PolarAxes] = inspect.signature(PolarAxes.format)
+PolarAxes.format = docstring._obfuscate_kwargs(PolarAxes.format)

ultraplot/axes/shared.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python
+"""
+An axes used to jointly format Cartesian and polar axes.
+"""
+# NOTE: We could define these in base.py but idea is projection-specific formatters
+# should never be defined on the base class. Might add to this class later anyway.
+import numpy as np
+
+from ..config import rc
+from ..internals import ic  # noqa: F401
+from ..internals import _pop_kwargs
+from ..utils import _fontsize_to_pt, _not_none, units
+
+
+class _SharedAxes(object):
+    """
+    Mix-in class with methods shared between `~ultraplot.axes.CartesianAxes`
+    and `~ultraplot.axes.PolarAxes`.
+    """
+
+    @staticmethod
+    def _min_max_lim(key, min_=None, max_=None, lim=None):
+        """
+        Translate and standardize minimum, maximum, and limit keyword arguments.
+        """
+        if lim is None:
+            lim = (None, None)
+        if not np.iterable(lim) or not len(lim) == 2:
+            raise ValueError(f"Invalid {key}{lim!r}. Must be 2-tuple of values.")
+        min_ = _not_none(**{f"{key}min": min_, f"{key}lim_0": lim[0]})
+        max_ = _not_none(**{f"{key}max": max_, f"{key}lim_1": lim[1]})
+        return min_, max_
+
+    def _update_background(self, x=None, tickwidth=None, tickwidthratio=None, **kwargs):
+        """
+        Update the background patch and spines.
+        """
+        # Update the background patch
+        kw_face, kw_edge = rc._get_background_props(**kwargs)
+        self.patch.update(kw_face)
+        if x is None:
+            opts = self.spines
+        elif x == "x":
+            opts = ("bottom", "top", "inner", "polar")
+        else:
+            opts = ("left", "right", "start", "end")
+        for opt in opts:
+            self.spines.get(opt, {}).update(kw_edge)
+
+        # Update the tick colors
+        axis = "both" if x is None else x
+        x = _not_none(x, "x")
+        obj = getattr(self, x + "axis")
+        edgecolor = kw_edge.get("edgecolor", None)
+        if edgecolor is not None:
+            self.tick_params(axis=axis, which="both", color=edgecolor)
+
+        # Update the tick widths
+        # NOTE: Only use 'linewidth' if it was explicitly passed. Do not
+        # include 'linewidth' inferred from rc['axes.linewidth'] setting.
+        kwmajor = getattr(obj, "_major_tick_kw", {})  # graceful fallback if API changes
+        kwminor = getattr(obj, "_minor_tick_kw", {})
+        if "linewidth" in kwargs:
+            tickwidth = _not_none(tickwidth, kwargs["linewidth"])
+        tickwidth = _not_none(tickwidth, rc.find("tick.width", context=True))
+        tickwidthratio = _not_none(
+            tickwidthratio, rc.find("tick.widthratio", context=True)
+        )  # noqa: E501
+        tickwidth_prev = kwmajor.get("width", rc[x + "tick.major.width"])
+        if tickwidth_prev == 0:
+            tickwidthratio_prev = rc["tick.widthratio"]  # no other way of knowing
+        else:
+            tickwidthratio_prev = (
+                kwminor.get("width", rc[x + "tick.minor.width"]) / tickwidth_prev
+            )  # noqa: E501
+        for which in ("major", "minor"):
+            kwticks = {}
+            if tickwidth is not None or tickwidthratio is not None:
+                tickwidth = _not_none(tickwidth, tickwidth_prev)
+                kwticks["width"] = tickwidth = units(tickwidth, "pt")
+                if tickwidth == 0:  # avoid unnecessary padding
+                    kwticks["size"] = 0
+                elif which == "minor":
+                    tickwidthratio = _not_none(tickwidthratio, tickwidthratio_prev)
+                    kwticks["width"] *= tickwidthratio
+            self.tick_params(axis=axis, which=which, **kwticks)
+
+    def _update_ticks(
+        self,
+        x,
+        *,
+        grid=None,
+        gridminor=None,
+        gridpad=None,
+        gridcolor=None,
+        ticklen=None,
+        ticklenratio=None,
+        tickdir=None,
+        tickcolor=None,
+        labeldir=None,
+        labelpad=None,
+        labelcolor=None,
+        labelsize=None,
+        labelweight=None,
+    ):
+        """
+        Update the gridlines and labels. Set `gridpad` to ``True`` to use grid padding.
+        """
+        # Filter out text properties
+        axis = "both" if x is None else x
+        kwtext = rc._get_ticklabel_props(axis)
+        kwtext_extra = _pop_kwargs(kwtext, "weight", "family")
+        kwtext = {"label" + key: value for key, value in kwtext.items()}
+        if labelcolor is not None:
+            kwtext["labelcolor"] = labelcolor
+        if labelsize is not None:
+            kwtext["labelsize"] = labelsize
+        if labelweight is not None:
+            kwtext_extra["weight"] = labelweight
+
+        # Apply tick settings with tick_params when possible
+        x = _not_none(x, "x")
+        obj = getattr(self, x + "axis")
+        kwmajor = getattr(obj, "_major_tick_kw", {})  # graceful fallback if API changes
+        kwminor = getattr(obj, "_minor_tick_kw", {})
+        ticklen_prev = kwmajor.get("size", rc[x + "tick.major.size"])
+        if ticklen_prev == 0:
+            ticklenratio_prev = rc["tick.lenratio"]  # no other way of knowing
+        else:
+            ticklenratio_prev = (
+                kwminor.get("size", rc[x + "tick.minor.size"]) / ticklen_prev
+            )  # noqa: E501
+        for b, which in zip((grid, gridminor), ("major", "minor")):
+            # Tick properties
+            # NOTE: Must make 'tickcolor' overwrite 'labelcolor' or else 'color'
+            # passed to __init__ will not apply correctly. Annoying but unavoidable
+            kwticks = rc._get_tickline_props(axis, which=which)
+            if labelpad is not None:
+                kwticks["pad"] = labelpad
+            if tickcolor is not None:
+                kwticks["color"] = tickcolor
+            if ticklen is not None or ticklenratio is not None:
+                ticklen = _not_none(ticklen, ticklen_prev)
+                kwticks["size"] = ticklen = units(ticklen, "pt")
+                if ticklen > 0 and which == "minor":
+                    ticklenratio = _not_none(ticklenratio, ticklenratio_prev)
+                    kwticks["size"] *= ticklenratio
+            if gridpad:  # use grid.labelpad instead of tick.labelpad
+                kwticks.pop("pad", None)
+                pad = rc.find("grid.labelpad", context=True)
+                if pad is not None:
+                    kwticks["pad"] = units(pad, "pt")
+
+            # Tick direction properties
+            # NOTE: These have no x and y-specific versions but apply here anyway
+            if labeldir == "in":  # put tick labels inside the plot
+                tickdir = "in"
+                kwticks.setdefault(
+                    "pad",
+                    -rc[f"{axis}tick.major.size"]
+                    - _not_none(labelpad, rc[f"{axis}tick.major.pad"])
+                    - _fontsize_to_pt(rc[f"{axis}tick.labelsize"]),
+                )
+            if tickdir is not None:
+                kwticks["direction"] = tickdir
+
+            # Gridline properties
+            # NOTE: Internally ax.grid() passes gridOn to ax.tick_params() but this
+            # is undocumented and might have weird side effects. Just use ax.grid()
+            b = rc._get_gridline_bool(b, axis=axis, which=which)
+            if b is not None:
+                self.grid(b, axis=axis, which=which)
+            kwlines = rc._get_gridline_props(which=which)
+            if "axisbelow" in kwlines:
+                self.set_axisbelow(kwlines.pop("axisbelow"))
+            if gridcolor is not None:
+                kwlines["grid_color"] = gridcolor
+
+            # Apply tick and gridline properties
+            kwticks.pop("ndivs", None)  # not in mpl
+            self.tick_params(axis=axis, which=which, **kwticks, **kwlines, **kwtext)
+
+        # Apply settings that can't be controlled with tick_params
+        if kwtext_extra:
+            for lab in obj.get_ticklabels():
+                lab.update(kwtext_extra)

ultraplot/axes/three.py

@@ -0,0 +1,34 @@
+#!/usr/bin/env python3
+"""
+The "3D" axes class.
+"""
+from . import base, shared
+
+try:
+    from mpl_toolkits.mplot3d import Axes3D
+except ImportError:
+    Axes3D = object
+
+
+class ThreeAxes(shared._SharedAxes, base.Axes, Axes3D):
+    """
+    Simple mix-in of `ultraplot.axes.Axes` with `~mpl_toolkits.mplot3d.axes3d.Axes3D`.
+
+    Important
+    ---------
+    Note that this subclass does *not* implement the `~ultraplot.axes.PlotAxes`
+    plotting overrides. This axes subclass can be used by passing ``proj='3d'`` or
+    ``proj='three'`` to axes-creation commands like `~ultraplot.figure.Figure.add_axes`,
+    `~ultraplot.figure.Figure.add_subplot`, and `~ultraplot.figure.Figure.subplots`.
+    """
+
+    # TODO: Figure out a way to have internal Axes3D calls to plotting commands
+    # access the overrides rather than the originals? May be impossible.
+    _name = "three"
+    _name_aliases = ("3d",)
+
+    def __init__(self, *args, **kwargs):
+        import mpl_toolkits.mplot3d  # noqa: F401 verify package is available
+
+        kwargs.setdefault("alpha", 0.0)
+        super().__init__(*args, **kwargs)