erlab.plotting.annotations

Plot annotations.

Module Attributes

SI_PREFIXES

Maps powers of 10 to valid SI prefix strings.

SI_PREFIX_NAMES

Names of the SI prefixes.

PRETTY_NAMES

Pretty names for labeling plots.

PRETTY_UNITS

Pretty units for labeling plots.

Functions

copy_mathtext(s[, fontsize, fontproperties, ...])

fancy_labels([ax, deg2rad])

get_si_str(si)

Return the SI prefix string to be plotted by matplotlib.

label_for_dim(dim_name[, deg2rad, escaped])

label_subplot_properties(axes, values[, ...])

Labels subplots with automatically generated labels.

label_subplots(axes[, values, startfrom, ...])

Labels subplots with automatically generated labels.

label_subplots_nature(axes[, values, ...])

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.

mark_points_y(pts, labels[, roman, bar, ax])

name_for_dim(dim_name[, escaped])

parse_point_labels(name[, roman, bar])

parse_special_point(name)

plot_hv_text(ax, val[, x, y])

plot_hv_text_right(ax, val[, x, y])

property_label(key, value[, decimals, si, ...])

scale_units(ax, axis[, si, prefix, power])

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

set_titles(axes, labels[, order])

set_xlabels(axes, labels[, order])

set_ylabels(axes, labels[, order])

sizebar(ax, value, unit[, si, resolution, ...])

Add a size bar to an axes.

unit_for_dim(dim_name[, deg2rad])

erlab.plotting.annotations.copy_mathtext(s, fontsize=None, fontproperties=None, outline=False, svg=True, rcparams=None, **mathtext_rc)[source]
erlab.plotting.annotations.fancy_labels(ax=None, deg2rad=False)[source]
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 (matplotlib.axes.Axes | Iterable[matplotlib.axes.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.

  • decimals (int | 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) – Powers of 10 for automatic SI prefix setting.

  • name (str | None) – When set, overrides automatic dimension name setting.

  • unit (str | None) – When set, overrides automatic unit setting.

  • order (Literal['C', 'F', 'A', 'K']) – 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’.

  • **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 (matplotlib.axes.Axes | Iterable[matplotlib.axes.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) – Integer or string labels corresponding to each Axes in axes for manual labels.

  • startfrom (int) – Start from this number when creating automatic labels. Has no effect when values is not None.

  • order (Literal['C', 'F', 'A', 'K']) – 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']) – The box location. The default is 'upper left'.

  • offset (tuple[float, float]) – Values that are used to position the legend in conjunction with loc, given in display units.

  • prefix (str) – String to prepend to the alphabet label.

  • suffix (str) – String to append to the alphabet label.

  • numeric (bool) – Use integer labels instead of alphabets.

  • capital (bool) – Capitalize automatically generated alphabetical labels.

  • fontweight (Literal['ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black']) – Set the font weight. The default is 'normal'.

  • fontsize (float | Literal['xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'] | 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.label_subplots_nature(axes, values=None, startfrom=1, order='C', offset=(-20.0, 7.0), prefix='', suffix='', numeric=False, capital=False, fontweight='black', fontsize=8, **kwargs)[source]

Labels subplots with automatically generated labels.

Parameters:

  • axes (matplotlib.axes.Axes | Sequence[matplotlib.axes.Axes]) – matplotlib.axes.Axes to label. If an array is given, the order will be determined by the flattening method given by order.

  • values (Sequence[int | str] | None) – Integer or string labels corresponding to each Axes in axes for manual labels.

  • startfrom (int) – Start from this number when creating automatic labels. Has no effect when values is not None.

  • order (Literal['C', 'F', 'A', 'K']) – 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’.

  • offset (tuple[float, float]) – Values that are used to position the labels, given in points.

  • prefix (str) – String to prepend to the alphabet label.

  • suffix (str) – String to append to the alphabet label.

  • numeric (bool) – Use integer labels instead of alphabets.

  • capital (bool) – Capitalize automatically generated alphabetical labels.

  • fontweight (Literal['ultralight', 'light', 'normal', 'regular', 'book', 'medium', 'roman', 'semibold', 'demibold', 'demi', 'bold', 'heavy', 'extra bold', 'black']) – Set the font weight. The default is 'normal'.

  • fontsize (float | Literal['xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large']) – 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]) – Position of the label in data coordinates

  • pad (tuple[float, float]) – Offset of the text in points.

  • literal (bool) – If True, take the input string literally.

  • roman (bool) – If False, True, itallic fonts are used.

  • bar (bool) – If True, prints a bar over the label.

  • ax (matplotlib.axes.Axes | Iterable[matplotlib.axes.Axes] | None) – matplotlib.axes.Axes to annotate.

erlab.plotting.annotations.mark_points_outside(points, labels, axis='x', roman=True, bar=False, ax=None)[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']) – If 'x', marks points along the horizontal axis. If 'y', marks points along the vertical axis.

  • roman (bool) – If False, True, itallic fonts are used.

  • bar (bool) – If True, prints a bar over the label.

  • ax (matplotlib.axes.Axes | Iterable[matplotlib.axes.Axes] | None) – matplotlib.axes.Axes to annotate.

erlab.plotting.annotations.plot_hv_text(ax, val, x=0.025, y=0.975, **kwargs)[source]
erlab.plotting.annotations.property_label(key, value, decimals=None, si=0, name=None, unit=None)[source]
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 (matplotlib.axes.Axes | Iterable[matplotlib.axes.Axes]) – _description_

  • axis (Literal['x', 'y', 'z']) – The axis you wish to rescale.

  • si (int) – Exponent of 10 corresponding to a SI prefix.

  • prefix (bool) – 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) – 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]
erlab.plotting.annotations.set_xlabels(axes, labels, order='C', **kwargs)[source]
erlab.plotting.annotations.set_ylabels(axes, labels, order='C', **kwargs)[source]
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 prefixes.

  • si (int) – Exponents that have a corresponding SI prefix

  • resolution (float) – Value to scale the data coordinates in terms of unit.

  • decimals (int) – Number of decimals on the size bar label.

  • label (str | 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']) – Location of the size bar.

  • pad (float) – Padding around the label and size bar, in fraction of the font size.

  • borderpad (float) – Border padding, in fraction of the font size.

  • sep (float) – Separation between the label and the size bar, in points.

  • frameon (bool) – If True, draw a box around the horizontal bar and label.

  • **kwargs – Keyword arguments forwarded to mpl_toolkits.axes_grid1.anchored_artists.AnchoredSizeBar.

erlab.plotting.annotations.SI_PREFIXES: dict[int, str] = {-24: 'y', -21: 'z', -18: 'a', -15: 'f', -12: 'p', -9: 'n', -6: 'μ', -3: 'm', -2: 'c', -1: 'd', 0: '', 1: 'da', 2: 'h', 3: 'k', 6: 'M', 9: 'G', 12: 'T', 15: 'P', 18: 'E', 21: 'Z', 24: 'Y'}

Maps powers of 10 to valid SI prefix strings.

erlab.plotting.annotations.SI_PREFIX_NAMES: tuple[str, ...] = ('yotta', 'zetta', 'exa', 'peta', 'tera', 'giga', 'mega', 'kilo', 'hecto', 'deca', '', 'deci', 'centi', 'milli', 'micro', 'nano', 'pico', 'femto', 'atto', 'zepto', 'yocto')

Names of the SI prefixes.