Added named_arrays.plt.text() function.

named_arrays/_scalars/scalar_named_array_functions.py

@@ -570,6 +570,46 @@
     return result
 
 
+@_implements(na.plt.text)
+def plt_text(
+    x: float | u.Quantity | na.AbstractScalarArray,
+    y: float | u.Quantity | na.AbstractScalarArray,
+    s: str | na.AbstractScalarArray,
+    ax: None | matplotlib.axes.Axes | na.AbstractScalarArray = None,
+    **kwargs,
+) -> na.AbstractScalarArray:
+
+    if ax is None:
+        ax = plt.gca()
+
+    try:
+        x = scalars._normalize(x)
+        y = scalars._normalize(y)
+        s = scalars._normalize(s)
+        ax = scalars._normalize(ax)
+    except na.ScalarTypeError:  # pragma: nocover
+        return NotImplemented
+
+    shape = na.shape_broadcasted(x, y, s, ax)
+
+    x = x.broadcast_to(shape)
+    y = y.broadcast_to(shape)
+    s = s.broadcast_to(shape)
+    ax = ax.broadcast_to(shape)
+
+    result = na.ScalarArray.empty(shape, dtype=matplotlib.axes.Axes)
+
+    for index in na.ndindex(shape):
+        result[index] = ax[index].ndarray.text(
+            x=x[index].ndarray,
+            y=y[index].ndarray,
+            s=s[index].ndarray,
+            **kwargs,
+        )
+
+    return result
+
+
 @_implements(na.jacobian)
 def jacobian(
         function: Callable[[na.AbstractScalar], na.AbstractScalar],

named_arrays/_scalars/tests/test_scalars.py

@@ -957,6 +957,16 @@
                 assert isinstance(result, na.ScalarArray)
                 assert result.dtype == matplotlib.image.AxesImage
 
+        class TestPltText:
+
+            def test_plt_text(self, array):
+                result = na.plt.text(
+                    x=array,
+                    y=array,
+                    s="test label",
+                )
+                assert isinstance(result, na.ScalarArray)
+
         @pytest.mark.parametrize(
             argnames="function",
             argvalues=[

named_arrays/plt.py

@@ -2,6 +2,7 @@
 from typing import Literal
 import matplotlib
 import matplotlib.pyplot as plt
+import astropy.units as u
 import numpy.typing as npt
 import named_arrays as na
 
@@ -12,6 +13,7 @@
     "scatter",
     "imshow",
     "pcolormesh",
+    "text",
 ]
 
 
@@ -627,3 +629,72 @@
         components=components,
         **kwargs,
     )
+
+
+def text(
+    x: float | u.Quantity | na.AbstractScalar,
+    y: float | u.Quantity | na.AbstractScalar,
+    s: str | na.AbstractScalar,
+    ax: None | matplotlib.axes.Axes | na.AbstractScalar = None,
+    **kwargs,
+) -> na.AbstractScalar:
+    """
+    A thin wrapper around :meth:`matplotlib.axes.Axes.text` for named arrays.
+
+    Parameters
+    ----------
+    x
+        The horizontal position of the text in data coordinates.
+    y
+        The vertical position of the text in data coordinates.
+    s
+        The text to plot.
+    ax
+        The matplotlib axes instance on which to plot the text.
+    kwargs
+        Additional keyword arguments to pass to :meth:`matplotlib.axes.Axes.text`.
+
+    Examples
+    --------
+
+    Plot an array of text values at different locations.
+
+    .. jupyter-execute::
+
+        import numpy as np
+        import matplotlib.pyplot as plt
+        import astropy.units as u
+        import named_arrays as na
+
+        # Create an array of azimuths where the next will be placed
+        azimuth = na.linspace(0, 360, axis="azimuth", num=4, endpoint=False) * u.deg
+
+        # Compute the x and y coordinates for the given azimuth
+        x = np.cos(azimuth)
+        y = np.sin(azimuth)
+
+        # Create an array of strings to plot at the chosen positions
+        s = na.ScalarArray(
+            ndarray=np.array(["East", "North", "West", "South"]),
+            axes="azimuth"
+        )
+
+        # Plot the array of strings
+        fig, ax = plt.subplots()
+        na.plt.text(
+            x=x,
+            y=y,
+            s=s,
+            ax=ax,
+        );
+        ax.set_xlim(-2, 2);
+        ax.set_ylim(-2, 2);
+    """
+    return na._named_array_function(
+        text,
+        x=x,
+        y=y,
+        s=s,
+        ax=ax,
+        **kwargs,
+    )