ScatterPlotElement

class PlasmaCalcs.plotting.scatter.ScatterPlotElement(array, x=None, *, ax=None, s=UNSET, markersize=UNSET, facecolors=UNSET, facecolor=UNSET, edgecolors=UNSET, edgecolor=UNSET, linewidths=UNSET, linewidth=UNSET, **kw_super)

Bases: MoviePlotElement

scatter plot.

array: xarray.DataArray, probably ndim=1.: the data to be plotted.

if ndim != 1, must provide x; all other dims will be stacked.
x: None or str: the coordinate to use for x-axis values.

None –> if array ndim==1, use the (first 1D) coord associated with the 1 dim,

(or just use the dim itself, if no such associated coord).

if array ndim!=1, crash with PlottingAmbiguityError.

aliases, provide at most one of each pair:

s, markersize: s from plt.scatter. size of markers. facecolors, facecolor: facecolors from plt.scatter. Color of marker faces in plot. edgecolors, edgecolor: edgecolors from plt.scatter. Color of marker edges in plot. linewidths, linewidth: linewidths from plt.scatter. Width of marker edges in plot.

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)).
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.)

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

Methods

`__init_subclass__`(args_super, *kw)	appends note about using self.plot_settings, to cls.__doc__.
`init_scatter`()	initialize the scatter plot; actually plot the data (probably).
`legend_handle`(*[, label])	returns a matplotlib.lines.Line2D suitable for use as a handle in a legend.
`update_data`(data)	update the plot using data['array'].
`_ensure_x_dim_in_array`(array)	Return array if self.x already a dim, else array.expand_dims(self.x)
`_infer_x`(x, array)	set self.x and self.array.
`_remember_then_remove_old`()	remember any relevant details from the old scatter plot (before removing it).
`_update_kw_from_aliases`(kw, key, **aliases)	update kw[key] = value implied from aliases.

Attributes

`array`	array for plot.
`ax`	the axes containing this scatter plot
`fig`	the figure containing this scatter plot
`scatter`	scatter plot object (matplotlib.collections.PathCollection)

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.

_ensure_x_dim_in_array(array): Return array if self.x already a dim, else array.expand_dims(self.x)

_infer_x(x, array): set self.x and self.array. See help(type(self)) for more details.

_remember_then_remove_old(): remember any relevant details from the old scatter plot (before removing it).

saves self._ax_old and self._kw_old, then does old.remove(), where old=self.scatter.

If self.scatter doesn’t exist, return the saved _ax_old and _kw_old.

returns (self._ax_old, self._kw_old)

_update_kw_from_aliases(kw, key, **aliases): update kw[key] = value implied from aliases.

if multiple aliases’ values are not UNSET, raise InputConflictError.

if all aliases’ values are UNSET, do not update kw[key].

returns the updated value, or UNSET of no update was made.

property array: array for plot. Internally, stored at self.data[‘array’]

property ax: the axes containing this scatter plot

property fig: the figure containing this scatter plot

init_scatter(): initialize the scatter plot; actually plot the data (probably).

stores plotted object in self.scatter and returns self.scatter.

if the array is all nan, plot nothing and return None.

otherwise, set self._plotted_at_least_once = True.

legend_handle(*, label=UNSET)

returns a matplotlib.lines.Line2D suitable for use as a handle in a legend.

Caution: not yet compatible with scatter plots with varying marker colors / sizes.

label: UNSET or str: if not UNSET, use this as the label, instead of self.plot_settings[‘label’]

Example:

handle1 = self.legend_handle()
handle2 = other_scatter_plot.legend_handle()
plt.legend(handles=[handle1, handle2])

One reason to consider using this is that self might plot 0 points on an axis sometimes,

so if creating the legend “automatically” instead, then it wouldn’t show up.

property scatter: scatter plot object (matplotlib.collections.PathCollection)

update_data(data): update the plot using data[‘array’].

return the list of all updated matplotlib Artist objects;

Probably [self.scatter], but might be empty list (if array is all nan).

(if self.init_scatter() didn’t make a plot due to all nan initial values, use that instead.)