Figure API

Figure

Figure(nrows: int = 1, ncols: int = 1, *, figsize: tuple[float, float] | None = None, width_ratios: list[float] | None = None, height_ratios: list[float] | None = None, theme: ThemeSpec | None = None, sharex: bool = False, sharey: bool = False, latex_labels: bool = False, hspace: float | None = None, wspace: float | None = None)

Compose multiple Plot objects into a multi-panel figure.

Two usage styles:

Simple grids::

Figure.grid([
    [PKSpectrum(k, pk), BackgroundEvolution(z, qty)],
    [TrianglePlot(samples, params)],  # auto-spans 2 columns
]).show()

Complex layouts with explicit spanning::

fig = Figure(nrows=2, ncols=3, width_ratios=[2, 1, 1], sharex=True)
fig.add(PKSpectrum(k, pk), row=0, col=0, colspan=2)
fig.add(XYPlot(x, y),      row=0, col=2)
fig.add(TrianglePlot(...), row=1, col=0, colspan=3)
fig.show()

Create a Figure layout container.

Parameters:

Name	Type	Description	Default
nrows	int	Number of rows in the grid.	1
ncols	int	Number of columns in the grid.	1
figsize	tuple[float, float] | None	Overall figure size (width, height) in inches.	None
width_ratios	list[float] | None	Relative column widths (length must equal ncols).	None
height_ratios	list[float] | None	Relative row heights (length must equal nrows).	None
theme	ThemeSpec | None	Visual theme applied to all panels.	None
sharex	bool	Share x-axis across panels in the same column.	False
sharey	bool	Share y-axis across panels in the same row.	False
latex_labels	bool	Propagate raw LaTeX strings to all panels.	False
hspace	float | None	Vertical space between rows. For matplotlib this is a fraction of the average axis height (e.g. 0.3); for altair it is in pixels (e.g. 20). None uses the backend default.	None
wspace	float | None	Horizontal space between columns. Same unit convention as hspace.	None

Methods:

add

add(plot: Plot[Any], *, row: int, col: int, rowspan: int = 1, colspan: int = 1) -> Figure

Add a plot at the given grid position. Returns self for chaining.

grid classmethod

grid(rows: list[list[Plot[Any] | None]], *, figsize: tuple[float, float] | None = None, width_ratios: list[float] | None = None, height_ratios: list[float] | None = None, theme: ThemeSpec | None = None, sharex: bool = False, sharey: bool = False, latex_labels: bool = False, hspace: float | None = None, wspace: float | None = None) -> Figure

Build a Figure from a list-of-lists of Plot objects.

Rows with fewer plots than the maximum row length are auto-spanned evenly. The number of plots in each row must evenly divide the maximum row length, or a ValueError is raised.

Example::

Figure.grid([
    [p1, p2],   # 2 columns
    [p3],       # p3 spans both columns automatically
])

show

show(backend: str | None = None, **kwargs: Any) -> None

Render and display the figure interactively.

Parameters:

Name	Type	Description	Default
backend	str | None	Backend name. Defaults to the active context/global backend.	None
**kwargs	Any	Forwarded to the backend's show() method.	{}

save

save(path: str | PathLike[str], backend: str | None = None, **kwargs: Any) -> None

Render and save the figure to a file.

Parameters:

Name	Type	Description	Default
path	str | PathLike[str]	Destination file path.	required
backend	str | None	Backend name. Defaults to the active context/global backend.	None
**kwargs	Any	Forwarded to the backend's save() method.	{}

render

render(backend: str | None = None) -> Any

Return the native figure object for the resolved backend.