plasma_plots.plotly_backend

Interactive Plotly versions of the plots: backend="plotly".

Every accessor plot that draws with Matplotlib (array.plasma.plot.*, dataset.plasma.plot.*, out.plot.*) takes backend="plotly". The plot is drawn with Matplotlib as usual, off screen, and the drawn figure is converted into a Plotly figure: the same data, color limits, fits, reference curves, labels and layout, but with hover values, zoom and, for animations and viewers, a slider in the browser. The two backends cannot disagree about what they show, because there is only one drawing code path.

result = phi.plasma.plot.slice( … coords=“physical”, plane=“XY”, t=-1, eta3=0, backend=“plotly” … ) result.fig # a plotly.graph_objects.Figure result.save(“phi.html”) # a standalone page; .png/.pdf/.svg need kaleido

the default for every plot from now on

plasma_plots.set_backend(“plotly”)

Plots return a PlotResult with either backend (fit_results and data included); animations and viewers return one too, whose figure has a slider. Plotly is optional: pip install "plasma-plots[plotly]".

The conversion itself is also available for any Matplotlib figure drawn with the plotting functions: [to_plotly()][to_plotly], [animation_to_plotly()][animation_to_plotly] and to_plotly().

What converts: lines, markers and scatters (also colored by a value), meshes (heatmaps on rectilinear grids; on mapped, curvilinear grids an image of the mesh with the values under the cursor), contour lines, quivers, colored line collections, horizontal and vertical lines and bands, annotations, colorbars, legends, log axes, twin axes, 3-D lines and scatters, shared and equal-aspect axes, and titles. Mathtext labels ($\omega$, $p_0$) become Unicode and sub/superscripts. Anything else is left out with a [ConversionWarning][ConversionWarning].

Attributes

Name	Description
BACKENDS	No description.
IMAGE_PIXELS	No description.
PX_PER_INCH	No description.
PX_PER_PT	No description.

Classes

Name	Description
ConversionWarning	A part of a Matplotlib figure that has no Plotly counterpart here and is left out.

Functions

Name	Description
animation_to_plotly	Convert a Matplotlib animation of the plotting functions into a Plotly figure with frames.
get_backend	Return the backend of plots that do not pass backend= themselves.
plotly_text	Turn a Matplotlib label into Plotly text.
resolve_backend	The backend a plot draws with: backend, or the default if it is None.
set_backend	Set the backend of every plot that does not pass backend= itself.
to_plotly	Convert a drawn Matplotlib figure into an interactive Plotly figure.
viewer_to_plotly	Convert a slider viewer into a Plotly figure with one slider.
with_backend	Give an accessor plot method the backend option.

BACKENDSattributemodule attribute#

View source

BACKENDS = ('matplotlib', 'plotly', 'tikz')

IMAGE_PIXELSattributemodule attribute#

View source

IMAGE_PIXELS = 1200

PX_PER_INCHattributemodule attribute#

View source

PX_PER_INCH = 100.0

PX_PER_PTattributemodule attribute#

View source

PX_PER_PT = PX_PER_INCH / 72.0

ConversionWarningclass#

View source

class ConversionWarning(UserWarning)

Bases: UserWarning

A part of a Matplotlib figure that has no Plotly counterpart here and is left out.

animation_to_plotlyfunction#

View source

def animation_to_plotly(animation, *, labels=None, prefix: str | None = None, play: bool = True, strict: bool = False)

Convert a Matplotlib animation of the plotting functions into a Plotly figure with frames.

Every frame is drawn by the animation’s own update function and converted like a figure, so the frames show exactly what the Matplotlib animation shows; a slider (and Play/Pause buttons) steps through them.

Parameters

Name	Type	Default	Description
animation	matplotlib.animation.FuncAnimation	required	The animation, e.g. from animate_slices().
labels	sequence of str	None	One slider label per frame. Default: the sweep values the animation was made for (for the animations of this package), else the frame numbers.
prefix	str	None	Shown before the current label, e.g. "t = ". Default: the sweep’s name.
play	bool	True	Add Play and Pause buttons. Default: True.
strict	bool	False	Raise instead of warning when a part of a frame cannot be converted. Default: False.

Returns

plotly.graph_objects.Figure

The first frame, with every frame in figure.frames.

Raises

ValueError

If the frames do not all have the same kinds of traces.

See Also

to_plotly() : The conversion of one figure.

Examples

>>> animation = animate_slices(phi.isel(eta3=0), step=2)
>>> animation_to_plotly(animation).write_html("phi.html")

get_backendfunction#

View source

def get_backend() -> str

Return the backend of plots that do not pass backend= themselves.

Returns

str

"matplotlib" (the default), "plotly" or "tikz".

See Also

set_backend() : Changes it.

plotly_textfunction#

View source

def plotly_text(text) -> str

Turn a Matplotlib label into Plotly text.

Mathtext ($\omega$, $p_0$) becomes Unicode and _{/^{; other <, > and & are escaped, newlines become
.}}

Parameters

Name	Type	Description
text	str or None	The label.

Returns

str

The Plotly text; "" for None.

Examples

>>> plotly_text(r"fit: $\gamma$ = 0.1")
'fit: γ = 0.1'
>>> plotly_text("$p_0$")
'p<sub>0</sub>'

resolve_backendfunction#

View source

def resolve_backend(backend: str | None) -> str

The backend a plot draws with: backend, or the default if it is None.

Inside another plot (e.g. ArrayPlots.slice calling SliceView.slice) it is always "matplotlib": the outermost call converts the finished figure.

Parameters

Name	Type	Default	Description
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	The backend asked for.

Returns

str

"matplotlib", "plotly" or "tikz".

set_backendfunction#

View source

def set_backend(backend: str) -> str

Set the backend of every plot that does not pass backend= itself.

Parameters

Name	Type	Default	Description
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	The new default ("tikz": see plasma_plots.tikz_backend).

Returns

str

The previous default, e.g. to restore it afterwards.

Raises

ValueError

If backend is not "matplotlib", "plotly" or "tikz".

See Also

get_backend() : The current default.

Examples

>>> previous = plasma_plots.set_backend("plotly")
>>> phi.plasma.plot.slice(t=-1, eta3=0)  # a Plotly figure
>>> plasma_plots.set_backend(previous)

to_plotlyfunction#

View source

def to_plotly(figure, *, strict: bool = False)

Convert a drawn Matplotlib figure into an interactive Plotly figure.

Parameters

Name	Type	Default	Description
figure	matplotlib.figure.Figure	required	A figure drawn by one of the plotting functions (or any figure with the artists they use, see plasma_plots.plotly_backend).
strict	bool	False	Raise instead of warning when a part of the figure cannot be converted. Default: False.

Returns

plotly.graph_objects.Figure

The same content: traces for the data, shapes for lines and bands spanning an axes, annotations for text, a colorbar per Matplotlib colorbar.

Raises

ImportError

If plotly is not installed.

See Also

animation_to_plotly() : The same for an animation. plasma_plots.plotting.PlotResult.to_plotly() : The same for a plot result.

Examples

>>> result = plot_slice(phi.isel(t=-1, eta3=0))
>>> to_plotly(result.fig).write_html("phi.html")

viewer_to_plotlyfunction#

View source

def viewer_to_plotly(viewer)

Convert a slider viewer into a Plotly figure with one slider.

The Matplotlib viewer has one slider per remaining dimension; a Plotly figure can combine only one, so exactly one dimension besides the two drawn may be left with more than one value.

Parameters

Name	Type	Description
viewer	plasma_plots.plotting.InteractiveSliceViewer	The viewer (drawn or not).

Returns

PlotResult

The Plotly figure, with a slider over the remaining dimension (a static slice if there is none).

Raises

ValueError

If more than one dimension remains to slide over.

See Also

animation_to_plotly() : The conversion behind this one.

with_backendfunction#

View source

def with_backend(method)

Give an accessor plot method the backend option.

The decorated method declares backend=None in its signature (so that its docs and help() show it) and draws with Matplotlib as before; with backend="plotly" or backend="tikz" (or that default, see set_backend()) the decorator draws off screen and returns the converted result instead (see plasma_plots.tikz_backend). An ax given with either raises TypeError, since such a figure cannot be drawn into a Matplotlib axes.

Parameters

Name	Type	Description
method	callable	A method returning a PlotResult, a FuncAnimation or an InteractiveSliceViewer.

Returns

callable

The method with the backend option.