Trigger Information in the PAT

Complete: 5

TIP This documentation refers to CMS.PhysicsTools/PatAlgos V08-09-04 (CMSSW_5_2_X).

Older tags -- also referring to PAT tutorials -- are found in the release notes.

TIP For twisted sections:

Introduction

The Aim of PAT-Specific Trigger Information

The trigger information as it comes with the RECO or AOD data tiers has been optimized for storage efficiency. This was reached for the cost of reduced user friendliness, since the information is:

  • split over several information sources;
  • partially complicated to access;
  • generally complicated to relate different types of information to each other.

The PAT trigger data formats have been designed as a complementary solution to provide easy and user friendly access to the same information, plus matching of trigger to reconstructed objects (PAT objects). This was reached also by paying the cost of an increased event size. However, since the PAT trigger information can be produced at the very end of an analysis tuple production chain, it does not come into conflict with the need of storage efficiency of any official production with persistent output. It is rather meant to be run by the users themselves if desired. So it aims for a maximum of flexibility, but also for user friendliness of the configuration.

General Information Sources for the User

In order to prepare oneself, the following information sources can be consulted:

  • CMS RunSummary (preferred for data):
    This applet provides information on particular runs, especially the used L1 and HLT keys. The links provided for those keys give access to detailed information, like e.g. an overview over used HLT paths etc.
  • TriggerSummaryAnalyzerAOD (data & MC):
    This useful little module provides information on HLT from the provenance and prints it.
    TIPSearch its output for " HLTConfigVersion " in order to find the HLT key.
    The usage of the module is demonstrated in
import FWCore.ParameterSet.Config as cms
process = cms.Process( "HLTPROV" )
# Conditions
process.load("Configuration.StandardSequences.FrontierConditions_GlobalTag_cff")
from Configuration.PyReleaseValidation.autoCond import autoCond
process.GlobalTag.globaltag = cms.string( autoCond[ 'startup' ] )
# Source
from PhysicsTools.PatAlgos.tools.cmsswVersionTools import pickRelValInputFiles
process.source = cms.Source("PoolSource",
  fileNames = cms.untracked.vstring(
    pickRelValInputFiles() # <-- picks automatically RelVal input files for the current release
  )
)
process.maxEvents = cms.untracked.PSet( input = cms.untracked.int32( 1 ) )
# Trigger analyzers
process.load( "HLTrigger.HLTcore.hltEventAnalyzerAOD_cfi" )
process.hltEventAnalyzerAOD.triggerName = cms.string( '@' ) # <-- wild-card for all HLT paths
# Schedule
process.p = cms.Path( process.hltEventAnalyzerAOD )
  • L1GtTrigReport (data & MC):
    This module provides information on L1 from the setup and data and prints it.
    Its usage is demonstrated in L1Trigger/GlobalTriggerAnalyzer/test/L1GtAnalyzer_cfg.py.
  • HLT Config Browser (data & MC) :
    Knowing the HLT key, one can browse the detailed HLT configuration here.
    TIPThe HLT configurations used for data are found in the tab ORCOFF, MC configurations are (currently) found under HLT Development.
    It gives access to:
    • configuration details, sorted for paths, sequences, modules, services, etc.;
    • trigger summary, accumulating L1 seeds and used filters for each path;
    • streams, giving information about primary datasets, paths, pre-scales and L1 conditions.

Original Data Sources UPDATED

The PAT uses the EDM data tier AOD as input. This provides trigger information (for the default HLT process name HLT) as follows:

  • several collections *_l1extraParticles_*_* of varyious types:
    • L1 trigger objects;
  • event setup of type L1GtTriggerMenu from CondDB:
    • L1 trigger algorithms, incl. prescales;
  • collection *_gtDigis_*_* of type L1GlobalTriggerReadoutRecord:
    • global trigger bits:
      • PhysDecl
    • HLT (dynamic) prescale set index in use;
  • collection *_l1L1GtObjectMap_*_* of type L1GlobalTriggerObjectMaps UPDATED:
    • L1 conditions and a part of the algorithms' information
    • links between L1 algorithms, conditions and objects
      ALERT! Only objects, which belong to a succeeding combination of a condition are linked.
  • collections edmConditionsIn{Event,Lumi,Run}Block_conditionsInEdm_*_*:
    • data taking conditions information
  • collection *_TriggerResults_*_HLT of type edm::TriggerResults:
    • HLT paths (no prescale information)
  • event setup of type ??? from CondDB:
    • HLT pre-scale set
  • collection *_hltTriggerSummaryAOD_*_HLT of type trigger::TriggerEvent:
    • HLT (L3) filters;
    • HLT objects
      ALERT! Only objects, which passed single object cuts of the HLT filters are stored, independently of the minimum number of objects required by the filter to succeed or the filter's result itself;
    • links between filters and objects;
  • Provenance:
    • links between HLT paths and filters;
    • (generic) modules in paths;

Concepts

Information organization

In the PAT trigger information, inks between different entities are saved "top-down", which means:

  • HLT paths resp. L1 algorithms know, which HLT filters resp. L1 conditions belong to them;
  • HLT filters resp. L1 conditions know, which HLT resp. L1 objects they have used.

HLT objects are restricted to fulfill the criteria of the filter they have been used in, where the number of evaluated objects is neglected. This means that e.g. a jet passing the Et cut of a di-jet filter is stored, even if the filter failed, due to the lack of a second sufficient jet.

Usage

The main conceptional design choice accounts for the desired user friendliness of the information access:

Access everything from one central entry point.

The class TriggerEvent provides this possibility by holding links to all other PAT trigger products and by making available not only direct access methods, but also methods to relate different informations to each other (x-links). Due to this design, the other PAT trigger data formats do not need much more methods than the usual setters & getters to access their data members.

Data Formats

In this section, the PAT trigger data formats as implemented in the DataFormats/PatCandidates package are described. These description explain data members, constructors and methods.

Special emphasis is put onto the explanation of the TriggerEvent methods, since they provide access to the complete PAT trigger information and are the central entry point for analysis users.

All data formats described here are members of the pat namespace within CMSSW. However, the namespace is omitted in the code snippets, just like a using namespace pat; directive has been used.

TriggerObject

The TriggerObject class inherits from reco::LeafCandidate.

Type definitions

  • typedef std::vector< TriggerObject > TriggerObjectCollection:
    collection of TriggerObject to be stored in the event;
  • typedef edm::Ref< TriggerObjectCollection > TriggerObjectRef:
    persistent reference to an item in a TriggerObjectCollection;
  • typedef edm::RefProd< TriggerObjectCollection > TriggerObjectRefProd:
    persistent reference to a TriggerObjectCollection product,
    used as data member of the TriggerEvent;
  • typedef edm::RefVector< TriggerObjectCollection > TriggerObjectRefVector:
    vector of persistent references to items in a TriggerObjectCollection;
  • typedef std::map< std::string, TriggerObjectRef > TriggerObjectMatchMap:
    container to store mapped references to TriggerObject,
    used to identify trigger object matches to a given PAT object by match producer module label;
  • typedef edm::Association< TriggerObjectCollection > TriggerObjectMatch:
    associates reco::Candidate (PAT objects) to items in a TriggerObjectCollection,
    used to store the trigger object matches in the event;
  • typedef edm::RefProd< TriggerObjectMatch > TriggerObjectMatchRefProd:
    persistent reference to a TriggerObjectMatch product;
  • typedef std::map< std::string, TriggerObjectMatchRefProd > TriggerObjectMatchContainer:
    container to store mapped reference to TriggerObjectMatch products,<
    used as data member of the TriggerEvent.

Additional data members

  • std::string collection_:
    label of the collection of origin;
  • std::vector< trigger::TriggerObjectType > triggerObjectTypes_:
    trigger object types assigned to this object as defined in DataFormats/HLTReco/interface/TriggerTypeDefs.h.
  • reco::CandidateBaseRef refToOrig_:
    reference to the to original trigger object based on reco::Candidate, meant for l1extra particles to access their additional functionalities.

  • The inherited data member pdgId_ is used correspondingly to the data member id_ of trigger::TriggerObject ("physics type").

Constructors

  • TriggerObject():
    default contructor.
  • TriggerObject( const trigger::TriggerObject& aTrigObj ):
    constructor from trigger object as stored in AOD.
  • TriggerObject( const reco::LeafCandidate & leafCand ):
    constructor from the inherited data format.
  • TriggerObject( const reco::CandidateBaseRef & candRef ):
    constructor from base reference to reco::Candidate, meant for l1extra particles.
  • TriggerObject( const reco::Particle::LorentzVector& vec, int id = 0 ) and
    TriggerObject( const reco::Particle::PolarLorentzVector& vec, int id = 0 ):
    constructors from Lorentz vectors and "PDG ID" (s. above);

Additional methods (beside usual setters & getters)

  • bool hasCollection( const edm::InputTag & coll ),
    bool hasCollection( const std::string & coll ) and
    bool coll( const std::string & coll ) ( * ):
    checks, if a certain label of original collection is assigned
    TIP works also without specifying the process name (but be aware of instances).
  • bool hasTriggerObjectType( trigger::TriggerObjectType triggerObjectType ),
    bool hasTriggerObjectType( int triggerObjectType ),
    bool type( trigger::TriggerObjectType triggerObjectType ) ( * ) and
    bool type( int triggerObjectType ) ( * ):
    checks, if a certain trigger object type is assigned.
  • const reco::CandidateBaseRef & origObjRef():
    provides the reco::Candidate base reference to the original l1extra particle.
  • const reco::Candidate * origObjCand():
    provides the reco::Candidate base of the original l1extra particle.
  • const l1extra::L1EmParticleRef origL1EmRef():
    provides the full reference to the original l1extra::L1EmParticle;
    returns an empty reference, if the objects is not an l1extra::L1EmParticle.
  • const L1GctEmCand * origL1GctEmCand():
    provides the original L1 object;
    returns 0, if the objects is not an l1extra::L1EmParticle or the original L1 object cannot be found.
  • const l1extra::L1EtMissParticleRef origL1EtMissRef():
    provides the full reference to the original l1extra::L1EtMissParticle;
    returns an empty reference, if the objects is not an l1extra::L1EtMissParticle.
  • const L1GctEtMiss  * origL1GctEtMiss():
    provides the original L1 object;
    returns 0, if the objects is not an l1extra::L1EtMissParticle or is not of ET type or the original L1 object cannot be found.
  • const L1GctEtTotal * origL1GctEtTotal():
    provides the original L1 object;
    returns 0, if the objects is not an l1extra::L1EtMissParticle or is not of ET type or the original L1 object cannot be found.
  • const L1GctHtMiss * origL1GctHtMiss():
    provides the original L1 object;
    returns 0, if the objects is not an l1extra::L1EtMissParticle or is not of HT type or the original L1 object cannot be found.
  • const L1GctEtHad * origL1GctEtHad():
    provides the original L1 object;
    returns 0, if the objects is not an l1extra::L1EtMissParticle or is not of HT type or the original L1 object cannot be found.
  • const l1extra::L1JetParticleRef origL1JetRef():
    provides the full reference to the original l1extra::L1JetParticle;
    returns an empty reference, if the objects is not an l1extra::L1JetParticle.
  • const L1GctJetCand * origL1GctJetCand():
    provides the original L1 object;
    returns 0, if the objects is not an l1extra::L1JetParticle or the original L1 object cannot be found.
  • const l1extra::L1MuonParticleRef origL1MuonRef():
    provides the full reference to the original l1extra::L1MuonParticle;
    returns an empty reference, if the objects is not an l1extra::L1MuonParticle.
  • const L1MuGMTExtendedCand * origL1GmtMuonCand():
    provides the original L1 object;
    returns 0, if the objects is not an l1extra::L1MuonParticle or the original L1 object cannot be found.

( * ) These special methods for the cut string parser are defined with:

  • short names for good readability of the cut string,
  • argument types, which work in the cut string parser.

TriggerObjectStandAlone

The TriggerObjectStandAlone inherits from TriggerObject.

It is meant to provide some of the information, which normally is organized top-down (s. here). So this stand-alone trigger object can be used in the absence of trigger event, paths and filters. However, the available information is significantly reduced compared to the "full" mode.

Type definitions

  • typedef std::vector< TriggerObjectStandAlone > TriggerObjectStandAloneCollection:
    collection of TriggerObjectStandAlone to be stored in the event;
  • typedef edm::Ref< TriggerObjectStandAloneCollection > TriggerObjectStandAloneRef:
    persistent reference to an item in a TriggerObjectStandAloneCollection;
  • typedef edm::RefProd< TriggerObjectStandAloneCollection > TriggerObjectStandAloneRefProd:
    persistent reference to a TriggerObjectStandAloneCollection product;
  • typedef edm::RefVector< TriggerObjectStandAloneCollection > TriggerObjectStandAloneRefVector:
    vector of persistent references to items in a TriggerObjectStandAloneCollection;
  • typedef edm::Association< TriggerObjectStandAloneCollection > TriggerObjectStandAloneMatch:
    associates reco::Candidate (PAT objects) to items in a TriggerObjectStandAloneCollection,
    used to store the stand-alone trigger object matches in the event.

Additional data members

In order to serve the stand-alone capability, these need to be stored:

  • std::vector< std::string > filterLabels_:
    vector of labels of those HLT filters resp. L1 conditions the object was used in;
  • std::vector< std::string > pathNames_:
    vector of names of those HLT paths resp. L1 algorithms, the HLT filters resp. L1 conditions were run in.
  • std::vector< bool > pathLastFilterAccepted_:
    vector of flags, if this object was used in the final filter of a succeeding HLT path resp. in a succeeding condition of a succeeding L1 algorithm
  • std::vector< bool > pathL3FilterAccepted_:
    vector of flags, if this object was used in an L3 filter of a succeeding HLT path,
    always false for correspondence to L1 algorithms.

The vector elements correspond to each other, just like in a (multi-)map.

Constructors

  • The same constructors as for TriggerObject also work for TriggerObjectStandAlone (ALERT! constructor from reco::CandidateBaseRef not yet);
  • additionally:
    TriggerObjectStandAlone( const TriggerObject& trigObj ):
    constructor from pat::TriggerObject.

Additional methods (beside usual setters & getters)

  • void addFilterLabel( const std::string & filterLabel ):
    adds an HLT filter label.
  • void addConditionName( const std::string & conditionName ):
    adds an L1 condition name.
  • void addPathName( const std::string & pathName, bool pathLastFilterAccepted = true, bool pathL3FilterAccepted = true ):
    adds an HLT path name with the optional parameters indicating, if the trigger object was used in the final filter ( pathLastFilterAccepted ) resp. in an L3 filter ( pathL3FilterAccepted ) and the path was succeeding.
  • void addAlgorithmName( const std::string & algorithmName, bool algoCondAccepted = true ):
    adds an L1 algorithm name with the optional parameter indicating, if the trigger object was used in a succeeding condition of a succeeding algorithm.
  • std::vector< std::string > filterLabels():
    returns the labels of all HLT filters this object was used in.
  • std::vector< std::string > conditionNames():
    returns the labels of all L1 conditions this object was used in.
  • std::vector< std::string > pathNames( bool pathLastFilterAccepted = false, bool pathL3FilterAccepted = true ):
    returns the names of all HLT paths this object was used in with the optional parameters indicating, if the trigger object should have been used in the final filter ( pathLastFilterAccepted ) resp. in an L3 filter ( pathL3FilterAccepted ) and the path was succeeding;
    ALERT! Check your code! The default of the optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to true and pathL3FilterAccepted has to be set to false.
  • std::vector< std::string > algorithmNames( bool algoCondAccepted = true ):
    returns the names of all L1 algorithms this object was used in with the optional parameter indicating, if the trigger object was used in a succeeding condition of a succeeding algorithm.
  • bool hasPathLastFilterAccepted():
    tests, if the object has been produced already using the data format version with the pathLastFilterAccepted_ flag vector.
  • bool hasAlgoConfAccepted():
    HLT equivalent to hasPathLastFilterAccepted().
  • bool hasPathL3FilterAccepted():
    tests, if the object has been produced already using the data format version with the pathL3FilterAccepted_ flag vector.

TIP The following methods with string type arguments allow for the usage of the wild-card character '*' :
ALERT! Please read also about fun with wild-cards.

  • bool hasFilterLabel( const std::string& filterLabel ) and
    bool filter( const std::string& filterLabel ) ( ** ):
    checks, if a certain HLT filter label is assigned to the stand-alone trigger object;
  • bool hasConditionName( const std::string& conditionName ) and
    bool cond( const std::string& conditionName ) ( ** ):
    checks, if a certain L1 condition name is assigned to the stand-alone trigger object;
  • bool hasPathName( const std::string& pathName, bool pathLastFilterAccepted = false, bool pathL3FilterAccepted = true ) and
    bool path( const std::string& pathName, unsigned pathLastFilterAccepted = 0, unsigned pathL3FilterAccepted = 1 ) ( ** ):
    checks, if a certain trigger path name is assigned to the stand-alone trigger object with the optional parameters indicating, if the trigger object should have been used in the final filter ( pathLastFilterAccepted ) resp. in an L3 filter ( pathL3FilterAccepted ) and the path was succeeding;
    ALERT! Check your code! The default of the optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to true / 1 and pathL3FilterAccepted has to be set to false / 0.
  • bool hasAlgorithmName( const std::string & algorithmName, bool algoCondAccepted = true ) and
    bool algo( const std::string & algorithmName, unsigned algoCondAccepted = 1 ) ( ** ):
    checks, if a certain L1 algorithm name is assigned to the stand-alone trigger object with the optional parameter indicating, if the trigger object was used in a succeeding condition of a succeeding algorithm;
  • bool hasCollection( const edm::InputTag & coll ),
    bool hasCollection( const std::string & coll ) and
    bool coll( const std::string & coll ) ( ** ):
    checks, if a certain label of original collection is assigned
    TIP works also without specifying the process name (but be aware of instances).

( ** ) These special methods for the cut string parser are defined with:

  • short names for good readability of the cut string,
  • argument types, which work in the cut string parser (no bool).

TriggerFilter

Type definitions

  • typedef std::vector< TriggerFilter > TriggerFilterCollection:
    collection of TriggerFilter to be stored in the event;
  • typedef edm::Ref< TriggerFilterCollection > TriggerFilterRef:
    persistent reference to an item in a TriggerFilterCollection;
  • typedef edm::RefProd< TriggerFilterCollection > TriggerFilterRefProd:
    persistent reference to a TriggerFilterCollection product,<
    used as data member of the TriggerEvent;
  • typedef edm::RefVector< TriggerFilterCollection > TriggerFilterRefVector:
    vector of persistent references to items in a TriggerFilterCollection.

Data members

  • std::string label_:
    InputTag label of the filter module (EDFilter);
  • std::string type_:
    type of the filter module (framework module definition);
  • std::vector< unsigned > objectKeys_:
    keys of used trigger objects in the trigger object collection;
  • std::vector< trigger::TriggerObjectType > triggeObjectTypes_:
    list of unique trigger object types of the used trigger objects, possibly empty;
  • int status_:
    coded status of the filter in this event:
    code -1 0 1
    status not run failed succeeded
  • bool saveTags_:
    identifier for L3 filters.

Constructors

  • TriggerFilter( const std::string& label, int status = -1, bool saveTags = false ) and
    TriggerFilter( const edm::InputTag& tag, int status = -1, bool saveTags = false ):
    constructors from filter InputTag (label), optional status code and optional L3 filter identifier.

Methods (beside usual setters & getters)

  • bool isL3():
    checks, if the filter is an L3 filter.
  • bool isFiring():
    checks, if the filter is a succeeding L3 filter ("firing" filter).
  • bool hasTriggerObjectType( trigger::TriggerObjectType triggerObjectType ) and
    bool hasTriggerObjectType( int triggerObjectType ):
    checks, if a given trigger object type is assigned to the filter.
  • bool hasObjectKey( unsigned objectKey ):
    checks, if a given trigger object represented by its key in the trigger object collection was used in the filter;

TriggerCondition

Type definitions

  • typedef std::vector< TriggerCondition > TriggerConditionCollection:
    collection of TriggerCondition to be stored in the event;
  • typedef edm::Ref< TriggerConditionCollection > TriggerConditionRef:
    persistent reference to an item in a TriggerConditionCollection;
  • typedef edm::RefProd< TriggerConditionCollection > TriggerConditionRefProd:
    persistent reference to a TriggerConditionCollection product,<
    used as data member of the TriggerEvent;
  • typedef edm::RefVector< TriggerConditionCollection > TriggerConditionRefVector:
    vector of persistent references to items in a TriggerConditionCollection.

Data members

  • std::string name_:
    name of the condition;
  • bool accept_:
    tells, if this condition succeded;
  • L1GtConditionCategory category_:
    L1 condition category;
  • L1GtConditionType type_:
    L1 condition type;
  • std::vector< trigger::TriggerObjectType > triggerObjectTypes_:
    list of unique trigger object types of the used trigger objects, possibly empty;
  • std::vector< unsigned > objectKeys_:
    keys of used trigger objects in the trigger object collection;

Constructors

  • TriggerCondition( const std::string & name ):
    constructor from condition name only;
  • TriggerCondition( const std::string & name, bool accept ):
    constructor from condition name and result.

Methods (beside usual setters & getters)

  • bool hasTriggerObjectType( trigger::TriggerObjectType triggerObjectType ) and
    bool hasTriggerObjectType( int triggerObjectType ):
    checks, if a given trigger object type is assigned to the condition;
  • bool hasObjectKey( unsigned objectKey ):
    checks, if a given trigger object represented by its key in the trigger object collection was used in the condition.

TriggerPath

Type definitions

  • typedef std::pair< bool, std::string > L1Seed;:
    an L1 seed consisting of its decision and name;
  • typedef std::vector< L1Seed > L1SeedCollection;:
    the type of the data member in the TriggerPath to store the L1 seeds;
  • typedef std::vector< TriggerPath > TriggerPathCollection:
    collection of TriggerPath to be stored in the event;
  • typedef edm::Ref< TriggerPathCollection > TriggerPathRef:
    persistent reference to an item in a TriggerPathCollection;
  • typedef edm::RefProd< TriggerPathCollection > TriggerPathRefProd:
    persistent reference to a TriggerPathCollection product,
    used as data member of the TriggerEvent;
  • typedef edm::RefVector< TriggerPathCollection > TriggerPathRefVector:
    vector of persistent references to items in a TriggerPathCollection.

Data members

  • std::string name_:
    name of the trigger path, usually referred to as trigger name;
  • unsigned index_:
    associated number in trigger table;
  • unsigned prescale_:
    applied prescaling factor;
  • bool run_:
    tells, if this path was run at all;
  • bool accept_:
    tells, if this path succeded;
  • bool error_:
    tells, if there was an error;
  • std::vector< std::string > modules_:
    ordered list of modules run in this path,
    not only active filters, but also reconstruction, prescaler et. modules,
    filled only on demand, since very heavy;
  • std::vector< unsigned > filterIndices_:
    keys of used trigger filters in the trigger filter collection,
    ordered;
  • unsigned lastActiveFilterSlot_:
    index of last active filter in modules_,
    only meaningful, if modules_ was filled.
  • L1SeedCollection l1Seeds_:
    vector of L1 seeds used in the path, consisting of pairs of the decisions and names.
  • unsigned l3Filters_:
    number of L3 filters in the path.

Constructors

  • TriggerPath( const std::string& name):
    simple constructor from trigger name;
  • TriggerPath( const std::string& name, unsigned index, unsigned prescale, bool run, bool accept, bool error, unsigned lastActiveFilterSlot ):
    complete constructor for all data members, which are not vectors.

Methods (beside usual setters & getters)

  • bool xTrigger():
    identifies x-triggers by l3Filters_ > 2.
  • int indexModule( const std::string& name ):
    returns index of a given module in modules_,
    returns size of modules if the requested module is unknown and -1 if modules_ is empty.
ALERT! CMSSW_3_9_X only:
  • std::vector< std::string > l1Seeds( const bool decision ):
    returns all names of L1 seeds used for that path with the given decision.
  • std::vector< std::string > acceptedL1Seeds():
    l1Seeds( true ).
  • std::vector< std::string > failedL1Seeds():
    l1Seeds( false ).

TriggerAlgorithm

Type definitions

  • typedef std::vector< TriggerAlgorithm > TriggerAlgorithmCollection:
    collection of TriggerAlgorithm to be stored in the event;
  • typedef edm::Ref< TriggerAlgorithmCollection > TriggerAlgorithmRef:
    persistent reference to an item in a TriggerAlgorithmCollection;
  • typedef edm::RefProd< TriggerAlgorithmCollection > TriggerAlgorithmRefProd:
    persistent reference to a TriggerAlgorithmCollection product,
    used as data member of the TriggerEvent;
  • typedef edm::RefVector< TriggerAlgorithmCollection > TriggerAlgorithmRefVector:
    vector of persistent references to items in a TriggerAlgorithmCollection.

Data members

  • std::string name_:
    name of the algorithm; * std::string alias_:
    alias name of the algorithm; * std::string logic_:
    logical expression of conditions used in the algorithm;
  • bool tech_:
    true , if this algorithm is a technical trigger; false, it it is an (physics) algorithm trigger;
  • unsigned bit_:
    trigger bit number in the L1 menu;
  • bool gtlResult_:
    result of the algorithm as determined on the GLT board before any mask or prescale
  • unsigned prescale_:
    applied prescaling factor;
  • bool mask_:
    tells, if masking was applied to the algorithm;
  • bool decisionBeforeMask_:
    real decision of the algorithm;
  • bool decisionAfterMask_:
    effective decision of the algorithm;
  • std::vector< unsigned > conditionKeys_;:
    keys of used conditions in the conditions collection.

Constructors

  • TriggerAlgorithm( const std::string& name):
    simple constructor from algorithm name;
  • TriggerAlgorithm( const std::string& name, const std::string & alias, bool tech, unsigned bit, unsigned prescale, bool mask, bool decisionBeforeMask, bool decisionAfterMask ):
    constructor for almost all non-vector data members (for backward compatibility);
  • TriggerAlgorithm( const std::string& name, const std::string & alias, bool tech, unsigned bit, bool gtlResult, unsigned prescale, bool mask, bool decisionBeforeMask, bool decisionAfterMask ):
    complete constructor for all non-vector data members.

Methods (beside usual setters & getters)

  • bool hasConditionKey( unsigned conditionKey ):
    checks, if a given condition represented by its key in the condition collection was used in the algorithm.

TriggerEvent

Data members

  • std::string nameL1Menu_:
    L1 menu name;
  • std::string nameHltTable_:
    HLT table name;
  • bool run_:
    tells, if the HLT was run at all;
  • bool accept_:
    tells, if the event was accepted by the HLT;
  • bool error_:
    tells, if an error occured;
  • bool physDecl_:
    global trigger PhysicsDeclared bit;
  • boost::uint32_t lhcFill_:
    LHC fill number;
    constant over run;
  • boost::uint16_t beamMode_:
    number identifying the current LHC beam operation mode, according to the BeamMode table in the BST configuration;
    constant over run;
  • boost::uint16_t beamMomentum_:
    momentum of the beams in GeV;
    constant over run;
    ALERT!not center-of-mass collisions energy;
  • boost::uint32_t intensityBeam1_:
    ;
    constant over lumi section;
  • boost::uint32_t intensityBeam2_:
    ;
    constant over lumi section;
  • boost::uint16_t bstMasterStatus_:
    ;
  • boost::uint32_t turnCount_:
    ;
  • float bCurrentStart_:
    ;
    constant over run;
  • =float bCurrentStop_:
    ;
    constant over run;
  • =float bCurrentAvg_:
    ;
    constant over run;
  • TriggerAlgorithmRefProd algorithms_:
    link to TriggerAlgorithmCollection product in the event;
  • TriggerConditionRefProd conditions_:
    link to TriggerConditionCollection product in the event;
  • TriggerPathRefProd paths_:
    link to TriggerPathCollection product in the event;
  • TriggerFilterRefProd filters_:
    link to TriggerFilterCollection product in the event;
  • TriggerObjectRefProd objects_:
    link to TriggerObjectCollection product in the event;
  • TriggerObjectMatchContainer objectMatchResults_:
    links to TriggerObjectMatch products in the event, mapped by their producer labels.

Constructors

  • TriggerEvent( const std::string& nameHltTable, bool run, bool accept, bool error, bool physDecl = true ):
    general constructor for all data members, which do not point to other products (excluding L1 for backward compatibility).
  • TriggerEvent( const std::string& nameL1Menu, const std::string& nameHltTable, bool run, bool accept, bool error, bool physDecl = true ):
    general constructor for all data members, which do not point to other products.

Methods - The central entry point to everything!

Usual setters & getters are not explained explicitely.

  • void setAlgorithms( const edm::Handle< TriggerAlgorithmCollection > & handleTriggerAlgorithms ):
    sets reference-to-product link to TriggerAlgorithmCollection in event from edm::Handle;
  • const TriggerAlgorithmCollection * algorithms():
    returns C++ pointer to TriggerAlgorithmCollection in event;
  • const TriggerAlgorithmRefVector algorithmRefs():
    returns vector of references to all algoritms in event;
  • const TriggerAlgorithm * algorithm( const std::string& nameAlgorithm ):
    returns C++ pointer to the algorithm with given name;
  • const TriggerAlgorithmRef algorithmRef( const std::string& nameAlgorithm ):
    returns reference to the algorithm with given name;
  • std::string nameAlgorithm( const unsigned bitAlgorithm, const bool techAlgorithm = true ):
    returns name of an algorithm, given its name and an indicator, if a technical trigger algorithm (default) or a physics one;
  • unsigned  indexAlgorithm( const std::string& nameAlgorithm ):
    returns index of algorithm with given name within TriggerAlgorithmCollection in event;
  • TriggerAlgorithmRefVector acceptedAlgorithms():
    returns vector of references to algorithm, which succeeded after mask;
  • TriggerAlgorithmRefVector acceptedAlgorithmsGtl():
    returns vector of references to algorithm, which succeeded on the GTL board;
  • TriggerAlgorithmRefVector techAlgorithms():
    returns vector of references to technical trigger algorithm;
  • TriggerAlgorithmRefVector acceptedTechAlgorithms():
    returns vector of references to technical trigger algorithm, which succeeded after mask;
  • TriggerAlgorithmRefVector acceptedTechAlgorithmsGtl():
    returns vector of references to technical trigger algorithm, which succeeded on the GTL board;
  • TriggerAlgorithmRefVector physAlgorithms():
    returns vector of references to physics trigger algorithm;
  • TriggerAlgorithmRefVector acceptedPhysAlgorithms():
    returns vector of references to physics trigger algorithm, which succeeded after mask;
  • TriggerAlgorithmRefVector acceptedPhysAlgorithmsGtl():
    returns vector of references to physics trigger algorithm, which succeeded on the GTL board;
  • void setConditions( const edm::Handle< TriggerConditionCollection > & handleTriggerConditions ):
    sets reference-to-product link to TriggerConditionCollection in event from edm::Handle;
  • const TriggerConditionCollection * conditions():
    returns C++ pointer to TriggerConditionCollection in event;
  • const TriggerConditionRefVector conditionRefs():
    returns vector of references to all conditions in event;
  • const TriggerCondition * condition( const std::string & nameCondition ):
    returns C++ pointer to the condition with given name;
  • const TriggerConditionRef conditionRef( const std::string& nameCondition ):
    returns reference to the condition with given name;
  • unsigned  indexCondition( const std::string& nameCondition ):
    returns index of condition with given name within TriggerConditionCollection in event;
  • TriggerConditionRefVector acceptedConditions():
    returns vector of references to succeeding conditions;
  • void setPaths( const edm::Handle< TriggerPathCollection >& handleTriggerPaths ):
    sets reference-to-product link to TriggerPathCollection in event from edm::Handle;
  • const TriggerPathCollection* paths():
    returns C++ pointer to TriggerPathCollection in event;
  • const TriggerPathRefVector pathRefs():
    returns vector of references to all paths in event;
  • const TriggerPath* path( const std::string& namePath ):
    returns C++ pointer to the path with given trigger name;
  • const TriggerPathRef pathRef( const std::string& namePath ):
    returns reference to the path with given name;
  • unsigned  indexPath( const std::string& namePath ):
    returns index of path with given trigger name within TriggerPathCollection in event;
  • TriggerPathRefVector acceptedPaths():
    returns vector of references to paths, which succeeded;
  • void setFilters( const edm::Handle< TriggerFilterCollection >& handleTriggerFilters ):
    sets reference-to-product link to TriggerFilterCollection in event from edm::Handle;
  • const TriggerFilterCollection* filters():
    returns C++ pointer to TriggerFilterCollection in event;
  • const TriggerFilterRefVector filterRefs():
    returns vector of references to all filters in event;
  • const TriggerFilter* filter( const std::string& labelFilter ):
    returns C++ pointer to the filter with given filter (module) label;
  • const TriggerFilterRef filterRef( const std::string& labelFilter ):
    returns reference to the filter with given filter (module) label;
  • unsigned indexFilter( const std::string& labelFilter ):
    returns index of filter with given filter label within TriggerFilterCollection in event;
  • TriggerFilterRefVector acceptedFilters():
    returns vector of references to filters which succeeded;
  • void setObjects( const edm::Handle< TriggerObjectCollection >& handleTriggerObjects ):
    sets reference-to-product link to TriggerObjectCollection in event from edm::Handle;
  • bool addObjectMatchResult( const TriggerObjectMatchRefProd& trigMatches, const std::string & labelMatcher ),
    bool addObjectMatchResult( const edm::Handle< TriggerObjectMatch >& trigMatches, const std::string & labelMatcher ) and
    bool addObjectMatchResult( const edm::OrphanHandle< TriggerObjectMatch >& trigMatches, const std::string & labelMatcher ):
    adds reference-to-product link to TriggerObjectMatch in event from product reference, edm::Handle or edm::OrpanHandle under the label of the producer module,
    returns false, if the label exists already in objectMatchResults_;
  • const TriggerObjectCollection* objects():
    returns C++ pointer to TriggerObjectCollection in event;
  • TriggerObjectRefVector objects( unsigned filterId ):
    return vector of references to objects with a given trigger object type assigned;
  • std::vector< std::string > triggerMatchers():
    returns a vector containing the labels of all linked trigger object matches in the event;
  • const TriggerObjectMatchContainer* triggerObjectMatchResults():
    returns a C++ pointer to the map with the links to the trigger object matches;
  • const TriggerObjectMatch* triggerObjectMatchResult( const std::string& labelMatcher ):
    returns C++ pointer to TriggerObjectMatch in event given the matcher module label;

TIP The following methods deal with cross-links between the several collections accessible from the pat::TriggerEvent.

  • TriggerConditionRefVector algorithmConditions( const std::string & nameAlgorithm ):
    returns vector of references to all conditions in the TriggerConditionCollection in the event, which were used in an algorithm given by its name;
  • bool conditionInAlgorithm( const TriggerConditionRef & conditionRef, const std::string & nameAlgorithm ):
    tests, if a condition given by a reference to it was run in an algorithm given by its name;
  • TriggerAlgorithmRefVector conditionAlgorithms( const TriggerConditionRef & conditionRef ):
    returns vector of references to all algorithms in the TriggerAlgorithmCollection in the event, which used a condition given by a reference to it;
  • std::vector< std::string > conditionCollections( const std::string & nameAlgorithm ):
    returns a vector of collection labels of the origins of the objects in a combination succeeding a condition given by its name;
  • TriggerObjectRefVector conditionObjects( const std::string & nameCondition ):
    returns a vector of references to all objects in a combination succeeding a condition given by its name;
  • bool objectInCondition( const TriggerObjectRef & usedobjectRef, const std::string & nameCondition ):
    tests, if an object given by a reference to it was in a combination succeeding a condition given by its name;
  • TriggerConditionRefVector objectConditions( const TriggerObjectRef & objectRef ):
    returns vector of references to all conditions in the TriggerConditionCollection in the event, which had an object in a succeeding combination given by a reference to it;
  • TriggerObjectRefVector algorithmObjects( const std::string & nameAlgorithm ):
    returns a vector of references to all objects in a succeeding combination of any condition in an algorithm given by its name;
  • bool objectInAlgorithm( const TriggerObjectRef & objectRef, const std::string & nameAlgorithm ):
    tests, if an object given by a reference to it was in a combination succeeding any condition in an algorithm given by its name;
  • TriggerAlgorithmRefVector objectAlgorithms( const TriggerObjectRef & objectRef ):
    returns vector of references to all algorithms in the TriggerAlgorithmCollection in the event, which had an object given by a reference to it in any combination succeeding any of the algorithm's conditions;
  • TriggerFilterRefVector pathModules( const std::string& namePath, bool all = true ):
    returns vector of references to all filters in the TriggerFilterCollection in the event, which have an entry in the modules_ vector of the path given by its trigger name,
    the list is complete, if the optional parameter all is set to true () default, and truncated after the last active filter has been reached otzherwise,
    the vector contains empty references for modules found in the data member modules_ of the path, but not in the TriggerFilterCollection in the event,
    the vector is empty, if modules_ is empty;
  • TriggerFilterRefVector pathFilters( const std::string& namePath, bool firing = true ):
    returns vector of references to all filters in the TriggerFilterCollection in the event, which were run in a path given by its trigger name;
    optional parameter firing restricts the result to succeeding L3 filters;
    ALERT! Check your code! The default of the new optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to false;
  • bool filterInPath( const TriggerFilterRef& filterRef, const std::string& namePath, bool firing = true ):
    tests, if a filter given by a reference to it was run in a path given by its trigger name;
    optional parameter firing restricts the result to succeeding L3 filters;
    ALERT! Check your code! The default of the new optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to false;
  • TriggerPathRefVector filterPaths( const TriggerFilterRef & filterRef, bool firing = true ):
    returns vector of references to all paths in the TriggerPathCollection in the event, which ran a filter given by a reference to it;
    optional parameter firing restricts the result to succeeding L3 filters;
    ALERT! Check your code! The default of the new optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to false;
  • std::vector< std::string > filterCollections( const std::string& labelFilter ):
    returns a vector of collection labels of the origins of the objects used as input to a filter given by its filter label;
  • TriggerObjectRefVector filterObjects( const std::string& labelFilter ):
    returns a vector of references to all objects used in a filter given by its filter label;
  • bool objectInFilter( const TriggerObjectRef& objectRef, const std::string& labelFilter ):
    tests, if an object given by a reference to it was used in a filter given by its filter label;
  • TriggerFilterRefVector objectFilters( const TriggerObjectRef& objectRef, bool firing = true ):
    returns vector of references to all filters in the TriggerFilterCollection in the event, which used an object given by a reference to it;
    optional parameter firing restricts the result to objects from succeeding L3 filters;
    ALERT! Check your code! The default of the new optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to false;
  • TriggerObjectRefVector pathObjects( const std::string& namePath, bool firing = true ):
    returns a vector of references to all objects used anywhere in a path given by its trigger name;
    optional parameter firing restricts the result to objects from succeeding L3 filters;
    ALERT! Check your code! The default of the new optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to false;
  • bool objectInPath( const TriggerObjectRef& objectRef, const std::string& namePath, bool firing = true ):
    tests, if an object given by a reference to it was used anywhere in a path given by its trigger name;
    optional parameter firing restricts the result to objects from succeeding L3 filters;
    ALERT! Check your code! The default of the new optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to false;
  • TriggerPathRefVector objectPaths( const TriggerObjectRef& objectRef, bool firing = true ):
    returns vector of references to all paths in the TriggerPathCollection in the event, which used anywhere an object given by a reference to it;
    optional parameter firing restricts the result to objects from succeeding L3 filters;
    ALERT! Check your code! The default of the new optional parameters changes the behaviour of code compared to versions of this data format without the pathL3FilterAccepted_ flag vector. To restore the old behaviour, this parameter has to be set to false.

Functions in helper classes

Due to technical restrictions on data formats in CMSSW, some methods had to be removed from pat::TriggerEvent and were reimplemented in the PhysicsTools/PatUtils package within the pat::helper namespace. The names of the methods where preserved and the usage as much as possible. The classes and their functions are defined in PhysicsTools/PatUtils/interface/TriggerHelper.h

The namespace is omitted in the code snippets, just like a using namespace pat::helper; directive has been used.

Class TriggerMatchHelper

This helper class provides access functions related to trigger object matches as registered in the PAT trigger event.

  • TriggerObjectRef triggerMatchObject( const reco::CandidateBaseRef& candRef, const std::string& labelMatcher, const edm::Event& event, const TriggerEvent& triggerEvent ):
    returns a reference to the trigger object matching a candidate (PAT object) given by a reference to it from a matcher module given by its label,
    ALERT! reference can be empty;
  • TriggerObjectRef triggerMatchObject( const reco::CandidateBaseRef& candRef, const TriggerObjectMatch* matchResult, const edm::Event& event, const TriggerEvent& triggerEvent ):
    returns a reference to the trigger object matching a candidate (PAT object) given by a reference to it from a trigger match given by a pointer to it as retrieved by pat::TriggerEvent::triggerObjectMatchResult,
    ALERT! reference can be empty;
  • template< class C > TriggerObjectRef triggerMatchObject( const edm::Handle< C > & candCollHandle, const size_t iCand, const std::string & labelMatcher, const edm::Event & event, const TriggerEvent & triggerEvent ):
    returns a reference to the trigger object matching a candidate (PAT object) given by a collection handle and the identifying index in the collection, from a matcher module given by its label,
    ALERT! reference can be empty;
    TIP the templated method accepts implicit type definition by the type of the handle;
  • template< class C > TriggerObjectRef triggerMatchObject( const edm::Handle< C > & candCollHandle, const size_t iCand, const TriggerObjectMatch * matchResult, const edm::Event & event, const TriggerEvent & triggerEvent ):
    returns a reference to the trigger object matching a candidate (PAT object) given by a collection handle and the identifying index in the collection, from a trigger match given by a pointer to it as retrieved by pat::TriggerEvent::triggerObjectMatchResult,
    ALERT! reference can be empty;
    TIP the templated method accepts implicit type definition by the type of the handle;
  • TriggerObjectMatchMap triggerMatchObjects( const reco::CandidateBaseRef& candRef, const edm::Event& event, const TriggerEvent& triggerEvent ):
    returns a vector of references to the trigger objects matching a candidate (PAT object) given by a reference to it from all matcher modules,
    ALERT! references in the vector can be empty;
  • TriggerObjectMatchMap triggerMatchObjects( const edm::Handle< C > & candCollHandle, const size_t iCand, const edm::Event& event, const TriggerEvent& triggerEvent ):
    returns a vector of references to the trigger objects matching a candidate (PAT object), given by a collection handle and the identifying index in the collection, from all matcher modules,
    ALERT! references in the vector can be empty;
  • reco::CandidateBaseRefVector triggerMatchCandidates( const TriggerObjectRef& objectRef, const std::string& labelMatcher, const edm::Event& event, const TriggerEvent& triggerEvent ):
    returns a vector of references to the candidates (PAT objects) matched by a trigger object given by a reference to it from a matcher module given by its label;
  • reco::CandidateBaseRefVector triggerMatchCandidates( const TriggerObjectRef& objectRef, const TriggerObjectMatch* matchResult, const edm::Event& event, const TriggerEvent& triggerEvent ):
    returns a vector of references to the candidates (PAT objects) matched by a trigger object given by a reference to it from a trigger match given by a pointer to it as retrieved by pat::TriggerEvent::triggerObjectMatchResult;
  • reco::CandidateBaseRefVector triggerMatchCandidates( const edm::Handle< TriggerObjectCollection > & trigCollHandle, const size_t iTrig, const std::string& labelMatcher, const edm::Event& event, const TriggerEvent& triggerEvent ):
    returns a vector of references to the candidates (PAT objects) matched by a trigger object given by a collection handle and the identifying index in the collection, from a matcher module given by its label;
  • reco::CandidateBaseRefVector triggerMatchCandidates( const edm::Handle< TriggerObjectCollection > & trigCollHandle, const size_t iTrig, const TriggerObjectMatch* matchResult, const edm::Event& event, const TriggerEvent& triggerEvent ):
    returns a vector of references to the candidates (PAT objects) matched by a trigger object given by a collection handle and the identifying index in the collection, from a trigger match given by a pointer to it as retrieved by pat::TriggerEvent::triggerObjectMatchResult.

Functions are available after simple instantiation of the class with e.g.

#include "CMS.PhysicsTools/PatUtils/interface/TriggerHelper.h"
using namespace pat;
using namespace pat::helper;
[...]
  const TriggerMatchHelper matchHelper;
  const TriggerObjectRef matchObjRef( matchHelper.triggerMatchObject( candRef, labelMatcher, event, triggerEvent ) );
  const TriggerObjectMatchMap matchMap( matchHelper.triggerMatchObjects( candRef, event, triggerEvent ) );
  const reco::CandidateBaseRefVector matchCandRefs( matchHelper.triggerMatchCandidates( objRef, labelMatcher, event, triggerEvent ) );

Data Formats for Trigger Matching

The data formats used to produce, store and access the trigger matching information are defined by typedef on the basis of TriggerObject resp. TriggerObjectStandAlone. S. here (TriggerObject) and here (TriggerObjectStandAlone) for available types.

The basic data format PATObject hosts embedded trigger matches as the TriggerObjectStandAloneCollection triggerObjectMatchesEmbedded. It has the following corresponding methods:

  • const TriggerObjectStandAloneCollection & triggerObjectMatches():
    returns the vector all embedded trigger matches.
  • const TriggerObjectStandAlone * triggerObjectMatch( const size_t idx = 0 ):
    returns one matched trigger object, identified by its index in the collection.
  • const TriggerObjectStandAloneCollection triggerObjectMatchesByType( const trigger::TriggerObjectType triggerObjectType ):
    returns a vector of all trigger matches, identified by a given trigger object type.
  • const TriggerObjectStandAlone * triggerObjectMatchByType( const trigger::TriggerObjectType triggerObjectType, const size_t idx = 0 ):
    returns one matched trigger object, identified by a given trigger object type and its index in the collection of all such trigger objects.
  • const TriggerObjectStandAloneCollection triggerObjectMatchesByCollection( const std::string & coll ) and
    const TriggerObjectStandAloneCollection triggerObjectMatchesByCollection( const char * coll )
    returns a vector of all trigger matches, identified by a given collection name;
    TIP the collection name does not need to contain the process name, but be aware of instances.
  • const TriggerObjectStandAlone * triggerObjectMatchByCollection( const std::string & coll, const size_t idx = 0 ) and
    const TriggerObjectStandAlone * triggerObjectMatchByCollection( const char * coll, const size_t idx = 0 ):
    returns one matched trigger object, identified by a given collection name and its index in the collection of all such trigger objects;
    TIP the collection name does not need to contain the process name, but be aware of instances.
  • const TriggerObjectStandAloneCollection triggerObjectMatchesByCondition( const std::string & nameCondition ) and
    const TriggerObjectStandAloneCollection triggerObjectMatchesByCondition( const char * nameCondition ):
    returns a vector of all trigger matches, identified by a given condition name.
  • const TriggerObjectStandAlone * triggerObjectMatchByCondition( const std::string & nameCondition, const size_t idx = 0 ) and
    const TriggerObjectStandAlone * triggerObjectMatchByCondition( const char * nameCondition, const size_t idx = 0 ):
    returns one matched trigger object, identified by a given condition name and its index in the collection of all such trigger objects.
  • const TriggerObjectStandAloneCollection triggerObjectMatchesByAlgorithm( const std::string & nameAlgorithm, const bool algoCondAccepted = true ),
    const TriggerObjectStandAloneCollection triggerObjectMatchesByAlgorithm( const char * nameAlgorithm, const bool algoCondAccepted = true ),
    const TriggerObjectStandAloneCollection triggerObjectMatchesByAlgorithm( const std::string & nameAlgorithm, const unsigned algoCondAccepted ) and
    const TriggerObjectStandAloneCollection triggerObjectMatchesByAlgorithm( const char * nameAlgorithm, const unsigned algoCondAccepted ):
    returns a vector of all trigger matches, identified by a given algorithm name, with the optional parameter indicating, if the trigger object should have been in a combination succeeding a condition and the algorithm was also succeeding;
    TIP please note that the functions using unsigned arguments instead of bool do not have a default value for it.
  • const TriggerObjectStandAlone * triggerObjectMatchByAlgorithm( const std::string & nameAlgorithm, const size_t idx = 0, const bool algoCondAccepted = true ),
    const TriggerObjectStandAlone * triggerObjectMatchByAlgorithm( const char * nameAlgorithm, const size_t idx = 0, const bool algoCondAccepted = true ),
    const TriggerObjectStandAlone * triggerObjectMatchByAlgorithm( const std::string & nameAlgorithm, const size_t idx = 0, const bool algoCondAccepted ) and
    const TriggerObjectStandAlone * triggerObjectMatchByAlgorithm( const char * nameAlgorithm, const size_t idx = 0, const bool algoCondAccepted ):
    returns one matched trigger object, identified by a given path name and its index in the collection of all such trigger objects, with the optional parameter indicating, if the trigger object should have been in a combination succeeding a condition and the algorithm was also succeeding;
    TIP please note that the functions using unsigned arguments instead of bool do not have a default value for it.
  • const TriggerObjectStandAloneCollection triggerObjectMatchesByFilter( const std::string & labelFilter ) and
    const TriggerObjectStandAloneCollection triggerObjectMatchesByFilter( const char * labelFilter ):
    returns a vector of all trigger matches, identified by a given filter name.
  • const TriggerObjectStandAlone * triggerObjectMatchByFilter( const std::string & labelFilter, const size_t idx = 0 ) and
    const TriggerObjectStandAlone * triggerObjectMatchByFilter( const char * labelFilter, const size_t idx = 0 ):
    returns one matched trigger object, identified by a given filter name and its index in the collection of all such trigger objects.
  • const TriggerObjectStandAloneCollection triggerObjectMatchesByPath( const std::string & namePath, const bool pathLastFilterAccepted = false, const bool pathL3FilterAccepted = true ),
    const TriggerObjectStandAloneCollection triggerObjectMatchesByPath( const char * namePath, const bool pathLastFilterAccepted = false, const bool pathL3FilterAccepted = true ),
    const TriggerObjectStandAloneCollection triggerObjectMatchesByPath( const std::string & namePath, const unsigned pathLastFilterAccepted, const unsigned pathL3FilterAccepted = 1 ) and
    const TriggerObjectStandAloneCollection triggerObjectMatchesByPath( const char * namePath, const unsigned pathLastFilterAccepted, const unsigned pathL3FilterAccepted = 1 ):
    returns a vector of all trigger matches, identified by a given path name, with the optional parameter indicating, if the trigger object should have been used in the final filter and the path was succeeding;
    TIP please note that the functions using unsigned arguments instead of bool do not have a default value for the first one;
    ALERT! Check your code! The originally optional parameter pathLastFilterAccepted is mandatory now, the new optional parameter pathL3FilterAccepted uses the new L3 filter identifiers; To restore the original behaviour, pass a true / 1 to pathLastFilterAccepted, to use the new feature pass a false / 0; if you passed a false / 0 to pathLastFilterAccepted so far, pass it now to both arguments; ALERT! Check your logic! The parameters pathLastFilterAccepted and pathL3FilterAccepted are combined with a logical AND. Since usually all last filters are also L3 filters, the combination true / 1,==false== / 0 does not make sense and will return an empty collection.
  • const TriggerObjectStandAlone * triggerObjectMatchByPath( const std::string & namePath, const size_t idx = 0, const bool pathLastFilterAccepted = false, const bool pathL3FilterAccepted = true ),
    const TriggerObjectStandAlone * triggerObjectMatchByPath( const char * namePath, const size_t idx = 0, const bool pathLastFilterAccepted = false, const bool pathL3FilterAccepted = true ),
    const TriggerObjectStandAlone * triggerObjectMatchByPath( const std::string & namePath, const size_t idx = 0, const unsigned pathLastFilterAccepted, const unsigned pathL3FilterAccepted = 1 ) and
    const TriggerObjectStandAlone * triggerObjectMatchByPath( const char * namePath, const size_t idx = 0, const unsigned pathLastFilterAccepted, const unsigned pathL3FilterAccepted = 1 ):
    returns one matched trigger object, identified by a given path name and its index in the collection of all such trigger objects, with the optional parameter indicating, if the trigger object should have been used in the final filter and the path was succeeding;
    TIP please note that the functions using unsigned arguments instead of bool do not have a default value for the first one;
    ALERT! Check your code! The originally optional parameter pathLastFilterAccepted is mandatory now, the new optional parameter pathL3FilterAccepted uses the new L3 filter identifiers; To restore the original behaviour, pass a true / 1 to pathLastFilterAccepted, to use the new feature pass a false / 0; if you passed a false / 0 to pathLastFilterAccepted so far, pass it now to both arguments. ALERT! Check your logic! The parameters pathLastFilterAccepted and pathL3FilterAccepted are combined with a logical AND. Since usually all last filters are also L3 filters, the combination true / 1,==false== / 0 does not make sense and will return a NULL pointer..

TIP Methods using std::string as parameter are also available for char* in order to be used also in CINT command lines.
TIP Methods using std::string or char * as parameter allow for the usage of the wild-card character '*' ALERT! Please read also about fun with wild-cards.
TIP Methods using bool as parameter are also available for unsigned in order to be used also in the cut string parser.

Producers

In this section, a brief description of the production process is given and the single producer configurations are explained.

ALERT! For some configuration parameters, default values are given. This does not mean, that these parameters have default values in case they are not assigned, but rather that these defaults can usually left unchanged in the configuration.

PATTriggerProducer UPDATED

The according framework module is called PATTriggerProducer:

The PATTriggerProducer accesses the existing trigger information in AOD, produces a TriggerObjectCollection, a TriggerObjectStandAloneCollection, a TriggerFilterCollection, a TriggerPathCollection, a TriggerConditionCollection and a TriggerAlgorithmCollection from it and puts them to the event. The TriggerFilterCollection and the TriggerPathCollection already contain the top-down x-links for HLT information as described here. In case this is requested, the amount of produced collections is reduced to the TriggerObjectStandAloneCollection only.

Module Configuration UPDATED

The default configuration file is PhysicsTools/PatAlgos/python/triggerLayer1/triggerProducer_cfi.py.

The configuration parameters are:

  • cms.bool onlyStandAlone:
    switch between production of the full information with five collections (False) and stand-alone information with one collection (True),
    default : False;
  • cms.bool addL1Algos (optional):
    indicates, if the L1 algorithms collection should be filled (otherwise produced empty);
    default : False;
    ALERT! The activation of this option needs a proper L1 menu available from the event setup. This is not the case out-of-the-box for CMSSW_4_2_X run on 2010 MC.
    TIP Find an example for the usage of the proper L1 menu here.
  • cms.bool mainBxOnly (optional):
    indicates, if L1 objects should be added also for objects found beyond the main bunch crossing;
    default : True.
  • cms.bool saveL1Refs (optional):
    indicates, if the refererences to the original L1 objects should be stored;
    ALERT! requires to keep *_l1extraParticles_*_[processName] and *_gctDigis_*_[processName] in the event; default : False.
  • cms.InputTag l1GlobalTriggerObjectMaps (optional) UPDATED:
    InputTag of the L1GlobalTriggerObjectMaps product,
    default : "l1L1GtObjectMap" UPDATED;
    ALERT! For data prodiuced with CMSSW_5_1_X or older, the label has to be changed to "l1L1GtObjectMap". However, it will not work at all for direct access to RAW files any more.
  • cms.string processName:
    name of the HLT process,
    TIP using '*' (wild-card) will pick up the process corresponding to the most recently run producer for a trigger::TriggerEvent (as configured with triggerEvent, s. below), independently of its availability in the event. It is presumed that CMSSW prohibits the usage of input file with differing event content.
    default : 'HLT';
  • cms.InputTag triggerResults (optional):
    InputTag of the edm::TriggerResult product,
    default : "TriggerResults";
  • cms.InputTag triggerEvent (optional):
    InputTag of the trigger::TriggerEvent product,
    default : "hltTriggerSummaryAOD";
  • cms.bool addPathModuleLabels (optional):
    adds the labels of all modules (not only the filters) to each path, if set to True,
    ALERT! adds ~8kB per event,
    default : False.
  • cms.vstring exludeCollections (optional):
    labels of original collections of HLT objects, which should be excluded from the trigger object collection; warning: spelling mistake in exlude
    default; empty vector
  • Optional:
    Leaving out one of these parameters means that the corresponding collection is ignored. (Defining an empty label of the InputTag has the same effect.)
    TIP The given defaults are not used automatically, when the configuration parameter is left out, but are the values that have to be used in most of the cases, when the parameter is used. In the default PAT work flow, these parameters are not set.
    ALERT! Do not change them, if you do not know exactly, what you are doing!
    For all cms.InputTag parameters in this section:
    TIPLeaving the process name unspecified leads to the automatic usage of the most recent collections found in the event;
    TIPUsing a '*' (wild-card) as process name leads to the automatic usage of the process name as configured by processName.
    • cms.InputTag l1ExtraMu:
      InputTag of the L1muon objects,
      default : l1extraParticles
    • cms.InputTag l1ExtraNoIsoEG:
      InputTag of the L1 non-isolated e/gamma objects,
      default : l1extraParticles:NonIsolated
    • cms.InputTag l1ExtraIsoEG:
      InputTag of the L1 isolted e/gamma objects,
      default : l1extraParticles:Isolated
    • cms.InputTag l1ExtraCenJet:
      InputTag of the L1 central jet objects,
      default : l1extraParticles:Central
    • cms.InputTag l1ExtraForJet:
      InputTag of the L1 forward jet objects,
      default : l1extraParticles:Forward
    • cms.InputTag l1ExtraTauJet:
      InputTag of the L1 tau jet objects,
      default : l1extraParticles:Tau
    • cms.InputTag l1ExtraETM:
      InputTag of the L1 missing ET objects,
      default : l1extraParticles:MET
    • cms.InputTag l1ExtraHTM:
      InputTag of the L1 missing HT objects,
      default : l1extraParticles:MHT
  • Optional:
    Leaving out one of these parameters means that it and its corresponding functionality are ignored completely.
    TIP In case these parameters are not set, pre-scales will automatically be extracted from the event setup, including dynamic changes within runs. In the default PAT work flow, these parameters are not set.
    ALERT! Since these configuartion parameters might extract other pre-scales than those really used, they should be set only, if you know exactly, what you are doing!
    • cms.string hltPrescaleLabel:
      label of the set of HLT pre-scales from the pre-scale table to be stored:
      • if no label is given or the given is not found in the table, table's default will be used;
      • if default cannot be determined, the first set will be used.
    • cms.string hltPrescaleTable:
      the InputTag's label of the HLT pre-scale tables stored as product in the run, lumi section or event:
      • if no label is given or the given is not found anywhere in the input file, provenance will be used;
      • if provenance not available, an empty HLT pre-scale table (all pre-scales 1) will be used

PATTriggerMatcher

The according framework modules are called:

  • PATTriggerMatcherDRLessByR:
    match by ΔR (default), ranking by ΔR (default),
    default module to be used;
  • PATTriggerMatcherDRDPtLessByR:
    match by ΔR and ΔPt, ranking by ΔR (default);
  • PATTriggerMatcherDRLessByPt:
    match by ΔR (default), ranking by ΔPt;
  • PATTriggerMatcherDRDPtLessByPt:
    match by ΔR and ΔPt, ranking by ΔPt.
  • PATTriggerMatcherDEtaLessByDR:
    match by Δη, ranking by ΔR.
  • PATTriggerMatcherDEtaLessByDEta:
    match by Δη, ranking by Δη.
These are all instances of the templated PhysObjectMatcher from the PhysicsTools/UtilAlgos package.

The PATTriggerMatcher selects the trigger objects to match, performs the match itself and puts the result as a TriggerObjectStandAloneMatch to the event. For the selection of the trigger objects considered for the match, the templated PATTriggerMatchSelector is used, which again passes the selection criteria to the StringCutObjectSelector (cut string parser).

Module Configuration

An example configuration file (also used int the default PAT trigger work flow) is PhysicsTools/PatAlgos/python/triggerLayer1/triggerMatcher_cfi.py.

The configuration parameters are:

  • cms.InputTag src:
    candidate (PAT object) collection in the event to match the trigger objects to;
  • cms.InputTag matched:
    TriggerObjectCollection in the event,
    default : "patTrigger";
  • cms.string matchedCuts:
    cut string passed to the cut string parser to select the considered trigger objects, based on the data format TriggerObjectStandAlone;
    substitutes the former configuration parameters andOr, filterIdsEnum, filterIds, filterLabels, pathNames and collectionTags (ALERT! backward incompatible);
    TIP find a transition guide here;
  • cms.double maxDPtRel:
    maximum ΔPtRel between PAT and trigger object,
    defaults (not yet optimized):
    object type electron photon muon tau to jet jet
    value 0.5 1.0 0.5 3.0 3.0
  • cms.double maxDeltaR:
    maximum ΔR between PAT and trigger object,
    default (not yet optimized):
    object type electron photon muon tau to jet jet
    value 0.5 0.2 0.5 0.1 0.4
  • cms.double maxDeltaEta:
    maximum Δη between PAT and trigger object,
  • cms.bool resolveAmbiguities:
    only one match per trigger object, if set to True,
    default : True;
  • cms.bool resolveByMatchQuality:
    stores best match instead of first, where the type of the ranking is given by the choice of the particular framework module,
    ALERT! works (and makes sense) only with resolveAmbiguities set to True,
    default : False.

Transition Guide for Old Configurations (CMSSW_3_9_X and older)

With CMSSW_3_10_X, the trigger objects considered for the PAT trigger matching are selected using the cut string parser instead of individual configuration parameters specifying the selection criteria., This needs only one single string configuration parameter called matchedCuts to pass the selection, rather than the set of the obsolete configuration parameters andOr, filterIdsEnum, filterIds, filterLabels, pathNames and collectionTags.

TIP This change is backward incompatible, and old trigger matching configurations missing the matchedCuts parameter will crash!
Therefore, old configurations have to be modified in order to work in CMSSW_3_10_X or later. This section explains, how this is done.

Dictionary

The following table provides a one-to-one transalation of obsolete configuration parameters into TriggerObjectStandAlone functions to be used in the cut string expression:

Old configuration parameter TriggerObjectStandAlone function to be used Remarks
bool andOr logical junctors in the cut string expression as explained here This is much more flexible than the static approach before.
vstring filterIdsEnum type( trigger::TriggerObjectType triggerObjectType ) The trigger::TriggerObjectType is provided as string according to the enum definition in this file, but without specifying the namespace trigger. S. example below.
This is for one single trigger objects type. The former vector has to be built (using the logical OR) using logical junctors.
vint32 filterIds type( int triggerObjectType ) This is for one single trigger objects type. The former vector has to be built (using the logical OR) using logical junctors.
vstring filterLabels filter( std::string filterLabel ) This is for one single filter label. The former vector has to be built (using the logical OR) using logical junctors.
TIP The string argument can contain also the wild-card character '*'.
vstring pathNames path( std::string pathName, unsigned pathLastFilterAccepted = 1 ) This is for one single path name. The former vector has to be built (using the logical OR) using logical junctors.
TIP The string argument can contain also the wild-card character '*'.
ALERT! Please read also about fun with wild-cards.
bool pathLastFilterAcceptedOnly included in path(...) (s. above) This can be applied individually per path now.
vstring collectionTags coll( std::string collName ) Accepts also an encoded edm::InputTag.
This is for one single collection name/tag. The former vector has to be built (using the logical OR) using logical junctors.
TIP The string argument can contain also the wild-card character '*'.

Examples

The examples given here are taken (mostly) from the transition of the default examples, identified by the matcher label. Only the affected configuration parameters are listed.

  • cleanMuonTriggerMatchHLTMu9:
    old:
andOr                      = cms.bool( False ),
filterIdsEnum              = cms.vstring( '*' ),
filterIds                  = cms.vint32( 0 ),
filterLabels               = cms.vstring( '*' ),
pathNames                  = cms.vstring(
  'HLT_Mu9'
),
pathLastFilterAcceptedOnly = cms.bool( True ),
collectionTags             = cms.vstring( '*' )
new:
matchedCuts = cms.string( 'path( "HLT_Mu9" )' )
  • cleanMuonTriggerMatchHLTMu13 (incl. wild-card, not a default example):
    old:
andOr                      = cms.bool( False ),
filterIdsEnum              = cms.vstring( '*' ),
filterIds                  = cms.vint32( 0 ),
filterLabels               = cms.vstring( '*' ),
pathNames                  = cms.vstring(
  'HLT_Mu13'
, 'HLT_Mu13_v1'
, 'HLT_Mu13_v2'
# , [...] # many, many more...
),
pathLastFilterAcceptedOnly = cms.bool( True ),
collectionTags             = cms.vstring( '*' )
new:
matchedCuts = cms.string( 'path( "HLT_Mu13" ) || path( "HLT_Mu13_v*" )' )
  • cleanMuonTriggerMatchHLTMu9All (not a default example):
    old:
andOr                      = cms.bool( False ),
filterIdsEnum              = cms.vstring( '*' ),
filterIds                  = cms.vint32( 0 ),
filterLabels               = cms.vstring( '*' ),
pathNames                  = cms.vstring( 
  'HLT_Mu9'
),
pathLastFilterAcceptedOnly = cms.bool( False ), # <--
collectionTags             = cms.vstring( '*' )
new:
matchedCuts = cms.string( 'path( "HLT_Mu9", 0 )' )
  • cleanMuonTriggerMatchTriggerMuon:
    old:
andOr                      = cms.bool( False ),
filterIdsEnum              = cms.vstring(
  'TriggerL1Mu'
, 'TriggerMuon'
),
filterIds                  = cms.vint32( 0 ),
filterLabels               = cms.vstring( '*' ),
pathNames                  = cms.vstring( '*' ),
pathLastFilterAcceptedOnly = cms.bool( True ),
collectionTags             = cms.vstring( '*' )
new:
matchedCuts = cms.string( 'type( "TriggerL1Mu" ) || type( "TriggerMuon" )' )
  • cleanElectronTriggerMatchL1EGammaCollection:
    old:
andOr                      = cms.bool( False ),
filterIdsEnum              = cms.vstring( '*' ),
filterIds                  = cms.vint32( 0 ),
filterLabels               = cms.vstring( '*' ),
pathNames                  = cms.vstring( '*' ),
pathLastFilterAcceptedOnly = cms.bool( True ),
collectionTags             = cms.vstring(
  'l1extraParticles:NonIsolated'
, 'l1extraParticles:Isolated'
)
new:
matchedCuts = cms.string( 'coll( "l1extraParticles:NonIsolated" ) || coll( "l1extraParticles:Isolated" )' )

PATTriggerEventProducer

The PATTriggerEventProducer produces the trigger event and puts it to the event. It also converts the matches of stand-alone trigger objects into matches to "normal" trigger objects and puts them also to the event.
ALERT! Since the PATTriggerMatcher label is also the label of the InputTag of the TriggerObjectStandAloneMatch products, it is not the label but the instance of the TriggerObjectMatch products, e.g. the event contains then these products:

patTriggerObjectStandAloneedmAssociation_myTriggerMatch__PAT
patTriggerObjectedmAssociation_triggerEvent_myTriggerMatch_PAT
where the label of the PATTriggerMatcher was myTriggerMatch amd the label of the PATTriggerEventProducer was triggerEvent.

Module Configuration

The default configuration file is PhysicsTools/PatAlgos/python/triggerLayer1/triggerEventProducer_cfi.py.

The configuration parameters are:

  • cms.string processName:
    name of the HLT process,
    TIP using '*' (wild-card) will pick up the process corresponding to the most recent trigger::TriggerEvent found in the input file
    default : 'HLT';
  • cms.InputTag triggerResults (optional):
    InputTag of the edm::TriggerResult product,
    default : "TriggerResults";
  • cms.InputTag patTriggerProducer (optional):
    InputTag of the TriggerObjectCollection, TriggerFilterCollection and TriggerPathCollection products,
    default : "patTrigger";
  • cms.InputTag l1GtTag (optional):
    InputTag of the L1CMS.GlobalTriggerReadoutRecord product;
    default : empty, which skips the addition of the according information;
    TIP "gtDigis" is the default name of the collection to be added;
  • cms.InputTag condGtTag (optional):
    InputTag of the edm::ConditionsIn{Event,Lumi,Run}Block products;
    default : empty, which skips the addition of the according information;
    TIP "conditionsInEdm" is the default name of the collection to be added;
  • cms.VInputTag patTriggerMatches (optional):
    InputTags of the TriggerObjectStandAloneMatch products to be converted into TriggerObjectMatch products,
    default : empty.

PATTriggerMatchEmbedder

The according framework modules are called:

  • PATTriggerMatchElectronEmbedder:
    embeds trigger object matches into a collection (std::vector) of pat::Electron;
  • PATTriggerMatchJetEmbedder:
    embeds trigger object matches into a collection (std::vector) of pat::Jet;
  • PATTriggerMatchMETEmbedder:
    embeds trigger object matches into a collection (std::vector) of pat::MET;
  • PATTriggerMatchMuonEmbedder:
    embeds trigger object matches into a collection (std::vector) of pat::Muon;
  • PATTriggerMatchPhotonEmbedder:
    embeds trigger object matches into a collection (std::vector) of pat::Photon;
  • PATTriggerMatchTauEmbedder:
    embeds rigger object matches into a collection (std::vector) of pat::Taus.
These are all instances of the templated PATTriggerMatchEmbedder

The PATTriggerMatchEmbedder simply copies a PAT object collection into a new collection and fills in addition its data member triggerObjectMatchesEmbedded_ (TriggerObjectStandAloneCollection) from the stand-alone trigger objects and their matches.

Module Configuration

The default configuration file is PhysicsTools/PatAlgos/python/triggerLayer1/triggerMatchEmbedder_cfi.py.

The configuration parameters are:

  • cms.InputTag src:
    InputTag of the PAT object collection to add the matches to;
  • cms.VInputTag matches:
    InputTags of the corresponding matcher modules;
    their input candidate collections (configuration parameter src) have to be the same as indicated by the src parameter of this embedder module.

ALERT! The embedded trigger object matches are only accessible from the newly produced PAT object collection with the label of the PATTriggerMatchEmbedder module, not from the original (input) PAT object collection, since they are added after the original PAT object collection has been produced.

For an embedder configured like this:
cleanPatMuonsTriggerMatch = cms.EDProducer( "PATTriggerMatchMuonEmbedder"
, src     = cms.InputTag( "cleanPatMuons" )
, matches = cms.VInputTag( 'myMuonTriggerMatch' )
)
the embedded trigger matches are accessible from the cleanPatMuonsTriggerMatch collection and not from cleanPatMuons.

Job Configuration

After the single modules have been explained separately, this section deals with modules, sequences, event content, etc. within a CMSSW job (process) as a whole.

It is assumed, that the PAT configurations and event content are available in the main configuration file by the lines

process.load( "CMS.PhysicsTools.PatAlgos.patSequences_cff" )
from CMS.PhysicsTools.PatAlgos.patEventContent_cff import *

Modules

The single modules producing PAT trigger information are not independent due to their output-input relations. So, a consistent configuration of its three steps is essential.

Order of module execution

The output-input relations of the producers are the following:

and determine the order of module execution:
  1. PATTriggerProducer anywhere;
  2. PATTriggerMatcher after PATTriggerProducer and after production of the PAT objects, which are finally stored in the event;
  3. PATTriggerEventProducer after PATTriggerProducer and PATTriggerMatcher;
  4. PATTriggerMatchEmbedder after PATTriggerProducer and PATTriggerMatcher.

Consistent configuration of modules and sequences

Some modules have configurable output, which of course influences the workflow, where this output is used again as input:

  • PATTriggerProducer:
    • processName:
      should be the same as processName in the PATTriggerEventProducer
      ⇒ best to stay with the default or to use a wild-card;
    • triggerResults:
      should be the same as triggerResults in the PATTriggerEventProducer
      ⇒ best to stay with the default;
    • onlyStandAlone:
      switches off the production of TriggerObjectCollection , TriggerFilterCollection and TriggerPathCollection
      ⇒ remove the PATTriggerEventProducer from the workflow due to missing input.
  • PATTriggerMatcher:
    • src:
      should be the label of a PAT object producer, whose output is stored in the event
      ⇒ cross-check with general PAT workflow and event content;
    • matched:
      should be the label of the PATTriggerProducer
      ⇒ best to stay with the default.
  • PATTriggerEventProducer:
    • processName:
      should be the same as processName in the PATTriggerProducer
      ⇒ best to stay with the default or to use a wild-card;
    • triggerResults:
      should be the same as triggerResults in the PATTriggerProducer
      ⇒ best to stay with the default;
    • patTriggerProducer:
      should be the label of the PATTriggerProducer
      ⇒ best to stay with the default;
    • patTriggerMatches:
      should be only labels of used PATTriggerMatcher modules
      ⇒ best to run the PATTriggerMatcher modules within the default sequence patTriggerMatcher, which is defined in PhysicsTools/PatAlgos/python/triggerLayer1/triggerMatcher_cfi.py, and to cross-check there.
  • PATTriggerMatchEmbedder:
    • src:
      should be the same as src in all PatTriggerMatcher modules listed in parameter matches;
    • matches:
      should be labels of PatTriggerMatcher modulesl with the same parameter src.

Event Content

The PAT event content configuration in PhysicsTools/PatAlgos/python/patEventContent_cff.py provides two default sets of event content for PAT trigger information:

  • patTriggerEventContent:
    contains the TriggerObjectCollection , TriggerFilterCollection , TriggerPathCollection, TriggerConditionCollection, TriggerAlgorithmCollection and TriggerEvent as produced in the default configurations,
    ALERT! does not contain the trigger matches, which have to be added additionally;
  • patTriggerStandAloneEventContent:
    contains the TriggerObjectStandAloneCollection and the TriggerObjectStandAloneMatch;
  • patTriggerL1RefsEventContent:
    contains the l1extraParticles and gctDigis collections with the original L1 trigger objects (needed, if L1 object references are stored; s. PATTriggerProducer).

Consistent configuration of the event content

Depending on the configuration parameter onlyStandAlone of the PATTriggerProducer, the according PAT trigger event content should be added. It is easiest to use the according tools for this, since they take care.

Tools UPDATED

In PhysicsTools/PatAlgos/python/tools/trigTools.py, some helpers are defined to switch on/off default configurations for PAT trigger information production. The use of these functions also serves for the issues of consistencies in configuration and event content. They are provided by appending the line

from CMS.PhysicsTools.PatAlgos.tools.trigTools import *
to the main configuration file.
ALERT! In general, these tools should always be used after any modification done to paths (including the out-path), seqences and the modules they contain, since the current configuration is used in these tools to determine e.g. the correct order of module executions or the output to be saved in the event.
Any further modifications afterwards can spoil the resulting configuration.
TIP The order of execution of these tools themselves does not matter, since they take care automatically.
Also automatic calls to missing pieces take place.

TIP In case, one uses one of the tools and modifies the module parameters put by it to the configuration afterwards, a second call to the same tool can fix the event content accordingly, as shown
from PhysicsTools.PatAlgos.tools.trigTools import *
switchOnTrigger( process )
process.patTrigger.addL1Algos = cms.bool( True ) # This needs an updated event content!
process.patTrigger.l1ExtraMu  = cms.InputTag( 'l1extraParticles', '' )
process.patTrigger.saveL1Refs = cms.bool( True ) # This needs an updated event content!
switchOnTrigger( process )                       # This updates the event content as needed :-)

The cms.Process has to be given to all tools as the first parameter. In addition, there is a list of optional parameters for each tool to customize the resulting configuration accordingly to individual needs. The optional parameters have the same meaning for all tools and are explained here.

Find also additional explanations in the PAT Tools SWGuide - Trigger Tools

The available functions are:

switchOnTrigger( process, triggerProducer, triggerEventProducer, sequence, hltProcess, outputModule )

This tool switches on the default production of full PAT trigger information with resulting collections for trigger objects, filters, paths and (optionally) L1 algorithms. The PATTriggerEvent is also produced as single entry point and cross-links between the collection items are preserved.

switchOnTriggerStandAlone( process, triggerProducer, sequence, hltProcess, outputModule )

This tool switches on the stand-alone production of PAT trigger objects. No PAT trigger event is produced and cross-links between the collection items are not preserved.

switchOnTriggerMatching( process, triggerMatchers, triggerProducer, triggerEventProducer, sequence, hltProcess, outputModule )

This tool switches on previously defined trigger matchers with resulting associative collections containing the match results. Also a link to the match results is added to the PATTriggerEvent.

switchOnTriggerMatchingStandAlone( process, triggerMatchers, triggerProducer, sequence, hltProcess, outputModule )

This tool switches on previously defined trigger matchers with resulting associative collections containing the stand-alone match results.

switchOnTriggerMatchEmbedding( process, triggerMatchers, triggerProducer, sequence, hltProcess, outputModule )

This tool clones PAT object collections, which were used in a trigger match and embeds the matched stand-alone trigger objects into the PAT objects. The original PAT object collections is determined from the matcher configurations and are usually removed from the event content. The new collections with the embedded matches are saved instead.

ALERT! This tool currently relies on the usage of standard PAT object collection labels as input to the matching. These collection labels comprise the output of all standard PAT producers, including the varieties of jet types and algorithms. A complete list of the supported collection labels can be found

* Photons:
    • patPhotons
    • selectedPatPhotons
    • cleanPatPhotons
  • Electrons:
    • patElectrons
    • selectedPatElectrons
    • cleanPatElectrons
  • Muons:
    • patMuons
    • selectedPatMuons
    • cleanPatMuons
  • Taus:
    • patTaus
    • selectedPatTaus
    • cleanPatTaus
  • MET:
    • patMETs
  • Jets:
    • patJets
    • selectedPatJets
    • cleanPatJets
    • various jet types and algorithms:
      Calo JPT PF
      IC5 patJetsIC5Calo
      selectedPatJetsIC5Calo
      cleanPatJetsIC5Calo
      patJetsIC5JPT
      selectedPatJetsIC5JPT
      cleanPatJetsIC5JPT
      patJetsIC5PF
      selectedPatJetsIC5PF
      cleanPatJetsIC5PF
      SC5 patJetsSC5Calo
      selectedPatJetsSC5Calo
      cleanPatJetsSC5Calo
      patJetsSC5JPT
      selectedPatJetsSC5JPT
      cleanPatJetsSC5JPT
      patJetsSC5PF
      selectedPatJetsSC5PF
      cleanPatJetsSC5PF
      KT4 patJetsKT4Calo
      selectedPatJetsKT4Calo
      cleanPatJetsKT4Calo
      patJetsKT4JPT
      selectedPatJetsKT4JPT
      cleanPatJetsKT4JPT
      patJetsKT4PF
      selectedPatJetsKT4PF
      cleanPatJetsKT4PF
      KT6 patJetsKT6Calo
      selectedPatJetsKT6Calo
      cleanPatJetsKT6Calo
      patJetsKT6JPT
      selectedPatJetsKT6JPT
      cleanPatJetsKT6JPT
      patJetsKT6PF
      selectedPatJetsKT6PF
      cleanPatJetsKT6PF
      AK5 patJetsAK5Calo
      selectedPatJetsAK5Calo
      cleanPatJetsAK5Calo
      patJetsAK5JPT
      selectedPatJetsAK5JPT
      cleanPatJetsAK5JPT
      patJetsAK5PF
      selectedPatJetsAK5PF
      cleanPatJetsAK5PF

removeCleaningFromTriggerMatching( process, outputModule )

This tool switches automatically any trigger match in the process to the usage of un-cleaned collections. Also the labels of the involved modules -- and by this the names of the output collections -- are modified accordingly.

ALERT! This tool relies on a naming scheme, where in PAT producer module labels

  • clean indicates cleaned collections;
  • selected indicates un-cleaned collections.

Optional Parameters

TIP As usual, the specification of an optional parameter can be skipped by using None or by parameter name specification.

  • triggerMatchers:
    This is a vector of strings indicating the labels of the matcher modules to be used.
    default: The vector contains all example matches defined in PhysicsTools/PatAlgos/python/triggerLayer1/triggerMatcher_cfi.py.
  • triggerProducer:
    This is a string indicating the label of the PATTriggerProducer to be used.
    default: 'patTrigger'
  • triggerEventProducer:
    This is a string indicating the label of the PATTriggerEventProducer to be used.
    default: 'patTriggerEvent'
  • sequence:
    This is a string indicating the name of the cms.Sequence to add the PAT trigger producer modules to. Also path names are allowed.
    ALERT!If sequence is a cms.Sequence, it has to be part of a path in the current process, otherwise PAT trigger production will not be run.
    default: 'patDefaultSequence'
  • hltProcess:
    This is a string indicating the name of the process, where the HLT was run.
    default: 'HLT'
    TIP using '*' (wild-card) will pick up the process corresponding to the most recent trigger::TriggerEvent found in the input file
  • outputModule:
    This is a string indicating the label of the PoolOutputModule used in the current process.
    TIPAn empty string ('') indicates that no output should be stored, e.g. when no PoolOutputModule is defined in on-the-fly production of a histogram file via TFileService.
    default: 'out'

Usage Examples

  • switch on default PAT trigger production:
from CMS.PhysicsTools.PatAlgos.patTemplate_cfg import *
process.p = cms.Path(
    process.patDefaultSequence
)
from CMS.PhysicsTools.PatAlgos.tools.trigTools import *
switchOnTrigger( process )
  • switch on PAT trigger production without default PAT for the most recent HLT process:
from CMS.PhysicsTools.PatAlgos.patTemplate_cfg import *
process.p = cms.Path()
from CMS.PhysicsTools.PatAlgos.tools.trigTools import *
switchOnTrigger( process, sequence = 'p', hltProcess = '*' )
TIP Note that the empty cms.Path has to be defined, before switchOnTrigger is called, because it is needed as parameter sequence. (The default patDefaultSequence is not part of a path here).
  • switch on trigger match embedding for a match of PAT muons to all triggers in the /Muons primary dataset (clone from existing examples) :
from CMS.PhysicsTools.PatAlgos.patTemplate_cfg import *
process.p = cms.Path(
    process.patDefaultSequence
)
from CMS.PhysicsTools.PatAlgos.triggerLayer1.triggerMatcher_cfi import cleanMuonTriggerMatchPDMu
process.patMuonMatch = cleanMuonTriggerMatchPDMu.clone()
from CMS.PhysicsTools.PatAlgos.tools.trigTools import *
switchOnTriggerMatchEmbedding( process, [ 'patMuonMatch' ] )
TIP Note that the necessary calls to switchOnTriggerStrandAlone and switchOnTriggerMatchingStrandAlone are done automatically.


One more trigger related tool is available in PhysicsTools/PatAlgos/python/tools/cmsswVersionTools.py

The corresponding function is:

run52xOn51xTrigger( process, sequence ) NEW

This tool adds collections holding L1 trigger information to older ( CMSSW_5_1_X ) input files, which are needed since CMSSW_5_2_X, which hold L1 trigger information. See also the corresponding entry about collection _l1L1GtObjectMap_*_ here.
The tool is also documented in the PAT Tools SWGuide - CMSSW Version Tools

Some Examples

Configurations

S. Usage Examples for Python tools.

Exceptional Cases

These are special cases, where no tools are available to fix the configuration:

L1 Information from 2010 MC

Since the 2010 MC L1 menu is not available for CMSSW_4_2_X conditions, one has to add it manually to the configuration, e.g. for Fall10:
import CondCore.DBCommon.CondDBCommon_cfi
process.l1GtTriggerMenu = cms.ESSource( "PoolDBESSource"
, CondCore.DBCommon.CondDBCommon_cfi.CondDBCommon
, toGet   = cms.VPSet(
    cms.PSet(
      connect = cms.untracked.string( 'frontier://FrontierProd/CMS_COND_31X_L1T' )
    , record  = cms.string( 'L1GtTriggerMenuRcd' )
    , tag     = cms.string( 'L1GtTriggerMenu_L1Menu_Commissioning2010_v4_mc' )  # L1 menu for Fall10 REDIGI (CMSSW_3_8_7)
    )
  )
)
process.preferL1GtTriggerMenu = cms.ESPrefer( "PoolDBESSource", "l1GtTriggerMenu" )

Analysis

Here are some code snippets¹) to give an idea about the usage of the PAT trigger data formats in analysis:

Comparison histograms of kinematics

  • Compare the kinematics of a all PAT objects to those of the matched trigger objects given their "physics type":
#include "DataFormats/HLTReco/interface/TriggerTypeDefs.h" // gives access to the (release cycle dependent) trigger object codes
[...]
edm::Handle< TriggerEvent > handlePatTriggerEvent;
iEvent.getByLabel( tagPatTriggerEvent_, handlePatTriggerEvent );
const TriggerObjectRefVector triggerElectrons( handlePatTriggerEvent->objects( trigger::TriggerElectron ) ); // uses trigger object code from the enum in DataFormats/HLTReco/interface/TriggerTypeDefs.h
for ( TriggerObjectRefVector::const_iterator it = triggerElectrons.begin(); it != triggerElectrons.end(); ++it ) {
  const TriggerObjectRef objRef( *it );
  const CandidateBaseRefVector candRefs( handlePatTriggerEvent->triggerMatchCandidates( objRef, labelMatcher, iEvent ) ); // 'const std::string labelMatcher'
  for ( CandidateBaseRefVector::const_iterator ic = candRefs.begin(); ic !=candRefs.end(); ++ic ) {
    const CandidateBaseRef candRef( *ic );
    histos2D_[ "ptObjCand" ]->Fill( candRef->pt(), objRef->pt() ); // 'std::map< std::string, TH2D* > histos2D_'
    histos2D_[ "etaObjCand" ]->Fill( candRef->eta(), objRef->eta() );
    histos2D_[ "phiObjCand" ]->Fill( candRef->phi(), objRef->phi() );
  }
}
[...]
  • Compare the kinematics of all matches given by the InputTag of the PATTriggerMatcher:
[...]
#include "DataFormats/Common/interface/AssociativeIterator.h"
[...]
edm::Handle< TriggerObjectMatch > triggerMatch;
iEvent.getByLabel( matchTag, triggerMatch ); // 'const edm::InputTag& matchTag' is the tag of the according PATTriggerMatcher
// loop over matched candidates
edm::AssociativeIterator< reco::CandidateBaseRef, TriggerObjectMatch > it( *triggerMatch, edm::EdmEventItemGetter< reco::CandidateBaseRef >( iEvent ) ), itEnd( it.end() );
while ( it != itEnd ) {
  const reco::CandidateBaseRef candRef( it->first );
  const TriggerObjectRef objRef( it->second );
  // escape for empty references
  if ( objRef.isNull() || ! objRef.isAvailable() ) {
    ++it;
    continue;
  }
  // fill histograms
  histos2D_[ "ptObjCand" ]->Fill( candRef->pt(), objRef->pt() ); // 'std::map< std::string, TH2D* > histos2D_'
  histos2D_[ "etaObjCand" ]->Fill( candRef->eta(), objRef->eta() );
  histos2D_[ "phiObjCand" ]->Fill( candRef->phi(), objRef->phi() );
  ++it;
}
[...]
ALERT! If one accesses the TriggerObjectMatch directly, a check for empty references is always needed due to properties the PhysObjectMatcher module.
This code leads then to plots like compareEta.png, comparePhi.png or comparePt.png

¹) This code is incomplete by definition and is not expected to run after a simple c&p to an analyzer.

Next Steps and Plans

For Users

Data Formats

  • Add link between L1 objects and their corresponding HLT representatives.

Matching

  • Add special matching for L1 muons.

Analysis

  • Add the possiblity to restrict the stored information to defined HLT paths.

Python Configuration Tools

  • Add the possibility to modify individual module parameters in calls to the Python tool (similar to clone()).

For Development and Integration

Infrastructure

  • Add proper unit tests.

Release Notes UPDATED

The versions given refer to the the tag of the CMS.PhysicsTools/PatAlgos package. The installation recipe is linked from the given tags in the headlines.
The CMSSW versions given refer to the inclusion of the according version of PAT trigger information into the release cycle. The actual tag in CMSSW is possibly a later one.
TIP The installation recipes should be followed especially for the tags given without corresponding release. Otherwise, you can simply use the (bare) release itself.

V08-09-04 (CMSSW_5_2_5) NEW
also PAT tutorial July 2012

TIP These are the tags this version of the documentation refers to!

Features:

  • New tool to run PAT trigger with L1 also on 51X input.

V08-08-22

TIP These tags are documented in this version of this TWiki!

Features:

  • Changes in L1Reco sequences, incl. renaming.

V08-08-12

TIP These tags are documented in this version of this TWiki!

Features:

  • Changed access to L1 menu, since it will come from DB, starting from CMSSW_5_2_0.

V08-07-08 and V08_06_28

TIP These tags are documented in this version of this TWiki!

Features:

  • Added identification of L3 filters by the new saveTags configuration parameter in the HLT menu:
    • This takes only effect for data taken with CMSSW_4_2_X or later in online, after the technical stop in May 2011 (run numbers > 165000);
    • Access functions with an (optional) argument whether to use the pathLastFilterAccepted flag have also an (optional) argument to use the new pathL3FilterAccepted flag,
      ALERT! Argument defaults might have changed. Check your code!

V08-06-19-01/V08-06-21 (CMSSW_4_2_1) and V08-06-01-17 (CMSSW_4_1_5)
also PAT tutorial Apr. 2011

TIP These tags are documented in this version of this TWiki!

Features:

  • fixed wrong usage of pointers instead of Refs in RefVector initialisation in pat::TriggerEvent

V08-06-00 (CMSSW_4_2_0_pre6) and V08-03-11

TIP These tags are documented in this version of this TWiki!

Features:

  • establish links between L1 (physics) algorithms and objects
    • via new data format pat::TriggerCondition to hold L1 conditions as applied on trigger boards;
    • links go to L1 objects as explicitely defined in the configuration of the PATTriggerProducer as InputTags;
    • links only established to objects belonging to an object combination, which fires the condition;
    • added according access functions to pat::TriggerEvent;
    • added according access functions to pat::TriggerObjectStandAlone
      ⇒ re-using existing data members, which originally hold HLT path and filter information;
    • added according access functions for embedded trigger matches to pat::PATObject';
  • added logical expression of conditions to the pat::TriggerAlgorithm;
  • added option to exclude HLT objects from certain collections from the PAT trigger objects:
    • via strings representing InputTags
      ⇒ format: "label[:instance[:process]]";
    • incl. wild-card mechanism;
  • added option to exclude L1 objects from others than the central bunch crossing.

V08-05-05 (CMSSW_4_2_0_pre3)

TIP These tags are documented in this version of this TWiki!

Features:

  • Changing default of pathLastFilterAccepted from false to true;
    ALERT! This can possibly be backward incompatible to private analysis code!
  • Added unsigned work-arounds for boolean arguments in pat::PATObject functions for the cut string parser.

V08-04-04 (CMSSW_3_11_0_pre2 and CMSSW_4_2_0_pre1)

TIP These tags are documented in this version of this TWiki!

Features:

  • switched to usage of the StringCutObjectSelector in the selection of trigger objects for the trigger objects matching;
    ALERT! Matching configurations are backward incompatible to CMSSW_3_9_X!

V08-02-02 (CMSSW_3_9_6) and V08-00-53

TIP These tags are documented in this version of this TWiki!

Features:

  • Added more standard collections to be available in the switchOnTriggerMatchEmbedding Python tool, incl. all standard jet collections;
  • Changed automatic HLT process name determination in order to use rather the last process, where the trigger::TriggerEvent has been produced, than the latest trigger::TriggerEvent present in the event; this is checked every run now, not every event anymore;
  • Reviewed connection of the automatic HLT process determination to the used l1extra collection tags;
  • A bit of code clean-up and synchronisation;
  • Added a bit more Doxygen documantation.

V08-01-09 and V08-00-32 (CMSSW_3_8_7)
also PAT tutorial Nov. 2010 (FNAL)

TIP These tags are documented in this version of this TWiki!

Features:

  • Added missing consideration of automatic process name determination to configurable l1extraParticles collection tags.

V08-01-08 and V08-00-29_autoProcessName

TIP These tags are documented in this version of this TWiki!

Features:

  • Option to automatically pick most recent HLT process (set process name to "*")

V08-01-07

TIP This tag is documented in this version of this TWiki!

Features:

  • Added L1 seeds to pat::TriggerPath.

V08-01-03 (CMSSW_3_9_0_pre6) and V08-00-26_newTriggerTools (CMSSW_3_8_6)

TIP These tags are documented in this version of this TWiki!

Features:

  • Bug fix in pat::TriggerEvent::techAlgorithms();
  • Added missing function to pat::helper::TriggerMatchHelper;
  • CMSSW_3_8_X tag: also the changes explained here apply.

V08-01-01 (CMSSW_3_9_0_pre4)

TIP These tags are documented in this version of this TWiki!

Features:

  • PAT trigger Python tools completely reviewed;
  • PAT trigger example matches removed from the default PAT trigger work flow.

V08-00-19 (CMSSW_3_8_1, CMSSW_3_9_0_pre2) and V07-13-37 (CMSSW_3_7_1),
also PAT tutorial Sep. 2010

TIP These tags are documented in this version of this TWiki!

Features:

  • Reducing verbosity of pat::PATTriggerEventProducer, when running over older (CMSSW version < CMSSW_3_6_X) input files:
    • Global Trigger and data taking conditions information have to be switched on explicitely now.

V08-00-09 (CMSSW_3_8_0_patch1, CMSSW_3_9_0_pre1) and V07-13-36

TIP These tags are documented in this version of this TWiki!

Features:

  • TWiki versioning started.

Contacts

Review status

Reviewer/Editor and Date Comments
Volker Adler - 03-Apr-2009 created page
Volker Adler - 04-Jul-2010 latest announced version
Volker Adler - 19-Jul-2010 additional Global Trigger status bits form conditionsInEdm
Volker Adler - 27-Sep-2010 added version control and updated to status of PAT trigger tutorial Sep. 2010
Volker Adler - 30-Sep-2010 new PAT trigger Python tools (announced)
Volker Adler - 01-Dec-2010 wild-cards for HLT process name and other updates (announced)
Volker Adler - 20-Dec-2010 bachward incompatible cut string parser usage in trigger matching and wild-cards in pat::TriggerObjectStandAlone (announced)
Volker Adler - 23-Feb-2011 establish links between L1 (physics) algorithms and objects, incl. the new data format pat::TriggerCondition (announced)
Volker Adler - 13-Apr-2011 final (belated) version for the Apr. 2011 PAT tutorial
Volker Adler - 28-May-2011 utilising new saveTags parameter of HLT modules to identify L3 filters,
incl. some bachward incompatible changes of defaults in optional parameters of access functions (announced)

-- VolkerAdler - 29-May-2011

Topic attachments
I Attachment History Action Size Date Who Comment
PNGpng compareEta.png r1 manage 11.8 K 2009-04-07 - 14:23 VolkerAdler  
PNGpng comparePhi.png r1 manage 10.3 K 2009-04-07 - 14:23 VolkerAdler  
PNGpng comparePt.png r1 manage 10.9 K 2009-04-07 - 14:23 VolkerAdler  
Edit | Attach | Watch | Print version | History: r148 < r147 < r146 < r145 < r144 | Backlinks | Raw View | WYSIWYG | More topic actions
Topic revision: r148 - 2014-10-29 - VolkerAdler



 
    • 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