Add facetgrid_figsize option to set_options

[kkollsga]

• Closes Add global config for FacetGrid to always follow matplotlib.rcParams['figure.figsize'] #11103
• Tests added
• User visible changes documented in whats-new.rst
• New functions/methods listed in api.rst (N/A — no new public functions)

Summary

• Adds a facetgrid_figsize option to xr.set_options() with two modes:
  • "computed" (default) — current behavior, figure size derived from size and aspect
  • "rcparams" — use matplotlib.rcParams['figure.figsize'] as the total figure size
• Explicit figsize parameter still takes precedence over both modes
• Follows the existing pattern of plot-related global options (cmap_sequential, cmap_divergent)

Test plan

• Validator test: invalid value raises ValueError, context manager works for both values
• Functional test: default behavior unchanged, "rcparams" mode uses mpl.rcParams, explicit figsize overrides
• Full test_options.py suite passes (21 tests)
• Full TestFacetGrid class passes (22 tests)
• pre-commit passes (all hooks)
• mypy has only pre-existing errors (missing stubs for pytest/dask/flox)

[Illviljan]

Could you add before and after plots?
I'm in particular interested how labels will look like.

[kkollsga]

Good point! Here are before/after comparisons:

3-column facet grid:

Top: "computed" (default) — current behavior, figsize derived from size × aspect × ncol → (10, 3)
Middle: "rcparams" with rcParams['figure.figsize'] = (10, 4) — similar layout, labels look fine
Bottom: "rcparams" with matplotlib's default (6.4, 4.8) — panels get narrower as expected when using a fixed figure size

6-panel facet grid with col_wrap=3:

Top: "computed" (default)
Bottom: "rcparams" with rcParams['figure.figsize'] = (12, 8)

The idea is that users opting into "rcparams" mode are typically those who already configure their global figsize to something sensible for their workflow. With a small default figsize the panels naturally get compressed, but that's the expected trade-off of using a fixed size regardless of facet count.

Note: when adding a suptitle to a FacetGrid, it collides with the column titles by default (both modes). Setting y=1.05 fixes this:

g.fig.suptitle("My title", y=1.05)

Script to reproduce these plots

import matplotlib as mpl
import matplotlib.pyplot as plt
import numpy as np
import xarray as xr
from PIL import Image

np.random.seed(42)


def make_sample_data(n_categories=3):
    labels = [f"category_{i+1}" for i in range(n_categories)]
    return xr.DataArray(
        np.random.randn(20, 25, n_categories),
        dims=["y", "x", "z"],
        coords={
            "x": np.linspace(-10, 10, 25),
            "y": np.linspace(-5, 5, 20),
            "z": labels,
        },
        name="temperature anomaly (°C)",
    )


def stack_images(paths, output, gap=30):
    imgs = [Image.open(p) for p in paths]
    width = max(im.width for im in imgs)
    height = sum(im.height for im in imgs) + gap * (len(imgs) - 1)
    combined = Image.new("RGB", (width, height), (255, 255, 255))
    y_offset = 0
    for im in imgs:
        combined.paste(im, (0, y_offset))
        y_offset += im.height + gap
    combined.save(output)


da3 = make_sample_data(3)
da6 = make_sample_data(6)

# -- Scenario 1: 3 columns --

g = da3.plot.pcolormesh(col="z", cmap="RdBu_r")
g.fig.suptitle('Mode: "computed" (default) — figsize = (10.0, 3.0)',
               fontsize=13, weight="bold", y=1.05)
g.fig.savefig("1a.png", dpi=150, bbox_inches="tight")
plt.close(g.fig)

with mpl.rc_context({"figure.figsize": (10.0, 4.0)}):
    with xr.set_options(facetgrid_figsize="rcparams"):
        g = da3.plot.pcolormesh(col="z", cmap="RdBu_r")
        g.fig.suptitle('Mode: "rcparams" — figsize = (10.0, 4.0)',
                       fontsize=13, weight="bold", y=1.05)
        g.fig.savefig("1b.png", dpi=150, bbox_inches="tight")
        plt.close(g.fig)

with xr.set_options(facetgrid_figsize="rcparams"):
    g = da3.plot.pcolormesh(col="z", cmap="RdBu_r")
    g.fig.suptitle('Mode: "rcparams" — mpl default figsize (6.4, 4.8)',
                   fontsize=13, weight="bold", y=1.05)
    g.fig.savefig("1c.png", dpi=150, bbox_inches="tight")
    plt.close(g.fig)

stack_images(["1a.png", "1b.png", "1c.png"], "facetgrid_comparison_3col.png")

# -- Scenario 2: 6 columns with col_wrap=3 --

g = da6.plot.pcolormesh(col="z", col_wrap=3, cmap="viridis")
g.fig.suptitle('Mode: "computed" (default) — 6 panels, col_wrap=3',
               fontsize=13, weight="bold", y=1.02)
g.fig.savefig("2a.png", dpi=150, bbox_inches="tight")
plt.close(g.fig)

with mpl.rc_context({"figure.figsize": (12.0, 8.0)}):
    with xr.set_options(facetgrid_figsize="rcparams"):
        g = da6.plot.pcolormesh(col="z", col_wrap=3, cmap="viridis")
        g.fig.suptitle('Mode: "rcparams" — figsize = (12.0, 8.0)',
                       fontsize=13, weight="bold", y=1.02)
        g.fig.savefig("2b.png", dpi=150, bbox_inches="tight")
        plt.close(g.fig)

stack_images(["2a.png", "2b.png"], "facetgrid_comparison_6col.png")

[headtr1ck]

I don't really see the usecase, but if you went through the effort of setting up a PR there must be some :)
LGTM.

[kkollsga]

Thanks for the review. The use case comes from #11103, users with matplotlib stylesheets for fixed-size publication figures (IEEE, AGU, etc.) or corporate style guides, where col=/row= silently overrides their rcParams['figure.figsize']. Users without stylesheets won't notice any difference.

[headtr1ck]

Have to be careful when merging #11266, those two PRs need some alignment. But nothing difficult.

[headtr1ck]

There was always some hesitation of adding global configs in the past but I think this is a useful addition.

[headtr1ck]

Actually... Why don't we also support setting the figsize directly as well?

[kkollsga]

Actually... Why don't we also support setting the figsize directly as well?

Good point! A tuple value could work nicely as a third mode alongside "computed" and "rcparams":

# 1. "computed" — current default, figsize scales with panel count
xr.set_options(facetgrid_figsize="computed")

# 2. "rcparams" — defers to matplotlib global state / stylesheet
#    e.g. with a corporate or publication style template:
plt.style.use("acme_corp.mplstyle")  # sets figure.figsize: 7.2, 4.5
xr.set_options(facetgrid_figsize="rcparams")

# 3. tuple — fixed figsize scoped to xarray, independent of mpl.rcParams
#    useful when you want consistent facet grids without touching global state
xr.set_options(facetgrid_figsize=(12, 6))

Let me implement this, and push an update to the pr.

[kkollsga]

I also looked at the #11266 alignment you mentioned. The figsize from the global option was being resolved after the grid shape computation, so _auto_grid in #11266 wouldn't have access to it. I moved the resolution step earlier so that both features compose cleanly. Whichever PR merges second should only need a straightforward rebase.

[headtr1ck]

Actually one more thing: can you change bullet point 3 here: https://github.com/pydata/xarray/blob/main/doc%2Fuser-guide%2Foptions.rst to be more general about plotting and add your new option.
Thanks!

[headtr1ck]

@Illviljan any last remark before we merge?