Functions documentation

Plots and analysis tools for SIMUnet.

validphys.simunet_analysis.bsm_facs_68bounds_fits(fits, bsm_names_to_latex)

Generate a table summarizing the 68% confidence level (CL) bounds for BSM factors from various fits.

This function processes a list of fits and utilizes bsm_facs_bounds_fits to calculate and return the 68% CL bounds for BSM coefficients.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• bsm_names_to_latex (dict) – A dictionary mapping BSM factor names to their LaTeX representations.

Returns

A pandas DataFrame containing the 68% CL bounds for each BSM factor in each fit.

Return type

pd.DataFrame

validphys.simunet_analysis.bsm_facs_95bounds_fits(fits, bsm_names_to_latex)

Generate a table summarizing the 95% confidence level (CL) bounds for BSM factors from various fits.

This function processes a list of fits and utilizes bsm_facs_bounds_fits to calculate and return the 95% CL bounds for BSM coefficients.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• bsm_names_to_latex (dict) – A dictionary mapping BSM factor names to their LaTeX representations.

Returns

A pandas DataFrame containing the 95% CL bounds for each BSM factor in each fit.

Return type

pd.DataFrame

validphys.simunet_analysis.bsm_facs_bounds(read_bsm_facs, bsm_names_to_latex)

Table generator to summarise information about the BSM coefficient results.

Parameters

• read_bsm_facs (pd.DataFrame) – DataFrame containing BSM factors.

• bsm_names_to_latex (dict) – Dictionary mapping BSM names to LaTeX representations.

Returns

DataFrame summarizing the bounds and statistics of BSM coefficients.

Return type

pd.DataFrame

validphys.simunet_analysis.bsm_facs_bounds_fits(fits, bsm_names_to_latex, n_sigma=2)

Generate a table summarizing the bounds of BSM coefficients in different fits.

This function processes a list of fits, extracting the BSM coefficients and summarizing their mean, standard deviation, and confidence levels. The confidence levels are computed as mean ± n_sigma * std.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• bsm_names_to_latex (dict) – A dictionary mapping BSM factor names to their LaTeX representations.

• n_sigma (int, optional) – The multiplier for the standard deviation to define confidence level bounds, by default 2.

Returns

A pandas DataFrame containing the bounds for each BSM factor in each fit, along with additional metrics like ‘Best-fit shift’ and ‘Broadening’.

Return type

pd.DataFrame

validphys.simunet_analysis.dataset_inputs_scaled_fit_cfactor(data, pdf, read_pdf_cfactors, quad_cfacs)

Same as validphys.results.dataset_scaled_fit_cfactor() but for a list of dataset inputs.

validphys.simunet_analysis.dataset_scaled_fit_cfactor(dataset, pdf, read_pdf_cfactors, quad_cfacs)

For each replica of pdf, scale the fit cfactors by the best fit value. :returns: res – An ndat x nrep array containing the scaled fit cfactors. :rtype: np.arrays

validphys.simunet_analysis.display_format(series)

Determines the format of the BSM factors to be displayed in the tables.

Parameters

series (pd.Series) – Series containing the BSM factors.

Returns

A list of formatted numbers representing the BSM factors.

Return type

list

validphys.simunet_analysis.fisher_information_by_sector(dataset_inputs, theoryid, groups_covmat, simu_parameters_names, pdf)

Obtains the Fisher information matrices for each of the BSM sectors.

This function computes the Fisher information matrix for each sector in a dataset, providing a measure of the amount of information each sector contributes to the parameters. The function accumulates datasets by sectors, calculates the reduced covariance matrices for each sector, and computes the Fisher information matrices. The diagonal elements of these matrices are extracted and normalized to provide a comparative view across sectors.

Parameters

• dataset_inputs (list of Dataset objects) – The datasets used for computing the Fisher information matrices.

• theoryid (int or array-like) – Theory identifier(s) associated with the datasets.

• groups_covmat (pd.DataFrame) – Covariance matrices for the groups in the datasets.

• simu_parameters_names (list of str) – List of names of the simulation parameters.

• pdf (PDF object) – The parton distribution function object.

Returns

A DataFrame with the normalized diagonal elements of the Fisher information matrices, indexed by simulation parameters and with sectors as columns.

Return type

pd.DataFrame

validphys.simunet_analysis.fisher_information_matrix(dataset_inputs, groups_index, theoryid, groups_covmat, simu_parameters_names, pdf)

Obtains the full Fisher information matrix for the BSM parameters.

This function computes the Fisher information matrix for Beyond the Standard Model (BSM) parameters given a dataset. It utilizes an internal function _compute_fisher_information_matrix to perform the computation.

Parameters

• dataset_inputs (array-like) – The inputs from the dataset used for computing the Fisher information matrix.

• groups_index (array-like) – Indexes representing different groups in the dataset.

• theoryid (array-like) – Array of theory identifiers.

• groups_covmat (array-like) – Covariance matrices for the groups in the dataset.

• simu_parameters_names (list) – List of names of the simulation parameters.

• pdf (PDF object) – The parton distribution function object.

Returns

The computed Fisher information matrix.

Return type

array-like

validphys.simunet_analysis.format_residuals(residuals)

Formats residuals for display, splitting them into intervals.

Parameters

residuals (list of float) – List of residual values (mean/std) for BSM factors.

Returns

List of intervals for display of residuals.

Return type

list of list

validphys.simunet_analysis.l = <validphys.loader.Loader object>

validphys.simunet_analysis.plot_2d_bsm_facs(read_bsm_facs, replica_data)

Plot two-dimensional distributions of the BSM coefficient results.

Parameters

• read_bsm_facs (pd.DataFrame) – DataFrame containing the BSM factors.

• replica_data (list) – List of FitInfo.

Returns

fig – A matplotlib figure object for the 2D distribution plot.

Return type

matplotlib.figure.Figure

validphys.simunet_analysis.plot_2d_bsm_facs_fits(fits, bsm_names_to_latex)

Generate 2D scatter plots and histograms comparing BSM factor values across different fits.

This function takes a set of fits and compares the BSM factors between them. For each pair of BSM factors, it creates a 2D scatter plot with corresponding histograms on the x and y axes.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• bsm_names_to_latex (dict) – Dictionary mapping BSM factor names to their LaTeX string representations.

Yields

fig (matplotlib.figure.Figure) – The matplotlib figure object for each pair of BSM factors.

validphys.simunet_analysis.plot_2d_bsm_facs_pair(read_bsm_facs, replica_data, bsm_names_to_latex, op1, op2)

Auxiliary function to plot 2D plots of a pair of operators in a N-dimensional fits with BSM factors.

Parameters

• read_bsm_facs (pd.DataFrame) – DataFrame containing BSM factors.

• replica_data (list) – List of FitInfo.

• bsm_names_to_latex (dict) – Dictionary mapping BSM names to LaTeX representations.

• op1 (str) – The first operator name.

• op2 (str) – The second operator name.

Returns

The figure object containing the 2D plot.

Return type

matplotlib.figure.Figure

validphys.simunet_analysis.plot_bsm_2d_combs(read_bsm_facs, replica_data, bsm_names_to_latex)

Plot two-dimensional distributions for all pairs of BSM coefficients in a fit.

Parameters

• read_bsm_facs (pd.DataFrame) – DataFrame containing BSM factors.

• replica_data (list) – List of FitInfo.

• bsm_names_to_latex (dict) – Dictionary mapping BSM names to LaTeX representations.

Yields

fig (matplotlib.figure.Figure) – A matplotlib figure object for each pair of BSM coefficient combination.

validphys.simunet_analysis.plot_bsm_corr(fit, read_bsm_facs, bsm_names_to_latex, corr_threshold=0.5)

Plot a correlation matrix to summarise information about the BSM coefficient results.

Parameters

• fit (FitSpec) – Object containing the specifications of the fit.

• read_bsm_facs (pd.DataFrame) – DataFrame containing BSM factors.

• bsm_names_to_latex (dict) – Dictionary mapping BSM names to LaTeX representations.

• corr_threshold (float, optional) – Threshold for coloration in the correlation matrix.

Returns

The figure object containing the correlation matrix plot.

Return type

matplotlib.figure.Figure

validphys.simunet_analysis.plot_bsm_facs_68res(fits, bsm_names_to_latex)

Generates plots of the 68% residuals of BSM coefficients for various fits.

This function processes a set of fits and generates plots showing the 68% residuals of the BSM (Beyond the Standard Model) coefficients. The residuals are calculated as the mean of the coefficients divided by their standard deviation, providing a measure of deviation from the Standard Model.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• bsm_names_to_latex (dict) – Dictionary mapping BSM factor names to their LaTeX representations.

Yields

fig (matplotlib.figure.Figure) – The matplotlib figure object for the residual plot.

validphys.simunet_analysis.plot_bsm_facs_bounds(fits, bsm_names_to_latex, bsm_names_to_plot_scales)

Generates plots of the bounds for BSM coefficients from various fits.

This function takes a list of fits and generates plots showing the mean, standard deviation, and confidence levels of the BSM coefficients. The confidence levels are calculated as mean ± 2*std. It supports both linear and symmetric logarithmic scales for the plots.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• bsm_names_to_latex (dict) – Dictionary mapping BSM factor names to their LaTeX representations.

• bsm_names_to_plot_scales (dict) – Dictionary to scale the BSM names for plotting.

Yields

fig (matplotlib.figure.Figure) – The matplotlib figure object for each generated plot.

validphys.simunet_analysis.plot_bsm_pdf_corr(pdf, read_bsm_facs, xplotting_grid, Q, bsm_names_to_latex, mark_threshold: float = 0.9, ymin: (<class 'float'>, <class 'NoneType'>) = None, ymax: (<class 'float'>, <class 'NoneType'>) = None, dashed_line_flavours: (<class 'list'>, <class 'NoneType'>) = None)

Plot the correlation between BSM factors and a PDF.

Parameters

• pdf (PDF object) – The parton distribution function being analyzed.

• read_bsm_facs (DataFrame or callable) – Data or function representing BSM factors.

• xplotting_grid (XGrid object) – Object containing the plotting grid information.

• Q (float) – Momentum transfer value in GeV.

• bsm_names_to_latex (dict) – Mapping of BSM factor names to their LaTeX representations.

• mark_threshold (float, optional) – Threshold for marking significant correlations, by default 0.9.

• ymin (float or None, optional) – Minimum y-axis value, by default None.

• ymax (float or None, optional) – Maximum y-axis value, by default None.

• dashed_line_flavours (list of str or None, optional) – List of flavours to be plotted with dashed lines, by default None.

Yields

• fig (matplotlib.figure.Figure) – The matplotlib figure object for the plot.

• bsm_fac (str) – Name of the BSM factor being plotted.

validphys.simunet_analysis.plot_bsm_pdf_corr_fits(fits, pdfs, xplotting_grids, Q, bsm_names_to_latex)

Plot correlations between BSM factors and multiple PDFs.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• pdfs (list of PDF objects) – List of parton distribution functions corresponding to the fits.

• xplotting_grids (list of XGrid objects) – List of plotting grid objects corresponding to each fit.

• Q (float) – Momentum transfer value in GeV.

• bsm_names_to_latex (dict) – Mapping of BSM factor names to their LaTeX representations.

Yields

fig (matplotlib.figure.Figure) – The matplotlib figure object for the plot.

validphys.simunet_analysis.plot_chi2_bsm_facs(read_bsm_facs, replica_data)

Generates bsm_fac value - chi2 scatter plots for all replicas in a fit.

Parameters

• read_bsm_facs (pd.DataFrame) – DataFrame containing BSM factors.

• replica_data (list) – List of FitInfo.

Returns

fig – A matplotlib figure object for the chi2 scatter plot.

Return type

matplotlib.figure.Figure

validphys.simunet_analysis.plot_fisher_information_by_sector(fisher_information_by_sector, bsm_names_to_latex, bsm_sectors_to_latex)

Produces a heatmap plot from the Fisher information by sector table.

This function creates a heatmap visualizing the Fisher information matrix, where rows correspond to BSM coefficients and columns correspond to different sectors. This visualization helps in understanding the impact of various sectors on the coefficients.

Parameters

• fisher_information_by_sector (pandas.DataFrame) – The Fisher information matrix with sectors as columns and BSM coefficients as rows.

• bsm_names_to_latex (dict) – Dictionary mapping BSM factor names to their LaTeX representations.

• bsm_sectors_to_latex (dict) – Dictionary mapping sector names to their LaTeX representations.

Returns

The figure object containing the heatmap plot of the Fisher information.

Return type

matplotlib.figure.Figure

validphys.simunet_analysis.plot_kde_bsm_facs(read_bsm_facs, bsm_names_to_latex)

Plots the kernel estimation density for a distribution of BSM coefficients.

Parameters

• read_bsm_facs (pd.DataFrame) – DataFrame containing the BSM factors.

• bsm_names_to_latex (dict) – Dictionary mapping BSM names to LaTeX representations.

Yields

fig (matplotlib.figure.Figure) – A matplotlib figure object for the KDE plot.

validphys.simunet_analysis.plot_nd_bsm_facs(read_bsm_facs, bsm_names_to_latex, posterior_plots_settings=None)

Plot a histogram for each BSM coefficient. The nd is used for n-dimensional, if two BSM facs are present: use instead validphys.results.plot_2d_bsm_facs()

Parameters

• read_bsm_facs (pd.DataFrame) – DataFrame containing the BSM factors.

• bsm_names_to_latex (dict) – Dictionary mapping BSM names to LaTeX representations.

• posterior_plots_settings (dict, optional) – Settings for posterior plots, such as number of bins and range settings.

Yields

fig (matplotlib.figure.Figure) – A matplotlib figure object for the histogram.

validphys.simunet_analysis.plot_nd_bsm_facs_fits(fits, bsm_names_to_latex, posterior_plots_settings=None)

Compare histograms of BSM factors between different fits in SIMUnet.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• bsm_names_to_latex (dict) – Dictionary mapping BSM names to their LaTeX representations.

• posterior_plots_settings (dict, optional) – Dictionary containing settings for posterior plots such as ‘n_bins’, ‘rangex’, ‘rangey’, and ‘same_bins’.

Yields

fig (matplotlib.figure.Figure) – A matplotlib figure object for each BSM coefficient comparison.

validphys.simunet_analysis.plot_smefit_comparison(fits, bsm_names_to_latex, smefit_reference, bsm_names_to_plot_scales, smefit_label)

Generates plots comparing bounds obtained from SIMUnet fits with those obtained by SMEFiT.

This function takes a set of SIMUnet fits and a SMEFiT reference, extracting BSM coefficients from each. It plots the mean and standard deviation of the BSM coefficients for each fit, along with confidence levels calculated as mean ± 2*std. It supports both linear and symmetric logarithmic scales for the plots.

Parameters

• fits (NSList) – List of FitSpec to be compared.

• bsm_names_to_latex (dict) – Dictionary mapping BSM factor names to their LaTeX representations.

• smefit_reference (list of dicts) – List of dictionaries containing BSM coefficient information from a SMEFiT reference.

• bsm_names_to_plot_scales (dict) – Dictionary to scale the BSM names for plotting.

• smefit_label (str) – Label for the SMEFiT reference to be used in the plot.

Yields

fig (matplotlib.figure.Figure) – The matplotlib figure object for the comparison plot.

validphys.simunet_analysis.plot_smefit_internal_comparison(bsm_names_to_latex, smefit_reference_1, smefit_reference_2, bsm_names_to_plot_scales, smefit_labels)

Generates comparison plots between SMEFiT fits.

This function creates plots to compare two different SMEFiT fits. It plots the best fit values and the bounds for BSM (Beyond the Standard Model) coefficients, allowing for an easy comparison of the two fits. It supports both linear and symmetric logarithmic scales.

Parameters

• bsm_names_to_latex (dict) – Dictionary mapping BSM factor names to their LaTeX representations.

• smefit_reference_1 (list of dicts) – List of dictionaries containing BSM coefficient information for the first SMEFiT reference.

• smefit_reference_2 (list of dicts) – List of dictionaries containing BSM coefficient information for the second SMEFiT reference.

• bsm_names_to_plot_scales (dict) – Dictionary to scale the BSM names for plotting.

• smefit_labels (list of str) – Labels for the SMEFiT references to be used in the plot.

Yields

fig (matplotlib.figure.Figure) – The matplotlib figure object for the comparison plot.

validphys.simunet_analysis.plot_tr_val_epoch(fit, replica_paths)

Plot the average across replicas of training and validation chi2 for a given epoch.

Parameters

• fit (FitSpec) – Object containing the specifications of the fit.

• replica_paths (list) – List of paths to the replica data.

Yields

fig (matplotlib.figure.Figure) – The figure object containing the plot.

validphys.simunet_analysis.principal_component_values(fisher_information_matrix)

Returns the eigenvalues corresponding to the various principal directions.

This function performs a principal component analysis (PCA) on the Fisher information matrix to return the eigenvalues. These eigenvalues represent the variance of the data along the principal components, which can be used to understand the dominant directions in the data.

Parameters

fisher_information_matrix (pd.DataFrame) – The Fisher information matrix.

Returns

A DataFrame containing the eigenvalues of the Fisher information matrix.

Return type

pd.DataFrame

validphys.simunet_analysis.principal_component_vectors(fisher_information_matrix, simu_parameters_names)

Performs a principal component analysis to obtain the principal directions (vectors).

This function calculates the principal component vectors from the Fisher information matrix, providing insights into the flat directions of the parameter space. These directions can indicate combinations of parameters that are less constrained by the data.

Parameters

• fisher_information_matrix (pd.DataFrame) – The Fisher information matrix.

• simu_parameters_names (list of str) – Names of the simulation parameters.

Returns

A DataFrame containing the principal component vectors, indexed by the simulation parameters.

Return type

pd.DataFrame

validphys.simunet_analysis.reorder_cols(cols)

Reorders columns based on predefined BSM factor display order.

Parameters

cols (list) – List of column names to be reordered.

Returns

Reordered list of columns.

Return type

list

validphys.simunet_analysis.tabulate_bsm_corr(fit, read_bsm_facs)

Generate a correlation table for BSM coefficients similar to the corresponding plot.

Parameters

• fit (FitSpec) – Object containing the specifications of the fit.

• read_bsm_facs (pd.DataFrame) – DataFrame containing BSM factors.

Returns

The correlation matrix as a DataFrame.

Return type

pd.DataFrame

validphys.simunet_analysis.truncate_colormap(cmap, minval=0.0, maxval=1.0, n=100)

Truncates a colormap to a specific range.

This function creates a new colormap based on a given colormap but truncated to the range specified by minval and maxval. This is useful for adjusting the range of colors used in a plot.

Parameters

• cmap (matplotlib.colors.Colormap) – The original colormap to be truncated.

• minval (float, optional) – The minimum value of the new colormap, by default 0.0.

• maxval (float, optional) – The maximum value of the new colormap, by default 1.0.

• n (int, optional) – The number of discrete colors in the new colormap, by default 100.

Returns

The truncated colormap.

Return type

matplotlib.colors.LinearSegmentedColormap