Plotting

Plot Optics Measurements

Wrapper for plot_tfs to easily plot the results from optics measurements.

from omc3.plotting.plot_optics_measurements import plot

figs = plot(
    folders=['folder1', 'folder2'],
    labels=['LabelForFolder1', 'LabelForFolder2'],
    combine_by=['files'],  # to compare folder1 and folder2
    output='output_directory',
    delta=True,  # delta from reference
    optics_parameters=['orbit', 'beta_phase', 'beta_amplitude',
                       'phase', 'total_phase',
                       'f1001_x', 'f1010_x'],
    x_axis='location',  # or 'phase-advance'
    ip_positions='LHCB1',
    suppress_column_legend=True,
    show=True,
    ncol_legend=2,
)

Arguments:

--Required--

folders (PathOrStr):

Optics Measurements folders containing the analysed data.
optics_parameters (str):

Optics parameters to plot, e.g. ‘beta_amplitude’. RDTs need to be specified with plane, e.g. ‘f1001_x’

--Optional--

change_marker:

Changes marker for each line in the plot.

action: store_true
combine_by:

Combine plots into one. Either files, planes (not separated into two axes) or both.

choices: ['files', 'planes']
delta:

Plot the difference to model instead of the parameter.

action: store_true
errorbar_alpha (float):

Alpha value for error bars

default: 0.6
ip_positions:

Input to plot IP-Positions into the plots. Either ‘LHCB1’ or ‘LHCB2’ for LHC defaults, a dictionary of labels and positions or path to TFS file of a model.
ip_search_pattern:

In case your IPs have a weird name. Specify regex pattern.

default: IP\d$
labels (str):

Labels for the folders. If not provided, the folder names (with parents until each label is unique) will be used.
lines_manual (DictAsString):

List of manual lines to plot. Need to contain arguments for axvline, and may contain the additional keys “text” and “loc” which is one of [‘bottom’, ‘top’, ‘line bottom’, ‘line top’] and places the text at the given location.

default: []
manual_style (DictAsString):

Additional style rcParameters which update the set of predefined ones.

default: {}
ncol_legend (int):

Number of bpm legend-columns. If < 1 no legend is shown.

default: 3
output (PathOrStr):

Folder to output the results to.
plot_styles (str):

Which plotting styles to use, either from plotting.styles.*.mplstyles or default mpl.

default: ['standard']
share_xaxis:

In case of multiple axes per figure, share x-axis.

action: store_true
show:

Shows plots.

action: store_true
suppress_column_legend:

Does not show column name in legend e.g. when combining by files (see also ncol_legend).

action: store_true
x_axis:

Which parameter to use for the x axis.

choices: ['location', 'phase-advance']

default: location
x_lim (OptionalFloat):

Limits on the x axis (Tupel)
y_lim (OptionalFloat):

Limits on the y axis (Tupel)

omc3.plotting.plot_optics_measurements.get_plottfs_style_params() → EntryPointParameters[source]: Parameters, that are only passed on.

omc3.plotting.plot_optics_measurements.plot(opt)[source]: Main plotting function.

Plot TFS

Easily plot tfs-files with all kinds of additional functionality and ways to combine plots.

from omc3.plotting.plot_tfs import plot

figs = plot(
    files=['beta_phase_{0}.tfs', 'beta_amp_{0}.tfs'],
    same_figure='planes',
    same_axes=['files'],
    x_columns=['S'],
    y_columns=['BET{0}'],
    error_columns=None,
    planes=['X', 'Y'],
    x_labels=['Location [m]'],
    file_labels=[r'$\beta$ from phase', r'$eta$ from amplitude'],
    # column_labels=[r'$\beta_{0}$'],    # would have bx in legend
    column_labels=[''],                  # removes COLUMNX COLUMNY from legend-names
    y_labels=[[r'$\beta_x$', r'$\beta_y$']],  # axes labels (outer = figures, inner = axes)
    output='output_dir',
    show=False,
    single_legend=True,
    change_marker=True,
)

Arguments:

--Required--

files (MultiClass): Path to files to plot. If planes are used, replace the plane in the filename with ‘{0}’
x_columns (str): List of column names to use as x-values.
y_columns (str): List of column names to plot (e.g. BETX, BETY or BET{0} if planes is used.)

--Optional--

change_marker: Changes marker for each line in the plot.

Action: store_true
column_labels (str): Column-Labels for the plots, default: y_columns.
error_columns (str): List of parameters to get error values from.
errorbar_alpha (float): Alpha value for error bars

Default: 0.6
file_labels (str): Labels for the files, default: filenames.
manual_style (DictAsString): Additional style rcParameters which update the set of predefined ones.

Default: {}
ncol_legend (int): Number of bpm legend-columns. If < 1 no legend is shown.

Default: 3
output (MultiClass): Folder to output the plots to.
output_prefix (str): Prefix for the output filename.

Default: plot_
planes (str): Works only with filenames ending in ‘x’ and ‘y’ and columns ending in X or Y. These suffixes will be attached to the given files and y_columns.

Choices: ('X', 'Y')
plot_styles (str): Which plotting styles to use, either from plotting.styles.*.mplstyles or default mpl.

Default: ['standard']
same_axes (str): Combine plots into single axes. Multiple choices possible.

Choices: ['files', 'columns', 'planes']
same_figure (str): Plot two axes into the same figure (can’t be the same as ‘same_axes’). Has no effect if there is only one of the given thing.

Choices: ['files', 'columns', 'planes']
share_xaxis: In case of multiple axes per figure, share x-axis.

Action: store_true
show: Shows plots.

Action: store_true
single_legend: Show only one legend instance (at the top plot).

Action: store_true
vertical_lines (DictAsString): List of vertical lines (e.g. IR positions) to plot. Need to contain arguments for axvline, and may contain the additional keys “text” and “loc” which is one of [‘bottom’, ‘top’, ‘line bottom’, ‘line top’] and places the text at the given location.

Default: []
x_labels (str): Labels for the x-axis, default: x_columns.
x_lim (float, int, None): Limits on the x axis (Tupel)
y_labels: Override labels for the y-axis, default: file_labels or column_labels (depending on same_axes). Needs to be a list of lists, where the inner list goes over the axes in one figure and the outer over the figures. If the respective length is 1, the same label will be used for all figures or axes.
y_lim (float, int None): Limits on the y axis (Tupel)

omc3.plotting.plot_tfs.get_id(filename_parts, column, file_label, column_label, same_axes, same_figure, prefix, plane='', planes=[])[source]: Get the right IDs for the current sorting way. This is where the actual sorting happens, by mapping the right IDs according to the chosen options.

omc3.plotting.plot_tfs.plot(opt)[source]: Main plotting function.

omc3.plotting.plot_tfs.sort_data(opt)[source]: Load all data from files and sort into figures.

Plot Spectrum

Spectrum plotter for frequency analysis output-data (supports also DRIVE output).

The spectra can be either plotted as stem-plots or as waterfall-plots. The stem-plots can be in any combination: split by given files, split by given bpms or combined in any way (by usage of the combine_by option). Note that if both of those are false (as is default) there will anyway be only one waterfall plot per given input file.

In case of split-by-file, plots are saved in a sub-directory of the given output_dir with the name of the original TbT file. In case of split by bpm the plots will have the bpm-name in their filename.

The lines_tunes and lines_nattunes lists accept tuples of multipliers for the respective tunes, which define the resonance lines plotted into the spectrum as well. A dashed line will indicate the average of all tunes given in the data of one figure, while a semi-transparent area will indicate min- and max- values of this line.

With lines_manual, one can plot vertical lines at manual locations (see parameter specs below).

The function returns two dictionaries, where the first dictionary contains the stem plots and the second one the waterfall plots. They are identifyable by unique id’s which depend on which combination of merging the spectra into one figure is used.

Arguments:

--Required--

files:

List of paths to the spectrum files. The files need to be given without their ‘.lin’/’.amps[xy]’,’.freqs[xy]’ endings. (So usually the path of the TbT-Data file.)

--Optional--

amp_limit (float):

All amplitudes <= limit are filtered. This value needs to be at least 0 to filter non-found frequencies.

default: 0.0
bpms:

List of BPMs for which spectra will be plotted. If not given all BPMs are used.
combine_by:

Choose how to combine the data into figures.

choices: ['bpms', 'files']

default: []
filetype (str):

Filetype to save plots as (i.e. extension without “.”)

default: pdf
lines_manual (DictAsString):

List of manual lines to plot. Need to contain arguments for axvline, and may contain the additional keys “text” and “loc” which is one of [‘bottom’, ‘top’, ‘line bottom’, ‘line top’] and places the text at the given location.

default: []
lines_nattunes (tuple):

List of natural tune lines to plot

default: [(1, 0), (0, 1)]
lines_tunes (tuple):

list of tune lines to plot

default: [(1, 0), (0, 1)]
manual_style (DictAsString):

Additional style rcParameters which update the set of predefined ones.

default: {}
ncol_legend (int):

Number of bpm legend-columns. If < 1 no legend is shown.

default: 5
output_dir (str):

Directory to write results to. If no option is given, plots will not be saved.
plot_styles (UnionPathStr):

Which plotting styles to use, either from plotting.styles.*.mplstyles or default mpl.

default: ['standard', 'spectrum']
plot_type:

Choose plot type (Multiple choices possible).

choices: ['stem', 'waterfall']

default: ['stem']
rescale:

Flag to rescale plots amplitude to max-line = 1

action: store_true
show_plots:

Flag to show plots

action: store_true
waterfall_cmap (str):

Colormap to use for waterfall plot.

default: inferno
waterfall_common_plane_colors:

Same colorbar scale for both planes in waterfall plots.

action: store_true
waterfall_line_width:

Line width of the waterfall frequency lines. “auto” fills them up until the next one.

default: 2
xlim (float):

Limits on the x axis (Tupel)

default: [0, 0.5]
ylim (float):

Limits on the y axis (Tupel)

default: [1e-09, 1.0]

omc3.plotting.plot_spectrum.get_reshuffled_tab20c()[source]: Reshuffle tab20c so that the colors change between next lines. Needs to be up here as it is used in DEFAULTS which is loaded early.

Plot Correction Test

Create plots for the correction tests performed with omc3.scripts.correction_test.

Arguments:

--Required--

input_dir (PathOrStr):

Path to the output_dir from omc3.correction_test.

--Optional--

change_marker:

Changes marker for each line in the plot.

action: store_true
combine_by:

Combine plots into one. Either files, planes (not separated into two axes) or both.

choices: ['files', 'planes']
corrections (str):

Corrections to plot (assumed to be subfolders in input_dir).

default: ['']
errorbar_alpha (float):

Alpha value for error bars

default: 0.6
individual_to_input:

Save plots for the individual corrections into the corrections input folders. Otherwise they go with suffix into the output_folders.

action: store_true
ip_positions:

Input to plot IP-Positions into the plots. Either ‘LHCB1’ or ‘LHCB2’ for LHC defaults, a dictionary of labels and positions or path to TFS file of a model.
ip_search_pattern:

In case your IPs have a weird name. Specify regex pattern.

default: IP\d$
lines_manual (DictAsString):

List of manual lines to plot. Need to contain arguments for axvline, and may contain the additional keys “text” and “loc” which is one of [‘bottom’, ‘top’, ‘line bottom’, ‘line top’] and places the text at the given location.

default: []
manual_style (DictAsString):

Additional style rcParameters which update the set of predefined ones.

default: {}
meas_dir (PathOrStr):

Path to the directory containing the measurement filesto plot the measurement as comparison.If not given, the data from the first corrections directory will be used.
ncol_legend (int):

Number of bpm legend-columns. If < 1 no legend is shown.

default: 3
output_dir (PathOrStr):

Path to save the plots into. If not given, no plots will be saved.
plot_styles (str):

Which plotting styles to use, either from plotting.styles.*.mplstyles or default mpl.

default: ['standard', 'correction_test']
share_xaxis:

In case of multiple axes per figure, share x-axis.

action: store_true
show:

Shows plots.

action: store_true
suppress_column_legend:

Does not show column name in legend e.g. when combining by files (see also ncol_legend).

action: store_true
x_axis:

Which parameter to use for the x axis.

choices: ['location', 'phase-advance']

default: location
x_lim (MultiClass):

Limits on the x axis (Tupel)
y_lim (MultiClass):

Limits on the y axis (Tupel)

omc3.plotting.plot_checked_corrections.get_plotting_style_parameters()[source]: Parameters related to the style of the plots.

omc3.plotting.plot_checked_corrections.plot_checked_corrections(opt: DotDict)[source]: Entrypoint for the plotting function.

omc3.plotting.plot_checked_corrections.save_plots(output_dir: Path, figure_dict: Dict[str, Figure], input_dir: Path | None = None)[source]: Save the plots.

omc3.plotting.plot_checked_corrections.show_plots(figure_dict: Dict[str, Figure])[source]: Displays the provided figures. If qtpy is installed, they are shown in a single window. The individual corrections are sorted into vertical tabs, the optics parameter into horizontal tabs. If qtpy is not installed, they are simply shown as individual figures. This is not recommended

Plot Amplitude Detuning Results

Provides the plotting function for amplitude detuning analysis

Arguments:

--Required--

kicks:

Kick files as data frames or tfs files.
labels (str):

Labels for the data. Needs to be same length as kicks.
plane (str):

Plane of the kicks.

choices: ['X', 'Y', 'XY', '3D']

--Optional--

action_plot_unit (str):

Unit the action should be plotted in.

choices: ['km', 'm', 'mm', 'um', 'nm', 'pm', 'fm', 'am']

default: um
action_unit (str):

Unit the action is given in.

choices: ['km', 'm', 'mm', 'um', 'nm', 'pm', 'fm', 'am']

default: m
bbq_corrected (bool):

Plot the data with BBQ correction (True) or without (False). None plots both in separate plots. Default: None.
correct_acd:

Correct for AC-Dipole kicks.

action: store_true
detuning_order (int):

Order of the detuning as int. Basically just the order of the applied fit.

default: 1
manual_style (DictAsString):

Additional style rcParameters which update the set of predefined ones.

default: {}
output (str):

Save the amplitude detuning plot here. Give filename with extension. An id for the 4 different plots will be added before the suffix.
plot_styles (UnionPathStr):

Plotting styles.

default: ['standard', 'amplitude_detuning']
show:

Show the amplitude detuning plot.

action: store_true
tune_scale (int):

Plotting exponent of the tune.

default: -3
x_lim (float):

Action limits in um (x-axis).
y_lim (float):

Tune limits in units of tune scale (y-axis).

class omc3.plotting.plot_amplitude_detuning.FitFuncs(fit: <built-in function callable>, upper: <built-in function callable>, lower: <built-in function callable>)[source]

omc3.plotting.plot_amplitude_detuning.plot_cube(ax: Axes, 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], f_low: callable, f_upp: callable, **kwargs)[source]: Plots a cube-like plot with f_low and f_upp as surfaces.

omc3.plotting.plot_amplitude_detuning.plot_odr(ax: Axes, odr_fit: Output, xmax: float, label: str = '', color=None)[source]: Adds a quadratic odr fit to axes.

omc3.plotting.plot_amplitude_detuning.plot_odr_3d(ax: Axes, odr_fits: Dict[str, Output], xymax: Sequence[float], color=None)[source]: Plot the odr fit in 3D.

Plot BBQ

Provides the plotting function for the extracted and cleaned BBQ data from timber.

Arguments:

--Required--

input:

BBQ data as data frame or tfs file.

--Optional--

interval (float):

x_axis interval that was used in calculations.
kick:

Kick file as data frame or tfs file.
manual_style (DictAsString):

Additional style rcParameters which update the set of predefined ones.

default: {}
output (str):

Save figure to this location.
plot_styles (UnionPathStr):

Which plotting styles to use, either from plotting.styles.*.mplstyles or default mpl.

default: ['standard', 'bbq']
show:

Show plot.

action: store_true
two_plots:

Plot two axis into the figure.

action: store_true
x_lim (float):

X-Axis limits. (yyyy-mm-dd HH:mm:ss.mmm)
y_lim (float):

Y-Axis limits.

omc3.plotting.plot_bbq.main(opt)[source]: Plot BBQ wrapper.