HZZ4lD3PDAnalysis Code

Useful links:

• Trac: https://svnweb.cern.ch/trac/atlasinst/browser/Institutes/Edinburgh/HZZ4lD3PDAnalysis/trunk

0. Environment Setup

The main HZZ4lD3PDAnalysis code just needs a recent version of ROOT set up in order to compile and run. However the HSG2 provided ZMassConstraint package relies on CLHEP, so your environment setup requires a version of the CLHEP libraries compatable with the version of gcc being used. Here is an example setup that works ok on the Edinburgh SLC6 machines.

export ATLAS_LOCAL_ROOT_BASE=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase
alias setupATLAS='source ${ATLAS_LOCAL_ROOT_BASE}/user/atlasLocalSetup.sh'
setupATLAS
localSetupGLite
localSetupROOT --quiet
localSetupGcc --gccVersion gcc462_x86_64_slc6

In order to use the ZMassConstraint package you must set the ROOTCORECLHEP environment variable to point to a CLHEP install before compiling the packages. If you do not want to use the ZMassContraint package you can skip this step. On Edinburgh PPE, you can use the CLHEP install in ~nedward2/sw

export ROOTCORECLHEP=~nedward2/sw

or alternatively you can use the afs install:

export ROOTCORECLHEP=/afs/cern.ch/sw/lcg/external/clhep/2.1.3.1/x86_64-slc6-gcc46-opt

1. Installation

First checkout RootCore, the ATLAS standalone package management system.

mkdir Packages
cd Packages
export PACKAGE_DIR=${PWD}
svn co svn+ssh://svn.cern.ch/reps/atlasoff/PhysicsAnalysis/D3PDTools/RootCore/tags/RootCore-00-01-59 RootCore
cd RootCore
./configure
source scripts/setup.sh

Every time you start a new terminal you need to do the following (in addition to setting up the environment as described above).

export PACKAGE_DIR=${HOME}/Packages
source $PACKAGE/RootCore/scripts/setup.sh

Now you need to check out a bunch of packages. These are all from the ATLAS SVN repositories. It helps if you can get a kerberos token first so that you don't have to type your password multiple times (e.g. "kinit user@CERN.CH"). Download the file packages.txt, then do

cd $PACKAGE_DIR
RootCore/scripts/checkout.sh packages.txt
RootCore/scripts/find_packages.sh
RootCore/scripts/compile.sh

If you have not set up CLHEP and do not wish to use the ZMassConstraint package you can comment out the lines:

atlasphys/Physics/Higgs/HSG2/Code/ZMassConstraint/tags/ZMassConstraint-00-00-19 ZMassConstraint
atlasoff/PhysicsAnalysis/D3PDTools/RootCoreCLHEP/tags/RootCoreCLHEP-00-00-07

from packages.txt so as not to check out and compile those packages.

2. The HZZ4lD3PDAnalysis package - running the code.

The HZZ4lD3PDAnalysis package is in the directory ${PACKAGE_DIR}/HZZ4lD3PDAnalysis (duh!). An example executable is in bin/test_run. The corresponding source code is in util/test_run.cxx. You may need to modify this to point a d3pd file visible to you, although if running on Edinburgh ph-ppe it should run as is. It is reccomended to cretae a new directory for running in:

cd ${PACKAGE_DIR}/HZZ4lD3PDAnalysis/
mkdir run
cd run/
../bin/test_run

This will run over 10k events in a H125 sample. It should be quite fast! The interesting output can then be found in: test_run/data-HZZ4l/sample.root (the other files created are mainly for book keepin).

Recompiling

If you need to recompile, you can do:

$ROOTCOREDIR/scripts/compile.sh

although this is quite slow because it checks all of your packages to see if they need recompiling. A faster option is to do:

cd ${PACKAGE_DIR}/HZZ4lD3PDAnalysis/cmt
make -f Makefile.RootCore

which only recompiles the HZZ4lD3PDAnalysis package. The script

${PACKAGE_DIR}/make.sh

will do the same thing.

Running with corrections

In the above test_run example, no corrections or weights are applied to the MC. A script for running on a larger sample for the HZZ accceptance challenge, with options to apply all of the necessary corrections, can be found in:

${PACKAGE_DIR}/HZZ4lD3PDAnalysis/scripts/hsg2_acceptance_challenge_Moriond2013.py

which can be run as:

python ${PACKAGE_DIR}/HZZ4lD3PDAnalysis/scripts/hsg2_acceptance_challenge_Moriond2013.py <output_dir> [<level>]

where is the output directory (must not exist) and (optional) is the 'level' of the acceptance challenge: 0 = no corrections, 1 = energy/z0/isolation corrections, 2 = all corrections and weights.

If running with the corrections enabled, some ROOT files from afs must be accessed (e.g. to get the distributions for pileup reweighting). When running on Edinburgh PPE machines you will need to get a kerberos token as they are in protected directories:

kinit <username>@CERN.CH
aklog

If you are running on your laptop with no afs access, you should copy the files locally, and change the file paths defined in the python script:

  HZZAnalysis.eventInfoBuilder.pileUpMcRootFileName = "/afs/cern.ch/atlas/groups/HSG2/H4l_2013/Moriond/ExtendedPileUpReweight4l/MC12a.prw.root"
  HZZAnalysis.eventInfoBuilder.pileUpDataRootFileName = "/afs/cern.ch/atlas/groups/HSG2/H4l_2013/Moriond/ExtendedPileUpReweight4l/ilumicalc_2012_AllYear_All_Good.root"

In order to apply the IP smearing, you must download the smearing histograms root file from here and place it in the HZZ4lD3PDAnalysis/share folder (see the IPSmearing twiki for more details).

3. How the code works

The code makes extensive use of some of the ATLAS [[https://twiki.cern.ch/twiki/bin/viewauth/AtlasProtected/PhysicsAnalysisTools][PhyicsAnalysisTools (PAT)] packages. D3PDReader code generated using the D3PDMakerReader package is used to handle reading of the D3PD in an efficient way (it can also be used for writing output ntuples in a similar but reduced format to the D3PD). The EventLoop package is used to manage file/IO and running the loop over events (like ROOT TSelector but in a somewhat more advanced way). One advantage of EventLoop is that it can handle submission and retrieval of jobs to different back-ends such as batch systems, PROOF, and the grid (in theory at least; I haven't tried this feature yet). It is worth carefully reading the EventLoop and D3PDMakerReader twikis to get an idea of how they work.

To work with EventLoop we create classes that inherit from EL::Algorithm. These classes look quite like Root TSelector/MakeSelector classes, e.g. they have initialize(), execute() and finalize() methods. Then to run a job, we write a short script or simple program (in C++ or CINT or python, pick your favourite!) which configures the analysis class; sets up the job, defining what samples to run on and where to run on them (locally, batch etc); and passes it all to EventLoop to be run. An example of this can be seen in the util/test_run.cxx and scripts/hsg2_acceptance_challenge_Moriond2013.py scripts described above.

Currently the main analysis class is HZZ4lD3PDAnalysis. This uses a number of tools to "build" and then "select" leptons. These tools are defined as separate classes which can be configured and used as needed.

Builder Classes

The D3PDReader consists of a set of classes which correspond to different blocks in the D3PD. For example, the ElectronD3PDObject corresponds to the el_* branches of the D3PD. For each of the el_* branches the ElectronD3PDObject has a method corresponding to that branch, e.g. ElectronD3PDObject::cl_E() which will return the contents of the el_cl_E branch for the current event. This particular branch is a vector < float > corresponding to the cluster energies of the reconstructed electrons. The D3PDReader is smart enough to know that the electron branches correspond to a collection of individual electrons. It thus also provides an ElectronD3PDObjectElement class, which describes one individual electron. Again, this class has methods corresponding to each of the electron branches, except now they will return the quantity corresponding to one particular electron e.g. float rather than vector< float >. Unfortunately it is not possible to modify the variables returned by these functions e.g. after applying a correction to the energy. Instead one can define UserVariables e.g. electron->Variable< float >("corrected_energy")() = 25456.03.

The Builder classes essentially just set a number of UserVariables on the D3PDObjects. The currently implemented builder classes, and the UserVariables they declare are listed below. NB The Builder classes have flags to define whether or not to apply the corrections. They are generally set to false by default and must be "turned on" in the configuration. The builder classes are smart enough to only apply MC corrections when we are processing MC, and data corrections when we are processing data - it figures this out via the AnalysisConfig::isMC flag.

All of the object builder classes set a TLorentzVector UserVariable called "tlv_physics". This corresponds to the corrected four-momentum that should be used for the physics analysis. So later on in the code, any time you have an electron/muon/jet and want to access it's energy/momentum/phi/eta (e.g. to fill a plot or make a cut), you should access this like:

el->Variable("tlv_physics")().E()

Note the extra () after the ("tlv_physics") bit. This is just due to the way D3PDReader implements the UserVariables.

ElectronBuilder

Sets properties on the ElectronD3PDObjectElements returned by D3PDReader::Event::el()

Variable	Type	Description
TLorentzVector	tlv_physics	Correct TLV to use for physics
float	cl_E_corr	Corrected cluster Energy (smeared, scaled etc)
float	sf_id_loosePP	ID Scale Factor Loose++
float	sf_reco	Reconsruction Scale Factor
int	pass_multilepton	does electron pass MultiLepton menu
float	Etcone20_corr	Corrected Etcone20 isolation
float	Etcone30_corr	Corrected Etcone20 isolation
float	Etcone40_corr	Corrected Etcone20 isolation
float	d0_corr	Corrected d0 (smeared, biased)
float	z0_corr	Corrected z0 (smeared)

MuonBuilder

Sets properties on the MuonD3PDObjectElements. The specific collection "built" depends on the argument passed to MuonBuilder::build(MuonAlgorithm::Name collection). Allowed values are: MuonAlgorithm::STACO, MuonAlgorithm::CALO, MuonAlgorithm::MUID, MuonAlgorithm::MUON (third chain).

Variable	Type	Description
TLorentzVector	tlv_physics	Correct TLV to use for physics
float	pt_corr	Corrected pT
float	pt_id_corr	Corrected pT (ID only)
float	pt_ms_corr	Corrected pT (MS only)
float	sf	Reconsruction Scale Factor
float	Etcone20_corr	Corrected Etcone20 isolation
float	Etcone30_corr	Corrected Etcone20 isolation
float	Etcone40_corr	Corrected Etcone20 isolation
float	d0_corr	Corrected d0 (smeared, biased)
float	z0_corr	Corrected z0 (smeared, biased)
int	allStationsHits	Hit in all 3 stations of the MS

JetBuilder

Sets properties on the JetD3PDObjectElements returned by D3PDReader::Event::jet_AntiKt4TopoEM()

Variable	Type	Description
TLorentzVector	tlv_physics	Correct TLV to use for physics

EventInfoBuilder

Sets event level properties on the EventInfoD3PDObject returned by D3PDReader::Event::eventinfo()

Type	Name	Description
int	RunNumber_physics	Corrected cluster Energy (smeared, scaled etc)
int	n1trkVt	No. Vertices with >=1 tracks
int	n2trkVtx	No. Vertices with >=2 tracks
int	n3trkVtx	No. Vertices with >=3 tracks
float	weight_pu	Pileup weight
float	weight_vtx	Vertex Weight
float	weight_mc	MC Weight

Selector Classes

These classes apply the object selection. They require that the builder methods have already been called ( Apply some checking that the collections have been built). They retrieve the object collections from the D3PDReader, and apply selection cuts, generally filling a cutflow as they go. They then return a vector of pointers to the selected objects. In addition, they set a UserVariable< int > called isSelected, to indicate whether or not the object has been selected (these are int not bool as internally these variables are stored in vectors and vector< bool > is problematic). The currently implemented selector classes are:

• ElectronSelector
• MuonSelector
• JetSelector

Running on files on ECDF_LOCALGROUPDISK locally

From the ppe machines, it is possible to run locally on HSG2 D3PDs stored on ECDF_LOCALGGROUPDISK. This is described in https://twiki.cern.ch/twiki/bin/view/Main/AtlasEdinburghLocalSoftware#Accessing_files_from_ECDF_LOCALG. A list of the HSG2 D3PDs with tag p1344 (produced early 2013) available on ECDF_LOCALGGROUPDISK as of May 2013 is here: ecdf_hsg2files_p1344_8May2012.sort.txt

ECDF setup

First get an ECDF account https://registration.ecdf.ed.ac.uk/eddiereg/. Request access to physics_ifp_ppe to gain access to the ppe storage on ecdf.