# plasma_plots.figures

*module*

Several plots in one figure, with any backend: ``plasma_plots.figure(...)``.

>>> with plasma_plots.figure(2, 1, sharex=True, backend="plotly") as fig:
...     energy.plasma.plot.timeseries(fit=(0.0, 5.0), ax=fig[0])
...     drift.plasma.plot.timeseries(logy=True, ax=fig[1])
>>> fig.save("energies.html")

Every plot method that takes ``ax=`` draws into one panel. The figure is drawn with Matplotlib and,
with ``backend="plotly"``, converted to one Plotly figure when the block ends, so the panels share
zoom where their axes are shared and every panel keeps its colorbar and legend; with
``backend="tikz"``, to one TikZ/pgfplots figure (see [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]).

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L1-L1)

## plasma_plots.figures.Figure

*class*

```python
class Figure
```

A figure of several panels, made by [`figure()`][plasma_plots.figures.figure].

Index it for a panel's Matplotlib axes (``fig[0]``, ``fig[1, 2]``) and pass that as ``ax=`` to
any plot method. After the ``with`` block, it saves and shows like a
[`PlotResult`][plasma_plots.plotting.PlotResult].

**Parameters**

- `nrows` (`int`) — The number of rows and columns of panels.
- `ncols` (`int`) — The number of rows and columns of panels.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — How the figure is finished; ``None`` for the default (see [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend]).
- `sharex` (`bool or {'row', 'col', 'all'}`) — Share the horizontal or vertical axes.
- `sharey` (`bool or {'row', 'col', 'all'}`) — Share the horizontal or vertical axes.
- `figsize` (`(float, float) or None`) — The size in inches; ``None`` for one from the number of panels.
- `title` (`str or None`) — A title above all panels.
- `**options` (default: `{}`) — Passed on to ``matplotlib.pyplot.subplots``.

**Attributes**

- `axes` (`numpy.ndarray of matplotlib.axes.Axes or None`) — The panels, ``(nrows, ncols)``; ``None`` on MPI ranks other than 0, where nothing is drawn.
- `results` (`list of PlotResult`) — What the plot methods drawn into the panels returned, in order (e.g. their ``fit_results``).

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L21-L225)

### plasma_plots.figures.Figure.axes

*attribute* · *instance attribute*

```python
axes = axes
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L91-L91)

### plasma_plots.figures.Figure.backend

*attribute* · *instance attribute*

```python
backend = backend
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L57-L57)

### plasma_plots.figures.Figure.results

*attribute* · *instance attribute*

```python
results = []
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L60-L60)

### plasma_plots.figures.Figure.fig

*property*

```python
fig
```

The finished Matplotlib, Plotly or TikZ figure.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L186-L188)

### plasma_plots.figures.Figure.result

*property*

```python
result
```

The figure, as a [`PlotResult`][plasma_plots.plotting.PlotResult].

After the ``with`` block the finished figure; inside it, the figure as drawn so far, so
that ``fig.save(...)`` works in either place.

**Returns**

- (`PlotResult or SkippedPlot`) — The figure, Matplotlib, Plotly or TikZ, with the ``fit_results`` of every panel.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L170-L183)

### plasma_plots.figures.Figure.save

*method*

```python
def save(path, **kwargs)
```

Save the figure, as [`PlotResult.save`][plasma_plots.plotting.PlotResult.save] does.

Inside the ``with`` block it saves the panels drawn so far.

**Parameters**

- `path` (`str or pathlib.Path`) — The file to write; its extension picks the format.
- `**kwargs` (default: `{}`) — Passed to [`PlotResult.save`][plasma_plots.plotting.PlotResult.save].

**Returns**

- (`str`) — The path written.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L190-L207)

### plasma_plots.figures.Figure.show

*method*

```python
def show()
```

Show the finished figure.

**Returns**

- (`Figure`) — This figure.

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L209-L218)

## plasma_plots.figures.figure

*function*

```python
def figure(nrows: int = 1, ncols: int = 1, *, backend: str | None = None, sharex: bool | str = False, sharey: bool | str = False, figsize=None, title: str | None = None, **options) -> Figure
```

Compose several plots into one figure, drawn with Matplotlib, or as one Plotly or TikZ figure.

Use it as a ``with`` block: every plot method given ``ax=fig[i]`` draws into panel ``i``;
at the end of the block the figure is finished, and with ``backend="plotly"`` or
``backend="tikz"`` converted once.

**Parameters**

- `nrows` (`int`) (default: `1`) — The number of rows of panels. Default: 1.
- `ncols` (`int`) (default: `1`) — The number of columns of panels. Default: 1.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Finish the figure as a Matplotlib figure, as an interactive Plotly figure, or as a TikZ/pgfplots figure for LaTeX. Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `sharex` (`bool or {'row', 'col', 'all'}`) (default: `False`) — Share the horizontal axes (and their zoom, in Plotly), as for ``matplotlib.pyplot.subplots``. Default: ``False``.
- `sharey` (`bool or {'row', 'col', 'all'}`) (default: `False`) — Share the vertical axes. Default: ``False``.
- `figsize` (`(float, float)`) (default: `None`) — The size in inches. Default: from the number of panels.
- `title` (`str`) (default: `None`) — A title above all panels. Default: none.
- `**options` (default: `{}`) — Passed on to ``matplotlib.pyplot.subplots``, e.g. ``gridspec_kw={"height_ratios": [3, 1]}``.

**Returns**

- (`Figure`) — The figure; index it for the panels' axes, and save or show it after the block.

**Examples**

```pycon
>>> with plasma_plots.figure(2, 1, sharex=True, backend="plotly") as fig:
...     energy.plasma.plot.timeseries(fit=(0.0, 5.0), ax=fig[0])
...     drift.plasma.plot.timeseries(logy=True, ax=fig[1])
>>> fig.save("energies.html")
>>> fig.results[0].fit_results[0].rate
```

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/figures.py#L228-L289)