PlotDimsInferrer

class PlasmaCalcs.plotting.plot_tools.plot_dims.PlotDimsInferrer(coords_or_array=UNSET, *, coords=UNSET, array=UNSET, xy_2D_ok=True, x=ATTR_UNSET, y=ATTR_UNSET, t=UNSET, row=ATTR_UNSET, col=ATTR_UNSET, others=ATTR_UNSET, expecting=UNSET, _prioritize_row_if_small=False, DIMS_INFER=UNSET)

Bases: object

manages inferring dims (or maybe 2D+ coords!) to use for plotting.

Parameters below, followed by explanation of non-str options.

Note that explicitly-provided selections can be implicitly-creatable;

e.g. ‘log_x’ or ‘x_index’ from ‘x’. All options (for any d in coords) are:

‘log_d’ –> log10 of d’s values

‘d_index’ –> np.arange(array.sizes[d]) if 1D, else array of tuples telling ndindex.

‘str_d’ –> str(v) for v in d’s values. (E.g. useful if d has object values)

coords_or_array: UNSET, xarray.DataArray or Dataset, list of str, or dict of (str or list of str)

xarray.DataArray or other way to indicate all possible dims and 1D+ coords.

Order matters only as a last resort for inferring a dim from otherwise-equal-priority coords.

UNSET –> provide coords or array instead.

DataArray or Dataset –> coords = xarray_coords_dims(array, include_coordless_dims=True)

list of str –> list of dim names.

dict –> mapping from coord/dim or list of dims associated with coord/dim.

(for key d which is already a dim, value should just be [d].)

coords: UNSET, list of str, or dict of (str or list of str)

same as coords_or_array, but only for coords.

UNSET –> provide array or coords_or_array instead.

array: UNSET or xarray.DataArray or Dataset

same as coords_or_array, but only for array.

UNSET –> provide coords or coords_or_array instead.

xy_2D_ok: bool

whether to allow x and y to correspond to 2D coordinates, instead of dims.

False –> x and y must correspond to 1D coords or dims.

x, y: ATTR_UNSET, UNSET, False, None, or str

coords or dims for x and y axes of the plot.

x, y must be 1D or 2D (e.g. for pcolormesh) within each subplot (i.e. after removing row & col dims).

row, col: ATTR_UNSET, UNSET, False, None, or str

dims to iterate over across subplot rows / down subplot columns.

row, col must be 1D.

row = dim to plot ACROSS rows, e.g. if row=’fluid’ then i’th column is i’th fluid.

col = dim to plot DOWN columns, e.g. if col=’component’ then i’th row is i’th component.

t: UNSET, False, None, or str

dim for time dimension of the plot (frames of a movie).

t must be 1D.

others: ATTR_UNSET, UNSET, False, None, or list of strs

other dims (or coordinates) to use for plotting, which may be used by other kinds of routines.

e.g., might put others=[‘line_number’] for a line plot with multiple lines.

each coord in others must be 1D (for now).

expecting: UNSET or str

shorthand to specify whether x, y, row, col, and other(s) should default to False or to None,

if they are not provided (i.e. if they are still the default of ATTR_UNSET).

For all options, see cls.EXPECTING_OPTIONS. Examples include:

‘image’ –> x=y=None, row=col=False, others=False

‘image_subplots’ –> x=y=None, row=col=UNSET, others=False

‘get_maybe_t’ –> x=y=row=col=False, others=UNSET

‘lines’ –> x=None, y=False, row=col=False, others=UNSET

_prioritize_row_if_small: False or (True or int, dict of dim sizes)

whether to prioritize inferring ‘row’ before ‘t’ if both would otherwise have the same priority level

(i.e. both UNSET or both None) and inferred row would be “small” in size.

“small” determined by int if input, else DEFAULTS.PLOT.SUBPLOTS_MAX_NROWS_NCOLS.

This rule is applied at a late stage of the inferring process,

(after trying to infer x, y, and checking for DIMS_INFER[‘t’])

so it might apply only rarely. If a known behavior is desired, just set t or row explicitly.

DIMS_INFER: UNSET or dict of (str: list of str)

mapping from dim name to list of coords/dims to check for inferring that dim.

UNSET –> use DEFAULTS.PLOT.DIMS_INFER. (See defaults.py for more info.)

The following non-str options are available for x, y, t, row, and col:

ATTR_UNSET –> default must be implied by expecting kwarg, else crash.

(not available for t; t cannot be ATTR_UNSET.)

UNSET –> only attempt to infer and use this dim for plotting if needed,

i.e. if there are extra unaccounted-for dims after inferring other dims.

False –> do not use this dim for plotting, and do not attempt to infer this dim.

(e.g., if not doing subplots, then row and col should be False.)

None –> dim not specified, but desired, and must be inferred.

(for x, y, t, row, col, this increases priority of inferring, compared to UNSET;

internally will attempt to fill any None before any UNSET.

However, for others, the priority is not increased;

even others=None will only be filled after all other dims are inferred.

Setting others=None just means to crash if len(others)==0 at the end.)

Methods

__call__(*[, return_all])	calling self returns self.result (or self._return_all_result() if return_all).
coords_of(keys, *[, ndim])	return list of all of the coords of these keys in result.
fill_coords(array, *[, only])	return array but with coords filled for all plot dims/coords needed by self.
fill_coords_and_promote(array, *[, only])	return array but with coords filled and 1D coords promoted,
from_array(array, *[, x, y, t, row, col, ...])	create PlotDimsInferrer from xarray.DataArray.
infer_dims(*[, return_all])	infer dims that need to be inferred, for plotting.
promote_dims(array, *[, only])	return array after promoting to dims any 1D coords being used for plotting.
_check_inferred_all()	ensure nothing remains unused, and that we filled everything we needed to.
_check_misc()	miscellaneous checks.
_cleaned_coords(coords)	returns a new dict, representing the info from coords in standard format,
_coord_from_filled(filled_coord)	return the coord in self.coords corresponding to filled_coord, the coord in result.
_filled_from_coord(coord)	return the (filled) coord in result corresponding to coord, the coord in self.coords.
_infer_2D_xy([checkif])	infer 2D coords for x and/or y if possible
_infer_basics([checkif])	infer basic stuff (non 2D) if possible
_infer_others()	infer others if possible
_infer_trivial()	infer trivial stuff, i.e. things specified explicitly by strings.
_resolve_coords_array_inputs(...)	return coords from inputs coords_or_array, coords, and array.
_resolve_expecting()	resolve expecting into default values for x, y, row, col, and others.
_return_all_result()	returns self.result but with extra stuff added to it as needed.
_translate_inputs(simple_inputs)	translate input sentinels from "simple_inputs" format into PlotDimsInferrer format.
_unfilled(coord)	returns the coord which would be filled by coord, or just coord, unchanged.
_without_rc_dims(dlist)	returns copy of list but removing self.row_dim and self.col_dim if they appear in it.

Attributes

EXPECTING_OPTIONS
FILL_COORDS_OPTIONS
all_coords	list of all coords needed for plotting, i.e. all coords which appear in self.result.values().
all_coords_1D	list of all coords needed for plotting which are 1D,
col_coord	col coord to use for plotting.
col_dim	col dimension for plotting.
col_pdi	col kwarg to pass to another PlotDimsInferrer to get it to infer same col as self.
fillmap	dict of {coord_in_array: filled_coord} for any filled coord not originally in coords,
inputs	dict of inputs for x, y, t, row, col, and others.
others_coords	others coords to use for plotting.
others_dims	list of other dimensions for plotting.
others_pdi	others kwarg to pass to another PlotDimsInferrer to get it to infer same others as self.
result	dict telling result of infer_dims.
row_coord	row coord to use for plotting.
row_dim	row dimension for plotting.
row_pdi	row kwarg to pass to another PlotDimsInferrer to get it to infer same row as self.
t_coord	t coord to use for plotting.
t_dim	t dimension for plotting.
t_pdi	t kwarg to pass to another PlotDimsInferrer to get it to infer same t as self.
x_coord	x coord to use for plotting.
x_dims	x dimensions for plotting.
x_pdi	x kwarg to pass to another PlotDimsInferrer to get it to infer same x as self.
xy_1D	returns whether x and y coords are both 1D.
xy_coords	(self.x_coord, self.y_coord)
y_coord	y coord to use for plotting.
y_dims	y dimensions for plotting.
y_pdi	y kwarg to pass to another PlotDimsInferrer to get it to infer same y as self.

__call__(*, return_all=False)

calling self returns self.result (or self._return_all_result() if return_all).

CONVENIENT NOTE: keys will be ordered to match the order in which they were inferred.

_check_inferred_all()

ensure nothing remains unused, and that we filled everything we needed to.

_check_misc()

miscellaneous checks. These would otherwise lead to confusing crashes elsewhere.

By checking here, we can instead crash here and provide helpful error messages.

_cleaned_coords(coords)

returns a new dict, representing the info from coords in standard format,

i.e. {cname: [list of dims for this coord]}, removing any cnames with empty list.

_coord_from_filled(filled_coord)

return the coord in self.coords corresponding to filled_coord, the coord in result.

This is often just filled_coord. But, e.g., ‘log_d’ might become ‘d’, depending on fillmap.

Equivalent: self.fillmap.inverse.get(filled_coord, filled_coord)

_filled_from_coord(coord)

return the (filled) coord in result corresponding to coord, the coord in self.coords.

This is often just coord. But, e.g., ‘d’ might become ‘log_d’, depending on fillmap.

Equivalent: self.fillmap.get(coord, coord)

_infer_2D_xy(checkif=None)

infer 2D coords for x and/or y if possible

_infer_basics(checkif=None)

infer basic stuff (non 2D) if possible

_infer_others()

infer others if possible

_infer_trivial()

infer trivial stuff, i.e. things specified explicitly by strings.

This includes exact matches with self.coords as well as matches with FILL_COORDS_OPTIONS.

_resolve_coords_array_inputs(coords_or_array, coords, array)

return coords from inputs coords_or_array, coords, and array.

Exactly one of these inputs must be provided, the others must be UNSET.

_resolve_expecting()

resolve expecting into default values for x, y, row, col, and others.

returns dict of defaults.

_return_all_result()

returns self.result but with extra stuff added to it as needed.

classmethod _translate_inputs(simple_inputs)

translate input sentinels from “simple_inputs” format into PlotDimsInferrer format.

Returns new dict, of inputs for cls. (Does not alter simple_inputs in place.)

“simple_inputs” format is what is seen and used by most of the actual plotting codes

(see PlotDimsMixin for more details.)

The translation rules are:

if ‘_skip_translation’ in simple_inputs, remove it;

if it was True, skip all other translation rules.

if key’s value is None, remove key.

i.e. use whatever the defaults would be if this key wasn’t supplied.

(might add other rules eventually but this is all for now.)

_unfilled(coord)

returns the coord which would be filled by coord, or just coord, unchanged.

E.g., ‘index_d’ –> ‘d’; ‘otherd’ –> ‘otherd’.

_without_rc_dims(dlist)

returns copy of list but removing self.row_dim and self.col_dim if they appear in it.

property all_coords

list of all coords needed for plotting, i.e. all coords which appear in self.result.values()

(Does NOT convert to “unfilled” coords).

Equivalent: self.coords_of(self.result.keys())

property all_coords_1D

list of all coords needed for plotting which are 1D,

i.e. all coords which appear in self.result.values(),

and whose corresponding dims in self.coords are 1D.

Equivalent: self.coords_of(self.result.keys(), ndim=1)

property col_coord

col coord to use for plotting. Equivalent: self.result.get(‘col’, None)

property col_dim

col dimension for plotting. This is self.coords[result[‘col’]][0] if ‘col’ in result, else None.

(also “unfills” appropriately, e.g. ‘log_colcoord’ –> ‘colcoord’ if needed).

property col_pdi

col kwarg to pass to another PlotDimsInferrer to get it to infer same col as self.

This is self.col_coord if not None, else False.

coords_of(keys, *, ndim='any')

return list of all of the coords of these keys in result.

Crash if any key is not in result.

e.g. keys=[‘x’, ‘others’] –> returns [result[‘x’], *result[‘others’]]

(Does NOT convert to “unfilled” coords).

ndim: ‘any’ or 1

if 1, only include coords whose corresponding dims in self.coords are 1D.

fill_coords(array, *, only=None)

return array but with coords filled for all plot dims/coords needed by self.

(makes copy of array if any changes are needed, else returns original array.)

Equivalent (if only is None) xarray_fill_coords(array, need=self.all_coords)

only: None, str, or list of strs

only fill coords corresponding to these keys in result,

e.g. only=[‘t’] –> only include result[‘x’].

fill_coords_and_promote(array, *, only=None)

return array but with coords filled and 1D coords promoted,

for all plot dims/coords needed by self.

Equivalent: self.promote_dims(self.fill_coords(array, only=only), only=only)

property fillmap

dict of {coord_in_array: filled_coord} for any filled coord not originally in coords,

but provided explicitly. E.g. {‘x’: ‘log_x’, ‘fluid’: ‘str_fluid’}.

filled_coord will be in result, but coord_in_array will be in self.coords.

fillmap.inverse tells dict of {filled_coord: coord_in_array} instead.

classmethod from_array(array, *, x=ATTR_UNSET, y=ATTR_UNSET, t=UNSET, row=ATTR_UNSET, col=ATTR_UNSET, others=ATTR_UNSET, expecting=UNSET, **kw_init)

create PlotDimsInferrer from xarray.DataArray.

Equivalent: cls(array.pc.coords_dims(include_coordless_dims=True), …)

See help(cls) for more details.

infer_dims(*, return_all=False)

infer dims that need to be inferred, for plotting.

return dict with some/all keys from: x, y, t, row, col, and others.

crash if this is not possible, given the constraints implied by the inputs.

CONVENIENT NOTE: keys will be ordered to match the order in which they were inferred.

internal result (without return_all) will also be saved to self.result.

(self.result will be reset at the start of this method if it is ever called again.)

return_all: bool

whether to return dict with all keys, or exclude ones where value isn’t UNSET or False.

False –> include only keys where value is not UNSET nor False.

property inputs

dict of inputs for x, y, t, row, col, and others. Excludes False.

property others_coords

others coords to use for plotting. Equivalent: self.result.get(‘others’, None)

property others_dims

list of other dimensions for plotting.

This is [self.coords[c][0] for c in result[‘others’]] if ‘others’ in result, else [].

(also “unfills” appropriately, e.g. ‘log_othercoord’ –> ‘othercoord’ if needed).

property others_pdi

others kwarg to pass to another PlotDimsInferrer to get it to infer same others as self.

This is self.others_coords if not None, else False.

promote_dims(array, *, only=None)

return array after promoting to dims any 1D coords being used for plotting.

Equivalent (if only is None): xarray_ensure_dims(array, dims=self.all_coords_1D, promote_dims_if_needed=True)

only: None, str, or list of strs

only fill promote corresponding to these keys in result (and which are 1D)

e.g. only=[‘t’] –> only include result[‘x’].

property result

dict telling result of infer_dims.

property row_coord

row coord to use for plotting. Equivalent: self.result.get(‘row’, None)

property row_dim

row dimension for plotting. This is self.coords[result[‘row’]][0] if ‘row’ in result, else None.

(also “unfills” appropriately, e.g. ‘log_rowcoord’ –> ‘rowcoord’ if needed).

property row_pdi

row kwarg to pass to another PlotDimsInferrer to get it to infer same row as self.

This is self.row_coord if not None, else False.

property t_coord

t coord to use for plotting. Equivalent: self.result.get(‘t’, None).

property t_dim

t dimension for plotting. This is self.coords[result[‘t’]][0] if ‘t’ in result, else None.

(also “unfills” appropriately, e.g. ‘log_tcoord’ –> ‘tcoord’ if needed).

property t_pdi

t kwarg to pass to another PlotDimsInferrer to get it to infer same t as self.

This is self.t_coord if not None, else False.

property x_coord

x coord to use for plotting. Equivalent: self.result.get(‘x’, None)

property x_dims

x dimensions for plotting. In 1D case, this is [self.coords[result[‘x’]][0]]

(also “unfills” appropriately, e.g. ‘log_xcoord’ –> ‘xcoord’ if needed).

However, self.coords[result[‘x’]] might have 2+ dims,

in which case will exclude any dims used for row and col.

(It is assumed that the other dims will not be t_dim nor in others_dims.)

property x_pdi

x kwarg to pass to another PlotDimsInferrer to get it to infer same x as self.

This is self.x_coord if not None, else False.

property xy_1D

returns whether x and y coords are both 1D.

property xy_coords

(self.x_coord, self.y_coord)

property y_coord

y coord to use for plotting. Equivalent: self.result.get(‘y’, None)

property y_dims

y dimensions for plotting. In 1D case, this is [self.coords[result[‘y’]][0]]

(also “unfills” appropriately, e.g. ‘log_ycoord’ –> ‘ycoord’ if needed).

However, self.coords[result[‘y’]] might have 2+ dims,

in which case will exclude any dims used for row and col.

(It is assumed that the other dims will not be t_dim nor in others_dims.)

property y_pdi

y kwarg to pass to another PlotDimsInferrer to get it to infer same y as self.

This is self.y_coord if not None, else False.