Physics Cut and Expression Parser

Complete: 5


The Physics Cut and Expression Parser is an utility that allows to define cuts and expressions defining mathematical combination of object variables with a human-readable string. The string is parsed and interpreted in terms of Reflex member functions for a specific object type, and can be used to apply cuts at run time in configurable common modules, like with Generic Selectors.

Where it is currently used

It is used in common selector and combiner modules. Examples are:

Examples of string cut configurations

Modules using string cuts as parameters will have configurations similar to the following:

  goodMuons = cms.EDFilter("CandViewSelector",
    src = cms.InputTag("allMuons"),
    cut = cms.string("pt > 5.0")

where the cut "pt > 5.0" will be applied to select the "good" muon candidates.

Suppported operators and functions

The following variables and operators are supported. Parentheses can be used to disambiguate operator precedence.

Variables mapped to object methods or variables

Any method can be used as variable name to which apply cuts for a given object type provided that:

  • returns a value convertible to double
  • is not a modifier (i.e.: is declared as const)
  • requires either no arguments or constant arguments: integers, floating point numbers, strings (using either single or double quotes), and enums (entered as strings, with quotes)
  • just like in C++, you can omit arguments that have a default value
  • if the method takes no arguments, you can omit the braces (e.g. pt instead of pt() )

In addition public data members of classes can be accessed (e.g. the field emEt of a reco::MuonIsolation object)

Examples of valid variables are:

  • pt: calls
  • covariance(0, 0): calls object.covariance(0, 0)
  • nCarrying(0.4) calls the 'nCarrying' method of reco::Jet specifying the fraction of carried energy.
  • bDiscriminator("trackCountingBJetTags") on a pat::Jet calls the method bDiscriminator passing a string argument "trackCountingBJetTags"
  • isGood('AllGlobalMuons') calls the reco::Muon::isGood(reco::Muon::AllGlobalMuons) metod. the 'AllGlobalMuons' string is converted automatically into the enum value.
  • userIso() or userIso will call userIso(0) on a pat::Photon , as the method is defined as userIso(int index=0)

Reflex dictionary will be used to match variable names to methods.

Warning, important Some of these features are available only in the newest releases of CMSSW: Warning, important

  • Enums are supported only from tag PhysicsTools/Utilities V06-09-05 (which should be included in some 2.2.X, but is not in 2.2.3)
  • Public data members are supported only from 2.2.X release

Warning, important In some releases of CMSSW there are also known bugs affecting the StringParser: Warning, important

  • In 2.2.X release, but before tag PhysicsTools/Utilities V06-09-07 (not yet in CMSSW 2.2.3), methods that start like a function won't work (e.g. any method starting with min , max , abs ...)
  • In 2.1.X releases if a method is defined in a mother class and re-defined in a children class, it might not work. This is fixed in 2.2.X.

Note: you can check which tag of the parser are you using by just typing adding -q PhysicsTools/Utilities

Nested object methods

Methods that return objects by value, by reference or by pointer, or reference to objects (edm::Ref, edm::Ptr, edm::RefToBase) can be used to call subsequent object methods, provided that the subsequent method satisfies the conditions listed in the above section.

Examples of such calls are:

  • > 10:
    calls the C++ equivalent of object.track().pt() > 10, where track() returns an edm::Ref<reco::TrackCollection>
  • min(daughter(0).pt,daughter(1).pt):
    calls the C++ equivalent of std::min(object.daughter(0)->pt(), object.daughter(1)->pt()), where daughter(i) returns a pointer to a reco::Candidate.

Mathematical operators

The following operators are supported with the usual precedence:

  • +: addition
  • -: subtraction or unary minus sign
  • *: multiplication
  • /: division
  • ^: power raising

Mathematical functions

The following functions are supported:
  • abs(x): absolute value
  • acos(x): arc cosine
  • asin(x): arc sine
  • atan(x): arc tangent
  • atan2(y,x): arc tangent of ratio y/x using arguments sign
  • chi2prob(c2,ndf): the integrated probability of having a chi-square greater than c2 with ndf degrees of freedom (ROOT::Math::chisquared_prob(c2,ndf)).
  • cos(x): cosine
  • cosh(x): hyperbolic cosine
  • exp(x): exponential
  • log(x): natural logarithm
  • log10(x): base-10 logarithm
  • min(x, y): smallest element
  • max(x, y): largest element
  • pow(x,y): power raising (identical to x^y)
  • sin(x): sine
  • sinh(x): hyperbolic sine
  • sqrt(x): square root
  • tan(x): tangent
  • tanh(x): hyperbolic tangent

Comparison operators

The following comparison operators are supported:
  • =: equal to
  • !=: not equal to
  • >: greater than
  • >=: greater or equal than
  • <: less than
  • <=: less or equal than

Starting from the tag V06-05-10 (CMSSW 2.1.7 and later) the following C-like operator is also supported:

  • ==: equal than

Boolean operators

The following boolean operators are supported with the usual precedence:
  • &: logical AND
  • |: logical OR
  • !: logical NOT

Starting from the tag V06-05-10 (CMSSW 2.1.7 and later) the following C-like operators are also supported:

  • &&: logical AND
  • ||: logical OR

Using the string-configurable generic object selector

For a type T, a generic selection functor is defined with the type:
  • StringCutObjectSelector<T>

It returns true or false if an object passes or fails a selection specified as a string a constructor parameter.

It can be used as follows:

   StringCutObjectSelector<reco::Track> select( "pt > 15.0 & abs(eta) < 2");
   reco::Track trk = ...; // get a track
   bool pass = select( trk );
   if( pass ) { /* ... */ }

Using the string-configurable generic object function

For a type T, a generic selection functor is defined with the type:

  • StringObjectFunction<T>

It returns for any object passed, the value of an expression specified as a string a constructor parameter.

It can be used as follows:

   StringObjectFunction<reco::Track> f( "px^2+py^2");
   reco::Track trk = ...; // get a track
   double ptSquare = f( trk );

Caveat with EDM provenance tracking system

The string-based cuts and expressions can be used with framework modules, and the specified cuts or expressions will be saved in the event files within the provenance tracking system.

Anyway, users should be aware that the cuts will be saved as string, so deriving the numeric values of the specified cuts will be a non-trivial operation because it will require a parsing of the cut string.

Performance issues

Parsing the expression string is done only once, usually in the constructor of selector and function objects, so it does not add significant overhead, provided that the same selector or function object is kept for more events.

What may cause a slight performance loss is the actual evaluation of expression. The parses, in fact, creates a composite structure in memory that invokes a virtual function call for every syntactical element in the expression.

Moreover, the passed object (track, in the example) has to be "converted" into a Reflex object in order to be evaluated.

Those two elements may be cause some performance overhead for critical applications, like HLT. For those application, compiled C++ expressions are expected to have better CPU performances.

For those analysis applications where configuration flexibility is an advantage w.r.t. extreme speed, those issues may be not important.

Review Status

Editor/Reviewer and date Comments
LucaLista - 08 Jan 2008 page author

Responsible: LucaLista
Last reviewed by:

Edit | Attach | Watch | Print version | History: r23 | r21 < r20 < r19 < r18 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r19 - 2009-05-06 - BenediktHegner

    • 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