Plot-Subfunctions

Optics Measurements Plots

Constants

Constants and definitions for the plotting module.

Utils

This module contains utilities for the plotting module.

class omc3.plotting.optics_measurements.utils.DataSet(x: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], y: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes], err: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes] | None = None)

Container to store the data to plot.

class omc3.plotting.optics_measurements.utils.FigureCollector

Class to collect figure containers and manage data adding.

add_data_for_id(figure_id: str, label: str, data: DataSet, x_label: str, y_label: str, path: Path | None = None, axes_id: str = '', axes_ids: Iterable[str] = ('',)) → None

Add the data at the appropriate figure container.

class omc3.plotting.optics_measurements.utils.FigureContainer(id_: str, path: Path, axes_ids: Iterable[str])

Container for attaching additional information to one figure.

class omc3.plotting.optics_measurements.utils.IDMap(figure_id: str, axes_id: str, legend_label: str, ylabel: str)

Container to store current figure and axes (id)-information.

omc3.plotting.optics_measurements.utils.safe_format(label: str, insert: str) → str | None

Formats label. Usually just .format() works fine, even if there is no {}-placeholder in the label, but it might cause errors if latex is used in the label or None. Hence the try-excepts.

Parameters:

• label (str) -- label to be formatted

• insert (str) -- string to be inserted into label

Returns:

String, if everything went alright. None otherwise.

Spectrum Plots

Plot Spectrum - Stem Plotter

Stem plotting functionality for spectrum plotter.

omc3.plotting.spectrum.stem.create_stem_plots(figures: dict, opt: DotDict) → None

Main loop for stem-plot creation.

Plot Spectrum - Waterfall Plotter

Waterfall plotting functionality for spectrum plotter.

omc3.plotting.spectrum.waterfall.create_waterfall_plots(figures: dict, opt: DotDict) → None

Main loop for waterfall plot creation.

Plot Spectrum - Utilities

Common functions and sorting functions for the spectrum plotter.

class omc3.plotting.spectrum.utils.FigureCollector

Class to collect figure containers and manage data adding.

add_data_for_id(id_data: IdData, data: dict) → None

Add the data at the appropriate figure container.

class omc3.plotting.spectrum.utils.FigureContainer(path: str)

Container for attaching additional information to one figure.

class omc3.plotting.spectrum.utils.IdData(id_: str, label: str, path: str)

Container to keep track of the id-sorting output

omc3.plotting.spectrum.utils.filter_amps(files: dict, limit: float)

Filter amplitudes by limit.

omc3.plotting.spectrum.utils.get_bpms(lin_files: dict, given_bpms: Iterable, filename: str, planes: Iterable = ('X', 'Y')) → dict

Return the bpm-names of the given bpms as found in the lin files. ‘file_path’ is only used for the error messages.

omc3.plotting.spectrum.utils.get_cycled_color(idx: int)

Get the color at (wrapped) idx in the color cycle. The CN-Method only works until ‘C9’.

omc3.plotting.spectrum.utils.get_data_for_bpm(data: dict, bpm: str, rescale: bool) → dict

Loads data from files and returns a dictionary (over planes) of a dictionary over the files containing the bpm data as pandas series.

omc3.plotting.spectrum.utils.get_stem_id(filename: str, bpm: str, output_dir: str, combine_by: frozenset, filetype: str) → IdData

Returns the stem-dictionary id and the path to which the output file should be written. By using more or less unique identifiers, this controls the creation of figures in the dictionary.

omc3.plotting.spectrum.utils.get_unique_filenames(files: Iterable | Sized)

Way too complicated method to assure unique dictionary names, by going backwards through the file-path until the names differ.

omc3.plotting.spectrum.utils.get_waterfall_id(filename: str, bpm: str, output_dir: str, combine_by: frozenset, filetype: str) → IdData

Returns the waterfall-dictionary id and the path to which the output file should be written. By using identifiers for figures and unique lables per figure, this controls the creation of figures in the dictionary.

omc3.plotting.spectrum.utils.index_filter(data: Series)

Only non-NaN and non-Zero data allowed. (Amps should not be zero due to _filter_amps() anyway.)

omc3.plotting.spectrum.utils.load_spectrum_data(file_path: Path, bpms: Iterable, planes: Iterable = ('X', 'Y'))

Load Amps, Freqs and Lin Files into a dictionary, keys are the fileendings without plane, with subdicts of the planes.

Common Plot Functionality

Plotting Utilities: Annotations

Helper functions to create annotations, legends as well as style labels in plots.

class omc3.plotting.utils.annotations.OOMFormatter(order=0, fformat='%1.1f', offset=True, mathText=True)

Order of Magnitude Formatter.

To set a fixed order of magnitude and fixed significant numbers. As seen on: https://stackoverflow.com/a/42658124/5609590

See: set_sci_magnitude

omc3.plotting.utils.annotations.figure_title(text, ax=None, pad=0, **kwargs)

Set the title all the way to the top.

Parameters:

• text -- Text for the title.

• ax -- Axes to use. If None is given, takes the current axes. Defaults to None.

• pad -- Padding from border.

• kwargs -- passed on to fontdict.

omc3.plotting.utils.annotations.get_annotation(ax=None, by_reference=True)

Returns the annotation set by set_annotation().

Parameters:

• ax -- Axes to get annotation from. If None is given, takes the current figure. Defaults to None.

• by_reference (bool) -- If True, returns the reference to the annotation, otherwise the text as string. Defaults to True.

omc3.plotting.utils.annotations.get_ip_positions(path)

Returns a dict of IP positions from tfs-file of path.

Parameters:

path (str) -- Path to the tfs-file containing IP-positions.

omc3.plotting.utils.annotations.get_legend_ncols(labels, max_length=78)

Calculate the number of columns in legend dynamically.

omc3.plotting.utils.annotations.get_name(fig_or_ax=None)

Returns the name of the figure or axes.

Parameters:

fig_or_ax -- Figure or Axes to to use.If None is given, takes the current figure. Defaults to None.

omc3.plotting.utils.annotations.make_top_legend(ax, ncol, frame=False, handles=None, labels=None, pad=0.02, transposed=False)

Create a legend on top of the plot.

omc3.plotting.utils.annotations.move_ip_labels(value, ax=None)

Moves IP labels according to max y * value.

omc3.plotting.utils.annotations.set_annotation(text, ax=None, position='right', pad=0.02)

Writes an annotation on the top right of the axes.

Parameters:

• text -- The annotation.

• ax -- Axes to set annotation on. If None is given, takes the current figure. Defaults to None.

• position -- left or right.

• pad -- padding to the axes.

omc3.plotting.utils.annotations.set_name(name, fig_or_ax=None)

Sets the name of the figure or axes.

Parameters:

• name (str) -- string to set as name.

• fig_or_ax -- Figure or Axes to to use. If None is given, takes the current figure. Defaults to None.

omc3.plotting.utils.annotations.set_sci_magnitude(ax, axis='both', order=0, fformat='%1.1f', offset=True, math_text=True)

Uses the OMMFormatter to set the scientific limits on axes.

Parameters:

• ax -- Plotting axes.

• axis (str) -- x, y or both.

• order (int) -- Magnitude Order.

• fformat (str) -- Format to use.

• offset (bool) -- Formatter offset.

• math_text (bool) -- Whether to use mathText.

omc3.plotting.utils.annotations.set_xaxis_label(ax=None)

Sets the standard x-axis label

Parameters:

ax -- Axes to put the label on. Defaults to gca().

omc3.plotting.utils.annotations.set_yaxis_label(param, plane, ax=None, delta=False, chromcoup=False)

Set y-axis labels.

Parameters:

• param -- One of the labels defined in ylabel in this module.

• plane -- Usually x or y, but can be any string actually to be placed into the label ({0}).

• ax -- Axes to put the label on. Defaults to `` gca()``.

• delta -- If True adds a Delta before the label. Defaults to False.

omc3.plotting.utils.annotations.show_ir(ip_dict, ax=None, mode='inside')

Plots the interaction regions into the background of the plot.

Parameters:

• ip_dict -- dict, dataframe or series containing IPLABEL : IP_POSITION.

• ax -- Axes to put the irs on. Defaults to gca()``.

• mode -- inside, outside + nolines or just lines.

omc3.plotting.utils.annotations.small_title(ax=None)

Alternative to annotation, which lets you use the title-functions.

Parameters:

ax -- Axes to use. If None is given, takes the current axes. Defaults to None.

omc3.plotting.utils.annotations.transpose_legend_order(ncol, handles=None, labels=None, ax=None)

Reorder handles and labels, so that the legend order is transposed, i.e. the entries are row-first instead of column-first.

Plotting Utilities: Colors

Helper functions to handle colors in plots.

omc3.plotting.utils.colors.change_color_brightness(color, amount=0.5)

Lightens the given color by multiplying (1-luminosity) by the given amount. Input can be matplotlib color string, hex string, or RGB tuple. An amount of 1 equals to no change. 0 is very bright (white) and 2 is very dark. Original code by Ian Hincks Source: https://stackoverflow.com/questions/37765197/darken-or-lighten-a-color-in-matplotlib

omc3.plotting.utils.colors.change_ebar_alpha_for_axes(ax, alpha)

Wrapper for change_ebar_alpha_for_line to change all in one axes.

omc3.plotting.utils.colors.change_ebar_alpha_for_line(ebar, alpha)

Changes the alpha value of an error-bar container. Loop through bars (ebar[1]) and caps (ebar[2]) and set the alpha value.

omc3.plotting.utils.colors.get_mpl_color(idx=None)

Gets the ‘new’ default matplotlib colors by index, or the whole cycle.

omc3.plotting.utils.colors.rgb_plotly_to_mpl(rgb_string)

Helper function to transforn plotly rbg to matplotlib rgb.

Plotting Utilities: Lines

Line-plotting related functionality.

class omc3.plotting.utils.lines.MarkerList

Create a list of predefined markers.

classmethod get_marker(marker_num)

Return marker of index marker_num

Parameters:

marker_num (int) -- return maker at this position in list (mod len(list))

get_next_marker()

Return the next marker in the list (circularly wrapped)

omc3.plotting.utils.lines.plot_vertical_line(ax, axvline_args: dict, text: str | None = None, text_loc: str | None = None, label_size: float = 10.0)

Plot a vertical line into the plot, where mline is a dictionary with arguments for axvline. Advanced capabilities include: Automatic alpha value (if not overwritten), automatic zorder = -1 (if not overwritten), and adding a label to the line, where the location is given by text_loc.

omc3.plotting.utils.lines.plot_vertical_lines_fast(ax, x, y=(0, 1), **kwargs)

Plots vertical lines, similar to axvline, but also in 3D, all at once and with only one label.

Parameters:

• ax -- Axis to plot on.

• x -- array of x-positions (data coordinates).

• y -- tuple of y-limits (axis coordinates, default (0,1) i.e. bottom to top).

• kwargs -- kwargs passed on to ax.plot.

omc3.plotting.utils.lines.text_to_marker(text: str, center: bool = True) → ndarray

Convert the given text to path which can be used as a marker in matplotlib plots, including the options of setting markerfacecolor and markeredgecolor.

Parameters:

• text (str) -- Text to use as a marker.

• center (bool) -- Center the path around the origin (otherwise bottom left is anchor).

Returns:

Array of the path vertices.

Plotting Utilities: Style

Helper functions to style plots.

omc3.plotting.utils.style.set_style(styles: Path | str | Sequence[Path | str] = 'standard', manual: Dict[str, Any] | None = None)

Sets the style for all following plots.

Parameters:

• styles -- List of styles (or single string), either path to style-file, name of style in styles or from the mpl styles

• manual -- Dict of manual parameters to update. Convention: REMOVE_ENTRY removes entry from given styles, i.e. falls back to mpl default.

Plot Window

In this module different classes are defined, allowing to put matplotlib figures manually into GUI windows. These windows are QT-based, created with qtpy which allows to use either PySide(2 or 6) or PyQt(5 or 6), depending on which it installed on the system. As the qtpy library is optional, there are some checks to make sure the imports do not fail, but then the classes cannot be used. To check if QtPy is installed, either run omc3.plotting.plot_window.is_qtpy_installed() or try to initialize one of the windows, which will fail with a TypeError, as they want to call QApplication which is set to None.

An exception to all of this is omc3.plotting.plot_window.create_pyplot_window_from_fig(), which allows to create a pyplot handled window from an already existing figure. This way, figures can be created without manager (which makes them resource friendlier) and can either be added to a QT-Window or, if not installed, opened by pyplot.

omc3.plotting.utils.windows.create_pyplot_window_from_fig(fig: Figure, title: str | None = None)

Create a window from the given figure, which is managed by pyplot. This is similar to how figures behave when created with pyplot.figure(), but you can crate the figure instance first and the manager later.

Caveat: Uses private functions of pyplot.

Parameters:

• fig (Figure) -- figure to be managed by pyplot.

• title (str) -- Title of the window.

omc3.plotting.utils.windows.is_qtpy_installed()

Returns True if QtPy is installed.

omc3.plotting.utils.windows.log_no_qtpy_many_windows()

Logs a warning that QtPy is not installed and many windows will be opened.