phasorpy 0.6__cp311-cp311-win_amd64.whl → 0.7__cp311-cp311-win_amd64.whl

phasorpy/plot/_phasorplot.py

@@ -10,7 +10,7 @@ from collections.abc import Sequence
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from .._typing import Any, ArrayLike, NDArray, IO
+    from .._typing import Any, ArrayLike, Literal, NDArray, IO
 
     from matplotlib.axes import Axes
     from matplotlib.figure import Figure
@@ -18,8 +18,16 @@ if TYPE_CHECKING:
 import numpy
 from matplotlib import pyplot
 from matplotlib.font_manager import FontProperties
+from matplotlib.legend import Legend
 from matplotlib.lines import Line2D
-from matplotlib.patches import Arc, Circle, Ellipse, FancyArrowPatch, Polygon
+from matplotlib.patches import (
+    Arc,
+    Circle,
+    Ellipse,
+    FancyArrowPatch,
+    Polygon,
+    Rectangle,
+)
 from matplotlib.path import Path
 from matplotlib.patheffects import AbstractPathEffect
 
@@ -32,19 +40,20 @@ from .._utils import (
     sort_coordinates,
     update_kwargs,
 )
-from ..phasor import (
+from ..lifetime import (
     phasor_from_lifetime,
     phasor_semicircle,
     phasor_to_apparent_lifetime,
-    phasor_transform,
 )
+from ..phasor import phasor_to_polar, phasor_transform
 
 GRID_COLOR = '0.5'
 GRID_LINESTYLE = ':'
 GRID_LINESTYLE_MAJOR = '-'
-GRID_LINEWIDH = 1.0
-GRID_LINEWIDH_MINOR = 0.5
+GRID_LINEWIDTH = 1.0
+GRID_LINEWIDTH_MINOR = 0.6
 GRID_FILL = False
+GRID_ZORDER = 2
 
 
 class PhasorPlot:
@@ -57,13 +66,18 @@ class PhasorPlot:
     allquadrants : bool, optional
         Show all quadrants of phasor space.
         By default, only the first quadrant with universal semicircle is shown.
-    ax : matplotlib axes, optional
+    ax : matplotlib.axes.Axes, optional
         Matplotlib axes used for plotting.
         By default, a new subplot axes is created.
     frequency : float, optional
         Laser pulse or modulation frequency in MHz.
-    grid : bool, optional, default: True
-        Display polar grid or universal semicircle.
+    pad : float, optional
+        Padding around the plot. The default is 0.05.
+    grid : dict or bool, optional
+        Display universal semicircle (default) or polar grid (allquadrants).
+        If False, no grid is displayed.
+        If a dictionary, it is passed to :py:meth:`PhasorPlot.polar_grid`
+        or :py:meth:`PhasorPlot.semicircle`.
     **kwargs
         Additional properties to set on `ax`.
 
@@ -77,14 +91,17 @@ class PhasorPlot:
     _ax: Axes
     """Matplotlib axes."""
 
-    _limits: tuple[tuple[float, float], tuple[float, float]]
-    """Axes limits (xmin, xmax), (ymin, ymax)."""
-
     _full: bool
     """Show all quadrants of phasor space."""
 
-    _semicircle_ticks: SemicircleTicks | None
-    """Last SemicircleTicks instance created."""
+    _labels: bool
+    """Plot has labels attached."""
+
+    _semicircle_ticks: CircleTicks | None
+    """Last CircleTicks instance created for semicircle."""
+
+    _unitcircle_ticks: CircleTicks | None
+    """Last CircleTicks instance created for unit circle."""
 
     _frequency: float
     """Laser pulse or modulation frequency in MHz."""
@@ -96,7 +113,8 @@ class PhasorPlot:
         ax: Axes | None = None,
         *,
         frequency: float | None = None,
-        grid: bool = True,
+        grid: dict[str, Any] | bool | None = None,
+        pad: float | None = None,
         **kwargs: Any,
     ) -> None:
         # initialize empty phasor plot
@@ -104,24 +122,38 @@ class PhasorPlot:
         self._ax.format_coord = (  # type: ignore[method-assign]
             self._on_format_coord
         )
+        self._labels = False
+
+        if grid is None:
+            grid_kwargs = {}
+            grid = True
+        if isinstance(grid, dict):
+            grid_kwargs = grid
+            grid = True
+        else:
+            grid_kwargs = {}
+            grid = bool(grid)
 
         self._semicircle_ticks = None
+        self._unitcircle_ticks = None
 
         self._full = bool(allquadrants)
         if self._full:
-            xlim = (-1.05, 1.05)
-            ylim = (-1.05, 1.05)
+            pad = 0.1 if pad is None else float(abs(pad))
+            xlim = (-1.0 - pad, 1.0 + pad)
+            ylim = (-1.0 - pad, 1.0 + pad)
             xticks: tuple[float, ...] = (-1.0, -0.5, 0.0, 0.5, 1.0)
             yticks: tuple[float, ...] = (-1.0, -0.5, 0.0, 0.5, 1.0)
             if grid:
-                self.polar_grid()
+                self.polar_grid(**grid_kwargs)
         else:
-            xlim = (-0.05, 1.05)
-            ylim = (-0.05, 0.7)
+            pad = 0.05 if pad is None else float(abs(pad))
+            xlim = (-pad, 1.0 + pad)
+            ylim = (-pad, 0.65 + pad)
             xticks = (0.0, 0.2, 0.4, 0.6, 0.8, 1.0)
             yticks = (0.0, 0.2, 0.4, 0.6)
             if grid:
-                self.semicircle(frequency=frequency)
+                self.semicircle(frequency=frequency, **grid_kwargs)
 
         title = 'Phasor plot'
         if frequency is not None:
@@ -135,14 +167,21 @@ class PhasorPlot:
             title=title,
             xlabel='G, real',
             ylabel='S, imag',
-            aspect='equal',
             xlim=xlim,
             ylim=ylim,
             xticks=xticks,
             yticks=yticks,
+            aspect='equal',
         )
-        self._limits = (kwargs['xlim'], kwargs['ylim'])
+        for key in ('xlim', 'ylim', 'xticks', 'yticks', 'title'):
+            if kwargs[key] is None:
+                del kwargs[key]
         self._ax.set(**kwargs)
+        # set axis limits after ticks
+        if 'xlim' in kwargs:
+            self._ax.set_xlim(kwargs['xlim'])
+        if 'ylim' in kwargs:
+            self._ax.set_ylim(kwargs['ylim'])
 
     @property
     def ax(self) -> Axes:
@@ -169,9 +208,22 @@ class PhasorPlot:
 
     def show(self) -> None:
         """Display all open figures. Call :py:func:`matplotlib.pyplot.show`."""
+        if self._labels:
+            self._ax.legend()
         # self.fig.show()
         pyplot.show()
 
+    def legend(self, **kwargs: Any) -> Legend:
+        """Add legend to plot.
+
+        Parameters
+        ----------
+        **kwargs
+            Keyword arguments passed to :py:func:`matplotlib.axes.Axes.legend`.
+
+        """
+        return self._ax.legend(**kwargs)
+
     def save(
         self,
         file: str | os.PathLike[Any] | IO[bytes] | None,
@@ -251,12 +303,11 @@ class PhasorPlot:
             if label is not None:
                 try:
                     lbl = label[i]
+                    if lbl is not None:
+                        self._labels = True
                 except IndexError:
                     pass
             lines = ax.plot(re, im, *args, label=lbl, **kwargs)
-        if label is not None:
-            ax.legend()
-        self._reset_limits()
         return lines
 
     def _histogram2d(
@@ -267,7 +318,7 @@ class PhasorPlot:
         **kwargs: Any,
     ) -> tuple[NDArray[Any], NDArray[Any], NDArray[Any]]:
         """Return two-dimensional histogram of imag versus real coordinates."""
-        update_kwargs(kwargs, range=self._limits)
+        update_kwargs(kwargs, range=(self._ax.get_xlim(), self._ax.get_ylim()))
         (xmin, xmax), (ymin, ymax) = kwargs['range']
         assert xmax > xmin and ymax > ymin
         bins = kwargs.get('bins', 128)
@@ -285,13 +336,6 @@ class PhasorPlot:
             **kwargs,
         )
 
-    def _reset_limits(self) -> None:
-        """Reset axes limits."""
-        try:
-            self._ax.set(xlim=self._limits[0], ylim=self._limits[1])
-        except AttributeError:
-            pass
-
     def hist2d(
         self,
         real: ArrayLike,
@@ -326,7 +370,10 @@ class PhasorPlot:
         if cmax is not None:
             h[h > cmax] = None
         self._ax.pcolormesh(xedges, yedges, h.T, **kwargs)
-        self._reset_limits()
+
+        # TODO: create custom labels for pcolormesh?
+        # if 'label' in kwargs:
+        #     self._labels = True
 
     def contour(
         self,
@@ -359,7 +406,10 @@ class PhasorPlot:
         xedges = xedges[:-1] + ((xedges[1] - xedges[0]) / 2.0)
         yedges = yedges[:-1] + ((yedges[1] - yedges[0]) / 2.0)
         self._ax.contour(xedges, yedges, h.T, **kwargs)
-        self._reset_limits()
+
+        # TODO: create custom labels for contour?
+        # if 'label' in kwargs:
+        #     self._labels = True
 
     def imshow(
         self,
@@ -369,6 +419,8 @@ class PhasorPlot:
     ) -> None:
         """Plot an image, for example, a 2D histogram (not implemented).
 
+        This method is not yet implemented and raises NotImplementedError.
+
         Parameters
         ----------
         image : array_like
@@ -452,14 +504,16 @@ class PhasorPlot:
                 )
 
         if fraction is None:
+            linestyle = kwargs.pop('ls', GRID_LINESTYLE)
+            linewidth = kwargs.pop('lw', GRID_LINEWIDTH)
             update_kwargs(
                 kwargs,
                 edgecolor=GRID_COLOR if color is None else color,
-                linestyle=GRID_LINESTYLE,
-                linewidth=GRID_LINEWIDH,
+                linestyle=linestyle,
+                linewidth=linewidth,
                 fill=GRID_FILL,
             )
-            self._ax.add_patch(Polygon(numpy.vstack((real, imag)).T, **kwargs))
+            self._ax.add_patch(Polygon(numpy.vstack([real, imag]).T, **kwargs))
             if marker is not None:
                 self._ax.plot(
                     real,
@@ -470,18 +524,20 @@ class PhasorPlot:
                     label=label_,
                 )
                 if label_ is not None:
-                    self._ax.legend()
+                    self._labels = True
             return
 
         fraction = numpy.asarray(fraction)[indices]
+        linestyle = kwargs.pop('ls', GRID_LINESTYLE)
+        linewidth = kwargs.pop('lw', GRID_LINEWIDTH)
         update_kwargs(
             kwargs,
             color=GRID_COLOR if color is None else color,
-            linestyle=GRID_LINESTYLE,
-            linewidth=GRID_LINEWIDH,
+            linestyle=linestyle,
+            linewidth=linewidth,
         )
         center_re, center_im = numpy.average(
-            numpy.vstack((real, imag)), axis=-1, weights=fraction
+            numpy.vstack([real, imag]), axis=-1, weights=fraction
         )
         for re, im in zip(real, imag):
             self._ax.add_line(
@@ -498,7 +554,7 @@ class PhasorPlot:
                 label=label_,
             )
             if label_ is not None:
-                self._ax.legend()
+                self._labels = True
 
     def line(
         self,
@@ -525,11 +581,10 @@ class PhasorPlot:
             List containing plotted line.
 
         """
+        linestyle = kwargs.pop('ls', GRID_LINESTYLE)
+        linewidth = kwargs.pop('lw', GRID_LINEWIDTH)
         update_kwargs(
-            kwargs,
-            color=GRID_COLOR,
-            linestyle=GRID_LINESTYLE,
-            linewidth=GRID_LINEWIDH,
+            kwargs, color=GRID_COLOR, linestyle=linestyle, linewidth=linewidth
         )
         return [self._ax.add_line(Line2D(real, imag, **kwargs))]
 
@@ -556,11 +611,13 @@ class PhasorPlot:
             :py:class:`matplotlib.patches.Circle`.
 
         """
+        linestyle = kwargs.pop('ls', GRID_LINESTYLE)
+        linewidth = kwargs.pop('lw', GRID_LINEWIDTH)
         update_kwargs(
             kwargs,
             color=GRID_COLOR,
-            linestyle=GRID_LINESTYLE,
-            linewidth=GRID_LINEWIDH,
+            linestyle=linestyle,
+            linewidth=linewidth,
             fill=GRID_FILL,
         )
         self._ax.add_patch(Circle((real, imag), radius, **kwargs))
@@ -576,7 +633,7 @@ class PhasorPlot:
     ) -> None:
         """Draw arrow between points.
 
-        By default, draw a straight arrow with a `'-|>'` style, a mutation
+        By default, draw a straight arrow with a ``'-|>'`` style, a mutation
         scale of 20, and a miter join style.
 
         Parameters
@@ -612,43 +669,55 @@ class PhasorPlot:
 
     def cursor(
         self,
-        real: float,
-        imag: float,
+        real: ArrayLike,
+        imag: ArrayLike,
+        real_limit: ArrayLike | None = None,
+        imag_limit: ArrayLike | None = None,
         /,
-        real_limit: float | None = None,
-        imag_limit: float | None = None,
-        radius: float | None = None,
-        radius_minor: float | None = None,
-        angle: float | None = None,
-        align_semicircle: bool = False,
+        *,
+        radius: ArrayLike | None = None,
+        radius_minor: ArrayLike | None = None,
+        angle: ArrayLike | Literal['phase', 'semicircle'] | str | None = None,
+        color: ArrayLike | None = None,
+        label: ArrayLike | None = None,
+        crosshair: bool = False,
+        polar: bool = False,
         **kwargs: Any,
     ) -> None:
-        """Plot phase and modulation grid lines and arcs at phasor coordinates.
+        """Draw cursor(s) at phasor coordinates.
 
         Parameters
         ----------
-        real : float
+        real : array_like
             Real component of phasor coordinate.
-        imag : float
+        imag : array_like
             Imaginary component of phasor coordinate.
-        real_limit : float, optional
+        real_limit : array_like, optional
             Real component of limiting phasor coordinate.
-        imag_limit : float, optional
+        imag_limit : array_like, optional
             Imaginary component of limiting phasor coordinate.
-        radius : float, optional
-            Radius of circle limiting phase and modulation grid lines and arcs.
-        radius_minor : float, optional
+        radius : array_like, optional
+            Radius of circular cursor.
+        radius_minor : array_like, optional
             Radius of elliptic cursor along semi-minor axis.
             By default, `radius_minor` is equal to `radius`, that is,
             the ellipse is circular.
-        angle : float, optional
+        angle : array_like or {'phase', 'semicircle'}, optional
             Rotation angle of semi-major axis of elliptic cursor in radians.
-            If None (default), orient ellipse cursor according to
-            `align_semicircle`.
-        align_semicircle : bool, optional
-            Determines elliptic cursor orientation if `angle` is not provided.
-            If true, align the minor axis of the ellipse with the closest
-            tangent on the universal semicircle, else align to the unit circle.
+            If None or 'phase', align the minor axis of the ellipse with
+            the closest tangent on the unit circle.
+            If 'semicircle', align the ellipse with the universal semicircle.
+        color : array_like, optional
+            Color of cursor.
+        label : array_like, optional
+            String label for cursor.
+        crosshair : bool, optional
+            If true, draw polar or Cartesian lines or arcs limited by radius.
+            Else, draw circle or ellipse (default).
+            Only applies if `radius` is provided.
+        polar : bool, optional
+            If true, draw phase line and modulation arc.
+            Else, draw Cartesian lines.
         **kwargs
             Additional parameters passed to
             :py:class:`matplotlib.lines.Line2D`,
@@ -663,64 +732,83 @@ class PhasorPlot:
         """
         if real_limit is not None and imag_limit is not None:
             return self.polar_cursor(
-                *phasor_to_polar_scalar(real, imag),
-                *phasor_to_polar_scalar(real_limit, imag_limit),
+                *phasor_to_polar(real, imag),
+                *phasor_to_polar(real_limit, imag_limit),
                 radius=radius,
                 radius_minor=radius_minor,
                 angle=angle,
-                align_semicircle=align_semicircle,
+                color=color,
+                label=label,
+                crosshair=crosshair,
+                polar=polar,
                 **kwargs,
             )
         return self.polar_cursor(
-            *phasor_to_polar_scalar(real, imag),
+            *phasor_to_polar(real, imag),
             radius=radius,
             radius_minor=radius_minor,
             angle=angle,
-            align_semicircle=align_semicircle,
-            # _circle_only=True,
+            color=color,
+            label=label,
+            crosshair=crosshair,
+            polar=polar,
             **kwargs,
         )
 
     def polar_cursor(
         self,
-        phase: float | None = None,
-        modulation: float | None = None,
-        phase_limit: float | None = None,
-        modulation_limit: float | None = None,
-        radius: float | None = None,
-        radius_minor: float | None = None,
-        angle: float | None = None,
-        align_semicircle: bool = False,
+        phase: ArrayLike | None = None,
+        modulation: ArrayLike | None = None,
+        phase_limit: ArrayLike | None = None,
+        modulation_limit: ArrayLike | None = None,
+        *,
+        radius: ArrayLike | None = None,
+        radius_minor: ArrayLike | None = None,
+        angle: ArrayLike | Literal['phase', 'semicircle'] | str | None = None,
+        color: ArrayLike | None = None,
+        label: ArrayLike | None = None,
+        crosshair: bool = False,
+        polar: bool = True,
         **kwargs: Any,
     ) -> None:
-        """Plot phase and modulation grid lines and arcs.
+        """Draw cursor(s) at polar coordinates.
 
         Parameters
         ----------
-        phase : float, optional
+        phase : array_like, optional
             Angular component of polar coordinate in radians.
-        modulation : float, optional
+        modulation : array_like, optional
             Radial component of polar coordinate.
-        phase_limit : float, optional
+        phase_limit : array_like, optional
             Angular component of limiting polar coordinate (in radians).
-            Modulation grid arcs are drawn between `phase` and `phase_limit`.
-        modulation_limit : float, optional
+            Modulation arcs are drawn between `phase` and `phase_limit`
+            if `polar` is true.
+        modulation_limit : array_like, optional
             Radial component of limiting polar coordinate.
-            Phase grid lines are drawn from `modulation` to `modulation_limit`.
-        radius : float, optional
-            Radius of circle limiting phase and modulation grid lines and arcs.
-        radius_minor : float, optional
+            Phase lines are drawn from `modulation` to `modulation_limit`
+            if `polar` is true.
+        radius : array_like, optional
+            Radius of circular cursor.
+        radius_minor : array_like, optional
             Radius of elliptic cursor along semi-minor axis.
             By default, `radius_minor` is equal to `radius`, that is,
             the ellipse is circular.
-        angle : float, optional
+        angle : array_like or {'phase', 'semicircle'}, optional
             Rotation angle of semi-major axis of elliptic cursor in radians.
-            If None (default), orient ellipse cursor according to
-            `align_semicircle`.
-        align_semicircle : bool, optional
-            Determines elliptic cursor orientation if `angle` is not provided.
-            If true, align the minor axis of the ellipse with the closest
-            tangent on the universal semicircle, else align to the unit circle.
+            If None or 'phase', align the minor axis of the ellipse with
+            the closest tangent on the unit circle.
+            If 'semicircle', align the ellipse with the universal semicircle.
+        color : array_like, optional
+            Color of cursor.
+        label : array_like, optional
+            String label for cursor.
+        crosshair : bool, optional
+            If true, draw polar or Cartesian lines or arcs limited by radius.
+            Else, draw circle or ellipse (default).
+            Only applies if `radius` is provided.
+        polar : bool, optional
+            If true, draw phase line and modulation arc.
+            Else, draw Cartesian lines.
         **kwargs
             Additional parameters passed to
             :py:class:`matplotlib.lines.Line2D`,
@@ -733,42 +821,169 @@ class PhasorPlot:
         phasorpy.plot.PhasorPlot.cursor
 
         """
+        shape = None
+        if phase is not None:
+            phase = numpy.atleast_1d(phase)
+            if phase.ndim != 1:
+                raise ValueError(f'invalid {phase.ndim=} != 1')
+            shape = phase.shape
+        if modulation is not None:
+            if shape is not None:
+                modulation = numpy.broadcast_to(modulation, shape)
+            else:
+                modulation = numpy.atleast_1d(modulation)
+                if modulation.ndim != 1:
+                    raise ValueError(f'invalid {modulation.ndim=} != 1')
+                shape = modulation.shape
+        if shape is None:
+            return
+
+        if phase_limit is not None:
+            phase_limit = numpy.broadcast_to(phase_limit, shape)
+        if modulation_limit is not None:
+            modulation_limit = numpy.broadcast_to(modulation_limit, shape)
+        if radius is not None:
+            radius = numpy.broadcast_to(radius, shape)
+        if radius_minor is not None:
+            radius_minor = numpy.broadcast_to(radius_minor, shape)
+        if angle is not None and not isinstance(angle, str):
+            angle = numpy.broadcast_to(angle, shape)
+        if label is not None:
+            label = numpy.broadcast_to(label, shape)
+            label = [str(c) for c in label]
+        if color is not None:
+            color = numpy.atleast_1d(color)
+            if color.dtype.kind == 'U':
+                color = numpy.broadcast_to(color, shape)
+                color = [str(c) for c in color]
+            else:
+                color = numpy.broadcast_to(color, (shape[0], color.shape[-1]))
+
+        for i in range(shape[0]):
+
+            if color is not None:
+                kwargs['color'] = color[i]
+            if label is not None:
+                kwargs['label'] = label[i]
+
+            self._cursor(
+                phase if phase is None else float(phase[i]),
+                modulation if modulation is None else float(modulation[i]),
+                phase_limit if phase_limit is None else float(phase_limit[i]),
+                (
+                    modulation_limit
+                    if modulation_limit is None
+                    else float(modulation_limit[i])
+                ),
+                radius=radius if radius is None else float(radius[i]),
+                radius_minor=(
+                    radius_minor
+                    if radius_minor is None
+                    else float(radius_minor[i])
+                ),
+                angle=(
+                    angle
+                    if (angle is None or isinstance(angle, str))
+                    else float(angle[i])
+                ),
+                crosshair=crosshair,
+                polar=polar,
+                **kwargs,
+            )
+
+    def _cursor(
+        self,
+        phase: float | None = None,
+        modulation: float | None = None,
+        phase_limit: float | None = None,
+        modulation_limit: float | None = None,
+        *,
+        radius: float | None = None,
+        radius_minor: float | None = None,
+        angle: float | Literal['phase', 'semicircle'] | str | None = None,
+        crosshair: bool = False,
+        polar: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        """Draw single cursor at polar coordinate."""
+        linestyle = kwargs.pop('ls', GRID_LINESTYLE_MAJOR)
+        linewidth = kwargs.pop('lw', GRID_LINEWIDTH)
         update_kwargs(
             kwargs,
             color=GRID_COLOR,
-            linestyle=GRID_LINESTYLE,
-            linewidth=GRID_LINEWIDH,
+            linestyle=linestyle,
+            linewidth=linewidth,
             fill=GRID_FILL,
+            zorder=GRID_ZORDER,
         )
-        _circle_only = kwargs.pop('_circle_only', False)
+
         ax = self._ax
         if radius is not None and phase is not None and modulation is not None:
             x = modulation * math.cos(phase)
             y = modulation * math.sin(phase)
             if radius_minor is not None and radius_minor != radius:
                 if angle is None:
-                    if align_semicircle:
+                    angle = phase
+                elif isinstance(angle, str):
+                    if angle == 'phase':
+                        angle = phase
+                    elif angle == 'semicircle':
                         angle = math.atan2(y, x - 0.5)
                     else:
-                        angle = phase
+                        raise ValueError(f'invalid {angle=}')
                 angle = math.degrees(angle)
-                ax.add_patch(
-                    Ellipse(
-                        (x, y),
-                        radius * 2,
-                        radius_minor * 2,
-                        angle=angle,
-                        **kwargs,
+
+                if not crosshair:
+                    # draw elliptical cursor
+                    ax.add_patch(
+                        Ellipse(
+                            (x, y),
+                            radius * 2,
+                            radius_minor * 2,
+                            angle=angle,
+                            **kwargs,
+                        )
                     )
+                    if 'label' in kwargs:
+                        self._labels = True
+                    return None
+
+                # TODO: implement crosshair intersecting with ellipse?
+                raise ValueError('crosshair not implemented with ellipse')
+
+            if not crosshair:
+                # draw circlar cursor
+                ax.add_patch(Circle((x, y), radius, **kwargs))
+                if 'label' in kwargs:
+                    self._labels = True
+                return None
+
+            del kwargs['fill']
+            if not polar:
+                # draw Cartesian crosshair lines limited by radius
+                x0, y0, x1, y1 = _intersect_circle_line(
+                    x, y, radius, x, y, x + 1, y
                 )
-                # TODO: implement gridlines intersecting with ellipse
+                ax.add_line(Line2D([x0, x1], [y0, y1], **kwargs))
+                if 'label' in kwargs:
+                    self._labels = True
+                    del kwargs['label']
+                x0, y0, x1, y1 = _intersect_circle_line(
+                    x, y, radius, x, y, x, y + 1
+                )
+                ax.add_line(Line2D([x0, x1], [y0, y1], **kwargs))
                 return None
-            ax.add_patch(Circle((x, y), radius, **kwargs))
-            if _circle_only:
+
+            if abs(x) < 1e-6 and abs(y) < 1e-6:
+                # phase and modulation not defined at origin
                 return None
-            del kwargs['fill']
+
+            # draw crosshair phase line and modulation arc limited by circle
             x0, y0, x1, y1 = _intersect_circle_line(x, y, radius, 0, 0, x, y)
-            ax.add_line(Line2D((x0, x1), (y0, y1), **kwargs))
+            ax.add_line(Line2D([x0, x1], [y0, y1], **kwargs))
+            if 'label' in kwargs:
+                self._labels = True
+                del kwargs['label']
             x0, y0, x1, y1 = _intersect_circle_circle(
                 0, 0, modulation, x, y, radius
             )
@@ -785,6 +1000,30 @@ class PhasorPlot:
             )
             return None
 
+        if not polar:
+            if phase is None or modulation is None:
+                return None
+
+            x0 = modulation * math.cos(phase)
+            y0 = modulation * math.sin(phase)
+            if phase_limit is None or modulation_limit is None:
+                # draw Cartesian crosshair lines
+                del kwargs['fill']
+                ax.add_line(Line2D([x0, x0], [-2, 2], **kwargs))
+                if 'label' in kwargs:
+                    self._labels = True
+                    del kwargs['label']
+                ax.add_line(Line2D([-2, 2], [y0, y0], **kwargs))
+            else:
+                # draw rectangle
+                x1 = modulation_limit * math.cos(phase_limit)
+                y1 = modulation_limit * math.sin(phase_limit)
+                ax.add_patch(Rectangle((x0, y0), x1 - x0, y1 - y0, **kwargs))
+                if 'label' in kwargs:
+                    self._labels = True
+            return None
+
+        # TODO: implement filled polar region/rectangle
         del kwargs['fill']
         for phi in (phase, phase_limit):
             if phi is not None:
@@ -796,9 +1035,12 @@ class PhasorPlot:
                 else:
                     x0 = 0
                     y0 = 0
-                    x1 = math.cos(phi)
-                    y1 = math.sin(phi)
-                ax.add_line(Line2D((x0, x1), (y0, y1), **kwargs))
+                    x1 = math.cos(phi) * 2
+                    y1 = math.sin(phi) * 2
+                ax.add_line(Line2D([x0, x1], [y0, y1], **kwargs))
+                if 'label' in kwargs:
+                    self._labels = True
+                    del kwargs['label']
         for mod in (modulation, modulation_limit):
             if mod is not None:
                 if phase is not None and phase_limit is not None:
@@ -806,7 +1048,8 @@ class PhasorPlot:
                     theta2 = math.degrees(max(phase, phase_limit))
                 else:
                     theta1 = 0.0
-                    theta2 = 360.0 if self._full else 90.0
+                    theta2 = 360.0  # if self._full else 90.0
+                # TODO: filling arc objects is not supported
                 ax.add_patch(
                     Arc(
                         (0, 0),
@@ -814,51 +1057,176 @@ class PhasorPlot:
                         mod * 2,
                         theta1=theta1,
                         theta2=theta2,
-                        fill=False,  # filling arc objects is not supported
+                        fill=False,
                         **kwargs,
                     )
                 )
+                if 'label' in kwargs:
+                    self._labels = True
+                    del kwargs['label']
         return None
 
-    def polar_grid(self, **kwargs: Any) -> None:
-        """Draw polar coordinate system.
+    def polar_grid(
+        self,
+        radii: int | Sequence[float] | None = None,
+        angles: int | Sequence[float] | None = None,
+        samples: int | None = None,
+        labels: Sequence[str] | None = None,
+        ticks: ArrayLike | None = None,
+        tick_space: ArrayLike | None = None,
+        tick_format: str | None = None,
+        **kwargs: Any,
+    ) -> None:
+        r"""Draw polar coordinate system.
 
         Parameters
         ----------
+        radii : int or sequence of float, optional
+            Position of radial gridlines in range (0, 1].
+            If an integer, the number of equidistant radial gridlines.
+            By default, three equidistant radial gridlines are drawn.
+            The unit circle (radius 1), if included, is drawn in major style.
+        angles : int or sequence of float, optional
+            Position of angular gridlines in range [0, 2 pi].
+            If an integer, the number of equidistant angular gridlines.
+            By default, 12 equidistant angular gridlines are drawn.
+        samples : int, optional
+            Number of vertices of polygon inscribed in unit circle.
+            By default, no inscribed polygon is drawn.
+        labels : sequence of str, optional
+            Tick labels on unit circle.
+            Labels are placed at equidistant angles if `ticks` are not
+            provided.
+        ticks : array_like, optional
+            Values at which to place tick labels on unit circle.
+            If `labels` are not provided, `ticks` values formatted with
+            `tick_format` are used as labels.
+            If `tick_space` is not provided, tick values are angles in radians.
+        tick_space : array_like, optional
+            Values used to convert `ticks` to angles.
+            For example, the wavelengths used to calculate spectral phasors
+            or the minimum and maximum wavelengths of a sine-cosine filter.
+        tick_format : str, optional
+            Format string for tick values if `labels` is None.
+            By default, the tick format is "{}".
         **kwargs
             Parameters passed to
             :py:class:`matplotlib.patches.Circle` and
             :py:class:`matplotlib.lines.Line2D`.
 
+        Raises
+        ------
+        ValueError
+            If number of ticks doesn't match number of labels.
+            If `tick_space` has less than two values.
+
+        Notes
+        -----
+        Use ``radii=1, angles=4`` to draw major gridlines only.
+
+        The values of ticks (:math:`v`) are converted to angles
+        (:math:`\theta`) using `tick_space` (:math:`s`) according to:
+
+        .. math::
+            \theta = \frac{v - s_0}{s_{-1} + s_1 - 2 s_0} \cdot 2 \pi
+
         """
         ax = self._ax
-        # major gridlines
-        kwargs_copy = kwargs.copy()
+        minor_kwargs = kwargs.copy()
+        linestyle = minor_kwargs.pop('ls', GRID_LINESTYLE)
+        linewidth = minor_kwargs.pop('lw', GRID_LINEWIDTH_MINOR)
         update_kwargs(
-            kwargs,
+            minor_kwargs,
             color=GRID_COLOR,
-            linestyle=GRID_LINESTYLE_MAJOR,
-            linewidth=GRID_LINEWIDH,
-            # fill=GRID_FILL,
+            linestyle=linestyle,
+            linewidth=linewidth,
+            zorder=GRID_ZORDER,
         )
-        ax.add_line(Line2D([-1, 1], [0, 0], **kwargs))
-        ax.add_line(Line2D([0, 0], [-1, 1], **kwargs))
-        ax.add_patch(Circle((0, 0), 1, fill=False, **kwargs))
-        # minor gridlines
-        kwargs = kwargs_copy
+        linestyle = kwargs.pop('ls', GRID_LINESTYLE_MAJOR)
+        linewidth = kwargs.pop('lw', GRID_LINEWIDTH)
         update_kwargs(
             kwargs,
             color=GRID_COLOR,
-            linestyle=GRID_LINESTYLE,
-            linewidth=GRID_LINEWIDH_MINOR,
+            linestyle=linestyle,
+            linewidth=linewidth,
+            zorder=GRID_ZORDER,
+            # fill=GRID_FILL,
         )
-        for r in (1 / 3, 2 / 3):
-            ax.add_patch(Circle((0, 0), r, fill=False, **kwargs))
-        for a in (3, 6):
-            x = math.cos(math.pi / a)
-            y = math.sin(math.pi / a)
-            ax.add_line(Line2D([-x, x], [-y, y], **kwargs))
-            ax.add_line(Line2D([-x, x], [y, -y], **kwargs))
+
+        if samples is not None and samples > 1:
+            angle = numpy.linspace(0, 2 * math.pi, samples, endpoint=False)
+            xy = numpy.vstack([numpy.cos(angle), numpy.sin(angle)]).T
+            ax.add_patch(Polygon(xy, fill=False, **kwargs))
+
+        if radii is None:
+            radii = [1 / 3, 2 / 3, 1.0]
+        elif isinstance(radii, int):
+            radii = numpy.linspace(0, 1, radii + 1, endpoint=True)[1:].tolist()
+        for r in radii:  # type: ignore[union-attr]
+            if r < 1e-3:
+                # skip zero radius
+                continue
+            if abs(r - 1.0) < 1e-3:
+                # unit circle
+                circle = Circle((0, 0), 1, fill=False, **kwargs)
+            elif r > 1.0:
+                continue
+            else:
+                # minor circle
+                circle = Circle((0, 0), r, fill=False, **minor_kwargs)
+            ax.add_patch(circle)
+
+        if angles is None:
+            angles = 12
+        if isinstance(angles, int):
+            angles = numpy.linspace(
+                0, 2 * math.pi, angles, endpoint=False
+            ).tolist()
+        for a in angles:  # type: ignore[union-attr]
+            if a < 0 or a > 2 * math.pi:
+                # skip angles out of range
+                continue
+            x = math.cos(a)
+            y = math.sin(a)
+            ax.add_line(Line2D([0.0, x], [0.0, y], **minor_kwargs))
+
+        if labels is None and ticks is None:
+            # no labels
+            return
+        if ticks is None:
+            # equidistant labels
+            assert labels is not None
+            ticks = numpy.linspace(0, 2 * math.pi, len(labels), endpoint=False)
+            tick_space = None
+        elif labels is None:
+            # use tick values as labels
+            assert ticks is not None
+            ticks = numpy.array(ticks, copy=True, ndmin=1)
+            if tick_format is None:
+                tick_format = '{}'
+            labels = [tick_format.format(t) for t in ticks]
+            ticks = ticks.astype(numpy.float64)
+        else:
+            # ticks and labels
+            ticks = numpy.array(ticks, dtype=numpy.float64, copy=True, ndmin=1)
+            if ticks.size != len(labels):
+                raise ValueError(f'{ticks.size=} != {len(labels)=}')
+
+        if tick_space is not None:
+            tick_space = numpy.asarray(tick_space, dtype=numpy.float64)
+            if tick_space.ndim != 1 or tick_space.size < 2:
+                raise ValueError(
+                    f'invalid {tick_space.ndim=} or {tick_space.size=} < 2'
+                )
+            assert isinstance(ticks, numpy.ndarray)  # for mypy
+            ticks -= tick_space[0]
+            ticks /= tick_space[-1] + tick_space[1] - 2 * tick_space[0]
+            ticks *= 2 * math.pi
+
+        real = numpy.cos(ticks)
+        imag = numpy.sin(ticks)
+        self._unitcircle_ticks = CircleTicks(labels=labels)
+        ax.plot(real, imag, path_effects=[self._unitcircle_ticks], **kwargs)
 
     def semicircle(
         self,
@@ -901,19 +1269,25 @@ class PhasorPlot:
 
         Returns
         -------
-        list[matplotlib.lines.Line2D]
+        list of matplotlib.lines.Line2D
             Lines representing plotted semicircle and ticks.
 
         """
         if frequency is not None:
             self._frequency = float(frequency)
 
+        linestyle = kwargs.pop('ls', GRID_LINESTYLE_MAJOR)
+        linewidth = kwargs.pop('lw', GRID_LINEWIDTH)
         update_kwargs(
             kwargs,
+            linestyle=linestyle,
+            linewidth=linewidth,
             color=GRID_COLOR,
-            linestyle=GRID_LINESTYLE_MAJOR,
-            linewidth=GRID_LINEWIDH,
+            zorder=GRID_ZORDER,
         )
+        if 'label' in kwargs:
+            self._labels = True
+
         if phasor_reference is not None:
             polar_reference = phasor_to_polar_scalar(*phasor_reference)
         if polar_reference is None:
@@ -949,10 +1323,13 @@ class PhasorPlot:
                     )
                 )
 
+        kwargs.pop('label', None)  # don't pass label to ticks
+        kwargs.pop('capstyle', None)
+
         if frequency is not None and polar_reference == (0.0, 1.0):
             # draw ticks and labels
             lifetime, labels = _semicircle_ticks(frequency, lifetime, labels)
-            self._semicircle_ticks = SemicircleTicks(labels=labels)
+            self._semicircle_ticks = CircleTicks((0.5, 0.0), labels=labels)
             lines.extend(
                 ax.plot(
                     *phasor_transform(
@@ -963,7 +1340,6 @@ class PhasorPlot:
                     **kwargs,
                 )
             )
-        self._reset_limits()
         return lines
 
     def _on_format_coord(self, x: float, y: float) -> str:
@@ -979,11 +1355,13 @@ class PhasorPlot:
         return '  '.join(reversed(ret))
 
 
-class SemicircleTicks(AbstractPathEffect):
-    """Draw ticks on universal semicircle.
+class CircleTicks(AbstractPathEffect):
+    """Draw ticks on unit circle or universal semicircle.
 
     Parameters
     ----------
+    origin : (float, float), optional
+        Origin of circle.
     size : float, optional
         Length of tick in dots.
         The default is ``rcParams['xtick.major.size']``.
@@ -995,23 +1373,31 @@ class SemicircleTicks(AbstractPathEffect):
 
     """
 
+    _origin: tuple[float, float]  # origin of circle
     _size: float  # tick length
     _labels: tuple[str, ...]  # tick labels
     _gc: dict[str, Any]  # keywords passed to _update_gc
 
     def __init__(
         self,
+        origin: tuple[float, float] | None = None,
+        /,
         size: float | None = None,
         labels: Sequence[str] | None = None,
         **kwargs: Any,
     ) -> None:
         super().__init__((0.0, 0.0))
 
+        if origin is None:
+            self._origin = 0.0, 0.0
+        else:
+            self._origin = float(origin[0]), float(origin[1])
+
         if size is None:
             self._size = pyplot.rcParams['xtick.major.size']
         else:
             self._size = size
-        if labels is None or not labels:
+        if labels is None or len(labels) == 0:
             self._labels = ()
         else:
             self._labels = tuple(labels)
@@ -1024,7 +1410,7 @@ class SemicircleTicks(AbstractPathEffect):
 
     @labels.setter
     def labels(self, value: Sequence[str] | None, /) -> None:
-        if value is None or not value:
+        if value is None:
             self._labels = ()
         else:
             self._labels = tuple(value)
@@ -1050,7 +1436,7 @@ class SemicircleTicks(AbstractPathEffect):
         # approximate half size of 'x'
         fontsize = renderer.points_to_pixels(font.get_size_in_points()) / 4
         size = renderer.points_to_pixels(self._size)
-        origin = affine.transform([[0.5, 0.0]])
+        origin = affine.transform((self._origin,))
 
         transpath = affine.transform_path(tpath)
         polys = transpath.to_polygons(closed_only=False)
@@ -1088,6 +1474,8 @@ class SemicircleTicks(AbstractPathEffect):
                 # TODO: get rendered text size from matplotlib.text.Text?
                 # this did not work:
                 # Text(d[i,0], h - d[i,1], label, ha='center', va='center')
+                if not s:
+                    continue
                 x = x + fontsize * len(s.split()[0]) * (dx - 1.0)
                 y = h - y + fontsize
                 renderer.draw_text(gc0, x, y, s, font, 0.0)