array.plasma.data

Every plot on array.plasma.plot has a twin here, as array.plasma.data.<method>(...), that does the same selection and returns the labeled xarray object instead of a figure. See the Selecting data guide.

Where the accessors come from

The examples use output of a Struphy Output, which loads plasma-plots and its .plasma accessors. For other xarray data, run import plasma_plots first (see Getting started).

array.plasma.data

The data behind each plot in :class:ArrayPlots, without rendering it.

lineout

lineoutmethod#

View source

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

Return the 1-D profile ArrayPlots.lineout() would plot.

Parameters

Name	Type	Default	Description
x	str	None	The dimension to keep: checked to be the only one left after selection. Default: whichever it is.
**selection		{}	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() : The check behind this method. ArrayPlots.lineout() : The plot of this profile.

Examples

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

vector

vectormethod#

View source

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() would plot.

Parameters

Name	Type	Default	Description
x	str	required	The dimension along the horizontal axis.
y	str	required	The dimension along the vertical axis.
components	(int, int)	(0, 1)	The positions along component_dim of the two components drawn. Default: (0, 1).
stride	int	1	Draw every stride-th arrow along x and y. Default: 1.
coordinates	('logical', 'physical')	"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		{}	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() : The plot of these components. plasma_plots.plotting.prepare_vector() : The function that prepares them.

volume_slices

volume_slicesmethod#

View source

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

Return the three orthogonal planes ArrayPlots.volume_slices() would plot.

Parameters

Name	Type	Default	Description
indices	dict of str to int	None	The index at which each dimension is held fixed, e.g. {"eta3": 0}. Default: the middle index of every dimension.
**selection		{}	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() : The plot of these planes. plasma_plots.plotting.prepare_volume_slices() : The function that prepares them.

grid

gridmethod#

View source

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	Type	Default	Description
name	str	None	The name of the point data. Default: the field’s label.
**selection		{}	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() : The function behind this method. ArrayData.to_vtk() : Write the grid to files instead.

Examples

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

to_vtk

to_vtkmethod#

View source

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

Name	Type	Default	Description
path	str or pathlib.Path	required	The .vts file (the suffix is set to .vts), or with a t dimension the directory to write into (created if needed).
name	str	None	The name of the point data, also the file stem in a time series. Default: the field’s label.
**selection		{}	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() : The function behind this method. ArrayData.grid() : One time as a PyVista grid, in memory.

Examples

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

slices_3d

slices_3dmethod#

View source

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

Return the logical cuts ArrayPlots.slices_3d() would draw.

Parameters

Name	Type	Default	Description
cuts	dict	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		{}	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() : The drawing of these cuts. plasma_plots.pyvista_plots.prepare_slices_3d() : The function that prepares them.

compare

comparemethod#

View source

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

Return the aligned difference or ratio ArrayPlots.compare() would plot.

Parameters

Name	Type	Default	Description
other	xarray.DataArray	required	The array to compare with, e.g. a reference run; aligned with this one first.
mode	('difference', 'ratio')	"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() : The plot of this difference or ratio. plasma_plots.plotting.prepare_compare() : The function that computes it.

Examples

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

view

viewmethod#

View source

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(), .viewer(), .animation() and .frames(), which each render one frame of exactly this data at a time.

Parameters

Name	Type	Default	Description
x	str	None	The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
y	str	None	The dimension along the vertical axis. Default: the second remaining dimension.
sweep	str	't'	The dimension stepped through by panels, the viewer’s slider, animations and exported frames. Default: "t".
coords	('logical', 'physical')	"logical"	Draw over the logical coordinates, or over the mapped physical coordinates (X, Y, Z). Default: "logical".
plane	('XY', 'XZ', 'YZ', 'RZ', 'X1X2')	"XY"	The physical plane, with coords="physical": "RZ" uses R = √(X² + Y²), "X1X2" GVEC’s reference coordinates. Default: "XY".
**selection		{}	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() : The configured view of this data, and its options.

Examples

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

slice

slicemethod#

View source

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() would plot.

Parameters

Name	Type	Default	Description
x	str	None	The dimension along the horizontal axis (logical coordinates). Default: the first of the two remaining dimensions.
y	str	None	The dimension along the vertical axis. Default: the second remaining dimension.
sweep	str	't'	The dimension stepped through by panels, the viewer’s slider, animations and exported frames. Default: "t".
coords	('logical', 'physical')	"logical"	Draw over the logical coordinates, or over the mapped physical coordinates (X, Y, Z). Default: "logical".
plane	('XY', 'XZ', 'YZ', 'RZ', 'X1X2')	"XY"	The physical plane, with coords="physical": "RZ" uses R = √(X² + Y²), "X1X2" GVEC’s reference coordinates. Default: "XY".
**selection		{}	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() : The plot of this slice.

Examples

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

dispersion

dispersionmethod#

View source

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

Return the space-time power spectrum ArrayPlots.dispersion() would plot.

The same as ArrayAnalysis.dispersion(); included here too for parity with every other plot.

Parameters

Name	Type	Default	Description
dim	str	None	The spatial dimension. Default: the sole dimension other than t.
detrend	bool	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() : The function behind this method. ArrayPlots.dispersion() : The plot of this spectrum. ArrayAnalysis.dispersion() : The same spectrum.

Examples

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

overlay_orbits

overlay_orbitsmethod#

View source

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() would plot.

Parameters

Name	Type	Default	Description
orbits	xarray.Dataset	required	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	required	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	required	The vertical dimension of the slice; orbits needs a variable of this name too.
max_markers	int	200	Draw only the first max_markers markers. Default: 200.
**selection		{}	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() : The plot of this slice and these orbits.

Examples

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

trajectories

trajectoriesmethod#

View source

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

Return the marker-position subset ArrayPlots.trajectories() would plot.

Parameters

Name	Type	Default	Description
max_markers	int	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() : The plot of these markers.

timeseries

timeseriesmethod#

View source

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

Return this time series and any others, validated, as ArrayPlots.timeseries() plots them.

Parameters

Name	Default	Description
*others	()	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() : The plot of these series.

Examples

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

poincare

poincaremethod#

View source

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

Return the Poincaré section ArrayPlots.poincare() would plot.

Parameters

Name	Type	Default	Description
seeds	(int, dict, array_like or xarray.Dataset)	8	Where the lines start; see plasma_plots.fieldlines.trace_field_lines(). Default: 8 along the radius.
turns	float	None	How many toroidal transits to trace. Default: 20.
section	float	None	The toroidal logical coordinate of the plane. Default: the first grid value.
**selection		{}	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().

See Also

ArrayPlots.poincare() : The plot of these punctures. ArrayAnalysis.field_lines() : The traced lines themselves.

Examples

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

critical_points

critical_pointsmethod#

View source

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

Return the O- and X-points ArrayPlots.critical_points() would mark.

Parameters

Name	Type	Default	Description
refine	bool	True	Locate the zero within the cell by Newton’s method (the cell’s centre otherwise). Default: True.
**selection		{}	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() : The function behind this method. ArrayPlots.critical_points() : The plot of these points.

Examples

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