Kinematic Resolutions in PAT

Complete: 2

Quick start

This twikipage describes the tools to work with the resolutions on kinematic variables in PAT and in CMSSW in general.

For a reconstructed particle one can parametrize the deviation of the measured four-momentum w.r.t the true one in any coordinate frame (e.g. cartesian, polar, ...); in any case there will be always 3 or 4 independent degrees of freedom (depending whether the mass of the particle is fixed or not), so that a 3x3 or 4x4 symmetric covariance matrix can be used.
Depending on the detector and reconstruction algorithm, there is normally one parametrization which is more suited for a given reconstructed object, because it has less non-gaussian tails and/or smaller off-diagonal terms in the covariance matrix.

Resolutions and Derivatives
Given a parametrization and a covariance matrix for an object, it's possible to extract from it the resolution on all possible kinematic variables.
For kinematic variables that are directly used as coordinates in that parametrization, these resolutions the square roots of the diagonal elements of the covariance matrix (e.g. px if using cartesian coordinates, or phi in polar ones). Otherwise, the error propagation formulas with derivatives can be used to compute the resolution: e.g. sigma(pt) = sigma(p) * sin(theta) + p * sigma(theta) cos(theta) -- where the sum is done in quadrature.

Kinematic Resolution Objects: pat::CandKinResolution
The kinematic resolution object defined by PAT contains the minimal set of information to describe the kinematic resolutions:

  • the choice of parametrization used
  • the covariance matrix of the parameters (or only it's diagonal part if the off-diagonal one is declared to be negligible)
  • the value of the constrains, if any (e.g. the mass of the particle)
A CandKinResolution object can be constructed either from a full 4x4 covariance matrix in double precision (c++ type AlgebraicSymMatrix44 ) or from a std::vector<float> with the diagonal terms of the matrix (3 or 4 depending on the parametrization).
From such object is possible to get the resolution on these kinematic variables: E, Et, P, Pt, 1/P, Eta, Theta, Phi, M, Px, Py, Pz . As the computation of the resolution might require to compute some derivatives, you need to provide also the four-vector of the object (it is not saved within the CandKinResolution object)

Resolutions embedded in PAT Objects
PAT Objects can carry CandKinResolution objects, to be used in the analysis (e.g. for kinematic fits). It is possible to retrieve directly from the PAT Object the resolutions on a given parameter (e.g. muon.resolPt() ), or the full CandKinResolution object.
Multiple CandKinResolution objects can be stored in the same PAT object, e.g. extracted from different algorithms or samples, for more detailed studies; in that case, the methods to retrieve resolutions will require you to specify also a label identifying the CandKinResolution object.

Working with Parametrizations

Definitions of parametrization

The CandKinResolution object allows to use basically all parametrizations known to the KinFitter library (CMS AN-2005/025 ).
Name free parameters constraints notes
Cart px, py, pz, m none (1)
ECart px, py, pz, e none (1)
MCCart px, py, pz m  
Spher p, theta, phi, m none (1)
ESpher p, theta, phi, e none (1)
MCSpher p, theta, phi m  
!MCPInvSpher 1/p, theta, phi m  
!EtThetaPhi et, theta, phi m m must be zero
!EtEtaPhi et, eta, phi m m must be zero
!MomDev p/P0, dptheta, dpphi, m/M0 none (2)(3)
!EMomDev p/P0, dptheta, dpphi, e/M0 none (2)(3)
!MCMomDev p/P0, dptheta, dpphi m (2)(3)
!EScaledDev p/P0, dptheta, dpphi, e/M0 none (2)(3)


  • (1) KinFitter uses as fourth parameter not the absolute deviation of the mass or energy but the relative one.
  • (2) For the definition of these parametrizations, see CMS AN-2005/025
  • (3) These parametrizations can be used in kinematic fits, but currently it's not possible to extract the individual resolutions on individual kinematic variables from them.

Operations on parametrizations

For a given parametrization, there are two fundamental operations:

  • determine the difference between two 4-vectors as a shift in the parameters
  • given a 4-vector and a shift in parameters, construct a new 4-vector
For most parametrizations it does also make sense to convert from a lorentz vector to a plain vector holding the 4 parameters and vice-versa.

In order to ease the work with parametrization, a helper tool !ParametrizationHelper is provided in the pat::helper:: namespace.

The most important functions provided are:

  • parametersFromP4 : convert a single vector from parameter space to lorentz space. In case of the momentum deviation parameters from KinFitter, it will just return a dummy parameter vector (1,0,0,0) .
  • p4fromParameters, polarP4fromParameters : given a set of parameters and a refererce four-vector, build a new four-vector. The reference four vector is needed to get the values of the missing parameter when using constrained parametrization (e.g. to determine the mass), or to work with momentum deviation parameters.
  • diffToParameters : extract the difference between two parameters as a shift in coordinates in a given frame.
  • isPhysical : given a set of parameters and a reference four-vector, checks if the addition of the two remains within the physical space (this can be necessary when writing e.g. a smearing module). This will only check basic inequalityes (E >= P; E &g;= M >= 0; theta in [0, pi] range, ...), it will not check strict equalities nor constraints.

Here is an example snipped of code that should clarify the usage of the above methods.

    using namespace pat::helper::ParametrizationHelper;
    reco::GenParticle  & sim = ...
    reco::Candidate   & rec = ...
    pat::CandKinResolution::Parametrization param = pat::CandKinResolution::MCSpher; // choose parametrization
    AlgebraicVector4 pars = parametersFromP4(param, sim.polarP4());

    // difference reco - sim as shift in parameters
    AlgebraicVector4 diff   = diffToParameters(param, sim.polarP4(), rec.polarP4());

    // check that adding back reco-sim on top of sim I'm still in the physical region
    if ( !isPhysical(param, pars + diff, simP4) )   { /* complain; */ }

    // remake reco P4 as sim parameters + shift (using simP4 as reference 4-vector)
    math::PtEtaPhiMLorentzVector recP4 = polarP4fromParameters(param, pars + diff, simP4);
    // now recP4 is equal to reco.polarP4() , up to round-off errors

There are some additional convenience functions:

  • to convert from a parametrization code to a string and vice-versa
  • to tell the number of degrees of freedom of a parametrization
  • to tell if a given parametrization is mass constrained (this includes the ones that require zero mass)
  • to tell if a given parametrization allows massive or massless four-vectors (currently the only one that disallows massless 4-vectors is !MomDev )

Working with Resolutions

All the math to compute resolutions in a given coordinate frame is done by a ResolutionHelper, which is used internally from the CandKinResolution object

The only function provided by this helper that can be useful to outside is rescaleForKinFitter that will rescale a 4x4 covariance matrix accordingly to take care of the difference in how parameters are defined: see note (1) of the paragraph "Definitions of parametrization" above.

Resolution providers and records

While CandKinResolution objects can be crafted by hand if needed, the standard resolutions will be distributed using resolution providers to decouple the code computing the resolution from the code that uses it.

A KinematicResolutionProvider is an generic base class that defines the interface of code computing resolutions. It has two methods:

  • pat::CandKinResolution getResolution(const reco::Candidate &c) const that must be implemented to put the specific logic that computes the resolution for the candidate (e.g. by using the candidate's parameters to lookup in a histogram)
  • void setup(const edm::EventSetup &iSetup) const this method by default does nothing, but can be implemented if the resolution provider needs access to EventSetup stuff. Note that the method must be const because the KinematicResolutionProvider lives in the EventSetup; if you need to modify datamembers of the provider, declare them as mutable , or use const_cast .
The header file for this class is CMS.PhysicsTools/PatAlgos/interface/KinematicResolutionProvider.h

KinematicResolutionProviders live the EventSetup record KinematicResolutionRcd (defined in CMS.PhysicsTools/PatAlgos/interface/KinematicResolutionRcd.h )

Accessing resolution from the EventSetup

Here is an example of how you can get a kinematic resolution object from the EventSetupin your code

#include "CMS.PhysicsTools/PatAlgos/interface/KinematicResolutionProvider.h
#include "CMS.PhysicsTools/PatAlgos/interface/KinematicResolutionRcd.h"

void MyAnalyzer::analyze(const edm::Event &iEvent, const edm::EventSetup &iSetup) {
       edm::ESHandle<KinematicResolutionProvider> provider;
       iSetup.get<KinematicResolutionRcd>().get(providerName_, provider);

       provider->setup(iSetup); // this might be needed for some providers

       const reco::Candidate &cand = ...
       pat::CandKinResolution reso =  provider->getResolution(cand);


Embedding resolutions in PAT Objects

Another possibility is to have these kinematic resolutions retrieved from the EventSetupand saved into PAT Objects, so that they can be inspected later also with FWLite.

This can be done simply by setting some parameters in the PAT object producer (the patXYZs for pat::XYZ).

The configuration changes are simply (example for jets)

process.patJets.addResolutions = True
process.patJets.resolutions = cms.PSet( default = cms.string("theProviderName") )

Of course, you need also to load also some cff file where the resolution provider is defined, e.g. coming from the POG.

If you want to specify multiple resolutions with their labels, just put extra entries in the cms.PSet

process.patJets.resolutions = cms.PSet( 
       default = cms.string("theProviderName"),  
       myfit   = cms.string("myOtherProvider"),  
and afterwards you will have jet.resolEt() returning the output of the theProviderName and jet.resolEt("myfit") returing the one of myOtherProvider .

Simple resolution provider using string functions

A simple resolution provider using string functions is included in PAT.

An example configuration of the module using some random resolution functions, is

process.jetResolutions = cms.ESProducer("StringResolutionProviderESProducer",
    parametrization = cms.string("EtEtaPhi"),  # specify the parametrization you want
    functions       = cms.VPSet(
            # selection string (See SWGuidePhysicsCutParser for details)
            # optional but needed if more than one PSet is specified
            bin = cms.string("0.87<=abs(eta) && abs(eta)<1.74"),
            # define resolution functions of each parameter
            et  = cms.string("et * (sqrt(0.08^2 + (1./sqrt(et))^2 + (5./et)^2))"), # sigma(Et); NOT sigma(Et)/Et !
            eta = cms.string("sqrt(0.008^2 + (1.5/et)^2)"),                        # sigma(Eta); also note that "+" is normal sum, not in quadrature!
            phi = cms.string("sqrt(0.008^2 + (2.6/et)^2)"),                        # sigma(Phi)
    constraints     = cms.vdouble(0), # Constraints if needed; e.g. EtEtaPhi is constrained to have mass == 0
This cfg fragment will put in the EventSetup a resolution provider with name jetResolutions .

Writing your own KinematicResolutionProvider

In order to write a new KinematicResolutionProvider, you need to define both the class for it and the ESProducer which will deliver it to framework.

Defining your provider is easy

#include "CMS.PhysicsTools/PatAlgos/interface/KinematicResolutionProvider.h

class MyResolutionProvider : public KinematicResolutionProvider {
       MyResolutionProvider (const edm::ParameterSet &iConfig) ; // you're actually free to decide what arguments does the constructor take
       virtual ~MyResolutionProvider() ;                                      // define a destructor, that might as well do nothing at all

       /// this is what you really have to code
       virtual pat::CandKinResolution getResolution(const reco::Candidate &c) const ;

       /// this you might want, or you might not.
       // void setup(const edm::EventSetup &iSetup) const 

       ... // whatever data you might need

Defining the ESProducer is likewise an easy task (even if a bit boring)

#include <FWCore/Framework/interface/ESProducer.h>
#include <FWCore/ParameterSet/interface/ParameterSet.h>

#include "CMS.PhysicsTools/PatAlgos/interface/MyResolutionProvider.h"
#include "CMS.PhysicsTools/PatAlgos/interface/KinematicResolutionRcd.h"

class MyResolutionProviderESProducer : public edm::ESProducer
                MyResolutionProviderESProducer() { }
                MyResolutionProviderESProducer(const edm::ParameterSet &iConfig) ;

                std::auto_ptr<KinematicResolutionProvider>  produce(const KinematicResolutionRcd &rcd) ;

                ... // whatever you need... perhaps nothing at all

MyResolutionProviderESProducer::MyResolutionProviderESProducer(const edm::ParameterSet &iConfig) 
   // declare that you will produce a KinematicResolutionProvider with the same name as the module label of this producer
   std::string myName = iConfig.getParameter<std::string>("@module_label");

MyResolutionProviderESProducer::produce(const KinematicResolutionRcd &rcd) {
        return std::auto_ptr<KinematicResolutionProvider>(new MyResolutionProvider(....));

#include "FWCore/PluginManager/interface/ModuleDef.h"
#include "FWCore/Framework/interface/MakerMacros.h"
#include "FWCore/Framework/interface/ModuleFactory.h"
DEFINE_FWK_EVENTSETUP_MODULE( MyResolutionProviderESProducer );

Note that the ESProducer must go in a directory from which you build plugins (e.g. EDAnalyzers), while the record probably should go in a non-plugin directory (but I'm not sure if this is really required)

Review status

Reviewer/Editor and Date (copy from screen) Comments
GiovanniPetrucciani - 06 Apr 2009 basic description of resolution objects

Responsible: SWGuidePAT
Last reviewed by: HolgerEnderle

Edit | Attach | Watch | Print version | History: r4 < r3 < r2 < r1 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r4 - 2010-05-05 - HolgerEnderle
    • 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-2021 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
or Ideas, requests, problems regarding TWiki? use Discourse or Send feedback