API Reference

Themes and Styling

PlottingToolsHEP.add_ATLAS_internal! — Function
add_ATLAS_internal!(ax, sec_text; offset=(250, -20), fontsize=20, energy=13.6)

Overlay the standard ATLAS label and centre-of-mass energy annotation onto axis ax. sec_text is the secondary descriptor placed after "ATLAS", e.g. "Internal" or "Simulation".

source

Plot Options

PlottingToolsHEP.HEPPlotOptions — Type
HEPPlotOptions(; kwargs...)

Common axis and labelling options shared across HEP plotting functions.

Fields

  • yscale: Y-axis scale function (default: identity)
  • xscale: X-axis scale function (default: identity)
  • xticks: X-axis tick specification (default: Makie.automatic)
  • yticks: Y-axis tick specification (default: Makie.automatic)
  • limits: Axis limits ((xmin, xmax), (ymin, ymax)), or (nothing, nothing) for automatic
  • ATLAS_label: Secondary text placed after "ATLAS" (e.g. "Internal"), or nothing to suppress
  • ATLAS_label_offset: Pixel offset of the ATLAS label from the top-left corner (default: (30, -20))
  • energy: Centre-of-mass energy in TeV shown in the ATLAS label (default: 13.6)

Example

opts = HEPPlotOptions(ATLAS_label="Internal", energy=14.0, limits=((-5, 5), (0, 200)))
plot_hist(h, "My Plot", "x [GeV]", "Events"; options=opts)
source

Plotting Functions

PlottingToolsHEP.plot_hist — Function
plot_hist(hist, title, xlabel, ylabel;
          label=nothing, normalize_hist=false,
          colticks=Makie.automatic, colorbar_label="",
          colorscale=identity, colorrange=Makie.automatic,
          options=HEPPlotOptions())

Plot a single Hist1D or Hist2D and return the Figure.

Hist2D entries are displayed as heatmaps with a colour bar; use colticks, colorbar_label, colorscale, and colorrange to control it. Common axis options (scale, ticks, limits, ATLAS label) are bundled in options.

source
PlottingToolsHEP.multi_plot — Function
multi_plot(hists, title, xlabel, ylabel, hist_labels;
           signal_hists=nothing, signal_labels=String[],
           data_hist=nothing, data_hist_style="scatter", data_label="Data",
           normalize_hists="", stack=false,
           lower_panel=:none, ratio_label="Data/MC",
           plot_errors=true, color=ATLAS_colors,
           legend_position=:inside,
           legend_align=(valign=0.95, halign=0.95),
           options=HEPPlotOptions())

Overlay multiple histograms on one axis and return the Figure.

  • normalize_hists: "" (none), "individual" (each normalized to 1), or "total" (all scaled to a common integral).
  • stack: if true, draw background histograms as a stacked histogram using stackedhist!.
  • signal_hists / signal_labels: optional second group drawn with dashed lines and individually normalised when normalize_hists="total". When provided, the legend is placed to the side unless legend_position=:inside.
  • data_hist: optional data histogram drawn on top in black.
  • lower_panel: controls the sub-panel drawn below the main axis:
    • :none – no sub-panel (default)
    • :ratio – Data/MC ratio panel (requires data_hist); label set by ratio_label
    • :s_sqrt_b – cumulative S/√B panel (requires signal_hists)
  • color: vector of colours matched to hist_labels (default: ATLAS_colors).
  • legend_position: :inside (default, overlaid on axis) or :side (fig[1,2]).
source
PlottingToolsHEP.plot_comparison — Function
plot_comparison(hist1, hist2, title, xlabel, ylabel,
                hist1_label, hist2_label, comp_label;
                normalize_hists=true, plot_as_data=[false, false],
                options=HEPPlotOptions())

Plot two histograms overlaid with a ratio panel below and return the Figure.

Set plot_as_data[i] = true to draw the i-th histogram as scatter points instead of a step histogram.

Note

This is a convenience wrapper around multi_plot. For more control (stacking, signal overlay, S/√B panel) use multi_plot directly.

source
PlottingToolsHEP.plot_signal_vs_background — Function
plot_signal_vs_background(signal_hists, bkg_hists, title, xlabel, ylabel,
                          signal_labels, bkg_labels;
                          normalize_hists="", stack=false,
                          plot_s_sqrt_b=true, color=ATLAS_colors,
                          options=HEPPlotOptions())

Plot signal and background histograms overlaid, optionally with a cumulative S/√B significance panel below, and return the Figure.

Note

This is a convenience wrapper around multi_plot. For more control use multi_plot directly with signal_hists, lower_panel=:s_sqrt_b, and legend_position=:side.

source

Event Display

PlottingToolsHEP.event_display — Function
event_display(jets, largeR_jets, leptons;
              η_range=-2.5:0.5:2.5, ϕ_range=-3.15:0.45:3.15,
              jet_R=0.4, largeR_jet_R=1.0,
              element_labels=["Electrons", "Large R Jets", "Jets"])

Draw a 2-D (η, ϕ) event display for jets, largeR_jets, and leptons.

Each object must support eta() and phi() from LorentzVectorHEP. Jets and large-R jets are drawn as circles of radius jet_R and largeR_jet_R respectively. Returns the Figure.

source