PlasmaCalcs.plotting.patches.XarrayRectanglePatch

class PlasmaCalcs.plotting.patches.XarrayRectanglePatch(ds, t=None, ax=None, init_plot=True, **kw_super)

Bases: XarrayPatch

MoviePlotNode of 2D rectangle.

stores a RectanglePatchPlotElement and has methods for plotting & updating it.

ds: xarray.Dataset, probably 0D or 1D.: xarray Dataset containing the rectangle params to be plotted.

if ndim=0, can still plot, but nothing to animate.

rectangle params are ‘x0’, ‘y0’, ‘width’, ‘height’.

(x0 and y0 point to lower left corner unless negative width or height.

units determined by transform; default data units.)
t: None or str: the array dimension which frames will index. E.g. ‘time’.

None –> infer from ds.dims. (if ds is 1D, use t=ds.dims[0]).
ax: None or Axes: the attached mpl.axes.Axes object.

None –> will use self.ax=plt.gca() when getting self.ax for the first time.
transform: UNSET, ‘data’, ‘axes’, 2-tuple of (‘data’ or ‘axes’), or Transform object (default: UNSET): indicate coordinate system to use for x and y inputs.

single string –> x and y both in this coordinate system.

tuple –> xy[0] tells x system; xy[1] tells y system.

‘data’ coords means input values match data values.

‘axes’ coords means input values correspond to distance across axis:

for x: left=0, right=1.

for y: bottom=0, top=1.
init_plot: bool (default: True): whether to call self.init_plot() immediately, during __init__.

(as a PlotSetting: tells the value of init_plot passed during __init__.)

False –> still must call self.init_plot() before using self(…) or self.updater(…)

(end-user will probably never use init_plot=False; it’s mostly for internal code.)

(might use False if creating MovieImage before defining the associated Axes.)
label: UNSET or str (default: UNSET): label for this plot element, to be included in a legend.

For xarrays, will label.format(**xarray_nondim_coords(array)).

additional kwargs can contain constant rectangle params with same key as in matplotlib,

but only if not provided in ds. E.g. ‘edgecolor’, but only if no ds[‘edgecolor’].

additional kwargs can also be any other PlotSettings.

See also: XarrayLimsPatch

__init__(ds, t=None, ax=None, init_plot=True, **kw_super)

Methods

`__init__`(ds[, t, ax, init_plot])
`add_child`(child)
`display`([show_depth, max_depth, shorthand])
`enumerate_flat`(*[, include_self])
`flat`(*[, include_self])
`flat_branches_until`(branches_until, *[, ...])
`get_animator`(*[, fps, blit, frames, plt_close])
`get_data_at_frame`(frame)
`get_nframes`()
`get_nframes_here`()
`help`()
`html`([show_depth, max_depth, shorthand])
`init_plot`()
`init_plots`(*[, plotted_ok])
`make_child`(obj)
`make_children`(objs)
`save`(filename[, frames, fps, blit])
`set_parent`(parent, *[, _internal])
`update_to_frame`(frame)

Attributes

`DEFAULT_TREE_SHORTHAND`
`DEFAULT_TREE_SHOW_DEPTH`
`DEFAULT_TREE_SHOW_MAX_DEPTH`
`PATCH_SETTINGS_LOOKUP`
`ani`
`ax`
`depth`
`fig`
`frame`
`frames`
`height`
`legend_handle`
`parent`
`parent_ref`
`patch`
`plotted`
`plotted_data`
`size`
`t_plot_dim`

add_child(child): adds this child (a Tree) to self.children. Also, child.set_parent(self).

returns the added child.

property ani: alias to get_animator

property ax: mpl.axes.Axes where this XarrayPatch is plotted, or None if not plotted.

property depth: number of layers above self. (parent, parent’s parents, etc.)

depth = 0 for the node with parent = None.

display(show_depth=None, max_depth=None, *, shorthand=None)

display self in html. Includes self.html() and DEFAULTS.TREE_CSS.

show_depth: None or int: max number of layers of tree to show by default (i.e. “not hidden” by default)

None –> use self.DEFAULT_TREE_SHOW_DEPTH if defined else DEFAULTS.TREE_SHOW_DEPTH
max_depth: None or int: max number of layers of tree to render (even if all layers are “not hidden”).

Anything deeper will not be converted to html string.

None –> use self.DEFAULT_TREE_SHOW_MAX_DEPTH if defined else DEFAULTS.TREE_SHOW_MAX_DEPTH
shorthand: None or bool: whether to use shorthand for the “Tree([depth=N, height=N, size=N], obj=…)” part of the repr.

True –> use shorthand; replace that^ with: “((N, N, N)) …”

None –> use self.DEFAULT_TREE_SHORTHAND if defined else DEFAULTS.TREE_SHORTHAND

element_cls: alias of RectanglePatchPlotElement

enumerate_flat(*, include_self=False): returns a generator which iterates over all of self’s descendants, in depth-first order,

yielding (index, node) pairs, such that self[index] == node.

Note that index will be a tuple with length == node.depth.

if include_self, yield self first, as: ((), self)).

property fig: mpl.figure.Figure where this XarrayPatch is plotted, or None if not plotted.

flat(*, include_self=False): returns a generator which iterates over all of self’s descendants, in depth-first order.

if include_self, yield self first.

flat_branches_until(branches_until, *, include_self=False): returns a generator which iterates over all of self’s descendants, in depth-first order,

but stop looking at descendants on a branch as soon as branches_until(node).

E.g. self.flat_branches_until(lambda node: node.obj==7) will be similar to flat,

but won’t go to any descendants for any node with obj==7.

if include self, yield self first, and check branches_until(self) before continuing.

otherwise, never check branches_until(self).

property frame: the currently-plotted frame

property frames: the frames that could be in the movie.

if set to None, will use self.get_nframes() instead.

if set to a slice, will use range(self.get_nframes())[frames] instead.

get_animator(*, fps=UNSET, blit=UNSET, frames=UNSET, plt_close=True, **kw_func_animation)

returns FuncAnimation instance using self as func.

Use kwarg defaults from self.plot_settings, for any kwargs not provided here.

fps: UNSET, None, or number (default: UNSET): frames per second.

UNSET –> use DEFAULTS.PLOT.FPS (default: 30).

(Or use value from self.plot_settings, if provided.)

None –> use matplotlib defaults.
blit: UNSET, None, or bool (default: UNSET): whether to use blitting.

UNSET –> use DEFAULTS.PLOT.BLIT (default: True).

(Or use value from self.plot_settings, if provided.)

if None, use matplotlib defaults.
frames: UNSET, None, int, iterable, or slice (default: UNSET): passed to FuncAnimation. Tells number of frames or which frames to plot.

If UNSET, use value from self.plot_settings if possible else getattr(self, ‘frames’, None).

if slice, use range(self.get_nframes())[frames], crashing if self doesn’t have ‘get_nframes’.
plt_close: bool: whether to plt.close() before returning the result.

This is useful in Jupyter, where commonly one cell might make a plot,

then call get_animator() to display movie in-line, but not plt.close().

In that case, plt_close=False would display animation & plot

[TODO] use init_func kwarg to avoid calling self twice for frame 0?

get_data_at_frame(frame): returns {‘params’: params at this frame}.

get_nframes(): return max of get_nframes_here() for self & all descendants of self.

If any node throws PlottingNframesUnknownError, pretend they said nframes=0.

If all nodes throw PlottingNframesUnknownError, raise the one from self.

get_nframes_here(): return the number of frames that could be in the movie, based on this node.

property height: number of layers below self. (children, children’s children, etc.)

height = 0 for a node with no children.

classmethod help(): prints a helpful message with examples for how to use this cls

html(show_depth=None, max_depth=None, *, shorthand=None)

returns html for displaying self and all of self’s children.

show_depth: None or int: max number of layers of tree to show by default (i.e. “not hidden” by default)

None –> use self.DEFAULT_TREE_SHOW_DEPTH if defined else DEFAULTS.TREE_SHOW_DEPTH
max_depth: None or int: max number of layers of tree to render (even if all layers are “not hidden”).

Anything deeper will not be converted to html string.

None –> use self.DEFAULT_TREE_SHOW_MAX_DEPTH if defined else DEFAULTS.TREE_SHOW_MAX_DEPTH
shorthand: None or bool: whether to use shorthand for the “Tree([depth=N, height=N, size=N], obj=…)” part of the repr.

True –> use shorthand; replace that^ with: “((N, N, N)) …”

None –> use self.DEFAULT_TREE_SHORTHAND if defined else DEFAULTS.TREE_SHORTHAND

init_plot(): plot for the first time. Save the PatchPlotElement in self.obj.

init_plots(*, plotted_ok=True)

init_plot for self & all descendants with non-None obj.

plotted_ok: bool: True –> skip node if node.plotted.

False –> call init_plot on all nodes with non-None obj.

property legend_handle: alias to self.obj.legend_handle;

method which returns a Patch suitable for use as a handle in a legend.

(implied handles are sometimes okay, but this is useful to increase hatch density if using hatches.)

make_child(obj): makes a child of self, with obj as its stored object, and returns the child.

make_children(objs): make_child(obj) for obj in objs; returns the list of newly made children.

property parent: parent node of self. None if self is root.

When set to a value, calls self.set_parent(value),

which also updates tracking info appropriately, and updates parent’s children.

property parent_ref: stores parent value, but internally uses weakref to avoid circular references.

Users should always use self.parent instead.

property patch: mpl.patches.Patch object of this XarrayPatch, or None if not plotted.

property plotted: whether this node’s element has actually been plotted yet.

False before init_plot; True after. Always None if self.obj is None.

property plotted_data: the currently plotted data.

save(filename, frames=UNSET, *, fps=UNSET, blit=UNSET, **kw)

save the movie to filename.

RECOMMENDED:

first, self.save(…, frames=N), with small N (e.g. N=5), to test movie formatting.

Troubleshooting: if movie getting cut off,

try plt.subplots_adjust(bottom=0.2, left=0.2, right=0.8, top=0.8),

or even more extreme values if necessary. (0 is bottom/left edge; 1 is top/right edge.)

frames: UNSET, None, int, iterable, or slice (default: UNSET): passed to FuncAnimation. Tells number of frames or which frames to plot.

If UNSET, use value from self.plot_settings if possible else getattr(self, ‘frames’, None).

if slice, use range(self.get_nframes())[frames], crashing if self doesn’t have ‘get_nframes’.
fps: UNSET, None, or number (default: UNSET): frames per second.

UNSET –> use DEFAULTS.PLOT.FPS (default: 30).

(Or use value from self.plot_settings, if provided.)

None –> use matplotlib defaults.
blit: UNSET, None, or bool (default: UNSET): whether to use blitting.

UNSET –> use DEFAULTS.PLOT.BLIT (default: True).

(Or use value from self.plot_settings, if provided.)

if None, use matplotlib defaults.

additional kwargs passed to FuncAnimation() or FuncAnimation.save().

returns abspath of the saved movie.

set_parent(parent, *, _internal=False): sets self.parent = parent. Also, parent.add_child(self), unless _internal=True.

Users should use self.parent = parent instead of calling set_parent directly.

property size: number of nodes in this tree. (here and below)

size = 1 for a node with no children.

property t_plot_dim: alias to t

update_to_frame(frame): update the plot for the given frame. set self.frame=frame.

also calls update_to_frame for all children.

return iterable of all updated artists.