Support tuple figsize in facetgrid_figsize option (#11103)

Extend facetgrid_figsize to accept a (width, height) tuple in addition
to "computed" and "rcparams". Also move figsize resolution before grid
shape computation for better composition with col_wrap="auto" (#11266).

Co-authored-by: Claude <noreply@anthropic.com>

Author: kkollsga

doc/whats-new.rst

@@ -157,7 +157,8 @@ New Features
 
 - Added ``facetgrid_figsize`` option to :py:func:`~xarray.set_options` allowing
   :py:class:`~xarray.plot.FacetGrid` to use ``matplotlib.rcParams['figure.figsize']``
-  instead of computing figure size from ``size`` and ``aspect`` (:issue:`11103`).
+  or a fixed ``(width, height)`` tuple instead of computing figure size from
+  ``size`` and ``aspect`` (:issue:`11103`).
   By `Kristian Kollsga <https://github.com/kkollsga>`_.
 - :py:class:`~xarray.indexes.NDPointIndex` now supports coordinates with fewer
   dimensions than coordinate variables, enabling indexing of scattered points

xarray/core/options.py

@@ -74,7 +74,7 @@ class T_Options(TypedDict):
         use_new_combine_kwarg_defaults: bool
         use_numbagg: bool
         use_opt_einsum: bool
-        facetgrid_figsize: Literal["computed", "rcparams"]
+        facetgrid_figsize: Literal["computed", "rcparams"] | tuple[float, float]
 
 
 OPTIONS: T_Options = {
@@ -148,7 +148,11 @@ def _positive_integer(value: Any) -> bool:
     "use_opt_einsum": lambda value: isinstance(value, bool),
     "use_flox": lambda value: isinstance(value, bool),
     "warn_for_unclosed_files": lambda value: isinstance(value, bool),
-    "facetgrid_figsize": _FACETGRID_FIGSIZE_OPTIONS.__contains__,
+    "facetgrid_figsize": lambda value: value in _FACETGRID_FIGSIZE_OPTIONS or (
+        isinstance(value, tuple)
+        and len(value) == 2
+        and all(isinstance(v, (int, float)) for v in value)
+    ),
 }
 
 
@@ -227,14 +231,15 @@ class set_options:
     chunk_manager : str, default: "dask"
         Chunk manager to use for chunked array computations when multiple
         options are installed.
-    facetgrid_figsize : {"computed", "rcparams"}, default: "computed"
+    facetgrid_figsize : {"computed", "rcparams"} or tuple of float, default: "computed"
         How :class:`~xarray.plot.FacetGrid` determines figure size when
         ``figsize`` is not explicitly passed:
 
         * ``"computed"`` : figure size is derived from ``size`` and ``aspect``
           parameters (current default behavior).
         * ``"rcparams"`` : use ``matplotlib.rcParams['figure.figsize']`` as the
           total figure size.
+        * ``(width, height)`` : use a fixed figure size (in inches).
     cmap_divergent : str or matplotlib.colors.Colormap, default: "RdBu_r"
         Colormap to use for divergent data plots. If string, must be
         matplotlib built-in colormap. Can also be a Colormap object
@@ -371,7 +376,10 @@ def __init__(self, **kwargs):
                 elif k == "display_style":
                     expected = f"Expected one of {_DISPLAY_OPTIONS!r}"
                 elif k == "facetgrid_figsize":
-                    expected = f"Expected one of {_FACETGRID_FIGSIZE_OPTIONS!r}"
+                    expected = (
+                        f"Expected one of {_FACETGRID_FIGSIZE_OPTIONS!r}"
+                        " or a (width, height) tuple of floats"
+                    )
                 elif k == "netcdf_engine_order":
                     expected = f"Expected a subset of {sorted(_NETCDF_ENGINES)}"
                 else:

xarray/plot/facetgrid.py

@@ -195,6 +195,19 @@ def __init__(
         else:
             raise ValueError("Pass a coordinate name as an argument for row or col")
 
+        # Resolve figsize from global option before computing grid shape,
+        # so that downstream heuristics (e.g. col_wrap="auto") can use it.
+        if figsize is None:
+            from xarray.core.options import OPTIONS
+
+            facetgrid_figsize = OPTIONS["facetgrid_figsize"]
+            if isinstance(facetgrid_figsize, tuple):
+                figsize = facetgrid_figsize
+            elif facetgrid_figsize == "rcparams":
+                import matplotlib as mpl
+
+                figsize = tuple(mpl.rcParams["figure.figsize"])
+
         # Compute grid shape
         if single_group:
             nfacet = len(data[single_group])
@@ -212,17 +225,10 @@ def __init__(
         subplot_kws = {} if subplot_kws is None else subplot_kws
 
         if figsize is None:
-            from xarray.core.options import OPTIONS
-
-            if OPTIONS["facetgrid_figsize"] == "rcparams":
-                import matplotlib as mpl
-
-                figsize = tuple(mpl.rcParams["figure.figsize"])
-            else:
-                # Calculate the base figure size with extra horizontal space
-                # for a colorbar
-                cbar_space = 1
-                figsize = (ncol * size * aspect + cbar_space, nrow * size)
+            # Calculate the base figure size with extra horizontal space
+            # for a colorbar
+            cbar_space = 1
+            figsize = (ncol * size * aspect + cbar_space, nrow * size)
 
         fig, axs = plt.subplots(
             nrow,

xarray/tests/test_options.py

@@ -87,10 +87,16 @@ def test_netcdf_engine_order() -> None:
 def test_facetgrid_figsize() -> None:
     with pytest.raises(ValueError):
         xarray.set_options(facetgrid_figsize="invalid")
+    with pytest.raises(ValueError):
+        xarray.set_options(facetgrid_figsize=(1.0,))
+    with pytest.raises(ValueError):
+        xarray.set_options(facetgrid_figsize=(1.0, 2.0, 3.0))
     with xarray.set_options(facetgrid_figsize="rcparams"):
         assert OPTIONS["facetgrid_figsize"] == "rcparams"
     with xarray.set_options(facetgrid_figsize="computed"):
         assert OPTIONS["facetgrid_figsize"] == "computed"
+    with xarray.set_options(facetgrid_figsize=(12.0, 8.0)):
+        assert OPTIONS["facetgrid_figsize"] == (12.0, 8.0)
 
 
 def test_display_style() -> None:

xarray/tests/test_plot.py

@@ -3597,6 +3597,13 @@ def test_facetgrid_figsize_rcparams() -> None:
                 actual_figsize = g.fig.get_size_inches()
                 np.testing.assert_allclose(actual_figsize, custom_figsize)
 
+    with figure_context():
+        # Tuple mode: fixed figsize via set_options
+        with xr.set_options(facetgrid_figsize=(14.0, 5.0)):
+            g = xplt.FacetGrid(da, col="z")
+            actual_figsize = g.fig.get_size_inches()
+            np.testing.assert_allclose(actual_figsize, (14.0, 5.0))
+
     with figure_context():
         # Explicit figsize should override the option
         with xr.set_options(facetgrid_figsize="rcparams"):