PlasmaCalcs.plotting.images.XarrayImage
- class PlasmaCalcs.plotting.images.XarrayImage(array, t=None, *, x=None, y=None, ax=None, image_mode='pcolormesh', init_plot=True, add_colorbar=UNSET, add_labels=True, title=UNSET, **kw_super)
Bases:
MoviePlotNode,PlotDimsMixinMoviePlotNode of an xarray.DataArray.stores an XarrayImagePlotElement & has methods for plotting & updating the image!“image” refers to a matplotlib.cm.ScalarMappable object, e.g. the result of imshow or pcolormesh.- array: xarray.DataArray, probably ndim=3; or xarray.Dataset with single data_var
- the data to be plotted. if ndim=2, can still plot, but nothing to animate.if xarray.Dataset, must have only one data_var; will create image of that data_var.
- t: None or str
- the array dimension which frames will index. E.g. ‘time’.None -> infer from array & any other provided dimensions.if provided but dimension not found, attempt xarray_promote_dim before crashing.
- x, y: None or str
- if provided, tells dimensions for the x, y plot axes.None -> infer from array & any other provided dimensions.if provided but dimension not found, attempt xarray_promote_dim before crashing.
- 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.
- image_mode: str (‘imshow’ or ‘pcolormesh’) (default: pcolormesh)
- tells whether this image will be pcolormesh or imshow.
- 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.)
- xmargin, ymargin, margin: None or number (greater than -0.5, probably close to 0.05) (default: None)
- margin to use for x/y axis, as a fraction of the data interval for that axis.None –> use matplotlib defaults(e.g., plt.rcParams[“axes.xmargin”] or [“axes.ymargin”], or 0 if using imshow)positive number –> pad around the data region, with this much whitespace.E.g. 0.05 means adding 5% whitespace on each side.Use this to zoom out.negative number –> remove this much of the outer parts of the data region.E.g. -0.2 means removing 20% space from each side.Use this to zoom in.For line plots, if also using
robust, ymargin will be applied to the robust y lims.(margin-related params share the same docstring, but refer to:‘xmargin’: x-axis, ‘ymargin’: y-axis, ‘margin’: x and/or y-axis.) - title: UNSET, None, or str (default: UNSET)
- title for a single axes/subplot. For xarrays, will title.format(**xarray_nondim_coords(array)).(Note: plot_settings[‘title’] should always be the ‘base’ title, before title.format(…))UNSET –> use array_at_current_frame._title_for_slice().None –> do not add a title.
- title_font: UNSET, None, or str (default: UNSET)
- font for title, e.g. ‘serif’, ‘sans-serif’, or ‘monospace’UNSET –> use DEFAULTS.PLOT.MOVIE_TITLE_FONT (default: monospace).None –> use matplotlib default.
- title_y: UNSET, None, or number (default: UNSET)
- y position for title, in axes coordinates.
- title_kw: UNSET, or dict (default: UNSET)
- any additional kwargs for plt.title.
- grid: UNSET, bool, or dict (default: UNSET)
- whether to ax.grid() for each axes.UNSET –> use rcParams[“axes.grid”].True –> ax.grid(True) for all axes.False –> ax.grid(False) for all axes.dict –> ax.grid(**grid) for all axes.
# [TODO] exampleTo view or adjust plot settings in self, see self.plot_settings, or help(self.plot_settings).- __init__(array, t=None, *, x=None, y=None, ax=None, image_mode='pcolormesh', init_plot=True, add_colorbar=UNSET, add_labels=True, title=UNSET, **kw_super)
Methods
__init__(array[, t, x, y, ax, image_mode, ...])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)help()html([show_depth, max_depth, shorthand])infer_xyt_dims(*[, xy_fail_ok, t_fail_ok])init_plots(*[, plotted_ok])make_child(obj)make_children(objs)save(filename[, frames, fps, blit])scatter_max(**kw_scatter)scatter_min(**kw_scatter)set_parent(parent, *[, _internal])update_to_frame(frame)Attributes
DEFAULT_TREE_SHORTHANDDEFAULT_TREE_SHOW_DEPTHDEFAULT_TREE_SHOW_MAX_DEPTHplot_dims_attrs- 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 XarrayImage is 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
XarrayImagePlotElement
- 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 this XarrayImage is 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 {‘array’: array at this frame}, properly transposed & ready for plotting.
- 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
- infer_xyt_dims(*, xy_fail_ok=False, t_fail_ok=True)
- infers (x,y,t) dims from self.x, y, dim.
- xy_fail_ok, t_fail_ok: bool
- controls behavior when failing to infer a dim:True –> return None for that dimFalse –> raise PlottingAmbiguityErrort_fail_ok corresponds to t; xy_fail_ok corresponds to x,y.
see also: DEFAULTS.PLOT.DIMS_INFER, plotting.infer_xyt_dims, infer_xy_dims, infer_movie_dim
- init_plot()
- plot for the first time. Save the XarrayImagePlotElement at 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.
- 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_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.
- scatter_max(**kw_scatter)
- scatter_min(**kw_scatter)
- 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
- the dimension which is actually used to index the movie’s frames (i.e. the “time axis”).setting self.t_plot_dim=value also sets self.{plot_dims_attrs[‘t’]}=value.getting self.t_plot_dim will get self.{plot_dims_attrs[‘t’]} if it is not None;otherwise, infer from self.{plot_dims_attrs[‘dims’]}, self.{plot_dims_attrs[‘x’]}, and self.{plot_dims_attrs[‘y’]}if self.{plot_dims_attrs[‘t_necessary_if’]}(), result might be None.
- 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.
- property x_plot_dim
- the dimension which is actually used to index the plot’s x axis.setting self.x_plot_dim=value also sets self.{plot_dims_attrs[‘x’]}=value.getting self.x_plot_dim will get self.{plot_dims_attrs[‘x’]} if it is not None;otherwise, infer from self.{plot_dims_attrs[‘dims’]}, self.{plot_dims_attrs[‘t’]}, and self.{plot_dims_attrs[‘y’]}.
- property xy_plot_dims
- (self.x_plot_dim, self.y_plot_dim)
- property xyt_plot_dims
- (self.x_plot_dim, self.y_plot_dim, self.t_plot_dim)
- property y_plot_dim
- the dimension which is actually used to index the plot’s y axis.setting self.y_plot_dim=value also sets self.{plot_dims_attrs[‘y’]}=value.getting self.y_plot_dim will get self.{plot_dims_attrs[‘y’]} if it is not None;otherwise, infer from self.{plot_dims_attrs[‘dims’]}, self.{plot_dims_attrs[‘t’]}, and self.{plot_dims_attrs[‘x’]}.