gatohep.plotting_utils#

gatohep.plotting_utils.assign_bins_and_order(model, data, reduce=False, eps=1e-06)#

Assign events to bins and compute bin significance.

Parameters:

  • model (tf.Module) – Trained model with Gaussian components.

  • data (dict) – Dictionary of input data with process names as keys.

  • reduce (bool, optional) – If True, reduce dimensionality. Default is False.

  • eps (float, optional) – Small value to avoid division by zero. Default is 1e-6.

Returns:

A tuple containing bin assignments, bin order, significances, and inverse mapping.

Return type:

tuple

gatohep.plotting_utils.fill_histogram_from_assignments(assignments, weights, nbins, name='BinAssignments')#

Fill a histogram from event assignments and weights.

Parameters:

  • assignments (array_like) – Array of bin assignments for each event.

  • weights (array_like) – Array of weights for each event.

  • nbins (int) – Number of bins in the histogram.

  • name (str, optional) – Name of the histogram axis. Default is “BinAssignments”.

Returns:

A histogram object.

Return type:

hist.Hist

gatohep.plotting_utils.get_distinct_colors(n)#

Generate a list of n distinct RGB colors.

Parameters:

n (int) – Number of distinct colors to generate.

Returns:

List of RGB color tuples.

Return type:

list of tuple

gatohep.plotting_utils.make_gif(frame_files, out_name, interval=800)#

Assemble a set of pre-rendered PNGs into an animated GIF without extra margins.

Parameters:

  • frame_files (Sequence[str]) – Ordered list of frame file paths.

  • out_name (str) – Destination GIF path.

  • interval (int, optional) – Frame duration in milliseconds. Default is 800 ms.

gatohep.plotting_utils.plot_bias_history(mean_bias_list, output_filename, *, epochs=None, temp_points=None, temp_label='Temperature', log_scale=False)#

Plot mean soft-hard bias with optional secondary axis for temperature/steepness.

gatohep.plotting_utils.plot_bin_boundaries_2D(model, bin_order, path_plot, *, resolution=1000, annotation=None)#

Plot hard-bin regions of a 2-D GMM on the 2-simplex face (x >= 0, y >= 0, x + y ≤ 1).

Parameters:

  • model (gato_gmm_model (must have dim == 2))

  • bin_order (list[int]) – Desired plotting order of the components.

  • path_plot (str) – Destination file (PDF, PNG, …).

  • resolution (int, optional) – Grid resolution per axis. Default 500.

  • reduce (bool, optional) – Ignored (for backward compatibility with older callers).

  • annotation (str, optional) – Text rendered in the upper-left corner of the axes (useful for tagging epochs in GIF frames). Default is None.

gatohep.plotting_utils.plot_category_mass_spectra(per_cat_hists, out_dir, *, sig_scales=(50, 200))#

Show per-category diphoton-mass spectra after categorisation.

Parameters:

  • per_cat_hists (Sequence[Mapping[str, hist.Hist]]) – Output of build_category_mass_maps().

  • out_dir (str) – Directory in which per-category plots are stored.

  • sig_scales (tuple[float, float], optional) – Multiplicative factors applied to signal1 and signal2.

gatohep.plotting_utils.plot_gmm_1d(model, output_filename, x_range=(0.0, 1.0), n_points=10000)#

Plot each weighted component of a 1D GMM.

Parameters:

  • model (gato_gmm_model (dim == 1))

  • output_filename (str)

  • x_range (tuple(float, float))

  • n_points (int)

gatohep.plotting_utils.plot_history(history_data, output_filename, y_label='Value', x_label='Epoch', boundaries=False, boundary_labels=None, title=None, log_scale=False)#

Plot the training history of a model.

Parameters:

  • history_data (list or ndarray) – History data to plot.

  • output_filename (str) – File name to save the plot.

  • y_label (str, optional) – Label for the y-axis. Default is “Value”.

  • x_label (str, optional) – Label for the x-axis. Default is “Epoch”.

  • boundaries (bool, optional) – If True, plot boundaries instead of scalar values. Default is False.

  • title (str, optional) – Title of the plot. Default is None.

  • log_scale (bool, optional) – If True, use a logarithmic scale for the y-axis. Default is False.

Return type:

None

gatohep.plotting_utils.plot_inclusive_mass(data, out_dir, *, sig_scales=(50, 200), bins=60, mass_range=(100.0, 180.0))#

Plot the inclusive diphoton-mass spectrum before categorisation.

Parameters:

  • data (Mapping[str, pandas.DataFrame]) – Event tables containing "mass" and "weight" columns.

  • out_dir (str) – Destination directory for the produced PDF files.

  • sig_scales (tuple[float, float], optional) – Multiplicative factors applied to the two signal histograms.

  • bins (int, optional) – Number of uniform histogram bins.

  • mass_range (tuple[float, float], optional) – Mass range in GeV for the inclusive plots.

gatohep.plotting_utils.plot_learned_gaussians(data, model, dim_x, dim_y, output_filename, conf_level=2.3, inv_mapping=None, reduce=False)#

Visualise the learned Gaussian components (2-D projection) together with a scatter of real data points.

Parameters:

  • data (dict) – {process: DataFrame} - each DataFrame must contain a column "NN_output" with arrays of shape (dim,).

  • model (gato_gmm_model) – Trained multi-D GMM.

  • dim_x (int) – Component of the NN output plotted on x / y axis.

  • dim_y (int) – Component of the NN output plotted on x / y axis.

  • output_filename (str) – Path where the figure is saved.

  • conf_level (float, optional) – Chi-square value that defines the ellipse (2.30 -> 1 sigma).

  • inv_mapping (dict, optional) – Map new bin index → original component index. If None, identity mapping is used.

  • reduce (bool, optional) – If True, map raw mean logits through softmax per component before projecting. (Keeps prior behaviour.)

gatohep.plotting_utils.plot_significance_comparison(baseline_results, optimized_results, output_filename, fig_size=(8, 6))#

Plot baseline vs. optimized significance for multiple signals.

Parameters:

  • baseline_results (dict) – Dictionary mapping signal names to baseline significance results.

  • optimized_results (dict) – Dictionary mapping signal names to optimized significance results.

  • output_filename (str) – File name to save the plot.

  • fig_size (tuple, optional) – Size of the figure. Default is (8, 6).

Return type:

None

gatohep.plotting_utils.plot_stacked_histograms(stacked_hists, process_labels, output_filename='./plot.pdf', axis_labels=('x-axis', 'Events'), signal_hists=None, signal_labels=None, normalize=False, log=False, log_min=None, return_figure=False, ax=None)#

Plot stacked histograms for backgrounds and overlay signal histograms.

Parameters:

  • stacked_hists (list of hist.Hist) – List of histograms for background processes.

  • process_labels (list of str) – List of labels for background processes.

  • output_filename (str, optional) – File name to save the figure. Default is “./plot.pdf”.

  • axis_labels (tuple of str, optional) – Labels for the x-axis and y-axis. Default is (“x-axis”, “Events”).

  • signal_hists (list of hist.Hist, optional) – List of histograms for signal processes. Default is None.

  • signal_labels (list of str, optional) – List of labels for signal histograms. Default is None.

  • normalize (bool, optional) – If True, normalize the histograms. Default is False.

  • log (bool, optional) – If True, use a logarithmic scale for the y-axis. Default is False.

  • log_min (float, optional) – Minimum value for the y-axis in log scale. Default is None.

  • return_figure (bool, optional) – If True, return the figure and axis instead of saving. Default is False.

  • ax (matplotlib.axes.Axes, optional) – Axis to plot on. Default is None.

Returns:

If return_figure is True, returns (fig, ax). Otherwise, saves the plot.

Return type:

None or tuple

gatohep.plotting_utils.plot_yield_vs_uncertainty(B_sorted, rel_unc_sorted, output_filename, log=False, x_label='Bin index', y_label_left='Background yield', y_label_right='Rel. stat. unc.', fig_size=(8, 6), bar_kwargs_left=None, bar_kwargs_right=None)#

Plot background yield and relative uncertainty as dual-axis bar plots.

Parameters:

  • B_sorted (array_like) – Sorted background yields.

  • rel_unc_sorted (array_like) – Sorted relative uncertainties.

  • output_filename (str) – File name to save the plot.

  • log (bool, optional) – If True, use a logarithmic scale for the y-axis. Default is False.

  • x_label (str, optional) – Label for the x-axis. Default is “Bin index”.

  • y_label_left (str, optional) – Label for the left y-axis. Default is “Background yield”.

  • y_label_right (str, optional) – Label for the right y-axis. Default is “Rel. stat. unc.”.

  • fig_size (tuple, optional) – Size of the figure. Default is (8, 6).

  • bar_kwargs_left (dict, optional) – Additional arguments for the left bar plot. Default is None.

  • bar_kwargs_right (dict, optional) – Additional arguments for the right bar plot. Default is None.

Return type:

None