The TauAnalysis Subsystem

Analysis workflow

The full analysis workflow supported by the TauAnalysis subsystem is displayed in the figure below.

The full analysis workflow proceeds in three stages, implemented in the top-level configuration files:

• run.._cfg.py
• harvest.._cfg.py
• make..Plots_cfg.py

In the filenames given above and the following instructions, the two dots ".." are placeholders for one of the analysis channels implemented in the TauAnalysis subsystem so far, i.e. replace ".." by either:

• ZtoMuTau
• ZtoElecTau
• ZtoElecMu
• WtoTauNu

In the first stage, a TauAnalysis specific PATTuple is produced from either AOD or RECO input.

Note: When using the TauAnalysis software with CMSSW_2_2_X RECO input is required.

This PATTuple can optionally written persistently into a .root file. By default, the PATTuple gets recreated dynamically, right before the histograms are filled. (The recreation of PATTuples has the advantage of requiring less disk space; it make the TauAnalysis software also easier to changes on the PAT level, but has the disadvantage, of course, that frequent recreation of the PATTuple takes time.) The histograms are first booked, filled and then saved into a .root file at the end of the first stage. This first stage is implemented in the top-level configuration file run.._cfg.py , located in the TauAnalysis/Configuration package.

The second stage is implemented in the configuration file harvest_cfg.py , located in the same package. Its purpose is to add for all the different signal and background processes (and in the future also for the data ) the histograms created in the first stage.

The histograms representing the contributions of different signal and background processes are finally plotted in various graphics file formats in the third stage. The third stage is implemented in the configuration file make..Plots_cfg.py , again located in the TauAnalysis/Configuration package.

Preceding these three analysis stages, an additional skimming stage is foreseen in the default workflow of the TauAnalysis software. The purpose of the Skimming stage is to reduce the number of events contained in the primary (unselected) data samples to a level (~100k events) which allows the skimmed AOD/RECO samples to be stored locally on CASTOR at CERN. The idea is that only for the initial skimming stage access to the Grid is required. The cmsRun run.._cfg.py and cmsRun harvest.._cfg.py jobs of the first and second analysis stages can then be submitted to the local CERN batch system, while the cmsRun make..Plots_cfg.py command of the third analysis stage can be executed interactively on a single lxplus node. More details on the skimming of signal and background samples of different analysis channels are given in section Skimming below.

In the design of the TauAnalysis software, care has been taken that the histogram summation and plotting tasks by default performed using functionality provided by the TauAnalysis software can also be performed by other means, e.g.:

• FWLite
• TTree::Draw in bare ROOT

PATTuple production

The aim of the TauAnalysis specific PATTuple is to provide "out-of-the-box":

• collections of PAT objects produced by the "official" PAT production sequence, but customized configuration parameters
• collections of additional objects specific to the TauAnalysis software

The production of the TauAnalysis specific PATTuples is defined in the configuration file TauAnalysis/Configuration/python/producePatTuple_cff.py and configuration files included therein.

The production of the TauAnalysis specific PATTuple proceeds in six stages:

In the first stage, producePrePat, isolation and particle id. variables are (re)computed on AOD/RECO level:

• particle flow based isolation variables are computed for reco::Electrons, reco::Muons and reco::PFTaus
• the reco::Track, ECAL recHit and HCAL tower based isolation variables are recomputed for reco::Electrons and reco::Muons in an enlarged, non-standard, isolation cone of radius dR = 1.0 (see the following links for a description of the electron and muon isolation variables)
• electron id. flags are recomputed (see the following link for a description of the (cut-based) electron id.)
• reco::PFTau objects are produced and tau id. discriminators are recomputed using the latest tau id. tags, including the "Tau Neural Classifier" (TaNC) based discriminators (see the following links for a SWGuidePFTauID[general description of the tau id. procedure]] and a WorkBookPFTauTagging#PFTau_Discriminants[list of tau id. discriminators]])

Based on the AOD/RECO objects (re)produced in the first stage, collections of PAT objects (pat::Electrons, pat::Muons, pat::Taus, pat::Jets and pat::MET) are produced in the patDefaultSequence stage. The TauAnalysis specific modifications to the "official" PAT production sequence are:

• pat::Electron (pat::Muon) isolation computed in an enlarged, non-standard, isolation cone of radius dR = 0.6 (dR = 1.0)
• pat::Electron id. flags taken from recomputed AOD/RECO input
• tau-jet corrections to reco::CaloMET applied
• HLT trigger bit matching for electrons and muons

In the subsequent producePostPat stage, additional collections of objects representing generator level information useful for tau analyses:

• genDecayProductsFromZs
• genPhaseSpaceEventInfo
• genMetWithMu

The collections of PAT objects produced in the second stage are then subject to acceptance, particle id. and isolation cuts in the fourth, produceLayer1SelLeptons plus selectLayer1Jets, stage.

Finally, collections of "di-tau" objects representing combinations of e+τ-jet, μ+τ-jet, e+μ and τ-jet pairs are produced in the fifth and sixth stage, produceDiTauPairsAllKinds and selectDiTauPairsAllKinds, respectively.

If you are interested, you can find more details about the selection of pat::Electron, pat::Muon, pat::Tau and pat::Jet objects and of the di-tau objects in the section How to implement a new Analysis channel.

NOTE: The latest tag b4_2_x_2011Aug02 of the TauAnalysis software compatible with CMSSW_4_2_x depends on changes in the pat::Tau DataFormat which break backwards compatibility with PAT-tuples produces with "plain" CMSSW_4_2_x --> Please do not update to tags b4_2_x_2011Aug02 or later if you want to keep using existing PAT-tuples !!

The CMSSW_4_2_X compatible version of the TauAnalysis software is based on CMSSW_4_2_4_patch1.

First you need to create a CMSSW_4_2_4_patch1 working area:

setenv SCRAM_ARCH slc5_amd64_gcc434
scram project CMSSW CMSSW_4_2_4_patch1
cd CMSSW_4_2_4_patch1/src
cmsenv

Once you have created the working area, you need to checkout from CVS the following packages (you can just copy and paste into your terminal):

echo "checking-out RecoTauTag packages"
cvs co -r 1.49 RecoTauTag/tau_tags.txt
addpkg -f RecoTauTag/tau_tags.txt

echo "checking-out PAT packages"
cvs co -r CMSSW_4_2_4_patch1 PhysicsTools/MVAComputer    
cvs up -r 1.3 PhysicsTools/MVAComputer/interface/MVAModuleHelper.h
cvs co -r V08-06-36 PhysicsTools/PatAlgos
cvs up -r 1.47 PhysicsTools/PatAlgos/python/tools/tauTools.py
cvs up -r 1.5 PhysicsTools/PatAlgos/plugins/PATSingleVertexSelector.cc
cvs up -r 1.5 PhysicsTools/PatAlgos/plugins/PATSingleVertexSelector.h
cvs co -r V08-03-12 PhysicsTools/Utilities
cvs co -r CMSSW_4_2_4_patch1 DataFormats/PatCandidates
cvs up -r 1.32 DataFormats/PatCandidates/interface/Tau.h
cvs up -r 1.3 DataFormats/PatCandidates/interface/TauCaloSpecific.h
cvs up -r 1.7 DataFormats/PatCandidates/interface/TauPFSpecific.h
cvs up -r 1.21 DataFormats/PatCandidates/src/Tau.cc
cvs up -r 1.3 DataFormats/PatCandidates/src/TauCaloSpecific.cc
cvs up -r 1.6 DataFormats/PatCandidates/src/TauPFSpecific.cc
cvs co -r 1.1 DataFormats/PatCandidates/interface/TauJetCorrFactors.h
cvs co -r 1.1 DataFormats/PatCandidates/src/TauJetCorrFactors.cc
cvs up -r 1.60 DataFormats/PatCandidates/src/classes.h
cvs up -r 1.70 DataFormats/PatCandidates/src/classes_def.xml

echo "checking-out TauAnalysis packages and other packages required by TauAnalysis" 
cvs co -r V00-01-01 CommonTools/CandUtils
cvs co -r cbern_isolation_29Sept11_d CommonTools/ParticleFlow
cvs up -r 1.1.2.2 CommonTools/ParticleFlow/python/pfPileUpCandidates_cff.py
cvs up -r 1.2 CommonTools/ParticleFlow/python/pfPileUp_cfi.py
cvs up -r 1.2 CommonTools/ParticleFlow/python/TopProjectors/pfNoPileUp_cfi.py
cvs up -r 1.2 CommonTools/ParticleFlow/python/Isolation/pfMuonIsolationFromDeposits_cff.py
cvs up -r 1.2 CommonTools/ParticleFlow/python/ParticleSelectors/pfCandsForIsolation_cff.py
cvs co -r V00-00-01 HiggsAnalysis/HiggsToTauTau
cvs co -r V00-06-08 MuonAnalysis/MomentumScaleCalibration     
cvs co -r CMSSW_4_2_4_patch1 PhysicsTools/CandUtils
cvs up -r 1.3 PhysicsTools/CandUtils/src/EventShapeVariables.cc
cvs co -r V04-05-07 JetMETCorrections/Type1MET 
cvs co -r b4_2_X_cvMEtCorr_02Feb2012 PhysicsTools/PatUtils 
cvs co -r V02-03-00 JetMETCorrections/Algorithms                     
rm JetMETCorrections/Algorithms/interface/L1JPTOffsetCorrector.h
rm JetMETCorrections/Algorithms/src/L1JPTOffsetCorrector.cc
cvs co -r V03-01-00 JetMETCorrections/Objects        
cvs co -r CMSSW_4_2_4_patch1 DataFormats/METReco
cvs up -r 1.28 DataFormats/METReco/src/classes.h
cvs up -r 1.25 DataFormats/METReco/src/classes_def.xml
cvs co -r CMSSW_4_2_4_patch1 RecoMET/METAlgorithms
cvs up -r 1.2 RecoMET/METAlgorithms/interface/SigInputObj.h
cvs co -r cbern_isolation_29Sept11_b RecoMuon/MuonIsolation
cp /afs/cern.ch/user/v/veelken/public/MuPFIsoHelper.cc RecoMuon/MuonIsolation/src
cvs co -r CMSSW_4_2_4_patch1 DataFormats/MuonReco
cvs up -r 1.1 DataFormats/MuonReco/interface/MuonPFIsolation.h
cvs co -r b4_2_x_2012May04 TauAnalysis
cvs co -r b4_2_x_2012May04 AnalysisDataFormats/TauAnalysis

Then, compile and link with:

scramv1 b -r -j 4

The CMSSW_5_2_X compatible version of the TauAnalysis software is based on CMSSW_5_2_3_patch3.

First you need to create a CMSSW_5_2_3_patch3 working area:

setenv SCRAM_ARCH slc5_amd64_gcc462
scram project CMSSW CMSSW_5_2_3_patch3
cd CMSSW_5_2_3_patch3/src
cmsenv

Once you have created the working area, you need to checkout from CVS the following packages (you can just copy and paste into your terminal):

echo "checking-out TauAnalysis packages and other packages required by TauAnalysis" 
cvs co -r V01-04-14 RecoTauTag/RecoTau
cvs co -r V01-04-01 RecoTauTag/Configuration
cvs co -r V00-00-01 HiggsAnalysis/HiggsToTauTau
cvs co -r edm-30March2012 HiggsAnalysis/HiggsToWW2Leptons
cvs co -r V02-01-00 HiggsAnalysis/CombinedLimit
cvs co -r CMSSW_5_2_3_patch3 PhysicsTools/CandUtils
cvs up -r 1.3 PhysicsTools/CandUtils/src/EventShapeVariables.cc
cvs co -r V04-06-05 JetMETCorrections/Type1MET
cvs co -r b5_2_X_cvMEtCorr_2012May04 RecoMET/METAlgorithms 
cvs co -r b5_2_X_cvMEtCorr_2012May04 RecoMET/METProducers
cvs co -r CMSSW_5_2_3_patch3 PhysicsTools/PatAlgos
cvs up -r 1.53 PhysicsTools/PatAlgos/python/tools/tauTools.py
cvs co -r CMSSW_5_2_3_patch3 PhysicsTools/SelectorUtils
cvs up -r 1.23 PhysicsTools/SelectorUtils/interface/PFJetIDSelectionFunctor.h
cvs co -r V00-04-01 CondFormats/EgammaObjects 
cvs co -r V00-00-09 -d CMGTools/External UserCode/CMG/CMGTools/External
cvs co -r V00-01root -d pharris/MVAMet UserCode/pharris/MVAMet
cvs up -r V00-02 -d pharris/MVAMet UserCode/pharris/MVAMet/data
cvs co -r b5_2_X_cvMEtCorr_2012May25 PhysicsTools/PatUtils 
cvs co -r V00-00-08 CommonTools/RecoUtils
cvs co -r V00-06-08 MuonAnalysis/MomentumScaleCalibration
cvs co -r b5_2_x_2012May25 TauAnalysis
cvs co -r b5_2_x_2012May08 AnalysisDataFormats/TauAnalysis

Then, compile and link with:

scramv1 b -r -j 4

The CMSSW_5_3_X compatible version of the TauAnalysis software is based on CMSSW_5_3_3_patch2.

First you need to create a CMSSW_5_3_3_patch2 working area:

setenv SCRAM_ARCH slc5_amd64_gcc462
scram project CMSSW CMSSW_5_3_3_patch2
cd CMSSW_5_3_3_patch2/src
cmsenv

Once you have created the working area, you need to checkout from CVS the following packages (you can just copy and paste into your terminal):

echo "checking-out TauAnalysis packages and other packages required by TauAnalysis" 
cvs co -r V01-04-17 RecoTauTag
cvs co -r V01-04-03 RecoTauTag/Configuration
cvs co -r V00-04-01 CondFormats/EgammaObjects
addpkg PhysicsTools/PatAlgos 
cvs up -r 1.57 PhysicsTools/PatAlgos/python/tools/tauTools.py
cvs up -r 1.6 PhysicsTools/PatAlgos/plugins/PATMHTProducer.h
addpkg PhysicsTools/CandUtils
cvs up -r 1.3 PhysicsTools/CandUtils/src/EventShapeVariables.cc
cvs co -r V00-03-32 PhysicsTools/SelectorUtils
cvs co -r V04-06-05 JetMETCorrections/Type1MET
cvs co -r 1.1 JetMETCorrections/Type1MET/interface/SysShiftMETcorrExtractor.h
cvs co -r 1.1 JetMETCorrections/Type1MET/src/SysShiftMETcorrExtractor.cc
cvs co -r V00-00-01 JetMETCorrections/METPUSubtraction
cvs co -r V00-00-13 CommonTools/RecoUtils
cvs co -r CMSSW_5_3_3_patch2 DataFormats/ParticleFlowCandidate
cvs up -r 1.15 DataFormats/ParticleFlowCandidate/src/classes.h
cvs up -r 1.23 DataFormats/ParticleFlowCandidate/src/classes_def.xml
cvs co -r CMSSW_5_3_3_patch2 DataFormats/StdDictionaries
cvs up -r 1.28 DataFormats/StdDictionaries/src/classes.h
cvs up -r 1.29 DataFormats/StdDictionaries/src/classes_def.xml
cvs co -r CMSSW_5_3_3_patch2 DataFormats/TrackReco
cvs up -r 1.44 DataFormats/TrackReco/src/classes.h
cvs up -r 1.53 DataFormats/TrackReco/src/classes_def.xml
cvs co -r CMSSW_5_3_3_patch2 DataFormats/VertexReco
cvs up -r 1.19 DataFormats/VertexReco/src/classes_def.xml
cvs up -r 1.16 DataFormats/VertexReco/src/classes.h
cvs co -r  V03-09-26 PhysicsTools/PatUtils
cvs up -r 1.8 PhysicsTools/PatUtils/python/patPFMETCorrections_cff.py
cvs co -r V00-00-16 -d EGamma/EGammaAnalysisTools UserCode/EGamma/EGammaAnalysisTools
cvs co -r  V03-03-16 DataFormats/METReco
cvs up -r 1.2 DataFormats/METReco/interface/SigInputObj.h
cvs co -r V00-02-09 -d CMGTools/External UserCode/CMG/CMGTools/External
cvs co -r V00-02 -d  pharris/MVAMet UserCode/pharris/MVAMet
cvs co -r ph_52X_MVAMet_v3 RecoMET/METAlgorithms 
rm RecoMET/METAlgorithms/interface/SigInputObj.h
cvs up -r 1.6 RecoMET/METAlgorithms/interface/SignAlgoResolutions.h
cvs up -r 1.3 RecoMET/METAlgorithms/interface/significanceAlgo.h
cvs co -r ph_52X_MVAMet_v3 RecoMET/METProducers
cp /afs/cern.ch/user/p/pharris/public/SealModule.cc RecoMET/METProducers/src/
cvs co -r V00-02-06 HiggsAnalysis/HiggsToTauTau
cvs co -r V02-01-00 HiggsAnalysis/CombinedLimit
cvs co -r b5_3_x_2012Sep11 TauAnalysis
cvs co -r b5_3_x_2012Sep11 AnalysisDataFormats/TauAnalysis

Then, compile and link with:

scramv1 b -r -j 4

Z→μ+τ-jet analysis

In order to run the Z→μ+τ-jet analysis locally on lxplus, execute the following:

cd TauAnalysis/Configuration/test
cmsRun runZtoMuTau_cfg.py

Skimmed signal and background samples for the Z→e+μ analysis are stored on CASTOR at CERN. In order to submit cmsRun jobs for the samples stored on CASTOR, you need to be logged-in on one of the lxplus nodes at CERN. Then execute:

cd TauAnalysis/Configuration/test
cmsenv
sh submitZtoMuTau.csh

This will submit the cmsRun jobs running over the skimmed signal and background samples to the CERN batch system.

You can check the status of the job excution via:

bjobs

For further batch commands, please see https://twiki.cern.ch/twiki/bin/view/CMS/CMSUKCMSSWBatch

The jobs should finish within 3-4 hours.

Once the bjobs command does not list any pending or running cmsRun jobs anymore, you can to produce plots. To do it execute:

cd TauAnalysis/Configuration/test
limit vmem unlim
cmsRun makeZtoMuTauPlots_cfg.py

(The limit vmem unlim increases the amount of memory available to cmsRun.)

After about 1 minute, you will see that there are quite a few new PNG graphics files in the directory TauAnalysis/Configuration/test/plots. You can view the graphics files e.g. with gimp by executing:

gimp ./plots/plotZtoMuTau_finalSamplePlots_muon_Pt.png

Note that by default, factorization of the muon isolation efficiency is used for the InclusivePPmuX and PPmuXptGt20 QCD Monte Carlo samples is used, in order to increase the effective event statistics (factorization means that only loose isolation criteria are applied during the event selection and that instead, the events are scaled by the ratio = (number of events passing tight muon isolation)/(number of events passing loose isolation).

In order to disable factorization of the muon isolation efficiency for the InclusivePPmuX and PPmuXptGt20 QCD Monte Carlo samples, change:

factorizationMode_InclusivePPmuX="factorized"
factorizationMode_PPmuXptGt20="factorized"

factorizationMode_InclusivePPmuX="noFactorization"
factorizationMode_PPmuXptGt20="noFactorization"

from TauAnalysis.Configuration.factorizationTools import enableFactorization_makeZtoMuTauPlots
enableFactorization_makeZtoMuTauPlots(process)

Z→e+τ-jet analysis

In order to run the Z→e+τ-jet analysis, do:

cd TauAnalysis/Configuration/test
cmsenv
sh submitZtoElecTau.csh

This will submit cmsRun jobs running over the skimmed signal and background samples to the CERN batch system. The output files will contain histograms of different variables at different points in the event selection sequence. One version of these files is stored at /castor/cern.ch/user/j/jkolb/elecTauAnalysis/data/.

WARNING: If you run all the jobs specified in the submitZtoElecTau.csh file, the output ROOT files will eventually consume more than 500MB in your local AFS directory.

Once all the histogram output files are produced and stored (e.g. on CASTOR), specify the path to the files in Configuration/python/plotZtoElecTau_processes_cfi.py (if necessary), and do:

cd TauAnalysis/Configuration/test
limit vmem unlim
cmsRun makeZtoElecTauPlots_cfg.py

Plots can be found in the Configuration/test/plots directory. Note that only the Ztautau, Zee, and Z/W+jets samples are currently working for plotting.

Z →e+μ analysis

The Z→e+μ analysis has been updated to run over the skimmed signal and background samples stored on CASTOR at CERN. In order to submit the cmsRun jobs, you need to be logged-in on one of the lxplus nodes at CERN. Then do:

cd TauAnalysis/Configuration/test
cmsenv
sh submitZtoElecMu.csh

This will submit the cmsRun jobs running over the skimmed signal and background samples to the CERN batch system.

You can check the status of the job excution via:

bjobs

For further batch commands, please see https://twiki.cern.ch/twiki/bin/view/CMS/CMSUKCMSSWBatch

The jobs should finish within 3-4 hours.

Once the bjobs command does not list any pending or running cmsRun jobs anymore, you can proceed to produce the plots. Now do:

cd TauAnalysis/Configuration/test
limit vmem unlim
cmsRun makeZtoElecMuPlots_cfg.py

(The limit vmem unlim increases the amount of memory available to cmsRun.)

After about 1 minute, you will see that there are quite a few new PNG graphics files in the TauAnalysis/Configuration/test/plots directory. You can view the graphics files e.g. with gimp by executing:

gimp ./plots/plotZtoElecMu_finalSamplePlots_electron_Pt.png

Note that at the moment, the Z→μ+τ-jet, Z→e+τ-jet and Z→e+μ analyses depend on electron and muon isolation computed for larger, non-standard, isolation cones. As a consequence, the runZtoMuTau_cfg.py and runZtoElecTau_cfg.py configuration files include the reconstruction of PAT objects for these enlarged isolation cones.

CVS

Impatient people who do not know anything about CVS can have a look at this Quick and Dirty Guide to CVS, which will teach you the most basic functionalities of CVS.

However, the best source of information is the CVS Book. It will not take so much time to read and after this, you will finally understand what CVS is doing, and what you are doing with CVS :), even when branches are involved.

Golden rule: before committing, please follow this procedure:

1. update
2. in case some files were modified by the update, compile and test and move to stage 3, otherwise commit !
3. update again, just in case somebody committed something while you were at stage 2. go back to stage 2.

Important remark:

Do not copy files over from a given CMSSW local area (let's call it A) into another one (let's call it B). If you want to import your modifications from A to B, in order for example to move to a more recent release of CMSSW, please do the following:

• commit your modifications in release A
• update your modifications in release B

CMS coding rules

Please have a look at the CMSCodingRules.

In particular, our code will stay easy to read and to understand provided everybody follows these simple guidelines:

• Add some comments to explain what you're doing
• Follow the naming scheme in place in the various packages. For example:
  • functions and data members start with lower case.
  • the name of the accessors is the same as the name of the data member they access.
• Indent your code.
  • If you're using emacs, the code should get auto-indented while you type. It is also possible to run auto-identation by typing Alt-x indent-region (keep alt pressed, type x, release alt and x, type indent-region).
  • If you don't use emacs, you can use this little script to indent your files.