Interfaces and Integrations

Uhepp has been integrated into multiple frameworks or packages. This page maintains a list of third-party software that interfaces with uhepp.

Common Analysis Framework

The Common Analysis Framework, or CAF, is an event processing framework used within the ATLAS collaboration to study data produced at the LHC. CAF provides a custom uhepp-compatible plotter that generates JSON files instead of graphics formats and optionally uploads the plot to To use the plotter, add the following lines to your visualize configuration.

plotter: uhepp
plotFormats: json
# Collection id, e.g. 1
plotter.uhepp.collection: 1


The FreeForestML framework (formally nnfwtbn), is a python-based event processing framework with a focus on neural network training. The default plotting environment in FreeForestML is based on uhepp and exposes the internal objects with the return_uhepp=True flag. The following example is a modified version of this example to show how to push a histogram to a collection.

plot = hist(df, v_higgs_m, 20, [s_bkg, s_data], range=(0, 200), selection=None,
            weight="weight",  ratio_label="Data / SM", return_uhepp=True)
# plot is a uhepp histogram

The FreeForestML also has a dedicated example Notebook to illustrate the uhepp integration.


The helper method uhepp.from_coffea() takes a Coffea histogram as input and converts it into uhepp histogram objects.

import numpy as np
import coffea.hist as hist
import uhepp

chist = hist.Hist("Counts",
                  hist.Cat("sample", "sample name"),
                  hist.Bin("x", "x value", 20, -10, 10),
                  hist.Bin("y", "y value", 20, -10, 10),
                  hist.Bin("z", "z value", 20, -10, 10),

xyz = np.random.multivariate_normal(mean=[1, 3, 7], cov=np.eye(3), size=10000)
chist.fill(sample="sample 1", x=xyz[:,0], y=xyz[:,1], z=xyz[:,2])

(hx, hy, hz), samples = uhepp.from_coffea(chist)


Using plots stored on uhepp hub in a latex document involves the following steps: Downloading the plot, rendering the plot, adding the includegraphics command to the latex document. With the following snippet, you can automate this procedure and add plots directly using the plot’s uuid.

Add this snippet in the preamble of your document:

  \immediate\write18{mkdir -p .uhepp_cache}
  \immediate\write18{test -f .uhepp_cache/#2.json || uhepp pull #2 .uhepp_cache/#2.json}
  \immediate\write18{test -f .uhepp_cache/#2.pdf  || uhepp render .uhepp_cache/#2.json .uhepp_cache/#2.pdf}

Embed plots with:



The ATLAS software TRExFitter provides the configuration option UheppFormat which, if set to TRUE, will trigger the generation of pre- and post-fit plots in signal, control and validation regions in uhepp format. The output is a YAML file which can be managed by the Python package uhepp or the command-line tool uhepp. A common use pattern is to push generated files to

Consult the TRExFitter documentation for further information.