gsplot.subplots#

subplots(shape: str | Sequence[Sequence[str | None]], /, *, nrows: None = None, ncols: None = None, mosaic: None = None, size: Literal['auto', 'single', 'double'] | tuple[float, float] | None = 'auto', unit: Literal['in', 'cm', 'mm', 'pt'] = 'in', sharex: bool | Literal['none', 'all', 'row', 'col'] = False, sharey: bool | Literal['none', 'all', 'row', 'col'] = False, squeeze: bool = True, width_ratios: Sequence[float] | None = None, height_ratios: Sequence[float] | None = None, subplot_kw: Mapping[str, Any] | None = None, fig: Figure | None = None, clear: bool = False, live: bool = False, layout: Literal['auto', 'constrained', 'tight', 'none'] = 'auto', style: Literal['auto', 'paper'] | None = 'auto', pad: float | None = None, xpad: float | None = None, ypad: float | None = None, xspace: float | None = None, yspace: float | None = None, w_pad: float | None = None, h_pad: float | None = None, wspace: float | None = None, hspace: float | None = None, config: Config | None = None, figsize: tuple[float, float] | None = None, tight_layout: bool | None = None, constrained_layout: bool | None = None) → tuple[Figure, AxesDict]#

subplots(*, mosaic: str | Sequence[Sequence[str | None]], nrows: None = None, ncols: None = None, size: Literal['auto', 'single', 'double'] | tuple[float, float] | None = 'auto', unit: Literal['in', 'cm', 'mm', 'pt'] = 'in', sharex: bool | Literal['none', 'all', 'row', 'col'] = False, sharey: bool | Literal['none', 'all', 'row', 'col'] = False, squeeze: bool = True, width_ratios: Sequence[float] | None = None, height_ratios: Sequence[float] | None = None, subplot_kw: Mapping[str, Any] | None = None, fig: Figure | None = None, clear: bool = False, live: bool = False, layout: Literal['auto', 'constrained', 'tight', 'none'] = 'auto', style: Literal['auto', 'paper'] | None = 'auto', pad: float | None = None, xpad: float | None = None, ypad: float | None = None, xspace: float | None = None, yspace: float | None = None, w_pad: float | None = None, h_pad: float | None = None, wspace: float | None = None, hspace: float | None = None, config: Config | None = None, figsize: tuple[float, float] | None = None, tight_layout: bool | None = None, constrained_layout: bool | None = None) → tuple[Figure, AxesDict]

Create or reuse a native Figure with concise publication defaults.

Parameters:

*shape – Zero values for keyword shape, one positive row count or mosaic, or two positive grid dimensions.
nrows – Explicit keyword alternatives to positional shape.
ncols – Explicit keyword alternatives to positional shape.
mosaic – Explicit keyword alternatives to positional shape.
size – "auto", "single", "double", explicit dimensions, or None and the physical unit for explicit dimensions.
unit – "auto", "single", "double", explicit dimensions, or None and the physical unit for explicit dimensions.
sharex – Native Matplotlib sharing and return-container controls.
sharey – Native Matplotlib sharing and return-container controls.
squeeze – Native Matplotlib sharing and return-container controls.
width_ratios – Positive ratios matching the outer layout dimensions.
height_ratios – Positive ratios matching the outer layout dimensions.
subplot_kw – Finite options copied into each Matplotlib subplot constructor.
fig – Optional existing Figure and whether to clear it after validation.
clear – Optional existing Figure and whether to clear it after validation.
live – Whether to run in interactive live mode. When true, reuses the active Figure (or creates one), automatically clears previous axes, and requests an idle canvas draw.
layout – "auto", "constrained", "tight", or "none".
style – "auto" or "paper" for target-local publication styling, or None to retain Matplotlib styling.
pad – Optional non-negative figure padding scalar.
xpad – Optional non-negative horizontal and vertical subplot padding scalars (aliases for w_pad and h_pad).
ypad – Optional non-negative horizontal and vertical subplot padding scalars (aliases for w_pad and h_pad).
xspace – Optional non-negative horizontal and vertical spacing fractions (aliases for wspace and hspace).
yspace – Optional non-negative horizontal and vertical spacing fractions (aliases for wspace and hspace).
w_pad – Matplotlib layout-engine padding and spacing alternatives.
h_pad – Matplotlib layout-engine padding and spacing alternatives.
wspace – Matplotlib layout-engine padding and spacing alternatives.
hspace – Matplotlib layout-engine padding and spacing alternatives.
config – Explicit immutable configuration for omitted size, unit, squeeze, and layout values.
figsize – Deprecated 1.x spellings retained for source compatibility.
tight_layout – Deprecated 1.x spellings retained for source compatibility.
constrained_layout – Deprecated 1.x spellings retained for source compatibility.

Returns:

The native Figure and Matplotlib Axes, array, or mosaic dictionary.

Return type:

tuple

Raises:

LayoutError – If shape, sizing, layout, style, compatibility, or reuse is invalid.

Notes

New automatic Figures use an 85 mm single-column or 170 mm multi-column canvas, constrained layout, and target-local paper styling. Reused Figures retain size, layout, and existing Axes styling unless compatible explicit values request otherwise.

Examples

>>> import gsplot as gs
>>> figure, axes = gs.subplots("AB")
>>> tuple(axes)
('A', 'B')
>>> figure.clear()