What is LiverpoolAnalysis?

LiverpoolAnalysis is a new series of packages developed for analysis within the athena framework. Used as a toolkit, LiverpoolAnalysis provides general-purpose C++ classes and python configuration files to allow analyses to be constructed at the job-options level, while still allowing the user to implement new code which can plug in between the existing tools. This page gives basic instructions to get the packages compiled and running. For more on the ideas behind LiverpoolAnalysis and its structure, please see this recent talk given at a joint W/Z meeting: LiverpoolAnalysisTalk.pdf

Where can I see the code?

The best way to understand any code is to have a look at it and its documentation. Almost all C++ classes in CVS have documentation, and this is presented in Doxygen format here:

Doxygen documentation

Initially, the most important part of any class is its interface with python. Or, in athena jargon, its "properties". These give the classes their flexibility, replacing coding in C++ with "gluing" algorithms and tools together in python. For example, say you want to dump electron and photon information at various stages. You might want to dump the AOD containers as they are, you might also want to dump some filtered collection (say, after some particle selection). You may also want to look at more complicated collections, ones which have been recalibrated or associated to jets. The DumpEgamma class can dump all of those, even within a single job. (It will of course not do the selection, recalibration or jet associations, but other LiverpoolAnalysis classes exist to do these.) Flexible configuration in the job options then gives you, the user, full control over the tree and branch structure of the output ntuple.

That is just an example. Much of the strength of LiverpoolAnalysis lies outside the plain dumping routines, in the tools and algorithms which make associations between different objects, including trigger objects, which only need to be dumped at an advanced stage of analysis to make the very final plots.

How is LiverpoolAnalysis structured?

There are now 4 core packages in LiverpoolAnalysis. This helps structure the classes and reduce internal dependencies:

• LivTools Generic tools, for particle selection, matching and so on.
• LivServices Services for cut flows, event weights, etc.
• LivAlgorithms These perform calculations, often using the tools in the LivTools package. They do things such as creating composite particles, associating particles, and acting as placeholder algorithms for the above tools.
• LivDumpers Designed to dump out useful information, either direct from an AOD container, or after application of the above tools and algorithms.

There are also other analysis-dependent packages which are intended to hold mainly job options, and relatively little C++ code. These packages are all called LivXAnalysis, where X is the channel, for example LivZAnalysis, LivH4lAnalysis and so on.

Checking out the packages

Setting up athena

First, you need to set up athena, if you haven't done this already. These are just very brief instructions for doing this using release 15 at Liverpool. For more detail (and instructions for CERN) please see this page. If you've already done this, skip this section. Note that releases 15.0.0 and 15.1.0 are incompatible when it comes to the tau classes. The current HEAD works in 15.0.0.

First you will need a requirements file, such as this one - copy this to your home directory and change the release on the first line. Then, execute the following commands from the same directory, changing the exact release number if required:

mkdir testarea
mkdir testarea/15.0.0.4
mkdir testarea/15.0.0.4/cmthome
mv requirements testarea/15.0.0.4/cmthome/
cd testarea/15.0.0.4/cmthome/
source /batchsoft/atlas/athena/15.0.0/CMT/v1r20p20081118/mgr/setup.sh
cmt config

Log out and back in again.

Getting and compiling the code

Setup athena as normal:

cd testarea/15.0.0.4/
source cmthome/setup.sh -tag=15.0.0.4
/usr/kerberos/bin/kinit flowerde@CERN.CH ## Change user name as appropriate

After that last line, you will need to give your CERN (lxplus) password. Next, you will need to find out which version of LiverpoolAnalysis to check out. Generally, the HEAD version is the most up to date, so we will check that out. Do this from your top level directory, ie ~/testarea/15.0.0.4/:

cvs co -r HEAD groups/Liverpool/LiverpoolAnalysis/LivTools
cvs co -r HEAD groups/Liverpool/LiverpoolAnalysis/LivServices
cvs co -r HEAD groups/Liverpool/LiverpoolAnalysis/LivAlgorithms
cvs co -r HEAD groups/Liverpool/LiverpoolAnalysis/LivDumpers
cvs co -r HEAD groups/Liverpool/LiverpoolAnalysis/LivZAnalysis  (or LivH4lAnalysis - you only need one or the other)
cvs update groups/Liverpool/LiverpoolAnalysis/ChangeLog

The last line is needed to get the "top-level" ChangeLog file, where changes should be logged before committing to CVS. Before compilation, you need to run one extra setup script, attached to this page here. Source it from the same directory as you checked the packages out from. Finally, you need to set all the packages up and compile. There are several ways to do this, one is to create yet another package called WorkArea, like so:

setupWorkArea.py
cd WorkArea/cmt
cmt bro cmt config
cmt bro source setup.sh
cmt bro gmake

Now go and make a cup of tea while that compiles. With this structure, all your day-to-day work (job options, ntuples etc) is done in WorkArea, which is nicely separated from the CVS code in your other packages. It may be good spending some time exploring the package structure you now have.

There are five example job options in LiverpoolAnalysis, split between Z/Graviton and Higgs examples. If you are new to athena, the simple Z boson example is the best to try first, as it has explanatory comments explaining what it does:

cd ~/testarea/15.2.0/WorkArea/
mkdir TestExample/ ## Call this whatever you want
cd TestExample/
athena LivZAnalysis/LivZBosonExample_topOptions.py

Once you have your output file (TestNtupleOutput.root), it's worth looking at it in conjunction with the job options file to understand it properly. I would also recommend reading and understanding the preselection file LivZBosonExample_preselection.py. To proceed further, it's convenient to make your own copy of the job options to edit:

cp ../../groups/Liverpool/LiverpoolAnalysis/LivZAnalysis/share/LivZBosonExample_topOptions.py .
### Edit the file
athena LivZBosonExample_topOptions.py

NOTE: If you try to run on a different AOD file, please check that the trigger sections will work first. For example, the trigger 'e20' is 'e20_loose' in more recent files. The checkTrigger.py script (comes with the release) can be run on your file to see which triggers are available in that dataset. If your file was made with version 13, this will seg fault - you need to check this page instead. Also note the comments in the example about running on files produced in v13.0.30 and for the FDR. If your dataset has no trigger running, the easiest (but not most efficient) way to turn the trigger analysis off is to replace

triggers = ['2e10','e12', .. etc ... ]

with

triggers = []

Running on the grid

Basic instructions on how to begin grid work can be found at ModernGanga5UsageAtLiverpool.

Running in version 14.4.0.X

Now that the main code has been updated to work with version 15, it will no longer work in version 14. The last version of the code compatible with this release has the CVS tag LiverpoolAnalysis-V14. To check this out, simply follow the instructions above, replacing HEAD with this tag, and of course replacing the version 15 release number throughout.

If you get errors complaining about: "tag: OFLCOND-SIM-00-00-06 does NOT exist" you need to tell athena to use a more up to date version of the conditions database (not sure what part of our code asks for a version that is more recent?). The solution is to set:

export DBRELEASE_OVERRIDE=6.3.1

and then redo the athena setup.

Running in version 14.5.0.X

None of the CVS-checked in versions will work in this release as-is. The problem arises because of changes that affect LivAlgorithms/MergeEgamma. Anyone wishing to use this release will for now need to perform the following steps:

• Follow the instructions as above for checking out for version 14.4.0.X.
• Then, copy the modified version of MergeEgamma from the HEAD. You'll only need the .h file here and the .cxx file here, no more.
• Compile and run as normal

Please note that this is sufficient to get LiverpoolAnalysis to compile. If anyone actually wishes to use MergeEgamma, some further changes are necessary. Please contact Mike for details of how to do this.

-- MikeFlowerdew - 07 Aug 2008