PlasmaCalcs.plotting.lines.XarrayLines

class PlasmaCalcs.plotting.lines.XarrayLines(array, dims=None, t=None, *, x=None, ax=None, add_legend=True, label=UNSET, cstyles=None, cstyles_default=False, **kw)

Bases: MovieOrganizerNode

MovieOrganizerNode for organizing multiple XarrayLines.

array: xarray.DataArray or xarray.Dataset: the array to plot lines from. Any number of dimensions is allowed.

if dataset, will be converted to array using to_array(dim=’variable’).

Note that dims other than t & x should be “not too long” otherwise plot will have lots of lines.
dims: None , str, or list of str: dimensions to iterate over; plot one line per point in these dimensions.

E.g. dims = [‘fluid’, ‘component’] –> plot one line per fluid-component pair.

[TODO] improve formatting; currently uses default cycler for line properties,

but if using multiple dims it would be nicer to have a different cycler for each dim,

e.g. colors for fluid, linestyles for component.

None –> infer from array.dims, t, and x.
t: None or str: dimension name for the time axis (for movies).

None –> infer from the array coords. See also: DEFAULTS.PLOT.DIMS_INFER

If no time dimension (None provided & can’t infer), that’s okay, but animation will fail.
x: None or str: dimension name for the x axis.

None –> infer from the array coords. See also: DEFAULTS.PLOT.DIMS_INFER
cstyles: None or dict of {{coordname: dict or list of tuples of (val, dict of kwargs for XarrayLine)}}: if provided, pass these dicts to individual lines with corresponding scalar val for coord.

use tuples of values to test equality instead of indexing a dict.

E.g., styles={{‘fluid’: [(‘e’, dict(ls=’–‘)), (‘H_II’, dict(color=’blue’))]}}

would ensure dashed line when arr[‘fluid’]==’e’, blue line when arr[‘fluid’]==’H_II’,

and have no effect whenever arr[‘fluid’] is not scalar, doesn’t exist, or isn’t ‘e’ or ‘H_II’.
cstyles_default: bool: tells how to handle conflict between kwargs from cstyles and kwargs passed directly to self.

True –> treat cstyles as ‘defaults’; kwargs from self override kwargs from cstyles.

False –> kwargs from cstyles take precedence.

robust: {robust} ymargin: {ymargin} add_legend: bool

whether to plot a legend, by default.

label: {label}: UNSET –> ‘dim=val’ for each line, for each dim in dims, e.g. ‘fluid=e-, component=x’

To view or adjust plot settings in self, see self.plot_settings, or help(self.plot_settings).

__init__(array, dims=None, t=None, *, x=None, ax=None, add_legend=True, label=UNSET, cstyles=None, cstyles_default=False, **kw)

Methods

`__init__`(array[, dims, t, x, ax, ...])
`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)
`plot_legend`()
`plot_title`()
`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`
`ani`
`ax`
`depth`
`fig`
`frame`
`frames`
`height`
`line0`
`lines`
`parent`
`parent_ref`
`plotted`
`plotted_data`
`size`

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 the lines are 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

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: figure where the lines are 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): return dict of data for the given frame, to be used by the MoviePlotElement at self.obj.

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: call init_plot on all nodes, and connect to tree.

This is fundamentally different from MoviePlotNode.init_plot’s usual purpose,

since this is about calling init_plot on the nodes, not on self.obj.

[TODO] should this function be renamed, for clarity?

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 line0: first line; lines[0].

property lines: alias to nodes

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.

plot_legend(): plot a legend! Plots to the right of the axes.

For more precise control of legend,

use add_legend=False during self.__init__,

and just call plt.legend() separately…

Also fig.set_layout_engine(‘tight’) if layout engine was None;

otherwise the legend might get cut off at the edges.

plot_title(): adds title (as a MovieTextNode) on self.ax.

raise PlottingAmbiguityError if title already plotted

(this prevents having multiple title nodes).

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.

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.