Gsf Electron Object

Complete: 4

Goals of this page

This page explains the interface and internal data of the standard reconstructed GSF electrons, actually the attributes and public interface of the C++ class CMS.GsfElectron. The page has been created for the release 312 of CMSSW, and there is no such page for previous releases. Some related topics are:

Introduction

This electron is called "GSF" and represented by the class GsfElectron because it is associated to an instance of GsfTrack. The class was previously called PixelMatchGsfElectron, and originally adapted from the TRecElectron class in ORCA.

The tracks have been made from a collection of trajectory seeds (class ElectronSeed) mixed from two sources : the egamma "ecal-driven" seeds which are determined from the ecal superclusters, and the particle flow "tracker-driven" seeds. Therefore, an electron can be qualified "ecal-driven" when its associated track seed has been found by the egamma "ecal-driven" approach, and/or can be qualified "tracker-driven" when its track seed comes from the track based electron seeding strategy developped by the particle flow.

Every instance of GsfElectron has a reference towards an instance of GsfElectronCore. The latter is a basic object just containing the reference to the associated GsfTrack and the associated superclusters (one or two depending if the track has been found by the ecal-driven approach, the tracker-driven approach, or both). The collection of core gsf electrons is produced first, and the preselection is not applied to them (more precisely part of the electron preselection is performed at the seeding level, thus included in producing the core gsf electrons, while the remaining part of the preselection is done when producing the gsf electrons from the cores). That means that not every instance of GsfElectronCore is refered by an instance of GsfElectron.

On top of the reference to the core partner, an instance of CMS.GsfElectron contains all the characteristics which have been computed for the preselection (some of the constructed electrons will finally be filtered out and not added to the persistent collection), all variables needed for further selection as well as the final estimate of the electron momentum. Apart from few exceptions, all those values are expected to be specified in the CMS.GsfElectron constructor and never modified afterwards: one will not find many setters in the interface, because we want to enforce that those values, used to filter-out some of the candidate electrons, will not be changed after this filtering.

Also, since there are many attributes in CMS.GsfElectron, we found it usefull to group them in consistent groups or blocks, which are implemented as internal structs in the class. When looking for the characteristics of a given electron, one can either get the full structures or the individual values. When constructing an electron, one can only provide structs, which reduces the risk of giving values in wrong order.

Interface blocks

Below, we describe each interface block one after the other. Generally, for each block, there is a dedicated C++ struct, an associated argument in the CMS.GsfElectron constructor, an associated private attribute in CMS.GsfElectron, a global getter, and a set of individual getters for each element in the structure. All those attributes are visibly mapped to the interface and could almost be public attributes, but we do not want to allow anyone to change their values once the electron is built. We mention here the CMS.GsfElectron internal structs because someone who is barely browsing and edm ROOT file will see them.

Candidate methods

This special block contains the redefined virtual methods inherited from RecoCandidate. It is worth to recall that GsfElectron indirectly inherits from Candidate and one can invoke all the methods from the Candidate class, for example p4() and charge() (those two values are set by the electron producer when constructing the GsfElectron).

  • int Candidate::charge()
  • const LorentzVector & Candidate::p4()

  • bool isElectron()
  • bool overlap( const Candidate & )

Core attributes

This special block gives access to the lower level products the electron depends on (clusters and tracks), and which have been previously put together into instances of GsfElectronCore. Each GsfElectron has a reference towards such a GsfElectronCore partner, called core_, which one can see when TBrowsing an edm ROOT file. One can either get the reference to the core partner (GsfElectron::core()) and call methods from GsfElectronCore, or call the similar GsfElectron methods, which internally delegates the call to the core partner. The following comments apply both to GsfElectronCore and GsfElectron.

As said above in the introduction, the electron seeds comes from two different sources : the egamma "ecal-driven" seeds which are determined from the ecal superclusters, and the "tracker-driven" seeds developed by the particle flow. Therefore, an electron can be qualified "ecal-driven", when its associated track seed has been found by the egamma "ecal-driven" approach, and/or can be qualified "tracker-driven" when its track seed comes from the track based particle flow electron seeding approach. Some electron seeds are found both by the "ecal-driven" and the "tracker-driven" approaches, in that case the seed and the associated electron will be both "ecal-driven" and "tracker-driven".

The superCluster() method below returns the "ecal-driven" supercluster unless the electron is purely "tracker-driven" (i.e. its seed has been found by the "tracker-driven" approach only). In the former case only, superCluster() will return the associated particle flow supercluster as produced by the PFTranslator, the same as the one returned by the method pflowSuperCluster(). Said differently: superCluster() always return a supercluster, and will privilege the egamma one from which the electron quantities are built when it exists. pflowSuperCluster() returns the "tracker-driven" supercluster when there is one, or an empty reference.

The list of methods:

   SuperClusterRef superCluster() ;
   GsfTrackRef gsfTrack() ;
   bool isEcalDriven() ;
   bool isTrackerDriven() ;
   SuperClusterRef pflowSuperCluster() ;

Track-Cluster matching attributes

Normal block of related quantities:

  • float eSuperClusterOverP(): the supercluster energy / track momentum at the point of closest approach (PCA) to the beam spot.
  • float deltaEtaSuperClusterTrackAtVtx(): the supercluster eta - track eta position at the PCA to the supercluster, extrapolated from the innermost track state.
  • float deltaPhiSuperClusterTrackAtVtx(): the supercluster phi - track phi position at the PCA to the supercluster, extrapolated from the innermost track state.
  • float eSeedClusterOverP(): the seed cluster energy / track momentum at the PCA to the beam spot.
  • float eSeedClusterOverPout(): the seed cluster energy / track momentum at the PCA to the seed cluster, extrapolated from the outermost track state.
  • float deltaEtaSeedClusterTrackAtCalo(): the seed cluster eta - track eta position at the PCA to the seed cluster, extrapolated from the outermost track state.
  • float deltaPhiSeedClusterTrackAtCalo(): the seed cluster phi - track phi position at the PCA to the seed cluster, extrapolated from the outermost track state.
  • CaloClusterPtr electronCluster(): the basic cluster best matching gsf track outermost direction.
  • float eEleClusterOverPout(): the electron cluster energy / track momentum at the PCA to the electron cluster (as defined by electronCluster()), extrapolated from the outermost track state.
  • float deltaEtaEleClusterTrackAtCalo(): the electron cluster eta - track eta position at the PCA to the electron cluster, extrapolated from the outermost state.
  • float deltaPhiEleClusterTrackAtCalo(): the electron cluster phi - track phi position at the PCA to the electron cluster, extrapolated from the outermost track state.

Within the electron, the corresponding values are grouped into an attribute called trackClusterMatching_, of type TrackClusterMatching. One will see this attribute when TBrowsing an edm ROOT file. The global getter CMS.GsfElectron::trackClusterMatching() gives direct access to the attribute.

Track extrapolations

Normal block of related quantities:

  • math::XYZPoint  trackPositionAtVtx(): the track PCA to the beam spot, extrapolating from the innermost track state.
  • math::XYZVector trackMomentumAtVtx(): the track momentum at the PCA to the beam spot.
  • math::XYZPoint  trackPositionAtCalo(): the track PCA to the supercluster position, extrapolating from the innermost track state.
  • math::XYZVector trackMomentumAtCalo(): the track momentum at the PCA to the supercluster position, extrapolated from the innermost track state.
  • math::XYZVector trackMomentumOut(): the track momentum at the PCA to seed cluster position, extrapolated from the outermost track state.
  • math::XYZVector trackMomentumAtEleClus(): the track momentum at PCA to the ele cluster position, extrapolated from the outermost track state.
  • math::XYZVector trackMomentumAtVtxWithConstraint(): the track momentum at the PCA to the beam spot using the beam spot constraint.

Within the electron, the corresponding values are grouped into an attribute called trackExtrapolations_, of type TrackExtrapolations. One will see this attribute when TBrowsing an edm ROOT file. The global getter CMS.GsfElectron::trackExtrapolations() gives direct access to the attribute.

Supercluster direct access

Just few methods which help you get information from the associated supercluster.

    math::XYZPoint superClusterPosition() const { return superCluster()->position() ; } // the super cluster position
    int basicClustersSize() const { return superCluster()->clustersSize() ; } // number of basic clusters inside the supercluster
    CaloCluster_iterator basicClustersBegin() const { return superCluster()->clustersBegin() ; }
    CaloCluster_iterator basicClustersEnd() const { return superCluster()->clustersEnd() ; }

Other tracks

Here, one will get access to other tracks than the main GSF track used to evaluate electron quantities and which have been attached to the electron. The closest CTF track is given together with its fraction of common hits with the main GSF track. One will also find the list of ambiguous GSF tracks coming from previously reconstructed electrons that were filtered out by the ambiguity resolution (cleaning of overlapping reconstructed electrons).

  • TrackRef closestCtfTrackRef(): get the CTF track best matching the GSF track associated to this electron.
  • float shFracInnerHits(): fraction of common hits between the GSF and CTF tracks.
  • GsfTrackRefVector::size_type ambiguousGsfTracksSize(): number of ambiguous GSF tracks.
  • GsfTrackRefVector::const_iterator ambiguousGsfTracksBegin(): iterator to the first ambiguous GSF track.
  • GsfTrackRefVector::const_iterator ambiguousGsfTracksEnd(): iterator after the last ambiguous GSF track.

Within the electron, the closest CTF track and corresponding fraction of common hits are grouped into an attribute called closestCtfTrack_, of type ClosestCtfTrack. One will see this attribute when TBrowsing an edm ROOT file. The global getter CMS.GsfElectron::closestCtfTrack() gives direct access to the attribute. When TBrowsing, one will also see the vector of ambiguous tracks called ambiguousGsfTracks_. Currently no getter gives direct access to the vector.

Fiducial flags

Block of flags about where the electron is impiging the ECAL. They are based on the position of the seed Xtal of the seed cluster of the supercluster relative to ECAL detector boundaries:

  • bool isEB(): true if the electron is in ECAL Barrel.
  • bool isEE(): true if the electron is in ECAL Endcaps.
  • bool isEBEEGap(): true if the electron is in the crack between EB and EE.
  • bool isEBEtaGap(): true if the electron is in EB, and in the eta gaps between modules.
  • bool isEBPhiGap(): true if the electron is in EB, and in the phi gaps between modules.
  • bool isEEDeeGap(): true if the electron is in EE, and in the gaps between dees.
  • bool isEERingGap(): true if the electron is in EE, and in the gaps between rings.

Within the electron, the corresponding values are grouped into an attribute called fiducialFlags_, of type FiducialFlags. One will see this attribute when TBrowsing an edm ROOT file. The global getter CMS.GsfElectron::fiducialFlags() gives direct access to the attribute. Also, a few more utility methods are combining some of the flags:

  • bool isEBGap(): true if isEBEtaGap() or isEBPhiGap().
  • bool isEEGap(): true if isEEDeeGap() or isEERingGap().
  • bool isGap(): true if isEBEEGap() or isEBGap() or isEEGap().

Shower Shape Variables

Normal block:

  • float sigmaEtaEta(): weighted cluster rms along eta and inside 5x5 (absolute eta).
  • float sigmaIetaIeta(): weighted cluster rms along eta and inside 5x5 (Xtal eta index).
  • float e1x5(): energy inside 1x5 in etaxphi around the seed Xtal.
  • float e2x5Max(): energy inside 2x5 in etaxphi around the seed Xtal (max bwt the 2 possible sums).
  • float e5x5(): energy inside 5x5 in etaxphi around the seed Xtal.
  • float hcalDepth1OverEcal(): hcal over ecal seed cluster energy using first hcal depth (hcal is energy of towers within dR=015).
  • float hcalDepth2OverEcal(): hcal over ecal seed cluster energy using 2nd hcal depth (hcal is energy of towers within dR=015).

Within the electron, the corresponding values are grouped into an attribute called showerShape_, of type ShowerShape. One will see this attribute when TBrowsing an edm ROOT file. The global getter CMS.GsfElectron::showerShape() gives direct access to the attribute. Also, one utility method is combining some of the stored values:

  • float hcalOverEcal() const { returns hcalDepth1OverEcal()+hcalDepth2OverEcal() ; }

Isolation Variables

The methods here have two flavors, one for an outer isolation cone of 03 and one for an outer isolation cone of 04:

  • float dr03TkSumPt(): track iso deposit with electron footprint removed.
  • float dr03EcalRecHitSumEt(): ecal iso deposit with electron footprint removed.
  • float dr03HcalDepth1TowerSumEt(): hcal depht 1 iso deposit with electron footprint removed.
  • float dr03HcalDepth2TowerSumEt(): hcal depht 2 iso deposit with electron footprint removed.

  • float dr04TkSumPt()
  • float dr04EcalRecHitSumEt()
  • float dr04HcalDepth1TowerSumEt()
  • float dr04HcalDepth2TowerSumEt()

Within the electron, the corresponding values are grouped into two attributes called dr03_ and dr04_, of type IsolationVariables. One will see those attributes when TBrowsing an edm ROOT file. The global getters CMS.GsfElectron::dr03IsolationVariables() and CMS.GsfElectron::dr04IsolationVariables() gives direct access to the attributes. Also, two utility methods are adding on the fly the two depth fo hcal:

  • float dr03HcalTowerSumEt() const { return dr03HcalDepth1TowerSumEt()+dr03HcalDepth2TowerSumEt() ; }
  • float dr04HcalTowerSumEt() const { return dr04HcalDepth1TowerSumEt()+dr04HcalDepth2TowerSumEt() ; }

Particle Flow Data

The single method mva() returns the value of the single attribute mva_, that one will see when TBrowsing an edm ROOT file. This value is provided by pflow algorithm, and has been primarily tuned for the identification of electrons in jets. It is computed for all the gsf tracks which are made from the merged set of seeds, both ecal and tracker driven. The possible values are:

  • [-1,1]: normal case.
  • [-3,-1]: PFElectronAlgo substract 2 when the Ecal cluster is not isolated (other kf tracks hitting the same cluster).
  • [-5,-3]: PFElectronAlgo substract 4 when E/p < 0.5 and H/(H+E) > 0.1 .
  • -2 : reserved value for the gsf tracks which have no PFSuperCluster associated.
  • -99 : reserved value the gsf tracks cleaned because of the duplicates removal done in PFElecTkProducer.

Brem fraction and classification

Few related values:

  • float fbrem(): the brem fraction from the gsf fit, ie (track momentum in - track momentum out) / track momentum in.
  • int numberOfBrems(): this utility method returns the number of basic clusters minus one.
  • Classification classification(): electron classification based on the two above values.

The Classification type is an enumeration:

  • UNKNOWN
  • GOLDEN: electrons with a track very well matching a supercluster made out of a single basic cluster; they are the electrons the least affected by bremsstralhung radiation; their energy resolution is shown to be close to the one of electrons in test beam.
  • BIGBREM: electrons with a track well matching a supercluster made out of a single basic cluster but with a very large value of the measured brem fraction.
  • NARROW: electrons with a track rather well matching a supercluster made out of a single basic cluster and with an intermediate value of the measured brem fraction.
  • SHOWERING: electrons with a track badly matching a supercluster made out of a single basic cluster or with a supercluster consisting of several basic clusters. This class corresponds to the worst measured electrons, with track-cluster patterns characteristic of electrons having encountered severe bremsstrahlung in the tracker material.
  • GAP: electrons impinging the ECAL close to detector boundaries (see above description of fiducial flags).

Within the electron, the corresponding values are staying into the two attributes fbrem_ and class_ (the number of brems is computed on the fly). One will see those attributes when TBrowsing an edm ROOT file. Worth to note: exceptionally, the electron classification is not set when constructing the object, but later on thanks to the setter:

  • void classifyElectron( Classification )

Corrections

Methods of this block helps to know which electron characteristics have been corrected or not, and what are the associated errors. If momentum has been corrected, the new value has replaced the old one in the attribute inherited from LeafCandidate. On the contrary, the ecal energy cannot be changed inplace in the supercluster and is stored in a dedicated GsfElectron attribute. The latter is initialized with the super cluster energy, and will keep this value if the ecal energy is not applied. A rule of thumb here is that when an electron attribute is corrected, the other dependent attributes are upgraded. As a consequence, the values of attributes to which a corrected value of the energy has been propagated (hcalDepth1OverEcal, hcalDepth2OverEcal, eSuperClusterOverP, eSeedClusterOverP, eEleClusterOverPout) can in principle be slightly different to the values used at the preselection stage. Currently there is no electron level energy correction (ie the flag below is false) and none of these variables are actualy used in the preselection.

Here are the accessors defined in this block:

  • bool isEcalEnergyCorrected(): true if ecal energy has been corrected.
  • float ecalEnergy(): the new corrected value, or the supercluster energy.
  • float ecalEnergyError()

  • bool isMomentumCorrected(): true if E-p combination has been applied.
  • float trackMomentumError(): track momentum error from gsf fit.
  • float electronMomentumError(): the final electron momentum error.

Within the electron, those flags, errors and ecal energy of this block are grouped into the attribute called corrections_, of type Corrections. One will see this attribute when TBrowsing an edm ROOT file. The global getter CMS.GsfElectron::corrections() gives direct access to the attribute.

At last, here are the setters for the corrections. They are expected to be called in the specified order, and after classifyElectron() defined in previous block:

  1. correctEcalEnergy( float newEnergy, float newEnergyError ): depending on classification and eta.
  2. correctMomemtum( const LorentzVector & momentum, float trackMomentumError, float electronMomentumError ): depending on classification and ecal energy and tracker momentum errors.

Constructors

This special block contains the main constructor, where almost all electron attributes have to be provided. The draw-back is that one must prepare all values before he constructs the object. The benefit is that, provided that the interface has no setters, one can ensure the attribute values will not be changed later on. Especially, since many of those values are used when choosing to keep or not an electron (preselection), one can be confident that each value stay stable and consistent with the cuts applied.

In such a design where the electron objects are rather immutable, it is important to have relevant cloning methods for the few use-cases which needs to duplicate the electrons. Currently, the only cloning method is shallow (only the top level object is cloned, not the lower-level objects it is pointing at). A more sophiticated cloning is under investigation.

    CMS.GsfElectron
     (
      const LorentzVector & p4, int charge, const GsfElectronCoreRef &,
      const TrackClusterMatching &, const TrackExtrapolations &, const ClosestCtfTrack &,
      const FiducialFlags &, const ShowerShape &, float fbrem, float mva
     ) ;
    CMS.GsfElectron * clone() const ;

Here are the few values and corrections not to be given to the constructor but set after the object construction:

  • ambiguous tracks,
  • isolation (dr03 and dr04),
  • classification,
  • corrections.

Review status

Reviewer/Editor and Date (copy from screen) Comments
DavidChamont - 17 Aug 2009 Creation of the page.

Responsible: DavidChamont

Edit | Attach | Watch | Print version | History: r23 < r22 < r21 < r20 < r19 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r23 - 2010-02-25 - DavidChamont
 
    • Cern Search Icon Cern Search
    • TWiki Search Icon TWiki Search
    • Google Search Icon Google Search

    CMSPublic All webs login

This site is powered by the TWiki collaboration platform Powered by PerlCopyright & 2008-2019 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback