# plasma_plots.accessors

*module*

The ``.plasma`` accessor: plots, diagnostics and plot data of a single labeled array or dataset.

Every product of an [`Output`][struphy.Output] carries this accessor after importing
``plasma_plots``, and so does every array derived from one:

- ``array.plasma.plot`` ([`ArrayPlots`][ArrayPlots]), ``array.plasma.analysis`` ([`ArrayAnalysis`][ArrayAnalysis])
  and ``array.plasma.data`` ([`ArrayData`][ArrayData]) for an ``xarray.DataArray``;
- ``dataset.plasma.plot`` ([`DatasetPlots`][DatasetPlots]), ``dataset.plasma.analysis``
  ([`DatasetAnalysis`][DatasetAnalysis]) and ``dataset.plasma.data`` ([`DatasetData`][DatasetData]) for an
  ``xarray.Dataset``, e.g. an orbits product.

Dimensions that are neither displayed nor swept are selected by naming them: an integer is a
position (``t=0`` the first, ``t=-1`` the last), and a float is the nearest coordinate value
(``t=0.35``).

**Examples**

```pycon
>>> import plasma_plots
>>> phi.plasma.plot.slice(x="eta1", y="eta2", t=-1)
>>> energy.plasma.analysis.growth_rate(window=(0.0, 5.0))
>>> orbits.plasma.plot.trajectories()
```

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

## plasma_plots.accessors.Backend

*attribute* · *module attribute*

```python
Backend = Literal['matplotlib', 'plotly', 'tikz']
```

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

## plasma_plots.accessors.Coordinates

*attribute* · *module attribute*

```python
Coordinates = Literal['logical', 'physical']
```

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

## plasma_plots.accessors.Plane

*attribute* · *module attribute*

```python
Plane = Literal['XY', 'XZ', 'YZ', 'RZ', 'X1X2']
```

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

## plasma_plots.accessors.ArrayAnalysis

*class*

```python
class ArrayAnalysis(_ArrayAccessor)
```

Bases: `plasma_plots.accessors._ArrayAccessor`

Quantitative diagnostics of one array, as ``array.plasma.analysis.<quantity>(...)``.

Each method applies a function of [`plasma_plots.analysis`][plasma_plots.analysis] or
[`plasma_plots.spectral`][plasma_plots.spectral] to this array; see there for the definitions and conventions.

**Examples**

```pycon
>>> energy.plasma.analysis.growth_rate(window=(0.0, 5.0))
>>> phi.plasma.analysis.time_fft(detrend=True)
```

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

### plasma_plots.accessors.ArrayAnalysis.band_filter

*method*

```python
def band_filter(omega_lo: float, omega_hi: float, *, detrend: bool = False) -> xr.DataArray
```

Return only the frequencies in ``[omega_lo, omega_hi]``.

**Parameters**

- `omega_lo` (`float`) — The lowest angular frequency kept.
- `omega_hi` (`float`) — The highest angular frequency kept, at least ``omega_lo``.
- `detrend` (`bool`) (default: `False`) — Subtract the temporal mean first; the result then has zero mean even if the band includes DC. Default: False.

**Returns**

- (`xarray.DataArray`) — The filtered signal, on this array's grid.

> **See Also**
>
> [`plasma_plots.spectral.band_filter()`][plasma_plots.spectral.band_filter] : The function behind this method.
> [`ArrayAnalysis.filter_time()`][plasma_plots.accessors.ArrayAnalysis.filter_time] : The dominant band, found automatically.

**Examples**

```pycon
>>> phi.plasma.analysis.band_filter(0.08, 0.11)
```

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

### plasma_plots.accessors.ArrayAnalysis.boozer_spectrum

*method*

```python
def boozer_spectrum(top: int | None = None, angles: str = 'boozer') -> xr.DataArray
```

Return the Boozer harmonics ``B_mn`` of this quantity over the radius.

**Parameters**

- `top` (`int`) (default: `None`) — Keep only the ``top`` harmonics with the largest peak amplitude over the radius, strongest first. Default: all.
- `angles` (`('boozer', 'any')`) (default: `"boozer"`) — Require the Boozer angles ``theta_B``, ``zeta_B`` (default), or take the harmonics in whatever angles the field has (not a Boozer spectrum then; e.g. for a comparison).

**Returns**

- (`xarray.DataArray`) — The real amplitudes over ``mode`` (with ``m``, ``n``) and the radius.

> **See Also**
>
> [`plasma_plots.analysis.boozer_spectrum()`][plasma_plots.analysis.boozer_spectrum] : The function behind this method.
> [`ArrayAnalysis.quasisymmetry_error()`][plasma_plots.accessors.ArrayAnalysis.quasisymmetry_error] : The symmetry-breaking part.
> [`ArrayPlots.boozer_spectrum()`][plasma_plots.accessors.ArrayPlots.boozer_spectrum] : The plot.

**Examples**

```pycon
>>> boozer.mod_B.plasma.analysis.boozer_spectrum(top=8)
```

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

### plasma_plots.accessors.ArrayAnalysis.critical_points

*method*

```python
def critical_points(refine: bool = True) -> xr.Dataset
```

Return the O-points and X-points of this flux function (at every time).

**Parameters**

- `refine` (`bool`) (default: `True`) — Locate the zero within the cell by Newton's method (the cell's centre otherwise). Default: True.

**Returns**

- (`xarray.Dataset`) — The points over ``point`` (and ``t``): positions, values and kinds.

> **See Also**
>
> [`plasma_plots.analysis.critical_points()`][plasma_plots.analysis.critical_points] : The function behind this method.
> [`ArrayAnalysis.reconnected_flux()`][plasma_plots.accessors.ArrayAnalysis.reconnected_flux] : The flux between them over time.
> [`ArrayPlots.critical_points()`][plasma_plots.accessors.ArrayPlots.critical_points] : The plot.

**Examples**

```pycon
>>> B.plasma.analysis.flux_function().plasma.analysis.critical_points()
```

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

### plasma_plots.accessors.ArrayAnalysis.cross_spectrum

*method*

```python
def cross_spectrum(other: xr.DataArray, *, dims=None, detrend: bool = True, window=None) -> xr.Dataset
```

Return the cross-spectrum, phase (of ``other`` relative to this) and coherence.

**Parameters**

- `other` (`xarray.DataArray`) — The second signal, on the same time grid; its phase is relative to this one.
- `dims` (`str or sequence of str`) (default: `None`) — Dimensions to sum the cross-spectrum over, as an ensemble. Default: none (no ``coherence``).
- `detrend` (`bool`) (default: `True`) — Subtract each signal's temporal mean first. Default: True.
- `window` (`(None, 'hann')`) (default: `None`) — Window applied to both signals before transforming. Default: None.

**Returns**

- (`xarray.Dataset`) — The cross-spectrum, phase and (with ``dims``) coherence over ``omega``.

> **See Also**
>
> [`plasma_plots.spectral.cross_spectrum()`][plasma_plots.spectral.cross_spectrum] : The function behind this method.
> [`ArrayPlots.cross_spectrum()`][plasma_plots.accessors.ArrayPlots.cross_spectrum] : The plot of this spectrum.

**Examples**

```pycon
>>> u.plasma.analysis.cross_spectrum(b, dims="eta3")
```

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

### plasma_plots.accessors.ArrayAnalysis.curl

*method*

```python
def curl(components: str = 'cartesian', domain=None) -> xr.DataArray
```

Return the curl of this vector field, in Cartesian components.

**Parameters**

- `components` (`('cartesian', 'contravariant')`) (default: `"cartesian"`) — What the components are: ``"cartesian"`` (default) ``(x, y, z)``, or ``"contravariant"`` components, which are pushed forward first.
- `domain` (`struphy domain`) (default: `None`) — The mapping (``out.domain``), for the exact Jacobian. Default: from the ``X``, ``Y``, ``Z`` coordinates.

**Returns**

- (`xarray.DataArray`) — The curl, with a ``component`` dimension.

> **See Also**
>
> [`plasma_plots.analysis.curl()`][plasma_plots.analysis.curl] : The function behind this method.

**Examples**

```pycon
>>> B.plasma.analysis.curl()
```

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

### plasma_plots.accessors.ArrayAnalysis.cylindrical_components

*method*

```python
def cylindrical_components() -> xr.DataArray
```

Return the Cartesian components rotated to ``(R, phi, Z)``.

**Returns**

- (`xarray.DataArray`) — The vector field in cylindrical components.

> **See Also**
>
> [`plasma_plots.analysis.cylindrical_components()`][plasma_plots.analysis.cylindrical_components] : The function behind this method.
> [`ArrayAnalysis.toroidal_components()`][plasma_plots.accessors.ArrayAnalysis.toroidal_components] : Components about a magnetic axis.

**Examples**

```pycon
>>> E.plasma.analysis.cylindrical_components()
```

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

### plasma_plots.accessors.ArrayAnalysis.damping_rate

*method*

```python
def damping_rate(window: tuple[float | None, float | None] = (None, None), amplitude: bool = False)
```

Fit exponential decay to the envelope of this oscillating time series.

**Parameters**

- `window` (`(float or None, float or None)`) (default: `(None, None)`) — The time interval ``(t0, t1)`` of the peaks that are used; ``None`` for an open end. Default: every sample.
- `amplitude` (`bool`) (default: `False`) — The series is quadratic in an amplitude (e.g. an energy): return the amplitude's rate. Default: ``False``.

**Returns**

- (`FitResult or None`) — The fit to the peaks; the rate is negative for damping. ``None`` with fewer than two valid peaks.

> **See Also**
>
> [`plasma_plots.analysis.damping_rate()`][plasma_plots.analysis.damping_rate] : The function behind this method.
> [`ArrayAnalysis.growth_rate()`][plasma_plots.accessors.ArrayAnalysis.growth_rate] : The same fit to the series itself.
> [`ArrayAnalysis.envelope()`][plasma_plots.accessors.ArrayAnalysis.envelope] : The peaks that are fitted.

**Examples**

```pycon
>>> energy.plasma.analysis.damping_rate(amplitude=True).rate
```

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

### plasma_plots.accessors.ArrayAnalysis.dispersion

*method*

```python
def dispersion(dim: str | None = None, detrend: bool = True) -> xr.DataArray
```

Return the space-time power spectrum of this ``(t, dim)`` field.

A plain FFT, as a function of angular frequency and wavenumber: the data behind a
dispersion-relation plot ([`ArrayPlots.dispersion()`][plasma_plots.accessors.ArrayPlots.dispersion]). ``dim`` defaults to the sole
dimension other than ``t``; select every other dimension away first. ``omega`` comes out
in the angular-frequency units implied by ``t``'s spacing (e.g. rad/s for physical
seconds, or a normalized angular frequency for normalized time).

**Parameters**

- `dim` (`str`) (default: `None`) — The spatial dimension. Default: the sole dimension other than ``t``.
- `detrend` (`bool`) (default: `True`) — Remove the time-mean at each point of ``dim`` first, which otherwise dominates the spectrum as a spurious zero-frequency line. Default: ``True``.

**Returns**

- (`xarray.DataArray`) — The power over ``omega`` and the wavenumber.

> **See Also**
>
> [`plasma_plots.analysis.power_spectrum()`][plasma_plots.analysis.power_spectrum] : The function behind this method, and the definition.
> [`ArrayPlots.dispersion()`][plasma_plots.accessors.ArrayPlots.dispersion] : The plot of this spectrum.
> [`ArrayAnalysis.fit_branches()`][plasma_plots.accessors.ArrayAnalysis.fit_branches] : Straight branches fitted to it.

**Examples**

```pycon
>>> spectrum = E.isel(eta2=0, eta3=0).plasma.analysis.dispersion()
```

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

### plasma_plots.accessors.ArrayAnalysis.divergence

*method*

```python
def divergence(components: str = 'cartesian', domain=None) -> xr.DataArray
```

Return the divergence of this vector field.

**Parameters**

- `components` (`('cartesian', 'contravariant')`) (default: `"cartesian"`) — What the components are, as for the 3-D views: ``"cartesian"`` (default) ``(x, y, z)``, or ``"contravariant"`` components, which are pushed forward first.
- `domain` (`struphy domain`) (default: `None`) — The mapping (``out.domain``), for the exact Jacobian. Default: from the ``X``, ``Y``, ``Z`` coordinates.

**Returns**

- (`xarray.DataArray`) — The divergence, without the ``component`` dimension.

> **See Also**
>
> [`plasma_plots.analysis.divergence()`][plasma_plots.analysis.divergence] : The function behind this method.

**Examples**

```pycon
>>> B.plasma.analysis.divergence()
```

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

### plasma_plots.accessors.ArrayAnalysis.drift

*method*

```python
def drift(ref=None) -> xr.DataArray
```

Return the signed deviation of this time series from ``ref`` or from its first sample.

**Parameters**

- `ref` (`float or array_like or xarray.DataArray`) (default: `None`) — The reference, broadcast against ``data``. Default: ``data`` at the first time sample.

**Returns**

- (`xarray.DataArray`) — The deviation over ``t``.

> **See Also**
>
> [`plasma_plots.analysis.drift()`][plasma_plots.analysis.drift] : The function behind this method.
> [`ArrayAnalysis.relative_error()`][plasma_plots.accessors.ArrayAnalysis.relative_error] : The absolute relative deviation.

**Examples**

```pycon
>>> energy.plasma.analysis.drift().plasma.plot.timeseries()
```

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

### plasma_plots.accessors.ArrayAnalysis.drop_periodic_endpoint

*method*

```python
def drop_periodic_endpoint(dim: str, *, period: float = 1.0) -> xr.DataArray
```

Return this array without a duplicated periodic endpoint along ``dim``.

**Parameters**

- `dim` (`str`) — The periodic dimension.
- `period` (`float`) (default: `1.0`) — The period in the coordinate of ``dim``. Default: 1.0.

**Returns**

- (`xarray.DataArray`) — This array, one point shorter along ``dim`` if its last point repeats the first.

> **See Also**
>
> [`plasma_plots.spectral.drop_periodic_endpoint()`][plasma_plots.spectral.drop_periodic_endpoint] : The function behind this method.

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

### plasma_plots.accessors.ArrayAnalysis.envelope

*method*

```python
def envelope() -> xr.DataArray
```

Return the local maxima of this time series.

**Returns**

- (`xarray.DataArray`) — The peaks, over their times ``t``.

> **See Also**
>
> [`plasma_plots.analysis.envelope()`][plasma_plots.analysis.envelope] : The function behind this method.

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

### plasma_plots.accessors.ArrayAnalysis.error

*method*

```python
def error(exact, *, norm: str = 'rms', relative: bool = False, dims=None, weighted: bool = False, domain=None, args=None) -> xr.DataArray
```

Return the error against an exact solution (an array or a function of the coordinates).

**Parameters**

- `exact` (`(callable, array_like, number or xarray.DataArray)`) — The exact solution: an array (aligned with ``data``, or broadcast to it) or a function of its coordinates, evaluated with [`evaluate_on()`][evaluate_on], e.g. ``lambda x, y, z, t: ...``.
- `norm` (`('rms', 'max', 'l1', 'l2', 'pointwise')`) (default: `"rms"`) — ``"pointwise"`` is the difference ``data − exact`` itself; ``"max"`` the largest absolute difference; ``"l1"`` the mean (or, weighted, the integral) of ``|data − exact|``; ``"l2"`` the square root of the mean (or integral) of ``|data − exact|²``; ``"rms"`` (default) as ``"l2"``, divided by the volume when weighted.
- `relative` (`bool`) (default: `False`) — Divide by the same norm of the exact solution; for ``"pointwise"``, by the largest ``|exact|`` over the whole array. Default: ``False``.
- `dims` (`str or sequence of str`) (default: `None`) — The dimensions the norm is taken over. Default: every dimension but ``t``. Weighted norms need exactly ``eta1``, ``eta2``, ``eta3``.
- `weighted` (`bool`) (default: `False`) — Integrate over the physical volume instead of averaging over the grid points (no effect on ``"max"`` and ``"pointwise"``). Default: ``False``.
- `domain` (`struphy domain`) (default: `None`) — The mapping (``out.domain``), for the exact ``|√g|`` of weighted norms. Default: from the ``X``, ``Y``, ``Z`` coordinates.
- `args` (`sequence of str`) (default: `None`) — The coordinates passed to a callable ``exact``, as in [`evaluate_on()`][evaluate_on]. Default: ``X``, ``Y``, ``Z`` (or the logical dimensions), then ``t``.

**Returns**

- (`xarray.DataArray`) — The error, over the dimensions not reduced by ``norm``.

> **See Also**
>
> [`plasma_plots.analysis.error()`][plasma_plots.analysis.error] : The function behind this method.

**Examples**

```pycon
>>> T.plasma.analysis.error(exact, relative=True)
>>> T.plasma.analysis.error(exact, norm="max")
```

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

### plasma_plots.accessors.ArrayAnalysis.fft

*method*

```python
def fft(dim: str, detrend: bool = False, window: str | None = None) -> xr.DataArray
```

Return the two-sided Fourier coefficients along ``dim``.

**Parameters**

- `dim` (`str`) — The dimension to transform.
- `detrend` (`bool`) (default: `False`) — Subtract the mean along ``dim`` first. Default: False.
- `window` (`(None, 'hann')`) (default: `None`) — Multiply by a periodic Hann window (see [`hann()`][hann]) first. Default: None (boxcar).

**Returns**

- (`xarray.DataArray`) — The complex coefficients.

> **See Also**
>
> [`plasma_plots.spectral.fft()`][plasma_plots.spectral.fft] : The function behind this method.
> [`ArrayAnalysis.time_fft()`][plasma_plots.accessors.ArrayAnalysis.time_fft] : The one-sided transform in time.

**Examples**

```pycon
>>> phi.plasma.analysis.fft(dim="eta1")
```

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

### plasma_plots.accessors.ArrayAnalysis.field_lines

*method*

```python
def field_lines(seeds=8, turns: float | None = None, length: float | None = None, step: float | None = None, direction: str = 'forward', section: float | None = None, stride: int | None = None, components: str = 'cartesian', **selection) -> xr.Dataset
```

Trace field lines of this vector field through its mapped grid.

**Parameters**

- `seeds` (`(int, dict, array_like or xarray.Dataset)`) (default: `8`) — Where the lines start, in logical coordinates: a number of seeds spread along the radial coordinate at the first poloidal and toroidal grid values (the outboard midplane of a torus whose angles start at 0); a dict of logical coordinates to values or 1-D arrays, which are combined into a grid of seeds (e.g. ``{"rho": 0.95, "theta": thetas, "zeta": zetas}`` for a connection-length map; a missing coordinate takes its first grid value); an ``(n, 3)`` array of points in the order of the logical dimensions; or a Dataset with one variable per logical coordinate. Default: 8.
- `turns` (`float`) (default: `None`) — Stop a line after this many toroidal transits (turns of the torus: nfp periods of the toroidal logical coordinate, i.e. 2π of GVEC's toroidal angle, one period of Struphy's ``eta3``). Default: 20 when the toroidal direction wraps around, else none.
- `length` (`float`) (default: `None`) — Stop a line after this arc length, in the units of ``X``, ``Y``, ``Z``. Default: with ``turns``, 1.5 times the length ``turns`` circles through the seeds' mean major radius would take (a safety net); without, four times the grid's extent.
- `step` (`float`) (default: `None`) — The step of arc length of the integrator. Default: the median spacing of the grid points (trilinear interpolation limits the accuracy before the step does).
- `direction` (`('forward', 'backward', 'both')`) (default: `"forward"`) — Along the field, against it, or each seed in both directions (two lines per seed, with the coordinates ``seed`` and ``direction`` telling them apart; the connection length is then the sum of both). Default: ``"forward"``.
- `section` (`float`) (default: `None`) — The toroidal logical coordinate of the poloidal plane whose punctures are recorded. Default: the first toroidal grid value (e.g. ``zeta = 0``).
- `stride` (`int`) (default: `None`) — Save every ``stride``-th step of each line. Default: as many as keep each line at about 20 000 samples at most; the punctures, transits and lengths count every step regardless.
- `components` (`('cartesian', 'contravariant')`) (default: `"cartesian"`) — What the components are: ``"cartesian"`` (default) ``(x, y, z)``, or contravariant logical components, as for [`plasma_plots.analysis.divergence()`][plasma_plots.analysis.divergence].
- `**selection` (default: `{}`) — The other dimensions, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`xarray.Dataset`) — The lines over ``(s, line)`` with their punctures, rotational transforms and connection lengths; it has ``.plasma.plot.poincare()``, ``.footprint()`` and the other field-line plots.

> **See Also**
>
> [`plasma_plots.fieldlines.trace_field_lines()`][plasma_plots.fieldlines.trace_field_lines] : The function behind this method.
> [`DatasetPlots.poincare()`][plasma_plots.accessors.DatasetPlots.poincare] : The Poincaré plot of the lines.
> [`ArrayAnalysis.sample_along()`][plasma_plots.accessors.ArrayAnalysis.sample_along] : A field along them.

**Examples**

```pycon
>>> lines = B.plasma.analysis.field_lines(seeds=12, turns=100, t=-1)
>>> lines.plasma.plot.poincare(color_by="iota")
>>> edge = B.plasma.analysis.field_lines(
...     seeds={"eta1": 0.98, "eta2": np.linspace(0, 1, 32)},
...     direction="both",
...     t=-1,
... )
```

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

### plasma_plots.accessors.ArrayAnalysis.filter_time

*method*

```python
def filter_time(dims=None, omega_min: float = 1e-08, pad_bins: int = 0)
```

Return the dominant frequency band, reconstructed.

**Parameters**

- `dims` (`str or sequence of str`) (default: `None`) — Non-time dimensions to sum the power over before choosing the band. Default: all dimensions except ``t`` and ``component``. Pass ``dims=()`` for independent filtering at each point.
- `omega_min` (`float`) (default: `1e-08`) — Finite, positive lowest frequency considered, which excludes DC. Default: 1e-8.
- `pad_bins` (`int`) (default: `0`) — Nonnegative number of extra bins on each side of the band. Default: 0.

**Returns**

- (`TimeFilterResult`) — The band and the reconstructed signal.

> **See Also**
>
> [`plasma_plots.spectral.filter_time()`][plasma_plots.spectral.filter_time] : The function behind this method.
> [`ArrayPlots.filtered()`][plasma_plots.accessors.ArrayPlots.filtered] : A probe of the signal against the reconstruction.

**Examples**

```pycon
>>> band = phi.plasma.analysis.filter_time(dims=("eta1", "eta2", "eta3"))
```

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

### plasma_plots.accessors.ArrayAnalysis.fit_branches

*method*

```python
def fit_branches(n_branches: int, k_range: tuple[float, float] | None = None, noise_level: float = 0.5, order: int = 10)
```

Fit straight dispersion branches (``omega = v * k``) to this ``(omega, k)`` power spectrum.

**Parameters**

- `n_branches` (`int`) — The number of branches, at least 1.
- `k_range` (`(float, float)`) (default: `None`) — The interval of non-negative k's that are scanned. Default: ``(k.max() / 8, k.max() / 2)``, which in practice skips both the low-k region where branches have not yet separated, and the folded Nyquist edge.
- `noise_level` (`float`) (default: `0.5`) — Maxima count only above this fraction of the column's peak power. Default: 0.5.
- `order` (`int`) (default: `10`) — A local maximum must exceed every one of its ``order`` neighbors on both sides along omega (out-of-range neighbors are clipped to the edge sample, as in ``scipy.signal.argrelextrema``). Default: 10.

**Returns**

- (`list of BranchFit`) — One fit per branch.

> **See Also**
>
> [`plasma_plots.analysis.fit_dispersion_branches()`][plasma_plots.analysis.fit_dispersion_branches] : The function behind this method.
> [`ArrayAnalysis.dispersion()`][plasma_plots.accessors.ArrayAnalysis.dispersion] : The spectrum to fit.
> [`ArrayAnalysis.trace_branch()`][plasma_plots.accessors.ArrayAnalysis.trace_branch] : The measured frequency along a curved branch.

**Examples**

```pycon
>>> field.plasma.analysis.dispersion().plasma.analysis.fit_branches(
...     n_branches=2
... )
```

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

### plasma_plots.accessors.ArrayAnalysis.flux_function

*method*

```python
def flux_function() -> xr.DataArray
```

Return the flux (or stream) function of this 2-D in-plane field.

**Returns**

- (`xarray.DataArray`) — The flux function, without the ``component`` dimension.

> **See Also**
>
> [`plasma_plots.analysis.flux_function()`][plasma_plots.analysis.flux_function] : The function behind this method.

**Examples**

```pycon
>>> B.plasma.analysis.flux_function()
```

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

### plasma_plots.accessors.ArrayAnalysis.gradient

*method*

```python
def gradient(domain=None) -> xr.DataArray
```

Return the Cartesian gradient of this scalar field on a mapped domain.

**Parameters**

- `domain` (`struphy domain`) (default: `None`) — The mapping (``out.domain``), for the exact Jacobian. Default: differentiate the ``X``, ``Y``, ``Z`` coordinates numerically.

**Returns**

- (`xarray.DataArray`) — The gradient, with a ``component`` dimension ``(x, y, z)``.

> **See Also**
>
> [`plasma_plots.analysis.gradient()`][plasma_plots.analysis.gradient] : The function behind this method.

**Examples**

```pycon
>>> phi.plasma.analysis.gradient()
```

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

### plasma_plots.accessors.ArrayAnalysis.growth_rate

*method*

```python
def growth_rate(window: tuple[float | None, float | None] = (None, None), amplitude: bool = False)
```

Fit ``exp(rate * t + intercept)`` to this time series within ``window``.

**Parameters**

- `window` (`(float or None, float or None)`) (default: `(None, None)`) — The time interval ``(t0, t1)`` of the fitted samples; ``None`` for an open end. Default: every sample.
- `amplitude` (`bool`) (default: `False`) — The series is quadratic in an amplitude (e.g. an energy): return the amplitude's rate. Default: ``False``.

**Returns**

- (`FitResult or None`) — ``.rate``, ``.intercept``, ``.time`` and ``.fitted``; ``None`` with fewer than two valid samples.

> **See Also**
>
> [`plasma_plots.analysis.growth_rate()`][plasma_plots.analysis.growth_rate] : The function behind this method.
> [`ArrayAnalysis.damping_rate()`][plasma_plots.accessors.ArrayAnalysis.damping_rate] : The same fit to the envelope of an oscillating series.
> [`ArrayPlots.timeseries()`][plasma_plots.accessors.ArrayPlots.timeseries] : The series with the fit drawn (``fit=``).

**Examples**

```pycon
>>> energy.plasma.analysis.growth_rate(window=(0.0, 5.0), amplitude=True).rate
```

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

### plasma_plots.accessors.ArrayAnalysis.map_coordinate

*method*

```python
def map_coordinate(dim: str, mapping, *, name: str | None = None, units: str | None = None, label: str | None = None) -> xr.DataArray
```

Replace a coordinate by a function of it, e.g. ``eta1`` by the minor radius in meters.

**Parameters**

- `dim` (`str`) — The dimension whose coordinate is mapped, e.g. ``"eta1"``.
- `mapping` (`callable or float`) — A function of the coordinate's values (``lambda eta1: 0.1 + 0.9 * eta1``), or a factor (a length, for ``length * eta1``).
- `name` (`str`) (default: `None`) — The name of the new dimension, e.g. ``"r"``. Default: keep ``dim``.
- `units` (`str`) (default: `None`) — The new coordinate's units, e.g. ``"m"``. Default: none.
- `label` (`str`) (default: `None`) — The new coordinate's axis label (its ``long_name``), mathtext allowed. Default: ``name``.

**Returns**

- (`xarray.DataArray`) — The array over the new coordinate, which every plot then draws and labels.

> **See Also**
>
> [`plasma_plots.arrays.map_coordinate()`][plasma_plots.arrays.map_coordinate] : The function behind this method.

**Examples**

```pycon
>>> r_T = T.plasma.analysis.map_coordinate(
...     "eta1", lambda eta1: 0.1 + 0.9 * eta1, name="r", units="m"
... )
>>> r_T.plasma.plot.profiles(x="r", eta2=0, eta3=0)
```

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

### plasma_plots.accessors.ArrayAnalysis.matrix_pencil

*method*

```python
def matrix_pencil(n_modes: int = 1, pencil: int | None = None, detrend: bool = False) -> xr.Dataset
```

Return frequencies and growth rates beyond the FFT resolution.

**Parameters**

- `n_modes` (`int`) (default: `1`) — The number of modes to fit and return: real oscillations for a real signal, complex exponentials for a complex one. The fit needs well over ``2 * n_modes`` samples. Default: 1.
- `pencil` (`int`) (default: `None`) — The pencil parameter (Hankel matrix width minus one), which trades noise robustness against resolution. Default: ``N // 2``.
- `detrend` (`bool`) (default: `False`) — Subtract the mean first. Default: False.

**Returns**

- (`xarray.Dataset`) — ``omega``, ``gamma``, ``amplitude`` and ``phase`` along ``mode``, strongest first.

> **See Also**
>
> [`plasma_plots.spectral.matrix_pencil()`][plasma_plots.spectral.matrix_pencil] : The function behind this method.
> [`ArrayPlots.pencil_fit()`][plasma_plots.accessors.ArrayPlots.pencil_fit] : The plot of this fit.

**Examples**

```pycon
>>> probe.plasma.analysis.matrix_pencil(n_modes=1)
```

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

### plasma_plots.accessors.ArrayAnalysis.mode_amplitudes

*method*

```python
def mode_amplitudes(top: int | None = None, real: bool = True, relative: bool = False) -> xr.DataArray
```

Return the real amplitudes of this mode spectrum along one ``mode`` dimension.

**Parameters**

- `top` (`int`) (default: `None`) — Keep only the ``top`` modes with the largest peak amplitude over every other dimension, strongest first. Default: all modes.
- `real` (`bool`) (default: `True`) — The field is real: each ``(m, n)`` is combined with its conjugate ``(-m, -n)``. Only the half with the first nonzero mode number positive is kept, and its amplitude doubled, so a field ``A cos(...)`` gives ``A``. A mode without a twin on the grid (the mean, or the Nyquist mode of an even grid) is kept as it is. Default: True.
- `relative` (`bool`) (default: `False`) — Divide by the amplitude of the mean (the mode with all numbers zero), which is then left out: e.g. density perturbations relative to the background density, as growth plots of an instability often show. NaN where the mean vanishes. Default: False.

**Returns**

- (`xarray.DataArray`) — The amplitudes over ``mode`` and every remaining dimension.

> **See Also**
>
> [`plasma_plots.spectral.mode_amplitudes()`][plasma_plots.spectral.mode_amplitudes] : The function behind this method.
> [`ArrayAnalysis.mode_spectrum()`][plasma_plots.accessors.ArrayAnalysis.mode_spectrum] : The spectrum this is applied to.

**Examples**

```pycon
>>> phi.plasma.analysis.mode_spectrum().plasma.analysis.mode_amplitudes(top=4)
```

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

### plasma_plots.accessors.ArrayAnalysis.mode_spectrum

*method*

```python
def mode_spectrum(dims=None, names=('m', 'n'), periods=None, scale=None) -> xr.DataArray
```

Return the complex amplitudes over poloidal/toroidal mode numbers.

**Parameters**

- `dims` (`str or sequence of str`) (default: `None`) — The periodic dimensions to transform. Default: the two angles of the logical dimensions (see [`plasma_plots.arrays.logical_dims()`][plasma_plots.arrays.logical_dims]), ``("eta2", "eta3")`` for Struphy.
- `names` (`str or sequence of str`) (default: `('m', 'n')`) — The name of the mode number of each dimension, one per dimension. Default: ``("m", "n")``.
- `periods` (`float or sequence of float`) (default: `None`) — Each direction's period in its coordinate: one number for all, or one per dimension. Default: the coordinate's ``period`` attribute (see [`plasma_plots.arrays.angle_period()`][plasma_plots.arrays.angle_period]), else 1.0.
- `scale` (`int or sequence of int`) (default: `None`) — Multiplies the mode numbers (one number, or one per dimension; cast to integers), e.g. ``scale=(1, 6)`` labels a sixth of a torus (Struphy's ``tor_period=6``) with full-torus toroidal mode numbers. Default: 2π over the ``period`` attribute of an angle (nfp for GVEC's toroidal angle), else 1.

**Returns**

- (`xarray.DataArray`) — The amplitudes over the mode numbers ``names`` and every remaining dimension.

> **See Also**
>
> [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum] : The function behind this method.
> [`ArrayAnalysis.mode_amplitudes()`][plasma_plots.accessors.ArrayAnalysis.mode_amplitudes] : Real amplitudes of this spectrum.

**Examples**

```pycon
>>> modes = phi.plasma.analysis.mode_spectrum()
```

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

### plasma_plots.accessors.ArrayAnalysis.mode_structure

*method*

```python
def mode_structure(omega: float, *, window: str | None = 'hann', detrend: bool = True) -> xr.DataArray
```

Return the complex amplitude at the exact frequency ``omega`` at every point.

**Parameters**

- `omega` (`float`) — The angular frequency ω.
- `window` (`('hann', None)`) (default: `"hann"`) — The weights ``w(t)``: a periodic Hann window, or ``None`` for uniform weights. Default: ``"hann"``.
- `detrend` (`bool`) (default: `True`) — Subtract the temporal mean at every point first. Default: True.

**Returns**

- (`xarray.DataArray`) — The complex amplitude over every dimension but ``t``.

> **See Also**
>
> [`plasma_plots.spectral.mode_structure()`][plasma_plots.spectral.mode_structure] : The function behind this method.
> [`ArrayPlots.mode_profiles()`][plasma_plots.accessors.ArrayPlots.mode_profiles] : The harmonics of this eigenfunction (``omega=``).

**Examples**

```pycon
>>> phi.plasma.analysis.mode_structure(omega)
```

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

### plasma_plots.accessors.ArrayAnalysis.norm

*method*

```python
def norm(dims=None, squared: bool = False) -> xr.DataArray
```

Return the L2 norm over ``dims`` (default: every dimension except ``t``).

**Parameters**

- `dims` (`str or sequence of str`) (default: `None`) — The dimensions summed over. Default: every dimension except ``t``.
- `squared` (`bool`) (default: `False`) — Return the squared norm ``Σ f²`` instead. Default: ``False``.

**Returns**

- (`xarray.DataArray`) — The norm over the remaining dimensions, e.g. ``t``.

> **See Also**
>
> [`plasma_plots.analysis.norm()`][plasma_plots.analysis.norm] : The function behind this method.

**Examples**

```pycon
>>> div_B.plasma.analysis.norm()
```

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

### plasma_plots.accessors.ArrayAnalysis.oscillation_frequency

*method*

```python
def oscillation_frequency(window: tuple[float | None, float | None] = (None, None), method: str = 'zero_crossings', detrend: bool = True)
```

Measure the frequency of this oscillating time series from its zero crossings or peaks.

**Parameters**

- `window` (`(float or None, float or None)`) (default: `(None, None)`) — The time interval ``(t0, t1)`` used; ``None`` for an open end. Default: every sample.
- `method` (`('zero_crossings', 'peaks')`) (default: `"zero_crossings"`) — Count the crossings of the mean (half a period apart), or the maxima (a period apart; for a signal that does not cross its mean, e.g. an energy, whose peaks are half the field's period apart). Default: ``"zero_crossings"``.
- `detrend` (`bool`) (default: `True`) — Subtract the mean over the window first, so that crossings are of the mean. Default: ``True``.

**Returns**

- (`OscillationFit or None`) — ``omega``, ``period`` and the ``times`` of the crossings or peaks used; ``None`` with fewer than two.

> **See Also**
>
> [`plasma_plots.analysis.oscillation_frequency()`][plasma_plots.analysis.oscillation_frequency] : The function behind this method.
> [`ArrayAnalysis.damping_rate()`][plasma_plots.accessors.ArrayAnalysis.damping_rate] : The decay of the same oscillation.

**Examples**

```pycon
>>> probe.plasma.analysis.oscillation_frequency(window=(5.0, 40.0)).omega
```

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

### plasma_plots.accessors.ArrayAnalysis.parallel_wavenumber

*method*

```python
def parallel_wavenumber(lines: xr.Dataset | None = None, method: str = 'fft', detrend: bool = True) -> xr.DataArray
```

Return the dominant parallel wavenumber of this field along field lines.

**Parameters**

- `lines` (`xarray.Dataset`) (default: `None`) — Traced lines to sample this field along first. Default: this array already is the samples of [`sample_along()`][plasma_plots.accessors.ArrayAnalysis.sample_along], over ``(s, line)``.
- `method` (`('fft', 'crossings')`) (default: `"fft"`) — How to estimate it. Default: ``"fft"``.
- `detrend` (`bool`) (default: `True`) — Remove the mean along each line first. Default: True.

**Returns**

- (`xarray.DataArray`) — ``k_parallel`` over ``line`` and the other dimensions.

> **See Also**
>
> [`plasma_plots.fieldlines.parallel_wavenumber()`][plasma_plots.fieldlines.parallel_wavenumber] : The function behind this method.
> [`plasma_plots.theory.waves.parallel_wavenumber()`][plasma_plots.theory.waves.parallel_wavenumber] : The expected ``(n + m/q)/R₀``.

**Examples**

```pycon
>>> phi.plasma.analysis.parallel_wavenumber(lines=lines)
```

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

### plasma_plots.accessors.ArrayAnalysis.polar_coordinates

*method*

```python
def polar_coordinates(center=(0.0, 0.0)) -> xr.DataArray
```

Return this array with coordinates ``r`` and ``theta`` in the ``X``-``Y`` plane.

**Parameters**

- `center` (`(float, float)`) (default: `(0.0, 0.0)`) — The origin ``(X, Y)`` of the polar coordinates. Default: ``(0.0, 0.0)``.

**Returns**

- (`xarray.DataArray`) — This array with the added coordinates.

> **See Also**
>
> [`plasma_plots.analysis.polar_coordinates()`][plasma_plots.analysis.polar_coordinates] : The function behind this method.

**Examples**

```pycon
>>> n.plasma.analysis.polar_coordinates(center=(0.0, 0.0))
```

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

### plasma_plots.accessors.ArrayAnalysis.project_mode

*method*

```python
def project_mode(dim: str, number: float, kind: str = 'sin', period: float = 1.0, bin_correction: bool = False) -> xr.DataArray
```

Return the amplitude of one Fourier mode along ``dim``.

**Parameters**

- `dim` (`str`) — The periodic dimension, e.g. ``"eta1"``.
- `number` (`float`) — The mode number, not a wavenumber: ``k = 2π number / L``.
- `kind` (`('sin', 'cos', 'complex')`) (default: `"sin"`) — ``"sin"`` (default) gives ``a`` of ``a sin(2π number x / period)``: ``2 ⟨f sin(…)⟩``; ``"cos"`` the cosine amplitude, and ``"complex"`` the complex amplitude ``2 ⟨f exp(−i…)⟩`` (``abs()`` the amplitude, ``np.angle()`` the phase).
- `period` (`float`) (default: `1.0`) — The period of ``dim``. Default: 1, the logical unit interval.
- `bin_correction` (`bool`) (default: `False`) — Undo the damping of binned particle data, whose bins average the mode over their width ``h``: divide by ``sinc(number h / period)``. Default: ``False``.

**Returns**

- (`xarray.DataArray`) — The amplitude over the other dimensions.

> **See Also**
>
> [`plasma_plots.analysis.project_mode()`][plasma_plots.analysis.project_mode] : The function behind this method.

**Examples**

```pycon
>>> rho.plasma.analysis.project_mode(dim="eta2", number=3, kind="complex")
```

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

### plasma_plots.accessors.ArrayAnalysis.quasisymmetry_error

*method*

```python
def quasisymmetry_error(helicity='QA', angles: str = 'boozer') -> xr.DataArray
```

Return the quasi-symmetry error of this ``|B|`` on each flux surface.

**Parameters**

- `helicity` (`('QA', 'QP', 'QH')`) (default: `"QA"`) — The symmetry: a name, or ``(M, N)`` with ``N`` a full-torus toroidal mode number (its sign picks the handedness). Default: ``"QA"``.
- `angles` (`('boozer', 'any')`) (default: `"boozer"`) — As for [`boozer_spectrum()`][plasma_plots.accessors.ArrayAnalysis.boozer_spectrum].

**Returns**

- (`xarray.DataArray`) — ``f_QS`` over the radius.

> **See Also**
>
> [`plasma_plots.analysis.quasisymmetry_error()`][plasma_plots.analysis.quasisymmetry_error] : The function behind this method.
> [`ArrayAnalysis.boozer_spectrum()`][plasma_plots.accessors.ArrayAnalysis.boozer_spectrum] : The harmonics it is computed from.

**Examples**

```pycon
>>> boozer.mod_B.plasma.analysis.quasisymmetry_error(helicity="QH")
```

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

### plasma_plots.accessors.ArrayAnalysis.rational_surfaces

*method*

```python
def rational_surfaces(count: int = 4, nfp: int | None = None, max_denominator: int = 12) -> xr.DataArray
```

Return where this rotational transform (or safety factor) profile is a low-order rational.

**Parameters**

- `count` (`int`) (default: `4`) — The number of rational values. Default: 4.
- `nfp` (`int`) (default: `None`) — The numerators are multiples of it. Default: the profile's ``nfp`` attribute (GVEC's, see [`plasma_plots.gvec.from_gvec()`][plasma_plots.gvec.from_gvec]), else 1.
- `max_denominator` (`int`) (default: `12`) — The largest ``m``. Default: 12.

**Returns**

- (`xarray.DataArray`) — The positions over ``surface``, with the coordinates ``n``, ``m`` and ``value``.

> **See Also**
>
> [`plasma_plots.analysis.rational_surfaces()`][plasma_plots.analysis.rational_surfaces] : The function behind this method.
> [`ArrayPlots.lineout()`][plasma_plots.accessors.ArrayPlots.lineout] : ``rationals=`` marks them on the profile.

**Examples**

```pycon
>>> ev.iota.plasma.analysis.rational_surfaces(count=3)
```

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

### plasma_plots.accessors.ArrayAnalysis.reconnected_flux

*method*

```python
def reconnected_flux(relative: bool = True, o_point=None, x_point=None) -> xr.DataArray
```

Return the reconnected flux over time: this flux function between an O- and an X-point.

**Parameters**

- `relative` (`bool`) (default: `True`) — Subtract the value at the first time. Default: True.
- `o_point` (`(float, float)`) (default: `None`) — The logical coordinates near which to look for the O-point. Default: the dominant island's.
- `x_point` (`(float, float)`) (default: `None`) — The same for the X-point.

**Returns**

- (`xarray.DataArray`) — ``ΔΨ(t)``.

> **See Also**
>
> [`plasma_plots.analysis.reconnected_flux()`][plasma_plots.analysis.reconnected_flux] : The function behind this method.
> [`ArrayAnalysis.growth_rate()`][plasma_plots.accessors.ArrayAnalysis.growth_rate] : Its growth rate.

**Examples**

```pycon
>>> A = B.plasma.analysis.flux_function()
>>> A.plasma.analysis.reconnected_flux().plasma.plot.timeseries(
...     fit=(10.0, 30.0)
... )
```

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

### plasma_plots.accessors.ArrayAnalysis.relative_error

*method*

```python
def relative_error(ref=None, skip_first: bool = True) -> xr.DataArray
```

Return the absolute relative deviation from ``ref`` or from this series' first sample.

**Parameters**

- `ref` (`float or array_like or xarray.DataArray`) (default: `None`) — The reference, broadcast against ``data``; must be non-zero everywhere. Default: ``data`` at the first time sample.
- `skip_first` (`bool`) (default: `True`) — Leave out the first time sample (zero against the default reference). Default: ``True``.

**Returns**

- (`xarray.DataArray`) — The relative deviation over ``t``.

> **See Also**
>
> [`plasma_plots.analysis.relative_error()`][plasma_plots.analysis.relative_error] : The function behind this method.
> [`ArrayAnalysis.drift()`][plasma_plots.accessors.ArrayAnalysis.drift] : The signed deviation.

**Examples**

```pycon
>>> energy.plasma.analysis.relative_error(ref=exact_solution)
```

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

### plasma_plots.accessors.ArrayAnalysis.sample_along

*method*

```python
def sample_along(lines: xr.Dataset) -> xr.DataArray
```

Return this scalar field interpolated along traced field lines.

**Parameters**

- `lines` (`xarray.Dataset`) — The lines of [`trace_field_lines()`][trace_field_lines].

**Returns**

- (`xarray.DataArray`) — The field over ``(s, line)`` after its other dimensions.

> **See Also**
>
> [`plasma_plots.fieldlines.sample_along()`][plasma_plots.fieldlines.sample_along] : The function behind this method.
> [`ArrayAnalysis.parallel_wavenumber()`][plasma_plots.accessors.ArrayAnalysis.parallel_wavenumber] : The dominant wavenumber along each line.
> [`ArrayPlots.along_field_lines()`][plasma_plots.accessors.ArrayPlots.along_field_lines] : The plot.

**Examples**

```pycon
>>> along = phi.plasma.analysis.sample_along(lines)
>>> along.isel(line=0).plasma.plot.slice(x="s", y="t")
```

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

### plasma_plots.accessors.ArrayAnalysis.spatial_average

*method*

```python
def spatial_average(dims=None) -> xr.DataArray
```

Return the mean over the logical space dimensions ``eta1``, ``eta2``, ``eta3`` (or ``dims``).

For a binned ``e1_v1`` distribution this is f(v1, t) averaged over space.

**Parameters**

- `dims` (`str or sequence of str`) (default: `None`) — The dimensions averaged over. Default: every logical dimension (``eta1``, ``eta2``, ``eta3``, or GVEC's ``rho``, ``theta``, ``zeta``) that ``data`` has.

**Returns**

- (`xarray.DataArray`) — The mean over the remaining dimensions.

> **See Also**
>
> [`plasma_plots.analysis.spatial_average()`][plasma_plots.analysis.spatial_average] : The function behind this method.

**Examples**

```pycon
>>> distribution.plasma.analysis.spatial_average()
```

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

### plasma_plots.accessors.ArrayAnalysis.spectral_peaks

*method*

```python
def spectral_peaks(n_peaks: int = 3, dims=None, omega_min: float = 1e-08, detrend=True, window=None) -> xr.Dataset
```

Return the strongest spectral peaks, with sub-bin frequencies.

**Parameters**

- `n_peaks` (`int`) (default: `3`) — The number of peaks to return at most. Default: 3.
- `dims` (`str or sequence of str`) (default: `None`) — Dimensions to sum the power over. Default: every dimension but ``omega``. Only ``omega`` may remain.
- `omega_min` (`float`) (default: `1e-08`) — The lowest frequency a peak may have, which excludes DC. Default: 1e-8.
- `detrend` (`bool or int`) (default: `True`) — For a time series: ``True`` subtracts the mean, ``False`` nothing, and an integer is the degree of a least-squares polynomial in ``t`` removed at every point first. An energy such as LinearMHD's ``en_U`` oscillates at twice the wave frequency around a slow trend, so its peaks with ``detrend=2`` sit at ``2 * omega``. Ignored for spectra. Default: True.
- `window` (`(None, 'hann')`) (default: `None`) — Window applied before transforming a time series. Default: None.

**Returns**

- (`xarray.Dataset`) — The peaks, strongest first.

> **See Also**
>
> [`plasma_plots.spectral.spectral_peaks()`][plasma_plots.spectral.spectral_peaks] : The function behind this method.
> [`ArrayPlots.power_spectrum()`][plasma_plots.accessors.ArrayPlots.power_spectrum] : The spectrum with the peaks labeled (``peaks=``).

**Examples**

```pycon
>>> phi.plasma.analysis.spectral_peaks(n_peaks=2)
```

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

### plasma_plots.accessors.ArrayAnalysis.spectrogram

*method*

```python
def spectrogram(length, step=None, detrend: bool = True, window: str | None = 'hann') -> xr.DataArray
```

Return power spectra in sliding time windows.

**Parameters**

- `length` (`int or float`) — The window length: a sample count (integer, 4 to the number of samples) or a time span (float).
- `step` (`int or float`) (default: `None`) — The shift between windows: a sample count (integer) or a time span (float). Default: a quarter of ``length``.
- `detrend` (`bool`) (default: `True`) — Subtract each window's mean. Default: True.
- `window` (`('hann', None)`) (default: `"hann"`) — The taper of each window, not compensated for. Default: ``"hann"``.

**Returns**

- (`xarray.DataArray`) — The power over ``(t, omega, ...)``, ``t`` being each window's center.

> **See Also**
>
> [`plasma_plots.spectral.spectrogram()`][plasma_plots.spectral.spectrogram] : The function behind this method.
> [`ArrayPlots.spectrogram()`][plasma_plots.accessors.ArrayPlots.spectrogram] : The plot of these spectra.

**Examples**

```pycon
>>> signal.plasma.analysis.spectrogram(length=200.0, step=10.0)
```

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

### plasma_plots.accessors.ArrayAnalysis.surface_average

*method*

```python
def surface_average(jacobian=None, domain=None, quadrature=None) -> xr.DataArray
```

Return the flux-surface average of this field over its two angles.

**Parameters**

- `jacobian` (`xarray.DataArray`) (default: `None`) — ``√g`` on the same grid, e.g. GVEC's ``Jac`` (its absolute value is used). Default: from ``domain``, else the numerical Jacobian of the ``X``, ``Y``, ``Z`` coordinates, which needs at least two radial points.
- `domain` (`struphy domain`) (default: `None`) — The mapping, for the exact ``√g`` of a Struphy run.
- `quadrature` (`dict`) (default: `None`) — Explicit weights for the angles, as for [`volume_integral()`][volume_integral].

**Returns**

- (`xarray.DataArray`) — ``⟨f⟩`` over the radius and every non-spatial dimension.

> **See Also**
>
> [`plasma_plots.analysis.surface_average()`][plasma_plots.analysis.surface_average] : The function behind this method.
> [`DatasetAnalysis.surface_average()`][plasma_plots.accessors.DatasetAnalysis.surface_average] : The same, with the Dataset's ``Jac``.

**Examples**

```pycon
>>> ev.mod_B.plasma.analysis.surface_average(jacobian=ev.Jac)
```

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

### plasma_plots.accessors.ArrayAnalysis.time_fft

*method*

```python
def time_fft(detrend: bool = False, window: str | None = None) -> xr.Dataset
```

Return the one-sided temporal coefficients and the power per bin.

**Parameters**

- `detrend` (`bool`) (default: `False`) — Subtract the temporal mean first. Default: False.
- `window` (`(None, 'hann')`) (default: `None`) — Multiply by a periodic Hann window (see [`hann()`][hann]) first. Default: None (boxcar).

**Returns**

- (`xarray.Dataset`) — ``coefficients`` and ``power`` over ``omega`` and the other dimensions.

> **See Also**
>
> [`plasma_plots.spectral.time_fft()`][plasma_plots.spectral.time_fft] : The function behind this method.
> [`ArrayPlots.power_spectrum()`][plasma_plots.accessors.ArrayPlots.power_spectrum] : The plot of the power.

**Examples**

```pycon
>>> phi.plasma.analysis.time_fft(detrend=True)
```

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

### plasma_plots.accessors.ArrayAnalysis.toroidal_components

*method*

```python
def toroidal_components(R0: float, Z0: float = 0.0) -> xr.DataArray
```

Return the Cartesian components rotated to ``(radial, poloidal, toroidal)`` about an axis at ``R0``.

**Parameters**

- `R0` (`float`) — The major radius of the magnetic axis.
- `Z0` (`float`) (default: `0.0`) — The height of the magnetic axis. Default: 0.

**Returns**

- (`xarray.DataArray`) — The vector field in toroidal components.

> **See Also**
>
> [`plasma_plots.analysis.toroidal_components()`][plasma_plots.analysis.toroidal_components] : The function behind this method.
> [`ArrayAnalysis.cylindrical_components()`][plasma_plots.accessors.ArrayAnalysis.cylindrical_components] : Components about the ``Z`` axis.

**Examples**

```pycon
>>> u.plasma.analysis.toroidal_components(R0=3.0)
```

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

### plasma_plots.accessors.ArrayAnalysis.trace_branch

*method*

```python
def trace_branch(theory, *, window: float = 0.2, k_range=None, threshold: float = 0.001) -> xr.Dataset
```

Return the measured frequency of a dispersion branch near ``theory(k)`` in this ``(omega, k)`` spectrum.

**Parameters**

- `theory` (`callable`) — The expected branch ``omega(k)``, applied to an array of ``k``; of a complex frequency (as [`plasma_plots.theory`][plasma_plots.theory] returns), the real part is used.
- `window` (`float`) (default: `0.2`) — The relative half-width of the search window about the theory. Default: 0.2.
- `k_range` (`(float, float)`) (default: `None`) — The ``k`` interval to trace (negative ``k`` are never traced). Default: every ``k >= 0``.
- `threshold` (`float`) (default: `0.001`) — Maxima weaker than this times the strongest one found count as no wave. Default: 1e-3.

**Returns**

- (`xarray.Dataset`) — The measured branch over ``k``.

> **See Also**
>
> [`plasma_plots.spectral.trace_branch()`][plasma_plots.spectral.trace_branch] : The function behind this method.
> [`ArrayPlots.against_theory()`][plasma_plots.accessors.ArrayPlots.against_theory] : The measured frequencies against the theory.

**Examples**

```pycon
>>> spectrum.plasma.analysis.trace_branch(
...     bohm_gross, window=0.2, k_range=(1.5, 5.5)
... )
```

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

### plasma_plots.accessors.ArrayAnalysis.velocity_moments

*method*

```python
def velocity_moments(dims=None) -> xr.Dataset
```

Return density, mean velocity and variance of a binned distribution over its velocity dimensions.

See [`plasma_plots.analysis.velocity_moments()`][plasma_plots.analysis.velocity_moments] for the definitions.

**Parameters**

- `dims` (`str or sequence of str`) (default: `None`) — The velocity dimensions integrated over, each with a coordinate of at least two bins. Default: every one of ``v1``, ``v2``, ``v3`` that ``f`` has.

**Returns**

- (`xarray.Dataset`) — The moments, over the remaining dimensions.

> **See Also**
>
> [`plasma_plots.analysis.velocity_moments()`][plasma_plots.analysis.velocity_moments] : The function behind this method.

**Examples**

```pycon
>>> distribution.plasma.analysis.velocity_moments()
```

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

## plasma_plots.accessors.ArrayData

*class*

```python
class ArrayData(_ArrayAccessor)
```

Bases: `plasma_plots.accessors._ArrayAccessor`

The data behind each plot in [`ArrayPlots`][plasma_plots.accessors.ArrayPlots], without rendering it.

Every method here mirrors one on ``array.plasma.plot`` and returns the plain, already
selected ``xarray`` object (or a small tuple/dict of them) that method would have drawn —
useful to hand to a different plotting library (Plotly, bokeh, ...), or to inspect directly.

**Examples**

```pycon
>>> phi.plasma.data.slice(x="eta1", y="eta2", t=-1)
>>> n.plasma.data.lineout(x="eta1", t=-1, eta2=0.3, eta3=0)
```

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

### plasma_plots.accessors.ArrayData.compare

*method*

```python
def compare(other: xr.DataArray, *, mode: Literal['difference', 'ratio'] = 'difference') -> xr.DataArray
```

Return the aligned difference or ratio [`ArrayPlots.compare()`][plasma_plots.accessors.ArrayPlots.compare] would plot.

**Parameters**

- `other` (`xarray.DataArray`) — The array to compare with, e.g. a reference run; aligned with this one first.
- `mode` (`('difference', 'ratio')`) (default: `"difference"`) — ``first - second``, or ``first / second`` (NaN where ``second`` is zero). Default: ``"difference"``.

**Returns**

- (`xarray.DataArray`) — This array minus ``other``, or divided by it, after alignment.

> **See Also**
>
> [`ArrayPlots.compare()`][plasma_plots.accessors.ArrayPlots.compare] : The plot of this difference or ratio.
> [`plasma_plots.plotting.prepare_compare()`][plasma_plots.plotting.prepare_compare] : The function that computes it.

**Examples**

```pycon
>>> field.plasma.data.compare(reference_field, mode="ratio")
```

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

### plasma_plots.accessors.ArrayData.critical_points

*method*

```python
def critical_points(refine: bool = True, **selection) -> xr.Dataset
```

Return the O- and X-points [`ArrayPlots.critical_points()`][plasma_plots.accessors.ArrayPlots.critical_points] would mark.

**Parameters**

- `refine` (`bool`) (default: `True`) — Locate the zero within the cell by Newton's method (the cell's centre otherwise). Default: True.
- `**selection` (default: `{}`) — The other dimensions, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`xarray.Dataset`) — The points over ``point`` (and the dimensions left, e.g. ``t``).

> **See Also**
>
> [`plasma_plots.analysis.critical_points()`][plasma_plots.analysis.critical_points] : The function behind this method.
> [`ArrayPlots.critical_points()`][plasma_plots.accessors.ArrayPlots.critical_points] : The plot of these points.

**Examples**

```pycon
>>> A.plasma.data.critical_points(t=-1)
```

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

### plasma_plots.accessors.ArrayData.dispersion

*method*

```python
def dispersion(dim: str | None = None, detrend: bool = True) -> xr.DataArray
```

Return the space-time power spectrum [`ArrayPlots.dispersion()`][plasma_plots.accessors.ArrayPlots.dispersion] would plot.

The same as [`ArrayAnalysis.dispersion()`][plasma_plots.accessors.ArrayAnalysis.dispersion]; included here too for parity with every
other plot.

**Parameters**

- `dim` (`str`) (default: `None`) — The spatial dimension. Default: the sole dimension other than ``t``.
- `detrend` (`bool`) (default: `True`) — Remove the time-mean at each point of ``dim`` first, which otherwise dominates the spectrum as a spurious zero-frequency line. Default: ``True``.

**Returns**

- (`xarray.DataArray`) — The power over angular frequency ``omega`` and wavenumber.

> **See Also**
>
> [`plasma_plots.analysis.power_spectrum()`][plasma_plots.analysis.power_spectrum] : The function behind this method.
> [`ArrayPlots.dispersion()`][plasma_plots.accessors.ArrayPlots.dispersion] : The plot of this spectrum.
> [`ArrayAnalysis.dispersion()`][plasma_plots.accessors.ArrayAnalysis.dispersion] : The same spectrum.

**Examples**

```pycon
>>> field.plasma.data.dispersion(dim="eta1")
```

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

### plasma_plots.accessors.ArrayData.grid

*method*

```python
def grid(name: str | None = None, **selection)
```

Return this field as a ``pyvista.StructuredGrid`` on its physical points.

Every dimension but ``eta1``, ``eta2``, ``eta3`` (and ``component``) is selected first.
This is the data behind every 3-D view, ready for any PyVista filter.

**Parameters**

- `name` (`str`) (default: `None`) — The name of the point data. Default: the field's label.
- `**selection` (default: `{}`) — Every dimension but ``eta1``, ``eta2``, ``eta3`` and ``component``, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`pyvista.StructuredGrid`) — The grid, with the field as its point data.

> **See Also**
>
> [`plasma_plots.pyvista_plots.structured_grid()`][plasma_plots.pyvista_plots.structured_grid] : The function behind this method.
> [`ArrayData.to_vtk()`][plasma_plots.accessors.ArrayData.to_vtk] : Write the grid to files instead.

**Examples**

```pycon
>>> grid = phi.plasma.data.grid(t=-1)
```

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

### plasma_plots.accessors.ArrayData.lineout

*method*

```python
def lineout(x: str | None = None, **selection) -> xr.DataArray
```

Return the 1-D profile [`ArrayPlots.lineout()`][plasma_plots.accessors.ArrayPlots.lineout] would plot.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension to keep: checked to be the only one left after ``selection``. Default: whichever it is.
- `**selection` (default: `{}`) — The other dimensions: an integer is a position (``t=-1`` the last), a float the nearest coordinate value.

**Returns**

- (`xarray.DataArray`) — The selected profile, over ``x`` only.

**Raises**

- `ValueError` — If more or fewer than one dimension remains, or ``x`` is not the remaining one.

> **See Also**
>
> [`plasma_plots.plotting.prepare_lineout()`][plasma_plots.plotting.prepare_lineout] : The check behind this method.
> [`ArrayPlots.lineout()`][plasma_plots.accessors.ArrayPlots.lineout] : The plot of this profile.

**Examples**

```pycon
>>> n.plasma.data.lineout(x="eta1", t=-1, eta2=0.3, eta3=0)
```

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

### plasma_plots.accessors.ArrayData.overlay_orbits

*method*

```python
def overlay_orbits(orbits: xr.Dataset, *, x: str, y: str, max_markers: int = 200, **selection) -> tuple[xr.DataArray, xr.Dataset]
```

Return the field slice and marker subset [`ArrayPlots.overlay_orbits()`][plasma_plots.accessors.ArrayPlots.overlay_orbits] would plot.

**Parameters**

- `orbits` (`xarray.Dataset`) — An orbits product with position variables named after ``view.x`` and ``view.y`` (e.g. its logical coordinates, to overlay directly on a logical-coordinates slice).
- `x` (`str`) — The horizontal dimension of the slice. ``orbits`` must have a position variable of the same name (e.g. logical ``eta1``, to overlay directly on a logical-coordinates slice of this field).
- `y` (`str`) — The vertical dimension of the slice; ``orbits`` needs a variable of this name too.
- `max_markers` (`int`) (default: `200`) — Draw only the first ``max_markers`` markers. Default: ``200``.
- `**selection` (default: `{}`) — Every other dimension of this field, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`tuple of (xarray.DataArray, xarray.Dataset)`) — The field slice, and the orbits of the first ``max_markers`` markers.

**Raises**

- `ValueError` — If ``orbits`` has no variables named ``x`` and ``y``, or no ``marker`` dimension.

> **See Also**
>
> [`ArrayPlots.overlay_orbits()`][plasma_plots.accessors.ArrayPlots.overlay_orbits] : The plot of this slice and these orbits.

**Examples**

```pycon
>>> field, paths = field.plasma.data.overlay_orbits(
...     orbits, x="eta1", y="eta2", t=-1
... )
```

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

### plasma_plots.accessors.ArrayData.poincare

*method*

```python
def poincare(seeds=8, turns: float | None = None, section: float | None = None, **selection) -> xr.Dataset
```

Return the Poincaré section [`ArrayPlots.poincare()`][plasma_plots.accessors.ArrayPlots.poincare] would plot.

**Parameters**

- `seeds` (`(int, dict, array_like or xarray.Dataset)`) (default: `8`) — Where the lines start; see [`plasma_plots.fieldlines.trace_field_lines()`][plasma_plots.fieldlines.trace_field_lines]. Default: 8 along the radius.
- `turns` (`float`) (default: `None`) — How many toroidal transits to trace. Default: 20.
- `section` (`float`) (default: `None`) — The toroidal logical coordinate of the plane. Default: the first grid value.
- `**selection` (default: `{}`) — The other dimensions, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`xarray.Dataset`) — The punctures over ``(puncture, line)``; see [`plasma_plots.fieldlines.poincare_section()`][plasma_plots.fieldlines.poincare_section].

> **See Also**
>
> [`ArrayPlots.poincare()`][plasma_plots.accessors.ArrayPlots.poincare] : The plot of these punctures.
> [`ArrayAnalysis.field_lines()`][plasma_plots.accessors.ArrayAnalysis.field_lines] : The traced lines themselves.

**Examples**

```pycon
>>> B.plasma.data.poincare(seeds=12, turns=100, t=-1)
```

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

### plasma_plots.accessors.ArrayData.slice

*method*

```python
def slice(x: str | None = None, y: str | None = None, sweep: str = 't', coords: Coordinates = 'logical', plane: Plane = 'XY', **selection) -> xr.DataArray
```

Return the single 2-D slice [`ArrayPlots.slice()`][plasma_plots.accessors.ArrayPlots.slice] would plot.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second remaining dimension.
- `sweep` (`str`) (default: `'t'`) — The dimension stepped through by panels, the viewer's slider, animations and exported frames. Default: ``"t"``.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Draw over the logical coordinates, or over the mapped physical coordinates (``X``, ``Y``, ``Z``). Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ', 'X1X2')`) (default: `"XY"`) — The physical plane, with ``coords="physical"``: ``"RZ"`` uses ``R = √(X² + Y²)``, ``"X1X2"`` GVEC's reference coordinates. Default: ``"XY"``.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and ``sweep``: an integer is a position (``-1`` the last), a float the nearest coordinate value. Checked now; a name that is not a dimension raises ``TypeError``.

**Returns**

- (`xarray.DataArray`) — The selected slice.

> **See Also**
>
> [`ArrayPlots.slice()`][plasma_plots.accessors.ArrayPlots.slice] : The plot of this slice.

**Examples**

```pycon
>>> phi.plasma.data.slice(x="eta1", y="eta2", t=-1)
>>> n.plasma.data.slice(coords="physical", plane="XY", t=-1, eta3=0)
```

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

### plasma_plots.accessors.ArrayData.slices_3d

*method*

```python
def slices_3d(cuts: dict | None = None, **selection) -> list[xr.DataArray]
```

Return the logical cuts [`ArrayPlots.slices_3d()`][plasma_plots.accessors.ArrayPlots.slices_3d] would draw.

**Parameters**

- `cuts` (`dict`) (default: `None`) — ``{dim: position or list of positions}`` along ``eta1``, ``eta2``, ``eta3``: a float is the nearest logical coordinate, an integer a grid index (``-1`` the last). Default: the middle of every dimension, or the whole plane of a 2-D field.
- `**selection` (default: `{}`) — Every dimension but ``eta1``, ``eta2``, ``eta3``, e.g. ``t=0``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`list of xarray.DataArray`) — One array per cut.

> **See Also**
>
> [`ArrayPlots.slices_3d()`][plasma_plots.accessors.ArrayPlots.slices_3d] : The drawing of these cuts.
> [`plasma_plots.pyvista_plots.prepare_slices_3d()`][plasma_plots.pyvista_plots.prepare_slices_3d] : The function that prepares them.

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

### plasma_plots.accessors.ArrayData.timeseries

*method*

```python
def timeseries(*others) -> list[xr.DataArray]
```

Return this time series and any ``others``, validated, as [`ArrayPlots.timeseries()`][plasma_plots.accessors.ArrayPlots.timeseries] plots them.

**Parameters**

- `*others` (default: `()`) — Further arrays with the single dimension ``t``; they may come from other runs and need not share this array's time grid.

**Returns**

- (`list of xarray.DataArray`) — This series first, then ``others``.

**Raises**

- `ValueError` — If a series does not have the dimension ``t``.

> **See Also**
>
> [`ArrayPlots.timeseries()`][plasma_plots.accessors.ArrayPlots.timeseries] : The plot of these series.

**Examples**

```pycon
>>> energy.plasma.data.timeseries(other_run_energy)
```

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

### plasma_plots.accessors.ArrayData.to_vtk

*method*

```python
def to_vtk(path, *, name: str | None = None, **selection) -> list[str]
```

Write this field to VTK structured-grid files for ParaView.

One ``.vts`` per time and a ``.pvd`` collection, or a single ``.vts`` without ``t``.
Select other dimensions first.

**Parameters**

- `path` (`str or pathlib.Path`) — The ``.vts`` file (the suffix is set to ``.vts``), or with a ``t`` dimension the directory to write into (created if needed).
- `name` (`str`) (default: `None`) — The name of the point data, also the file stem in a time series. Default: the field's label.
- `**selection` (default: `{}`) — Every dimension but ``t``, ``eta1``, ``eta2``, ``eta3`` and ``component``: an integer is a position, a float the nearest coordinate value. ``t`` is kept unless selected too.

**Returns**

- (`list of str`) — The paths of the written files.

> **See Also**
>
> [`plasma_plots.pyvista_plots.save_vtk()`][plasma_plots.pyvista_plots.save_vtk] : The function behind this method.
> [`ArrayData.grid()`][plasma_plots.accessors.ArrayData.grid] : One time as a PyVista grid, in memory.

**Examples**

```pycon
>>> field.plasma.data.to_vtk("frames")
```

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

### plasma_plots.accessors.ArrayData.trajectories

*method*

```python
def trajectories(max_markers: int = 200) -> xr.Dataset
```

Return the marker-position subset [`ArrayPlots.trajectories()`][plasma_plots.accessors.ArrayPlots.trajectories] would plot.

**Parameters**

- `max_markers` (`int`) (default: `200`) — Draw only the first ``max_markers`` markers. Default: ``200``.

**Returns**

- (`xarray.Dataset`) — The orbits of the first ``max_markers`` markers.

**Raises**

- `ValueError` — If the orbits lack ``x``, ``y`` or ``z``, or a ``marker`` dimension.

> **See Also**
>
> [`ArrayPlots.trajectories()`][plasma_plots.accessors.ArrayPlots.trajectories] : The plot of these markers.

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

### plasma_plots.accessors.ArrayData.vector

*method*

```python
def vector(x: str, y: str, components: tuple[int, int] = (0, 1), stride: int = 1, coordinates: Coordinates = 'logical', **selection) -> xr.DataArray
```

Return the selected, strided vector field [`ArrayPlots.vector()`][plasma_plots.accessors.ArrayPlots.vector] would plot.

**Parameters**

- `x` (`str`) — The dimension along the horizontal axis.
- `y` (`str`) — The dimension along the vertical axis.
- `components` (`(int, int)`) (default: `(0, 1)`) — The positions along ``component_dim`` of the two components drawn. Default: ``(0, 1)``.
- `stride` (`int`) (default: `1`) — Draw every ``stride``-th arrow along ``x`` and ``y``. Default: ``1``.
- `coordinates` (`('logical', 'physical')`) (default: `"logical"`) — Place the arrows at the logical coordinates, or at the attached physical ``X``, ``Y``, ``Z`` (then ``x`` and ``y`` must be two of ``eta1``, ``eta2``, ``eta3``, and the axes have equal scales). Default: ``"logical"``.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and the component dimension, e.g. ``t=-1, eta3=0``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`xarray.DataArray`) — The two selected components over ``x`` and ``y``, every ``stride``-th point.

> **See Also**
>
> [`ArrayPlots.vector()`][plasma_plots.accessors.ArrayPlots.vector] : The plot of these components.
> [`plasma_plots.plotting.prepare_vector()`][plasma_plots.plotting.prepare_vector] : The function that prepares them.

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

### plasma_plots.accessors.ArrayData.view

*method*

```python
def view(x: str | None = None, y: str | None = None, sweep: str = 't', coords: Coordinates = 'logical', plane: Plane = 'XY', **selection) -> xr.DataArray
```

Return every remaining dimension of this array, sweep included.

This data is shared by [`ArrayPlots.panels()`][plasma_plots.accessors.ArrayPlots.panels], ``.viewer()``, ``.animation()`` and
``.frames()``, which each render one frame of exactly this data at a time.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second remaining dimension.
- `sweep` (`str`) (default: `'t'`) — The dimension stepped through by panels, the viewer's slider, animations and exported frames. Default: ``"t"``.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Draw over the logical coordinates, or over the mapped physical coordinates (``X``, ``Y``, ``Z``). Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ', 'X1X2')`) (default: `"XY"`) — The physical plane, with ``coords="physical"``: ``"RZ"`` uses ``R = √(X² + Y²)``, ``"X1X2"`` GVEC's reference coordinates. Default: ``"XY"``.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and ``sweep``: an integer is a position (``-1`` the last), a float the nearest coordinate value. Checked now; a name that is not a dimension raises ``TypeError``.

**Returns**

- (`xarray.DataArray`) — The selection ordered ``(sweep, x, y)``. With ``coords="physical"`` the periodic seam of a cell-centered grid is closed, as in every drawn frame (one more point along a periodic angle).

**Raises**

- `ValueError` — If other dimensions than ``sweep``, ``x`` and ``y`` remain, or the physical
coordinates are missing.

> **See Also**
>
> [`ArrayPlots.view()`][plasma_plots.accessors.ArrayPlots.view] : The configured view of this data, and its options.

**Examples**

```pycon
>>> n.plasma.data.view(coords="physical", plane="XY", eta3=0)
```

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

### plasma_plots.accessors.ArrayData.volume_slices

*method*

```python
def volume_slices(indices: dict[str, int] | None = None, **selection) -> dict[str, xr.DataArray]
```

Return the three orthogonal planes [`ArrayPlots.volume_slices()`][plasma_plots.accessors.ArrayPlots.volume_slices] would plot.

**Parameters**

- `indices` (`dict of str to int`) (default: `None`) — The index at which each dimension is held fixed, e.g. ``{"eta3": 0}``. Default: the middle index of every dimension.
- `**selection` (default: `{}`) — Every dimension but the three of the volume, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`dict of str to xarray.DataArray`) — The three planes.

> **See Also**
>
> [`ArrayPlots.volume_slices()`][plasma_plots.accessors.ArrayPlots.volume_slices] : The plot of these planes.
> [`plasma_plots.plotting.prepare_volume_slices()`][plasma_plots.plotting.prepare_volume_slices] : The function that prepares them.

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

## plasma_plots.accessors.ArrayPlots

*class*

```python
class ArrayPlots(_ArrayAccessor)
```

Bases: `plasma_plots.accessors._ArrayAccessor`

Plots of one array, as ``array.plasma.plot.<kind>(...)``.

Dimensions that are neither displayed nor swept are selected by naming them: an integer is a
position (``t=0`` the first, ``t=-1`` the last), and a float is the nearest coordinate value
(``t=0.35``). Selecting a name that is not a dimension of the array, or a string or bool
value, raises ``TypeError``.

> **See Also**
>
> [`ArrayData`][plasma_plots.accessors.ArrayData] : The data behind each of these plots, without rendering it.
> [`ArrayAnalysis`][plasma_plots.accessors.ArrayAnalysis] : Quantitative diagnostics of the same array.

**Examples**

```pycon
>>> phi.plasma.plot.slice(x="eta1", y="eta2", t=-1)
>>> phi.plasma.plot.lineout(x="eta1", t=-1, eta2=0.5, eta3=0)
```

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

### plasma_plots.accessors.ArrayPlots.against_theory

*method*

```python
def against_theory(theory=None, *, show_error: bool = True, xlabel=None, ylabel=None, title=None, logx: bool = False, logy: bool = False, backend: Backend | None = None)
```

Plot these measured values as points against a ``theory`` function.

The array is 1-D, over a parameter (e.g. the wavenumber); the relative error is shown
too.

**Parameters**

- `theory` (`callable, (x, y) pair or dict`) (default: `None`) — A function of the parameter, an ``(x, y)`` pair, or a dict of labels to these, drawn as lines over the measured range. Complex values (e.g. from [`plasma_plots.theory`][plasma_plots.theory]) are compared by their real part; for growth or damping rates pass ``lambda k: f(k).imag``.
- `show_error` (`bool`) (default: `True`) — Add a second panel with ``(measured - theory) / theory`` against the first theory, for every measured series. A theory given as points is interpolated linearly between them (NaN outside them). Default: ``True``.
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate label of the first measured array.
- `ylabel` (`str`) (default: `None`) — The value axis label. Default: the value label of the first measured array.
- `title` (`str`) (default: `None`) — The title. Default: ``"Measured against theory"``.
- `logx` (`bool`) (default: `False`) — Use a logarithmic parameter axis. Default: ``False``.
- `logy` (`bool`) (default: `False`) — Use a logarithmic value axis. Default: ``False``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes (with ``show_error``, the upper one) and the drawn artists.

> **See Also**
>
> [`plasma_plots.plotting.plot_measured_vs_theory()`][plasma_plots.plotting.plot_measured_vs_theory] : The function behind this method.
> [`ArrayAnalysis.trace_branch()`][plasma_plots.accessors.ArrayAnalysis.trace_branch] : Measured frequencies of a dispersion branch, to plot here.

**Examples**

```pycon
>>> traced = spectrum.plasma.analysis.trace_branch(
...     bohm_gross, k_range=(1.5, 5.5)
... )
>>> traced.omega.plasma.plot.against_theory(bohm_gross)
```

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

### plasma_plots.accessors.ArrayPlots.along_field_lines

*method*

```python
def along_field_lines(lines: xr.Dataset, *, k_parallel: bool = False, method: str = 'fft', max_lines: int = 12, ax=None, title: str | None = None, backend: Backend | None = None, **selection)
```

Plot this scalar field along traced field lines, one curve per line.

**Parameters**

- `lines` (`xarray.Dataset`) — The lines of [`ArrayAnalysis.field_lines()`][plasma_plots.accessors.ArrayAnalysis.field_lines].
- `k_parallel` (`bool`) (default: `False`) — Estimate each line's parallel wavenumber (see [`parallel_wavenumber()`][plasma_plots.fieldlines.parallel_wavenumber]) and put it in the legend. Default: False.
- `method` (`('fft', 'crossings')`) (default: `"fft"`) — The estimate's method. Default: ``"fft"``.
- `max_lines` (`int`) (default: `12`) — Draw only the first ``max_lines`` lines. Default: 12.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The title. Default: the samples' label.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — The other dimensions, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the lines; with ``k_parallel``, ``data["k_parallel"]``.

> **See Also**
>
> [`plasma_plots.fieldline_plots.plot_along_field_lines()`][plasma_plots.fieldline_plots.plot_along_field_lines] : The function behind this method.
> [`ArrayAnalysis.sample_along()`][plasma_plots.accessors.ArrayAnalysis.sample_along] : The samples, without plotting them.
> [`ArrayAnalysis.parallel_wavenumber()`][plasma_plots.accessors.ArrayAnalysis.parallel_wavenumber] : The parallel wavenumber alone.

**Examples**

```pycon
>>> phi.plasma.plot.along_field_lines(lines, k_parallel=True, t=-1)
```

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

### plasma_plots.accessors.ArrayPlots.animation

*method*

```python
def animation(x: str | None = None, y: str | None = None, sweep: str = 't', coords: Coordinates = 'logical', plane: Plane = 'XY', vmin=None, vmax=None, shared_clim: bool = True, cmap: str | None = None, equal_aspect: bool | None = None, title: str | None = None, symmetric: bool = False, robust: bool = False, levels=None, fill: bool = True, overlays: dict | None = None, xlabel: str | None = None, ylabel: str | None = None, colorbar_label: str | None = None, interval: int = 100, step: int = 1, max_frames: int | None = None, alongside=None, backend: Backend | None = None, **selection)
```

Animate the sweep; keep a reference to the returned Matplotlib animation.

The same as ``plot.view(...).animation(...)``; see [`view()`][plasma_plots.accessors.ArrayPlots.view] for the shared options.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second remaining dimension.
- `sweep` (`str`) (default: `'t'`) — The dimension stepped through by panels, the viewer's slider, animations and exported frames. Default: ``"t"``.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Draw over the logical coordinates, or over the mapped physical coordinates (``X``, ``Y``, ``Z``). Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ', 'X1X2')`) (default: `"XY"`) — The physical plane, with ``coords="physical"``: ``"RZ"`` uses ``R = √(X² + Y²)``, ``"X1X2"`` GVEC's reference coordinates. Default: ``"XY"``.
- `vmin` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `vmax` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `shared_clim` (`bool`) (default: `True`) — Fix the color limits over all selected data, including frames omitted by a panel layout or export step; ``False`` rescales each frame. Default: ``True``.
- `cmap` (`str`) (default: `None`) — The colormap. Default: the Struphy style's.
- `equal_aspect` (`bool`) (default: `None`) — Equal axis scales. Default: ``True`` for physical coordinates, else ``False``.
- `title` (`str`) (default: `None`) — The title. Default: the array's label.
- `symmetric` (`bool`) (default: `False`) — Center the color limits on zero, for perturbations with a diverging ``cmap``. Default: ``False``.
- `robust` (`bool`) (default: `False`) — Take the color limits from the 1st/99th percentiles, so a few outliers do not wash out the rest. Default: ``False``.
- `levels` (`int or sequence of float`) (default: `None`) — Contour lines of the field on top, e.g. an interface or flux surfaces: a number of evenly spaced levels, or explicit values. Default: none.
- `fill` (`bool`) (default: `True`) — Draw the colored field; with ``False`` only the ``levels`` lines are drawn, colored by ``cmap``. Default: ``True``.
- `overlays` (`dict`) (default: `None`) — Further elements on top: ``contours_of`` (a second field whose contour lines are drawn, e.g. the flux function over the current; with ``contour_levels``, ``contour_color``), ``boundary=True`` (the grid's outline), ``grid_lines=n`` (every n-th grid line), ``lines`` (label to ``(x, y)`` or a function ``y(x)``, e.g. characteristics on a space-time map) and ``points`` (label to ``(x, y)``), in ``line_color`` and ``point_color`` (white by default, for dark colormaps).
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's name and units.
- `ylabel` (`str`) (default: `None`) — The vertical axis label. Default: the coordinate's name and units.
- `colorbar_label` (`str`) (default: `None`) — The color bar label. Default: the array's label and units.
- `interval` (`int`) (default: `100`) — The delay between frames, in milliseconds. Default: 100.
- `step` (`int`) (default: `1`) — Show every ``step``-th element of the sweep. Default: 1.
- `max_frames` (`int`) (default: `None`) — Keep at most this many frames, evenly spaced over those ``step`` leaves (the first and last included), e.g. to keep a Plotly animation small. Default: all.
- `alongside` (`list of xarray.DataArray`) (default: `None`) — Further arrays with the same dimensions (e.g. the density next to the vorticity), animated side by side in sync, each with its own color limits and the same selection and options.
- `backend` (`('matplotlib', 'plotly')`) (default: `"matplotlib"`) — Draw with Matplotlib, or as an interactive Plotly figure with a slider (in ``result.fig``; needs plotly, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and ``sweep``: an integer is a position (``-1`` the last), a float the nearest coordinate value. Checked now; a name that is not a dimension raises ``TypeError``.

**Returns**

- (`matplotlib.animation.FuncAnimation or PlotResult`) — The animation; with ``backend="plotly"`` a result whose Plotly figure has a slider and Play/Pause buttons.

> **See Also**
>
> [`ArrayPlots.view()`][plasma_plots.accessors.ArrayPlots.view] : The configured view this method draws, and its options.
> [`plasma_plots.plotting.animate_slices()`][plasma_plots.plotting.animate_slices] : The function that animates one array.
> [`plasma_plots.plotting.animate_fields()`][plasma_plots.plotting.animate_fields] : The function that animates several side by side.

**Examples**

```pycon
>>> n.plasma.plot.animation(
...     coords="physical", plane="XY", eta3=0, levels=[0.2]
... )
>>> vorticity.plasma.plot.animation(alongside=[density], eta3=0)
```

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

### plasma_plots.accessors.ArrayPlots.boozer_spectrum

*method*

```python
def boozer_spectrum(top: int = 8, helicity=None, log: bool = True, angles: str = 'boozer', x_of=None, xlabel: str | None = None, title: str | None = None, backend: Backend | None = None, **selection)
```

Plot the strongest Boozer harmonics of this ``|B|`` over the radius, and the quasi-symmetry error.

**Parameters**

- `top` (`int`) (default: `8`) — The number of harmonics drawn, strongest first. Default: 8.
- `helicity` (`('QA', 'QP', 'QH')`) (default: `"QA"`) — The symmetry to judge against (see [`quasisymmetry_error()`][plasma_plots.analysis.quasisymmetry_error]). Default: none.
- `log` (`bool`) (default: `True`) — A logarithmic amplitude axis. Default: True.
- `angles` (`('boozer', 'any')`) (default: `"boozer"`) — As for [`boozer_spectrum()`][plasma_plots.analysis.boozer_spectrum].
- `x_of` (`callable`) (default: `None`) — Maps the radial coordinate to the plotted axis, e.g. ``lambda rho: a * rho``.
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's.
- `title` (`str`) (default: `None`) — The title. Default: the harmonics' label.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Other dimensions to select first: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the lines; ``data`` holds the ``amplitudes`` and the ``error``.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_boozer_spectrum()`][plasma_plots.spectral_plots.plot_boozer_spectrum] : The function behind this method.
> [`ArrayAnalysis.boozer_spectrum()`][plasma_plots.accessors.ArrayAnalysis.boozer_spectrum] : The harmonics alone.
> [`ArrayAnalysis.quasisymmetry_error()`][plasma_plots.accessors.ArrayAnalysis.quasisymmetry_error] : The error alone.

**Examples**

```pycon
>>> boozer.mod_B.plasma.plot.boozer_spectrum(top=8, helicity="QA")
```

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

### plasma_plots.accessors.ArrayPlots.compare

*method*

```python
def compare(other: xr.DataArray, *, mode: Literal['difference', 'ratio'] = 'difference', ax=None, backend: Backend | None = None)
```

Plot a one-dimensional aligned difference or ratio against another array.

**Parameters**

- `other` (`xarray.DataArray`) — The array to compare with, e.g. a reference run; aligned with this one first.
- `mode` (`('difference', 'ratio')`) (default: `"difference"`) — ``first - second``, or ``first / second`` (NaN where ``second`` is zero). Default: ``"difference"``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn line.

> **See Also**
>
> [`plasma_plots.plotting.plot_compare()`][plasma_plots.plotting.plot_compare] : The function behind this method.
> [`ArrayData.compare()`][plasma_plots.accessors.ArrayData.compare] : The difference or ratio, without plotting it.

**Examples**

```pycon
>>> field.plasma.plot.compare(reference_field, mode="ratio")
```

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

### plasma_plots.accessors.ArrayPlots.convergence

*method*

```python
def convergence(*others, order: float | None = None, xlabel: str | None = None, title: str = 'Convergence', ax=None, backend: Backend | None = None)
```

Plot these errors against their resolution (or step size) on log-log axes, with the order.

The array is 1-D over the resolution, e.g. an error norm per number of cells; each series
gets its fitted convergence order (or, with ``order``, a reference slope).

**Parameters**

- `*others` (default: `()`) — Further 1-D error arrays, e.g. of other methods or norms, drawn in the same axes.
- `order` (`float`) (default: `None`) — With ``None`` (default), fits and draws the observed order via [`plasma_plots.analysis.convergence_order()`][plasma_plots.analysis.convergence_order]. Pass an explicit ``order`` (e.g. ``2`` for second-order) to draw a reference slope through the first point instead of fitting one.
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's label.
- `title` (`str`) (default: `'Convergence'`) — The axes title. Default: ``"Convergence"``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and, per series, the error line and its fitted or reference line.

**Raises**

- `ValueError` — If an array is not one-dimensional.

> **See Also**
>
> [`plasma_plots.plotting.plot_convergence()`][plasma_plots.plotting.plot_convergence] : The function behind this method.
> [`plasma_plots.analysis.convergence_order()`][plasma_plots.analysis.convergence_order] : The fitted order, without plotting it.

**Examples**

```pycon
>>> errors = xr.DataArray(
...     l2_errors, dims="n", coords={"n": [16, 32, 64, 128]}, name="L2 error"
... )
>>> errors.plasma.plot.convergence(max_errors, backend="plotly")
```

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

### plasma_plots.accessors.ArrayPlots.critical_points

*method*

```python
def critical_points(x: str | None = None, y: str | None = None, coords: Coordinates = 'logical', plane: Plane = 'XY', levels=14, cmap=None, label_values: bool = False, ax=None, backend: Backend | None = None, **selection)
```

Plot the contours of this flux function with its O-points and X-points.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis. Default: the first of the plane.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second of the plane.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Logical coordinates, or the physical ``plane``. Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ')`) (default: `"XY"`) — The physical plane. Default: ``"XY"``.
- `levels` (`int or sequence of float`) (default: `14`) — Contour lines of the flux, as for [`plot_slice()`][plot_slice]. Default: 14.
- `cmap` (`str or matplotlib.colors.Colormap`) (default: `None`) — The colormap. Default: ``"RdBu_r"``.
- `label_values` (`bool`) (default: `False`) — Write the flux value next to each point. Default: False.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — The other dimensions, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes, the mesh, the contours and the scatters; ``data["points"]`` holds the points.

> **See Also**
>
> [`plasma_plots.plotting.plot_critical_points()`][plasma_plots.plotting.plot_critical_points] : The function behind this method.
> [`ArrayAnalysis.critical_points()`][plasma_plots.accessors.ArrayAnalysis.critical_points] : The points alone.
> [`ArrayAnalysis.reconnected_flux()`][plasma_plots.accessors.ArrayAnalysis.reconnected_flux] : The flux between them over time.

**Examples**

```pycon
>>> A = B.plasma.analysis.flux_function()
>>> A.plasma.plot.critical_points(t=-1, eta3=0)
>>> A.plasma.plot.critical_points(coords="physical", t=-1, eta3=0)
```

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

### plasma_plots.accessors.ArrayPlots.cross_spectrum

*method*

```python
def cross_spectrum(other: xr.DataArray, *, dims=None, detrend: bool = True, window=None, omega_max=None, backend: Backend | None = None)
```

Plot the magnitude, coherence and phase of ``other`` relative to this signal.

The coherence is shown only with ``dims``.

**Parameters**

- `other` (`xarray.DataArray`) — The second signal, on the same time grid; its phase is relative to this one.
- `dims` (`str or sequence of str`) (default: `None`) — Dimensions to sum the cross-spectrum over, as an ensemble. Default: none (no ``coherence``).
- `detrend` (`bool`) (default: `True`) — Subtract each signal's temporal mean first. Default: True.
- `window` (`(None, 'hann')`) (default: `None`) — Window applied to both signals before transforming. Default: None.
- `omega_max` (`float`) (default: `None`) — The largest angular frequency shown. Default: all.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists; ``data`` holds ``"peak_omega"`` and ``"peak_phase_deg"``.

> **See Also**
>
> [`plasma_plots.spectral.cross_spectrum()`][plasma_plots.spectral.cross_spectrum] : The function behind this method.
> [`plasma_plots.spectral_plots.plot_cross_spectrum()`][plasma_plots.spectral_plots.plot_cross_spectrum] : The plot of its result.
> [`ArrayAnalysis.cross_spectrum()`][plasma_plots.accessors.ArrayAnalysis.cross_spectrum] : The spectrum, without plotting it.

**Examples**

```pycon
>>> u.plasma.plot.cross_spectrum(b, dims="eta3", omega_max=1.5)
```

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

### plasma_plots.accessors.ArrayPlots.dispersion

*method*

```python
def dispersion(dim: str | None = None, detrend: bool = True, branches: dict | None = None, log: bool = True, dynamic_range: float = 6.0, kmin: float | None = None, kmax: float | None = None, omega_max: float | None = None, vmin: float | None = None, vmax: float | None = None, cmap=None, ax=None, title: str | None = None, frequencies: dict | None = None, points: dict | None = None, fits=(), backend: Backend | None = None)
```

Plot the space-time power spectrum of this ``(t, dim)`` field as a dispersion relation.

``branches`` optionally overlays named theoretical curves (a mapping of label to a
callable ``omega(k)``, or an explicit ``(k, omega)`` pair), to compare against, e.g.
``{"Bohm-Gross": lambda k: np.sqrt(1 + 3 * k**2)}``. ``frequencies`` draws labeled
horizontal lines (cutoffs), ``points`` measured points (``(k, omega)`` pairs or
[`plasma_plots.spectral.trace_branch()`][plasma_plots.spectral.trace_branch] results).

**Parameters**

- `dim` (`str`) (default: `None`) — The spatial dimension to transform. Default: the one besides ``t`` (see [`plasma_plots.analysis.power_spectrum()`][plasma_plots.analysis.power_spectrum]).
- `detrend` (`bool`) (default: `True`) — Remove the time-mean at each point of ``dim`` first, which otherwise dominates the spectrum as a spurious zero-frequency line. Default: ``True``.
- `branches` (`dict or callable`) (default: `None`) — Theoretical curves to compare against, drawn dashed: a dict of labels to a callable ``omega(k)`` or an explicit ``(k, omega)`` pair of arrays; or one callable that returns a dict of branch names to frequencies, such as the dispersion relations of [`plasma_plots.theory`][plasma_plots.theory] or Struphy's ``struphy.dispersion_relations`` objects (a callable in the dict may return such a dict too). Complex frequencies are drawn by their real part.
- `log` (`bool`) (default: `True`) — Color by ``log10`` of the power. Default: ``True``.
- `dynamic_range` (`float`) (default: `6.0`) — With ``log``, the number of decades below the peak that the default color limits cover. Default: ``6.0``.
- `kmin` (`float`) (default: `None`) — Show only ``k >= kmin``, e.g. ``0`` for the positive quadrant. Default: all ``k``.
- `kmax` (`float`) (default: `None`) — Show only ``|k| <= kmax``. Default: all ``k``.
- `omega_max` (`float`) (default: `None`) — Show only ``ω <= omega_max``. Default: all non-negative ``ω``.
- `vmin` (`float`) (default: `None`) — The lower color limit (in ``log10`` of the power with ``log``). Default: the peak minus ``dynamic_range`` with ``log``, else the minimum.
- `vmax` (`float`) (default: `None`) — The upper color limit (in ``log10`` of the power with ``log``). Default: the peak.
- `cmap` (`str or matplotlib.colors.Colormap`) (default: `None`) — The colormap. Default: Matplotlib's default.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The axes title. Default: ``"Dispersion relation of <label>"``.
- `frequencies` (`dict of str to float`) (default: `None`) — Labeled horizontal lines, e.g. cutoffs or resonances.
- `points` (`dict`) (default: `None`) — Measured points to mark: a dict of labels to a ``(k, omega)`` pair or a [`trace_branch()`][plasma_plots.spectral.trace_branch] result (an ``xarray.Dataset`` with ``k`` and ``omega``).
- `fits` (`sequence of BranchFit`) (default: `()`) — Fitted straight branches from [`fit_dispersion_branches()`][plasma_plots.analysis.fit_dispersion_branches], drawn dotted as ``omega = velocity * k`` over the shown ``k >= 0``. Default: none.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists.

> **See Also**
>
> [`plasma_plots.plotting.plot_dispersion()`][plasma_plots.plotting.plot_dispersion] : The function behind this method.
> [`ArrayAnalysis.dispersion()`][plasma_plots.accessors.ArrayAnalysis.dispersion] : Just the spectrum, without plotting it.

**Examples**

```pycon
>>> E.plasma.plot.dispersion(
...     dim="eta1", branches={"Bohm-Gross": lambda k: np.sqrt(1 + 3 * k**2)}
... )
>>> # or pass the spectrum itself
>>> spectrum = E.plasma.analysis.dispersion(dim="eta1")
>>> fits = spectrum.plasma.analysis.fit_branches(n_branches=1)
>>> spectrum.plasma.plot.dispersion(
...     kmin=0, fits=fits, dynamic_range=15, backend="plotly"
... )
```

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

### plasma_plots.accessors.ArrayPlots.filtered

*method*

```python
def filtered(result, *, ax=None, backend: Backend | None = None, **selection)
```

Plot a probe of this signal against a filtered reconstruction.

``result`` is a [`ArrayAnalysis.filter_time()`][plasma_plots.accessors.ArrayAnalysis.filter_time] result or a filtered array; the probe
is selected by keyword.

**Parameters**

- `result` (`TimeFilterResult or xarray.DataArray`) — A [`TimeFilterResult`][plasma_plots.spectral.TimeFilterResult] or a filtered array (e.g. from [`band_filter()`][plasma_plots.spectral.band_filter]) on the grid of ``data``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but ``t``, selected by keyword: an integer is a position (``-1`` the last), a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes, and the raw and the filtered line.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_filtered()`][plasma_plots.spectral_plots.plot_filtered] : The function behind this method.
> [`ArrayAnalysis.filter_time()`][plasma_plots.accessors.ArrayAnalysis.filter_time] : The dominant band, reconstructed.
> [`ArrayAnalysis.band_filter()`][plasma_plots.accessors.ArrayAnalysis.band_filter] : A chosen band, reconstructed.

**Examples**

```pycon
>>> band = phi.plasma.analysis.filter_time(dims=("eta1", "eta2", "eta3"))
>>> phi.plasma.plot.filtered(band, eta1=0.4, eta2=0.0, eta3=0.0)
```

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

### plasma_plots.accessors.ArrayPlots.frames

*method*

```python
def frames(directory, *, x: str | None = None, y: str | None = None, sweep: str = 't', coords: Coordinates = 'logical', plane: Plane = 'XY', vmin=None, vmax=None, shared_clim: bool = True, cmap: str | None = None, equal_aspect: bool | None = None, title: str | None = None, symmetric: bool = False, robust: bool = False, levels=None, fill: bool = True, overlays: dict | None = None, xlabel: str | None = None, ylabel: str | None = None, colorbar_label: str | None = None, step: int = 1, prefix: str = 'frame', dpi: int = 110, **selection)
```

Export the sweep as PNG frames.

Equivalent to ``plot.view(...).save_frames(directory)``; see [`view()`][plasma_plots.accessors.ArrayPlots.view] for the shared
options.

**Parameters**

- `directory` (`str or pathlib.Path`) — The directory to write into; created if needed.
- `x` (`str`) (default: `None`) — The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second remaining dimension.
- `sweep` (`str`) (default: `'t'`) — The dimension stepped through by panels, the viewer's slider, animations and exported frames. Default: ``"t"``.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Draw over the logical coordinates, or over the mapped physical coordinates (``X``, ``Y``, ``Z``). Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ', 'X1X2')`) (default: `"XY"`) — The physical plane, with ``coords="physical"``: ``"RZ"`` uses ``R = √(X² + Y²)``, ``"X1X2"`` GVEC's reference coordinates. Default: ``"XY"``.
- `vmin` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `vmax` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `shared_clim` (`bool`) (default: `True`) — Fix the color limits over all selected data, including frames omitted by a panel layout or export step; ``False`` rescales each frame. Default: ``True``.
- `cmap` (`str`) (default: `None`) — The colormap. Default: the Struphy style's.
- `equal_aspect` (`bool`) (default: `None`) — Equal axis scales. Default: ``True`` for physical coordinates, else ``False``.
- `title` (`str`) (default: `None`) — The title. Default: the array's label.
- `symmetric` (`bool`) (default: `False`) — Center the color limits on zero, for perturbations with a diverging ``cmap``. Default: ``False``.
- `robust` (`bool`) (default: `False`) — Take the color limits from the 1st/99th percentiles, so a few outliers do not wash out the rest. Default: ``False``.
- `levels` (`int or sequence of float`) (default: `None`) — Contour lines of the field on top, e.g. an interface or flux surfaces: a number of evenly spaced levels, or explicit values. Default: none.
- `fill` (`bool`) (default: `True`) — Draw the colored field; with ``False`` only the ``levels`` lines are drawn, colored by ``cmap``. Default: ``True``.
- `overlays` (`dict`) (default: `None`) — Further elements on top: ``contours_of`` (a second field whose contour lines are drawn, e.g. the flux function over the current; with ``contour_levels``, ``contour_color``), ``boundary=True`` (the grid's outline), ``grid_lines=n`` (every n-th grid line), ``lines`` (label to ``(x, y)`` or a function ``y(x)``, e.g. characteristics on a space-time map) and ``points`` (label to ``(x, y)``), in ``line_color`` and ``point_color`` (white by default, for dark colormaps).
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's name and units.
- `ylabel` (`str`) (default: `None`) — The vertical axis label. Default: the coordinate's name and units.
- `colorbar_label` (`str`) (default: `None`) — The color bar label. Default: the array's label and units.
- `step` (`int`) (default: `1`) — Export every ``step``-th element of the sweep. Default: 1.
- `prefix` (`str`) (default: `'frame'`) — The file names are ``<prefix>_0000.png``, ``<prefix>_0001.png``, ... Default: ``"frame"``.
- `dpi` (`int`) (default: `110`) — The resolution of the images. Default: 110.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and ``sweep``: an integer is a position (``-1`` the last), a float the nearest coordinate value. Checked now; a name that is not a dimension raises ``TypeError``.

**Returns**

- (`list of str`) — The paths of the written files.

> **See Also**
>
> [`ArrayPlots.view()`][plasma_plots.accessors.ArrayPlots.view] : The configured view this method draws, and its options.
> [`plasma_plots.plotting.save_frames()`][plasma_plots.plotting.save_frames] : The function that writes the frames.

**Examples**

```pycon
>>> phi.plasma.plot.frames("frames", x="eta1", y="eta2", eta3=0, step=5)
```

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

### plasma_plots.accessors.ArrayPlots.glyphs

*method*

```python
def glyphs(components: Literal['cartesian', 'contravariant'] = 'cartesian', stride: int = 2, scale: float | None = None, cmap='viridis', show_domain: bool = True, title: str | None = None, plotter=None, **selection)
```

Draw PyVista arrows of this ``(component, eta1, eta2, eta3)`` vector field.

The arrows are colored by magnitude.

**Parameters**

- `components` (`('cartesian', 'contravariant')`) (default: `"cartesian"`) — How to read the components: Cartesian x/y/z, or contravariant logical components, pushed forward. Default: ``"cartesian"``.
- `stride` (`int`) (default: `2`) — Draw an arrow at every ``stride``-th point in every direction. Default: 2.
- `scale` (`float`) (default: `None`) — Arrow length of the largest vector, in physical units. Default: a tenth of the domain size.
- `cmap` (`str or matplotlib colormap`) (default: `'viridis'`) — The colormap of the magnitude. Default: ``"viridis"``.
- `show_domain` (`bool`) (default: `True`) — Draw the domain's outer surface translucently for context. Default: ``True``.
- `title` (`str`) (default: `None`) — Text in the scene's corner. Default: the field's label; ``""`` for none.
- `plotter` (`pyvista.Plotter`) (default: `None`) — Draw into this scene instead of a new one, to combine several views. The camera is only aimed at the field when this function creates the plotter.
- `**selection` (default: `{}`) — Every dimension but ``component``, ``eta1``, ``eta2``, ``eta3``, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`pyvista.Plotter`) — The plotter with the arrows, not yet shown.

> **See Also**
>
> [`plasma_plots.pyvista_plots.pyvista_glyphs()`][plasma_plots.pyvista_plots.pyvista_glyphs] : The function behind this method.
> [`ArrayPlots.streamlines()`][plasma_plots.accessors.ArrayPlots.streamlines] : Field lines of the same field.

**Examples**

```pycon
>>> B.plasma.plot.glyphs(stride=3, t=-1).show()
```

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

### plasma_plots.accessors.ArrayPlots.isosurface

*method*

```python
def isosurface(values=5, cmap='viridis', opacity: float = 1.0, clim=None, show_domain: bool = True, title: str | None = None, symmetric: bool = False, robust: bool = False, plotter=None, **selection)
```

Draw PyVista contour surfaces of this scalar field in physical space.

For a 2-D field, contour lines over the colored plane instead.

**Parameters**

- `values` (`int or list of float`) (default: `5`) — The number of evenly spaced levels strictly between the color limits, or explicit levels. Default: 5.
- `cmap` (`str or matplotlib colormap`) (default: `'viridis'`) — The colormap. Default: ``"viridis"``.
- `opacity` (`float`) (default: `1.0`) — Opacity of the surfaces (of the plane for a 2-D field). Default: 1.
- `clim` (`(float, float)`) (default: `None`) — Color limits; default from the field's values, see ``symmetric`` and ``robust``.
- `show_domain` (`bool`) (default: `True`) — Draw the domain's outer surface translucently for context (3-D fields only). Default: ``True``.
- `title` (`str`) (default: `None`) — Text in the scene's corner. Default: the field's label; ``""`` for none.
- `symmetric` (`bool`) (default: `False`) — Color limits symmetric about zero. Default: ``False``.
- `robust` (`bool`) (default: `False`) — Color limits from percentiles instead of the extremes, so outliers don't wash out the colors. Default: ``False``.
- `plotter` (`pyvista.Plotter`) (default: `None`) — Draw into this scene instead of a new one, to combine several views. The camera is only aimed at the field when this function creates the plotter.
- `**selection` (default: `{}`) — Every dimension but ``eta1``, ``eta2``, ``eta3``, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`pyvista.Plotter`) — The plotter with the surfaces, not yet shown.

> **See Also**
>
> [`plasma_plots.pyvista_plots.pyvista_isosurface()`][plasma_plots.pyvista_plots.pyvista_isosurface] : The function behind this method.
> [`ArrayPlots.slices_3d()`][plasma_plots.accessors.ArrayPlots.slices_3d] : Surfaces of constant logical coordinate instead.

**Examples**

```pycon
>>> phi.plasma.plot.isosurface(values=[-0.5, 0.5], cmap="RdBu_r", t=0).show()
```

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

### plasma_plots.accessors.ArrayPlots.line_animation

*method*

```python
def line_animation(x: str | None = None, sweep: str = 't', reference=None, x_of=None, xlabel: str | None = None, ylim=None, step: int = 1, max_frames: int | None = None, interval: int = 100, title: str | None = None, alongside=None, alongside_logy: bool = False, backend: Backend | None = None, **selection)
```

Animate a one-dimensional profile over ``sweep``.

Optionally with the exact profile of each frame (``reference=lambda x, t: ...``). Keep a
reference to the returned animation, or it stops.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis. Default: the one besides ``sweep``.
- `sweep` (`str`) (default: `'t'`) — The dimension to animate over. Default: ``"t"``.
- `reference` (`callable, (x, y) pair or dict`) (default: `None`) — The exact profile of each frame, drawn dashed in black: a function of the plotted ``x`` and of the sweep value (``lambda x, t: ...``; a function of ``x`` alone is fixed), an ``(x, y)`` pair, a 1-D ``xarray.DataArray`` (drawn over its own coordinate), or a dict of labels to these.
- `x_of` (`callable`) (default: `None`) — Maps the ``x`` coordinate to the plotted axis, e.g. ``lambda eta1: L * eta1``.
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's label, or ``"x"`` with ``x_of``.
- `ylim` (`(float, float)`) (default: `None`) — The fixed value axis limits. Default: the range of the data and references, padded by 5 %.
- `step` (`int`) (default: `1`) — Use every ``step``-th value of the sweep. Default: ``1``.
- `max_frames` (`int`) (default: `None`) — Keep at most this many frames, evenly spaced over those ``step`` leaves (the first and last included), e.g. to keep a Plotly animation small. Default: all.
- `interval` (`int`) (default: `100`) — The delay between frames, in milliseconds. Default: ``100``.
- `title` (`str`) (default: `None`) — The title, followed in each frame by the sweep value. Default: the array's label.
- `alongside` (`sequence`) (default: `None`) — One panel below the profile per item, in sync with it: an array over ``sweep`` and one other dimension (another profile, animated, e.g. the density next to the velocity), or an array over ``sweep`` alone, or a list of those (time series such as energies, drawn whole with a marker at each frame's value of the sweep, nearest where the times differ). Default: none.
- `alongside_logy` (`bool`) (default: `False`) — Logarithmic value axes for the time-series panels. Default: ``False``.
- `backend` (`('matplotlib', 'plotly')`) (default: `"matplotlib"`) — Draw with Matplotlib, or as an interactive Plotly figure with a slider (in ``result.fig``; needs plotly, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but ``x`` and ``sweep``: an integer is a position (``eta2=0``), a float the nearest coordinate value.

**Returns**

- (`matplotlib.animation.FuncAnimation or PlotResult`) — The animation, one frame per step along ``sweep``; with ``backend="plotly"`` a result whose Plotly figure has a slider and Play/Pause buttons.

> **See Also**
>
> [`plasma_plots.plotting.animate_lines()`][plasma_plots.plotting.animate_lines] : The function behind this method.
> [`ArrayPlots.lineout()`][plasma_plots.accessors.ArrayPlots.lineout] : One frame, as a static plot.

**Examples**

```pycon
>>> T.plasma.plot.line_animation(reference={"exact": exact}, step=2)
>>> u.plasma.plot.line_animation(
...     x="eta1",
...     alongside=[n, [en_U, en_B]],
...     alongside_logy=True,
...     eta2=0,
...     eta3=0,
... )
```

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

### plasma_plots.accessors.ArrayPlots.lineout

*method*

```python
def lineout(x: str | None = None, ax=None, title: str | None = None, reference=None, x_of=None, xlabel: str | None = None, rationals: int | None = None, nfp: int | None = None, backend: Backend | None = None, **selection)
```

Plot a one-dimensional profile after selecting every other dimension.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension to keep. Default: the only one left after ``selection``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The axes title. Default: the array's label.
- `reference` (`callable, array, (x, y) pair or dict`) (default: `None`) — Exact or expected profiles, drawn dashed: a function of the plotted ``x`` (or of ``x`` and ``t``, taking the profile's time), a 1-D ``xarray.DataArray`` (drawn over its own coordinate), an ``(x, y)`` pair, or a dict of labels to these.
- `x_of` (`callable`) (default: `None`) — Maps the coordinate to the plotted axis, e.g. ``lambda eta1: L * eta1``.
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's label.
- `rationals` (`int`) (default: `None`) — Mark where a rotational transform (or safety factor) profile takes its ``rationals`` lowest-order rational values ``n/m``: a dotted line at each value, labeled, and a point at each crossing (see [`plasma_plots.analysis.rational_surfaces()`][plasma_plots.analysis.rational_surfaces]). Default: none.
- `nfp` (`int`) (default: `None`) — With ``rationals``: the numerators ``n`` are multiples of it. Default: the profile's ``nfp`` attribute, else 1.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — The other dimensions: an integer is a position (``t=-1`` the last), a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn lines.

> **See Also**
>
> [`plasma_plots.plotting.plot_lineout()`][plasma_plots.plotting.plot_lineout] : The function behind this method.
> [`ArrayData.lineout()`][plasma_plots.accessors.ArrayData.lineout] : The selected profile, without plotting it.

**Examples**

```pycon
>>> phi.plasma.plot.lineout(x="eta1", t=-1, eta2=0.5, eta3=0)
>>> T.plasma.plot.lineout(
...     x="eta1", t=-1, reference=exact, x_of=lambda eta1: L * eta1
... )
>>> # GVEC's ι(ρ) and its rational surfaces
>>> ev.iota.plasma.plot.lineout(rationals=4)
```

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

### plasma_plots.accessors.ArrayPlots.mode_amplitudes

*method*

```python
def mode_amplitudes(dims=None, names=('m', 'n'), top: int = 6, fit=None, reduce: str = 'max', scale=None, relative: bool = False, logy: bool = True, ax=None, backend: Backend | None = None, **selection)
```

Plot the amplitude of the strongest ``(m, n)`` modes of this field over time.

Each mode is reduced over the remaining dimensions (e.g. radius) by ``reduce``, with
optional growth fits (``fit=(t0, t1)`` or ``True``).

**Parameters**

- `dims` (`sequence of str`) (default: `None`) — The periodic dimensions to decompose. Default: the two logical angles, ``("eta2", "eta3")`` or GVEC's (see [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum]).
- `names` (`sequence of str`) (default: `('m', 'n')`) — The names of the mode numbers along ``dims``. Default: ``("m", "n")``.
- `top` (`int`) (default: `6`) — The number of modes drawn, those with the largest peak amplitude. Default: 6.
- `fit` (`(float, float) or bool`) (default: `None`) — Fit an exponential growth rate γ to each mode: a time window ``(t0, t1)``, or ``True`` for the whole record. Default: no fit.
- `reduce` (`('max', 'mean')`) (default: `"max"`) — How each mode is reduced over the remaining dimensions. Default: ``"max"``.
- `scale` (`int or sequence of int`) (default: `None`) — Multiplies the mode numbers, e.g. ``(1, 6)`` for full-torus ``n`` of a sixth of a torus. Default: 1, or nfp along GVEC's toroidal angle (see [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum]).
- `relative` (`bool`) (default: `False`) — Show each mode relative to the mean (the zero mode). Default: ``False``.
- `logy` (`bool`) (default: `True`) — Logarithmic amplitude axis. Default: True.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Dimensions other than ``t`` to select first: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes, the drawn lines, the fits in ``fit_results`` and the plotted ``data["amplitudes"]``.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_mode_amplitudes()`][plasma_plots.spectral_plots.plot_mode_amplitudes] : The function behind this method.
> [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum] : The decomposition into modes.
> [`plasma_plots.spectral.mode_amplitudes()`][plasma_plots.spectral.mode_amplitudes] : Real amplitudes of the modes.

**Examples**

```pycon
>>> phi.plasma.plot.mode_amplitudes(top=2, fit=(100, 500))
```

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

### plasma_plots.accessors.ArrayPlots.mode_map

*method*

```python
def mode_map(dims=None, m_range=None, n_range=None, reduce: str = 'max', scale=None, log: bool = True, ax=None, backend: Backend | None = None, **selection)
```

Plot ``|amplitude|`` over the ``(m, n)`` plane at one time.

The time is selected by keyword (e.g. ``t=-1``); the amplitude is reduced over the
remaining dimensions by ``reduce``.

**Parameters**

- `dims` (`sequence of str`) (default: `None`) — The two periodic dimensions to decompose. Default: the two logical angles, ``("eta2", "eta3")`` or GVEC's (see [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum]).
- `m_range` (`(int, int)`) (default: `None`) — The range of ``m`` shown, both ends included. Default: all.
- `n_range` (`(int, int)`) (default: `None`) — The range of ``n`` shown, both ends included. Default: all.
- `reduce` (`('max', 'mean')`) (default: `"max"`) — How the amplitude is reduced over the remaining dimensions. Default: ``"max"``.
- `scale` (`int or sequence of int`) (default: `None`) — Multiplies the mode numbers, e.g. ``(1, 6)`` for full-torus ``n`` of a sixth of a torus. Default: 1, or nfp along GVEC's toroidal angle (see [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum]).
- `log` (`bool`) (default: `True`) — Color by ``log10(|amplitude|)``, clipped at 4 decades below the maximum. Default: True.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — The time and any other dimensions to select first, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes, the mesh and the plotted ``data["amplitude"]``.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_mode_map()`][plasma_plots.spectral_plots.plot_mode_map] : The function behind this method.
> [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum] : The decomposition into modes.

**Examples**

```pycon
>>> phi.plasma.plot.mode_map(t=-1, m_range=(0, 16))
```

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

### plasma_plots.accessors.ArrayPlots.mode_profiles

*method*

```python
def mode_profiles(omega: float | None = None, *, x: str | None = None, dims=None, x_of=None, xlabel: str | None = None, top: int = 4, phase: bool = True, scale=None, backend: Backend | None = None, **selection)
```

Plot the radial profile of each ``(m, n)`` harmonic of this field.

**Parameters**

- `omega` (`float`) (default: `None`) — A frequency: the eigenfunction at that frequency (amplitude and phase), ``mode_spectrum(mode_structure(field, omega))``. Default: the harmonics' amplitudes at one time, which is then selected by keyword (e.g. ``t=-1``).
- `x` (`str`) (default: `None`) — The radial dimension. Default: the radial logical one (``eta1``, or GVEC's ``rho``).
- `dims` (`sequence of str`) (default: `None`) — The periodic dimensions to decompose. Default: the two logical angles, ``("eta2", "eta3")`` or GVEC's (see [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum]).
- `x_of` (`callable`) (default: `None`) — Maps the ``x`` coordinate to the plotted axis, e.g. ``lambda eta1: 0.1 + 0.9 * eta1``. The axis is then labeled ``r``.
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's label, or ``r`` with ``x_of``.
- `top` (`int`) (default: `4`) — The number of strongest harmonics drawn; ``(m, n)`` and ``(-m, -n)`` count as one (the stronger is drawn, labeled by the half whose first nonzero number is positive). Default: 4.
- `phase` (`bool`) (default: `True`) — Add the phase panel (only for complex ``structure``). Default: True.
- `scale` (`int or sequence of int`) (default: `None`) — Multiplies the mode numbers, e.g. ``(1, 6)`` for full-torus ``n`` of a sixth of a torus. Default: 1, or nfp along GVEC's toroidal angle (see [`plasma_plots.spectral.mode_spectrum()`][plasma_plots.spectral.mode_spectrum]).
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Dimensions to select first (without ``omega``, the time): an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes, the drawn lines and the plotted ``data["profiles"]``.

**Raises**

- `ValueError` — Without ``omega``, if ``t`` is not selected.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_mode_profiles()`][plasma_plots.spectral_plots.plot_mode_profiles] : The function behind this method.
> [`ArrayAnalysis.mode_structure()`][plasma_plots.accessors.ArrayAnalysis.mode_structure] : The complex amplitude at one frequency.
> [`ArrayAnalysis.mode_spectrum()`][plasma_plots.accessors.ArrayAnalysis.mode_spectrum] : The decomposition into modes.

**Examples**

```pycon
>>> phi.plasma.plot.mode_profiles(
...     omega, x_of=lambda eta1: 0.1 + 0.9 * eta1, top=2
... )
>>> phi.plasma.plot.mode_profiles(t=-1, scale=(1, 6))
```

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

### plasma_plots.accessors.ArrayPlots.movie

*method*

```python
def movie(path, *, kind: Literal['isosurface', 'slices', 'glyphs', 'streamlines'] = 'slices', step: int = 1, framerate: int = 10, clim=None, **options)
```

Render one PyVista 3-D view per time step into a GIF or video.

Every dimension but ``t`` and the spatial (and ``component``) dimensions must already be
selected.

**Parameters**

- `path` (`str or pathlib.Path`) — The output file: a GIF for ``.gif``, a video (e.g. ``.mp4``) for any other suffix.
- `kind` (`('isosurface', 'slices', 'glyphs', 'streamlines')`) (default: `"isosurface"`) — The view of each frame. Default: ``"slices"``.
- `step` (`int`) (default: `1`) — Use every ``step``-th position of ``sweep``. Default: 1.
- `framerate` (`int`) (default: `10`) — Frames per second. Default: 10.
- `clim` (`(float, float)`) (default: `None`) — Color limits of the scalar views (``"isosurface"``, ``"slices"``). Default: from the whole sweep, with the ``symmetric`` and ``robust`` options.
- `**options` (default: `{}`) — Options of the chosen view, e.g. ``cuts=`` for ``kind="slices"`` (see [`slices_3d()`][plasma_plots.accessors.ArrayPlots.slices_3d], [`isosurface()`][plasma_plots.accessors.ArrayPlots.isosurface], [`glyphs()`][plasma_plots.accessors.ArrayPlots.glyphs], [`streamlines()`][plasma_plots.accessors.ArrayPlots.streamlines]).

**Returns**

- (`str`) — The path of the written file.

> **See Also**
>
> [`plasma_plots.pyvista_plots.save_movie()`][plasma_plots.pyvista_plots.save_movie] : The function behind this method.

**Examples**

```pycon
>>> phi.plasma.plot.movie(
...     "mode.gif",
...     kind="slices",
...     cuts={"eta3": [0, 0.25, 0.5, 0.75]},
...     cmap="RdBu_r",
... )
```

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

### plasma_plots.accessors.ArrayPlots.overlay_orbits

*method*

```python
def overlay_orbits(orbits: xr.Dataset, *, x: str, y: str, max_markers: int = 200, ax=None, cmap=None, backend: Backend | None = None, **selection)
```

Plot this field's slice with marker orbit paths from ``orbits`` overlaid.

A Poincare-style diagnostic for checking particle confinement or orbit topology against a
background field.

**Parameters**

- `orbits` (`xarray.Dataset`) — An orbits product with position variables named after ``view.x`` and ``view.y`` (e.g. its logical coordinates, to overlay directly on a logical-coordinates slice).
- `x` (`str`) — The horizontal dimension of the slice. ``orbits`` must have a position variable of the same name (e.g. logical ``eta1``, to overlay directly on a logical-coordinates slice of this field).
- `y` (`str`) — The vertical dimension of the slice; ``orbits`` needs a variable of this name too.
- `max_markers` (`int`) (default: `200`) — Draw only the first ``max_markers`` markers. Default: ``200``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `cmap` (`str or matplotlib.colors.Colormap`) (default: `None`) — The colormap of the field. Default: ``"viridis"``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every other dimension of this field, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes, the slice's mesh and one line per orbit.

> **See Also**
>
> [`plasma_plots.plotting.plot_field_with_orbits()`][plasma_plots.plotting.plot_field_with_orbits] : The function behind this method.
> [`ArrayData.overlay_orbits()`][plasma_plots.accessors.ArrayData.overlay_orbits] : The slice and orbits, without plotting them.

**Examples**

```pycon
>>> phi.plasma.plot.overlay_orbits(orbits, x="eta1", y="eta2", t=-1, eta3=0)
```

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

### plasma_plots.accessors.ArrayPlots.panels

*method*

```python
def panels(x: str | None = None, y: str | None = None, sweep: str = 't', coords: Coordinates = 'logical', plane: Plane = 'XY', vmin=None, vmax=None, shared_clim: bool = True, cmap: str | None = None, equal_aspect: bool | None = None, title: str | None = None, symmetric: bool = False, robust: bool = False, levels=None, fill: bool = True, overlays: dict | None = None, xlabel: str | None = None, ylabel: str | None = None, colorbar_label: str | None = None, nrows: int = 3, ncols: int = 4, backend: Backend | None = None, **selection)
```

Render evenly spaced snapshots along the sweep.

The same as ``plot.view(...).panels(nrows=nrows, ncols=ncols)``; see [`view()`][plasma_plots.accessors.ArrayPlots.view] for the
shared options.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second remaining dimension.
- `sweep` (`str`) (default: `'t'`) — The dimension stepped through by panels, the viewer's slider, animations and exported frames. Default: ``"t"``.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Draw over the logical coordinates, or over the mapped physical coordinates (``X``, ``Y``, ``Z``). Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ', 'X1X2')`) (default: `"XY"`) — The physical plane, with ``coords="physical"``: ``"RZ"`` uses ``R = √(X² + Y²)``, ``"X1X2"`` GVEC's reference coordinates. Default: ``"XY"``.
- `vmin` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `vmax` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `shared_clim` (`bool`) (default: `True`) — Fix the color limits over all selected data, including frames omitted by a panel layout or export step; ``False`` rescales each frame. Default: ``True``.
- `cmap` (`str`) (default: `None`) — The colormap. Default: the Struphy style's.
- `equal_aspect` (`bool`) (default: `None`) — Equal axis scales. Default: ``True`` for physical coordinates, else ``False``.
- `title` (`str`) (default: `None`) — The title. Default: the array's label.
- `symmetric` (`bool`) (default: `False`) — Center the color limits on zero, for perturbations with a diverging ``cmap``. Default: ``False``.
- `robust` (`bool`) (default: `False`) — Take the color limits from the 1st/99th percentiles, so a few outliers do not wash out the rest. Default: ``False``.
- `levels` (`int or sequence of float`) (default: `None`) — Contour lines of the field on top, e.g. an interface or flux surfaces: a number of evenly spaced levels, or explicit values. Default: none.
- `fill` (`bool`) (default: `True`) — Draw the colored field; with ``False`` only the ``levels`` lines are drawn, colored by ``cmap``. Default: ``True``.
- `overlays` (`dict`) (default: `None`) — Further elements on top: ``contours_of`` (a second field whose contour lines are drawn, e.g. the flux function over the current; with ``contour_levels``, ``contour_color``), ``boundary=True`` (the grid's outline), ``grid_lines=n`` (every n-th grid line), ``lines`` (label to ``(x, y)`` or a function ``y(x)``, e.g. characteristics on a space-time map) and ``points`` (label to ``(x, y)``), in ``line_color`` and ``point_color`` (white by default, for dark colormaps).
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's name and units.
- `ylabel` (`str`) (default: `None`) — The vertical axis label. Default: the coordinate's name and units.
- `colorbar_label` (`str`) (default: `None`) — The color bar label. Default: the array's label and units.
- `nrows` (`int`) (default: `3`) — The number of panel rows. Default: 3.
- `ncols` (`int`) (default: `4`) — The number of panel columns. Default: 4.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and ``sweep``: an integer is a position (``-1`` the last), a float the nearest coordinate value. Checked now; a name that is not a dimension raises ``TypeError``.

**Returns**

- (`PlotResult`) — The figure, the array of axes and the drawn meshes.

> **See Also**
>
> [`ArrayPlots.view()`][plasma_plots.accessors.ArrayPlots.view] : The configured view this method draws, and its options.
> [`plasma_plots.plotting.plot_panels()`][plasma_plots.plotting.plot_panels] : The function that draws the panels.

**Examples**

```pycon
>>> phi.plasma.plot.panels(x="eta1", y="eta2", nrows=2, ncols=3, eta3=0)
```

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

### plasma_plots.accessors.ArrayPlots.pencil_fit

*method*

```python
def pencil_fit(n_modes: int = 1, pencil: int | None = None, detrend: bool = False, backend: Backend | None = None, **selection)
```

Plot a matrix-pencil fit of this ``(t,)`` series.

The samples against the fit, and the modes in the complex-frequency plane.

**Parameters**

- `n_modes` (`int`) (default: `1`) — The number of modes to fit and return: real oscillations for a real signal, complex exponentials for a complex one. The fit needs well over ``2 * n_modes`` samples. Default: 1.
- `pencil` (`int`) (default: `None`) — The pencil parameter (Hankel matrix width minus one), which trades noise robustness against resolution. Default: ``N // 2``.
- `detrend` (`bool`) (default: `False`) — Subtract the mean first. Default: False.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but ``t``, e.g. a probe point: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists; ``data`` holds the ``"fit"`` and the reconstructed ``"model"``.

> **See Also**
>
> [`plasma_plots.spectral.matrix_pencil()`][plasma_plots.spectral.matrix_pencil] : The function behind this method.
> [`plasma_plots.spectral_plots.plot_pencil_fit()`][plasma_plots.spectral_plots.plot_pencil_fit] : The plot of its result.
> [`ArrayAnalysis.matrix_pencil()`][plasma_plots.accessors.ArrayAnalysis.matrix_pencil] : The fit, without plotting it.

**Examples**

```pycon
>>> probe.plasma.plot.pencil_fit(n_modes=1)
```

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

### plasma_plots.accessors.ArrayPlots.poincare

*method*

```python
def poincare(seeds=8, turns: float | None = None, section: float | None = None, coords: str = 'physical', color_by: str | None = 'line', islands: bool = False, boundary: xr.DataArray | None = None, ax=None, backend: Backend | None = None, **selection)
```

Trace field lines of this vector field and plot their Poincaré section.

A convenience for [`ArrayAnalysis.field_lines()`][plasma_plots.accessors.ArrayAnalysis.field_lines] followed by
[`DatasetPlots.poincare()`][plasma_plots.accessors.DatasetPlots.poincare]; keep the traced lines (``result.data["lines"]``) to
plot them again, cut another plane or sample a field along them.

**Parameters**

- `seeds` (`(int, dict, array_like or xarray.Dataset)`) (default: `8`) — Where the lines start; see [`plasma_plots.fieldlines.trace_field_lines()`][plasma_plots.fieldlines.trace_field_lines]. Default: 8 along the radius.
- `turns` (`float`) (default: `None`) — How many toroidal transits to trace. Default: 20.
- `section` (`float`) (default: `None`) — The toroidal logical coordinate of the plane. Default: the first grid value.
- `coords` (`('physical', 'logical')`) (default: `"physical"`) — Draw ``R`` against ``z`` (physical), or the poloidal angle against the radial logical coordinate (logical). Default: ``"physical"``.
- `color_by` (`('line', 'iota', 'classification', 'connection_length', None)`) (default: `"line"`) — One color per line (cycling), a color bar over each line's rotational transform or connection length, or the classes of [`classify_field_lines()`][plasma_plots.fieldlines.classify_field_lines] (surface, island, chaotic) with a legend; ``None`` for one color. Default: ``"line"``.
- `islands` (`bool`) (default: `False`) — Label the island chains with their ``n/m`` and widths. Default: False.
- `boundary` (`xarray.DataArray`) (default: `None`) — A field with physical coordinates whose outermost surface is drawn at the section (physical coordinates only).
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — The other dimensions, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the scatters; ``data["lines"]`` holds the traced lines, ``data["section"]`` the punctures.

> **See Also**
>
> [`plasma_plots.fieldline_plots.plot_poincare()`][plasma_plots.fieldline_plots.plot_poincare] : The function behind this method.
> [`ArrayAnalysis.field_lines()`][plasma_plots.accessors.ArrayAnalysis.field_lines] : The traced lines, to keep.
> [`ArrayData.poincare()`][plasma_plots.accessors.ArrayData.poincare] : The punctures, without plotting them.

**Examples**

```pycon
>>> B.plasma.plot.poincare(seeds=12, turns=100, t=-1)
>>> B.plasma.plot.poincare(color_by="classification", islands=True, t=-1)
```

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

### plasma_plots.accessors.ArrayPlots.power_spectrum

*method*

```python
def power_spectrum(dims=None, detrend: bool = True, window: str | None = None, peaks: int | None = None, band=None, frequencies: dict | None = None, logy: bool = True, omega_max: float | None = None, ax=None, title: str | None = None, backend: Backend | None = None, **selection)
```

Plot the power per frequency bin, averaged over ``dims``.

``dims`` defaults to all but ``component``; optional peak labels, a shaded filter
``band`` and reference ``frequencies``.

**Parameters**

- `dims` (`str or sequence of str`) (default: `None`) — Dimensions to average the power over. At most one other dimension may remain, which gives one line per coordinate value. Default: every dimension but ``omega`` and ``component``.
- `detrend` (`bool`) (default: `True`) — Subtract the signal's mean before transforming. Default: True.
- `window` (`(None, 'hann')`) (default: `None`) — Window applied before transforming a signal. Default: None.
- `peaks` (`int`) (default: `None`) — Mark and label this many of the strongest peaks of a single line, with sub-bin frequencies (see [`spectral_peaks()`][plasma_plots.spectral.spectral_peaks]). Default: none.
- `band` (`(TimeFilterResult, xarray.Dataset or (float, float))`) (default: `None`) — A frequency band to shade: a [`filter_time()`][plasma_plots.spectral.filter_time] result or its ``spectrum`` (with one band selected), or an ``(omega_lo, omega_hi)`` pair.
- `frequencies` (`dict`) (default: `None`) — Named reference frequencies drawn as vertical dotted lines, e.g. ``{"gap": 0.8}`` for a continuum-gap estimate.
- `logy` (`bool`) (default: `True`) — Logarithmic power axis. Default: True.
- `omega_max` (`float`) (default: `None`) — The highest frequency shown. Default: all.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The axes title. Default: the power's label.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Dimensions other than ``t`` to select first (e.g. a probe point ``eta1=0.4``): an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists; ``data`` holds the averaged ``"power"`` and the found ``"peaks"``.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_power_spectrum()`][plasma_plots.spectral_plots.plot_power_spectrum] : The function behind this method.
> [`ArrayAnalysis.time_fft()`][plasma_plots.accessors.ArrayAnalysis.time_fft] : The spectrum, without plotting it.
> [`ArrayAnalysis.spectral_peaks()`][plasma_plots.accessors.ArrayAnalysis.spectral_peaks] : The peaks, without plotting them.

**Examples**

```pycon
>>> band = phi.plasma.analysis.filter_time(dims=("eta1", "eta2", "eta3"))
>>> phi.plasma.plot.power_spectrum(
...     peaks=2, band=band, frequencies={"TAE gap": omega_tae}
... )
```

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

### plasma_plots.accessors.ArrayPlots.profiles

*method*

```python
def profiles(x: str | None = None, over: str = 't', at=None, x_of=None, xlabel: str | None = None, ax=None, title: str | None = None, reference=None, backend: Backend | None = None, **selection)
```

Plot profiles along ``x`` at several values of ``over`` in one axes.

By default four times. ``x_of`` maps ``x`` to the plotted axis (e.g. the minor radius);
``reference`` overlays the exact profiles (``lambda x, t: ...``).

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis. Default: the radial logical one (``eta1``, or GVEC's ``rho``).
- `over` (`str`) (default: `'t'`) — The dimension to draw one profile per value of. Default: ``"t"``.
- `at` (`int, float or sequence of these`) (default: `None`) — The values of ``over``: integers are positions, floats nearest values. Default: four evenly spaced positions.
- `x_of` (`callable`) (default: `None`) — Maps the ``x`` coordinate to the plotted axis, e.g. ``lambda eta1: 0.1 + 0.9 * eta1`` for the minor radius of a hollow torus.
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's label, or ``"r"`` with ``x_of``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The axes title. Default: the array's label.
- `reference` (`callable, array, (x, y) pair or dict`) (default: `None`) — Exact or expected profiles, drawn in each profile's color in dashed styles: a function of the plotted ``x`` (or of ``x`` and the value of ``over``), a 1-D ``xarray.DataArray`` (drawn over its own coordinate), an ``(x, y)`` pair, or a dict of labels to these.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every other dimension, e.g. ``eta2=0.125, eta3=0``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn lines.

> **See Also**
>
> [`plasma_plots.plotting.plot_profiles()`][plasma_plots.plotting.plot_profiles] : The function behind this method.
> [`ArrayPlots.lineout()`][plasma_plots.accessors.ArrayPlots.lineout] : A single profile.

**Examples**

```pycon
>>> T.plasma.plot.profiles(
...     x="eta1", at=[0, 10, 20, 40], reference={"exact": exact}
... )
```

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

### plasma_plots.accessors.ArrayPlots.radial_power

*method*

```python
def radial_power(x: str | None = None, x_of=None, xlabel: str | None = None, continuum=None, detrend: bool = True, window: str | None = None, log: bool = True, dynamic_range: float = 3.0, omega_max: float | None = None, ax=None, backend: Backend | None = None, **selection)
```

Plot the time-power over ``(omega, x)``, averaged over the other dimensions.

The other dimensions are e.g. the angles; optional continuous spectra are drawn on top.

**Parameters**

- `x` (`str`) (default: `None`) — The spatial dimension. Default: the radial logical one (``eta1``, or GVEC's ``rho``).
- `x_of` (`callable`) (default: `None`) — Maps the ``x`` coordinate to the plotted axis, e.g. ``lambda eta1: 0.1 + 0.9 * eta1`` for the minor radius of a hollow torus. The axis is then labeled ``r``.
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's label, or ``r`` with ``x_of``.
- `continuum` (`tuple or xarray.DataArray`) (default: `None`) — Continuous spectra overlaid as curves: a ``(spectrum, modes)`` pair as for [`plot_continuous_spectrum()`][plasma_plots.plotting.plot_continuous_spectrum], evaluated on the plotted axis, or a ``(mode, branch, x)`` array from [`prepare_continuous_spectrum()`][plasma_plots.plotting.prepare_continuous_spectrum].
- `detrend` (`bool`) (default: `True`) — Subtract the temporal mean first. Default: ``True``.
- `window` (`(None, 'hann')`) (default: `None`) — The taper of the time FFT. Default: ``None`` (boxcar).
- `log` (`bool`) (default: `True`) — Color by ``log10(power)``, clipped at ``dynamic_range`` decades below the maximum. Default: True.
- `dynamic_range` (`float`) (default: `3.0`) — With ``log``, the number of decades shown. Default: 3.0.
- `omega_max` (`float`) (default: `None`) — The highest frequency shown. Default: all.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Dimensions to select first: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes, the drawn artists and the plotted ``data["power"]``.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_radial_power()`][plasma_plots.spectral_plots.plot_radial_power] : The function behind this method.
> [`plasma_plots.spectral.time_fft()`][plasma_plots.spectral.time_fft] : The transform it plots the power of.

**Examples**

```pycon
>>> phi.plasma.plot.radial_power(
...     x_of=lambda eta1: 0.1 + 0.9 * eta1, omega_max=0.5
... )
```

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

### plasma_plots.accessors.ArrayPlots.slice

*method*

```python
def slice(x: str | None = None, y: str | None = None, sweep: str = 't', coords: Coordinates = 'logical', plane: Plane = 'XY', vmin=None, vmax=None, shared_clim: bool = True, cmap: str | None = None, equal_aspect: bool | None = None, title: str | None = None, symmetric: bool = False, robust: bool = False, levels=None, fill: bool = True, overlays: dict | None = None, xlabel: str | None = None, ylabel: str | None = None, colorbar_label: str | None = None, ax=None, backend: Backend | None = None, **selection)
```

Render one 2-D slice.

The same as ``plot.view(...).slice(ax=ax)``; see [`view()`][plasma_plots.accessors.ArrayPlots.view] for the shared options.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second remaining dimension.
- `sweep` (`str`) (default: `'t'`) — The dimension stepped through by panels, the viewer's slider, animations and exported frames. Default: ``"t"``.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Draw over the logical coordinates, or over the mapped physical coordinates (``X``, ``Y``, ``Z``). Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ', 'X1X2')`) (default: `"XY"`) — The physical plane, with ``coords="physical"``: ``"RZ"`` uses ``R = √(X² + Y²)``, ``"X1X2"`` GVEC's reference coordinates. Default: ``"XY"``.
- `vmin` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `vmax` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `shared_clim` (`bool`) (default: `True`) — Fix the color limits over all selected data, including frames omitted by a panel layout or export step; ``False`` rescales each frame. Default: ``True``.
- `cmap` (`str`) (default: `None`) — The colormap. Default: the Struphy style's.
- `equal_aspect` (`bool`) (default: `None`) — Equal axis scales. Default: ``True`` for physical coordinates, else ``False``.
- `title` (`str`) (default: `None`) — The title. Default: the array's label.
- `symmetric` (`bool`) (default: `False`) — Center the color limits on zero, for perturbations with a diverging ``cmap``. Default: ``False``.
- `robust` (`bool`) (default: `False`) — Take the color limits from the 1st/99th percentiles, so a few outliers do not wash out the rest. Default: ``False``.
- `levels` (`int or sequence of float`) (default: `None`) — Contour lines of the field on top, e.g. an interface or flux surfaces: a number of evenly spaced levels, or explicit values. Default: none.
- `fill` (`bool`) (default: `True`) — Draw the colored field; with ``False`` only the ``levels`` lines are drawn, colored by ``cmap``. Default: ``True``.
- `overlays` (`dict`) (default: `None`) — Further elements on top: ``contours_of`` (a second field whose contour lines are drawn, e.g. the flux function over the current; with ``contour_levels``, ``contour_color``), ``boundary=True`` (the grid's outline), ``grid_lines=n`` (every n-th grid line), ``lines`` (label to ``(x, y)`` or a function ``y(x)``, e.g. characteristics on a space-time map) and ``points`` (label to ``(x, y)``), in ``line_color`` and ``point_color`` (white by default, for dark colormaps).
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's name and units.
- `ylabel` (`str`) (default: `None`) — The vertical axis label. Default: the coordinate's name and units.
- `colorbar_label` (`str`) (default: `None`) — The color bar label. Default: the array's label and units.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and ``sweep``: an integer is a position (``-1`` the last), a float the nearest coordinate value. Checked now; a name that is not a dimension raises ``TypeError``.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn mesh.

> **See Also**
>
> [`ArrayPlots.view()`][plasma_plots.accessors.ArrayPlots.view] : The configured view this method draws, and its options.
> [`plasma_plots.plotting.plot_slice()`][plasma_plots.plotting.plot_slice] : The function that draws the slice.
> [`ArrayData.slice()`][plasma_plots.accessors.ArrayData.slice] : The selected slice, without plotting it.

**Examples**

```pycon
>>> phi.plasma.plot.slice(x="eta1", y="eta2", t=-1)
>>> n.plasma.plot.slice(
...     coords="physical", plane="XY", t=-1, eta3=0, levels=[0.2]
... )
```

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

### plasma_plots.accessors.ArrayPlots.slices_3d

*method*

```python
def slices_3d(cuts: dict | None = None, cmap='viridis', clim=None, show_domain: bool = True, title: str | None = None, symmetric: bool = False, robust: bool = False, plotter=None, **selection)
```

Draw PyVista surfaces of constant logical coordinate in physical space.

E.g. ``cuts={"eta3": [0, 0.25]}`` for poloidal cross-sections, ``cuts={"eta1": 0.8}`` for
one flux surface. A 2-D field is shown as its whole plane by default.

**Parameters**

- `cuts` (`dict`) (default: `None`) — ``{dim: position or list of positions}`` along ``eta1``, ``eta2``, ``eta3``: a float is the nearest logical coordinate, an integer a grid index (``-1`` the last). Default: the middle of every dimension, or the whole plane of a 2-D field.
- `cmap` (`str or matplotlib colormap`) (default: `'viridis'`) — The colormap. Default: ``"viridis"``.
- `clim` (`(float, float)`) (default: `None`) — Color limits, shared by every cut; default from the whole field's values, see ``symmetric`` and ``robust``.
- `show_domain` (`bool`) (default: `True`) — Draw the domain's outer surface translucently for context. Not drawn when the whole plane of a 2-D field is shown. Default: ``True``.
- `title` (`str`) (default: `None`) — Text in the scene's corner. Default: the field's label; ``""`` for none.
- `symmetric` (`bool`) (default: `False`) — Color limits symmetric about zero. Default: ``False``.
- `robust` (`bool`) (default: `False`) — Color limits from percentiles instead of the extremes, so outliers don't wash out the colors. Default: ``False``.
- `plotter` (`pyvista.Plotter`) (default: `None`) — Draw into this scene instead of a new one, to combine several views. The camera is only aimed at the field when this function creates the plotter.
- `**selection` (default: `{}`) — Every dimension but ``eta1``, ``eta2``, ``eta3``, e.g. ``t=0``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`pyvista.Plotter`) — The plotter with the cuts, not yet shown.

> **See Also**
>
> [`plasma_plots.pyvista_plots.pyvista_slices()`][plasma_plots.pyvista_plots.pyvista_slices] : The function behind this method.
> [`ArrayData.slices_3d()`][plasma_plots.accessors.ArrayData.slices_3d] : The cuts, without drawing them.

**Examples**

```pycon
>>> phi.plasma.plot.slices_3d(
...     cuts={"eta3": [0, 0.25, 0.5, 0.75]}, cmap="RdBu_r", t=0
... ).show()
```

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

### plasma_plots.accessors.ArrayPlots.spectrogram

*method*

```python
def spectrogram(length, step=None, detrend: bool = True, window: str | None = 'hann', log: bool = True, dynamic_range: float = 4.0, omega_max: float | None = None, frequencies: dict | None = None, ax=None, backend: Backend | None = None, **selection)
```

Plot short-time power spectra over ``(t, omega)``.

Any dimensions that remain after ``selection`` are averaged.

**Parameters**

- `length` (`int or float`) — The window length: a number of samples (integer) or a time span (float).
- `step` (`int or float`) (default: `None`) — The shift between windows, in the same forms. Default: a quarter of ``length``.
- `detrend` (`bool`) (default: `True`) — Subtract each window's mean first. Default: ``True``.
- `window` (`('hann', None)`) (default: `"hann"`) — The taper of each window. Default: ``"hann"``.
- `log` (`bool`) (default: `True`) — Color by ``log10(power)``. Default: True.
- `dynamic_range` (`float`) (default: `4.0`) — With ``log``, the number of decades the colors span below the maximum. Default: 4.0.
- `omega_max` (`float`) (default: `None`) — The highest frequency shown. Default: all.
- `frequencies` (`dict`) (default: `None`) — Named reference frequencies drawn as horizontal dotted lines.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Dimensions other than ``t`` to select first: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists; ``data["spectrogram"]`` is the power.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_spectrogram()`][plasma_plots.spectral_plots.plot_spectrogram] : The function behind this method.
> [`plasma_plots.spectral.spectrogram()`][plasma_plots.spectral.spectrogram] : The spectra it plots.
> [`ArrayAnalysis.spectrogram()`][plasma_plots.accessors.ArrayAnalysis.spectrogram] : The spectra, without plotting them.

**Examples**

```pycon
>>> signal.plasma.plot.spectrogram(length=200.0, step=10.0, omega_max=0.45)
```

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

### plasma_plots.accessors.ArrayPlots.streamlines

*method*

```python
def streamlines(components: Literal['cartesian', 'contravariant'] = 'cartesian', n_points: int = 100, source_radius: float | None = None, source_center=None, max_length: float | None = None, tube_radius: float | None = None, cmap='viridis', show_domain: bool = True, title: str | None = None, plotter=None, **selection)
```

Draw PyVista field lines of this vector field, e.g. magnetic field lines.

**Parameters**

- `components` (`('cartesian', 'contravariant')`) (default: `"cartesian"`) — How to read the components: Cartesian x/y/z, or contravariant logical components, pushed forward by [`push_forward()`][push_forward]. Default: ``"cartesian"``.
- `n_points` (`int`) (default: `100`) — The number of seed points (at most the number of grid points when seeding on the grid). Default: 100.
- `source_radius` (`float`) (default: `None`) — Seed in a sphere of this radius instead of at grid points. Default (when ``source_center`` is given): a quarter of the domain size.
- `source_center` (`(float, float, float)`) (default: `None`) — Seed in a sphere around this physical point instead of at grid points. Default (when ``source_radius`` is given): the bounding-box center.
- `max_length` (`float`) (default: `None`) — Maximum length of each line. Default: four times the domain size.
- `tube_radius` (`float`) (default: `None`) — Draw the lines as tubes of this radius. Default: plain lines.
- `cmap` (`str or matplotlib colormap`) (default: `'viridis'`) — The colormap of the magnitude. Default: ``"viridis"``.
- `show_domain` (`bool`) (default: `True`) — Draw the domain's outer surface translucently for context. Default: ``True``.
- `title` (`str`) (default: `None`) — Text in the scene's corner. Default: ``"<label> field lines"``; ``""`` for none.
- `plotter` (`pyvista.Plotter`) (default: `None`) — Draw into this scene instead of a new one, to combine several views. The camera is only aimed at the field when this function creates the plotter.
- `**selection` (default: `{}`) — Every dimension but ``component``, ``eta1``, ``eta2``, ``eta3``, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`pyvista.Plotter`) — The plotter with the field lines, not yet shown.

> **See Also**
>
> [`plasma_plots.pyvista_plots.pyvista_streamlines()`][plasma_plots.pyvista_plots.pyvista_streamlines] : The function behind this method.
> [`ArrayPlots.glyphs()`][plasma_plots.accessors.ArrayPlots.glyphs] : Arrows of the same field.

**Examples**

```pycon
>>> B.plasma.plot.streamlines(
...     n_points=60, source_center=(3.5, 0, 0), t=-1
... ).show()
```

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

### plasma_plots.accessors.ArrayPlots.surface_map

*method*

```python
def surface_map(x: str | None = None, y: str | None = None, iota=None, lines: xr.Dataset | None = None, count: int = 6, start: float = 0.0, turns: float | None = 2.0, line_color: str = 'w', ax=None, backend: Backend | None = None, **options)
```

Plot this quantity on one flux surface, unfolded over the angles, with field lines.

Select the surface and the time by keyword, e.g. ``rho=0.5`` or ``eta1=0.5, t=-1``.
Field lines are straight lines of slope ι in straight-field-line angles (Boozer, PEST),
or traced lines ([`ArrayAnalysis.field_lines()`][plasma_plots.accessors.ArrayAnalysis.field_lines]) on any grid.

**Parameters**

- `x` (`str`) (default: `None`) — The toroidal angle. Default: the toroidal logical dimension.
- `y` (`str`) (default: `None`) — The poloidal angle. Default: the poloidal logical dimension.
- `iota` (`float or xarray.DataArray`) (default: `None`) — The rotational transform of the surface, or its profile over the radial coordinate, at whose value in ``data``'s coordinates it is interpolated. Draws ``count`` straight field lines. Default: none.
- `lines` (`xarray.Dataset`) (default: `None`) — Traced lines ([`trace_field_lines()`][plasma_plots.fieldlines.trace_field_lines]), drawn over the angles as they are, every line in the Dataset. Default: none.
- `count` (`int`) (default: `6`) — The number of straight lines, equally spaced in the poloidal angle. Default: 6.
- `start` (`float`) (default: `0.0`) — The poloidal angle of the first straight line at the left edge. Default: 0.
- `turns` (`float`) (default: `2.0`) — How many toroidal transits of each traced line to draw (a long line covers an irrational surface completely); ``None`` for all. Default: 2.
- `line_color` (`str`) (default: `'w'`) — The color of the field lines. Default: white.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**options` (default: `{}`) — The remaining dimensions to select (an integer is a position, a float the nearest value), and the options of [`plasma_plots.plotting.plot_slice()`][plasma_plots.plotting.plot_slice] (``cmap``, ``levels``, ``overlays``, ...).

**Returns**

- (`PlotResult`) — The figure, the axes, the mesh and the lines; ``data["iota"]`` holds the ι drawn.

> **See Also**
>
> [`plasma_plots.fieldline_plots.plot_surface_map()`][plasma_plots.fieldline_plots.plot_surface_map] : The function behind this method.
> [`ArrayPlots.slice()`][plasma_plots.accessors.ArrayPlots.slice] : The surface without field lines.

**Examples**

```pycon
>>> boozer.mod_B.plasma.plot.surface_map(rho=0.5, iota=boozer.iota, count=8)
>>> phi.plasma.plot.surface_map(eta1=0.5, t=-1, lines=lines)
```

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

### plasma_plots.accessors.ArrayPlots.timeseries

*method*

```python
def timeseries(*others, logy: bool = True, fit=None, fit_amplitude: bool = False, title: str | None = None, ax=None, reference=None, backend: Backend | None = None)
```

Plot this time series, and any others given, in one axes.

**Parameters**

- `*others` (default: `()`) — Further arrays with the single dimension ``t``; they may come from other runs and need not share this array's time grid.
- `logy` (`bool`) (default: `True`) — Use a logarithmic value axis. Default: ``True``.
- `fit` (`(float or None, float or None) or bool`) (default: `None`) — Time window ``(t0, t1)`` of an exponential fit per series (``None`` for an open end), or ``True`` for the whole series. Rates are in ``result.fit_results``. Default: no fit.
- `fit_amplitude` (`bool`) (default: `False`) — The series is quadratic in an amplitude (e.g. an energy); fit the amplitude's rate. Default: ``False``.
- `title` (`str`) (default: `None`) — The axes title. Default: the first series' label.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `reference` (`callable, array, (t, values) pair or dict`) (default: `None`) — Exact or expected curves, drawn dashed: a function of ``t``, an array, a ``(t, values)`` pair, or a mapping of labels to these.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes, the drawn lines, and in ``fit_results`` one [`FitResult`][plasma_plots.analysis.FitResult] (or ``None``) per series.

> **See Also**
>
> [`plasma_plots.plotting.plot_timeseries()`][plasma_plots.plotting.plot_timeseries] : The function behind this method.
> [`ArrayData.timeseries()`][plasma_plots.accessors.ArrayData.timeseries] : The validated series, without plotting them.
> [`ArrayAnalysis.growth_rate()`][plasma_plots.accessors.ArrayAnalysis.growth_rate] : The same fit, without plotting it.

**Examples**

```pycon
>>> energy.plasma.plot.timeseries(
...     logy=True, fit=(0.0, 2.0), fit_amplitude=True
... )
>>> energy.plasma.plot.timeseries(other_run_energy)
```

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

### plasma_plots.accessors.ArrayPlots.trajectories

*method*

```python
def trajectories(max_markers: int = 200, show_paths: bool | None = None, ax=None, backend: Backend | None = None)
```

Plot the three-dimensional paths of saved markers, for an orbit product.

**Parameters**

- `max_markers` (`int`) (default: `200`) — Draw only the first ``max_markers`` markers. Default: ``200``.
- `show_paths` (`bool`) (default: `None`) — Draw each marker's path, not only its last position. Default: ``True`` for up to 200 markers.
- `ax` (`mpl_toolkits.mplot3d.Axes3D`) (default: `None`) — A 3-D axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the 3-D axes and the drawn artists.

> **See Also**
>
> [`plasma_plots.plotting.plot_marker_trajectories()`][plasma_plots.plotting.plot_marker_trajectories] : The function behind this method.
> [`ArrayData.trajectories()`][plasma_plots.accessors.ArrayData.trajectories] : The plotted markers, without plotting them.
> [`DatasetPlots.trajectories()`][plasma_plots.accessors.DatasetPlots.trajectories] : The same for an orbits Dataset.

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

### plasma_plots.accessors.ArrayPlots.vector

*method*

```python
def vector(x: str, y: str, components: tuple[int, int] = (0, 1), stride: int = 1, coordinates: Coordinates = 'logical', ax=None, backend: Backend | None = None, **selection)
```

Plot two vector components after selecting time and remaining dimensions.

**Parameters**

- `x` (`str`) — The dimension along the horizontal axis.
- `y` (`str`) — The dimension along the vertical axis.
- `components` (`(int, int)`) (default: `(0, 1)`) — The positions along ``component_dim`` of the two components drawn. Default: ``(0, 1)``.
- `stride` (`int`) (default: `1`) — Draw every ``stride``-th arrow along ``x`` and ``y``. Default: ``1``.
- `coordinates` (`('logical', 'physical')`) (default: `"logical"`) — Place the arrows at the logical coordinates, or at the attached physical ``X``, ``Y``, ``Z`` (then ``x`` and ``y`` must be two of ``eta1``, ``eta2``, ``eta3``, and the axes have equal scales). Default: ``"logical"``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and the component dimension, e.g. ``t=-1, eta3=0``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the quiver.

> **See Also**
>
> [`plasma_plots.plotting.plot_vector()`][plasma_plots.plotting.plot_vector] : The function behind this method.
> [`ArrayData.vector()`][plasma_plots.accessors.ArrayData.vector] : The selected, strided components, without plotting them.

**Examples**

```pycon
>>> E.plasma.plot.vector(x="eta1", y="eta2", t=-1, eta3=0)
```

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

### plasma_plots.accessors.ArrayPlots.view

*method*

```python
def view(x: str | None = None, y: str | None = None, sweep: str = 't', coords: Coordinates = 'logical', plane: Plane = 'XY', vmin=None, vmax=None, shared_clim: bool = True, cmap: str | None = None, equal_aspect: bool | None = None, title: str | None = None, symmetric: bool = False, robust: bool = False, levels=None, fill: bool = True, overlays: dict | None = None, xlabel: str | None = None, ylabel: str | None = None, colorbar_label: str | None = None, **selection) -> 'SliceView'
```

Configure a reusable slice view without rendering a figure.

Use xarray's ``.sel()``/``.isel()`` for general selection, or pass remaining dimensions
here. The options apply to every presentation of the view: [`slice()`][plasma_plots.accessors.ArrayPlots.slice],
[`panels()`][plasma_plots.accessors.ArrayPlots.panels], [`viewer()`][plasma_plots.accessors.ArrayPlots.viewer], [`animation()`][plasma_plots.accessors.ArrayPlots.animation] and [`frames()`][plasma_plots.accessors.ArrayPlots.frames] take the same ones.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second remaining dimension.
- `sweep` (`str`) (default: `'t'`) — The dimension stepped through by panels, the viewer's slider, animations and exported frames. Default: ``"t"``.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Draw over the logical coordinates, or over the mapped physical coordinates (``X``, ``Y``, ``Z``). Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ', 'X1X2')`) (default: `"XY"`) — The physical plane, with ``coords="physical"``: ``"RZ"`` uses ``R = √(X² + Y²)``, ``"X1X2"`` GVEC's reference coordinates. Default: ``"XY"``.
- `vmin` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `vmax` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `shared_clim` (`bool`) (default: `True`) — Fix the color limits over all selected data, including frames omitted by a panel layout or export step; ``False`` rescales each frame. Default: ``True``.
- `cmap` (`str`) (default: `None`) — The colormap. Default: the Struphy style's.
- `equal_aspect` (`bool`) (default: `None`) — Equal axis scales. Default: ``True`` for physical coordinates, else ``False``.
- `title` (`str`) (default: `None`) — The title. Default: the array's label.
- `symmetric` (`bool`) (default: `False`) — Center the color limits on zero, for perturbations with a diverging ``cmap``. Default: ``False``.
- `robust` (`bool`) (default: `False`) — Take the color limits from the 1st/99th percentiles, so a few outliers do not wash out the rest. Default: ``False``.
- `levels` (`int or sequence of float`) (default: `None`) — Contour lines of the field on top, e.g. an interface or flux surfaces: a number of evenly spaced levels, or explicit values. Default: none.
- `fill` (`bool`) (default: `True`) — Draw the colored field; with ``False`` only the ``levels`` lines are drawn, colored by ``cmap``. Default: ``True``.
- `overlays` (`dict`) (default: `None`) — Further elements on top: ``contours_of`` (a second field whose contour lines are drawn, e.g. the flux function over the current; with ``contour_levels``, ``contour_color``), ``boundary=True`` (the grid's outline), ``grid_lines=n`` (every n-th grid line), ``lines`` (label to ``(x, y)`` or a function ``y(x)``, e.g. characteristics on a space-time map) and ``points`` (label to ``(x, y)``), in ``line_color`` and ``point_color`` (white by default, for dark colormaps).
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's name and units.
- `ylabel` (`str`) (default: `None`) — The vertical axis label. Default: the coordinate's name and units.
- `colorbar_label` (`str`) (default: `None`) — The color bar label. Default: the array's label and units.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and ``sweep``: an integer is a position (``-1`` the last), a float the nearest coordinate value. Checked now; a name that is not a dimension raises ``TypeError``.

**Returns**

- (`SliceView`) — The configured view; it creates no figure and does not copy the array.

> **See Also**
>
> [`SliceView`][plasma_plots.accessors.SliceView] : What the configured view can draw.
> [`plasma_plots.plotting.plot_slice()`][plasma_plots.plotting.plot_slice] : The function that draws one slice.
> [`ArrayData.view()`][plasma_plots.accessors.ArrayData.view] : The selected data, sweep included, without plotting it.

**Examples**

```pycon
>>> view = f.plasma.plot.view(x="eta1", y="v1", cmap="RdBu_r")
>>> view.slice(t=-1)
>>> view.panels(nrows=2, ncols=3)
>>> view.save_frames("frames")
```

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

### plasma_plots.accessors.ArrayPlots.viewer

*method*

```python
def viewer(x: str | None = None, y: str | None = None, sweep: str = 't', coords: Coordinates = 'logical', plane: Plane = 'XY', vmin=None, vmax=None, shared_clim: bool = True, cmap: str | None = None, equal_aspect: bool | None = None, title: str | None = None, symmetric: bool = False, robust: bool = False, levels=None, fill: bool = True, overlays: dict | None = None, xlabel: str | None = None, ylabel: str | None = None, colorbar_label: str | None = None, backend: Backend | None = None, **selection)
```

Create an interactive slider view; keep a reference to the returned viewer.

The same as ``plot.view(...).viewer()``; see [`view()`][plasma_plots.accessors.ArrayPlots.view] for the shared options.

**Parameters**

- `x` (`str`) (default: `None`) — The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
- `y` (`str`) (default: `None`) — The dimension along the vertical axis. Default: the second remaining dimension.
- `sweep` (`str`) (default: `'t'`) — The dimension stepped through by panels, the viewer's slider, animations and exported frames. Default: ``"t"``.
- `coords` (`('logical', 'physical')`) (default: `"logical"`) — Draw over the logical coordinates, or over the mapped physical coordinates (``X``, ``Y``, ``Z``). Default: ``"logical"``.
- `plane` (`('XY', 'XZ', 'YZ', 'RZ', 'X1X2')`) (default: `"XY"`) — The physical plane, with ``coords="physical"``: ``"RZ"`` uses ``R = √(X² + Y²)``, ``"X1X2"`` GVEC's reference coordinates. Default: ``"XY"``.
- `vmin` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `vmax` (`float`) (default: `None`) — Explicit color limits; each overrides its limit with or without ``shared_clim``.
- `shared_clim` (`bool`) (default: `True`) — Fix the color limits over all selected data, including frames omitted by a panel layout or export step; ``False`` rescales each frame. Default: ``True``.
- `cmap` (`str`) (default: `None`) — The colormap. Default: the Struphy style's.
- `equal_aspect` (`bool`) (default: `None`) — Equal axis scales. Default: ``True`` for physical coordinates, else ``False``.
- `title` (`str`) (default: `None`) — The title. Default: the array's label.
- `symmetric` (`bool`) (default: `False`) — Center the color limits on zero, for perturbations with a diverging ``cmap``. Default: ``False``.
- `robust` (`bool`) (default: `False`) — Take the color limits from the 1st/99th percentiles, so a few outliers do not wash out the rest. Default: ``False``.
- `levels` (`int or sequence of float`) (default: `None`) — Contour lines of the field on top, e.g. an interface or flux surfaces: a number of evenly spaced levels, or explicit values. Default: none.
- `fill` (`bool`) (default: `True`) — Draw the colored field; with ``False`` only the ``levels`` lines are drawn, colored by ``cmap``. Default: ``True``.
- `overlays` (`dict`) (default: `None`) — Further elements on top: ``contours_of`` (a second field whose contour lines are drawn, e.g. the flux function over the current; with ``contour_levels``, ``contour_color``), ``boundary=True`` (the grid's outline), ``grid_lines=n`` (every n-th grid line), ``lines`` (label to ``(x, y)`` or a function ``y(x)``, e.g. characteristics on a space-time map) and ``points`` (label to ``(x, y)``), in ``line_color`` and ``point_color`` (white by default, for dark colormaps).
- `xlabel` (`str`) (default: `None`) — The horizontal axis label. Default: the coordinate's name and units.
- `ylabel` (`str`) (default: `None`) — The vertical axis label. Default: the coordinate's name and units.
- `colorbar_label` (`str`) (default: `None`) — The color bar label. Default: the array's label and units.
- `backend` (`('matplotlib', 'plotly')`) (default: `"matplotlib"`) — Draw with Matplotlib, or as an interactive Plotly figure with a slider (in ``result.fig``; needs plotly, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but ``x``, ``y`` and ``sweep``: an integer is a position (``-1`` the last), a float the nearest coordinate value. Checked now; a name that is not a dimension raises ``TypeError``.

**Returns**

- (`plasma_plots.plotting.InteractiveSliceViewer or PlotResult`) — The viewer, with sliders for the unselected dimensions; with ``backend="plotly"`` a result whose Plotly figure has one slider (one unselected dimension at most).

> **See Also**
>
> [`ArrayPlots.view()`][plasma_plots.accessors.ArrayPlots.view] : The configured view this method draws, and its options.
> [`plasma_plots.plotting.InteractiveSliceViewer`][plasma_plots.plotting.InteractiveSliceViewer] : The viewer class.

**Examples**

```pycon
>>> viewer = phi.plasma.plot.viewer(x="eta1", y="eta2")
```

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

### plasma_plots.accessors.ArrayPlots.volume

*method*

```python
def volume(name: str | None = None, cmap='viridis', opacity='linear', **selection)
```

Create a PyVista volume plotter for a selected scalar field.

**Parameters**

- `name` (`str`) (default: `None`) — The name of the scalars in the PyVista grid. Default: the array's label, else ``"value"``.
- `cmap` (`str`) (default: `'viridis'`) — The colormap. Default: ``"viridis"``.
- `opacity` (`str or sequence of float`) (default: `'linear'`) — PyVista's opacity transfer function. Default: ``"linear"``.
- `**selection` (default: `{}`) — Every dimension but ``eta1``, ``eta2``, ``eta3``, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`pyvista.Plotter`) — The plotter, not yet shown; call ``plotter.show()``.

> **See Also**
>
> [`plasma_plots.plotting.pyvista_volume()`][plasma_plots.plotting.pyvista_volume] : The function behind this method.
> [`ArrayPlots.isosurface()`][plasma_plots.accessors.ArrayPlots.isosurface] : Contour surfaces instead of a volume rendering.

**Examples**

```pycon
>>> density.plasma.plot.volume(cmap="viridis", opacity="linear", t=-1).show()
```

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

### plasma_plots.accessors.ArrayPlots.volume_slices

*method*

```python
def volume_slices(indices: dict[str, int] | None = None, cmap=None, backend: Backend | None = None, **selection)
```

Render three orthogonal slices of a selected scalar volume.

**Parameters**

- `indices` (`dict of str to int`) (default: `None`) — The index at which each dimension is held fixed, e.g. ``{"eta3": 0}``. Default: the middle index of every dimension.
- `cmap` (`str or matplotlib.colors.Colormap`) (default: `None`) — The colormap. Default: Matplotlib's default.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Every dimension but the three of the volume, e.g. ``t=-1``: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the three axes and the drawn meshes.

> **See Also**
>
> [`plasma_plots.plotting.plot_volume_slices()`][plasma_plots.plotting.plot_volume_slices] : The function behind this method.
> [`ArrayData.volume_slices()`][plasma_plots.accessors.ArrayData.volume_slices] : The three planes, without plotting them.

**Examples**

```pycon
>>> density.plasma.plot.volume_slices(t=-1)
```

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

## plasma_plots.accessors.DatasetAnalysis

*class*

```python
class DatasetAnalysis
```

Quantitative diagnostics of one dataset, as ``dataset.plasma.analysis.<quantity>(...)``.

**Examples**

```pycon
>>> orbits.plasma.analysis.classify_orbits()
```

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

### plasma_plots.accessors.DatasetAnalysis.bounce_period

*method*

```python
def bounce_period(v_par: str = 'v_par') -> xr.DataArray
```

Return the bounce period of each trapped marker.

**Parameters**

- `v_par` (`str`) (default: `'v_par'`) — The name of the parallel-velocity variable. Default: ``"v_par"``.

**Returns**

- (`xarray.DataArray`) — The bounce period over ``marker``.

> **See Also**
>
> [`plasma_plots.analysis.bounce_period()`][plasma_plots.analysis.bounce_period] : The function behind this method.
> [`DatasetAnalysis.classify_orbits()`][plasma_plots.accessors.DatasetAnalysis.classify_orbits] : Which markers are trapped.

**Examples**

```pycon
>>> orbits.plasma.analysis.bounce_period()
```

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

### plasma_plots.accessors.DatasetAnalysis.classify_field_lines

*method*

```python
def classify_field_lines(max_denominator: int = 12, tolerance: float | None = None, threshold: float = 0.1, min_spread: float | None = None) -> xr.DataArray
```

Classify each traced field line: on a flux surface (0), in an island (1) or chaotic (2).

**Parameters**

- `max_denominator` (`int`) (default: `12`) — The largest ``m`` of the rationals considered. Default: 12.
- `tolerance` (`float`) (default: `None`) — How close ι must be to ``n/m``. Default: two over the number of toroidal transits of the line (the resolution of ι from the trace), at least 1e-3.
- `threshold` (`float`) (default: `0.1`) — The median radial jump between punctures that are neighbours in the poloidal angle, relative to the line's radial spread, above which a non-librating line is chaotic (a smooth curve through 100 punctures gives a few hundredths). Default: 0.1.
- `min_spread` (`float`) (default: `None`) — The radial spread of the punctures (in the radial logical coordinate) below which a line is on a surface. Default: half the radial grid spacing of the traced field.

**Returns**

- (`xarray.DataArray`) — The class of each line over ``line``.

> **See Also**
>
> [`plasma_plots.fieldlines.classify_field_lines()`][plasma_plots.fieldlines.classify_field_lines] : The function behind this method.
> [`DatasetAnalysis.islands()`][plasma_plots.accessors.DatasetAnalysis.islands] : The island chains and their widths.

**Examples**

```pycon
>>> lines.plasma.analysis.classify_field_lines()
```

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

### plasma_plots.accessors.DatasetAnalysis.classify_orbits

*method*

```python
def classify_orbits(v_par: str = 'v_par') -> xr.DataArray
```

Classify each marker of this guiding-center orbits product: passing (0), trapped (1) or lost (-1).

See [`plasma_plots.analysis.classify_orbits()`][plasma_plots.analysis.classify_orbits] for the criteria.

**Parameters**

- `v_par` (`str`) (default: `'v_par'`) — The name of the parallel-velocity variable. Default: ``"v_par"``.

**Returns**

- (`xarray.DataArray`) — The class of each marker, over ``marker``.

> **See Also**
>
> [`plasma_plots.analysis.classify_orbits()`][plasma_plots.analysis.classify_orbits] : The function behind this method.
> [`DatasetPlots.orbit_classification()`][plasma_plots.accessors.DatasetPlots.orbit_classification] : The markers in a phase-space plane, colored by class.

**Examples**

```pycon
>>> orbits.plasma.analysis.classify_orbits()
```

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

### plasma_plots.accessors.DatasetAnalysis.footprint

*method*

```python
def footprint() -> xr.Dataset
```

Return where these traced field lines left the grid, with their connection lengths.

**Returns**

- (`xarray.Dataset`) — The exit points over ``line``.

> **See Also**
>
> [`plasma_plots.fieldlines.footprint()`][plasma_plots.fieldlines.footprint] : The function behind this method.
> [`DatasetPlots.footprint()`][plasma_plots.accessors.DatasetPlots.footprint] : The plot.

**Examples**

```pycon
>>> edge.plasma.analysis.footprint()
```

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

### plasma_plots.accessors.DatasetAnalysis.islands

*method*

```python
def islands(max_denominator: int = 12, tolerance: float | None = None, threshold: float = 0.1, min_spread: float | None = None) -> xr.Dataset
```

Return the island chains these traced field lines show, with their widths.

**Parameters**

- `max_denominator` (`int`) (default: `12`) — The largest ``m`` of the rationals considered. Default: 12.
- `tolerance` (`float`) (default: `None`) — How close ι must be to ``n/m``; see [`classify_field_lines()`][plasma_plots.accessors.DatasetAnalysis.classify_field_lines].
- `threshold` (`float`) (default: `0.1`) — The chaos criterion of [`classify_field_lines()`][plasma_plots.accessors.DatasetAnalysis.classify_field_lines]. Default: 0.1.
- `min_spread` (`float`) (default: `None`) — The surface criterion of [`classify_field_lines()`][plasma_plots.accessors.DatasetAnalysis.classify_field_lines]. Default: half the radial grid spacing.

**Returns**

- (`xarray.Dataset`) — Over ``chain``: ``n``, ``m``, ``width``, ``center``, ...

> **See Also**
>
> [`plasma_plots.fieldlines.islands()`][plasma_plots.fieldlines.islands] : The function behind this method.
> [`DatasetPlots.poincare()`][plasma_plots.accessors.DatasetPlots.poincare] : ``islands=True`` labels them.

**Examples**

```pycon
>>> lines.plasma.analysis.islands().to_dataframe()
```

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

### plasma_plots.accessors.DatasetAnalysis.loss_map

*method*

```python
def loss_map(x: str = 'v_par', y: str | None = None, t=0, absB=None) -> xr.Dataset
```

Return each marker's initial phase-space position, whether it is lost, and when.

**Parameters**

- `x` (`str`) (default: `'v_par'`) — The first quantity. Default: ``"v_par"``.
- `y` (`str`) (default: `None`) — The second quantity. Default: ``"mu"``, or ``"v_perp"`` without ``mu``.
- `t` (`int or float`) (default: `0`) — The time of the plotted values: an integer position (default ``0``, the initial one) or a float nearest value.
- `absB` (`callable`) (default: `None`) — ``|B|(x, y, z)``, for ``"energy"`` and ``"pitch"`` (see [`orbit_invariants()`][plasma_plots.accessors.DatasetAnalysis.orbit_invariants]).

**Returns**

- (`xarray.Dataset`) — ``x``, ``y``, ``lost`` and ``loss_time`` over ``marker``.

> **See Also**
>
> [`plasma_plots.analysis.loss_map()`][plasma_plots.analysis.loss_map] : The function behind this method.
> [`DatasetPlots.loss_map()`][plasma_plots.accessors.DatasetPlots.loss_map] : The plot.

**Examples**

```pycon
>>> orbits.plasma.analysis.loss_map(x="energy", y="pitch", absB=absB)
```

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

### plasma_plots.accessors.DatasetAnalysis.lost_fraction

*method*

```python
def lost_fraction(weight: str | None = None) -> xr.DataArray
```

Return the fraction of markers lost from the domain, over time.

**Parameters**

- `weight` (`str`) (default: `None`) — Weigh each marker by its initial value of this variable, e.g. ``"weight"``. Default: count the markers.

**Returns**

- (`xarray.DataArray`) — The fraction over ``t``.

> **See Also**
>
> [`plasma_plots.analysis.lost_fraction()`][plasma_plots.analysis.lost_fraction] : The function behind this method.
> [`DatasetPlots.lost_fraction()`][plasma_plots.accessors.DatasetPlots.lost_fraction] : The plot.

**Examples**

```pycon
>>> orbits.plasma.analysis.lost_fraction(weight="weight")
```

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

### plasma_plots.accessors.DatasetAnalysis.marker_density

*method*

```python
def marker_density(dims=('eta1'), bins=32, weight: str | None = None, ranges=None) -> xr.DataArray
```

Return the markers binned over position variables, per unit volume.

**Parameters**

- `dims` (`str or sequence of str`) (default: `('eta1')`) — The position variables to bin over, e.g. ``("eta1",)`` or ``("x", "y")``. Default: ``("eta1",)``.
- `bins` (`int or sequence of int`) (default: `32`) — The number of bins, for all or for each. Default: 32.
- `weight` (`str`) (default: `None`) — Weigh each marker by this variable, e.g. ``"weight"``. Default: count the markers.
- `ranges` (`dict`) (default: `None`) — ``{variable: (low, high)}`` bin ranges. Default: ``(0, 1)`` for the logical ``eta`` coordinates, the markers' extent otherwise.

**Returns**

- (`xarray.DataArray`) — The density over ``t`` and the binned variables.

> **See Also**
>
> [`plasma_plots.analysis.marker_density()`][plasma_plots.analysis.marker_density] : The function behind this method.
> [`DatasetPlots.marker_density()`][plasma_plots.accessors.DatasetPlots.marker_density] : Sampling against physical density.

**Examples**

```pycon
>>> orbits.plasma.analysis.marker_density(dims="eta1", weight="weight")
```

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

### plasma_plots.accessors.DatasetAnalysis.orbit_invariants

*method*

```python
def orbit_invariants(absB=None) -> xr.Dataset
```

Return the speed, guiding-centre energy and pitch of the saved orbits.

**Parameters**

- `absB` (`callable`) (default: `None`) — ``|B|(x, y, z)`` as a function of the physical positions (numpy arrays), e.g. ``lambda x, y, z: out.equil.absB0(*out.domain.inverse_map(x, y, z))``. Needed for the energy and the pitch.

**Returns**

- (`xarray.Dataset`) — The invariants per marker and time.

> **See Also**
>
> [`plasma_plots.analysis.orbit_invariants()`][plasma_plots.analysis.orbit_invariants] : The function behind this method.

**Examples**

```pycon
>>> orbits.plasma.analysis.orbit_invariants(absB=absB_xyz)
```

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

### plasma_plots.accessors.DatasetAnalysis.poincare_section

*method*

```python
def poincare_section(angle: float | None = None) -> xr.Dataset
```

Return the punctures of a poloidal plane by these traced field lines.

**Parameters**

- `angle` (`float`) (default: `None`) — The toroidal logical coordinate of the plane. Default: the traced section.

**Returns**

- (`xarray.Dataset`) — The punctures over ``(puncture, line)``.

> **See Also**
>
> [`plasma_plots.fieldlines.poincare_section()`][plasma_plots.fieldlines.poincare_section] : The function behind this method.
> [`DatasetPlots.poincare()`][plasma_plots.accessors.DatasetPlots.poincare] : The plot.

**Examples**

```pycon
>>> lines.plasma.analysis.poincare_section(angle=np.pi / 5)
```

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

### plasma_plots.accessors.DatasetAnalysis.rotational_transform

*method*

```python
def rotational_transform() -> xr.DataArray
```

Return the rotational transform of each traced field line.

**Returns**

- (`xarray.DataArray`) — ``iota`` over ``line``.

> **See Also**
>
> [`plasma_plots.fieldlines.rotational_transform()`][plasma_plots.fieldlines.rotational_transform] : The function behind this method.

**Examples**

```pycon
>>> lines.plasma.analysis.rotational_transform()
```

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

### plasma_plots.accessors.DatasetAnalysis.seed_grid

*method*

```python
def seed_grid(name: str = 'connection_length') -> xr.DataArray
```

Return a per-line quantity of these field lines over their grid of seeds.

**Parameters**

- `name` (`str`) (default: `'connection_length'`) — The per-line variable. Default: ``"connection_length"``.

**Returns**

- (`xarray.DataArray`) — ``name`` over the two varying seed coordinates.

> **See Also**
>
> [`plasma_plots.fieldlines.seed_grid()`][plasma_plots.fieldlines.seed_grid] : The function behind this method.
> [`DatasetPlots.connection_length()`][plasma_plots.accessors.DatasetPlots.connection_length] : The plot of the connection lengths.

**Examples**

```pycon
>>> edge.plasma.analysis.seed_grid("connection_length").plasma.plot.slice()
```

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

### plasma_plots.accessors.DatasetAnalysis.surface_average

*method*

```python
def surface_average(name: str, *, jacobian: str | None = 'Jac', domain=None, quadrature=None) -> xr.DataArray
```

Return the flux-surface average of one variable, with this Dataset's Jacobian.

**Parameters**

- `name` (`str`) — The variable, e.g. ``"mod_B"``.
- `jacobian` (`str or None`) (default: `'Jac'`) — The variable holding ``√g``, used if the Dataset has it. ``None`` (or a missing variable) takes ``domain``, else the numerical Jacobian of ``X``, ``Y``, ``Z``. Default: ``"Jac"``, GVEC's.
- `domain` (`struphy domain`) (default: `None`) — The mapping, for the exact ``√g`` of a Struphy run.
- `quadrature` (`dict`) (default: `None`) — Explicit weights for the angles, as for [`volume_integral()`][volume_integral].

**Returns**

- (`xarray.DataArray`) — ``⟨name⟩`` over the radius and every non-spatial dimension.

> **See Also**
>
> [`plasma_plots.analysis.surface_average()`][plasma_plots.analysis.surface_average] : The function behind this method.

**Examples**

```pycon
>>> ev.plasma.analysis.surface_average("mod_B")
```

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

### plasma_plots.accessors.DatasetAnalysis.weight_statistics

*method*

```python
def weight_statistics(weight: str = 'weight') -> xr.Dataset
```

Return the statistics of the marker weights over time, with the noise estimate.

**Parameters**

- `weight` (`str`) (default: `'weight'`) — The weight variable. Default: ``"weight"``, Struphy's.

**Returns**

- (`xarray.Dataset`) — ``mean``, ``std``, ``total``, ``noise``, ``effective_markers``, ... over ``t``.

> **See Also**
>
> [`plasma_plots.analysis.weight_statistics()`][plasma_plots.analysis.weight_statistics] : The function behind this method.
> [`DatasetPlots.weight_histogram()`][plasma_plots.accessors.DatasetPlots.weight_histogram] : The distribution of the weights.

**Examples**

```pycon
>>> orbits.plasma.analysis.weight_statistics().noise.plasma.plot.timeseries()
```

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

## plasma_plots.accessors.DatasetData

*class*

```python
class DatasetData
```

The data behind each plot in [`DatasetPlots`][plasma_plots.accessors.DatasetPlots], without rendering it.

**Examples**

```pycon
>>> markers.plasma.data.scatter(x="x", y="y", t=-1).to_dataframe()
```

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

### plasma_plots.accessors.DatasetData.footprint

*method*

```python
def footprint() -> xr.Dataset
```

Return the exit points [`DatasetPlots.footprint()`][plasma_plots.accessors.DatasetPlots.footprint] would plot.

**Returns**

- (`xarray.Dataset`) — The exit points over ``line``, with the connection lengths.

> **See Also**
>
> [`plasma_plots.fieldlines.footprint()`][plasma_plots.fieldlines.footprint] : The function behind this method.
> [`DatasetPlots.footprint()`][plasma_plots.accessors.DatasetPlots.footprint] : The plot of these points.

**Examples**

```pycon
>>> edge.plasma.data.footprint()
```

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

### plasma_plots.accessors.DatasetData.loss_map

*method*

```python
def loss_map(x: str = 'v_par', y: str | None = None, t=0, absB=None) -> xr.Dataset
```

Return the per-marker values [`DatasetPlots.loss_map()`][plasma_plots.accessors.DatasetPlots.loss_map] would plot.

**Parameters**

- `x` (`str`) (default: `'v_par'`) — The first quantity. Default: ``"v_par"``.
- `y` (`str`) (default: `None`) — The second quantity. Default: ``"mu"``, or ``"v_perp"`` without ``mu``.
- `t` (`int or float`) (default: `0`) — The time of the plotted values: an integer position (default ``0``, the initial one) or a float nearest value.
- `absB` (`callable`) (default: `None`) — ``|B|(x, y, z)``, for ``"energy"`` and ``"pitch"`` (see [`orbit_invariants()`][orbit_invariants]).

**Returns**

- (`xarray.Dataset`) — ``x``, ``y``, ``lost`` and ``loss_time`` over ``marker``.

> **See Also**
>
> [`plasma_plots.analysis.loss_map()`][plasma_plots.analysis.loss_map] : The function behind this method.
> [`DatasetPlots.loss_map()`][plasma_plots.accessors.DatasetPlots.loss_map] : The plot of these values.

**Examples**

```pycon
>>> orbits.plasma.data.loss_map(x="energy", y="pitch", absB=absB)
```

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

### plasma_plots.accessors.DatasetData.orbit_classification

*method*

```python
def orbit_classification(x: str = 'v_par', y: str | None = None, v_par: str = 'v_par', t=0) -> xr.Dataset
```

Return the per-marker ``x``, ``y`` and ``classification`` that orbit_classification plots.

The values [`DatasetPlots.orbit_classification()`][plasma_plots.accessors.DatasetPlots.orbit_classification] would plot.

**Parameters**

- `x` (`str`) (default: `'v_par'`) — The quantity along the horizontal axis. Default: ``"v_par"``.
- `y` (`str`) (default: `None`) — The quantity along the vertical axis. Default: the magnetic moment ``mu`` (Particles5D), or ``v_perp`` if there is no ``mu`` (Particles5Dvperp).
- `v_par` (`str`) (default: `'v_par'`) — The parallel velocity the classification uses. Default: ``"v_par"``.
- `t` (`int or float`) (default: `0`) — The time of the plotted values: an integer position (default ``0``, the initial phase-space position, before any marker is lost; ``-1`` the last), or a float nearest value.

**Returns**

- (`xarray.Dataset`) — ``x``, ``y`` and ``classification`` over ``marker``.

> **See Also**
>
> [`DatasetPlots.orbit_classification()`][plasma_plots.accessors.DatasetPlots.orbit_classification] : The plot of these values.
> [`plasma_plots.plotting.prepare_orbit_classification()`][plasma_plots.plotting.prepare_orbit_classification] : The function that prepares them.

**Examples**

```pycon
>>> orbits.plasma.data.orbit_classification(x="p_phi")
```

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

### plasma_plots.accessors.DatasetData.poincare

*method*

```python
def poincare(angle: float | None = None) -> xr.Dataset
```

Return the punctures [`DatasetPlots.poincare()`][plasma_plots.accessors.DatasetPlots.poincare] would plot.

**Parameters**

- `angle` (`float`) (default: `None`) — The toroidal logical coordinate of the plane. Default: the traced section.

**Returns**

- (`xarray.Dataset`) — The punctures over ``(puncture, line)``.

> **See Also**
>
> [`plasma_plots.fieldlines.poincare_section()`][plasma_plots.fieldlines.poincare_section] : The function behind this method.
> [`DatasetPlots.poincare()`][plasma_plots.accessors.DatasetPlots.poincare] : The plot of these punctures.

**Examples**

```pycon
>>> lines.plasma.data.poincare().to_dataframe()
```

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

### plasma_plots.accessors.DatasetData.scatter

*method*

```python
def scatter(x: str, y: str, color: str | None = None, color_at=None, **selection) -> xr.Dataset
```

Return the per-marker positions and colors [`DatasetPlots.scatter()`][plasma_plots.accessors.DatasetPlots.scatter] would plot.

``.to_dataframe()`` hands them straight to e.g. Plotly Express.

**Parameters**

- `x` (`str`) — The variables for the horizontal and vertical axes.
- `y` (`str`) — The variables for the horizontal and vertical axes.
- `color` (`str`) (default: `None`) — The variable to color by. Default: none.
- `color_at` (`int or float`) (default: `None`) — Take the colors at another time (an integer position such as ``0``, or a float value). Default: at the selected time.
- `**selection` (default: `{}`) — The other dimensions, e.g. ``t``: an integer is a position (``t=-1`` the last), a float the nearest coordinate value.

**Returns**

- (`xarray.Dataset`) — ``x``, ``y`` and ``color`` over ``marker``.

> **See Also**
>
> [`plasma_plots.plotting.prepare_marker_scatter()`][plasma_plots.plotting.prepare_marker_scatter] : The function behind this method.
> [`DatasetPlots.scatter()`][plasma_plots.accessors.DatasetPlots.scatter] : The plot of these markers.

**Examples**

```pycon
>>> markers.plasma.data.scatter(
...     x="x", y="y", color="density", t=-1
... ).to_dataframe()
>>> # colored by the start
>>> markers.plasma.data.scatter(x="x", y="y", color="x", color_at=0, t=-1)
```

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

### plasma_plots.accessors.DatasetData.trajectories

*method*

```python
def trajectories(max_markers: int = 200) -> xr.Dataset
```

Return the marker-position subset [`DatasetPlots.trajectories()`][plasma_plots.accessors.DatasetPlots.trajectories] would plot.

**Parameters**

- `max_markers` (`int`) (default: `200`) — Draw only the first ``max_markers`` markers. Default: ``200``.

**Returns**

- (`xarray.Dataset`) — The orbits of the first ``max_markers`` markers.

**Raises**

- `ValueError` — If the orbits lack ``x``, ``y`` or ``z``, or a ``marker`` dimension.

> **See Also**
>
> [`DatasetPlots.trajectories()`][plasma_plots.accessors.DatasetPlots.trajectories] : The plot of these markers.

**Examples**

```pycon
>>> markers.plasma.data.trajectories(max_markers=50)
```

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

## plasma_plots.accessors.DatasetPlots

*class*

```python
class DatasetPlots
```

Plots of one dataset, as ``dataset.plasma.plot.<kind>(...)``.

Most of them are for an orbits product, with one ``(t, marker)`` variable per saved
quantity; others plot the Dataset results of a spectral analysis.

**Examples**

```pycon
>>> orbits.plasma.plot.trajectories()
>>> orbits.plasma.plot.orbit_classification()
```

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

### plasma_plots.accessors.DatasetPlots.animation

*method*

```python
def animation(x: str, y: str, color: str | None = None, color_at=None, background: xr.DataArray | None = None, background_options: dict | None = None, step: int = 1, max_frames: int | None = None, interval: int = 100, s: int = 8, cmap=None, trail: int | None = None, paths: bool = False, backend: Backend | None = None)
```

Animate the markers moving over time, optionally over a field animated in sync.

E.g. over an SPH density. Keep a reference to the returned animation.

**Parameters**

- `x` (`str`) — The data variable along the horizontal axis, e.g. the position ``"x"``; ``"R"`` is ``√(x² + y²)`` when the data has no ``R`` of its own (with ``y="z"`` the poloidal plane).
- `y` (`str`) — The data variable along the vertical axis, e.g. the position ``"y"``.
- `color` (`str`) (default: `None`) — A variable to color by: per frame, or fixed at the time ``color_at``; or ``"classification"``, the orbit class of each marker (passing, trapped, lost; needs ``v_par``, see [`classify_orbits()`][plasma_plots.analysis.classify_orbits]), with a legend. Default: one color.
- `color_at` (`int or float`) (default: `None`) — Fix the colors at this time (an integer position, e.g. ``0`` for the initial position, to follow fluid parcels, or a float value). Default: the colors of each frame.
- `background` (`xarray.DataArray`) (default: `None`) — A field drawn behind the markers: with a ``t`` dimension (other dimensions selected) at the nearest time of each frame, with shared color limits; without one, fixed (drawn once). On its own ``x``/``y`` dimensions if it has them (a Cartesian field), in logical coordinates if ``x``/``y`` are ``eta1``/``eta2``/``eta3``, else in the physical plane of ``x``/``y`` (the field then needs its ``X``, ``Y``, ``Z`` coordinates).
- `background_options` (`dict`) (default: `None`) — Rendering options for the background, as for [`plot_slice()`][plot_slice] (``cmap``, ``symmetric``, ``levels``, ...).
- `step` (`int`) (default: `1`) — Use every ``step``-th time. Default: ``1``.
- `max_frames` (`int`) (default: `None`) — Keep at most this many frames, evenly spaced over those ``step`` leaves (the first and last included), e.g. to keep a Plotly animation small. Default: all.
- `interval` (`int`) (default: `100`) — The delay between frames, in milliseconds. Default: ``100``.
- `s` (`int`) (default: `8`) — The marker size, in points². Default: ``8``.
- `cmap` (`str or matplotlib.colors.Colormap`) (default: `None`) — The colormap for ``color``. Default: ``"viridis"``.
- `trail` (`int`) (default: `None`) — Draw each marker's last ``trail`` samples as a faint line behind it. Default: none.
- `paths` (`bool`) (default: `False`) — Draw each marker's whole path, fixed and faint, under the animation. Default: ``False``.
- `backend` (`('matplotlib', 'plotly')`) (default: `"matplotlib"`) — Draw with Matplotlib, or as an interactive Plotly figure with a slider (in ``result.fig``; needs plotly, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`matplotlib.animation.FuncAnimation or PlotResult`) — The animation; with ``backend="plotly"`` a result whose Plotly figure has a slider and Play/Pause buttons.

> **See Also**
>
> [`plasma_plots.plotting.animate_markers()`][plasma_plots.plotting.animate_markers] : The function behind this method.
> [`DatasetPlots.scatter()`][plasma_plots.accessors.DatasetPlots.scatter] : One frame, as a static plot.

**Examples**

```pycon
>>> markers.plasma.plot.animation(
...     x="x", y="y", color="density", background=n, step=2
... )
>>> orbits.plasma.plot.animation(
...     x="R",
...     y="z",
...     color="classification",
...     trail=300,
...     paths=True,
...     background=psi,
... )
```

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

### plasma_plots.accessors.DatasetPlots.connection_length

*method*

```python
def connection_length(log: bool = True, cmap=None, s: float = 14.0, ax=None, title: str | None = None, backend: Backend | None = None)
```

Plot the connection length of each field line over its seed.

**Parameters**

- `log` (`bool`) (default: `True`) — Show the decimal logarithm of the connection length. Default: True.
- `cmap` (`str or matplotlib colormap`) (default: `None`) — The colormap. Default: ``"viridis"``.
- `s` (`float`) (default: `14.0`) — The marker size of a scatter, in points². Default: 14.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The title. Default: ``"connection length"``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the mesh or scatter; ``data["connection_length"]``.

> **See Also**
>
> [`plasma_plots.fieldline_plots.plot_connection_length()`][plasma_plots.fieldline_plots.plot_connection_length] : The function behind this method.
> [`DatasetAnalysis.seed_grid()`][plasma_plots.accessors.DatasetAnalysis.seed_grid] : The values over the seed grid.

**Examples**

```pycon
>>> edge.plasma.plot.connection_length()
```

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

### plasma_plots.accessors.DatasetPlots.cross_spectrum

*method*

```python
def cross_spectrum(omega_max: float | None = None, backend: Backend | None = None)
```

Plot the magnitude, coherence and phase of a ``cross_spectrum`` Dataset.

**Parameters**

- `omega_max` (`float`) (default: `None`) — The highest frequency shown. Default: all.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists; ``data`` holds ``"peak_omega"`` and ``"peak_phase_deg"``.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_cross_spectrum()`][plasma_plots.spectral_plots.plot_cross_spectrum] : The function behind this method.
> [`ArrayAnalysis.cross_spectrum()`][plasma_plots.accessors.ArrayAnalysis.cross_spectrum] : The Dataset to plot.

**Examples**

```pycon
>>> u.plasma.analysis.cross_spectrum(
...     b, dims="eta3"
... ).plasma.plot.cross_spectrum(omega_max=1.5)
```

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

### plasma_plots.accessors.DatasetPlots.field_lines

*method*

```python
def field_lines(plane: str = 'RZ', color_by: str | None = 'line', max_lines: int = 200, cmap=None, boundary: xr.DataArray | None = None, ax=None, title: str | None = None, backend: Backend | None = None)
```

Plot these traced field lines projected onto a plane, or in 3-D.

**Parameters**

- `plane` (`('RZ', 'XY', 'XZ', 'YZ', '3d')`) (default: `"RZ"`) — The projection: the poloidal plane ``R``-``z`` (default), a Cartesian plane, or a 3-D axes.
- `color_by` (`('line', 'iota', 'absB', 's', None)`) (default: `"line"`) — One color per line (cycling), each line colored by its rotational transform, or each line colored along its path by ``|B|`` or the arc length ``s`` (with a color bar; 2-D planes only); ``None`` for one color. Default: ``"line"``.
- `max_lines` (`int`) (default: `200`) — Draw only the first ``max_lines`` lines. Default: 200.
- `cmap` (`str or matplotlib colormap`) (default: `None`) — The colormap. Default: ``"viridis"``.
- `boundary` (`xarray.DataArray`) (default: `None`) — A field with physical coordinates whose outermost surface is drawn in the ``RZ`` plane.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into (a 3-D axes for ``plane="3d"``). Default: a new figure.
- `title` (`str`) (default: `None`) — The title. Default: the lines' label.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the lines.

> **See Also**
>
> [`plasma_plots.fieldline_plots.plot_field_lines()`][plasma_plots.fieldline_plots.plot_field_lines] : The function behind this method.
> [`DatasetPlots.poincare()`][plasma_plots.accessors.DatasetPlots.poincare] : Their punctures of a poloidal plane.

**Examples**

```pycon
>>> lines.plasma.plot.field_lines(plane="RZ", color_by="iota")
>>> lines.plasma.plot.field_lines(plane="3d", max_lines=20)
```

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

### plasma_plots.accessors.DatasetPlots.footprint

*method*

```python
def footprint(log: bool = True, s: float = 14.0, cmap=None, ax=None, title: str | None = None, backend: Backend | None = None)
```

Plot where these open field lines leave the grid, colored by connection length.

**Parameters**

- `log` (`bool`) (default: `True`) — Color by the decimal logarithm of the connection length. Default: True.
- `s` (`float`) (default: `14.0`) — The marker size, in points². Default: 14.
- `cmap` (`str or matplotlib colormap`) (default: `None`) — The colormap. Default: ``"viridis"``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The title. Default: how many lines left the grid.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the scatter; ``data["footprint"]`` holds the exit points.

> **See Also**
>
> [`plasma_plots.fieldline_plots.plot_footprint()`][plasma_plots.fieldline_plots.plot_footprint] : The function behind this method.
> [`DatasetData.footprint()`][plasma_plots.accessors.DatasetData.footprint] : The exit points, without plotting them.
> [`DatasetPlots.connection_length()`][plasma_plots.accessors.DatasetPlots.connection_length] : The connection lengths over the seeds.

**Examples**

```pycon
>>> edge.plasma.plot.footprint()
```

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

### plasma_plots.accessors.DatasetPlots.loss_map

*method*

```python
def loss_map(x: str = 'v_par', y: str | None = None, t=0, absB=None, ax=None, s: int = 10, cmap=None, title: str | None = None, backend: Backend | None = None)
```

Plot which markers are lost, over their initial phase-space position, colored by when.

**Parameters**

- `x` (`str`) (default: `'v_par'`) — The quantity along the horizontal axis: a variable, or ``"energy"``, ``"pitch"`` or ``"speed"`` (see [`loss_map()`][plasma_plots.analysis.loss_map]). Default: ``"v_par"``.
- `y` (`str`) (default: `None`) — The vertical one. Default: ``"mu"``, or ``"v_perp"`` without ``mu``.
- `t` (`int or float`) (default: `0`) — The time of the plotted positions: an integer position (default ``0``) or a float nearest value.
- `absB` (`callable`) (default: `None`) — ``|B|(x, y, z)``, for ``"energy"`` and ``"pitch"``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `s` (`int`) (default: `10`) — The marker size, in points². Default: 10.
- `cmap` (`str or matplotlib.colors.Colormap`) (default: `None`) — The colormap of the loss time. Default: ``"plasma"``.
- `title` (`str`) (default: `None`) — The title. Default: how many markers are lost.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the scatters; ``data["losses"]``.

> **See Also**
>
> [`plasma_plots.plotting.plot_loss_map()`][plasma_plots.plotting.plot_loss_map] : The function behind this method.
> [`DatasetData.loss_map()`][plasma_plots.accessors.DatasetData.loss_map] : The values, without plotting them.
> [`DatasetPlots.orbit_classification()`][plasma_plots.accessors.DatasetPlots.orbit_classification] : Passing, trapped and lost markers.

**Examples**

```pycon
>>> orbits.plasma.plot.loss_map(x="energy", y="pitch", absB=absB)
```

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

### plasma_plots.accessors.DatasetPlots.lost_fraction

*method*

```python
def lost_fraction(weight: str | None = None, percent: bool = True, ax=None, title: str | None = None, backend: Backend | None = None)
```

Plot the fraction of markers lost from the domain, against time.

**Parameters**

- `weight` (`str`) (default: `None`) — Weigh each marker by its initial value of this variable, i.e. count particles rather than markers. Default: count markers.
- `percent` (`bool`) (default: `True`) — Show percentages. Default: True.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The title. Default: the final fraction.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the line; ``data["lost_fraction"]``.

> **See Also**
>
> [`plasma_plots.plotting.plot_lost_fraction()`][plasma_plots.plotting.plot_lost_fraction] : The function behind this method.
> [`DatasetAnalysis.lost_fraction()`][plasma_plots.accessors.DatasetAnalysis.lost_fraction] : The fraction alone.

**Examples**

```pycon
>>> orbits.plasma.plot.lost_fraction(weight="weight")
```

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

### plasma_plots.accessors.DatasetPlots.marker_density

*method*

```python
def marker_density(x: str = 'eta1', weight: str | None = 'weight', against: xr.DataArray | None = None, bins: int = 32, normalize: bool = True, ax=None, title: str | None = None, backend: Backend | None = None, **selection)
```

Plot where the markers are against what they represent, along one coordinate.

**Parameters**

- `x` (`str`) (default: `'eta1'`) — The position variable to bin over, e.g. ``"eta1"`` or ``"x"``. Default: ``"eta1"``.
- `weight` (`str`) (default: `'weight'`) — The weight variable, for the weighted density; ``None`` leaves it out. Default: ``"weight"`` (skipped when the Dataset has no such variable).
- `against` (`xarray.DataArray`) (default: `None`) — A reference profile over the same coordinate (every other dimension selected, or with ``t`` matching ``markers``), drawn dashed. Default: none.
- `bins` (`int`) (default: `32`) — The number of bins. Default: 32.
- `normalize` (`bool`) (default: `True`) — Divide each profile by the mean of its magnitude, so that the shapes compare (a δf perturbation sums to nearly nothing, so its plain mean would not do). Default: True.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The title. Default: ``"marker density"``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — The time: ``t=-1`` (default, the last) or a float nearest value.

**Returns**

- (`PlotResult`) — The figure, the axes and the lines; ``data`` holds the densities.

> **See Also**
>
> [`plasma_plots.plotting.plot_marker_density()`][plasma_plots.plotting.plot_marker_density] : The function behind this method.
> [`DatasetAnalysis.marker_density()`][plasma_plots.accessors.DatasetAnalysis.marker_density] : The binned densities.

**Examples**

```pycon
>>> orbits.plasma.plot.marker_density(
...     x="eta1", against=n.isel(eta2=0, eta3=0), t=-1
... )
```

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

### plasma_plots.accessors.DatasetPlots.orbit_classification

*method*

```python
def orbit_classification(x: str = 'v_par', y: str | None = None, v_par: str = 'v_par', t=0, ax=None, s: int = 8, backend: Backend | None = None)
```

Plot markers in a phase-space plane, colored as passing, trapped or lost.

By default initial ``v_par`` against ``mu``; for a guiding-center orbits product.

**Parameters**

- `x` (`str`) (default: `'v_par'`) — The quantity along the horizontal axis. Default: ``"v_par"``.
- `y` (`str`) (default: `None`) — The quantity along the vertical axis. Default: the magnetic moment ``mu`` (Particles5D), or ``v_perp`` if there is no ``mu`` (Particles5Dvperp).
- `v_par` (`str`) (default: `'v_par'`) — The parallel velocity the classification uses. Default: ``"v_par"``.
- `t` (`int or float`) (default: `0`) — The time of the plotted values: an integer position (default ``0``, the initial phase-space position, before any marker is lost; ``-1`` the last), or a float nearest value.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `s` (`int`) (default: `8`) — The marker size, in points². Default: ``8``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists; ``data["counts"]`` holds the number of markers per class.

> **See Also**
>
> [`plasma_plots.plotting.plot_orbit_classification()`][plasma_plots.plotting.plot_orbit_classification] : The function behind this method.
> [`DatasetData.orbit_classification()`][plasma_plots.accessors.DatasetData.orbit_classification] : The plotted values, without plotting them.
> [`DatasetAnalysis.classify_orbits()`][plasma_plots.accessors.DatasetAnalysis.classify_orbits] : The classification alone.

**Examples**

```pycon
>>> orbits.plasma.plot.orbit_classification()
>>> orbits.plasma.plot.orbit_classification(x="p_phi")
```

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

### plasma_plots.accessors.DatasetPlots.orbit_grid

*method*

```python
def orbit_grid(markers=8, ncols: int = 4, boundary: xr.DataArray | None = None, backend: Backend | None = None)
```

Plot one small poloidal panel per marker, colored by orbit class.

**Parameters**

- `markers` (`int or sequence of int`) (default: `8`) — A number of markers (spread over the classes when ``v_par`` is saved) or a list of marker indices. Default: ``8``.
- `ncols` (`int`) (default: `4`) — The number of panels per row. Default: ``4``.
- `boundary` (`xarray.DataArray`) (default: `None`) — A field with physical coordinates whose outer (last ``eta1``) surface is drawn in every panel, at its first ``eta3``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn lines; ``data["markers"]`` holds the plotted markers.

> **See Also**
>
> [`plasma_plots.plotting.plot_orbit_grid()`][plasma_plots.plotting.plot_orbit_grid] : The function behind this method.
> [`DatasetPlots.poloidal()`][plasma_plots.accessors.DatasetPlots.poloidal] : All orbits in one panel.

**Examples**

```pycon
>>> orbits.plasma.plot.orbit_grid(markers=8, ncols=4, boundary=field)
>>> orbits.plasma.plot.orbit_grid(markers=[3, 17, 42])
```

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

### plasma_plots.accessors.DatasetPlots.orbits_3d

*method*

```python
def orbits_3d(color_by: str = 't', max_markers: int = 200, tube_radius: float | None = None, cmap=None, domain: xr.DataArray | None = None, title: str | None = None, plotter=None)
```

Draw PyVista 3-D orbit lines, colored by ``"t"``, ``"classification"`` or any variable.

``domain`` is a field whose boundary is drawn for context.

**Parameters**

- `color_by` (`str`) (default: `'t'`) — ``"t"``, ``"classification"`` (passing, trapped, lost, with a legend) or the name of any ``(t, marker)`` variable, e.g. ``"v_par"``. Default: ``"t"``.
- `max_markers` (`int`) (default: `200`) — At most this many markers are drawn. Default: 200.
- `tube_radius` (`float`) (default: `None`) — Draw the orbits as tubes of this radius. Default: plain lines.
- `cmap` (`str or matplotlib colormap`) (default: `None`) — The colormap (not used for ``"classification"``). Default: ``"viridis"``.
- `domain` (`xarray.DataArray`) (default: `None`) — A field with physical coordinates whose outer surface is drawn translucently; other than ``eta1``, ``eta2``, ``eta3``, its dimensions are taken at their first position.
- `title` (`str`) (default: `None`) — Text in the scene's corner. Default: ``"Marker orbits"``; ``""`` for none.
- `plotter` (`pyvista.Plotter`) (default: `None`) — Draw into this scene instead of a new one, to combine several views.

**Returns**

- (`pyvista.Plotter`) — The plotter with the orbits, not yet shown.

> **See Also**
>
> [`plasma_plots.pyvista_plots.pyvista_orbits()`][plasma_plots.pyvista_plots.pyvista_orbits] : The function behind this method.
> [`DatasetPlots.trajectories()`][plasma_plots.accessors.DatasetPlots.trajectories] : A static Matplotlib overview.

**Examples**

```pycon
>>> orbits.plasma.plot.orbits_3d(
...     color_by="classification", domain=phi.isel(t=0)
... ).show()
```

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

### plasma_plots.accessors.DatasetPlots.paths

*method*

```python
def paths(x: str = 'x', y: str = 'y', markers=6, near=None, background: xr.DataArray | None = None, background_options: dict | None = None, t=0, ax=None, backend: Backend | None = None)
```

Plot the paths of a few markers in a plane, with start and end markers.

Optionally over a field (e.g. stream-function contour lines).

**Parameters**

- `x` (`str`) (default: `'x'`) — The quantity along the horizontal axis. Default: ``"x"``.
- `y` (`str`) (default: `'y'`) — The quantity along the vertical axis. Default: ``"y"``.
- `markers` (`int or sequence of int`) (default: `6`) — A number of markers (spread evenly over the saved markers) or a list of marker indices. Default: ``6``.
- `near` (`sequence of (float, float)`) (default: `None`) — Picks instead the marker starting closest to each of a list of ``(x, y)`` points, e.g. a row across the domain.
- `background` (`xarray.DataArray`) (default: `None`) — A field drawn behind the paths at the time ``t``: on its own ``x``/``y`` dimensions if it has them (a Cartesian field), in logical coordinates if ``x``/``y`` are ``eta1``/``eta2``/``eta3``, else in the physical plane of ``x``/``y`` (the field then needs its ``X``, ``Y``, ``Z`` coordinates).
- `background_options` (`dict`) (default: `None`) — Passed to [`plot_slice()`][plot_slice] for the background, e.g. ``dict(levels=12, fill=False)`` for the contour lines of a stream function.
- `t` (`int or float`) (default: `0`) — The time of the background: an integer position or a float value. Default: ``0``, the first.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists; ``data["markers"]`` holds the chosen markers.

> **See Also**
>
> [`plasma_plots.plotting.plot_marker_paths()`][plasma_plots.plotting.plot_marker_paths] : The function behind this method.

**Examples**

```pycon
>>> orbits.plasma.plot.paths(markers=4, background=psi.isel(t=0))
```

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

### plasma_plots.accessors.DatasetPlots.poincare

*method*

```python
def poincare(coords: str = 'physical', color_by: str | None = 'line', s: float = 3.0, cmap=None, islands: bool = False, boundary: xr.DataArray | None = None, max_lines: int | None = None, ax=None, title: str | None = None, backend: Backend | None = None, **classification)
```

Plot the Poincaré section of these traced field lines.

**Parameters**

- `coords` (`('physical', 'logical')`) (default: `"physical"`) — Draw ``R`` against ``z`` (physical), or the poloidal angle against the radial logical coordinate (logical). Default: ``"physical"``.
- `color_by` (`('line', 'iota', 'classification', 'connection_length', None)`) (default: `"line"`) — One color per line (cycling), a color bar over each line's rotational transform or connection length, or the classes of [`classify_field_lines()`][plasma_plots.fieldlines.classify_field_lines] (surface, island, chaotic) with a legend; ``None`` for one color. Default: ``"line"``.
- `s` (`float`) (default: `3.0`) — The marker size, in points². Default: 3.
- `cmap` (`str or matplotlib colormap`) (default: `None`) — The colormap of ``"iota"`` and ``"connection_length"``. Default: ``"viridis"``.
- `islands` (`bool`) (default: `False`) — Label the island chains with their ``n/m`` and widths. Default: False.
- `boundary` (`xarray.DataArray`) (default: `None`) — A field with physical coordinates whose outermost surface is drawn at the section (physical coordinates only).
- `max_lines` (`int`) (default: `None`) — Draw only the first ``max_lines`` lines. Default: all.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The title. Default: the section's label and angle.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**classification` (default: `{}`) — Options of [`classify_field_lines()`][plasma_plots.fieldlines.classify_field_lines] (``max_denominator``, ``tolerance``, ``threshold``, ``min_spread``), for ``color_by="classification"`` and ``islands_``.

**Returns**

- (`PlotResult`) — The figure, the axes and the scatters; ``data`` holds the section and, with ``islands``, the chains and the classification.

> **See Also**
>
> [`plasma_plots.fieldline_plots.plot_poincare()`][plasma_plots.fieldline_plots.plot_poincare] : The function behind this method.
> [`DatasetData.poincare()`][plasma_plots.accessors.DatasetData.poincare] : The punctures, without plotting them.
> [`DatasetAnalysis.islands()`][plasma_plots.accessors.DatasetAnalysis.islands] : The island chains alone.

**Examples**

```pycon
>>> lines.plasma.plot.poincare(color_by="iota")
>>> lines.plasma.plot.poincare(color_by="classification", islands=True)
```

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

### plasma_plots.accessors.DatasetPlots.poloidal

*method*

```python
def poloidal(color_by: str | None = 'classification', max_markers: int = 200, boundary: xr.DataArray | None = None, ax=None, backend: Backend | None = None)
```

Plot orbits projected onto the poloidal plane (``R`` against ``z``).

By default colored as passing, trapped or lost.

**Parameters**

- `color_by` (`str or None`) (default: `'classification'`) — ``"classification"`` colors by orbit class (needs ``v_par``, see [`classify_orbits()`][plasma_plots.analysis.classify_orbits]); ``"t"`` or the name of a ``(t, marker)`` variable (e.g. ``"v_par"``) colors each orbit along its path, with a color bar; ``None`` gives one color per marker. Default: ``"classification"``.
- `max_markers` (`int`) (default: `200`) — Draw only the first ``max_markers`` markers. Default: ``200``.
- `boundary` (`xarray.DataArray`) (default: `None`) — Any field with physical coordinates, whose outer (last ``eta1``) surface is drawn at its first ``eta3`` as the domain boundary.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn lines.

> **See Also**
>
> [`plasma_plots.plotting.plot_orbit_poloidal()`][plasma_plots.plotting.plot_orbit_poloidal] : The function behind this method.
> [`DatasetPlots.orbit_grid()`][plasma_plots.accessors.DatasetPlots.orbit_grid] : One panel per marker.

**Examples**

```pycon
>>> orbits.plasma.plot.poloidal(boundary=field)
```

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

### plasma_plots.accessors.DatasetPlots.power_spectrum

*method*

```python
def power_spectrum(backend: Backend | None = None, **options)
```

Plot the power of a ``time_fft`` Dataset.

**Parameters**

- `**options` (default: `{}`) — The keyword options of [`plasma_plots.spectral_plots.plot_power_spectrum()`][plasma_plots.spectral_plots.plot_power_spectrum], e.g. ``peaks=2``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists; ``data`` holds the averaged ``"power"`` and the found ``"peaks"``.

> **See Also**
>
> [`plasma_plots.spectral_plots.plot_power_spectrum()`][plasma_plots.spectral_plots.plot_power_spectrum] : The function behind this method.
> [`ArrayAnalysis.time_fft()`][plasma_plots.accessors.ArrayAnalysis.time_fft] : The Dataset to plot.

**Examples**

```pycon
>>> phi.plasma.analysis.time_fft(detrend=True).plasma.plot.power_spectrum(
...     peaks=2
... )
```

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

### plasma_plots.accessors.DatasetPlots.quantities

*method*

```python
def quantities(quantities=('v_par', 'mu'), markers=6, drift_of=('mu'), backend: Backend | None = None)
```

Plot saved orbit quantities over time for a few markers.

E.g. ``v_par`` bouncing, or the drift of the invariant ``mu``.

**Parameters**

- `quantities` (`sequence of str`) (default: `('v_par', 'mu')`) — The quantities, one panel each. Default: ``("v_par", "mu")``.
- `markers` (`int or sequence of int`) (default: `6`) — A number of markers (spread over the classes if ``v_par`` is saved, so passing and trapped ones both show) or a list of marker indices. Default: ``6``.
- `drift_of` (`bool or sequence of str`) (default: `('mu')`) — The quantities shown as their change since ``t = 0`` (default ``("mu",)``, an invariant of guiding-center motion, so its drift measures the pusher's accuracy); ``True`` for all, ``False`` for none.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, one axes per quantity and the drawn lines.

> **See Also**
>
> [`plasma_plots.plotting.plot_orbit_quantities()`][plasma_plots.plotting.plot_orbit_quantities] : The function behind this method.

**Examples**

```pycon
>>> orbits.plasma.plot.quantities(markers=4)
```

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

### plasma_plots.accessors.DatasetPlots.scatter

*method*

```python
def scatter(x: str, y: str, color: str | None = None, ax=None, cmap=None, s: int = 8, color_at=None, background: xr.DataArray | None = None, background_options: dict | None = None, equal_aspect: bool | None = None, backend: Backend | None = None, **selection)
```

Scatter two marker variables, optionally colored by a third (e.g. density or a tracer).

Remaining dimensions such as ``t`` are selected by keyword, exactly like
[`ArrayPlots.lineout()`][plasma_plots.accessors.ArrayPlots.lineout]: an integer is a position (``-1`` the last), and a float is the
nearest coordinate value. ``color_at`` colors by the values at another time (e.g. ``0``,
the initial positions); ``background`` draws a field behind the markers.

**Parameters**

- `x` (`str`) — The data variable along the horizontal axis, e.g. the position ``"x"``.
- `y` (`str`) — The data variable along the vertical axis, e.g. the position ``"y"``.
- `color` (`str`) (default: `None`) — A data variable to color the markers by, e.g. a Lagrangian tracer, weight or density, with a color bar. Default: one color.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `cmap` (`str or matplotlib.colors.Colormap`) (default: `None`) — The colormap for ``color``. Default: ``"viridis"``.
- `s` (`int`) (default: `8`) — The marker size, in points². Default: ``8``.
- `color_at` (`int or float`) (default: `None`) — Take the colors at another time (an integer position such as ``0``, or a float value), e.g. each marker's initial position, to follow where fluid parcels go. Default: the selected time.
- `background` (`xarray.DataArray`) (default: `None`) — A field drawn behind the markers at the same time (select its other dimensions first): on its own ``x``/``y`` dimensions if it has them (a Cartesian field), in logical coordinates if ``x``/``y`` are ``eta1``/``eta2``/``eta3``, else in the physical plane of ``x``/``y`` (``x``, ``y``, ``z``; the field then needs its ``X``, ``Y``, ``Z`` coordinates).
- `background_options` (`dict`) (default: `None`) — Passed to [`plot_slice()`][plot_slice] for the background (e.g. ``cmap``, ``levels``, ``fill=False``).
- `equal_aspect` (`bool`) (default: `None`) — Draw both axes to the same scale. Default: when ``x`` and ``y`` have the same ``units`` attribute (e.g. two positions), not for a phase space such as ``x`` against ``vx``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — The remaining dimensions, such as ``t``, exactly like [`ArrayPlots.lineout()`][plasma_plots.accessors.ArrayPlots.lineout]: an integer is a position (``t=-1`` the last), a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn artists.

> **See Also**
>
> [`plasma_plots.plotting.plot_marker_scatter()`][plasma_plots.plotting.plot_marker_scatter] : The function behind this method.
> [`DatasetData.scatter()`][plasma_plots.accessors.DatasetData.scatter] : The selected markers, without plotting them.
> [`DatasetPlots.animation()`][plasma_plots.accessors.DatasetPlots.animation] : The markers moving over time.

**Examples**

```pycon
>>> markers.plasma.plot.scatter(x="x", y="y", color="density", t=-1)
>>> markers.plasma.plot.scatter(x="x", y="y", color="tracer", color_at=0, t=-1)
```

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

### plasma_plots.accessors.DatasetPlots.trajectories

*method*

```python
def trajectories(max_markers: int = 200, show_paths: bool | None = None, ax=None, backend: Backend | None = None)
```

Plot the three-dimensional paths of saved markers, for an ``orbits`` product.

**Parameters**

- `max_markers` (`int`) (default: `200`) — Draw only the first ``max_markers`` markers. Default: ``200``.
- `show_paths` (`bool`) (default: `None`) — Draw each marker's path, not only its last position. Default: ``True`` for up to 200 markers.
- `ax` (`mpl_toolkits.mplot3d.Axes3D`) (default: `None`) — A 3-D axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the 3-D axes and the drawn artists.

> **See Also**
>
> [`plasma_plots.plotting.plot_marker_trajectories()`][plasma_plots.plotting.plot_marker_trajectories] : The function behind this method.
> [`DatasetData.trajectories()`][plasma_plots.accessors.DatasetData.trajectories] : The plotted markers, without plotting them.
> [`DatasetPlots.orbits_3d()`][plasma_plots.accessors.DatasetPlots.orbits_3d] : Interactive PyVista orbit lines.

**Examples**

```pycon
>>> orbits.plasma.plot.trajectories(max_markers=200)
```

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

### plasma_plots.accessors.DatasetPlots.weight_histogram

*method*

```python
def weight_histogram(weight: str = 'weight', t=-1, bins: int = 50, log: bool = True, density: bool = True, ax=None, title: str | None = None, backend: Backend | None = None)
```

Plot the distribution of the marker weights at one or several times.

**Parameters**

- `weight` (`str`) (default: `'weight'`) — The weight variable. Default: ``"weight"``.
- `t` (`(int, float or sequence)`) (default: `-1`) — The time(s): integer positions (``-1`` the last) or float nearest values, one or several. Default: ``-1``.
- `bins` (`int`) (default: `50`) — The number of bins, shared by all times. Default: 50.
- `log` (`bool`) (default: `True`) — A logarithmic count axis. Default: True.
- `density` (`bool`) (default: `True`) — Normalize each histogram to unit area. Default: True.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `title` (`str`) (default: `None`) — The title. Default: the noise estimate at the last time shown.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the axes and one outline per time; ``data["statistics"]``.

> **See Also**
>
> [`plasma_plots.plotting.plot_weight_histogram()`][plasma_plots.plotting.plot_weight_histogram] : The function behind this method.
> [`DatasetAnalysis.weight_statistics()`][plasma_plots.accessors.DatasetAnalysis.weight_statistics] : The numbers.

**Examples**

```pycon
>>> orbits.plasma.plot.weight_histogram(t=[0, 0.5, -1])
```

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

## plasma_plots.accessors.PlasmaAccessor

*class*

```python
class PlasmaAccessor
```

Struphy diagnostics of one array: ``array.plasma.plot``, ``.analysis`` and ``.data``.

Registered on every ``xarray.DataArray`` when ``plasma_plots`` is imported. A GVEC
evaluation is read in plasma-plots' conventions first (see [`plasma_plots.gvec.from_gvec()`][plasma_plots.gvec.from_gvec]).

**Examples**

```pycon
>>> import plasma_plots
>>> phi.plasma.plot.slice(x="eta1", y="eta2", t=-1)
```

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

### plasma_plots.accessors.PlasmaAccessor.analysis

*property*

```python
analysis: 'ArrayAnalysis'
```

Diagnostics of this array, e.g. ``array.plasma.analysis.growth_rate()``.

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

### plasma_plots.accessors.PlasmaAccessor.data

*property*

```python
data: 'ArrayData'
```

The data behind each plot, without rendering it.

E.g. for a different plotting library: ``array.plasma.data.slice(x="eta1", y="v1", t=-1)``.

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

### plasma_plots.accessors.PlasmaAccessor.plot

*property*

```python
plot: 'ArrayPlots'
```

Plots of this array, e.g. ``array.plasma.plot.slice(x="eta1", y="v1", t=-1)``.

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

## plasma_plots.accessors.PlasmaDatasetAccessor

*class*

```python
class PlasmaDatasetAccessor
```

Struphy diagnostics of one dataset, e.g. an ``orbits`` product: ``dataset.plasma.plot``.

Also ``dataset.plasma.analysis`` and ``dataset.plasma.data``. Registered on every
``xarray.Dataset`` when ``plasma_plots`` is imported. A GVEC evaluation is read in
plasma-plots' conventions first (see [`plasma_plots.gvec.from_gvec()`][plasma_plots.gvec.from_gvec]).

**Examples**

```pycon
>>> orbits.plasma.plot.trajectories()
>>> orbits.plasma.analysis.classify_orbits()
```

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

### plasma_plots.accessors.PlasmaDatasetAccessor.analysis

*property*

```python
analysis: 'DatasetAnalysis'
```

Diagnostics of this dataset, e.g. ``orbits.plasma.analysis.classify_orbits()``.

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

### plasma_plots.accessors.PlasmaDatasetAccessor.data

*property*

```python
data: 'DatasetData'
```

The data behind each plot, without rendering it: ``orbits.plasma.data.scatter(...)``.

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

### plasma_plots.accessors.PlasmaDatasetAccessor.plot

*property*

```python
plot: 'DatasetPlots'
```

Plots of this dataset, e.g. ``orbits.plasma.plot.trajectories()``.

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

## plasma_plots.accessors.SliceView

*class*

```python
class SliceView
```

A configured array view, shared by static, interactive and exported plots.

Construct with ``array.plasma.plot.view(...)`` ([`ArrayPlots.view()`][plasma_plots.accessors.ArrayPlots.view]), which sets its
selection and rendering options. Configuration does not create figures or copy the
underlying array.

**Examples**

```pycon
>>> view = phi.plasma.plot.view(
...     x="eta1", y="eta2", cmap="RdBu_r", symmetric=True
... )
>>> view.slice(t=-1)
>>> view.animation(step=2)
```

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

### plasma_plots.accessors.SliceView.animation

*method*

```python
def animation(interval=100, step=1, max_frames=None, alongside=None, backend: Backend | None = None)
```

Create a Matplotlib animation using this view's rendering options.

Keep a reference to the returned animation.

**Parameters**

- `interval` (`int`) (default: `100`) — The delay between frames, in milliseconds. Default: ``100``.
- `step` (`int`) (default: `1`) — Use every ``step``-th value of the sweep. Default: ``1``.
- `max_frames` (`int`) (default: `None`) — Keep at most this many frames, evenly spaced over those ``step`` leaves (the first and last included), e.g. to keep a Plotly animation small. Default: all.
- `alongside` (`list of xarray.DataArray`) (default: `None`) — Further arrays with the same dimensions, animated side by side in sync, each with its own color limits.
- `backend` (`('matplotlib', 'plotly')`) (default: `"matplotlib"`) — Draw with Matplotlib, or as an interactive Plotly figure with a slider (in ``result.fig``; needs plotly, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`matplotlib.animation.FuncAnimation or PlotResult`) — The animation; with ``backend="plotly"`` a result whose Plotly figure has a slider and Play/Pause buttons.

> **See Also**
>
> [`plasma_plots.plotting.animate_slices()`][plasma_plots.plotting.animate_slices] : The function behind this method.
> [`plasma_plots.plotting.animate_fields()`][plasma_plots.plotting.animate_fields] : The function used with ``alongside``.

**Examples**

```pycon
>>> view.animation(step=2)
```

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

### plasma_plots.accessors.SliceView.panels

*method*

```python
def panels(nrows=3, ncols=4, backend: Backend | None = None)
```

Draw snapshots spread evenly along the sweep.

**Parameters**

- `nrows` (`int`) (default: `3`) — The number of rows of panels. Default: ``3``.
- `ncols` (`int`) (default: `4`) — The number of columns of panels. Default: ``4``.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`PlotResult`) — The figure, the array of axes and the drawn meshes.

> **See Also**
>
> [`plasma_plots.plotting.plot_panels()`][plasma_plots.plotting.plot_panels] : The function behind this method.

**Examples**

```pycon
>>> view.panels(nrows=2, ncols=3)
```

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

### plasma_plots.accessors.SliceView.save_frames

*method*

```python
def save_frames(directory, *, step=1, prefix='frame', dpi=110)
```

Export PNG frames using this view's rendering options.

**Parameters**

- `directory` (`str or pathlib.Path`) — The directory to write into.
- `step` (`int`) (default: `1`) — Use every ``step``-th value of the sweep. Default: ``1``.
- `prefix` (`str`) (default: `'frame'`) — The start of each file name. Default: ``"frame"``.
- `dpi` (`int`) (default: `110`) — The resolution of the PNGs. Default: ``110``.

**Returns**

- (`list of str`) — The paths of the written files.

> **See Also**
>
> [`plasma_plots.plotting.save_frames()`][plasma_plots.plotting.save_frames] : The function behind this method.

**Examples**

```pycon
>>> view.save_frames("frames")
```

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

### plasma_plots.accessors.SliceView.slice

*method*

```python
def slice(ax=None, backend: Backend | None = None, **selection)
```

Draw a snapshot, e.g. ``view.slice(t=-1)``.

With ``shared_clim``, the color limits come from all of the view's data, so the snapshot
uses the same scale as its panels, animation and exported frames.

**Parameters**

- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `backend` (`('matplotlib', 'plotly', 'tikz')`) (default: `"matplotlib"`) — Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in ``result.fig``; needs plotly or maxplotlib, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend] and [`plasma_plots.tikz_backend`][plasma_plots.tikz_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.
- `**selection` (default: `{}`) — Further dimensions to select, e.g. ``t=-1``, in addition to (or overriding) the view's own selection: an integer is a position, a float the nearest coordinate value.

**Returns**

- (`PlotResult`) — The figure, the axes and the drawn mesh.

> **See Also**
>
> [`plasma_plots.plotting.plot_slice()`][plasma_plots.plotting.plot_slice] : The function behind this method.

**Examples**

```pycon
>>> view.slice(t=-1)
```

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

### plasma_plots.accessors.SliceView.viewer

*method*

```python
def viewer(backend: Backend | None = None)
```

Create a viewer with sliders for the unselected dimensions.

Keep a reference to the returned viewer.

**Parameters**

- `backend` (`('matplotlib', 'plotly')`) (default: `"matplotlib"`) — Draw with Matplotlib, or as an interactive Plotly figure with a slider (in ``result.fig``; needs plotly, see [`plasma_plots.plotly_backend`][plasma_plots.plotly_backend]). Default: the one set with [`plasma_plots.set_backend()`][plasma_plots.plotly_backend.set_backend], ``"matplotlib"`` unless changed.

**Returns**

- (`plasma_plots.plotting.InteractiveSliceViewer or PlotResult`) — The viewer, with this view's rendering options; with ``backend="plotly"`` a result whose Plotly figure has one slider (one unselected dimension at most).

> **See Also**
>
> [`plasma_plots.plotting.InteractiveSliceViewer`][plasma_plots.plotting.InteractiveSliceViewer] : The viewer class.

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