PatCandidates/interface/Muon.h

0001 //
0002 //
0003
0004 #ifndef DataFormats_PatCandidates_Muon_h
0005 #define DataFormats_PatCandidates_Muon_h
0006
0007 /**
0008   \class    pat::Muon Muon.h "DataFormats/PatCandidates/interface/Muon.h"
0009   \brief    Analysis-level muon class
0010
0011    pat::Muon implements the analysis-level muon class within the 'pat'
0012    namespace.
0013
0014    Please post comments and questions to the Physics Tools hypernews:
0015    https://hypernews.cern.ch/HyperNews/CMS/get/physTools.html
0016
0017   \author   Steven Lowette, Giovanni Petrucciani, Frederic Ronga, Colin Bernet
0018
0019 */
0020
0021 #include "DataFormats/MuonReco/interface/Muon.h"
0022 #include "DataFormats/MuonReco/interface/MuonFwd.h"
0023 #include "DataFormats/MuonReco/interface/MuonSelectors.h"
0024 #include "DataFormats/MuonReco/interface/MuonMETCorrectionData.h"
0025 #include "DataFormats/MuonReco/interface/MuonTimeExtra.h"
0026
0027 #include "DataFormats/TrackReco/interface/Track.h"
0028 #include "DataFormats/PatCandidates/interface/Lepton.h"
0029 #include "DataFormats/ParticleFlowCandidate/interface/IsolatedPFCandidateFwd.h"
0030 #include "DataFormats/ParticleFlowCandidate/interface/IsolatedPFCandidate.h"
0031 #include "DataFormats/MuonReco/interface/MuonSimInfo.h"
0032
0033 // Define typedefs for convenience
0034 namespace pat {
0035   class Muon;
0036   typedef std::vector<Muon> MuonCollection;
0037   typedef edm::Ref<MuonCollection> MuonRef;
0038   typedef edm::RefVector<MuonCollection> MuonRefVector;
0039 }  // namespace pat
0040
0041 namespace reco {
0042   /// pipe operator (introduced to use pat::Muon with PFTopProjectors)
0043   std::ostream& operator<<(std::ostream& out, const pat::Muon& obj);
0044 }  // namespace reco
0045
0046 // Class definition
0047 namespace pat {
0048
0049   class PATMuonSlimmer;
0050
0051   class Muon : public Lepton<reco::Muon> {
0052   public:
0053     /// default constructor
0054     Muon();
0055     /// constructor from a reco muon
0056     Muon(const reco::Muon& aMuon);
0057     /// constructor from a RefToBase to a reco muon (to be superseded by Ptr counterpart)
0058     Muon(const edm::RefToBase<reco::Muon>& aMuonRef);
0059     /// constructor from a Ptr to a reco muon
0060     Muon(const edm::Ptr<reco::Muon>& aMuonRef);
0061     /// destructor
0062     ~Muon() override;
0063
0064     /// required reimplementation of the Candidate's clone method
0065     Muon* clone() const override { return new Muon(*this); }
0066
0067     // ---- methods for content embedding ----
0068     /// reference to Track reconstructed in the tracker only (reimplemented from reco::Muon)
0069     reco::TrackRef track() const override;
0070     using reco::RecoCandidate::track;  // avoid hiding the base implementation
0071     /// reference to Track reconstructed in the tracker only (reimplemented from reco::Muon)
0072     reco::TrackRef innerTrack() const override { return track(); }
0073     /// reference to Track reconstructed in the muon detector only (reimplemented from reco::Muon)
0074     reco::TrackRef standAloneMuon() const override;
0075     /// reference to Track reconstructed in the muon detector only (reimplemented from reco::Muon)
0076     reco::TrackRef outerTrack() const override { return standAloneMuon(); }
0077     /// reference to Track reconstructed in both tracked and muon detector (reimplemented from reco::Muon)
0078     reco::TrackRef combinedMuon() const override;
0079     /// reference to Track reconstructed in both tracked and muon detector (reimplemented from reco::Muon)
0080     reco::TrackRef globalTrack() const override { return combinedMuon(); }
0081     /// Track selected to be the best measurement of the muon parameters (including PFlow global information)
0082     const reco::Track* bestTrack() const override { return muonBestTrack().get(); }
0083     /// Track selected to be the best measurement of the muon parameters (including PFlow global information)
0084     reco::TrackRef muonBestTrack() const override;
0085     /// Track selected to be the best measurement of the muon parameters (from muon information alone)
0086     reco::TrackRef tunePMuonBestTrack() const override;
0087
0088     /// set reference to Track selected to be the best measurement of the muon parameters (reimplemented from reco::Muon)
0089     /// if force == false, do not embed this track if it's embedded already (e.g. ig it's a tracker track, and that's already embedded)
0090     void embedMuonBestTrack(bool force = false);
0091     /// set reference to Track selected to be the best measurement of the muon parameters (reimplemented from reco::Muon)
0092     /// if force == false, do not embed this track if it's embedded already (e.g. ig it's a tracker track, and that's already embedded)
0093     void embedTunePMuonBestTrack(bool force = false);
0094     /// set reference to Track reconstructed in the tracker only (reimplemented from reco::Muon)
0095     void embedTrack();
0096     /// set reference to Track reconstructed in the muon detector only (reimplemented from reco::Muon)
0097     void embedStandAloneMuon();
0098     /// set reference to Track reconstructed in both tracked and muon detector (reimplemented from reco::Muon)
0099     void embedCombinedMuon();
0100     // rekey TrackExtra references of embedded tracks
0101     void rekeyEmbeddedTracks(std::vector<edm::Handle<edm::Association<reco::TrackExtraCollection>>> const& assocs);
0102
0103     // ---- methods for MuonMETCorrectionData ----
0104     /// muon MET corrections for caloMET; returns the muon correction struct if embedded during pat tuple production or an empty element
0105     reco::MuonMETCorrectionData caloMETMuonCorrs() const {
0106       return (embeddedCaloMETMuonCorrs_ ? caloMETMuonCorrs_.front() : reco::MuonMETCorrectionData());
0107     };
0108     void embedCaloMETMuonCorrs(const reco::MuonMETCorrectionData& t);
0109     /// muon MET corrections for tcMET; returns the muon correction struct if embedded during pat tuple production or an empty element
0110     reco::MuonMETCorrectionData tcMETMuonCorrs() const {
0111       return (embeddedTCMETMuonCorrs_ ? tcMETMuonCorrs_.front() : reco::MuonMETCorrectionData());
0112     };
0113     void embedTcMETMuonCorrs(const reco::MuonMETCorrectionData& t);
0114
0115     // ---- methods for TeV refit tracks ----
0116
0117     /// reference to Track reconstructed using hits in the tracker + "good" muon hits (reimplemented from reco::Muon)
0118     reco::TrackRef pickyTrack() const override;
0119     /// reference to Track reconstructed using hits in the tracker + info from the first muon station that has hits (reimplemented from reco::Muon)
0120     reco::TrackRef tpfmsTrack() const override;
0121     /// reference to Track reconstructed using DYT algorithm
0122     reco::TrackRef dytTrack() const override;
0123     /// Deprecated accessors to call the corresponding above two functions; no dytMuon since this naming is deprecated.
0124     reco::TrackRef pickyMuon() const { return pickyTrack(); }  // JMTBAD gcc deprecated attribute?
0125     reco::TrackRef tpfmsMuon() const { return tpfmsTrack(); }  // JMTBAD gcc deprecated attribute?
0126     /// embed reference to the above picky Track
0127     void embedPickyMuon();
0128     /// embed reference to the above tpfms Track
0129     void embedTpfmsMuon();
0130     /// embed reference to the above dyt Track
0131     void embedDytMuon();
0132
0133     // add extra timing information
0134     void readTimeExtra(const reco::MuonTimeExtra& t);
0135
0136     // ---- PF specific methods ----
0137     /// reference to the source IsolatedPFCandidates
0138     /// null if this has been built from a standard muon
0139     reco::PFCandidateRef pfCandidateRef() const;
0140     /// add a reference to the source IsolatedPFCandidate
0141     void setPFCandidateRef(const reco::PFCandidateRef& ref) { pfCandidateRef_ = ref; }
0142     /// embed the IsolatedPFCandidate pointed to by pfCandidateRef_
0143     void embedPFCandidate();
0144     /// get the number of non-null PF candidates
0145     size_t numberOfSourceCandidatePtrs() const override {
0146       size_t res = 0;
0147       if (pfCandidateRef_.isNonnull())
0148         res++;
0149       if (refToOrig_.isNonnull())
0150         res++;
0151       return res;
0152     }
0153     /// get the candidate pointer with index i
0154     reco::CandidatePtr sourceCandidatePtr(size_type i) const override;
0155
0156     // ---- methods for accessing muon identification ----
0157     /// accessor for the various muon id algorithms currently defined
0158     /// in DataFormats/MuonReco/interface/MuonSelectors.h
0159     /// e.g. bool result = patmuon.muonID("TMLastStationLoose")
0160     bool muonID(const std::string& name) const;
0161     /// wrapper for the muonID method to maintain backwards compatibility
0162     /// with when the reco::Muon::isGood method existed
0163     bool isGood(const std::string& name) const { return muonID(name); }
0164     /// if muon id results are ever extracted from muon id value maps
0165     /// then the isMuonIDAvailable method will be defined
0166     //bool isMuonIDAvailable(const std::string& name) const;
0167
0168     /// Muon Selectors as specified in
0169     /// https://twiki.cern.ch/twiki/bin/view/CMSPublic/SWGuideMuonId
0170     bool isTightMuon(const reco::Vertex&) const;
0171     bool isLooseMuon() const;
0172     bool isMediumMuon() const;
0173     bool isSoftMuon(const reco::Vertex&) const;
0174     bool isHighPtMuon(const reco::Vertex&) const;
0175
0176     // ---- overload of isolation functions ----
0177     /// Overload of pat::Lepton::trackIso(); returns the value of
0178     /// the summed track pt in a cone of deltaR<0.3
0179     float trackIso() const { return isolationR03().sumPt; }
0180     /// Overload of pat::Lepton::trackIso(); returns the value of
0181     /// the summed Et of all recHits in the ecal in a cone of
0182     /// deltaR<0.3
0183     float ecalIso() const { return isolationR03().emEt; }
0184     /// Overload of pat::Lepton::trackIso(); returns the value of
0185     /// the summed Et of all caloTowers in the hcal in a cone of
0186     /// deltaR<0.4
0187     float hcalIso() const { return isolationR03().hadEt; }
0188     /// Overload of pat::Lepton::trackIso(); returns the sum of
0189     /// ecalIso() and hcalIso
0190     float caloIso() const { return ecalIso() + hcalIso(); }
0191
0192     /// returns PUPPI isolations
0193     float puppiChargedHadronIso() const { return puppiChargedHadronIso_; }
0194     float puppiNeutralHadronIso() const { return puppiNeutralHadronIso_; }
0195     float puppiPhotonIso() const { return puppiPhotonIso_; }
0196     /// returns PUPPINoLeptons isolations
0197     float puppiNoLeptonsChargedHadronIso() const { return puppiNoLeptonsChargedHadronIso_; }
0198     float puppiNoLeptonsNeutralHadronIso() const { return puppiNoLeptonsNeutralHadronIso_; }
0199     float puppiNoLeptonsPhotonIso() const { return puppiNoLeptonsPhotonIso_; }
0200     /// sets PUPPI isolations
0201     void setIsolationPUPPI(float chargedhadrons, float neutralhadrons, float photons) {
0202       puppiChargedHadronIso_ = chargedhadrons;
0203       puppiNeutralHadronIso_ = neutralhadrons;
0204       puppiPhotonIso_ = photons;
0205     }
0206     /// sets PUPPINoLeptons isolations
0207     void setIsolationPUPPINoLeptons(float chargedhadrons, float neutralhadrons, float photons) {
0208       puppiNoLeptonsChargedHadronIso_ = chargedhadrons;
0209       puppiNoLeptonsNeutralHadronIso_ = neutralhadrons;
0210       puppiNoLeptonsPhotonIso_ = photons;
0211     }
0212
0213     /// Muon High Level Selection
0214     /// The user can choose to cache this info so they can drop the
0215     /// global tracks. If the global track is present these should
0216     /// not be set, but the "getters" will return the appropriate
0217     /// value. The exception is dB which requires the beamline
0218     //  as external input.
0219
0220     // ---- embed various impact parameters with errors ----
0221     //
0222     // example:
0223     //
0224     //    // this will return the muon inner track
0225     //    // transverse impact parameter
0226     //    // relative to the primary vertex
0227     //    muon->dB(pat::Muon::PV2D);
0228     //
0229     //    // this will return the uncertainty
0230     //    // on the muon inner track
0231     //    // transverse impact parameter
0232     //    // relative to the primary vertex
0233     //    // or -1.0 if there is no valid PV in the event
0234     //    muon->edB(pat::Muon::PV2D);
0235     //
0236     // IpType defines the type of the impact parameter
0237     typedef enum IPTYPE { PV2D = 0, PV3D = 1, BS2D = 2, BS3D = 3, PVDZ = 4, IpTypeSize = 5 } IpType;
0238     void initImpactParameters(void);  // init IP defaults in a constructor
0239     double dB(IPTYPE type) const;
0240     double edB(IPTYPE type) const;
0241
0242     /// the version without arguments returns PD2D, but with an absolute value (for backwards compatibility)
0243     double dB() const { return std::abs(dB(PV2D)); }
0244     /// the version without arguments returns PD2D, but with an absolute value (for backwards compatibility)
0245     double edB() const { return std::abs(edB(PV2D)); }
0246
0247     void setDB(double dB, double edB, IPTYPE type = PV2D) {
0248       ip_[type] = dB;
0249       eip_[type] = edB;
0250       cachedIP_ |= (1 << int(type));
0251     }
0252
0253     /// numberOfValidHits returns the number of valid hits on the global track.
0254     unsigned int numberOfValidHits() const;
0255     void setNumberOfValidHits(unsigned int numberOfValidHits) {
0256       numberOfValidHits_ = numberOfValidHits;
0257       cachedNumberOfValidHits_ = true;
0258     }
0259
0260     /// Norm chi2 gives the normalized chi2 of the global track.
0261     double normChi2() const;
0262     void setNormChi2(double normChi2) {
0263       normChi2_ = normChi2;
0264       cachedNormChi2_ = true;
0265     }
0266
0267     /// Returns the segment compatibility, using muon::segmentCompatibility (DataFormats/MuonReco/interface/MuonSelectors.h)
0268     double segmentCompatibility(
0269         reco::Muon::ArbitrationType arbitrationType = reco::Muon::SegmentAndTrackArbitration) const;
0270
0271     /// pipe operator (introduced to use pat::Muon with PFTopProjectors)
0272     friend std::ostream& reco::operator<<(std::ostream& out, const pat::Muon& obj);
0273
0274     friend class PATMuonSlimmer;
0275
0276     float pfEcalEnergy() const { return pfEcalEnergy_; }
0277     void setPfEcalEnergy(float pfEcalEnergy) { pfEcalEnergy_ = pfEcalEnergy; }
0278
0279     /// near-by jet information
0280     float jetPtRatio() const { return jetPtRatio_; }
0281     float jetPtRel() const { return jetPtRel_; }
0282     void setJetPtRatio(float jetPtRatio) { jetPtRatio_ = jetPtRatio; }
0283     void setJetPtRel(float jetPtRel) { jetPtRel_ = jetPtRel; }
0284
0285     /// Soft Muon MVA
0286     float softMvaValue() const { return softMvaValue_; }
0287     void setSoftMvaValue(float softmva) { softMvaValue_ = softmva; }
0288     float softMvaRun3Value() const { return softMvaRun3Value_; }
0289     void setSoftMvaRun3Value(float softmva) { softMvaRun3Value_ = softmva; }
0290
0291     /// Muon MVA ID
0292     float mvaIDValue() const { return mvaIDValue_; }
0293     void setMvaIDValue(float mvaID) { mvaIDValue_ = mvaID; }
0294
0295     // 1/beta for prompt particle hypothesis
0296     /// (time is constraint to the bunch crossing time)
0297     float inverseBeta() const { return inverseBeta_; }
0298     float inverseBetaErr() const { return inverseBetaErr_; }
0299
0300     /// MC matching information
0301     reco::MuonSimType simType() const { return simType_; }
0302     reco::ExtendedMuonSimType simExtType() const { return simExtType_; }
0303     //  FLAVOUR:
0304     //  - for non-muons: 0
0305     //  - for primary muons: 13
0306     //  - for non primary muons: flavour of the mother: std::abs(pdgId) of heaviest quark, or 15 for tau
0307     int simFlavour() const { return simFlavour_; }
0308     int simHeaviestMotherFlavour() const { return simHeaviestMotherFlavour_; }
0309     int simPdgId() const { return simPdgId_; }
0310     int simMotherPdgId() const { return simMotherPdgId_; }
0311     int simBX() const { return simBX_; }
0312     int simTpEvent() const { return simTpEvent_; }
0313     float simProdRho() const { return simProdRho_; }
0314     float simProdZ() const { return simProdZ_; }
0315     float simPt() const { return simPt_; }
0316     float simEta() const { return simEta_; }
0317     float simPhi() const { return simPhi_; }
0318     float simMatchQuality() const { return simMatchQuality_; }
0319
0320     void initSimInfo(void);
0321     void setSimType(reco::MuonSimType type) { simType_ = type; }
0322     void setExtSimType(reco::ExtendedMuonSimType type) { simExtType_ = type; }
0323     void setSimFlavour(int f) { simFlavour_ = f; }
0324     void setSimHeaviestMotherFlavour(int id) { simHeaviestMotherFlavour_ = id; }
0325     void setSimPdgId(int id) { simPdgId_ = id; }
0326     void setSimMotherPdgId(int id) { simMotherPdgId_ = id; }
0327     void setSimBX(int bx) { simBX_ = bx; }
0328     void setSimTpEvent(int tpEvent) { simTpEvent_ = tpEvent; }
0329     void setSimProdRho(float rho) { simProdRho_ = rho; }
0330     void setSimProdZ(float z) { simProdZ_ = z; }
0331     void setSimPt(float pt) { simPt_ = pt; }
0332     void setSimEta(float eta) { simEta_ = eta; }
0333     void setSimPhi(float phi) { simPhi_ = phi; }
0334     void setSimMatchQuality(float quality) { simMatchQuality_ = quality; }
0335
0336     /// Trigger information
0337     const pat::TriggerObjectStandAlone* l1Object(const size_t idx = 0) const {
0338       return triggerObjectMatchByType(trigger::TriggerL1Mu, idx);
0339     }
0340     const pat::TriggerObjectStandAlone* hltObject(const size_t idx = 0) const {
0341       return triggerObjectMatchByType(trigger::TriggerMuon, idx);
0342     }
0343     bool triggered(const char* pathName) const { return triggerObjectMatchByPath(pathName, true, true) != nullptr; }
0344
0345   protected:
0346     // ---- for content embedding ----
0347
0348     /// best muon track (global pflow)
0349     bool embeddedMuonBestTrack_;
0350     std::vector<reco::Track> muonBestTrack_;
0351     /// best muon track (muon only)
0352     bool embeddedTunePMuonBestTrack_;
0353     std::vector<reco::Track> tunePMuonBestTrack_;
0354     /// track of inner track detector
0355     bool embeddedTrack_;
0356     std::vector<reco::Track> track_;
0357     /// track of muon system
0358     bool embeddedStandAloneMuon_;
0359     std::vector<reco::Track> standAloneMuon_;
0360     /// track of combined fit
0361     bool embeddedCombinedMuon_;
0362     std::vector<reco::Track> combinedMuon_;
0363
0364     /// muon MET corrections for tcMET
0365     bool embeddedTCMETMuonCorrs_;
0366     std::vector<reco::MuonMETCorrectionData> tcMETMuonCorrs_;
0367     /// muon MET corrections for caloMET
0368     bool embeddedCaloMETMuonCorrs_;
0369     std::vector<reco::MuonMETCorrectionData> caloMETMuonCorrs_;
0370
0371     // Capability to embed TeV refit tracks as the inner/outer/combined ones.
0372     bool embeddedPickyMuon_;
0373     bool embeddedTpfmsMuon_;
0374     bool embeddedDytMuon_;
0375     std::vector<reco::Track> pickyMuon_;
0376     std::vector<reco::Track> tpfmsMuon_;
0377     std::vector<reco::Track> dytMuon_;
0378
0379     // ---- PF specific members ----
0380     /// true if the IsolatedPFCandidate is embedded
0381     bool embeddedPFCandidate_;
0382     /// if embeddedPFCandidate_, a copy of the source IsolatedPFCandidate
0383     /// is stored in this vector
0384     reco::PFCandidateCollection pfCandidate_;
0385     /// reference to the IsolatedPFCandidate this has been built from
0386     /// null if this has been built from a standard muon
0387     reco::PFCandidateRef pfCandidateRef_;
0388
0389     // V+Jets group selection variables.
0390     bool cachedNormChi2_;  /// has the normalized chi2 been cached?
0391     double normChi2_;      /// globalTrack->chi2() / globalTrack->ndof()
0392
0393     bool cachedNumberOfValidHits_;    /// has the numberOfValidHits been cached?
0394     unsigned int numberOfValidHits_;  /// globalTrack->numberOfValidHits()
0395
0396     // ---- cached impact parameters ----
0397     uint8_t cachedIP_;       // has the IP (former dB) been cached?
0398     float ip_[IpTypeSize];   // dB and edB are the impact parameter at the primary vertex,
0399     float eip_[IpTypeSize];  // and its uncertainty as recommended by the tracking group
0400
0401     /// PUPPI isolations
0402     float puppiChargedHadronIso_;
0403     float puppiNeutralHadronIso_;
0404     float puppiPhotonIso_;
0405     /// PUPPINoLeptons isolations
0406     float puppiNoLeptonsChargedHadronIso_;
0407     float puppiNoLeptonsNeutralHadronIso_;
0408     float puppiNoLeptonsPhotonIso_;
0409
0410     float pfEcalEnergy_;
0411
0412     /// near-by jet information
0413     float jetPtRatio_;
0414     float jetPtRel_;
0415
0416     /// Muon MVA
0417     float mvaIDValue_;
0418     float softMvaValue_;
0419     float softMvaRun3Value_ = 0;
0420
0421     /// Inverse beta
0422     float inverseBeta_;
0423     float inverseBetaErr_;
0424
0425     /// MC matching information
0426     reco::MuonSimType simType_;
0427     reco::ExtendedMuonSimType simExtType_;
0428     int simFlavour_;
0429     int simHeaviestMotherFlavour_;
0430     int simPdgId_;
0431     int simMotherPdgId_;
0432     int simBX_;
0433     int simTpEvent_;
0434     float simProdRho_;
0435     float simProdZ_;
0436     float simPt_;
0437     float simEta_;
0438     float simPhi_;
0439     float simMatchQuality_;
0440   };
0441
0442 }  // namespace pat
0443
0444 #endif