erlab.plotting.general¶

General plotting utilities.

Functions

`clean_labels`(axes[, remove_inner_ticks])	Clean the labels of the given axes.
`fermiline`([ax, value, orientation])	Plot a constant energy line to denote the Fermi level.
`figwh`([ratio, wide, wscale, style, fixed_height])
`gradient_fill`(x, y[, y0, color, cmap, ...])	Apply a gradient fill to a line plot.
`place_inset`(parent_axes, width, height[, ...])	Easy placement of inset axes.
`plot_array`(arr[, ax, colorbar, colorbar_kw, ...])	Plot a 2D `xarray.DataArray` using `matplotlib.pyplot.imshow()`.
`plot_array_2d`(larr, carr[, ax, ...])	Plot a 2D array with associated color array.
`plot_slices`(maps[, figsize, transpose, ...])	Automated comparison plot of slices.

erlab.plotting.general.clean_labels(axes, remove_inner_ticks=False, **kwargs)[source]¶

Clean the labels of the given axes.

This function removes the labels from the axes except for the outermost axes and prettifies the remaining labels with fancy_labels.

Changed in version 2.5.0: The function now calls Axes.label_outer recursively instead of setting the labels to an empty string.

Parameters:

axes (Iterable[Axes]) – The axes to clean the labels for.
remove_inner_ticks (bool, default: False) – If True, remove the inner ticks as well (not only tick labels).
**kwargs – Additional keyword arguments to be passed to fancy_labels.

erlab.plotting.general.fermiline(ax=None, value=0.0, orientation='h', **kwargs)[source]¶

Plot a constant energy line to denote the Fermi level.

Parameters:

ax (Axes | None, default: None) – The matplotlib.axes.Axes to annotate.
value (float, default: 0.0) – The coordinate of the line. Defaults to 0, assuming binding energy.
orientation (Literal['h', 'v'], default: "h") – If ‘h’, a horizontal line is plotted. If ‘v’, a vertical line is plotted.
**kwargs – Keyword arguments passed onto matplotlib.lines.Line2D.

Returns:

matplotlib.lines.Line2D

Return type:

Line2D | list[Line2D | list[Line2D | MultipleLine2D]]

erlab.plotting.general.figwh(ratio=0.6180339887498948, wide=0, wscale=1, style='aps', fixed_height=True)[source]¶

erlab.plotting.general.gradient_fill(x, y, y0=None, color='C0', cmap=None, transpose=False, reverse=False, ax=None, **kwargs)[source]¶

Apply a gradient fill to a line plot.

Parameters:

x (Collection[float]) – Data of the plot to fill under.
y (Collection[float]) – Data of the plot to fill under.
y0 (float | None, default: None) – The minimum y value of the gradient. If None, defaults to the minimum of y.
color (str | tuple[float, float, float] | tuple[float, float, float, float], default: "C0") – A valid matplotlib color to make the gradient from.
cmap (str | Colormap | None, default: None) – If given, ignores color and fills with the given colormap.
transpose (bool, default: False) – Transpose the gradient.
reverse (bool, default: False) – Reverse the gradient.
ax (Axes | None, default: None) – The matplotlib.axes.Axes to plot in.
**kwargs – Keyword arguments passed onto matplotlib.axes.Axes.imshow().

Returns:

matplotlib.image.AxesImage

Return type:

AxesImage

erlab.plotting.general.place_inset(parent_axes, width, height, pad=0.1, loc='upper right', **kwargs)[source]¶

Easy placement of inset axes.

Parameters:

parent_axes (Axes) – matplotlib.axes.Axes to place the inset axes.
width (float | str) – Size of the inset axes to create. If float, specifies the size in inches, e.g. 1.3. If str, specifies the size in relative units, e.g. '40%' of parent_axes.
height (float | str) – Size of the inset axes to create. If float, specifies the size in inches, e.g. 1.3. If str, specifies the size in relative units, e.g. '40%' of parent_axes.
pad (float | tuple[float, float], default: 0.1) – Padding between parent_axes and inset in inches.
loc (Literal['upper left', 'upper center', 'upper right', 'center left', 'center', 'center right', 'lower left', 'lower center', 'lower right'], default: "upper right") – Location to place the inset axes.
**kwargs – Keyword arguments are passed onto matplotlib.axes.Axes.inset_axes.

Returns:

matplotlib.axes.Axes

Return type:

Axes

erlab.plotting.general.plot_array(arr, ax=None, *, colorbar=False, colorbar_kw=None, gamma=1.0, norm=None, xlim=None, ylim=None, crop=False, rad2deg=False, func=None, func_args=None, rtol=1.0e-5, atol=1.0e-8, rasterized=True, **improps)[source]¶

Plot a 2D xarray.DataArray using matplotlib.pyplot.imshow().

If the input array is detected to have non-evenly spaced coordinates, it is plotted as a matplotlib.image.NonUniformImage.

Parameters:

arr (DataArray) – A two-dimensional xarray.DataArray with evenly spaced coordinates.
ax (Axes | None, default: None) – The target matplotlib.axes.Axes.
colorbar (bool, default: False) – Whether to plot a colorbar.
colorbar_kw (dict | None, default: None) – Keyword arguments passed onto erlab.plotting.colors.nice_colorbar().
xlim (float | tuple[float, float] | None, default: None) – If given a sequence of length 2, those values are set as the lower and upper limits of each axis. If given a single float, the limits are set as (-lim, lim). If None, automatically determines the limits from the data.
ylim (float | tuple[float, float] | None, default: None) – If given a sequence of length 2, those values are set as the lower and upper limits of each axis. If given a single float, the limits are set as (-lim, lim). If None, automatically determines the limits from the data.
rad2deg (bool | Iterable[str], default: False) – If True, converts some known angle coordinates from radians to degrees. If an iterable of str is given, only the coordinates that correspond to the given strings are converted.
func (Callable | None, default: None) – A callable that processes the data prior to display. Its output must be an array that has the same shape as the input.
func_args (dict | None, default: None) – Keyword arguments passed onto func.
rtol (float, default: 1.0e-5) – By default, the input array is checked for evenly spaced coordinates. If it is not evenly spaced, it is plotted as a matplotlib.image.NonUniformImage instead of a matplotlib.image.AxesImage. rtol and atol are the tolerances for the coordinates to be considered evenly spaced. The default values are consistent with numpy.isclose.
atol (float, default: 1.0e-8) – By default, the input array is checked for evenly spaced coordinates. If it is not evenly spaced, it is plotted as a matplotlib.image.NonUniformImage instead of a matplotlib.image.AxesImage. rtol and atol are the tolerances for the coordinates to be considered evenly spaced. The default values are consistent with numpy.isclose.
rasterized (bool, default: True) – Force rasterized output.
**improps – Keyword arguments passed onto matplotlib.pyplot.imshow().

Returns:

matplotlib.image.AxesImage

Return type:

AxesImage

Notes

Some keyword arguments have different default behavior compared to matplotlib.

interpolation is set to 'none' for evenly spaced data and 'nearest' for nonuniform data.
aspect is set to 'auto'.
origin is set to 'lower'.
The image is rasterized by default.

erlab.plotting.general.plot_array_2d(larr, carr, ax=None, *, normalize_with_larr=False, xlim=None, ylim=None, cmap=None, lnorm=None, cnorm=None, background=None, colorbar=True, cax=None, colorbar_kw=None, imshow_kw=None, N=256, rtol=1.0e-5, atol=1.0e-8, **indexers_kwargs)[source]¶

Plot a 2D array with associated color array.

The lightness array represents the intensity values, while the color array represents some other property. The arrays must have the same shape.

Parameters:

larr (DataArray) – The 2D array representing the lightness values.
carr (DataArray) – The 2D array representing the color values.
ax (Axes | None, default: None) – The axes on which to plot the array. If None, the current axes will be used.
normalize_with_larr (bool, default: False) – Whether to normalize the color array with the lightness array. Default is False.
xlim (float | tuple[float, float] | None, default: None) – The x-axis limits for the plot. If a float, it represents the symmetric limits around 0. If a tuple, it represents the lower and upper limits. If None, the limits are determined from the data.
ylim (float | tuple[float, float] | None, default: None) – The y-axis limits for the plot. If a float, it represents the symmetric limits around 0. If a tuple, it represents the lower and upper limits. If None, the limits are determined from the data.
cmap (Colormap | str | None, default: None) – The colormap to use for the color array. If None, a linear segmented colormap consisting of blue, black, and red is used.
lnorm (Normalize | None, default: None) – The normalization object for the lightness array.
cnorm (Normalize | None, default: None) – The normalization object for the color array.
background (tuple[float, float, float] | str | tuple[float, float, float, float] | tuple[tuple[float, float, float] | str, float] | tuple[tuple[float, float, float, float], float] | None, default: None) – The background color to use for the plot. If None, white is used.
colorbar (bool, default: True) – Whether to create a colorbar. Default is True.
cax (Axes | None, default: None) – The axes on which to create the colorbar if colorbar is True. If None, a new axes will be created for the colorbar.
colorbar_kw (dict | None, default: None) – Additional keyword arguments to pass to matplotlib.pyplot.colorbar.
imshow_kw (dict | None, default: None) – Additional keyword arguments to pass to matplotlib.pyplot.imshow.
N (int, default: 256) – The number of levels in the colormap. Default is 256.
rtol (float, default: 1.0e-5) – By default, the input array is checked for evenly spaced coordinates. rtol and atol are the tolerances for the coordinates to be considered evenly spaced. The default values are consistent with numpy.isclose.
atol (float, default: 1.0e-8) – By default, the input array is checked for evenly spaced coordinates. rtol and atol are the tolerances for the coordinates to be considered evenly spaced. The default values are consistent with numpy.isclose.
**indexers_kwargs (dict) – Additional keyword arguments to pass to qsel to select the data to plot. Note that the resulting data after the selection must be 2D.

Returns:

im (matplotlib.image.AxesImage) – The plotted image.
cb (matplotlib.colorbar.Colorbar or None) – The colorbar associated with the plot. If colorbar is False, None is returned.

Return type:

tuple[AxesImage, Colorbar | None]

Example

>>> import erlab.plotting as eplt
>>> import matplotlib.pyplot as plt
>>> import xarray as xr
>>> larr = xr.DataArray([[1, 2, 3], [4, 5, 6]])
>>> carr = xr.DataArray([[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]])
>>> eplt.plot_array_2d(larr, carr)

erlab.plotting.general.plot_slices(maps, figsize=None, *, transpose=False, xlim=None, ylim=None, crop=True, same_limits=False, axis='auto', show_all_labels=False, colorbar='none', hide_colorbar_ticks=True, annotate=True, cmap=None, norm=None, order='C', cmap_order='C', norm_order=None, gradient=False, gradient_kw=None, subplot_kw=None, annotate_kw=None, colorbar_kw=None, axes=None, **values)[source]¶

Automated comparison plot of slices.

Parameters:

maps (DataArray | Sequence[DataArray]) – Arrays to plot.
figsize (tuple[float, float] | None, default: None) – Figure size.
transpose (bool, default: False) – Transpose each map before plotting.
xlim (float | tuple[float | None, float | None] | None, default: None) – If given a sequence of length 2, those values are set as the lower and upper limits of each axis. If given a single float, the limits are set as (-lim, lim). If None, automatically determines the limits from the data.
ylim (float | tuple[float | None, float | None] | None, default: None) – If given a sequence of length 2, those values are set as the lower and upper limits of each axis. If given a single float, the limits are set as (-lim, lim). If None, automatically determines the limits from the data.
crop (bool, default: True) – If True, crops the data to the limits given by xlim and ylim prior to plotting.
same_limits (bool | Literal['row', 'col', 'all'], default: False) – If True, all images will have the same vmin and vmax. Passing 'row' or 'col' will set same limits for rows or columns, respectively. Passing 'all' is equivalent to True.

axis (Literal['on', 'off', 'equal', 'scaled', 'tight', 'auto', 'image', 'square'], default: "auto") –

Passed onto matplotlib.axes.Axes.axis(). Possible values are:

Value	Description
’on’	Turn on axis lines and labels.
’off’	Turn off axis lines and labels.
’equal’	Set equal scaling (i.e., make circles circular) by changing axis limits. This is the same as `ax.set_aspect('equal', adjustable='datalim')`. Explicit data limits may not be respected in this case.
’scaled’	Set equal scaling (i.e., make circles circular) by changing dimensions of the plot box. This is the same as `ax.set_aspect('equal', adjustable='box', anchor='C')`. Additionally, further autoscaling will be disabled.
’tight’	Set limits just large enough to show all data, then disable further autoscaling.
’auto’	Automatic scaling (fill plot box with data).
’image’	’scaled’ with axis limits equal to data limits.
’square’	Square plot; similar to ‘scaled’, but initially forcing `xmax-xmin == ymax-ymin`.

show_all_labels (bool, default: False) – If True, shows every xlabel and ylabel. If False, labels on shared axes are minimized. When False and the axes argument is given, the order must be specified to correctly hide shared labels.

colorbar (Literal['none', 'right', 'rightspan', 'all'], default: "none") –

Controls colorbar behavior. Possible values are:

Value	Description
’none’	Do not show colorbars.
’right’	Creates a colorbar on the right for each row.
’rightspan’	Create a single colorbar that spans all axes.
’all’	Plot a colorbar for every axes.

hide_colorbar_ticks (bool, default: True) – If True, hides colorbar ticks.
annotate (bool, default: True) – If False, turn off automatic annotation.
cmap (str | Colormap | Iterable[str | Colormap | Iterable[Colormap | str]] | None, default: None) – If supplied a single str or matplotlib.colors.Colormap, the colormap is applied to all axes. Otherwise, a nested sequence with the same shape as the resulting axes can be provided to use different colormaps for different axes. If the slices are 1D, this argument can be used to supply valid colors as line colors for different slices.
norm (Normalize | Iterable[Normalize | Iterable[Normalize]] | None, default: None) – If supplied a single matplotlib.colors.Normalize, the norm is applied to all axes. Otherwise, a nested sequence with the same shape as the resulting axes can be provided to use different norms for different axes.
order (Literal['C', 'F'], default: "C") – Order to display the data. Effectively, this determines if each map is displayed along the same row or the same column. ‘C’ means to flatten in row-major (C-style) order, and ‘F’ means to flatten in column-major (Fortran-style) order.
cmap_order (Literal['C', 'F'], default: "C") – The order to flatten when given a nested sequence for cmap, Defaults to 'C'.
norm_order (Literal['C', 'F'] | None, default: None) – The order to flatten when given a nested sequence for norm, Defaults to cmap_order.
gradient (bool, default: False) – If True, for 1D slices, fills the area under the curve with a gradient. Has no effect for 2D slices.
gradient_kw (dict | None, default: None) – Extra arguments to gradient_fill().
subplot_kw (dict | None, default: None) – Extra arguments to matplotlib.pyplot.subplots(): refer to the matplotlib documentation for a list of all possible arguments.
annotate_kw (dict | None, default: None) – Extra arguments to erlab.plotting.annotations.label_subplot_properties(). Only applied when annotate is True.
colorbar_kw (dict | None, default: None) – Extra arguments to erlab.plotting.colors.proportional_colorbar().
axes (Iterable[Axes] | None, default: None) – A nested sequence of matplotlib.axes.Axes. If supplied, the returned matplotlib.figure.Figure is inferred from the first axes.
**values – Key-value pair of cut location and bin widths. See examples. Remaining arguments are passed onto plot_array().

Returns:

fig (matplotlib.figure.Figure)
axes (array-like of matplotlib.axes.Axes)

Return type:

tuple[Figure, Iterable[Axes]]

Examples

# Two maps: map1, map2
# Create a figure with a 3 by 2 grid.

fig, axes = plot_slices([map1, map2], eV=[0, -0.1, -0.2], eV_width=0.05)