erlab.plotting.annotations¶

Plot annotations.

Module Attributes

`PRETTY_NAMES`	Pretty names for automated labeling of plots.
`PRETTY_UNITS`	Pretty units for automated labeling of plots.

Functions

`copy_mathtext`(s[, fontsize, fontproperties, ...])	Copy math equations to the clipboard as SVG.
`fancy_labels`([ax, radians])	Apply pretty labels to Matplotlib axes based on their current label text.
`integer_ticks`(ax)	Set the ticks on the x and y axes to only display integer values.
`label_subplot_properties`(axes, values[, ...])	Labels subplots with automatically generated labels.
`label_subplots`(axes[, values, startfrom, ...])	Labels subplots with automatically generated labels.
`mark_points`(points, labels, *[, y, pad, ...])	Mark points above the horizontal axis.
`mark_points_outside`(points, labels[, axis, ...])	Mark points above the horizontal axis.
`property_labels`([values, decimals, si, ...])	Generate labels from a dictionary of values.
`scale_units`(ax, axis[, si, prefix, power])	Rescales ticks and adds an SI prefix to the axis label.
`set_titles`(axes, labels[, order])	Set titles for multiple axes.
`set_xlabels`(axes, labels[, order])	Set x-axis labels for multiple axes.
`set_ylabels`(axes, labels[, order])	Set y-axis labels for multiple axes.
`sizebar`(ax, value, unit[, si, resolution, ...])	Add a size bar to an axes.

erlab.plotting.annotations.PRETTY_NAMES: dict[str, tuple[str, str]] = {'Eb': ('\\ensuremath{E}', '$E$'), 'Ek': ('\\ensuremath{E_{\\text{kin}}}', '$E_{\\text{kin}}$'), 'T': ('\\ensuremath{T}', '$T$'), 'alpha': ('\\ensuremath{\\alpha}', '$\\alpha$'), 'beta': ('\\ensuremath{\\beta}', '$\\beta$'), 'chi': ('\\ensuremath{\\chi}', '$\\chi$'), 'eV': ('\\ensuremath{E-E_F}', '$E-E_F$'), 'hv': ('\\ensuremath{h\\nu}', '$h\\nu$'), 'kp': ('\\ensuremath{k_{||}}', '$k_{||}$'), 'kx': ('\\ensuremath{k_{x}}', '$k_x$'), 'ky': ('\\ensuremath{k_{y}}', '$k_y$'), 'kz': ('\\ensuremath{k_{z}}', '$k_z$'), 'phi': ('\\ensuremath{\\phi}', '$\\phi$'), 'psi': ('\\ensuremath{\\psi}', '$\\psi$'), 'sample_temp': ('\\ensuremath{T}', '$T$'), 't': ('\\ensuremath{t}', '$t$'), 'temperature': ('Temperature', 'Temperature'), 'theta': ('\\ensuremath{\\theta}', '$\\theta$'), 'xi': ('\\ensuremath{\\xi}', '$\\xi$')}¶

Pretty names for automated labeling of plots.

Contains a mapping from dimension names to tuples of strings. The first element of the tuple is used when matplotlib is configured to use LaTeX, and the second is used for Mathtext. Unless you have explicitly set the text.usetex parameter in your matplotlib configuration, the second element will be used.

erlab.plotting.annotations.PRETTY_UNITS: dict[str, tuple[str, str]] = {'Eb': ('eV', 'eV'), 'Ek': ('eV', 'eV'), 'T': ('K', 'K'), 'alpha': ('deg', 'deg'), 'beta': ('deg', 'deg'), 'chi': ('deg', 'deg'), 'eV': ('eV', 'eV'), 'hv': ('eV', 'eV'), 'kp': ('Å\\ensuremath{{}^{-1}}', 'Å${}^{-1}$'), 'kx': ('Å\\ensuremath{{}^{-1}}', 'Å${}^{-1}$'), 'ky': ('Å\\ensuremath{{}^{-1}}', 'Å${}^{-1}$'), 'kz': ('Å\\ensuremath{{}^{-1}}', 'Å${}^{-1}$'), 'phi': ('deg', 'deg'), 'psi': ('deg', 'deg'), 'sample_temp': ('K', 'K'), 't': ('s', 's'), 'temperature': ('K', 'K'), 'theta': ('deg', 'deg'), 'xi': ('deg', 'deg')}¶

Pretty units for automated labeling of plots.

erlab.plotting.annotations.copy_mathtext(s, fontsize=None, fontproperties=None, outline=False, rcparams=None, **mathtext_rc)[source]¶

Copy math equations to the clipboard as SVG.

Parameters:

s (str) – The math text to convert to SVG.
fontsize (float | Literal['xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'] | None, default: None) – The font size to use for the math text. If None, the default font size is used.
fontproperties (FontProperties | None, default: None) – The font properties to use for the math text. If None, the default font properties are used.
outline (bool, default: False) – If True, the SVG will contain outlined paths instead of text.
rcparams (dict | None, default: None) – Additional rc parameters to use for the math text rendering. If None, the default rc parameters are used.

Returns:

str – The SVG string representation of the math text.

Return type:

str

Example

>>> import erlab.plotting as eplt
>>> svg_str = eplt.copy_mathtext(r"$E = mc^2$", fontsize=12)

erlab.plotting.annotations.fancy_labels(ax=None, *, radians=False)[source]¶

Apply pretty labels to Matplotlib axes based on their current label text.

This function converts plain dimension names already set on the axes into nicely formatted labels (e.g., symbols and units). The labels are determined based on PRETTY_NAMES and PRETTY_UNITS.

Parameters:

ax (Axes | Iterable[Axes] | None, default: None) – The target axes or an iterable of axes. If None (default), the current axes is used.
radians (bool, optional) – If True, angle units will be displayed in radians instead of degrees.

Examples

>>> import matplotlib.pyplot as plt
>>> import erlab.plotting as eplt
>>> fig, ax = plt.subplots()
>>> ax.set_xlabel("kx")
>>> ax.set_ylabel("eV")
>>> fancy_labels(ax)
>>> ax.get_xlabel()
'$k_x$ (Å${}^{-1}$)'
>>> ax.get_ylabel()
'$E-E_F$ (eV)'

erlab.plotting.annotations.integer_ticks(ax)[source]¶

Set the ticks on the x and y axes to only display integer values.

Modifies the x and y ticks of the given axes to only show integer values that are within the current limits of the axes.

Parameters:: ax (Axes | Iterable[Axes]) – Axes or iterable of Axes.

erlab.plotting.annotations.label_subplot_properties(axes, values, decimals=None, si=0, name=None, unit=None, order='C', **kwargs)[source]¶

Labels subplots with automatically generated labels.

Parameters:

axes (Axes | Iterable[Axes]) – matplotlib.axes.Axes to label. If an array is given, the order will be determined by the flattening method given by order.
values (dict) – Key-value pair of annotations. The values may be a single value or an array-like of values. If a single value, it will be converted to a list of length 1. If an array of 2 or more dimensions is given, it will be flattened with the order given by order. All values must be of the same length when flattened.
decimals (int | None, default: None) – Number of decimal places to round to. If decimals is None, no rounding is performed. If decimals is negative, it specifies the number of positions to the left of the decimal point.
si (int, default: 0) – Powers of 10 for automatic SI prefix setting.
name (str | None, default: None) – When set, overrides automatic dimension name setting.
unit (str | None, default: None) – When set, overrides automatic unit setting.
order (Literal['C', 'F', 'A', 'K'], default: "C") – Order in which to flatten ax. ‘C’ means to flatten in row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran-style) order. The default is ‘C’.
**kwargs – Extra arguments to erlab.plotting.annotations.label_subplots.

erlab.plotting.annotations.label_subplots(axes, values=None, startfrom=1, order='C', loc='upper left', offset=(0.0, 0.0), prefix='', suffix='', numeric=False, capital=False, fontweight='normal', fontsize=None, **kwargs)[source]¶

Labels subplots with automatically generated labels.

Parameters:

axes (Axes | Iterable[Axes]) – matplotlib.axes.Axes to label. If an array is given, the order will be determined by the flattening method given by order.
values (Iterable[int | str] | None, default: None) – Integer or string labels corresponding to each Axes in axes for manual labels.
startfrom (int, default: 1) – Start from this number when creating automatic labels. Has no effect when values is not None.
order (Literal['C', 'F', 'A', 'K'], default: "C") – Order in which to flatten ax. ‘C’ means to flatten in row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran-style) order. ‘A’ means to flatten in column-major order if a is Fortran contiguous in memory, row-major order otherwise. ‘K’ means to flatten a in the order the elements occur in memory. The default is ‘C’.
loc (Literal['upper left', 'upper center', 'upper right', 'center left', 'center', 'center right', 'lower left', 'lower center', 'lower right'], default: "upper left") – The box location. The default is 'upper left'.
offset (tuple[float, float], default: (0.0, 0.0)) – Values that are used to position the legend in conjunction with loc, given in display units.
prefix (str, default: "") – String to prepend to the alphabet label.
suffix (str, default: "") – String to append to the alphabet label.
numeric (bool, default: False) – Use integer labels instead of alphabets.
capital (bool, default: False) – Capitalize automatically generated alphabetical labels.
fontweight (Literal['ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black'], default: "normal") – Set the font weight. The default is 'normal'.
fontsize (float | Literal['xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'] | None, default: None) – Set the font size. The default is 'medium' for axes, and 'large' for figures.
**kwargs – Extra arguments to matplotlib.text.Text: refer to the matplotlib documentation for a list of all possible arguments.

erlab.plotting.annotations.mark_points(points, labels, *, y=0.0, pad=(0, 1.75), literal=False, roman=True, bar=False, ax=None, **kwargs)[source]¶

Mark points above the horizontal axis.

Useful when annotating high symmetry points along a cut.

Parameters:

points (Sequence[float]) – Floats indicating the position of each label.
labels (Sequence[str]) – Sequence of label strings indicating a high symmetry point. Must be the same length as points.
y (float | Sequence[float], default: 0.0) – Position of the label in data coordinates. If a single float is given, it will be used for all points. If a sequence is given, it must be the same length as points.
pad (tuple[float, float], default: (0, 1.75)) – Offset of the text in points.
literal (bool, default: False) – If True, take the input string literally.
roman (bool, default: True) – If False, itallic fonts are used.
bar (bool, default: False) – If True, prints a bar over the label.
ax (Axes | Iterable[Axes] | None, default: None) – matplotlib.axes.Axes to annotate. If None, the current axes is used.
**kwargs – Extra arguments to matplotlib.axes.Axes.text. By default, the horizontal alignment is set to 'center' and the vertical alignment is set to 'baseline'. The text is not clipped to the axes limits.

erlab.plotting.annotations.mark_points_outside(points, labels, axis='x', *, literal=False, roman=True, bar=False, ax=None, **kwargs)[source]¶

Mark points above the horizontal axis.

Useful when annotating high symmetry points along a cut.

Parameters:

points (Sequence[float]) – Floats indicating the position of each label.
labels (Sequence[str]) – Sequence of label strings indicating a high symmetry point. Must be the same length as points.
axis (Literal['x', 'y'], default: "x") – If 'x', marks points along the horizontal axis. If 'y', marks points along the vertical axis.
literal (bool, default: False) – If True, take the input string literally.
roman (bool, default: True) – If False, itallic fonts are used.
bar (bool, default: False) – If True, prints a bar over the label.
ax (Axes | Iterable[Axes] | None, default: None) – matplotlib.axes.Axes to annotate.
**kwargs – Extra arguments to matplotlib.text.Text: refer to the matplotlib documentation for a list of all possible arguments.

erlab.plotting.annotations.property_labels(values=None, decimals=None, si=0, name=None, unit=None, order='C', **values_kwargs)[source]¶

Generate labels from a dictionary of values.

Given a dictionary of values, this function generates a list of label strings with the key as the dimension name and the value as the dimension value. Multiple key-value pairs will be separated by a newline character in each label. The name and unit will be automatically determined from the key.

Parameters:

values (dict | None, default: None) – Key-value pair of annotations. The values may be a single value or an array-like of values. If a single value, it will be converted to a list of length 1. If an array of 2 or more dimensions is given, it will be flattened with the order given by order. All values must be of the same length when flattened.
decimals (int | None, default: None) – Number of decimal places to round to. If decimals is None, no rounding is performed. If decimals is negative, it specifies the number of positions to the left of the decimal point.
si (int, default: 0) – Powers of 10 for automatic SI prefix setting.
name (str | None, default: None) – When set, overrides automatic dimension name setting.
unit (str | None, default: None) – When set, overrides automatic unit setting.
order (Literal['C', 'F', 'A', 'K'], default: "C") – Order in which to flatten ax. ‘C’ means to flatten in row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran-style) order. The default is ‘C’.

erlab.plotting.annotations.scale_units(ax, axis, si=0, *, prefix=True, power=False)[source]¶

Rescales ticks and adds an SI prefix to the axis label.

Useful when you want to rescale the ticks without actually rescaling the data. For example, when plotting a cut from a low pass energy scan, you might want to convert the energy units from eV to meV.

Using this function on an axis where the major locator is not the default formatter matplotlib.ticker.ScalarFormatter will result in undefined behavior.

Parameters:

ax (Axes | Iterable[Axes]) – Axes or iterable of Axes to rescale.
axis (Literal['x', 'y', 'z']) – The axis you wish to rescale.
si (int, default: 0) – Exponent of 10 corresponding to a SI prefix.
prefix (bool, default: True) – If True, tries to detect the unit from the axis label and scales it accordingly. The scaling behaviour is controlled by the power argument. If no units are found in the axis label, it is silently ignored.
power (bool, default: False) – If False, prefixes the detected unit on the axis label with a SI prefix corresponding to si. If True, the unit is prefixed with a scientific notation instead.

erlab.plotting.annotations.set_titles(axes, labels, order='C', **kwargs)[source]¶

Set titles for multiple axes.

Parameters:

axes – Axes to set titles for.
labels (Iterable[str] | str) – Title strings to set. If a single string is given, it will be used for all axes.
order (default: "C") – Order in which to flatten ax. ‘C’ means to flatten in row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran-style) order. The default is ‘C’.
**kwargs – Extra arguments to matplotlib.axes.Axes.set_title: refer to the matplotlib documentation for a list of all possible arguments.

erlab.plotting.annotations.set_xlabels(axes, labels, order='C', **kwargs)[source]¶

Set x-axis labels for multiple axes.

Parameters:

axes – Axes to set x-axis labels for.
labels (Iterable[str] | str) – Label strings to set. If a single string is given, it will be used for all axes.
order (default: "C") – Order in which to flatten ax. ‘C’ means to flatten in row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran-style) order. The default is ‘C’.
**kwargs – Extra arguments to matplotlib.axes.Axes.set_xlabel: refer to the matplotlib documentation for a list of all possible arguments.

erlab.plotting.annotations.set_ylabels(axes, labels, order='C', **kwargs)[source]¶

Set y-axis labels for multiple axes.

Parameters:

axes – Axes to set y-axis labels for.
labels (Iterable[str] | str) – Label strings to set. If a single string is given, it will be used for all axes.
order (default: "C") – Order in which to flatten ax. ‘C’ means to flatten in row-major (C-style) order. ‘F’ means to flatten in column-major (Fortran-style) order. The default is ‘C’.
**kwargs – Extra arguments to matplotlib.axes.Axes.set_ylabel: refer to the matplotlib

erlab.plotting.annotations.sizebar(ax, value, unit, si=0, resolution=1.0, decimals=0, label=None, loc='lower right', pad=0.1, borderpad=0.5, sep=3.0, frameon=False, **kwargs)[source]¶

Add a size bar to an axes.

Parameters:

ax (Axes) – The matplotlib.axes.Axes instance to place the size bar in.
value (float) – Length of the size bar in terms of unit.
unit (str) – An SI unit string without any prefixes. For example, ‘m’ for meters.
si (int, default: 0) – Exponents that have a corresponding SI prefix. This determines the unit of the label that is shown next to the size bar. For example, if the value is 200e-6 and the unit is "m", setting si=-6 will result in a label of "200 μm", and si=-3 will result in "0.2 mm" (assuming decimals is set appropriately).
resolution (float, default: 1.0) – Scale of the current axes coordinates. For example, if the plot axes values are given in μm, the resolution should be 1e-6.
decimals (int, default: 0) – Number of decimals displayed on the size bar label.
label (str | None, default: None) – When provided, overrides the automatically generated label string.
loc (Literal['upper left', 'upper center', 'upper right', 'center left', 'center', 'center right', 'lower left', 'lower center', 'lower right'], default: "lower right") – Location of the size bar.
pad (float, default: 0.1) – Padding around the label and size bar, in fraction of the font size.
borderpad (float, default: 0.5) – Border padding, in fraction of the font size.
sep (float, default: 3.0) – Separation between the label and the size bar, in points.
frameon (bool, default: False) – If True, draw a box around the horizontal bar and label.
**kwargs – Keyword arguments forwarded to mpl_toolkits.axes_grid1.anchored_artists.AnchoredSizeBar.

Example

>>> # Plot a size bar with a length of 200 μm on an axes given in mm
>>> eplt.sizebar(ax, value=200e-6, unit="m", si=-6, resolution=1e-3)