Align naming convention with plt.subplots (#7194)

* Align axs naming with plt.subplots

* Update plotting.rst

* Update facetgrid.py

* Update facetgrid.py

* Update doc/user-guide/plotting.rst

Co-authored-by: Mathias Hauser <[email protected]>

* Update facetgrid.py

* Update whats-new.rst

* Update facetgrid.py

Co-authored-by: Mathias Hauser <[email protected]>

Author: Illviljan

doc/user-guide/plotting.rst

@@ -156,18 +156,18 @@ Keyword arguments work the same way, and are more explicit.
 
 To add the plot to an existing axis pass in the axis as a keyword argument
 ``ax``. This works for all xarray plotting methods.
-In this example ``axes`` is an array consisting of the left and right
+In this example ``axs`` is an array consisting of the left and right
 axes created by ``plt.subplots``.
 
 .. ipython:: python
     :okwarning:
 
-    fig, axes = plt.subplots(ncols=2)
+    fig, axs = plt.subplots(ncols=2)
 
-    axes
+    axs
 
-    air1d.plot(ax=axes[0])
-    air1d.plot.hist(ax=axes[1])
+    air1d.plot(ax=axs[0])
+    air1d.plot.hist(ax=axs[1])
 
     plt.tight_layout()
 
@@ -348,8 +348,8 @@ The keyword arguments ``xincrease`` and ``yincrease`` let you control the axes d
 
 In addition, one can use ``xscale, yscale`` to set axes scaling;
 ``xticks, yticks`` to set axes ticks and ``xlim, ylim`` to set axes limits.
-These accept the same values as the matplotlib methods ``Axes.set_(x,y)scale()``,
-``Axes.set_(x,y)ticks()``, ``Axes.set_(x,y)lim()`` respectively.
+These accept the same values as the matplotlib methods ``ax.set_(x,y)scale()``,
+``ax.set_(x,y)ticks()``, ``ax.set_(x,y)lim()``, respectively.
 
 
 Two Dimensions
@@ -701,12 +701,12 @@ that links a :py:class:`DataArray` to a matplotlib figure with a particular stru
 This object can be used to control the behavior of the multiple plots.
 It borrows an API and code from `Seaborn's FacetGrid
 <https://seaborn.pydata.org/tutorial/axis_grids.html>`_.
-The structure is contained within the ``axes`` and ``name_dicts``
+The structure is contained within the ``axs`` and ``name_dicts``
 attributes, both 2d NumPy object arrays.
 
 .. ipython:: python
 
-    g.axes
+    g.axs
 
     g.name_dicts
 
@@ -726,10 +726,10 @@ they have been plotted.
 
     g = t.plot.imshow(x="lon", y="lat", col="time", col_wrap=3, robust=True)
 
-    for i, ax in enumerate(g.axes.flat):
+    for i, ax in enumerate(g.axs.flat):
         ax.set_title("Air Temperature %d" % i)
 
-    bottomright = g.axes[-1, -1]
+    bottomright = g.axs[-1, -1]
     bottomright.annotate("bottom right", (240, 40))
 
     @savefig plot_facet_iterator.png
@@ -928,7 +928,7 @@ by faceting are accessible in the object returned by ``plot``:
         col="time",
         subplot_kws={"projection": ccrs.Orthographic(-80, 35)},
     )
-    for ax in p.axes.flat:
+    for ax in p.axs.flat:
         ax.coastlines()
         ax.gridlines()
     @savefig plotting_maps_cartopy_facetting.png width=100%
@@ -958,11 +958,11 @@ These are provided for user convenience; they all call the same code.
     import xarray.plot as xplt
 
     da = xr.DataArray(range(5))
-    fig, axes = plt.subplots(ncols=2, nrows=2)
-    da.plot(ax=axes[0, 0])
-    da.plot.line(ax=axes[0, 1])
-    xplt.plot(da, ax=axes[1, 0])
-    xplt.line(da, ax=axes[1, 1])
+    fig, axs = plt.subplots(ncols=2, nrows=2)
+    da.plot(ax=axs[0, 0])
+    da.plot.line(ax=axs[0, 1])
+    xplt.plot(da, ax=axs[1, 0])
+    xplt.line(da, ax=axs[1, 1])
     plt.tight_layout()
     @savefig plotting_ways_to_use.png width=6in
     plt.draw()

doc/whats-new.rst

@@ -42,6 +42,10 @@ Deprecations
 
 - Positional arguments for all plot methods have been deprecated (:issue:`6949`, :pull:`7052`).
   By `Michael Niklas <https://github.com/headtr1ck>`_.
+- ``xarray.plot.FacetGrid.axes`` has been renamed to ``xarray.plot.FacetGrid.axs``
+  because it's not clear if ``axes`` refers to single or multiple ``Axes`` instances.
+  This aligns with ``matplotlib.pyplot.subplots``. (:pull:`7194`)
+  By `Jimmy Westling <https://github.com/illviljan>`_.
 
 Bug fixes
 ~~~~~~~~~
@@ -60,7 +64,8 @@ Documentation
   By `Jessica Scheick <https://github.com/jessicas11>`_.
 - Add example of using :py:meth:`DataArray.coarsen.construct` to User Guide. (:pull:`7192`)
   By `Tom Nicholas <https://github.com/TomNicholas>`_.
-
+- Rename ``axes`` to ``axs`` in plotting to align with ``matplotlib.pyplot.subplots``. (:pull:`7194`)
+  By `Jimmy Westling <https://github.com/illviljan>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~

xarray/plot/facetgrid.py

@@ -94,7 +94,7 @@ class FacetGrid(Generic[T_Xarray]):
 
     Attributes
     ----------
-    axes : ndarray of matplotlib.axes.Axes
+    axs : ndarray of matplotlib.axes.Axes
         Array containing axes in corresponding position, as returned from
         :py:func:`matplotlib.pyplot.subplots`.
     col_labels : list of matplotlib.text.Annotation
@@ -112,7 +112,7 @@ class FacetGrid(Generic[T_Xarray]):
     data: T_Xarray
     name_dicts: np.ndarray
     fig: Figure
-    axes: np.ndarray
+    axs: np.ndarray
     row_names: list[np.ndarray]
     col_names: list[np.ndarray]
     figlegend: Legend | None
@@ -223,7 +223,7 @@ def __init__(
             cbar_space = 1
             figsize = (ncol * size * aspect + cbar_space, nrow * size)
 
-        fig, axes = plt.subplots(
+        fig, axs = plt.subplots(
             nrow,
             ncol,
             sharex=sharex,
@@ -258,7 +258,7 @@ def __init__(
         self.data = data
         self.name_dicts = name_dicts
         self.fig = fig
-        self.axes = axes
+        self.axs = axs
         self.row_names = row_names
         self.col_names = col_names
 
@@ -282,13 +282,37 @@ def __init__(
         self._mappables = []
         self._finalized = False
 
+    @property
+    def axes(self) -> np.ndarray:
+        warnings.warn(
+            (
+                "self.axes is deprecated since 2022.11 in order to align with "
+                "matplotlibs plt.subplots, use self.axs instead."
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.axs
+
+    @axes.setter
+    def axes(self, axs: np.ndarray) -> None:
+        warnings.warn(
+            (
+                "self.axes is deprecated since 2022.11 in order to align with "
+                "matplotlibs plt.subplots, use self.axs instead."
+            ),
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        self.axs = axs
+
     @property
     def _left_axes(self) -> np.ndarray:
-        return self.axes[:, 0]
+        return self.axs[:, 0]
 
     @property
     def _bottom_axes(self) -> np.ndarray:
-        return self.axes[-1, :]
+        return self.axs[-1, :]
 
     def map_dataarray(
         self: T_FacetGrid,
@@ -347,7 +371,7 @@ def map_dataarray(
             rgb=kwargs.get("rgb", None),
         )
 
-        for d, ax in zip(self.name_dicts.flat, self.axes.flat):
+        for d, ax in zip(self.name_dicts.flat, self.axs.flat):
             # None is the sentinel value
             if d is not None:
                 subset = self.data.loc[d]
@@ -449,7 +473,7 @@ def map_plot1d(
         func_kwargs["add_legend"] = False
         func_kwargs["add_title"] = False
 
-        add_labels_ = np.zeros(self.axes.shape + (3,), dtype=bool)
+        add_labels_ = np.zeros(self.axs.shape + (3,), dtype=bool)
         if kwargs.get("z") is not None:
             # 3d plots looks better with all labels. 3d plots can't sharex either so it
             # is easy to get lost while rotating the plots:
@@ -478,7 +502,7 @@ def map_plot1d(
 
         # Plot the data for each subplot:
         for add_lbls, d, ax in zip(
-            add_labels_.reshape((self.axes.size, -1)), name_dicts.flat, self.axes.flat
+            add_labels_.reshape((self.axs.size, -1)), name_dicts.flat, self.axs.flat
         ):
             func_kwargs["add_labels"] = add_lbls
             # None is the sentinel value
@@ -542,7 +566,7 @@ def map_dataarray_line(
     ) -> T_FacetGrid:
         from .dataarray_plot import _infer_line_data
 
-        for d, ax in zip(self.name_dicts.flat, self.axes.flat):
+        for d, ax in zip(self.name_dicts.flat, self.axs.flat):
             # None is the sentinel value
             if d is not None:
                 subset = self.data.loc[d]
@@ -609,7 +633,7 @@ def map_dataset(
             raise ValueError("Please provide scale.")
             # TODO: come up with an algorithm for reasonable scale choice
 
-        for d, ax in zip(self.name_dicts.flat, self.axes.flat):
+        for d, ax in zip(self.name_dicts.flat, self.axs.flat):
             # None is the sentinel value
             if d is not None:
                 subset = self.data.loc[d]
@@ -643,7 +667,7 @@ def _finalize_grid(self, *axlabels: Hashable) -> None:
             self.set_titles()
             self.fig.tight_layout()
 
-            for ax, namedict in zip(self.axes.flat, self.name_dicts.flat):
+            for ax, namedict in zip(self.axs.flat, self.name_dicts.flat):
                 if namedict is None:
                     ax.set_visible(False)
 
@@ -703,15 +727,15 @@ def add_colorbar(self, **kwargs: Any) -> None:
         if "label" not in kwargs:
             kwargs.setdefault("label", label_from_attrs(self.data))
         self.cbar = self.fig.colorbar(
-            self._mappables[-1], ax=list(self.axes.flat), **kwargs
+            self._mappables[-1], ax=list(self.axs.flat), **kwargs
         )
 
     def add_quiverkey(self, u: Hashable, v: Hashable, **kwargs: Any) -> None:
         kwargs = kwargs.copy()
 
         magnitude = _get_nice_quiver_magnitude(self.data[u], self.data[v])
         units = self.data[u].attrs.get("units", "")
-        self.quiverkey = self.axes.flat[-1].quiverkey(
+        self.quiverkey = self.axs.flat[-1].quiverkey(
             self._mappables[-1],
             X=0.8,
             Y=0.9,
@@ -747,7 +771,7 @@ def _get_largest_lims(self) -> dict[str, tuple[float, float]]:
         for axis in ("x", "y", "z"):
             # Find the plot with the largest xlim values:
             lower, upper = lims_largest[axis]
-            for ax in self.axes.flat:
+            for ax in self.axs.flat:
                 get_lim: None | Callable[[], tuple[float, float]] = getattr(
                     ax, f"get_{axis}lim", None
                 )
@@ -781,13 +805,13 @@ def _set_lims(
         >>> ds = xr.tutorial.scatter_example_dataset(seed=42)
         >>> fg = ds.plot.scatter(x="A", y="B", hue="y", row="x", col="w")
         >>> fg._set_lims(x=(-0.3, 0.3), y=(0, 2), z=(0, 4))
-        >>> fg.axes[0, 0].get_xlim(), fg.axes[0, 0].get_ylim()
+        >>> fg.axs[0, 0].get_xlim(), fg.axs[0, 0].get_ylim()
         ((-0.3, 0.3), (0.0, 2.0))
         """
         lims_largest = self._get_largest_lims()
 
         # Set limits:
-        for ax in self.axes.flat:
+        for ax in self.axs.flat:
             for (axis, data_limit), parameter_limit in zip(
                 lims_largest.items(), (x, y, z)
             ):
@@ -858,7 +882,7 @@ def set_titles(
         nicetitle = functools.partial(_nicetitle, maxchar=maxchar, template=template)
 
         if self._single_group:
-            for d, ax in zip(self.name_dicts.flat, self.axes.flat):
+            for d, ax in zip(self.name_dicts.flat, self.axs.flat):
                 # Only label the ones with data
                 if d is not None:
                     coord, value = list(d.items()).pop()
@@ -867,7 +891,7 @@ def set_titles(
         else:
             # The row titles on the right edge of the grid
             for index, (ax, row_name, handle) in enumerate(
-                zip(self.axes[:, -1], self.row_names, self.row_labels)
+                zip(self.axs[:, -1], self.row_names, self.row_labels)
             ):
                 title = nicetitle(coord=self._row_var, value=row_name, maxchar=maxchar)
                 if not handle:
@@ -886,7 +910,7 @@ def set_titles(
 
             # The column titles on the top row
             for index, (ax, col_name, handle) in enumerate(
-                zip(self.axes[0, :], self.col_names, self.col_labels)
+                zip(self.axs[0, :], self.col_names, self.col_labels)
             ):
                 title = nicetitle(coord=self._col_var, value=col_name, maxchar=maxchar)
                 if not handle:
@@ -922,7 +946,7 @@ def set_ticks(
         x_major_locator = MaxNLocator(nbins=max_xticks)
         y_major_locator = MaxNLocator(nbins=max_yticks)
 
-        for ax in self.axes.flat:
+        for ax in self.axs.flat:
             ax.xaxis.set_major_locator(x_major_locator)
             ax.yaxis.set_major_locator(y_major_locator)
             for tick in itertools.chain(
@@ -957,7 +981,7 @@ def map(
         """
         plt = import_matplotlib_pyplot()
 
-        for ax, namedict in zip(self.axes.flat, self.name_dicts.flat):
+        for ax, namedict in zip(self.axs.flat, self.name_dicts.flat):
             if namedict is not None:
                 data = self.data.loc[namedict]
                 plt.sca(ax)