Functions to perform Monte Carlo matching for reconstructed Particles. More...

#include <MCMatching.h>

Collaboration diagram for MCMatching:

Public Types
enum	MCErrorFlags { c_Correct = 0 , c_MissFSR = 1 , c_MissingResonance = 2 , c_DecayInFlight = 4 , c_MissNeutrino = 8 , c_MissGamma = 16 , c_MissMassiveParticle = 32 , c_MissKlong = 64 , c_MisID = 128 , c_AddedWrongParticle = 256 , c_InternalError = 512 , c_MissPHOTOS = 1024 , c_AddedRecoBremsPhoton = 2048 }
	Flags that describe different reconstruction errors. More...

Static Public Member Functions
static std::string	explainFlags (unsigned int flags)
	Return string with all human-readable flags, e.g. More...

static bool	setMCTruth (const Belle2::Particle *particle)
	This is the main function of MC matching algorithm. More...

static int	getMCErrors (const Belle2::Particle particle, const Belle2::MCParticle mcParticle=nullptr)
	Returns quality indicator of the match as a bit pattern where the individual bits indicate the the type of mismatch. More...

static int	setMCErrorsExtraInfo (Belle2::Particle particle, const Belle2::MCParticle mcParticle)
	Sets error flags in extra-info (also returns it). More...

static void	fillGenMothers (const Belle2::MCParticle *mcP, std::vector< int > &genMCPMothers)
	Fills vector with array (1-based) indices of all generator ancestors of given MCParticle. More...

static int	findCommonMother (const Belle2::MCParticle *mcP, const std::vector< int > &firstMothers, int lastMother)
	Finds a mother of mcP that is in firstMothers, from [lastMother, end]. More...

static bool	isFSP (int pdg)
	Returns true if given PDG code indicates a FSP.

static bool	isFSR (const Belle2::MCParticle *p)
	Returns true if given MCParticle is a final state radiation (FSR) photon based on MCParticle::c_IsFSRPhoton. More...

static bool	isFSRLegacy (const Belle2::MCParticle *p)
	Returns true if given MCParticle is a final state radiation (FSR) photon. More...

static bool	isRadiativePhoton (const Belle2::MCParticle *p)
	Returns true if given MCParticle is a radiative photon. More...

static int	getMissingParticleFlags (const Belle2::Particle particle, const Belle2::MCParticle mcParticle)
	Determines which daughters of 'mcParticle' are not reconstructed by any daughter of 'particle'. More...

static int	getFlagsOfFSP (const Particle particle, const MCParticle mcParticle)
	Returns flags of given Final State Particle. More...

static int	getFlagsOfDaughters (const Particle daughter, const MCParticle mcParticle)
	Returns flags of daughters of given particle. More...

static int	getFlagsOfBremsPhotonDaughter (const Particle daughter, const MCParticle mcParticle, const std::vector< const MCParticle * > &genParts)
	Returns flags of given daughter which is a brems photon. More...

static int	getNumberOfDaughtersWithoutNeutrinos (const MCParticle *mcParticle)
	Determines the number of daughter particles which are not neutrinos. More...

static int	countMissingParticle (const Belle2::Particle particle, const Belle2::MCParticle mcParticle, const std::vector< int > &daughterPDG)
	Count the number of missing daughters of the 'particle'. More...

static int	getFlagsIgnoredByProperty (const Belle2::Particle *particle)
	Returns the flags ignored by PropertyFlags of given particle. More...

static int	makeDaughterAcceptMask (int daughterProperty)
	Returns the daughter mask from given daughterProperty. More...

Static Public Attributes
static const std::string	c_extraInfoMCErrors = "mcErrors"
	Name of extra-info field stored in Particle.

Detailed Description

Functions to perform Monte Carlo matching for reconstructed Particles.

End users should usually not need to run these functions directly, but can use the matchMCTruth() python function in modularAnalysis (or the MCMatching module). Afterwards, Particles have relations to the matched MCParticle.

Different MCErrorFlags flags can be queried using getMCErrors(), or the associated 'mcErrors' variable (available via VariablesToNtuple, the MCTruth ntuple tool, etc.). For checking if a Particle is correctly reconstructed, the 'isSignal' variable can be used.

Definition at line 28 of file MCMatching.h.

Member Enumeration Documentation

◆ MCErrorFlags

enum MCErrorFlags

Flags that describe different reconstruction errors.

Enumerator
c_Correct	This Particle and all its daughters are perfectly reconstructed.
c_MissFSR	A Final State Radiation (FSR) photon is not reconstructed (based on MCParticle::c_IsFSRPhoton).
c_MissingResonance	The associated MCParticle decay contained additional non-final-state particles (e.g. a rho) that weren't reconstructed. This is probably O.K. in most cases
c_DecayInFlight	A Particle was reconstructed from the secondary decay product of the actual particle. This means that a wrong hypothesis was used to reconstruct it, which e.g. for tracks might mean a pion hypothesis was used for a secondary electron.
c_MissNeutrino	A neutrino is missing (not reconstructed).
c_MissGamma	A photon (not FSR) is missing (not reconstructed).
c_MissMassiveParticle	A generated massive FSP is missing (not reconstructed).
c_MissKlong	A Klong is missing (not reconstructed).
c_MisID	One of the charged final state particles is mis-identified.
c_AddedWrongParticle	A non-FSP Particle has wrong PDG code, meaning one of the daughters (or their daughters) belongs to another Particle.
c_InternalError	There was an error in MC matching. Not a valid match. Might indicate fake/background track or cluster.
c_MissPHOTOS	A photon created by PHOTOS was not reconstructed (based on MCParticle::c_IsPHOTOSPhoton)
c_AddedRecoBremsPhoton	A photon added with the bremsstrahlung recovery tools (correctBrems or correctBremsBelle) has no MC particle assigned, or it doesn't belong to the decay chain.

Definition at line 33 of file MCMatching.h.

                       {
       c_Correct               = 0,  
       c_MissFSR               = 1, 
       c_MissingResonance      = 2, 
       c_DecayInFlight         = 4, 
       c_MissNeutrino          = 8, 
       c_MissGamma             = 16, 
       c_MissMassiveParticle   = 32, 
       c_MissKlong             = 64, 
       c_MisID                 = 128, 
       c_AddedWrongParticle    = 256, 
       c_InternalError         = 512, 
       c_MissPHOTOS            = 1024, 
       c_AddedRecoBremsPhoton  = 2048, 
     };

Member Function Documentation

◆ countMissingParticle()

int countMissingParticle	(	const Belle2::Particle *	particle,
		const Belle2::MCParticle *	mcParticle,
		const std::vector< int > &	daughterPDG
	)

static

Count the number of missing daughters of the 'particle'.

Returns: number of missing daughters having given PDG codes

Definition at line 558 of file MCMatching.cc.

 {
   unordered_set<const MCParticle*> mcMatchedParticles;
   // Missing particles which are accepted by the property flags are NOT stored.
   // --> Such particles are also counted in nMissingDaughter.
   appendParticles(particle, mcMatchedParticles);
   vector<const MCParticle*> genParts;
   appendParticles(mcParticle, genParts);
  
   int nMissingDaughter = 0;
  
   for (const MCParticle* genPart : genParts) {
     const bool missing = (mcMatchedParticles.find(genPart) == mcMatchedParticles.end());
     if (missing) {
  
       const int generatedPDG = genPart->getPDG();
       const int absGeneratedPDG = abs(generatedPDG);
  
       auto result = find(daughterPDG.begin(), daughterPDG.end(), absGeneratedPDG);
       if (result != daughterPDG.end())
         nMissingDaughter++;
     }
   }
  
   return nMissingDaughter;
 }

◆ explainFlags()

std::string explainFlags ( unsigned int flags )

static

Return string with all human-readable flags, e.g.

explainFlags(402) returns "c_MissingResonance | c_MissGamma | c_MisID | c_AddedWrongParticle".

Can also be used from Python:

import basf2
from ROOT import Belle2, gInterpreter
gInterpreter.ProcessLine('#include "analysis/utility/MCMatching.h"')
print(Belle2.MCMatching.explainFlags(123))

Definition at line 26 of file MCMatching.cc.

◆ fillGenMothers()

void fillGenMothers	(	const Belle2::MCParticle *	mcP,
		std::vector< int > &	genMCPMothers
	)

static

Fills vector with array (1-based) indices of all generator ancestors of given MCParticle.

Parameters

mcP	pointer to the MCParticle
genMCPMothers	pointer to the generator ancestors MCParticle
reference	to the vector of integers to hold the results

Definition at line 61 of file MCMatching.cc.

◆ findCommonMother()

int findCommonMother	(	const Belle2::MCParticle *	mcP,
		const std::vector< int > &	firstMothers,
		int	lastMother
	)

static

Finds a mother of mcP that is in firstMothers, from [lastMother, end].

To actually find the common mother of all daughters, each time this function is called for a daughter particle, specify the return value from the last call for lastMother.

Note: this looks like an ideal case for applying a more sophisticated algorithm for LCA (lowest common ancestor) problems. However, our trees aren't very large, so additional preprocessing might slow this down (I saw this when experimenting with the algorithm). This might still be worth looking into if an algorithm with inexpensive preprocessing were used, or the preprocessing was done only once per event. See http://community.topcoder.com/tc?module=Static&d1=tutorials&d2=lowestCommonAncestor for an interesting introduction to related algorithms.

Returns: index of the first common mother in firstMothers (!), or -1 if not found.

Definition at line 70 of file MCMatching.cc.

◆ getFlagsIgnoredByProperty()

int getFlagsIgnoredByProperty ( const Belle2::Particle * particle )

static

Returns the flags ignored by PropertyFlags of given particle.

Only c_isIgnored... flags are considered. c_isUnspecified is already considered in setMCErrorsExtraInfo function.

Returns: ORed combination of corresponding MCErrorFlags with PropertyFlags of given particle

Definition at line 585 of file MCMatching.cc.

◆ getFlagsOfBremsPhotonDaughter()

int getFlagsOfBremsPhotonDaughter	(	const Particle *	daughter,
		const MCParticle *	mcParticle,
		const std::vector< const MCParticle * > &	genParts
	)

static

Returns flags of given daughter which is a brems photon.

Special treatment for brems is done.

Parameters

daughter
mcParticle	(this is MC mother of daughter)
genParts	vector of MC (n*grand-)daughters

Returns: flags of given daughter

Definition at line 406 of file MCMatching.cc.

◆ getFlagsOfDaughters()

int getFlagsOfDaughters	(	const Particle *	daughter,
		const MCParticle *	mcParticle
	)

static

Returns flags of daughters of given particle.

Parameters

daughter
mcParticle

Returns: flags of daughters of given particle

Definition at line 368 of file MCMatching.cc.

◆ getFlagsOfFSP()

int getFlagsOfFSP	(	const Particle *	particle,
		const MCParticle *	mcParticle
	)

static

Returns flags of given Final State Particle.

Parameters

particle
mcParticle

Returns: flags of given particle

Definition at line 340 of file MCMatching.cc.

◆ getMCErrors()

int getMCErrors	(	const Belle2::Particle *	particle,
		const Belle2::MCParticle *	mcParticle = `nullptr`
	)

static

Returns quality indicator of the match as a bit pattern where the individual bits indicate the the type of mismatch.

The values are defined in the MCErrorFlags enum and described in detail there.

A return value equal to c_Correct == 0 indicates a perfect MC match (everything OK).

The value is also stored inside the Particle's extra-info fields (so it is calculated only once per candidate).

Parameters

particle	pointer to the particle. setMCTruth() must have been called previously (usually via the MCMatching module)!
mcParticle	pointer to the matched MCParticle. Can be specified to avoid repeated lookups.

Returns: ORed combination of MCErrorFlags describing differences between reconstructed particle and MC truth.

Definition at line 279 of file MCMatching.cc.

◆ getMissingParticleFlags()

int getMissingParticleFlags	(	const Belle2::Particle *	particle,
		const Belle2::MCParticle *	mcParticle
	)

static

Determines which daughters of 'mcParticle' are not reconstructed by any daughter of 'particle'.

Returns: ORed combination of MCErrorFlags flags for missing particles.

Definition at line 499 of file MCMatching.cc.

◆ getNumberOfDaughtersWithoutNeutrinos()

int getNumberOfDaughtersWithoutNeutrinos ( const MCParticle * mcParticle )

static

Determines the number of daughter particles which are not neutrinos.

Needed to handle the special case tau -> rho nu correctly.

Parameters

mcParticle

Returns: number of daughters which are not neutrinos

Definition at line 432 of file MCMatching.cc.

◆ isFSR()

bool isFSR ( const Belle2::MCParticle * p )

static

Returns true if given MCParticle is a final state radiation (FSR) photon based on MCParticle::c_IsFSRPhoton.

Assumes PDG code of p is 22.

Definition at line 466 of file MCMatching.cc.

◆ isFSRLegacy()

bool isFSRLegacy ( const Belle2::MCParticle * p )

static

Returns true if given MCParticle is a final state radiation (FSR) photon.

This is a legacy version of isFSR(const Belle2::MCParticle* p) function that works on MC samples without MCParticle::c_IsFSRPhoton and MCParticle::c_IsPHOTOSPhoton properly set (for example Belle MC).

Definition at line 471 of file MCMatching.cc.

◆ isRadiativePhoton()

bool isRadiativePhoton ( const Belle2::MCParticle * p )

static

Returns true if given MCParticle is a radiative photon.

Assumes PDG code of p is 22.

Definition at line 492 of file MCMatching.cc.

◆ makeDaughterAcceptMask()

int makeDaughterAcceptMask ( int daughterProperty )

static

Returns the daughter mask from given daughterProperty.

Returns: ORed combination of MCErrorFlags to be accepted for the daughter

Definition at line 594 of file MCMatching.cc.

◆ setMCErrorsExtraInfo()

int setMCErrorsExtraInfo	(	Belle2::Particle *	particle,
		const Belle2::MCParticle *	mcParticle
	)

static

Sets error flags in extra-info (also returns it).

Users should use getMCErrors(), which only calculates this information when necessary.

Definition at line 290 of file MCMatching.cc.

◆ setMCTruth()

bool setMCTruth ( const Belle2::Particle * particle )

static

This is the main function of MC matching algorithm.

When executed the algorithm searches for first common generated mother (MCParticle) of this particle's daughters. If such MCParticle is found the Particle -> MCParticle relation is set between them. If the relation between daughter particles and matched generated MC particle does not exist the algorithm sets it also for them.

Parameters

particle pointer to the Particle to be mc-matched

Returns: returns true if relation is set and false otherwise

Definition at line 86 of file MCMatching.cc.

The documentation for this struct was generated from the following files:

analysis/utility/include/MCMatching.h
analysis/utility/src/MCMatching.cc

Public Types

Static Public Member Functions

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ MCErrorFlags

Member Function Documentation

◆ countMissingParticle()

◆ explainFlags()

◆ fillGenMothers()

◆ findCommonMother()

◆ getFlagsIgnoredByProperty()

◆ getFlagsOfBremsPhotonDaughter()

◆ getFlagsOfDaughters()

◆ getFlagsOfFSP()

◆ getMCErrors()

◆ getMissingParticleFlags()

◆ getNumberOfDaughtersWithoutNeutrinos()

◆ isFSR()

◆ isFSRLegacy()

◆ isRadiativePhoton()

◆ makeDaughterAcceptMask()

◆ setMCErrorsExtraInfo()

◆ setMCTruth()