Skip to content
Read LHCO files into a Python class
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.




:mod:`LHCO_reader` is a Python module for reading LHCO files from detector simulators such as PGS into a Python class, with useful functions for implementing an analysis. It can also read ROOT files from Delphes, by immediately converting them to LHCO files. :mod:`LHCO_reader` can calculate \alpha_T and razor variables, and M_{T2} and M_{T2}^W variables are included by linking :mod:`LHCO_reader` with external libraries.

For the full documentation, read the online docs. For a tutorial and further background information, see the manual at arXiv:1510.07319.

Submit any bugs or issues at the git-hub issues page.


If you use :mod:`LHCO_reader`, please cite arXiv:1510.07319:

    author         = "Fowlie, Andrew",
    title          = "{LHCO_reader: A new code for reading and analyzing
                    detector-level events stored in LHCO format}",
    year           = "2015",
    eprint         = "1510.07319",
    archivePrefix  = "arXiv",
    primaryClass   = "hep-ph",
    reportNumber   = "COEPP-MN-15-10",
    SLACcitation   = "%%CITATION = ARXIV:1510.07319;%%"


The module does not require complicated installation. Simply:

pip install LHCO_reader

or clone the module for the very-latest version:

git clone

or download it via a web browser.


To load the module :mod:`LHCO_reader` and look at an LHCO file, simply:

from LHCO_reader import LHCO_reader
events = LHCO_reader.Events(f_name="example.lhco")
print events

The :class:`Events` object in the above code is a list-like object. Cuts can be implemented with lambda-functions, e.g. to cut events with one tau-lepton:

tau = lambda event: event.number()["tau"] == 1

To test the module:

python -v

The module requires some common modules that you might need to install separately, the most obscure of which is :mod:`prettytable`, see here for installation.

Structure of events

The code is object-oriented. A LHCO file is parsed into several objects. The :class:`Events` object is structured as follows:

for event in events:
  ... scrutinize an event ...

but beware that altering list-type objects in a loop can be problematic. The best way to cut :class:`Events` is with the :func:`Events.cut` function.

There are many useful functions, including printing in LHCO format (:func:`LHCO`), plotting (:func:`plot`), sorting (:func:`order`) and cutting events (:func:`cut`), manipulating four-momenta with boosts (:func:`vector`), counting the numbers of types of object in an event (:func:`number`), angular separation (:func:`delta_R`), that should make implementing an analysis easy.

Dictionary keys

The :class:`Event` dictionary's keys are

  • electron
  • muon
  • tau
  • jet
  • MET (missing transverse energy)
  • photon

The :class:`Object` dictionary's keys from the LHCO file are

  • event
  • type
  • eta
  • phi
  • PT
  • jmass
  • ntrk
  • btag
  • hadem

event and type are integers, and other properties are floats.

We add various additional properties, including a function :func:`vector()`, which returns a four-momentum object.

Kinematic variables

Complicated kinematic variables could be included from the Oxbridge kinetics library.

>>> object_1 = events[0]["jet"][0]
>>> object_2 = events[0]["jet"][1]
>>> MET = events[0]["MET"][0]
>>> from oxbridge_kinetics import MT2
>>> MT2(object_1, object_2, MET)


ROOT files can be converted into LHCO files with :mod:`root2lhco` in Delphes, which can be linked with and called from within :mod:`LHCO_reader` via :mod:`LHCO_converter`, i.e. you can load a ROOT file, which will be immediately converted into an LHCO file and parsed. If you wish to use ROOT files:

You can’t perform that action at this time.