This is the high energy physics module for the OWLS analysis framework. This
module implements many of the features of the ROOT analysis framework using the
Pandas data analysis library. Instead of using
TTree objects, this library relies on the Pandas
and uses the Numexpr JIT
eval() functionality in Pandas to efficiently
evaluate kinematic and selection expressions. See the "Usage" section below for
The OWLS analysis framework supports Python 2.7, 3.3, 3.4, and 3.5.
Installation is most easily performed via pip:
pip install git+https://github.com/havoc-io/owls-hep.git
Alternatively, you may execute
setup.py manually, but this is not supported.
Although this module exposes functionality for low-level expression manipulation
and evaluation, it is more useful for its high-level
manipulation facilties, which expose object-oriented interfaces to automatically
load data and manipulate expressions efficiently.
Process class represents a physical process considered in an analysis. It
contains a list of ROOT data files containing the simulated or recorded events
for a process as well as metadata describing how to display the process in lists
Region class represents a potentially weighted event selection of event.
Processes can be "projected" into regions, and these projections can be used to
compute counts or histograms. Regions also contain metadata describing their
Calculation class represents a calculation to be made using a
process/region pair. This could be something like a count or a histogram, and
indeed implementations of both of these are provided by the library using the
owls-cache/owls-parallel modules for efficiency.
Calculation class is also subclassed by the
HigherOrderCalculation implementations are designed to wrap
Calculation classes and perform derivative calculations. They can be used for
things such as background estimation (using a multi-region extrapolation) or
uncertainty estimation (using varied systematics). Because fundamental
calculations such as counting and histogramming use the owls-cache and
owls-parallel module to batch and parallelize their operations, higher order
calculations can freely compute thousands and thousands of counts or histograms
or any other calculation without worrying about code structure/organization
while still reaping the benefits of caching, batching, and efficient data
Estimation class is provided as a base for background estimation
calculations, and provides useful, type-agnostic algebraic facilities for counts
and histograms. The
Uncertainty class provides a base for uncertainty
estimations, and facilities for plotting those uncertainties.
Facilities for N-dimensional plotting are also provided by the
Plot class, but
sadly this is really just a wrapper around ROOT's plotting. Ideally we'd switch
to something like matplotlib, but unfortunately ROOT is the only plotting engine
that provides some of the more obscure features needed for High Energy Physics
For more information on all of these classes and the various utility functions that accompany them, see the meticulously crafted Python docstrings. If you have access to the owls-hsg4 analysis code, you can see the full OWLS framework in action.