Tune Analysis

Package Content

Module tune_analysis.bbq_tools

Tools to handle BBQ data.

This package contains a collection of tools to handle and modify BBQ data:

• Calculating moving average
• Plotting

tune_analysis.bbq_tools.get_moving_average(data_series, length=20, min_val=None, max_val=None, fine_length=None, fine_cut=None)

Get a moving average of the data_series over length entries. The data can be filtered beforehand. The values are shifted, so that the averaged value takes ceil((length-1)/2) values previous and floor((length-1)/2) following values into account.

Parameters:

• data_series -- Series of data
• length -- length of the averaging window
• min_val -- minimum value (for filtering)
• max_val -- maximum value (for filtering)
• fine_length -- length of the averaging window for fine cleaning
• fine_cut -- allowed deviation for fine cleaning

Returns: filtered and averaged Series and the mask used for filtering data.

tune_analysis.bbq_tools.plot_bbq_data(bbq_df, interval=None, xmin=None, xmax=None, ymin=None, ymax=None, output=None, show=True, two_plots=False)

Plot BBQ data.

Parameters:

• bbq_df -- BBQ Dataframe with moving average columns
• interval -- start and end time of used interval, will be marked with red bars
• xmin -- Lower x limit (time)
• xmax -- Upper x limit (time)
• ymin -- Lower y limit (tune)
• ymax -- Upper y limit (tune)
• output -- Path to the output file
• show -- Shows plot if True
• two_plots -- Plots each tune in it’s own axes if True

Returns:

Plotted figure

Module tune_analysis.constants

tune_analysis.constants.get_action_col(plane)

Label for the action column.

tune_analysis.constants.get_action_err_col(plane)

Label for the action error column.

tune_analysis.constants.get_bbq_col(plane)

Label for the BBQ column

tune_analysis.constants.get_experiment_timezone()

Get time zone for measurement data.

tune_analysis.constants.get_mav_col(plane)

Label for the moving average BBQ column.

tune_analysis.constants.get_mav_std_col(plane)

Label for the standard deviation of the moving average data.

tune_analysis.constants.get_natq_col(plane)

Label for the natural tune column.

tune_analysis.constants.get_natq_corr_col(plane)

Label for the corrected natural tune column.

tune_analysis.constants.get_natq_err_col(plane)

Label for the natural tune error column.

tune_analysis.constants.get_odr_header_offset(j_plane, q_plane)

Header key for odr offset (i.e. beta[0])

tune_analysis.constants.get_odr_header_offset_corr(j_plane, q_plane)

Header key for corrected odr offset (i.e. beta[0])

tune_analysis.constants.get_odr_header_slope(j_plane, q_plane)

Header key for odr slope (i.e. beta[1])

tune_analysis.constants.get_odr_header_slope_corr(j_plane, q_plane)

Header key for corrected odr slope (i.e. beta[1])

tune_analysis.constants.get_odr_header_slope_std(j_plane, q_plane)

Header key for odr slope standard deviation (i.e. sd_beta[1])

tune_analysis.constants.get_odr_header_slope_std_corr(j_plane, q_plane)

Header key for corrected odr slope standard deviation (i.e. sd_beta[1])

tune_analysis.constants.get_paired_lables(action_plane, tune_plane)

Labels for the action/tune plots.

tune_analysis.constants.get_planes()

Names for the planes.

tune_analysis.constants.get_tend_head()

Label for fill end time from header.

tune_analysis.constants.get_timber_bbq_key(plane, beam)

Key to extract bbq from timber.

tune_analysis.constants.get_time_col()

Label for the TIME column.

tune_analysis.constants.get_total_natq_std_col(plane)

Return the total standard deviation for the natural tune.

tune_analysis.constants.get_tstart_head()

Label for fill start time from header.

tune_analysis.constants.get_used_in_mav_col(plane)

Label for the column showing if BBQ value was used in moving average.

Module tune_analysis.detuning_tools

Some tools for amplitude detuning, mainly plotting.

Important Convention:

The beta-parameter in the ODR models go upwards with order, i.e. | beta[0] = y-Axis offset | beta[1] = slope | beta[2] = quadratic term | etc.

tune_analysis.detuning_tools.do_linear_odr(x, y, xerr, yerr)

Returns linear odr fit.

Parameters:

• x -- Series of x data
• y -- Series of y data
• xerr -- Series of x data errors
• yerr -- Series of y data errors

Returns: Linear odr fit. Betas see linear_model().

tune_analysis.detuning_tools.linear_model(beta, x)

Return a linear model beta[0] + beta[1] * x.

Parameters:

• beta -- beta[0] = y-offset beta[1] = slope
• x -- x-value

tune_analysis.detuning_tools.plot_detuning(x, y, xerr, yerr, labels, xmin=None, xmax=None, ymin=None, ymax=None, odr_fit=None, odr_plot=<function plot_linear_odr>, output=None, show=True)

Plot amplitude detuning.

Parameters:

• x -- Action data.
• y -- Tune data.
• xerr -- Action error.
• yerr -- Tune error.
• xmin -- Lower action range to plot.
• xmax -- Upper action range to plot.
• ymin -- Lower tune range to plot.
• ymax -- Upper tune range to plot.
• odr_fit -- results of the odr-fit (e.g. see do_linear_odr)
• odr_plot -- function to plot odr_fit (e.g. see plot_linear_odr)
• labels -- Dict of labels to use for the data (“line”), the x-axis (“x”) and the y-axis (“y”)
• output -- Output file of the plot.
• show -- Show the plot in window.

Returns:

Plotted Figure

tune_analysis.detuning_tools.plot_linear_odr(ax, odr_fit, lim)

Adds a linear odr fit to axes.

tune_analysis.detuning_tools.print_odr_result(printer, odr_out)

Logs the odr output results.

Adapted from odr_output pretty print.

Module tune_analysis.kickac_modifiers

Functions to add data to or extract data from kick_ac files.

tune_analysis.kickac_modifiers.add_bbq_data(kickac_df, bbq_series, column)

Add bbq values from series to kickac dataframe into column.

Parameters:

• kickac_df -- kickac dataframe (needs to contain column “TIME_COL” or has time as index)
• bbq_series -- series of bbq data with time as index
• column -- column name to add the data into

Returns: modified kickac dataframe

tune_analysis.kickac_modifiers.add_corrected_natural_tunes(kickac_df)

Adds the corrected natural tunes to kickac

Parameters:kickac_df -- Dataframe containing the data Returns:Modified kick_ac

tune_analysis.kickac_modifiers.add_moving_average(kickac_df, bbq_df, **kwargs)

Adds the moving average of the bbq data to kickac_df and bbq_df.

tune_analysis.kickac_modifiers.add_odr(kickac_df, odr_fit, action_plane, tune_plane, corrected=False)

Adds the odr fit of the (un)corrected data to the header of the kickac.

Parameters:

• kickac_df -- Dataframe containing the data
• odr_fit -- odr-fit data (definitions see detuning_tools.py)
• action_plane -- Plane of the action
• tune_plane -- Plane of the tune

Returns:

Modified kick_ac

tune_analysis.kickac_modifiers.add_total_natq_std(kickac_df)

Add the total standard deviation of the natural tune to the kickac. The total standard deviation is here defined as the standard deviation of the measurement plus the standard deviation of the moving average.

Parameters:kickac_df -- Dataframe containing the data Returns:Modified kick_ac

tune_analysis.kickac_modifiers.get_ampdet_data(kickac_df, action_plane, tune_plane, corrected=False)

Extract the data needed for plotting the (un)corrected amplitude detuning from the kickac dataframe.

Parameters:

• kickac_df -- Dataframe containing the data
• action_plane -- Plane of the action
• tune_plane -- Plane of the tune

Returns:

Dictionary containing x,y, x_err and y_err

tune_analysis.kickac_modifiers.get_odr_data(kickac_df, action_plane, tune_plane, corrected=False)

Extract the data from odr.

Parameters:

• kickac_df -- Dataframe containing the data
• action_plane -- Plane of the action
• tune_plane -- Plane of the tune

Returns:

Dictionary containing x,y, ylower, yupper, offset and label

Module tune_analysis.timber_extract

Tools to extract data from timber.

It is a bit heavy on the LHC-side at the moment. Feel free to make it more accelerator independent.

tune_analysis.timber_extract.extract_between_times(t_start, t_end, keys=None, names=None)

Extracts data for keys between t_start and t_end from timber.

Parameters:

• t_start -- starting time in UTC format
• t_end -- end time in UTC format
• keys -- list of data to extract
• names -- dict to map keys to column names

Returns: tfs pandas dataframe.

tune_analysis.timber_extract.get_fill_times(db, fill_number)

Returns start and end time of fill with fill number.

Parameters:

• db -- pytimber database
• fill_number -- fill number

Returns: tuple of start and end time

tune_analysis.timber_extract.get_tune_and_coupling_variables(db)

Returns the tune and coupling variable names. :param db: pytimber database

Returns: list of variable names

tune_analysis.timber_extract.lhc_fill_to_tfs(fill_number, keys=None, names=None)

Extracts data for keys of fill from timber.

Parameters:

• fill_number -- fill number
• keys -- list of data to extract
• names -- dict to map keys to column names

Returns: tfs pandas dataframe.