Instructions for Participants

Version 2.0: October 25, 2004
Ketevi A. Assamagan

Where do I get Documentation before coming to the Tutorial?

It is assumed that the user is familiar with how to use ATHENA. If that is not the case, he or she should first read this.

Documentation for doing analyses on AOD

The analysis EDM Classes:ParticleEvent, BTaggingEvent and CompositeParticleEvent

Some Analysis Example Codes

Histograms and Ntuples in ATHENA

How do I get started doing analysis on AOD?

We provide a package, UserAnalysis, to help you get started with the development of your analysis codes. This package consists of a simple Gaudi Algorithm, the AnalysisSkeleton. The user may check out this package and start implementing his/her analysis code.

What should I do before coming to the tutorial?

We will use the software Release 8.8.1 for this tuturial

Exercise 0: I should make sure that CMT is setup correctly

1. login to lxplus

ssh myUserName@lxplus

2. Check that my $Home requirements file is set for 8.8.1

Here is Jane Doe's $Home requirements file

###################################################################
tag Tutorial 8.8.1 special
tag AOD 8.8.1 special
set CMTSITE CERN
set SITEROOT /afs/cern.ch
macro ATLAS_DIST_AREA ${SITEROOT}/atlas/software/dist
macro ATLAS_TEST_AREA "" \
Tutorial "${HOME}/scratch0/Tutorial/8.8.1" \
AOD "${HOME}/public/aod/workarea"

use AtlasLogin AtlasLogin-* $(ATLAS_DIST_AREA)
###################################################################

3. Setup CMT

Jane Doe's working directory for this tutorial is "${HOME}/scratch0/Tutorial/8.8.1" where
${HOME}=/afs/cern.ch/user/j/janedoe/
So, Jane Doe will setup CMT by doing this
source setup.sh -tag=Tutorial,opt
Then, Jane Doe checks that the CMT path is correctly defined by doing this:
echo $CMTPATH
Something like this is printed to the screen

/afs/cern.ch/user/j/janedoe/scratch0/Tutorial/8.8.1/:/afs/cern.ch/atlas/software/dist/8.8.1:
/afs/cern.ch/atlas/offline/external/Gaudi/0.14.6.6:
/afs/cern.ch/atlas/offline/external/LCGCMT/LCGCMT_26_2c

The path to Jane Doe's working directory, to the ATLAS software distribution, to external libraries are all defined.

4. Change Directory to your working area for this tutorial

Jane Doe does the following:
cd scratch0/Tutorial/8.8.1

5. We will use UserAnalysis/UserAnalysis-00-01-08 for this tutorial

So Jane Doe checks out this package by doing this
cmt co -r UserAnalysis-00-01-08 PhysicsAnalysis/AnalysisCommon/UserAnalysis

6. Let us compile, build and test this package by doing the following

cd PhysicsAnalysis/AnalysisCommon/UserAnalysis/UserAnalysis-00-01-08/cmt/
cmt config
source setup.sh
gmake

7. Let us make sure that everything is OK and we are ready for the tutorial by doing this

cd ../run
get_files HelloWorldOptions.py
athena.py -b HelloWorldOptions.py

Stuff like this should be printed to the screen

HelloWorld INFO execute()
HelloWorld INFO An INFO message
HelloWorld WARNING A WARNING message
HelloWorld ERROR An ERROR message
HelloWorld FATAL A FATAL error message
AthenaEventLoopMgr INFO ===>>> end of event 9 <<<===
HistorySvc INFO Service finalised successfully
ChronoStatSvc.f... INFO Service finalized succesfully
ToolSvc INFO Removing all tools created by ToolSvc
ApplicationMgr INFO Application Manager Finalized successfully
ApplicationMgr INFO Application Manager Terminated successfully

If you successfuly reach this point, you are ready for the tutorial, otherwise, please seek help before Monday, you may contact me.

My first analysis code on AOD

Once the above steps are successful, you should try this before coming to the tutorial

(a) run the AnalysisSkeleton Algorithm

cd ../run
get_files AnalysisSkeleton_jobOptions.py
athena.py -b AnalysisSkeleton_jobOptions.py

This will run the user analysis skeleton algorithm which you find in the package UserAnalysis. However, it will not run because of two things:
i. The input data file specified in the job Options AnalysisSkeleton_jobOptions.py is not defined
ii. The PoolFileCatalog.xml file which defines the ID of the input data is also not there

(b) Before you run your analysis code

The input AOD data file(s) and the corresponding PoolFileCatalog.xml file must be correctly set. Let us do this now and try to run again:

i. Edit AnalysisSkeleton_jobOptions.py and replace these lines

# The AOD input file
EventSelector.InputCollections = [
"AOD_Zee.root",
"AOD_Zmm.root",
"AOD_Ztt.root"
]

by these ones

# The AOD input file
EventSelector.InputCollections = [
"rfio:/castor/cern.ch/user/k/ketevi/ttbar/aod/dc2.003026.A0_top.g4dig807.aod881._00001.pool.root"
]

ii. The PoolFileCatalog.xml

Now, we need to get the PoolFileCatalog.xml file which defines the ID of this data file
You can copy it from here
cp /afs/cern.ch/user/k/ketevi/w0/aod/PoolFileCatalog.xml .

iii. You may want to look in the PoolFileCatalog.xml to convince yourself that the path and file name of your input data in AnalysisSkeleton_jobOptions.py appear in there
iv. You can re-run the analysis skeleton as follows:
athena.py -b AnalysisSkeleton_jobOptions.py
Now it should successfully, producing a ROOT output file called AnalysisSkeleton.root.
v. Open this file in ROOT and browse the histograms

If you reach this point, congratulations! Then, edit the header file AnalysisStekeleton.h and the implementation file AnalysisSkeleton.cxx to see what this analysis code is doing. If you did not successfully reach this point, seek help, you may contact me

Exercise 1: Plot the W to jj Invariant Mass

At the end of this exercise, you should have a plot of the W to jj invariant mass. The data file data you are using is the top pair production, simulated for the Data Challenge 2. You will retrieve a container AOD jets from the persistency storage. You will loop over the jets in the container, and for each jet, you will plot the jet tranverse momentum and pseudo-rapidity. You will put a cut of 20 GeV on the jet transverse momentum, and for the jets that pass the cut, you will make the jet-jet combinations, calculate the jet-jet invariant mass and put it in a histogram. So, you are adding 3 histograms to the list that we already have.

Some Clarifications


i. The AOD jet class is called ParticleJet.h: this is for all types of jets at the exception of the tau jet and the B jet which have their own class, namely TauJet.h and BJet.h. The AOD object classes can be found in ParticleEvent and BTaggingEvent. Click on the ParticleEvent link and take a look at the ParticleJet class which you will be using in this exercise. Never mind if there are stuff in there that you do not know about yet.

ii. A container of AOD objects: by container, we mean an STL vector, or rather, a DataVector of AOD objects. The DataVector is just an STL vector which, by default, in the C++ language, "owns" the stuff that it contains. Each AOD object has an associated container. For example, the ParticleJet has a corresponding ParticleJetContainer.h class. Click on the ParticleEvent link above and look at the ParticleJetContainer class which you will also need in this exercise.

iii. Retrieve the container of AOD jets: the AOD data file that you are using, for example the one that you have in your job options file AnalysisSkeleton_jobOptions.py, was created for you by somebody - you will learn later how to create your own ESD and AOD. When you want to us the AOD objects in your analysis code, on event by event basis, you ask for a pointer to the container of the AOD objects. For example, in the execute() method of the AnalysisSkeleton.cxx, you were asking for the container of the Electron AOD:

const ElectronContainer* elecTES;
sc=m_storeGate->retrieve( elecTES, m_electronContainerName);
if( sc.isFailure() || !elecTES ) {
mLog << MSG::WARNING
<< "No AOD electron container found in TDS"
<< endreq;
return StatusCode::SUCCESS;
}
mLog << MSG::DEBUG << "ElectronContainer successfully retrieved" << endreq;

iv. Container Names: you need to know the "name" of the container that you want to access. What we mean by name here is the std::string code that was used to create the AOD container. You need to know that so you can ask for that container if you need it. In the above snippet of code, the data member m_electronContainerName defines the name of the ElectronContainer that you want to retrieve. If you look in the constructor of AnalysisSkeleton.cxx, you will see that m_electronContainerName is initialized to "ElectronCollection". That is the name used when the AOD electron container was produced for you. Below is the complete list of containers/objects with their name.

Container/Object Names for Fast Simulation AOD


ElectronContainer Name = "AtlfastElectronCollection"
PhotonContainer Name = "AtlfastPhotonCollection"
MuonContainer Name = "AtlfastMuonCollection"
TauJetContainer Name = "AtlfastTauJetContainer"
BJetContainer Name = "AtlfastBJetContainer"
ParticleJetContainer Name = "AtlfastParticleJetContainer"
Missing Et objet Name = "AtlfastMissingEt"
TruthParticleContainer Name = "SpclMC"

Container/Object Names (other than Fast Simulation)


ElectronContainer Name = "ElectronCollection"
PhotonContainer Name = "PhotonCollection"
MuonContainer Name = "MuonCollection"
TauJetContainer Name = "TauJetCollection"
BJetContainer Name = "BCandidates"
ParticleJetContainer Name = "ParticleJetContainer"
Missing Et objet Name = "MissingEtObject"
TruthParticleContainer Name = "SpclMC"
Inner Detector TrackParticles = TrackParticleCandidate
Muonboy TrackParticles = MuonboyTrackParticles
STACO TrackParticles = StacoTrackParticles
MOORE TrackParticles = MooreTrackParticles
MuID StandAlone TrackParticles = MuidStandAloneTrackParticles
MuID Combined TrackParticles = MuidCombnoSeedTrackParticles

v. Loop over the Objects in the Container: after you successfully retrieve the container and have a pointer to it in the transient data store (TDS), you can get the iterators over the container since the container is a DataVector. Look at the example in the execute() method of AnalysisSkeleton.cxx:

const ElectronContainer* elecTES;
sc=m_storeGate->retrieve( elecTES, m_electronContainerName);
if( sc.isFailure() || !elecTES ) {
mLog << MSG::WARNING
<< "No AOD electron container found in TDS"
<< endreq;
return StatusCode::SUCCESS;
}
mLog << MSG::DEBUG << "ElectronContainer successfully retrieved" << endreq;

/// iterators over the container
ElectronContainer::const_iterator elecItr = elecTES->begin();
ElectronContainer::const_iterator elecItrE = elecTES->end();

for (; elecItr != elecItrE; ++elecItr) {
if( (*elecItr)->hasTrack() &&
(*elecItr)->pt()> m_etElecCut ) {
m_h_elecpt->fill( (*elecItr)->pt(), 1.);
m_h_eleceta->fill( (*elecItr)->eta(), 1.);
...

vi. Access to the Kinematics: all the AOD objects are 4Momentum objects, meaning that they should be able to answer all your questions about their kinematics. For example, to ask the Electron object for its transverse momentum and pseudo rapidity:

for (; elecItr != elecItrE; ++elecItr) {
if( (*elecItr)->hasTrack() &&
(*elecItr)->pt()> m_etElecCut ) {
double electronPt = (*elecItr)->pt();
double electronEta = (*elecItr)->eta();
...

Look at the 4Momentum implementation for further details.

vii. Histogramming: Some example of how to create, fill and save histograms in ATHENA are shown in AnalysisSkeleton.h, AnalysisSkeleton.cxx and AnalysisSkeleton_jobOptions.py. For further details, look at this page:

Histograms and Ntuples in ATHENA

iix Now you have all that you need to do this exercise: proceed as described below. When you finish the exercise, your ROOT output file, AnalysisSkeleton.root, should have only 3 histograms in it, the transverse momenta of the jets, the pseudo-rapidities of the jets, and the jet-jet invariamt masses, for jets above 20 GeV.

Clean up


i. In AnalysisSkeleton.h and AnalysisSkeleton.cxx, remove everything between the lines "Remove this if not needed" or "to be removed if not needed".

ii. Recompile the code as you did above previously, this to make sure that nothing got screwed up when you removed the lines in question.

Write your Analysis Code


i. Include the follwing lines in AnalysisSkeleton.cxx

#include "ParticleEvent/ParticleJet.h"
#include "ParticleEvent/ParticleJetContainer.h"

ii. Add the piece of code define the AOD jet container name, so you can change it your job options if necessary.
iii. Define the 3 histograms mentioned above
iii. Add the piece of code to retrieve the AOD jet container from the TDS
iv. Add the piece of code to iterate over the AOD container
v. For each jet, get its transverse momentum and pseudo rapidity and fill the relevant histograms if the jet transverse momentum is greater than 20 GeV
vi. Add the piece of code to do the jet-jet combinations, and for each combination, to calculate the jet-jet invariant and the fill the histogram
vii. Compile and build your analysis code

Run your Analysis Code


You need more statistics, so proceed as follows

i. Change directory to your run directory
ii. cp ~ketevi/w0/aod/PoolFileCatalog.xml .
iii. cp ~ketevi/w0/aod/aodinput.py .
iv. Edit AnalysisSkeleton_jobOptions.py and replace these lines

# The AOD input file
EventSelector.InputCollections = [
"rfio:/castor/cern.ch/user/k/ketevi/ttbar/aod/dc2.003026.A0_top.g4dig807.aod881._00001.pool.root"
]

by these ones

# The AOD input file
include ( "aodinput.py" )

v. Now, run your analysis code by doing this
athena.py -b AnalysisSkeleton_jobOptions.py

vi. Open AnalysisSkeleton.root in ROOT, examine the jet-jet invariant mass distribution and make sure that it is, a sort of, OK: a bump around the W mass