ZZtop

ZZtop is an Athena-based analysis program designed to run on AODs.

The purpose of this page is to keep all the documentation of the ZZtop code. Would be great is any new algorithms etc are documented below.

How the code works:

The main algorithm is ZZtop. This class inherits from an Athena base class AthAlgorithm through a base class ZZtopBase. The ZZtop class steers the code and executes the methods of all other classes, which are sub-algorithms of ZZtop. This has several advantages, such as letting us configure the sequence of algorithms much more freely and making ZZtop independent of the evolution of other pieces of Athena code, like the now obsolete CBNT_AthenaAware.

The remaining classes are divided into pre-selection classes (ZZtopElectron, ZZtopMuon, ZZtopJet), analysis filters (ZZtopAnalysis), and object dumpers (ZZtopCaloCluster, ZZtopTrigElectron). The pre-selectors, read data from the AOD file (through StoreGate) and may apply pre-selection cuts on the reconstructed objects, as described below. Objects which pass these cuts are "kept" in containers for later use by the analysis classes (only links to the objects are kept in these containers). The analysis classes then read these objects and can apply further event selection cuts, e.g. on the number of preselected muon objects in the event, or combine object quantities to calculate e.g. invariant masses etc. See below how to configure ZZtop. Both types of algorithm class can declare, fill and store histograms, or branches of a TTree, which are written to a root file (by default zztop.root). Finally, the dumper classes can be used to write to a TTree some quantities necessary for particular studies. The preselection and dumper algorithms both inherit from ZZtopBase. The analysis filters inherit from ZZtopFilterBase so that they can be used later for event skimming. The diagram below illustrates the way ZZtop works.

The algorithms of the TopInputs package can be made to run before ZZtop and do object preselection as configured in TTbarDefaults.py. These preselected objects are then picked up by ZZtop. This is the default mode of running ZZtop. Alternatively, objects can be retrieved from their StoreGate containers and cuts applied directly to them in the preselector classes.

SVN repository

To view the code see the SLT group area in the ATLAS SVN repository.

Validation

A set of validation plots are produced nightly to compare the latest version of ZZtop with a reference version (currently ZZtop-00-01-12). The plots can be found here

Instructions

How to start:

1. Set up Athena in your favourite way. E.g.:

$ source ~/cmthome/setup.sh -tag=TopPhys,16.6.3.5.1,32,setup

NOTE: if using asetup do instead:

$  asetup TopPhys,16.6.3.5.1,32,setup

and remember to add the test directory to the CMTPATH (if needed, depends on your setup). E.g. in z-shell:

$ export CMTPATH=`pwd`:$CMTPATH

2. Check out the latest ZZtop version from the SLT group area:

$ svn co svn+ssh://svn.cern.ch/reps/topslt/ZZtop/trunk
A    trunk/python
A    trunk/python/__init__.py
A    trunk/python/ZZtopFlags.py
A    trunk/share
...
A    trunk/src/ZZtopAnalysis.cxx
Checked out revision 173.

NOTE: to check out a specific tag (e.g. ZZtop-00-01-27) do:

$ svn co svn+ssh://svn.cern.ch/reps/topslt/ZZtop/tags/ZZtop-00-01-27

3. Change the directory name to ZZtop, go to ZZtop/cmt and compile

$ mv trunk ZZtop
$ cd ZZtop/cmt
$ make
#CMT---> (Makefile.header) Rebuilding ../i686-slc5-gcc43-opt/i686-slc5-gcc43-opt.make
#CMT---> (Makefile.header) Rebuilding ../i686-slc5-gcc43-opt/setup.make
#CMT---> (Makefile.header) Rebuilding ../i686-slc5-gcc43-opt/constituents.make
#CMT---> (constituents.make) Rebuilding library links
...
installation done
#CMT---> (constituents.make) install_joboptions done
#CMT---> all ok.

How to run the code:

Interactively...

Run interactively with ZZtop_master_jobOptions.py:

$ mkdir run
$ cd run
$ athena ZZtop/ZZtop_master_jobOptions.py >&! log | tee

Turn algorithms ON and OFF using the switches in this file:

# set ZZtop configuration flags
from ZZtop.ZZtopFlags import ZZtopFlags

ZZtopFlags.DoElectron    = True
ZZtopFlags.DoMuon        = True
ZZtopFlags.DoJet         = True
ZZtopFlags.DoAnalysis    = True
ZZtopFlags.DoSkimming    = True
ZZtopFlags.DoTrigElectron= True
ZZtopFlags.DoCaloCluster = True
ZZtopFlags.StoreGateDump = True

StoreGateDump is there to write out the names and types of all containers in StoreGate, to make it easier to find the right container names when something goes wrong.

This file includes ZZtop_master.py, which you should not edit unless you're adding a new sub-algorithm. In turn, this includes the configuration files for each sub-algorithm, such as DoMuon_jobOptions.py, etc.

On Real Data...

Fill here...

How to do skimming and slimming

Since tag ZZtop-00-01-39, the job options are in place to do skimming and slimming in ZZtop. This uses class MultipleStreamManager (MSMgr) from Database/!AthenaPOOL/!OutputStreamAthenaPool and some useful code from PhysicsAnalysis/!DPDUtils. Technically, what is needed is to create a new POOL output stream, derived from MSMgr, to define it's contents, and to decide which events get sent to the new stream.

The flags (defaults shown):

ZZtopFlags.DoSkimming       = True
ZZtopFlags.SkimAcceptAlgs  = ["ZZtopAnalysis"]   
ZZtopFlags.DoSlimming        = False 

in ZZtop_master_jobOptions.py control the behaviour of the skimming and slimming. The flag "!DoSkimming = True" triggers the building of the output stream. The list of algorithm names passed to SkimAcceptAlgs should inherit from ZZtopFilterBase and decide when to accept events into the output stream. The flag DoSlimming = True would trigger slimming of the AOD content. By default this flag is set to False and the entire contents of the input AOD are copied to the output derived AOD for the accepted events.

How to write your own analysis:

1. Copy the ZZtopAnalysis into a class of your own. You'll need to copy files src/ZZtopAnalysis.cxx, ZZtop/ZZtopAnalysis.h, and share/DoAnalysis_jobOptions.py.
   • Your analysis class .cxx file should be placed in the src/ directory
   • The idea is that the code that everyone uses (preselectors, main class, base classes) should stay in the src/core/ directory
2. Change these to implement your analysis. Things you need to know:
   • Use the prepare() method to initialize counters, variables etc
   • Use the bookHistos() and bookTree() methods to book your histograms and register them with the THistSvc, and to book the and TTree branches, as in the example
   • Use the analyze method to:
     1. Retrieve the object containers you need for analysis (electrons, muons etc)
     2. Calculate any intermediate quantities you need and fill histograms, update counters etc
     3. You can use the setFilterPass(true/false) to signal passing/failing events - will be used later for event skimming
   • You'll need to know how to use the Athena objects (or EDM, event data model, for short...). See the usual wikis for more info:
     • Main ATLAS physics wiki; follow links to the right combined performance groups: https://twiki.cern.ch/twiki/bin/view/AtlasProtected/AtlasPhysics
     • Electrons: https://twiki.cern.ch/twiki/bin/view/AtlasProtected/EgammaAOD
     • Muons: https://twiki.cern.ch/twiki/bin/view/AtlasProtected/MuonCombinedEventDataModel
     • Jets: https://twiki.cern.ch/twiki/bin/view/AtlasProtected/JetAnalysis
     • This page should also be useful when it is updated for the right releases: https://twiki.cern.ch/twiki/bin/view/Atlas/AODClassSummary
3. For your new algorithm to run you will need to edit the following files:
   • src/components/ZZtop_entries.cxx
   • python/ZZtopFlags.py
   • share/ZZtop_master.py
   • share/ZZtop_master_jobOptions.py
4. Test your analysis thoroughly! Especially if you are changing any files in the src/core/ directory or corresponding header files in ZZtop/.
5. Commit your changes to the SVN repository

How to commit your changes to SVN:

• Before committing, remember to decide on what tag you will give to this version of ZZtop. If you only did bug fixes or added variables into the ntuple, you just need to increase zz in ZZtop-xx-yy-zz, but if you added new code, or new functions, then you should increase yy.
• you can only commit code if you have checked out the trunk (not a tag) and do an "update" in case some other changes happened. SVN will try to resolve conflicts but that typically does not work well.
• Update the ZZtop version tag in cmt/version.cmt.
• Edit the ChangeLog: write: which tag this will be, list each piece of code that you modified and what you did, specify any useful information like "To be used for EPS Event Selection".
• commit the changes you've made (remember to leave an explanatory message with "-m"):
• for new code before you commit you need to do svn add filename
• once you have committed your code, start clean, check it out again and see if everything is happy
• remember to make ZZtop_master_jobOptions.py run on Ricardo's file so that the validation job can run

$ svn ci -m "code cleanup"
Sending        ChangeLog
Deleting       ZZtop/ZZtopBJet.h
Sending        ZZtop/ZZtopCaloCluster.h ...
Sending        src/components/ZZtop_entries.cxx
Transmitting file data ..................
Committed revision 29440.

• tag the changes so they can be retrieved in a consistent way

$ svn cp svn+ssh://svn.cern.ch/reps/topslt/ZZtop/trunk -r 126 svn+ssh://svn.cern.ch/reps/topslt/ZZtop/tags/ZZtop-00-01-00
Committed revision 127.

• you can view the directories in SVN with:

$ svn ls svn+ssh://svn.cern.ch/reps/topslt/ZZtop/trunk
ChangeLog
ZZtop/
cmt/
doc/
python/
share/
src/

How to add developers to the commit list (just for the topslt librarian)

Currently topslt librarian is: VB. Login using either personal login or libtopsl account (password in James email). go to /afs/cern.ch/project/svn/reps/topslt/conf and edit the authz file.

How to configure the code

Main switches in ZZtop_master_jobOptions.py:

• ZZtopFlags.DoElectron: use ZZtopElectron preselector class
• ZZtopFlags.DoMuon: use ZZtopMuon preselector class
• ZZtopFlags.DoJet: use ZZtopJet preselector class
• ZZtopFlags.DoAnalysis: use ZZtopAnalysis class
  • When adding new analysis classes, a corresponding flag should be added to python/ZZtopFlags and ZZtop_master.py needs to be modified
• ZZtopFlags.DoSkimming: reserved for later use
• ZZtopFlags.DoTrigElectron: use ZZtopTrigElectron dumper class
• ZZtopFlags.DoCaloCluster: use ZZtopCaloCluster dumper class
• ZZtopFlags.StoreGateDump: write out StoreGate contents for every event - use only for debugging!
• ZZtopFlags.DoElectronEC: Analysis code which does the Electron Event Challenge and prints out values at the end

ZZtop main class

Set flags in DoZZtop_jobOptions.py.

Algorithm configuration:

• ZZtop.WriteNtuple (True/False): write ntuple
• ZZtop.OutputLevel (INFO/DEBUG/etc): debug output level
• ZZtop.TreeName: stream/TTree name - default is "/file1/ZZtop" which writes a TTree called ZZtop in file zztop.root

ZZtop Preselector Classes

Each preselector class can be configured to:

• Use TopInputs selected objects or retrieve objects from a given StoreGate collection and apply selection cuts to these objects
• Write out/not write a block of variables in the output TTree - unless ZZtop.WriteNtuple = False
• Write histograms in a given directory in the output ROOT file
• Have a different OutputLevel for debugging

Note: cuts applied only if retrieving raw objects from StoreGate, not when using TopInputs selected objects.

ZZtop Muon preselector class

Set flags in DoMuon_jobOptions.py.

Algorithm configuration:

• ZZtopMuon.WriteNtuple (True/False): write ntuple
• ZZtopMuon.OutputLevel (INFO/DEBUG/etc): debug output level
• ZZtopMuon.HistPath: stream/directory path for raw data histograms (before preselection) - default is "/file1/histos/RawData"
• ZZtopMuon.UseTopInputs (True/False): get muons either directly from SG or from TopInputs
• ZZtopMuon.TopInputsContName: TopInputs container name (by default uses configuration set in TopInputsSelection.TTbarDefaults)
• ZZtopMuon.AODContainerName: StoreGate name of muon container to use for pre-selection
• ZZtopMuon.CheckDataType: obsolete - check data type is full sim. MC, fast sim. or real data
• ZZtopMuon.UserContainerName: name of ZZtop link container to store pointers to preselected objects - by default "ZZtopPreSelectedMuons"

Muon preselection cuts:

• ZZtopMuon.MuonEtCut: pass pT > cut
• ZZtopMuon.MuonEtaCut: pass |eta|<cut
• ZZtopMuon.MuonIsolCone30: pass Eisol<cut
• ZZtopMuon.MuonIsolRatio30: pass Isolation ratio < cut
• ZZtopMuon.MuonChi2Cut: not currently used

ZZtop Electron preselector class

Set flags in DoElectron_jobOptions.py.

Algorithm configuration:

• ZZtopElectron.WriteNtuple (True/False): write ntuple
• ZZtopElectron.OutputLevel (INFO/DEBUG/etc): debug output level
• ZZtopElectron.HistPath: stream/directory path for raw data histograms (before preselection) - default is "/file1/histos/RawData"
• ZZtopElectron.UseTopInputs (True/False): get muons either directly from SG or from TopInputs
• ZZtopElectron.TopInputsContName: TopInputs container name (by default uses configuration set in TopInputsSelection.TTbarDefaults)
• ZZtopElectron.AODContainerName: StoreGate name of muon container to use for pre-selection
• ZZtopElectron.CheckDataType (True/False): not used - originally to check data type is full sim. MC, fast sim. or real data
• ZZtopElectron.UserContainerName: name of ZZtop link container to store pointers to preselected objects - by default "ZZtopPreSelectedElectrons"

Electron preselection cuts:

• ZZtopElectron.ElectronEtCut: pass ET>cut
• ZZtopElectron.ElectronEtaCut: pass |eta|<cut
• ZZtopElectron.ElectronIsEM: not used for now
• ZZtopElectron.ElectronCutCrack: reject electrons in barrel-endcap calorimeter crack region
• ZZtopElectron.ElectronCrackMinEta: eta of barrel-endcap calorimeter crack lower edge (1.37)
• ZZtopElectron.ElectronCrackMaxEta: eta of barrel-endcap calorimeter crack lower edge (1.52)
• ZZtopElectron.TrackMatchContainer: "egDetailAOD"

ZZtop Jet preselector class

Set flags in DoJet_jobOptions.py.

Algorithm configuration:

• ZZtopJet.WriteNtuple (True/False): write ntuple
• ZZtopJet.OutputLevel (INFO/DEBUG/etc): debug output level
• ZZtopJet.HistPath: stream/directory path for raw data histograms (before preselection) - default is "/file1/histos/RawData"
• ZZtopJet.UseTopInputs (True/False): get muons either directly from SG or from TopInputs
• ZZtopJet.TopInputsContName: TopInputs container name (by default uses configuration set in TopInputsSelection.TTbarDefaults)
• ZZtopJet.AODContainerName: StoreGate name of muon container to use for pre-selection
• ZZtopJet.CheckDataType: obsolete - check data type is full sim. MC, fast sim. or real data
• ZZtopJet.UserContainerName: name of ZZtop link container to store pointers to preselected objects - by default "ZZtopPreSelectedJets"

Jet preselection cuts:

• ZZtopJet.JetEtCut: pass if ET>cut
• ZZtopJet.JetEtaCut: pass if |eta|<cut

ZZtop Analysis classes:

There is at present only one example analysis class: ZZtopAnalysis. The idea is that each analysis should be implemented as a different class (or set of related classes). For ZZtopAnalysis, flags are set in ZZtopAnalysis_jobOptions.py:

• ZZtopAnalysis.WriteNtuple (True/False): write ntuple
• ZZtopAnalysis.OutputLevel (INFO/DEBUG/etc): debug output level
• ZZtopAnalysis.HistPath: stream/directory path for raw data histograms (before preselection) - default is "/file1/histos/RawData"
• ZZtopAnalysis.PresElecContainer: name of ZZtop link container with pointers to preselected objects - by default "ZZtopPreSelectedElectrons"
• ZZtopAnalysis.PresMuonContainer: name of ZZtop link container with pointers to preselected objects - by default "ZZtopPreSelectedMuons"
• ZZtopAnalysis.PresJetsContainer: name of ZZtop link container with pointers to preselected objects - by default "ZZtopPreSelectedJets"

Analysis cuts:

• ZZtopAnalysis.CutNrElectrons
• ZZtopAnalysis.CutNrMuons
• ZZtopAnalysis.CutNrJets
• ZZtopAnalysis.CutJetEt

TTree variables

• EventNr : Event number
• RunNr : Run number
• TimeStamp : Time in ns since 1970
• BunchCross: Bunch cross ID
• LumiBlock : Luminosity block ID
• MCchannel : Monte Carlo channel (process number) assigned by MC generator
• EvGenWeight: For simulated events, statistical weight assigned by MC generator

Muon preselector block:

• nrMuons : number of input (raw) muons
• muonPt : muon pT
• muonEta : muon eta
• muonPhi : muon phi
• muonChi2 : chi squared of the combined muon fit
• muonIsol : muon isolation in a delta(R) cone of 0.3
• muonIsoR : muon isolation energy in a delta(R)=0.3 divided by the muon momentum

Electron preselector block:

• nElec : number of electrons
• Eleta : electron eta
• Elphi : electron phi
• Elpt : electron pT
• ElAuth : electron author
• Eleoverp : E / p of electron candidate
• ElisEM : isEM

Jet preselector block:

• nJets : number of jets
• jetEt : jet ET
• jetEta : jet eta

TrigElectron dumper block:

See the TrigElectron class in Trigger/TrigEvent/TrigParticle

• ntrigElec : number of TtrigElectrons
• trigElEt : TrigElectron ET estimated from the calorimeter cluster
• trigElEta : TrigElectron eta estimated from the track
• trigElPhi : TrigElectron phi estimated from the track
• trigElroiWord : Region-of-Interest identifier of L1 RoI where TrigElectron was found; always zero for releases before 16.6.x.y due to a bug
• trigEltrkAuth : ID of algorithm which produced the track: 0=all, 1=SiTrack, 2=IDScan, 4=TRTxK, 5=SiTrack+IDScan
• trigEltrkZ0 : Z of track at perigee with respect to beamline
• trigElTRThits : number of TRT hits in the TrigElectron track
• trigElTRThiTh : number of high-threshold TRT hits in the TrigElectron track
• trigElTRTratio : ratio of high-threshold TRT hits to all TRT hits in TrigElectron track
• trigEltrkIndx : index of track in L2 TrigInDetTrack containers
• trigEltrkPt : track PT
• trigElcharge : charge obtained from TrigElectron track
• trigEltrkChi2 : TrigElectron track Chi2 / nr. Degrees of Freedom
• trigElnPIXhits : number of Pixel spacepoints in the TrigElectron track
• trigElnSCThits : number of SCT hits in the TrigElectron track
• trigElerrTrPt : error in TrigElectron track PT obtained from the track fit
• trigElerrEta : error in TrigElectron track eta obtained from the track fit
• trigElerrPhi : error in TrigElectron track phi obtained from the track fit
• trigElerrZ0 : error in TrigElectron track Z at perigee obtained from the track fit
• trigElXtrpEta : TrigElectron eta at the calorimeter surface
• trigElXtrpPhi : TrigElectron phi at the calorimeter surface
• trigElDeta : delta(eta) between TrigElectron track extrapolated to calorimeter surface and the TrigElectron calorimeter cluster
• trigElDphi : delta(phi) between TrigElectron track extrapolated to calorimeter surface and the TrigElectron calorimeter cluster
• trigElEtOverPt : TrigElectron cluster ET/ track PT
• trigElCaloEta : eta of TrigElectron calorimeter cluster
• trigElCaloPhi : phi of TrigElectron calorimeter cluster
• trigElReta : calorimeter shower shape - cluster energy ratio E(3x7)/E(7x7)
• trigElRphi : calorimeter shower shape - cluster energy ratio E(3x7)/E(7x7)
• trigElEthad1 : calorimeter cluster ET in first hadronic layer
• trigElF0 : fraction of calorimeter cluster E in presampler divided by cluster energy
• trigElF1 : fraction of calorimeter cluster E in first layer divided by cluster energy
• trigElF2 : fraction of calorimeter cluster E in second layer divided by cluster energy
• trigElF3 : fraction of calorimeter cluster E in third layer divided by cluster energy

Calorimeter cluster dumper block:

See the CaloCluster documentation

• nCaloClus : number of calorimeter clusters
• clEta :
• clPhi :
• clX :
• clY :
• clZ :
• clEnergy :
• clET :
• clTime :
• clNrBadCh :
• clSizeEtaEMB2 :
• clSizePhiEMB2 :
• clNrSamples :
• clEnPresB :
• clEtaPresB :
• clPhiPresB :
• clEnPresE :
• clEtaPresE :
• clPhiPresB :
• clEnEMB1 :
• clEtaEMB1 :
• clPhiEMB1 :
• clEnEMB2 :
• clEtaEMB2 :
• clPhiEMB2 :
• clEnEMB3 :
• clEtaEMB3 :
• clPhiEMB3 :

ZZtopROOT

ZZtopROOT is a ROOT package with the intention of standardising the framework in which ZZtop nTuples are analysed and provides the user with a jobOption style interface to running the code. It also helps to move away from the monster 10,000+ line ROOT analyses to a more readable and developable piece of code.

How the code works:

Essentially the package is a wrapper around ROOT's TSelector class. At the core is a class called ZZtopROOTBase which provides the common services such as exposure of the ZZtop nTuple TTree branches/variables, looping over each entry in the tree, event counters, setting of cut values and message handling. From this class users can then derive their own analysis, inheriting the aforementioned features. For example see:

• ZZtopROOTSkeleton

Additionally there is another core class, ZZtopROOTEC, which extends ZZtopROOTBase to include all the nescessary methods needed to run the event challenge. An example class deriving from ZZtopROOTEC can be found in:

• ZZtopROOTECSkeleton

The diagram below shows the structure of the package:

Deriving classes from ZZtopROOTBase (generic analyses)

Classes derived from the ZZtopROOTBase class, inherit all its functionality so no repetition of code is needed. The only requirement for these (or any) clasees derived from ZZtopROOTBase is that they define and implement the following methods:

• Two public constructors which call ZZtopROOTBase constructors e.g.

       ZZtopROOTYourClassName::ZZtopROOTYourClassName(TTree * tree): ZZtopROOTBase(tree) { }
       ZZtopROOTYourClassName::ZZtopROOTYourClassName(TTree * tree, TString strName): ZZtopROOTBase(tree, strName) { }
       

• A prepareAnalysis(), doAnalysis(), and finalizeAnalysis() method, e.g.

       void ZZtopROOTYourClassName::prepareAnalysis()
       Bool_t ZZtopROOTYourClassName::doAnalysis()
       void ZZtopROOTYourClassName::finalizeAnalysis()
       

The above the methods are called in the order they appear. prepareAnalysis() is called once at the begining of the run and can be used to register histograms and print out start of run information. doAnalysis() is called once per event as is where the meat of the analysis and filling of histograms is done. finalizeAnalysis() is called once at the end of the run and can be used to print out end of run information.

An example class with comments can be found in ZZtopROOTSkeleton.

Deriving classes from ZZtopROOTEC (event challenge type analyses)

Classes derived from the ZZtopROOTEC class inherit all its functionality along with the functionality of ZZtopROOTBase thus minimising the amount of code the user needs to write themselves. The only requirement for these (or any) clasees derived from ZZtopROOTEC is that they define and implement the following methods:

• Two public constructors which call ZZtopROOTAnalysis constructors e.g.

       ZZtopROOTECYourClassName::ZZtopROOTECYourClassName(TTree * tree): ZZtopROOTEC(tree) { }
       ZZtopROOTElectronAnalysis::ZZtopROOTECYourClassName(TTree * tree, TString strName): ZZtopROOTEC(tree, strName) { }
       

• A prepareAnalysisEC(), doAnalysisEC(), and finalizeAnalysisEC() method, e.g.

       void ZZtopROOTECYourClassName::prepareAnalysisEC()
       Bool_t ZZtopROOTECYourClassName::doAnalysisEC()
       void ZZtopROOTECYourClassName::finalizeAnalysisEC()
       

The above the methods are called in the order they appear. prepareAnalysisEC) is called once at the begining of the run and can be used to register histograms and print out start of run information. doAnalysisEC() is called once per event as is where the meat of the analysis and filling of histograms is done. finalizeAnalysisEC() is called once at the end of the run and can be used to print out end of run information.

An example class with comments can be found in ZZtopROOTECSkeleton. Additionally, a class showing how to run the full event challenge (as of 16.6.5.5.1) can be found in ZZtopROOTECAnalysis.

How do I add a histogram?

There is a specialist class called HistogramContainer which is used to collate all the user's histograms. To add a 1D histogram you first have to register it in the prepareAnalysis() method of the analysis, e.g.

m_histograms->add1DHisto(new TH1F("ElCutFlow","Electron Cut Flow", 15, -0.5, 14.5));

m_histograms is an instance of the HistogramContainer and contains a method add1DHisto(TH1F* aNewHistogram). Note that the first argument in the TH1F() constructor is a string (here "ElCutFlow") which is used as a unique name (tag) for this histogram. This name is important as it used to fetch the right histogram from the HistogramContainer when you want to fill it. Histograms should be filled in the doAnalysis() method, e.g.

m_histograms->find1DHisto("ElCutFlow")->Fill(0.,EvGenWeight);

This retrieves the histogram with the string tag "ElCutFlow" from the HistogramContainer and then fills it with an appropriate value and weight. The benefit of the HistogramContainer class is that you do not need to worry about writing out your histogram to a ROOT file as this is taken care of for you.

How do print to the terminal?

Printing to the terminal should be done with the dout(messageLevel) function. This is a wrapper around the std::cout function which is used to control the level of output required by the user without having a million if (...) statements in the code. There are 4 message levels defined, ERROR, WARNING, INFO, DEBUG. In addition there is also a user configurable amount of events for which you can request the DEBUG information. To output some information to the terminal you can do:

dout(DEBUG) << "My Message " << someVariable << endl;

If the message level has been set to INFO then this message will be sent to a dummy stream and therefore will not be seen in the output. However, if the message level has been set to DEBUG then the user will see this message and all INFO, WARNING and ERROR messages to. This follows the same idea as Athena's messaging service.

What variables can I set the value of at run-time?

One of the features of the package is that it allows the user to set values of cuts at run time rather than having to recompile each time a value is changed. Currently all the values of the cuts can be set at run-time along with the status . Here is the complete list of available public methods:

ZZtopROOTBase methods:

• void nEvtsDebug(Int_t intEvts) - number of events to debug
• void messageLevel(Int_t level) - the message level required, 0 = ERROR, 1 = WARNING, 2 = INFO, 3 = DEBUG

• void muonPtCut(Double_t cutval) - the muon pT cut value in GeV
• void electronEtCut(Double_t cutval) - the electron eT cut value in GeV
• void metEtCut_el(Double_t cutval) - the missing eT cut value in GeV for the e+jets channel
• void metEtCut_mu(Double_t cutval) - the missing eT cut value in GeV for the mu+jets channel
• void jetPtCut(Double_t cutval) - the jet pT cut value in GeV
• void jetEtaCut(Double_t cutval) - the jet Eta cut value
• void wmtCut(Double_t cutval) - W transverse mass cut value in GeV
• void wmtMETCut(Double_t cutval) - W transverse mass cut plus missing eT cut value in GeV
• void nTracksCut(Int_t cutval) - number of tracks cut value
• void badJetPtCut(Double_t cutval) - bad jet pT cut value in GeV

• void isData(Bool_t cutval) - is data flag, false = MC, true = real data (default = false)
• void useSMT(Bool_t cutval) - use SMT tagged b-jets (default = false)

ZZtopROOTEC methods:

• void setCutStatus(int cutNumber, bool status) - turn on/off a specific cut, e.g. setCutStatus(10, false). By default all cuts are active.

Note that all the cut values are defaulted to their value as per the 16.6.5.5.1 event challenge ( see ZZtopROOTBase.C::defaultCuts() ), so you only need to change the value if you require it to be different. This is a fairly minimal list at the moment but can easily be extended at the user's request.

Instructions:

Setup:

Firstly to get the package do the following (NOTE: don't setup Athena as its not needed!):

cd <your favourite analysis area>
svn co svn+ssh://svn.cern.ch/reps/topslt/ZZtop/trunk/root/ZZtopROOT

You now will have a directory called ZZtopROOT which contains the source for the ZZtopROOT package. Before you can run the package you will need to compile it against ROOT. You should be able to compile it against any version of ROOT and on any architecture. The only requirement is that you are using a version of ROOT that has been compiled for the architecture and version of gcc on the machine you intend to run on. For example, if you intend to run on a 64bit SLC5 machine with gcc version 4.3 then you would need to have the $ROOTSYS environment variable pointing to a slc5.gcc4.3-x86_64 version of ROOT and append $ROOTSYS/lib to your $LD_LIBRARY_PATH. This may sound tedious but ROOT comes with a setup script that takes care of that for you. For example at RHUL:

source /usr/local/root/v5.26.00/slc5.gcc4.3-x86_64/setup.(c)sh

setups the environment for you. To test your configuration:

echo $ROOTSYS 

should point to /usr/local/root/v5.26.00/slc5.gcc4.3-x86_64/root and

root-config --libs

should produce sensible output (list the core ROOT libraries). Once your configuration is set then you can proceed onto compiling the package. I have included an install script to make things easier:

cd <your favourite analysis area>/ZZtopROOT
./install.sh

If all goes well then it should produce a shared library libZZtopROOT.so in the Code/Release directory.

Run

Now you're ready to run. Navigate to the Run directory and look through the contents of the file ZZtop_rootJobOptions.C:

cd <your favourite analysis area>/ZZtopROOT/Run
emacs ZZtop_rootJobOptions.C

The only thing you will need to change here is the location of your nTuples (in chain->Add("......")). You can choose to change values of cuts and the message level if you wish (see the section above for a list of variables that can be set at run-time). When you're happy with the settings then run the analysis:

root (-b -q) ZZtop_rootJobOptions.C | tee ZZtopROOTrun.log

The output will be a histogram file ZZtopROOT_histos.root which currently just contains cut flow histograms.

-- RicardoGoncalo - 26-May-2011 -- NeilCooperSmith - 19-Sep-2011