Instructions for Participants

Version 7.0: December 19, 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.

Some useful information

Histograms and Ntuples in ATHENA

What should I do before coming to the tutorial?

We will use the software Release 9.0.2 at BNL for this tuturial. However, you will do exercise 0 with the release 9.0.1. Then, you will be asked to do exercise 0.5 with 9.0.2 before coming to the tutorial.

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

1. Login to one of the acas interactive machines at BNL

You must first login through the gateway machine:

ssh atlasgw00.bnl.gov

Then you login to an acas machine
rterm -i

2. If you have not used CMT at BNL before

If you have not used CMT at the BNL before, do as follows before proceeding further:

cd
source /afs/usatlas.bnl.gov/cernsw/contrib/CMT/v1r16p20040901/mgr/setup.csh
cmt config

3. Check that my $Home requirements file is set for 9.0.1

Here is Jane Doe's $Home requirements file. If you do not have a file called "requirements", create one add the lines below to it:

###################################################################
set     CMTSITE         BNL
set     SITEROOT        /afs/usatlas.bnl.gov
macro   ATLAS_DIST_AREA ${SITEROOT}/software/dist
macro   ATLAS_TEST_AREA "" \
        9.0.1        "${HOME}/Tutorial" \
        9.0.2        "${HOME}/Tutorial"

use     AtlasLogin      AtlasLogin-*    $(ATLAS_DIST_AREA)

###################################################################

4. Setup CMT

Jane Doe's working directory for this tutorial is "${HOME}/Tutorial/9.0.1" where
${HOME}=/direct/usatlas+u/janedoe. Create the directory Turtorial/9.0.1 if you do not have it:
mkdir -p Tutorial/9.0.1
So, Jane Doe will setup CMT by doing this
source setup.csh -tag=9.0.1,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

/usatlas/u/janedoe/Tutorial/9.0.1/:/afs/usatlas.bnl.gov/software/dist/9.0.1:
/afs/usatlas.bnl.gov/offline/external/Gaudi/0.14.6.12:
/afs/usatlas.bnl.gov/offline/external/LCGCMT/LCGCMT_26_2d

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

5. Change Directory to your working area for this tutorial

Jane Doe does the following:
cd Tutorial/9.0.1

6. We will use Reconstruction/RecExample/RecExCommon for this tutorial

So Jane Doe checks out this package by doing this
cmt co -r RecExCommon-00-02-85 Reconstruction/RecExample/RecExCommon

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

cd Reconstruction/RecExample/RecExCommon/RecExCommon-00-02-85/cmt/
cmt config
source setup.csh
gmake

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

cd ../run
get_files PDGTABLE.MeV
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 coming, you may contact me.

9. The next time you login

The next you login to the acas machine, you set up CMT by just doing the following

In ${HOME} directory or where you have your "requirements" file
source setup.csh -tag=9.0.1,opt

Then

cd Tutorial/9.0.1/Reconstruction/RecExample/RecExCommon/.../cmt
cmt config
source setup.csh
cd ../run

Take a look at this page for further details about setting up CMT

Exercise 0.5: Setup your enviroment for the Release 9.0.2

Redo steps 1-9 above to setup your environment for the release 9.0.2; you will need to check out RecExCommon-00-02-87 for 9.0.2 (step 6 above). We will use release 9.0.2 at the tutorial. Your are advised not to put CMT setup files in you ${HOME} directory since the setup.csh file there could be created by different applications. It is a good and recommended practice to create a "cmthome" directory under your ${HOME} for CMT setup:

cd
mkdir cmthome
cd cmthome
put your "requirements" file here. It should now look like this
###################################################################
set     CMTSITE         BNL
set     SITEROOT        /afs/usatlas.bnl.gov
macro   ATLAS_DIST_AREA ${SITEROOT}/software/dist
macro   ATLAS_TEST_AREA "" \
        9.0.1        "${HOME}/cmthome/Tutorial" \
        9.0.2        "${HOME}/cmthome/Tutorial"

use     AtlasLogin      AtlasLogin-*    $(ATLAS_DIST_AREA)

###################################################################
mv ${HOME}/Tutorial .
source /afs/usatlas.bnl.gov/cernsw/contrib/CMT/v1r16p20040901/mgr/setup.csh
cmt config
source setup.sch -tag=9.0.2,opt
cd Tutorial/9.0.2/Reconstruction/RecExample/RecExCommon/.../cmt

Exercise 1: Running the Reconstruction Software (ESD/AOD Production)

10. Run the ATLAS Reconstruction software

First all, let us compile everything:
cd ../cmt
cmt broadcast gmake

Second, change directory to the "run" directory
cd ../run

Get the default reconstruction "data card" file to run with
get_files myTopOptions.py

Third, we need to edit this file to define our options, in particular, the input datafile to run with and the number of events to process

The Number of Event: EvtMax = 5
The input data file:
PoolRDOInput = [ "/usatlas/magdacache002/common/ketevi/dijets180/dc2.003003.digit.B1_jets_180._00012.pool.root.1" ]

This file corresponds to di-jet events (180 GeV) fully simulated in Geant4 and digitized (simualtion of the electronic output)
Let us switch off Muonbox:

 
doMuonbox = False
At the very bottom of myTopOptions.py, add the following lines, to connect to the database at BNL instead of at CERN
NovaCnvSvc.Host = "db1.usatlas.bnl.gov"
RDBAccessSvc = Service( "RDBAccessSvc" )
RDBAccessSvc.HostName   = "pdb01"
Take a look at my version of myTopOptions.py to see where in the file I added the above options (you may copy my version of myTopOptions.py)
~ketevi/cmthome/9.0.2/Reconstruction/.../run/myTopOptions.py

However, we still cannot run, there is one input file that we have to specify before running: the PoolFileCatalog.xml.
Copy this file from:
~ketevi/cmthome/9.0.2/PoolFileCatalog.xml
Edit PoolFileCatalog.xml to check that our data file is correctly defined in there

athena.py -b myTopOptions.py

This will run 5 events and produce 2 output files
ntuple.root
histo.root

The variables in the ntuple are described here
open ntuple.root in ROOT and browse it: plot the number of muons reconstructed in the MuonSpectrometer:
root ntuple.root
or
root
TFile *ntuple = TFile::Open("ntuple.root")
then
.ls
ntuple->cd("CBNT")
t3333->Draw("nmuonmo")
b = TBrowser()
click on ROOT files
click on ntuple.root
double click on CBNT
double click on t3333
and browse the ntuple
.q

11. Produce your own ESD

11.1 Check out the UserAnalysis Package

cd ~janedoe/Tutorial/9.0.2
cmt co -r UserAnalysis-00-01-09 PhysicsAnalysis/AnalysisCommon/UserAnalysis

11.2 Compile and build the UserAnalysis Package

cd PhysicsAnalysis/AnalysisCommon/UserAnalysis/UserAnalysis-00-01-09/cmt/
cmt config
source setup.csh
cmt broadcast gmake

11.3 Set up for the ESD Production

cd ../run
cp ~ketevi/cmthome/9.0.2/PoolFileCatalog.xml .
get_files PDGTABLE.MeV
get_files myTopOptions.py

Add the following lines to your myTopOptions.py file above this line:
include ("RecExCommon/RecExCommon_flags.py").

############################################################################
# For ESD Production
doWriteESD = True
#number of Event to process
EvtMax = 5
#switch off Muonbox - it is too slow, people ar working on the speed issues
doMuonbox = False
# suppress the production of ntuple and histogram files
doCBNT = False
doHist = False
# the input raw data file
PoolRDOInput = [ "/usatlas/magdacache002/common/ketevi/dijets180/dc2.003003.digit.B1_jets_180._00012.pool.root.1" ]
#############################################################################
Add these lines at the bottom of myTopOptions.py
NovaCnvSvc.Host = "db1.usatlas.bnl.gov"
RDBAccessSvc = Service( "RDBAccessSvc" )
RDBAccessSvc.HostName   = "pdb01"
Now run myTopOptions.py as you did in step 10. When the run is finished, and ESD file named ESD.pool.root will be available in your directory. You can can change the name and set the location of the ESD file by adding this line to your myTopOptions.py file
PoolESDOutput = "ESD output file path and name"

Note that PoolFileCatalog.xml gets automatically updated at the end of the job with the new ESD file that you just produced. To see this, dump PoolFileCatalog.xml
cat PoolFileCatalog.xml

12. Produce your own AOD from ESD

Comment out or the remove the ESD production lines from your myTopOptions.py and add the following lines instead

#############################################################################
#AOD Production from ESD
# RecExCommon Flags
AllAlgs    = False
readESD    = True
doWriteAOD = True
doHist     = False
PoolESDInput = [ "ESD.pool.root" ]

# Detector Flags
from AthenaCommon.DetFlags import DetFlags
DetFlags.detdescr.ID_setOn()
DetFlags.detdescr.Calo_setOn()

# AOD Flags
from ParticleEventAthenaPool.AODFlags import AODFlags
AODFlags.Streaming = False

#############################################################################
Since we are producing the AOD from the ESD, we need to have the ESD file available: use the ESD that you produced in step 11. as the input for the AOD production. The default output name for the AOD is AOD.pool.root. Check that this file is available in your "run" at the end of the AOD production job. To specify a different file name for your AOD, add this line:
PoolAODOutput = "file path and name"

You may dump your PoolFileCatalog.xml to confirm that it is updated, at the end of the job, with the new AOD file that you just produced

13. Running on many input files

For the ESD production is step 11., we only used one raw data file which has only 50 events. For more statistics on the same dataset, you can specify more input files. Suppose you want 100 events in the ESD: since each of these di-jets have 50 events, the PoolRDOInput (see step 10 above) could be changed to the following:
PoolRDOInput = [
"/usatlas/magdacache002/common/ketevi/dijets180/dc2.003003.digit.B1_jets_180/dc2.003003.digit.B1_jets_180._00012.pool.root.1",
"/usatlas/magdacache002/common/ketevi/dijets180/dc2.003003.digit.B1_jets_180/dc2.003003.digit.B1_jets_180._00018.pool.root.1"
]
Note that all the files that you list as input must be defined in your PoolFileCatalog.xml. The same is true for the production of the AOD, if you run over many different input ESD files. It is however recommended that you keep a one-to-one correspondence between the raw data file, the ESD and the AOD.

14. Configuring your ESD/AOD production jobs

OK. This is what we've done so far since step 10.:
i. We run the standard reconstruction, myTopOptions.py --- we edited this file to specify few important options such as the input raw data file
ii. We run ESD production: again, we edited myTopOptions.py and specify few more options needed for the production of the ESD
iii. We run the AOD production: again, we edited myTopOptions.py, removed the ESD production options, then defined the AOD production options.

This constant editing of myTopOptions.py could lead to errors, and also one does not keep track of the options that are been set/unset. It is possible to specify your options in seperate files. We will show how to do it follows:
(a) Create a new file called optRecExToESD.py for the options to produce the ESD and and these lines to the file and save it.

############################################################################
# For ESD Production
doWriteESD = True
#number of Event to process
EvtMax = 5
#switch off Muonbox - it is too slow, people ar working on the speed issues
doMuonbox = False

# suppress the production of ntuple and histogram files
doCBNT = False
doHist = False

# The ESD output file name
PoolESDOutput = "ESD.pool.root"
# the input data file
PoolRDOInput = [ "/usatlas/magdacache002/common/ketevi/dijets180/dc2.003003.digit.B1_jets_180._00012.pool.root.1" ]

#############################################################################
(b) Create a new file called optESDtoAOD.py for the options to produce the AOD from the ESD and add these lines to the file and save it
#############################################################################
#AOD Production from ESD
# RecExCommon Flags
AllAlgs    = False
readESD    = True
doWriteAOD = True
doHist     = False
PoolAODOutput = "AOD.pool.root"
PoolESDInput = [ "ESD.pool.root" ]

# Detector Flags
from AthenaCommon.DetFlags import DetFlags
DetFlags.detdescr.ID_setOn()
DetFlags.detdescr.Calo_setOn()

# AOD Flags
from ParticleEventAthenaPool.AODFlags import AODFlags
AODFlags.Streaming = False

#############################################################################
(c) Remove the file myTopOptions.py from your "run" directory
rm myTopOptions.py
(d) Get a fresh, un-spoiled copy of myTopOptions.py from the release
get_files myTopOptions.py
(e) Edit myTopOptions.py and at the very bottom of this file add these lines, as we did in steps 10. and 11.
NovaCnvSvc.Host = "db1.usatlas.bnl.gov"
RDBAccessSvc = Service( "RDBAccessSvc" )
RDBAccessSvc.HostName   = "pdb01"
(f) Now reproduce your ESD with the following command
athena.py -b optRecExToESD.py myTopOptions.py
(g) Reproduce your AOD with the following command
athena.py -b optESDtoAOD.py myTopOptions.py

Note that it is also possible to specify the options on the command line
athena.py -b -c 'EvtMax=100; PoolESDInput=["ESD.pool.root"]; PoolAODOutput="AOD.pool.root"; ...' myTopOptions.py
Where do I find the list of the reconstruction flags?

Where do I find the AOD production flags?

15. Fast Simulation AOD

Fast simulation AOD can be obtained from generated events. Suppose you use Pythia to generate ttbar events and you save the output of the generator as POOL file

get_files produceGenEvents_jobOptions.py

Edit this file to see what is in it: the generation of ttbar events in Pythia. Run this job options:

athena.py -b produceGenEvents_jobOptions.py

it will create an output file, McEvent.root. The file contains the output of generator. Note that the simulation steps are as follow

(a) Event generation: you run Pythia or some other generator and you save the output in POOL files as we just did above
(b) Detector simulation: you simulate the detector response by using (a) as input. The output of this process is also saved as POOL files
(c) Digitization: simulation of the electronic output or the raw data. (b) is used as input and the output can either be byte stream files or POOL files
(d) Reconstruction and ESD production: (c) is used as input. So far in this exercise, we have been using simulated raw data file in POOL as the input to our reconstruction. We could as well have used simulated byte stream files, or combined test beam byte stream files (although this would necessitate a different package ...)

The generated files, the simulated files, the digitized files and ESD all contain the generated event record. This means you can use any of these files as input for the fast simulation AOD. Alternatively, you can produce your own generated events, using the job options produceGenEvents_jobOptions.py for examples, then in a subsequent step, use these generated events as input to your fast simulation AOD production:

get_files FastSimToAOD_jobOptions.py

Edit this file and replace this line

    INPUT = [ "rfio:/castor/cern.ch/atlas/project/dc2/preprod/evgen804/dc2.002896.pyt_h130_llll.evgen804/data/dc2.002896.pyt_h130_llll.evgen804._0001.pool.root" ]
with this one
    INPUT = [ "McEvent.root" ]
Edit FastSimToAOD_jobOptions.py and comment out this line
PoolSvc.ReadCatalog = [ "xmlcatalog_file:PoolFileCatalog.xml" ]

Now produce your fast simulation AOD
athena.py -b FastSimToAOD_jobOptions.py

Note that you can change number of events, the input file name and the AOD output file name, directly at the command line: look in FastSimToAOD_jobOptions.py for further details. But try this:
athena.py -b -c 'INPUT=["ESD.pool.root"]; OUTPUT="fastAOD.root"; EVTMAX=100' FastSimToAOD_jobOptions.py

16. Large Scale Production of ESD and AOD

For large statistics, you may submit batch jobs on Condor at BNL or LSF at CERN. Example scripts to do this can be found in the AnalysisExamples. Some individuals have successfully produced large scale ESD and AOD on the grid: the steps to do this are beyond the scope of this tutorial.

17. Create your own analysis algorithm

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. You can also run the reconstruction, the ESD and AOD production from this package as you've just done above.

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 the input data file specified in the job Options AnalysisSkeleton_jobOptions.py is not defined. 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 = [
   "AOD.pool.root" ]
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.
Open this file in ROOT and browse the histograms

Talks

DC2 Data and Tier1 [ppt] Hong Ma

Overview of the ATLAS software [pdf] or [ppt] Ketevi A. Assamagan

Exercise 2: di-jet Invariant Mass

At the end of this exercise, you should have a plot of the di-jet invariant mass. The data file data you are using is the di-jet production at 180 GeV, 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 calculate the di-jet invariant mass and put it in a histogram: use the 2 leading jets, add 2 histograms for the transverse momenta of the two leading jets. So, you are adding 5 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 di-jet invariamt mass.

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 calculate the di-jet invariant mass and the fill the histogram: in their containers, the AOD objects are ordered in falling transverse momentum
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/cmthome/9.0.2/dijets/aodinput.py .
iii. Look inside aodinput.py to see the list of the input AOD files
iv. Edit AnalysisSkeleton_jobOptions.py and replace these lines
# The AOD input file
EventSelector.InputCollections = [
   "AOD.pool.root"
]
by these ones
# The AOD input file
include ("aodinput.py")
Remove thes lines
include( "AthenaPoolCnvSvc/ReadAthenaPool_jobOptions.py" )
EventSelector = Service( "EventSelector" )
Add the following lines at the top of the file
include( "AthenaPoolCnvSvc/ReadAthenaPool_jobOptions.py" )
include( "EventAthenaPool/EventAthenaPool_joboptions.py" )
EventSelector = Service( "EventSelector" )
EventSelector.BackNavigation = True
v. Now, run your analysis code by doing this
athena.py -b AnalysisSkeleton_jobOptions.py

vi. Open AnalysisSkeleton.root in ROOT, examine the di-jet invariant mass distribution and make sure that it is OK: a threshold around 360 GeV

Here is the solution to this exercise:

  /// the 2 leading jets - the collections are ordered
  if (jetTES->size() >= 2) {
     double pt1 = (*jetTES)[0]->pt();
     double pt2 = (*jetTES)[1]->pt();
     m_histJet1Pt->fill(pt1, m_eventWeight);
     m_histJet2Pt->fill(pt2, m_eventWeight);
     double mjj = ((*jetTES)[0]->hlv()+(*jetTES)[1]->hlv()).m();
     m_histMjj->fill(mjj, m_eventWeight);
  }
You may take a look at my version of AnalysisSkeleton.h/.cxx.
It is is ~ketevi/cmthome/9.0.2/PhysicsAnalysis/AnalysisCommon/UserAnalsyis/

Open AnalysisSkeleton.root in ROOT and fit a Gaussian to the di-jet mass distribution
root AnalysisSkeleton.root
.x AnalysisSkeleton.C
...
.q
Where AnalysisSkeleton.C is a ROOT macro to do the fit. My version can be found in ~ketevi/cmthome/9.0.2/PhysicsAnalysis/AnalysisCommon/UserAnalysis/.../run/

Exercise 3: The Analysis Examples

It is recommended that you check out the UserAnalysis package as you did above and develop your analysis code there. You can also run the reconstruction, ESD and AOD production in the UserAnalysis package - you do not need to check out any other packages. However, we produce some analysis example algorithms in the package AnalysisExamples. There, you will find information on the following:
	(a) Batch production large scale ESD and AOD
	(b) Merging AOD files
	(c) Documentation 
	(d) Single Particle Identification Example
	(e) Z -> 2 leptons example
	(f) Higgs -> 4 leptons example
	(g) ttbar example
	(h) How to use the analysis tools
	(i) How to do back navigation to from the AOD to the ESD
	(j) Access to tracks 
	(l) Interface to the interactive analysis
	(k) How to use ntuple and histograms in your analysis algorithms
These examples are intended to show you how to use the analysis tools: you should not copy them literaly. Rather, you should think about how to organize your analysis. For instance, the examples do show how to remove ambiguities and overlaps between electrons, taus, jets, etc.

Exercise 4: If the release does not work out of the box

Sometimes the release may not work "out of the box" and you may need to check out corrected package tags from the CVS repostory. But this, you will have to do from the CVS repository at CERN (not BNL). Indeed, the Release 9.0.2 does not work "out of the box" for the interaction analysis. Let us try to patch it:
echo $CVSROOT
You should see something like this on your screen:
/afs/usatlas.bnl.gov/software/cvs
This means that the CVS repository is set to BNL

cd
check if you have a directory called "bin" or not. If not, create:
mkdir bin
cd bin
cp ~ketevi/bin/atlas_cvs.csh .
edit atlas_cvs.csh. You should see this:

setenv CVSROOT ":kserver:atlas-sw.cern.ch:/atlascvs"
echo CVSROOT is $CVSROOT
echo Do a kdestroy first: "/usr/kerberos/bin/kdestroy"
echo authenticate with "/usr/bin/klog.krb -cell CERN.CH"

This script allows you to set the CVS ROOT to the CERN CVS repository so you can get the most recent versions of the needed packages to patch the release.

source atlas_cvs.csh
/usr/kerberos/bin/kdestroy
/usr/bin/klog.krb -cell CERN.CH

The last command will ask you for your CERN afs password. If you do not have an account at CERN, you are encouraged to get one. If you do have one, enter it and proceed as follows:

echo $CVSROOT
now you see this
:kserver:atlas-sw.cern.ch:/atlascvs

Change directory to your workarea for this tutorial. For me it is this:
cd ~ketevi/cmthome/9.0.2

The interactive analysis which we will do in Exercise 5 does not work in 9.0.2. We need to patch the release by checking out the fix from the repository at CERN:
cmt co -r PyKernel-00-00-02 Control/PyKernel
cmt co -r PyAnalysisExamples-00-00-11 PhysicsAnalysis/PyAnalysis/PyAnalysisExamples
cmt co -r PyParticleTools-00-00-08 PhysicsAnalysis/PyAnalysis/PyParticleTools
Now, we need to make sure that the above tags are used, not the onces that come with the release 9.0.2 itself.
Note: if you do not have CERN account, just copy the files from my area:
cp -R ~ketevi/cmthome/9.0.2/Control .
cd PhysicsAnalysis
cp -R ~ketevi/cmthome9.0.2/PhysicsAnalysis/PyAnalysis .
cd ..
cd PhysicsAnalysis/AnalysisCommon/UserAnalysis/.../cmt
Edit the file called "requirements" and above this line
use AthenaCommon                AthenaCommon-*                  Control

add these lines

use PyKernel                    PyKernel-*                      Control 
use PyAnalysisExamples          PyAnalysisExamples-*            PhysicsAnalysis/PyAnalysis
use PyParticleTools             PyParticleTools-*               PhysicsAnalysis/PyAnalysis
Save the "requirements" file and do this
cmt config

You should see stuff like this printed out, otherwise there a problem and you need to fix the "requirements" file before proceeding further

Removing all previous make fragments from cmt
Removing all previous make fragments from i686-rh73-gcc32-opt
Creating setup scripts.
Creating cleanup scripts.
run directory already installed

Now build the packages that we just checked out to use them on top of the release 9.0.2:

cmt broadcast gmake

Exercise 5: The interactive Analysis in Athena

cd ../run
get_files Interactive_topO.py

Interactive Analysis and AOD Browsing
initialize the application manager:
theApp.initialize()
create and fill a ROOT histogram on the fly:
elecPt = PyKernel.hist("ElectronContainer#ElectronCollection","$x.pt()",nEvent=5)
Plot this histogram:
elecPt.Draw()
Now you can fit this histogram or do any histogram operation on it in ROOT
Create, fill and plot a histogram
plot("ElectronContainer#ElectronCollection","$x.pt()",nEvent=5)

AOD browsing
include ("PyAnalysisExamples/PyPoolBrowser.py")

Edit AnalysisSkeleton_jobOptions.py and add this line at the bottom of it
include ("PyAnalysisCore/InitPyAnalysisCore.py")

An interactive session [pdf] or [ppt]

Now fit a Gaussian to your di-jet mass distribution.

Exercise 6: TrackParticle, Navigation, SymLink, CompositeParticle

At the end of this exercice, you should know how to access and do analysis with track parameters, how to do back navigation from AOD to ESD, how to use constituent navigation, how to do SymLink and how to manipulate composite objects.

Some Clarifications


i. The TrackParticle: It is designed to handle tracking and vertexing output. It is the interface between the user analysis domain and track and vertex reconstruction. Since the track object itself is not in the AOD, the TrackParticle, which is an AOD object, not only allows the user to have access to relevant tracking information, but it also has "links" the ESD tracks, which are therefore accessible, if needed, through back navigation. The TrackParticle class can be found in TrackParticle.

ii. Constituent Navigation: It is the ability to access information at any point in a relational tree. A jet, for example, may consists of calorimeter clusters as constituents, and each cluster having calorimeter cells as constiutents. Accessing information at any node in the relation tree behing the jet itself is the constituent navigation. The navigation tools are implemented in Navigation.

iii. Back Navigation: It is the ability to access an object which is not in the AOD but is in the ESD. An AOD, created from an ESD, "knows" the ESD from which it came. As a concrete example, the electron object is in the AOD but the e/gamma object from which the electron was created is not in the AOD, rather it is in the ESD. A user doing analysis on AOD may want to access the e/gamma object of a particular electron: this would be done through back navigation provided the ESD POOL are also available and accessible. To eanble back nagivation, you just have to add the following line to your job options, for example to AnalysisSkeleton_jobOptions.py:
# enable Back Navigation
EventSelector.BackNavigation = True

iv. SymLink: Suppose a user retrieves the AOD electron container, process each electron in some ways, does some pre-selection and record her own container of pre-selected electrons into the TDS. At a later stage in here analysis, she may want to retrieve her container of pre-selected electrons and do somthing with them. However, instead of retrieving her own pre-selected electron container as an ElectronContainer, she wants to retrieve it as a ParticleBaseContainer. After all, the Electon class derives from the ParticleBase which is the common implementation of all AOD particles. The ability to record a container of type Electron for example, and later retrieve it as a container of type ParticleBase for example is known as SymLink.

v. CompositeParticle: Its design is still evolving. The composite object, for example, the W as the composite of 2 jets, is itself a ParticleBase or an IParticle. But it is also a 4Momentum object. Further it needs to provide navigation to its constituents somehow. The current implementation of the CompositeParticle Class. is most likely to evolve while maintaining somehow the main ingredients of IParticle, 4Momentum and constituent navigation.

Exercice 6.1: Re-organize your AnalysisSkeleton Class


The di-jet mass reconstruction that you did in Exercice 1 needs to be re-packaged into a private method of AnalysisSkeleton. This, for clarity since we are going add more stuff for the exercices to follow

6.1.1 In AnalysisSkeleton.h add a private method: StatusCode dijet()
6.1.2 In AnalysisSkeleton.cxx, put all your implementation of the dijet mass reconstruction in the dijet() method
6.1.3 In the execute() method of AnalysisSkeleton.cxx, make a call to dijet():
  ...
  StatusCode sc = StatusCode::SUCCESS;
  
  /// dijet mass reconstruction
  sc = dijet();
  if (sc.isFailure()) {
    mLog << MSG::WARNING << "dijet mass reconstruction failed" << endreq;
    return StatusCode::SUCCESS;
  }
6.1.4 Recompile and run AnalysisSkeleton. It should work as before.

Exercice 6.2: Access to TrackParticle in the AOD


6.2.1 In AnalysisSkeleton, add another method: StatusCode trackParticleAndNavigation()
6.2.2 Make a call to trackParticleAndNavigation() in the execute() method as you did for the dijet() method above
6.2.3 Add a histogram to plot the momentum of the track
6.2.4 In the method trackParticleAndNavigation(), retrieve the ElectronContainer from the TDS.
6.2.5 Iterate over the ElectonContainer, for each Electron access its TrackParticle and histogram the momentum of the track
  Retrieve the ElectronContainer elecTDS
  ElectronContainer::const_iterator elecItr  = elecTDS->begin();
  ElectronContainer::const_iterator elecItrE = elecTDS->end();
  for (; elecItr != elecItrE; ++elecItrE)
    {
      /// access to the Electron's TrackParticle
      const Rec::TrackParticle *trackParticle = (*elecItr)->track();
      if (track != 0) {
         double trackP = track->p();
         fill the histogram
      } 
    } 

Exercice 6.3: Back Navigation to ESD


In the same iteration loop, we will try to access calorimeter cluster of the Electron and histogram the cluster energy
6.3.1 Add a histogram for the calorimeter cluster energy
6.3.2 In the same loop above for the TrackParticle, ask the Electron for its e/gamma object by back navigating to the ESD since the e/gamma object is not in the AOD
6.3.3 From the e/gamma, get the calorimeter cluster and histogram the cluster energy
6.3.4 When you finish doing all this, the trackParticleAndNavigation() method should look, a sort of, like this
  Retrieve the ElectronContainer elecTDS
  ElectronContainer::const_iterator elecItr  = elecTDS->begin();
  ElectronContainer::const_iterator elecItrE = elecTDS->end();
  for (; elecItr != elecItrE; ++elecItrE)
    {
      /// access to the Electron's TrackParticle
      const Rec::TrackParticle *trackParticle = (*itE)->track();
      if (track != 0) { 
         double trackP = track->p();
         fill the histogram
      } 

      /// back navigation to ESD to access Electron's egamma object
      const egamma *eg = (*elecItr)->eg();
      if (eg) { 
          const LArCluster *cluster = eg->get_Cluster();
          if(cluster) { 
            double et = (clus)->et();
            double eta = (clus)->eta();
            double e = et*cosh(eta);
	    histogram the energy
          } 
       } 
    }
6.3.5 Compile the code and resolve any compilation problem: proceed as follow
6.3.5.1 Change directory to your "cmt" directory
6.3.5.2 edit the "requirements" file
6.3.5.3 add the following lines to the requirements file:
use Particle            Particle-01-*      Reconstruction
use egammaEvent         egammaEvent-01-*   Reconstruction
just below this line
use ParticleEvent ParticleEvent-00-* PhysicsAnalysis/AnalysisCommon
6.3.5.4 cmt config
6.3.5.5 gmake
We need the above 2 lines for the TrackParticle and the egamma object respectively.

Exercice 6.4: Constituent Navigation


6.4.0 In AnalysisSkeleton.cxx, #include this line, needed for the navigation tools
#include "Navigation/NavigationToken.h"
Then, in your requirements file, include the following line
use Navigation    Navigation-00-*   Control
before the "MissingEtEvent" line.
6.4.1 Go back your dijet() method and add an iteration loop over the ParticleJetContainer, if you do not already have it. For each ParticleJet, you will navigate to the cell node in the jet relational tree, and add the cell transverse energies and plot it.
6.4.2 Add a histogram from the jet transverse energy
6.4.3 clarification: To navigate to constituent, you have to formulate a navigation query. The NavigationToken class implements navigation queries for clients: the basic idea is to formulate a query of any specific object type in the relational tree.
6.4.4 Now for each ParticleJet, query for the cells in the jet relational tree, then add up the cell energies and histogram it. The snippet of code in the wjj() method should look like this

  ...
  /// iterators over the container
ParticleJetContainer::const_iterator jetItr = jetTES->begin(); ParticleJetContainer::const_iterator jetItrE = jetTES->end(); for (; jetItr != jetItrE; ++jetItr) { ... NavigationToken cellToken; (*jetItr)->fillToken(cellToken,double(1.)); NavigationToken::const_iterator c = cellToken.begin(); NavigationToken::const_iterator cend = cellToken.end(); mLog << MSG::DEBUG << "# cells found " << cellToken.size() << endreq; double etSum = 0; for(; c != cend; ++c) { const CaloCell* thisCell = *c; double weight = cellToken.getParameter(thisCell); double et = weight * thisCell->et(); etSum += et; } now put the etSum into the histogram }
Note that we have done constituent navigation from the ParticleJet to the cells. But since the cell are not the AOD, you have also done back navigation to the ESD to access the cells.

Exercice 6.5: SymLink and CompositeParticle


6.5.1 Add another method to AnalysisSkeleton, StatusCode symLinkExample(). In the wjj() method, you retrieved the container of particle jets as ParticleJetContainer. Now, in symLinkExample(), you will retrieve the same container as ParticleBaseContainer. Sometimes, you may want to do this because you want to use common tools which to do not operate on ParticleJet, but rather on ParticleBase.

6.5.2 Add another histogram for the transverse momentum of jet from the ParticleBaseContainer. Iterate over this container and fill the histogram. Later on when you run your code, make sure that this histogram is identical to the one you created in the wjj() method for the jet transverse momentum in Exercise 1:
  const ParticleBaseContainer* particleBaseTES=0;
  sc=m_storeGate->retrieve( particleBaseTES, m_jetContainerName);
  if( sc.isFailure()  ||  !jetTES ) {
     mLog << MSG::WARNING
          << "No AOD jet container found in TDS as symLink"
          << endreq;
     return StatusCode::SUCCESS;
  }
  mLog << MSG::DEBUG << "ParticleBaseContainer successfully retrieved as symLink" << endreq;

  /// iterators over the ParticleBase container
  ParticleBaseContainer::const_iterator partItr  = particleBaseTES->begin();
  ParticleBaseContainer::const_iterator partItrE = particleBaseTES->end();

  for (; partItr != partItrE; ++partItr) {
	now fill the histogram
  }
  ...

The symLink feature should not be abused. It is recommended to use symLink only if you absolutely have to. Do not do none sensical stuff, for example trying to retrieve an ElectronContainer as symLink to a ParticleJetContainer.

6.5.3 Create the dijet candidates as composite particles. Redo the analysis combination plus selection on the ParticleBaseContainer --- the selection is that the transverse momentum of the jet is greater than 20 GeV as in dijet() method. For each selected jet-jet pair, create the jet-jet pair as a composite particle.
  /// m-jj variant mass with a selection on the jet transverse momenta
  AnalysisUtils::Combination combination(particleBaseTES,2);
  std::vector(const ParticleBaseContainer::base_value_type*) jetPair;
  while (combination.goodOnes(this, jetPair, selectJet)) {
      CompositeParticle(particleBaseTES) dijets;
      dijets.add(particleBaseTES,jetPair[0],jetPair[1]);
      double Wmass = dijets.m();
      now histogram the mass 
   }

Exercice 5.6: Test your Code


6.6.1 Compile and build your code. Resolve any compilation errors
6.6.2 We want enable back navigation first:
6.6.3 cd to your "run" directory
6.6.4 Enable back navigation by adding this line to your job options

EventSelector.BackNavigation = True

6.6.5 Run your code. Now, you have the basic knowledge necessary to start doing analysis in ATHENA. If you do not success in this exercise, take a loop at my version on acas: ~ketevi/cmthome/9.0.2/PhysicsAnalysis/AnalysisCommon/UserAnalysis/.