Documentation for Tag And Probe Muon Efficiencies. ( 2012 - 53X reReco)

.

Introduction

Meetings and mailing lists

Hypernews: hn-cms-muon@cern.ch

The Muon POG meetings ????

Twiki pages

An axample for "my twiki" : https://twiki.cern.ch/twiki/bin/viewauth/CMS/ElectronTagAndProbe

Base Line Muon Selection : Silvia July 2013 : https://twiki.cern.ch/twiki/bin/view/CMSPublic/SWGuideMuonId

Reference muon momentum scale and resolution; Giovanni Abbiendi,June 2013 :https://twiki.cern.ch/twiki/bin/view/CMS/MuonReferenceResolution

Tag and probe

To start with ; 24-May-2012, DavidFutyan https://twiki.cern.ch/twiki/bin/view/CMS/TagAndProbe?sortcol=1;table=1;up=0#sorted_table

Muon Tag and probe

Documentation for TagProbeFitTreeProducer April 2011, G.Petrucciani: https://twiki.cern.ch/twiki/bin/view/CMSPublic/SWGuideTagProbeFitTreeProducer

Documentation for TagProbeFitTreeAnalyzer Dec. 2010, G. Petrucciani: https://twiki.cern.ch/twiki/bin/view/CMSPublic/SWGuideTagProbeFitTreeAnalyzer

MuonID 17-Jul-2013, SilviaGoyLopez https://twiki.cern.ch/twiki/bin/view/CMSPublic/SWGuideMuonId

Muon T&P for Higgs Analyses June 2013, PietVerwilligen: https://twiki.cern.ch/twiki/bin/view/CMS/TagAndProbeForHIG

Hypernews

See also this hypernews thread ???

Presentations, Notes ...

Tagand Probe Turorial CMSSW312 Hunt August 2009: http://indico.cern.ch/getFile.py/access?contribId=88&resId=0&materialId=slides&confId=58768

Muon Pog: Tag and Probe Tutorial: June 2010 : https://indico.cern.ch/conferenceDisplay.py?confId=96277

2012 : Previous to : 53X reReco

Muon Efficiencies 2012 in 53X : Eduardo and Isabel October 2012: https://indico.cern.ch/getFile.py/access?contribId=3&resId=0&materialId=slides&confId=214870

ID and ISO efficiencies and scale factors for ABCD 2012 dataset : Feb 2013 : https://indico.cern.ch/contributionDisplay.py?contribId=2&confId=233592

2012 : 53X reReco

Muon ID and Iso efficiencies (2012 53x rereco) (partII) : Isabel and Carmen June 2013: https://indico.cern.ch/getFile.py/access?contribId=1&resId=0&materialId=slides&confId=257630

Software

The Code

??? Use pile-up reweighting for Monte Carlo (MC) as described here.
3-D pile-up reweighting is not needed in 2012. ???

The Code : more.

ExtractFitPlots : Huges Brun : https://github.com/HuguesBrun/ExtractFitPlots

The Imput

2012 full pp data V5 TagAndProbeForHig

The scripts

Results

2012 reReco

Reference muon id and isolation efficiencies : Silvia July 2013 https://twiki.cern.ch/twiki/bin/view/CMS/MuonReferenceEffs

FitPlots Id and Iso, usual functions : Isabel June 2013: https://twiki.cern.ch/twiki/bin/view/CMS/Muon_Id_and_Iso_Efficiencies_2012_develop

Group web page for storing fits > https://cms-muonpog.web.cern.ch/cms-muonpog/

2012 previous results

Summary table

parameter	type	req.	description
tagProbePairs	InputTag	yes	input collection of (tag+probe pairs)
arbitration	string	yes	how to handle tags with more than one probe supported values are None, OneProbe, BestMass, Random2, OnePair, NonDuplicate
massForArbitration	double	-	used if arbitration is BestMass
variables	PSet	yes	variables of the probe to be included in the dataset
flags	PSet	yes	criterias that define passing probes
<xyz>Variables <xyz>Flags	PSet	no	Same as variables and flags, but with information on the tag (<xyz> = tag), mc object matched to the probe (mc), or tag & probe pair (pair). The branche names will be prefixed by <xyz>_. The parameters are optional, but must always come in pairs: e.g. if you set the tagVariables you must also set the tagFlags (even to an empty PSet).
isMC	bool	yes	true on mc, false on data
tagMatches probeMatches	InputTag	if isMC	associations from tags and probes to mc truth needed if isMC is true
motherPdgId	int32 or vint32	if isMC	list of PDG Ids for the mothers of the tag & probe pairs.
makeMCUnbiasTree	bool	if isMC	produce also a TTree with one entry per true probe, without looking if the tag is reconstructed and selected
checkMotherInUnbiasEff	bool	if makeMCUnbiasTree	If set, a "true probe" for the above tree must be matched to a particle coming from one of the resonances specified through the parameter moderPdgId. if not set, any truth-matched probe is used in the tree.
allProbes	InputTag	if makeMCUnbiasTree	the collection of all the probes, to make the unbiased efficiency
fillTagTree	bool	no	default is false; if present and set to true, the module will fill a separate tree tag_tree with the same variables of the probes, but applied to tags.
ignoreExceptions	bool	no	default is false; if present and set to true, exceptions thrown when evaluating the tree variables are silently ignored.
addRunLumiInfo	bool	no	default is false; if present and set to true, two branches run and lumi will be added to the tree, containing the run and lumisection number.
addEventVariablesInfo	bool	no	if set to true, some per-event variables will be added to the tree (see below for description)
eventWeight	double or InputTag	no	Save a weight variable in the tree, either a constant in cfg (if the parameter is a cms.double) or a double stored the edm::Event (if the parameter is a cms.InputTag)

Input (tag+probe) pairs

Parameter tagProbePairs
In order to run the TagProbeFitTreeProducer you need to provide a list of pairs, as a reco::ShallowCloneCompositeCandidates that have as daughters the tag and the probe (in this order). This is specified through the parameter tagProbePairs of type cms.InputTag

This is usually accomplished with this a standard CMSSW module, CandViewShallowCloneCombiner, as in this example

process.tagProbes = cms.EDProducer("CandViewShallowCloneCombiner",
    decay = cms.string("tagMuons@+ trkProbes@-"), # charge coniugate states are implied; 'tagMuons' and 'trkProbes' should be collections of Candidates
    cut   = cms.string("2.5 < mass < 3.8"),
)

Parameters arbitration, massForArbitration
If there is more than one (tag+probe) pair for a given tag, the code module can be configured to handle the arbitration.

The five supported settings for the arbitration parameter are:

• "None": don't perform any arbitration, use all (tag+probe) pairs.
• "OneProbe": keep only tags that are matched to a single probe.
• "BestMass": use the (tag+probe) pair that has the invariant mass nearest to the value of the massForArbitration parameter.
• "Random2" : if there are exactly two (tag+probe) sharing the same tag, choose one randomly. If there are more than two, invalidate all (or at least that's what I have understood - G.P.)
• "NonDuplicate" : if more than one (tag+probe) pair shares the same probe, just keep one of them (the one with highest tag p_T). This can make sense in some more general cases than di-object resonances, when you just need a tag to get your probe on disk * "OnePair": disallow the same (tag+probe) pair to enter the dataset twice with the two roles exchanged. You can use this if you're looking not at properties of the individual muon but rather at properties of the pair (e.g. Δz between the two muons) or properties of the event (e.g. number of vertices, number of jets).
  Note: if your efficiency depends on which of the two legs is the tag and which of the two is the probe is the probe, you cannot use this setting.

there is no real relationship between tags and probes. Note that this arbitration still allows a tag to have multiple probes associated to it.

If you need some other generic arbitration algorithm let us know so that we can add it to the module. If instead you need some analysis-specific arbitration (e.g. use the probe that has more pixel hit in the tracker track), you can code it as a module that filters the collection of reco::CompositeCandidate objects before it's passed as input to the TagProbeFitTreeProducer. You can check if two reco::ShallowCloneCompositeCandidates c1, c2 share the tag by checking if (c1.daughter(0)->masterClone() == c2.daughter(0)->masterClone()).

Variable definition

The probe variables to include in the output dataset can be defined in two ways:

• Simple variables that can be computed from the probe object itself, accessing its data members and methods (e.g. eta(), pt(), track().numberOfValidHits(), ...)
  These are specified as simple string expressions
• External variables that require access to other information outside the object (e.g. distance to nearest jet) or more complex C++ code.
  An exernal variable is defined by specifying a cms.InputTag to an edm::ValueMap<float> that contains the values for each probe.
  This allows you to write your own CMSSW module to compute the variable with complete freedom.

An example using simple variables and an external one is:

variables = cms.PSet(
    # simple variables
    pt = cms.string("pt()"),       # define the variable "pt" to be computed calling "object.pt()"
    phi = cms.string("phi"),      # you can even omit the () if the method has no arguments
    abseta = cms.string("abs(eta)"),   # and you can also use some mathematical functions
    scEta = cms.string("superCluster.eta"), # or use nested objects
    # external variables
    drjet = cms.InputTag("electronJetDR"), # external variable, from a ValueMap.
)

If you want a simple example of CMSSW module that computes an external variable, you can look at PhysicsTools/TagAndProbe/plugins/DeltaRNearestObjectComputer.cc. You can use this approach even if the variable is not specific of the probe but of the full event (e.g. the total number of jets), you just have to set the same value for all probes.

We should add here a list of existing modules computing external variables that can be of general use

Since tag V02-03-00 you can also include in the tree variables of the tag candidate, (tag+probe) pair or of the mc candidate matched to the probe. Such variables can be defined in the optional PSets called tagVariables, pairVariables, mcVariables. The associated branches will be prefixed with tag_, pair_ and mc_.

Global variables

• setting parameter addRunLumiInfo to true will cause the module to write in the tree also the run, lumisection and event number
• setting parameter addEventVariablesInfo to true will cause the module to add in the tree the number of good primary vertices, the MET, SumET and MET significance for the three algorithms (calo, tc, pf), and the (x,y,z) position of the primary vertex and beamspot. This requires the following collections to be available in the event: offlineBeamSpot, offlinePrimaryVertices, met, tcMet, pfMet (all input tags are hard coded, sorry).

Passing probe flag definitions

For each probe you should specify one or more flags that define if the probe is passing one or more selections for which you're measuring the efficiency. Just like for the variables, there are two possibilities:

• Simple selections, specified by a cut on some of the object's variables or accessing some of the object's methods.
• Complex selections, computed by an external module and specified by providing an InputTag to a collection of passing probes.
  The collection of passing probes must contain references to the probe objects that pass the selection.

An example configuration is:

flags = cms.PSet(
   # some simple selections
    lastStationLoose = cms.string("muonID('TMLastStationLoose')"), # direct access to Muon ID as provided by PAT Muons
    hltMu3 = cms.string("!triggerObjectMatchesByPath('HLT_Mu3').empty()"), # if this is a PAT Muon with embedded trigger matches, you can check them
    relTkIso = cms.string("isolationR03().sumPt / pt() < 0.2"),  # cut on the relative isolation, using the values stored in the reco::Muon object
    # external variables
    drjet = cms.InputTag("muonMatchedToPixelTrack"), # external, from a collection of references to passing probes.
)

An example of CMSSW module that performs a selection by reference is MuonAnalysis/Examples/plugins/MuonSelectorExample.cc. That module just performs simple cuts on the objects, but you can perform a selection as complex as you want (e.g. try to match the probe to some other detector signal or physics object).
If CMSSW complains about missing dictionaries when you run your module, you can try to change it so that it writes out a generic edm::RefToBaseVector<reco::Candidate> which you can fill from your edm::View<X> by creating RefToBase=s as edm::RefToBase<reco::Candidate> ref = edm::RefToBase<reco::Candidate>(view->refAt(idx));. If you still get issues with dictionaries, try again but replacing =RefToBase with Ptr, RefToBaseVector with PtrVector, refAt(i) with ptrAt(i).

There's already a simple way to select objects that are match by ΔR to some other object, we should document how to use it. There are a few common modules that you can consider for this task:

• CandViewCleaner: selects candidates from the srcCands collection that don't overlap with a candidates in any of the srcObjects collections (VInputTag); the overlap is defined by ΔR, controlled by parameter deltaRMin
• The PAT cross-cleaning tools provide another very flexible way of matching (PAT) objects to any other objects. In this case, you should use as probe collection the output of the cleaner in flagging mode (requireNoOverlaps set to False), and then you can define the passing probes using string cuts (e.g. isAJet = cms.string("hasOverlaps('jets')"))

Since tag V02-03-00 you can also include in the tree boolean flags associated to the tag candidate, (tag+probe) pair or of the mc candidate matched to the probe. Such variables can be defined in the optional PSets called tagVariables, pairVariables, mcVariables. The associated branches will be prefixed with tag_, pair_ and mc_.

Simulation Truth information

These variables will be used only if the parameter isMC is set to true.

Parameters tagMatches, probeMatches
These two parameters of type InputTag are used to define the association maps from the tags and probes to the simulation truth. Associations using simple matching by ΔR can be produced easily with the existing CMSSW module MCTruthDeltaRMatcherNew. For more complex matching, you can use any other matcher provided that the output is an edm::Association>reco::GenParticleCollection>

Example using MCTruthDeltaRMatcherNew:

process.muMcMatch = cms.EDFilter("MCTruthDeltaRMatcherNew",
    src = cms.InputTag("muons"),
    matched = cms.InputTag("genParticles"),
    pdgId = cms.vint32(13),
    distMin = cms.double(0.3),
)

Parameter motherPdgId
The MC truth efficiency is usually defined using di-leptons from a specific resonance (or set of resonances), not just any pair of truth-matched leptons. If motherPdgId is set to a non-empty list of pdgId codes, the leptons will defined as "true" if they're matched to a true lepton that has one ancestor among those pdgId. If the list is empty, any truth-matched lepton is used.

For convenience, a list of useful pdg ids for resonances is:

γ, Z	22, 23
J/Psi, Psi(2S)	443, 100443
Y(1S), Y(2S), Y(3S)	553, 100553, 200553
π0, η, φ	111, 221, 333

A full list is available at rpp2009-rev-monte-carlo-numbering.pdf
Sometimes in CMSSW a higher-state of a particle is faked at generator level using a lower state and changing the mass, so it might happen that e.g. a Psi(2S) is generated with the pdgId of 443 instead of 100443.

Parameters makeMCUnbiasTree , checkMotherInUnbiasEff, allProbes
These parameters are used when computing the "unbiased" MC efficiency, that is without requiring the tag to be selected or even reconstructed. If makeMCUnbiasTree is set, the module will produce also another TTree that contains variables and flags for all true probes, irrespectively of the tag. This requires you to specify also the full collection of probes using the parameter allProbes of type InputTag.

If checkMotherInUnbiasEff is set to true, the "unbiased" MC efficiency is computed only using truth-matched leptons coming from the resonances selected by the parameter motherPdgId. If it's set to false, any truth-matched lepton is used in the efficiency.

Output

The output of the module is a directory within the TFileService output file, containing:

• a TTree fitter_tree with one entry per (tag+probe) pair, and the following branches
  • mass/F: the mass of the T&P pair.
  • <variable>/F: for each probe variable
  • <flag>/I: for each passing probe flag, with values 1 for pass and 0 for fail (we didn't use x/B columns because they don't always get imported well by RooFit)
  • mcTrue/I: this flag is set to true if the (tag+probe) pair is matched to mc truth and is to be used in the mc efficiency.
    The branch is present only if isMC is set to true.
• if makeMCUnbiasTree is activated, there is also another TTree named mcUnbias_tree=m with one entry per truth-matched probe, and an identical layout except that it has no =mass and mcTrue branches.

Metadata
The output of the TFileService is not an EDM file and lacks provenance tracking. In order to allow you to recover the information used to produce it, the TagProbeFitTreeProducer embeds a full dump of the process cfg file into the header of the TTree fitter_tree as a TObjString. You can dump that information from bare ROOT or FWLite using the macro PhysicsTools/TagAndProbe/test/psetDumpFromTTree.C. If you have merged multiple files with hadd, you might get the dump more than once.

Example configuration files

Three example configuration files for TagProbeFitTreeProducer are provided under CMS.PhysicsTools/CMS.TagAndProbe/test/ :

newstyleWrite.py
A very simple cfg file just to illustrate the procedure; it works at the J/Psi peak, and computes the efficiency for a tracker muon to be reconstructed as a global muon. As it's a simplified example, it doesn't take trigger into account.

testTagProbeFitTreeProducer_ZMuMu.py
Another toy cfg file that provides example of the different ways of defining variables and passing probe criteria. It works at the Z peak, using tracker muons as probes and determining the efficiency for those muons to pass the calorimetric muon id, the global muon reconstruction and a simple relative isolation cut. It uses an external module to provide as variable also the ΔR between the probe and the nearest jet.

testTagProbeFitTreeProducer_JPsi.py
A simplified version of the Muon T&P used for the J/Psi T&P October Excercise in 2009, measuring the in three steps the efficiency to reconstruct a tracker track (with standalone muon probes) and a global muon (with tracker track probes) and the efficiency for a global muon to pass the HLT_Mu3 trigger. It works with PAT objects, and requires some muon-specific packages to define the passing probes performing matching between standalone muon and tracker tracks.

%RESPONSIBLE% GiovanniPetrucciani