XarraySubplots

class PlasmaCalcs.plotting.subplots_extensions.XarraySubplots(array, row=None, col=None, *, wrap=None, x=None, y=None, t=None, fig=None, vmin=None, vmax=None, robust=UNSET, share_vlims=False, title=UNSET, title_y=UNSET, suptitle=UNSET, suptitle_y=UNSET, rtitle=UNSET, ttitle=UNSET, aspect=UNSET, layout=UNSET, cax_mode=UNSET, axsize=UNSET, add_colorbars=True, **kw)

Bases: MovieSubplots, PlotDimsMixin

grid of subplots from array data. Can be animated as a movie!

array: xarray.DataArray or xarray.Dataset

the array to plot. up to 5D (row, col, x, y, t).
(Note that row & col dims should be “not too long” otherwise plot will be very large)
if dataset, up to 4D; will be converted to DataArray with new dim named ‘variable’.
internally, will store xarray_fill_coords(array) to utilize coordless dims’ indices in titles.

row: None, False, or str

coord (1D) to plot ACROSS rows. E.g. row=’fluid’ –> i’th COLUMN is fluid i.
None –> infer automatically from array. row will be inferred before column.
False –> do not use row dimension; result has ncols=1 (unless using wrap).

col: None, False, or str

coord (1D) to plot DOWN columns. E.g. col=’component’ –> j’th ROW is component j.
None –> infer automatically from array.
False –> do not use col dimension; result has nrows=1 (unless using wrap).

wrap: None or int

wrap row or col dimension after this many images.

can only be provided if provided row or col but not both.

E.g. if row==’fluid’, wrap=4, and input has 10 fluids, will make rows of 4, 4, 2 images.

Any remaining “empty” plots will have their axes hidden.

x, y: None or str

x and y axes’ coords for each subplot (each can be at most 2D within each subplot)

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

t: None, False, or str

coord (1D) dimension name for the time axis (for movies).
None –> infer from the array coords. See also: DEFAULTS.PLOT.DIMS_INFER
False –> do not use time dimension; result cannot be animated.

vmin, vmax: None, scalar value, or array-like

if provided, tells value for vmin, vmax for all subplots, ignoring share_vlims and robust.

if providing only one, still use share_vlims and robust for the other

(e.g. if provided vmax but vmin=None, use share_vlims and robust when deciding on vmin).

if array-like vmin, use vmin=vmin[i][j] for plot in i’th row and j’th column. Similar for vmax.

(doesn’t squeeze. e.g., if only 1 row exists, because row=None, then use vmin[0][j])

(if non-None wrap, vlims shape should correspond to the shape after wrapping.)

(use None limit to instead use share_vlims and robust for that subplot.

E.g. vmin=[[0, 2, None]], share_vlims=’row’, robust=10, for subplots with 1 row, 3 cols,

will use vmin=0 for first plot, 2 for second plot,

and vmin=10th percenticle across all values in all three plots, for the third plot.)

share_vlims: bool or str (‘all’, ‘row’, ‘col’) (default: False)

whether to share vmin/vmax across ImageSubplots.
True –> use ‘all’
‘all’ –> share vlims across all image subplots.
‘row’ –> share vlims across each row of image subplots.
‘col’ –> share vlims across each column of image subplots.

robust: UNSET, bool, or number between 0 and 50 (default: UNSET)

use np.percentile when determining vmin/vmax, if robust.
For imshow/image plots, this refers to colorbar lims; for line plots, this refers to y lims.
UNSET –> use DEFAULTS.PLOT.ROBUST (default: True).
False –> just use min and max of values, don’t use percentile.
True –> use DEFAULTS.PLOT.ROBUST_PERCENTILE (default: 2.0)
number –> use np.percentile with this percentile for vmin (and 100 - this percentile for vmax).

axsize: UNSET, number, or (width, height) in inches (default: UNSET)

size of a single subplot, in inches.
UNSET –> use DEFAULTS.PLOT.SUBPLOTS_AXSIZE (default: (2, 2)).
number –> use width = height = axsize.
mutually exclusive with figsize, cannot provide both.

aspect: UNSET, None, str, or number (default: UNSET)

aspect ratio for each Axes, by default.

UNSET –> use DEFAULTS.PLOT.ASPECT (default: equal_or_auto).

None –> use matplotlib defaults; do not otherwise adjust aspect.

str –> ‘equal’, ‘auto’, or ‘equal_or_auto’.

‘equal’ and ‘auto’ get passed directly to matplotlib; ‘equal’ is equivalent to aspect=1.

‘equal_or_auto’ tries to pick ‘equal’, but uses ‘auto’ if aspect is too far from 1,

i.e. if max(data_aspect, 1/data_aspect) < aspect_ratio_max

(default: DEFAULTS.PLOT.ASPECT_RATIO_MAX=20)

number –> height scaling / width scaling.

E.g. aspect=2 –> 1 data unit of height is twice long as 1 data unit of width.

layout: UNSET, None, or str (default: UNSET)

layout for subplots, by default.
Suggestion: use layout=’compressed’, make_cax=’mpl’, and tweak wspace & hspace,
OR use layout=’none’, make_cax=’pc’, and tweak suptitle_y, left, top, and bottom.
UNSET –> use DEFAULTS.PLOT.LAYOUT (default: compressed).
None –> use matplotlib defaults.
str –> should be ‘constrained’, ‘compressed’, ‘tight’, or ‘none’.

suptitle: UNSET, None, or str (default: UNSET)

suptitle for a single axes/subplot. For xarrays, will suptitle.format(**xarray_nondim_coords(array)).
(Note: plot_settings[‘suptitle’] should always be the ‘base’ suptitle, before suptitle.format(…))
UNSET –> use self.default_suptitle. For XarraySubplots this includes information about t_plot_dim.
None –> use no suptitle.
(Note - self.plot_settings[‘suptitle’] will always be the ‘base’ suptitle, before applying suptitle_format.)

suptitle_y: UNSET, None, or number (default: UNSET)

y position for suptitle, in figure coordinates.

suptitle_font: UNSET, None, or str (default: UNSET)

font for suptitle, e.g. ‘serif’, ‘sans-serif’, or ‘monospace’
UNSET –> use DEFAULTS.PLOT.MOVIE_TITLE_FONT (default: monospace).
None –> use matplotlib default.

suptitle_kw: UNSET, or dict (default: UNSET)

any additional kwargs for plt.suptitle.

suptitle_width: UNSET, None, or number (default: UNSET)

suggested width [number of characters] for suptitle;
default routines might make multiline suptitle to avoid going longer than this.
UNSET –> use DEFAULTS.PLOT.SUPTITLE_WIDTH (default: 40).
None –> no maximum width.

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() if XarrayImage (or other single-array plot).

use XarraySubplotTitlesInferer.infer_title() if XarraySubplots (or other multi-array plot).

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.

subplot_title_width: UNSET, None, or number (default: UNSET)

suggested width [number of characters] for subplot titles;
default title routines might make multiline title if title would be longer than this.
UNSET –> use DEFAULTS.PLOT.SUBPLOT_TITLE_WIDTH (default: 20).
None –> no maximum width.

rtitle: UNSET or str (default: UNSET)

rightmost-column ‘title’ to put only on righthand side of subplots on the rightmost column.
For xarrays, will rtitle.format(**xarray_nondim_coords(array)).
Note: rtitles created via PlasmaCalcs’ plot_note(), which uses plt.annotate, not plt.ylabel().
UNSET –> do not add rtitle.

rtitle_kw: UNSET, or dict (default: UNSET)

any additional kwargs for plot_note() when making rtitle.
(note: includes font=plot_settings[‘title_font’] unless fontfamily specified in rtitle_kw.)
(note: to specify location, use loc or xy in axes coords or as str; see plot_note() for details.)
UNSET –> use DEFAULTS.PLOT.RTITLE_KW (default: {‘rotation’: 270, ‘loc’: ‘outside center right’, ‘fontsize’: ‘large’}).

ttitle: UNSET or str (default: UNSET)

topmost-row title to put only on subplots in the top row.
For xarrays, will ttitle.format(**xarray_nondim_coords(array)).
Mutually exclusive with providing title, and overrides default titles if provided.
UNSET –> do not add ttitle.

ttitle_kw: UNSET, or dict (default: UNSET)

any additional kwargs for plt.title when making ttitle.
(note: includes font=plot_settings[‘title_font’] unless fontfamily specified in ttitle_kw.)
UNSET –> use DEFAULTS.PLOT.TTITLE_KW (default: {}).
None –> use no title.

cax_mode: UNSET, ‘mpl’, ‘pc’ (default: UNSET)

tells how to make a new axis for a colorbar if one was not provided.

UNSET –> use DEFAULTS.PLOT.CAX_MODE (default: mpl).

‘mpl’ –> use matplotlib logic, the same exact logic as in plt.colorbar.

‘pc’ –> use PlasmaCalcs logic; it looks better when using layout=’none’,

however ‘pc’ logic doesn’t play nicely with other layout options yet.

colorbar_kw: unset or dict (default: UNSET)

any additional kwargs for plt.colorbar.

add_colorbars: UNSET, bool, or str (default: True)

whether to add colorbars during init_plot, for ImageSubplots.

str –> use self.colorbars(mode=add_colorbars). E.g. ‘auto’, ‘all’, ‘row’.

additional kwargs go to other places [TODO][DOC] fill in the details.

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

Methods

`__call__`(frame)	update the plot for the given frame.
`__getitem__`(i)	returns self.children[i].
`__init_subclass__`(args_super, *kw)	appends note about using self.plot_settings, to cls.__doc__.
`__iter__`()	iterates over self.children.
`__len__`()	return len(self.axs)
`add_child`(child)	adds this child (a Tree) to self.children.
`apply_misc_formatting`()	apply misc formatting according to self.plot_settings.
`ax_apply`(f, *[, sca])	return numpy array of f(ax) applied to each ax.
`ax_cbars`(*[, no_image, no_cbar])	return array of colorbars associated with images on each ax.
`ax_images`(*[, fill_value])	return array of the image on each ax (or fill_value if no image on that ax).
`color_scheme_matches`(im0, im1)	return whether color for im0 matches color scheme for im1
`colorbar`([mappable, cax, ax, location, ...])	create a colorbar, like plt.colorbar(), but using Colorbar class instead.
`colorbars`([mode])	create colorbars for each image in self.
`colorbars_at`([slice, sca, missing_ok, ...])	create colorbars for each ax in self.iter_ax(slice), using self.colorbar(...).
`colorbars_col`(icol, **kw_colorbars_at)	create colorbars for each ax in column icol, using self.colorbars_at(...).
`colorbars_row`(irow, **kw_colorbars_at)	create colorbars for each ax in row irow, using self.colorbars_at(...).
`display`([show_depth, max_depth, shorthand])	display self in html.
`enumerate_flat`(*[, include_self])	returns a generator which iterates over all of self's descendants, in depth-first order,
`find_mappable`([ax, im])	return the relevant mappable.
`flat`(*[, include_self])	returns a generator which iterates over all of self's descendants, in depth-first order.
`flat_branches_until`(branches_until, *[, ...])	returns a generator which iterates over all of self's descendants, in depth-first order,
`get_animator`(*[, fps, blit, frames, plt_close])	returns FuncAnimation instance using self as func.
`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.
`get_nframes_here`()	return the number of frames that could be in the movie, based on this node.
`grid`(args_grid, *kw_grid)	ax.grid(...) on all axs
`has_node_where`(condition, *[, include_self])	returns True if any node in self or descendants satisfies condition(node).
`help`()	prints a helpful message with examples for how to use this cls
`hide_empty_axes`()	hide axes (ax.set_visible(False)) without any data (check via ax.has_data())
`html`([show_depth, max_depth, shorthand])	returns html for displaying self and all of self's children.
`init_plot`()	plot for the first time: call init_plot on all nodes,
`init_plots`(*[, plotted_ok])	init_plot for self & all descendants with non-None obj.
`iter_ax`([slice, sca, restore, skip])	iterate over axs, one at a time, yielding ((irow, icol), ax) for each ax.
`iter_cbars`()	iterate across axs, yielding ((irow, icol), cbar) for each ax with a colorbar.
`iter_col`(icol, *[, sca, restore])	iterate over axs in column icol, yielding ((irow, icol), ax) for each ax.
`iter_images`()	iterate across axs, yielding ((irow, icol), image) for each ax with an image.
`iter_row`(irow, *[, sca, restore])	iterate over axs in row irow, yielding ((irow, icol), ax) for each ax.
`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.
`plot_rtitles`()	adds rtitles (as MovieText node objects) via plot_note() on right-hand-side of right-most images.
`plot_suptitle`()	adds suptitle (as a MovieText node)
`remove_redundant_labels`([which, ignore_empty])	remove labels which are redundant, e.g. ticklabels,.
`rightmost_images`(*[, as_idx])	list of rightmost existing image (i.e., non-None) in each row.
`save`(filename[, frames, fps, blit])	save the movie to filename.
`sca`(irow, icol)	set current axis to self.axs[irow, icol]
`scatter_max`(**kw_scatter)	use XarrayScatter to plt.scatter() a marker at argmax of each subplot image's array.
`scatter_min`(**kw_scatter)	use XarrayScatter to plt.scatter() a marker at argmin of each subplot image's array.
`scatter_where`(condition, **kw_scatter)	use XarrayScatter to plt.scatter() markers where condition is True.
`set_min_n_ticks`([min_n_ticks])	set_min_n_ticks on all axs.
`set_parent`(parent, *[, _internal])	sets self.parent = parent.
`set_updater`(irow, icol, updater)	set updater on ax[irow, icol] to updater
`subplots_adjust`(**kw)	plt.subplots_adjust, using values from self.plot_settings by default.
`subplots_figsize`([nrows, ncols, axsize, ...])	returns figsize to use for subplots so that every subplot has size axsize.
`update_to_frame`(frame)	update the plot for the given frame.
`updaters`(*[, fill_value])	return array of updaters for each ax (or fill_value if no updater on that ax).
`xlabel`(xlabel[, mode, only])	set xlabel on relevant axs, or as supxlabel.
`ylabel`(ylabel[, mode, only])	set ylabel on relevant axs, or as supylabel.
`_calculate_vlims`(values, *[, vmin, vmax, ...])	return the calculated vmin, vmax, for all of these values.
`_colorbars_auto`(**kw_colorbars_at)	create colorbars for each image in self.
`_get_array_grid`(array[, row, col, wrap])	return array of xarray.DataArray objects, organized into a grid.
`_get_common_label`(x, iline, *[, ignore_empty])	return the x or y label shared by all nonempty plots in this line, or None if that's impossible.
`_get_common_tick_info`(x, iline, *[, ...])	return the x or y tick_info shared by all nonempty plots in this line, or None if that's impossible.
`_get_frames`(value)	gets frames based on value and possibly self.get_nframes() if necessary.
`_get_vlims_arr`([arrs, vmin, vmax, ...])	return array of vmin, vmax, for each array in arrs.
`_init_plot_checks`()	checks to run before init_plot().
`_make_plot_dims`()	returns plot_dims from plot_dims_inputs and PLOT_DIMS_EXPECTING.
`_on_added_child`(child)	called immediately after adding a child to self.
`_on_added_descendant`(descendant)	called immediately after adding a descendant to self (or any of self.children).
`_on_adding_ancestor`(ancestor)	called immediately before adding an ancestor to self (i.e., self.parent, parent of self.parent, etc)
`_on_setting_parent`(parent)	called immediately before setting self.parent = parent.
`_remove_redundant_labels`(x, *[, ignore_empty])	remove xlabels or ylabels in self which are redundant, i.e. same across col (if 'x') or row (if 'y').
`_remove_redundant_ticklabels`(x, *[, ...])	remove x or y ticklabels in self which are redundant, i.e. same across col (if 'x') or row (if 'y').
`_repr_html_`()	returns html string for displaying self.
`_shorthand_repr`()	returns shorthand repr for this node (without children).

Attributes

`DEFAULT_TREE_SHORTHAND`
`DEFAULT_TREE_SHOW_DEPTH`
`DEFAULT_TREE_SHOW_MAX_DEPTH`
`PLOT_DIMS_EXPECTING`
`ani`	alias to get_animator
`ax_idx`	array of indices (irow, icol), with same shape as axs array, dtype=object
`axes_class`
`axs`	array of axes objects.
`cache_state`	int, associated with cached results.
`cbars`	list of colorbars appearing on any ax across self.
`depth`	number of layers above self.
`fig`	the Figure on which self is / will be plotted.
`frame`	the currently-plotted frame
`frames`	the frames that could be in the movie.
`height`	number of layers below self.
`image0`	top-left image; images[0,0].
`images`	alias to nodes
`isels`	np.array (dtype=object) of (None or dict of index details), one for each subplot.
`ncols`	number of columns in axs array.
`nrows`	number of rows in axs array.
`parent`	parent node of self.
`parent_ref`	stores parent value, but internally uses weakref to avoid circular references.
`plot_dims`	PlotDimsInferrer for this plotting object.
`plot_dims_inputs`	inputs for creating self.plot_dims.
`plotted`	whether this node's element has actually been plotted yet.
`plotted_data`	the currently plotted data.
`shape`	shape of axs array, as (nrows, ncols).
`size`	number of nodes in this tree.

__call__(frame): update the plot for the given frame. return iterable of all updated artists.

Defining __call__ in this way means self is compatible for direct use by FuncAnimation.

__getitem__(i): returns self.children[i]. If i is a tuple, index repeatedly, e.g. self[i[0]][i[1]][i[2]]…

classmethod __init_subclass__(*args_super, **kw): appends note about using self.plot_settings, to cls.__doc__.

if “PlotSettings” or “plot_settings” appears in cls.__doc__, do NOT append this note;

assuming instead that this means the doc already mentions how to use plot_settings.

__iter__(): iterates over self.children.

__len__(): return len(self.axs)

static _calculate_vlims(values, *, vmin=None, vmax=None, robust=False, to_dict=False, expand_flat=True)

return the calculated vmin, vmax, for all of these values.

values: array-like or list of array-like objects

the values to use for calculating the vlims.

if list of array-like objects, the array-like objects may be of different shapes.

vmin, vmax: None or value

if provided, use this value for vmin, vmax. Otherwise, calculate it.

robust: UNSET, bool, or number between 0 and 50 (default: UNSET)

use np.percentile when determining vmin/vmax, if robust.
For imshow/image plots, this refers to colorbar lims; for line plots, this refers to y lims.
UNSET –> use DEFAULTS.PLOT.ROBUST (default: True).
False –> just use min and max of values, don’t use percentile.
True –> use DEFAULTS.PLOT.ROBUST_PERCENTILE (default: 2.0)
number –> use np.percentile with this percentile for vmin (and 100 - this percentile for vmax).

to_dict: bool

if True, return dict(vmin=vmin, vmax=vmax) instead of (vmin, vmax)

expand_flat: bool

if True, and computed vmin > vmax, and provided vmin or vmax but not both,

then adjust the not-provided value such that vmin > vmax. I.e.:

provided vmin –> use vmax = vmin + 0.05. (this matches matplotlib default when vmin=vmax)

provided vmax –> use vmin = vmax - 0.05. (this matches matplotlib default when vmin=vmax)

_colorbars_auto(**kw_colorbars_at): create colorbars for each image in self. Equivalent to self.colorbars(mode=’auto’, …).

infer where to put colorbars by checking which images have equal im.get_clim() and im.cmap.

for rows where all subplots have the same clim and cmap, put colorbar at right.

_get_array_grid(array, row=UNSET, col=UNSET, wrap=UNSET): return array of xarray.DataArray objects, organized into a grid.

E.g. when wrap=None, result[i,j] = self.array.isel({row: i, col: j}).

see help(type(self)) for details on row, col, wrap.

if row or col is UNSET, get value from self.plot_dims.row_coord, col_coord.

if wrap is UNSET, get value from self.wrap

_get_common_label(x, iline, *, ignore_empty=True): return the x or y label shared by all nonempty plots in this line, or None if that’s impossible.

x: ‘x’ or ‘y’.

iline: int, index of the line to check. (icol if ‘x’, irow if ‘y’)

ignore_empty: bool, whether to ignore axes in this column which have no data.

_get_common_tick_info(x, iline, *, ignore_empty=True): return the x or y tick_info shared by all nonempty plots in this line, or None if that’s impossible.

tick_info is (xticklocs, xticklabels, xlim) (or y if x=’y’), with str xticklabels (not Text objects).

x: ‘x’ or ‘y’.

iline: int, index of the line to check. (icol if ‘x’, irow if ‘y’)

ignore_empty: bool, whether to ignore axes in this column which have no data.

_get_frames(value): gets frames based on value and possibly self.get_nframes() if necessary.

if result would be None, crash instead.

_get_vlims_arr(arrs=None, *, vmin=None, vmax=None, share_vlims=False, robust=UNSET): return array of vmin, vmax, for each array in arrs.

arrs: None or array of arrays.

if None, use self.arrs.

vmin, vmax: None, value, or array-like with same shape as arrs

if provided, use this value for vmin, vmax for all subplots, ignoring share_vlims and robust.

See help(type(self)) for more details.

share_vlims: bool or str (‘all’, ‘row’, ‘col’) (default: False)

whether to share vmin/vmax across ImageSubplots.

True –> use ‘all’

‘all’ –> share vlims across all image subplots.

‘row’ –> share vlims across each row of image subplots.

‘col’ –> share vlims across each column of image subplots.

robust: UNSET, bool, or number between 0 and 50 (default: UNSET)

use np.percentile when determining vmin/vmax, if robust.

For imshow/image plots, this refers to colorbar lims; for line plots, this refers to y lims.

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

False –> just use min and max of values, don’t use percentile.

True –> use DEFAULTS.PLOT.ROBUST_PERCENTILE (default: 2.0)

number –> use np.percentile with this percentile for vmin (and 100 - this percentile for vmax).

_init_plot_checks(): checks to run before init_plot().

Here, checks:

- if self.plotted, raise PlottingAmbiguityError.

- if self.obj is None, raise PlottingAmbiguityError.

_make_plot_dims(): returns plot_dims from plot_dims_inputs and PLOT_DIMS_EXPECTING.

_on_added_child(child): called immediately after adding a child to self.

Tracks depth, height, size. This method does not connect any parents or children.

_on_added_descendant(descendant): called immediately after adding a descendant to self (or any of self.children).

Tracks depth, height, size. This method does not connect any parents or children.

_on_adding_ancestor(ancestor): called immediately before adding an ancestor to self (i.e., self.parent, parent of self.parent, etc)

Tracks depth, height, size. This method does not connect any parents or children.

_on_setting_parent(parent): called immediately before setting self.parent = parent.

Tracks depth, height, size. This method does not connect any parents or children.

_remove_redundant_labels(x, *, ignore_empty=True): remove xlabels or ylabels in self which are redundant, i.e. same across col (if ‘x’) or row (if ‘y’).

x: ‘x’ or ‘y’.

ignore_empty: bool, whether to ignore axes in this column which have no data.

_remove_redundant_ticklabels(x, *, ignore_empty=True): remove x or y ticklabels in self which are redundant, i.e. same across col (if ‘x’) or row (if ‘y’).

x: ‘x’ or ‘y’.

ignore_empty: bool, whether to ignore axes in this column which have no data.

_repr_html_()

returns html string for displaying self. (this display hook is used by Jupyter automatically.).

Includes self.html() and DEFAULTS.TREE_CSS.

[TODO] apply the css to ONLY this output cell in Jupyter, instead of all output cells…

_shorthand_repr(): returns shorthand repr for this node (without children).

returns ‘— name —’ if self.name provided, else “((depth, height, 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

apply_misc_formatting(): apply misc formatting according to self.plot_settings.

ax_apply(f, *, sca=True): return numpy array of f(ax) applied to each ax. result has dtype=object.

if sca, call plt.sca() before working on each ax.

ax_cbars(*, no_image=None, no_cbar=False): return array of colorbars associated with images on each ax.

for ax with no image, value will be no_image (default None).

for ax with image but no colorbar, value will be no_cbar (default False).

property ax_idx: array of indices (irow, icol), with same shape as axs array, dtype=object

ax_images(*, fill_value=None): return array of the image on each ax (or fill_value if no image on that ax).

property axs: array of axes objects.

property cache_state: int, associated with cached results.

property cbars: list of colorbars appearing on any ax across self.

equivalent: [cbar for ((irow, icol), cbar) in self.iter_cbars()]

static color_scheme_matches(im0, im1): return whether color for im0 matches color scheme for im1

static colorbar(mappable=None, *, cax=None, ax=None, location=None, size=None, pad=None, **kw_colorbar_here): create a colorbar, like plt.colorbar(), but using Colorbar class instead.

mappable: None or mpl.cm.ScalarMappable

the mappable for this colorbar.

if None, attempt to find it using find_mappable(ax=ax, im=mappable).

cax: None or axes object

the axes for this colorbar.

None –> use make_cax(…), or make cax using mpl_get_cax(…), depending on cax_mode.

kwargs for make_cax would be:

ax, location, sca, ticks_position, pad, size, **kw_add_axes.

cax_mode: UNSET, ‘mpl’, ‘pc’ (default: UNSET)

tells how to make a new axis for a colorbar if one was not provided.

UNSET –> use DEFAULTS.PLOT.CAX_MODE (default: mpl).

‘mpl’ –> use matplotlib logic, the same exact logic as in plt.colorbar.

‘pc’ –> use PlasmaCalcs logic; it looks better when using layout=’none’,

however ‘pc’ logic doesn’t play nicely with other layout options yet.

location: None, ‘right’, ‘left’, ‘top’, or ‘bottom’

location of colorbar relative to image.

None –> use DEFAULTS.PLOT.CAX_LOCATION (default: right)

also passed to super().__init__, so that orientation is set appropriately.

The following are relevant if cax not provided, and using cax_mode=’mpl’:

sca: bool (default False)

whether to adjust the plt.gca() to cax.

False –> plt.gca() will be unchanged by this operation.

ticks_position: None (default), ‘right’, ‘left’, ‘top’, or ‘bottom’

None -> ticks are on opposite side of colorbar from image.

string -> use this value to set ticks position.

pad: None or number (default 0.01)

padding between cax and ax, as a percentage of ax size.

None –> use DEFAULTS.PLOT.CAX_PAD (default: 0.01)

size: None or number (default 0.02)

size of colorbar, as a percentage of ax size.

None –> use DEFAULTS.PLOT.CAX_SIZE (default: 0.02)

kw_add_axes: dict

passed to make_cax(…, **kw_add_axes)… which passes it to plt.gcf().add_axes().

additional kwargs get passed to matplotlib.colorbar.Colorbar.__init__.

colorbars(mode='auto', **kw_colorbars_at): create colorbars for each image in self.

mode: True, ‘auto’, ‘all’, ‘row’, slice, or tuple

tells where to create the colorbars.

True –> use mode=’auto’

‘auto’ –> infer, by checking which images have equal im.get_clim() and im.cmap.

For rows where all image subplots have the same clim and cmap, mode=’row’

(unless the right-most in row has no image; then use mode=’all’).

‘all’ –> each image gets its own colorbar.

‘row’ –> each row gets its own colorbar, at the right-most image in the row.

slice or tuple –> self.colorbars_at(slice, …)

# [TODO] add ‘col’ option, for horizontal colorbars at top of columns.

# [TODO] add ‘single’ option, for one tall colorbar on the right of figure.

# [TODO] make_shared_cax() which makes a tall colorbar with same height as multiple axes.

colorbars_at(slice=None, *, sca=False, missing_ok=True, iter_ax='all', location=None, ticks_position=None, pad=None, size=None, kw_add_axes={}, **kw_colorbar): create colorbars for each ax in self.iter_ax(slice), using self.colorbar(…).

slice: None, int, slice, or tuple

if provided, only include the axes from axs[slice].

when in this mode, (irow, icol) will still correspond to self.axs[(irow, icol)],

(not self.axs[slice][irow, icol]).

sca: bool

whether to set current axis to the last-created colorbar, after the operation is complete.

False –> afterwards, plt.gca() will be restored to what it was before this operation began.

missing_ok: bool

whether it is okay for some axs to not have a mappable.

iter_ax: ‘all’, ‘row’, or ‘col’

which axes to iterate over.

slice will be passed to the appropriate iter func. E.g. ‘row’ –> iter_row(slice, …)

The remaining kwargs go to self.colorbar(…):

location: None, ‘right’, ‘left’, ‘top’, or ‘bottom’

location of colorbar relative to image.

None –> use DEFAULTS.PLOT.CAX_LOCATION (default: right)

ticks_position: None (default), ‘right’, ‘left’, ‘top’, or ‘bottom’

None -> ticks are on opposite side of colorbar from image.

string -> use this value to set ticks position.

pad: None or number (default 0.01)

padding between cax and ax, as a percentage of ax size.

None –> use DEFAULTS.PLOT.CAX_PAD (default: 0.01)

size: None or number (default 0.02)

size of colorbar, as a percentage of ax size.

None –> use DEFAULTS.PLOT.CAX_SIZE (default: 0.02)

kw_add_axes: dict

passed to make_cax(…, **kw_add_axes)… which passes it to plt.gcf().add_axes().

colorbars_col(icol, **kw_colorbars_at): create colorbars for each ax in column icol, using self.colorbars_at(…).

Equivalent to self.colorbars_at(icol, iter_ax=’col’, …)

colorbars_row(irow, **kw_colorbars_at): create colorbars for each ax in row irow, using self.colorbars_at(…).

Equivalent to self.colorbars_at(irow, iter_ax=’row’, …)

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: the Figure on which self is / will be plotted.

static find_mappable(ax=None, *, im=None): return the relevant mappable. By default, return plt.gci().

if plt.gci() is None, instead attempt to find a mappable on plt.gca();

if there is exactly 1, return it, else raise PlottingError.

the error will be MappableNotFoundError if 0, else PlottingAmbiguityError.

providing im uses im instead of plt.gci()

providing ax using ax instead of plt.gca() (only if didn’t provide im)

ax: None or axes object

if provided, use ax.findobj to find mappable.

(cannot provide both ax and im)

if None, check plt.gci() first, then use findobj if that is also None.

im: None or mappable.

if provided, return it.

if None, attempt plt.gci(); returning it if that is not None

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.

grid(*args_grid, **kw_grid): ax.grid(…) on all axs

has_node_where(condition, *, include_self=False): returns True if any node in self or descendants satisfies condition(node).

if include_self, check self as well.

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

hide_empty_axes(): hide axes (ax.set_visible(False)) without any data (check via ax.has_data())

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

property image0: top-left image; images[0,0].

property images: alias to nodes

init_plot(): plot for the first time: call init_plot on all nodes,

and organize into a nice tree structure which can be indexed like an array.

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 isels: np.array (dtype=object) of (None or dict of index details), one for each subplot.

E.g. full_array.isel(self.isels[1,4]) == self.images[1,4].array.

iter_ax(slice=None, *, sca=True, restore=True, skip=None): iterate over axs, one at a time, yielding ((irow, icol), ax) for each ax.

slice: None, int, slice, or tuple

if provided, only include the axes from axs[slice].

when in this mode, (irow, icol) will still correspond to self.axs[(irow, icol)],

(not self.axs[slice][irow, icol]).

sca: bool

if True, call plt.sca(ax) before yielding each ax.

restore: bool

if True, restore original plt.gca() after iteration is stopped.

skip: None or callable of ((irow, icol), ax) –> bool

if provided, skip axes for which skip(irow, icol, ax) returns True.

iter_cbars(): iterate across axs, yielding ((irow, icol), cbar) for each ax with a colorbar.

(axs without colorbars will be skipped.)

iter_col(icol, *, sca=True, restore=True, **kw_iter_ax): iterate over axs in column icol, yielding ((irow, icol), ax) for each ax. See also: self.iter_ax

icol: int or slice

column index(es) to iterate over. Can be negative int, e.g. -1 will be the rightmost column.

bool

if True, call plt.sca(ax) before yielding each ax.

bool

if True, restore original plt.gca() after iteration is stopped.

iter_images(): iterate across axs, yielding ((irow, icol), image) for each ax with an image.

(axs without image will be skipped.)

iter_row(irow, *, sca=True, restore=True, **kw_iter_ax): iterate over axs in row irow, yielding ((irow, icol), ax) for each ax. See also: self.iter_ax

irow: int or slice

row index(es) to iterate over. Can be negative int, e.g. -1 will be the bottom row.

bool

if True, call plt.sca(ax) before yielding each ax.

bool

if True, restore original plt.gca() after iteration is stopped.

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 ncols: number of columns in axs array.

property nrows: number of rows in axs array.

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 plot_dims: PlotDimsInferrer for this plotting object.

Created from plot_dims_inputs and PLOT_DIMS_EXPECTING.

See help(self.plot_dims_inferrer_cls) for more details.

plot_dims_inferrer_cls: alias of PlotDimsInferrer

property plot_dims_inputs: inputs for creating self.plot_dims.

(Internally actually uses PlotDimsInferrer._translate_inputs(plot_dims_inputs);

provide _skip_translation=True to skip the normal translation rules.)

plot_rtitles(): adds rtitles (as MovieText node objects) via plot_note() on right-hand-side of right-most images.

(only if self.plot_settings[‘rtitle’] is not UNSET.)

plot_suptitle(): adds suptitle (as a MovieText node)

raise PlottingAmbiguityError if suptitle already plotted

(this prevents having multiple suptitle 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.

remove_redundant_labels(which=['x', 'y'], *, ignore_empty=True): remove labels which are redundant, e.g. ticklabels,

ylabels except in left col, xlabels except in bottom row.

if sharexlike=False or shareylike=False, will not remove the corresponding labels.

if self.plot_settings[‘polar’], keep xticklabels (i.e. angles) on top row instead of bottom.

which: iterable of str in (‘x’, ‘y’)

which labels to remove. Default: (‘x’, ‘y’)

ignore_empty: bool

whether to ignore empty axes (checked via ax.has_data())

rightmost_images(*, as_idx=False, missing_ok: True): list of rightmost existing image (i.e., non-None) in each row.

as_idx: bool

whether to return indices of images within self.images, instead of image objects.

missing_ok: bool

whether it is okay for some row to have no images (result will be None in those rows).

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.

sca(irow, icol): set current axis to self.axs[irow, icol]

scatter_max(**kw_scatter): use XarrayScatter to plt.scatter() a marker at argmax of each subplot image’s array.

animatable (e.g. different max for each frame); for each image, image.add_child(scatter result).

default style: {**DEFAULTS.PLOT.SCATTER_STYLE, **DEFAULTS.PLOT.SCATTER_MAX}

returns np.array with same shape as self, containing the results of XarrayScatter calls.

scatter_min(**kw_scatter): use XarrayScatter to plt.scatter() a marker at argmin of each subplot image’s array.

animatable (e.g. different max for each frame); for each image, image.add_child(scatter result).

default style: {**DEFAULTS.PLOT.SCATTER_STYLE, **DEFAULTS.PLOT.SCATTER_MAX}

returns np.array with same shape as self, containing the results of XarrayScatter calls.

scatter_where(condition, **kw_scatter): use XarrayScatter to plt.scatter() markers where condition is True.

animatable (e.g. different max for each frame); for each image, image.add_child(scatter result).

condition: callable or DataArray of bools

callable –> use condition(arr) for each image in self, where arr=image.array.

DataArray –> use condition.isel(ii) for each image in self,

where ii is the corresponding dict of indices from self.isels.

returns np.array with same shape as self, containing the results of XarrayScatter calls.

Example:

xsubs = array.pc.image(…)

xsubs.scatter_where(lambda arr: arr > 7.5) # markers at all values larger than 7.5

xsubs.save(filename) # save animation to filename (if xsubs.plot_dims.t_coord is not None)

set_min_n_ticks(min_n_ticks=UNSET): set_min_n_ticks on all axs.

Use min_n_ticks from self.plot_settings if not provided here.

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.

set_updater(irow, icol, updater): set updater on ax[irow, icol] to updater

property shape: shape of axs array, as (nrows, ncols).

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

size = 1 for a node with no children.

subplots_adjust(**kw): plt.subplots_adjust, using values from self.plot_settings by default.

Note: adjusts the parameters for self.fig, not necessarily plt.gcf().

plt.subplots_adjust docs:

————————-

<function subplots_adjust at 0x755d5c390b80>

static subplots_figsize(nrows=1, ncols=1, axsize=None, *, left=None, right=None, bottom=None, top=None, wspace=None, hspace=None): returns figsize to use for subplots so that every subplot has size axsize.

axsize: None, number, or (width, height)

size of a single subplot, in inches.

if None, use DEFAULTS.PLOT.SUBPLOTS_AXSIZE.

if number, use width=height=axsize.

left, right, bottom, top, wspace, hspace: None or number (probably between 0 and 1)

corresponding value that will be used during plt.subplots_adjust;

figsize must be adjust accordingly to account for whitespace between and around subplots.

None –> plt.rcParams[‘figure.subplot.left’], plt.rcParams[‘figure.subplot.right’], etc.

left, right, bottom, top: tell position of edge of subplots grid, as fraction of figure width / height.

wspace, hspace: tell width of padding between subplots, as fraction of axsize width / height.

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.

updaters(*, fill_value=None): return array of updaters for each ax (or fill_value if no updater on that ax).

xlabel(xlabel, mode=None, *, only=True, **kw): set xlabel on relevant axs, or as supxlabel.

mode: None or str in (‘edge’, ‘all’, ‘sup’)

None –> use self.xlabel_mode

‘edge’ –> only set xlabel on axs in bottom row

‘all’ –> set xlabel on all axs.

‘sup’ –> set xlabel on self.fig, as supxlabel.

only: bool, default True

if only, then also set xlabel to ‘’ on all other axes.

kwargs are passed to ax.set_xlabel or fig.supxlabel, as appropriate.

ylabel(ylabel, mode=None, *, only=True, **kw): set ylabel on relevant axs, or as supylabel.

mode: None or str in (‘edge’, ‘all’, ‘sup’)

None –> use self.xlabel_mode

‘all’ –> set ylabel on all axs.

‘sup’ –> set ylabel on self.fig, as supylabel.

only: bool, default True

if only, then also set ylabel to ‘’ on all other axes.

kwargs are passed to ax.set_ylabel or fig.supylabel, as appropriate.