7.3. Variables

While basf2 operates on ParticleList s, it is also important to calculate physics quantities associated with a given candidate or event.

In basf2 analysis, variables are handled by the VariableManager. There are many variables available for use in analysis. Probably the most obvious, and useful are: p, E, Mbc, and deltaE.

You can search the variables in an alphabetical basf2 Variable Index, or browse Variables by group.

7.3.1. VariableManager

The VariableManager handles all variables in basf2 analysis. It is implemented as a singleton C++ class with a python interface.

The C++ documentation is here.

Tip

For (unfortunate) historical reasons, the python accessor to the VariableManager singleton is called variables and is in the python variables module. This leads to strange-looking python import commands.

For example:

from variables import variables

To avoid confusion, example/tutorial scripts often use a namespace alias vm. You might want to use this in your scripts.

from variables import variables as vm # shorthand for VariableManager

class VariableManager

Singleton class to hold all variables and aliases in the current scope.

addAlias(alias, expression)

Create a new alias.

Variable names are deliberately verbose and explicit (to avoid ambiguity). However, it is often not desirable to deal with long unwieldy variable names particularly in the context of Variable Manager Output.

Example:

Aliases to a verbose variable may be set with:

>>> from variables import variables as vm
>>> vm.addAlias("shortname", "aReallyLongAndSpecificVariableName(1, 2, 3)")

See also

variables.utils.create_aliases and variables.utils.create_aliases_for_selected might be helpful if you find yourself setting many aliases in your analysis script.

Warning

The VariableManager instance is configured independently of the basf2.Path. In case of adding the same alias twice, the configuration just before calling basf2.process is what wins.

Parameters:

• alias (str) – New alias to create

• expression (str) – The expression the alias should evaluate to

Returns:

True if the alias was successfully added

getAliasNames()

Get a list of all alias names (in reverse order added)

Tip

This returns a ROOT.vector which you will probably need to convert into a python list(str).

>>> my_aliases = list(vm.getAliasNames())

Returns:

ROOT.vector list of alias names

addCollection(collection, variables)

Create a new variable collection.

Tip

This method takes a ROOT.vector<string> as input. It’s probably easier to use variables.utils.add_collection which wraps this function for you.

Parameters:

• collection (str) – The new collection to create.

• variables – A ROOT.std.vector(string) instance of variables to add as the variable collection.

Returns:

True if the collection was successfully added

getCollection(collection)

Get a list of all variables in the collection.

Parameters:

collection (str) – The name of the existing variable collection

Returns:

ROOT.vector list of variable names

printAliases()

Prints all aliases currently registered. Useful to call just before calling basf2.process on an analysis basf2.Path when debugging.

7.3.2. Variables by group

Here is a categorised list of variables known to basf2. You can also look at the alphabetical index: basf2 Variable Index.

Kinematics

ArmenterosDaughter1Qt

Transverse momentum of the first daughter with respect to the V0 mother. The mother is required to have exactly two daughters

Unit:

GeV/c

ArmenterosDaughter2Qt

Transverse momentum of the second daughter with respect to the V0 mother. The mother is required to have exactly two daughters

Unit:

GeV/c

ArmenterosLongitudinalMomentumAsymmetry

Longitudinal momentum asymmetry of V0’s daughters. The mother (V0) is required to have exactly two daughters

E

energy

Unit:

GeV

ECLClusterE_uncertainty

energy uncertainty as given by the underlying ECL cluster

Unit:

GeV

E_uncertainty

energy uncertainty (\(\sqrt{\sigma^2}\))

Unit:

GeV

ErrM

uncertainty of invariant mass

Unit:

GeV/\(\text{c}^2\)

ImpactXY

The impact parameter of the given particle in the xy plane

Unit:

cm

InvM

invariant mass (determined from particle’s daughter 4-momentum vectors). If this particle is V0 or decays at rho > 5 mm, its daughter 4-momentum vectors at fitted vertex are taken. If this particle has no daughters, defaults to M.

Unit:

GeV/\(\text{c}^2\)

InvMLambda

Invariant mass (determined from particle’s daughter 4-momentum vectors), assuming the first daughter is a pion and the second daughter is a proton. If the particle has not 2 daughters, it returns just the mass value.

Unit:

GeV/\(\text{c}^2\)

M

The particle’s mass.

Note that this is context-dependent variable and can take different values depending on the situation. This should be the “best” value possible with the information provided.

• If this particle is track- or cluster- based, then this is the value of the mass hypothesis.

• If this particle is an MC particle then this is the mass of that particle.

• If this particle is composite, then initially this takes the value of the invariant mass of the daughters.

• If this particle is composite and a mass or vertex fit has been performed then this may be updated by the fit.

• You will see a difference between this mass and the InvM.

Unit:

GeV/\(\text{c}^2\)

M2

The particle’s mass squared.

Unit:

\([\text{GeV}/\text{c}^2]^2\)

Mbc

beam constrained mass

Unit:

GeV/\(\text{c}^2\)

PDG

PDG code

Q

energy released in decay

Unit:

GeV

SigM

signed deviation of particle’s invariant mass from its nominal mass in units of the uncertainty on the invariant mass (dM/ErrM)

b2bClusterPhi

Azimuthal angle in the lab system that is back-to-back to the particle’s associated ECLCluster in the CMS. Returns NAN if no cluster is found. Useful for low multiplicity studies.

Unit:

rad

b2bClusterTheta

Polar angle in the lab system that is back-to-back to the particle’s associated ECLCluster in the CMS. Returns NAN if no cluster is found. Useful for low multiplicity studies.

Unit:

rad

b2bPhi

Azimuthal angle in the lab system that is back-to-back to the particle in the CMS. Useful for low multiplicity studies.

Unit:

rad

b2bTheta

Polar angle in the lab system that is back-to-back to the particle in the CMS. Useful for low multiplicity studies.

Unit:

rad

cosAngleBetweenMomentumAndVertexVector

cosine of the angle between momentum and vertex vector (vector connecting ip and fitted vertex) of this particle

cosAngleBetweenMomentumAndVertexVectorInXYPlane

cosine of the angle between momentum and vertex vector (vector connecting ip and fitted vertex) of this particle in xy-plane

cosTheta

momentum cosine of polar angle

cosThetaBetweenParticleAndNominalB

cosine of the angle in CMS between momentum the particle and a nominal B particle. It is somewhere between -1 and 1 if only a massless particle like a neutrino is missing in the reconstruction.

cosThetaErr

error of momentum cosine of polar angle

cosToThrustOfEvent

Returns the cosine of the angle between the particle and the thrust axis of the event, as calculate by the EventShapeCalculator module. buildEventShape() must be run before calling this variable

dM

mass minus nominal mass

Unit:

GeV/\(\text{c}^2\)

dQ

Q minus nominal energy released in decay

Unit:

GeV

deltaE

difference between E and half the center of mass energy

Unit:

GeV

eRecoil

energy recoiling against given Particle

Unit:

GeV

m2Recoil

invariant mass squared of the system recoiling against given Particle

Unit:

\([\text{GeV}/\text{c}^2]^2\)

m2RecoilSignalSide

Squared recoil mass of the signal side which is calculated in the CMS frame under the assumption that the signal and tag side are produced back to back and the tag side energy equals the beam energy. The variable must be applied to the Upsilon and the tag side must be the first, the signal side the second daughter

Unit:

\([\text{GeV}/\text{c}^2]^2\)

mRecoil

Invariant mass of the system recoiling against given Particle

Unit:

GeV/\(\text{c}^2\)

momDevChi2

momentum deviation \(\chi^2\) value calculated as \(\chi^2 = \sum_i (p_i - mc(p_i))^2/\sigma(p_i)^2\), where \(\sum\) runs over i = px, py, pz and \(mc(p_i)\) is the mc truth value and \(\sigma(p_i)\) is the estimated error of i-th component of momentum vector

momVertCovM(i, j)

returns the (i,j)-th element of the MomentumVertex Covariance Matrix (7x7). Order of elements in the covariance matrix is: px, py, pz, E, x, y, z.

Unit:

GeV/c, GeV/c, GeV/c, GeV, cm, cm, cm

p

momentum magnitude

Unit:

GeV/c

pErr

error of momentum magnitude

Unit:

GeV/c

pRecoil

magnitude of 3 - momentum recoiling against given Particle

Unit:

GeV/c

pRecoilPhi

Azimuthal angle of a particle’s missing momentum

Unit:

rad

pRecoilTheta

Polar angle of a particle’s missing momentum

Unit:

rad

phi

momentum azimuthal angle

Unit:

rad

phiErr

error of momentum azimuthal angle

Unit:

rad

pt

transverse momentum

Unit:

GeV/c

ptErr

error of transverse momentum

Unit:

GeV/c

px

momentum component x

Unit:

GeV/c

pxErr

error of momentum component x

Unit:

GeV/c

pxRecoil

component x of 3-momentum recoiling against given Particle

Unit:

GeV/c

py

momentum component y

Unit:

GeV/c

pyErr

error of momentum component y

Unit:

GeV/c

pyRecoil

component y of 3-momentum recoiling against given Particle

Unit:

GeV/c

pz

momentum component z

Unit:

GeV/c

pzErr

error of momentum component z

Unit:

GeV/c

pzRecoil

component z of 3-momentum recoiling against given Particle

Unit:

GeV/c

theta

polar angle

Unit:

rad

thetaErr

error of polar angle

Unit:

rad

xp

scaled momentum: the momentum of the particle in the CMS as a fraction of its maximum available momentum in the collision

Helicity

acoplanarityAngle

Acoplanarity angle (see Particle::getAcoplanarity) assuming a two body decay of the particle and its daughters. See PDG Polarization Review for the definition of the acoplanarity angle.

Unit:

rad

cosAcoplanarityAngle(i, j)

Cosine of the acoplanarity angle (\(\Phi\) in the PDG Polarization Review). Given a two-body decay, the acoplanarity angle is defined as the angle between the two decay planes in the reference frame of the mother.

We calculate the acoplanarity angle as the angle between the two normal vectors of the decay planes. Each normal vector is the cross product of the momentum of one daughter (in the frame of the mother) and the momentum of one of the granddaughters (in the reference frame of the daughter).

This variable needs two integer arguments: the first one, i is the index of the first granddaughter, and the second one, j the index of the second granddaughter.

For example, in the decay \(B^0 \to \left(J/\psi \to \mu^+ \mu^-\right) \left(K^{*0} \to K^+ \pi^-\right)\), if the provided particle is \(B^0\) and the selected indices are (0, 0), the variable will return the acoplanarity using the \(\mu^+\) and the \(K^+\) granddaughters.

cosHelicityAngle(i, j)

Cosine of the helicity angle between the momentum of the selected granddaughter and the direction opposite to the momentum of the provided particle in the reference frame of the selected daughter (\(\theta_1\) and \(\theta_2\) in the PDG 2018, p. 722).

This variable needs two integer arguments: the first one, i, is the index of the daughter and the second one, j is the index of the granddaughter.

For example, in the decay \(B^0 \to \left(J/\psi \to \mu^+ \mu^-\right) \left(K^{*0} \to K^+ \pi^-\right)\), if the provided particle is \(B^0\) and the selected indices are (0, 0), the variable will return the angle between the momentum of the \(\mu^+\) and the direction opposite to the momentum of the \(B^0\), both momenta in the rest frame of the \(J/\psi\).

This variable is needed for angular analyses of \(B\)-meson decays into two vector particles.

cosHelicityAngleBeamMomentum(i)

Cosine of the helicity angle of the \(i\)-th daughter of the particle provided, assuming that the mother of the provided particle corresponds to the centre-of-mass system, whose parameters are automatically loaded by the function, given the accelerator’s conditions.

cosHelicityAngleDaughter(i [, j])

Cosine of the helicity angle of the i-th daughter (see Particle::getCosHelicityDaughter). The optional second argument is the index of the granddaughter that defines the angle, default is 0.

For example, in the decay: \(B^0 \to \left(J/\psi \to \mu^+ \mu^-\right) \left(K^{*0} \to K^+ \pi^-\right)\), if the provided particle is \(B^0\) and the selected index is 0, the variable will return the helicity angle of the \(\mu^+\). If the selected index is 1 the variable will return the helicity angle of the \(K^+\) (defined via the rest frame of the \(K^{*0}\)). In rare cases if one wanted the helicity angle of the second granddaughter, indices 1,1 would return the helicity angle of the \(\pi^-\)).

See PDG Polarization Review for the definition of the helicity angle.

cosHelicityAngleForQuasiTwoBodyDecay(i, j)

Cosine of the helicity angle between the momentum of the provided particle and the momentum of the first selected daughter (i-th) in the reference frame of the sum of two selected daughters (i-th + j-th).

The variable is supposed to be used for the analysis of a quasi-two-body decay. The number of daughters of the given particle must be three. Otherwise, the variable returns NaN.

For example, in the decay \(\bar{B}^0 \to D^+ K^- K^{*0}\), if the provided particle is \(\bar{B}^0\) and the selected indices are (1, 2), the variable will return the angle between the momentum of the \(\bar{B}^0\) and the momentum of the \(K^-\), both momenta in the rest frame of the \(K^- K^{*0}\).

cosHelicityAngleMomentum

If the given particle has two daughters: cosine of the angle between the line defined by the momentum difference of the two daughters in the frame of the given particle (mother) and the momentum of the given particle in the lab frame.

If the given particle has three daughters: cosine of the angle between the normal vector of the plane defined by the momenta of the three daughters in the frame of the given particle (mother) and the momentum of the given particle in the lab frame.

Otherwise, it returns 0.

cosHelicityAngleMomentumPi0Dalitz

To be used for the decay \(\pi^0 \to e^+ e^- \gamma\): cosine of the angle between the momentum of the gamma in the frame of the given particle (mother) and the momentum of the given particle in the lab frame.

One can call the variable for the decay \(\pi^0 \to \gamma \gamma, \gamma \to e^+ e^-\) as well.

Otherwise, it returns 0.

cosHelicityAnglePrimary

Cosine of the helicity angle (see``Particle::getCosHelicity``) assuming the center of mass system as mother rest frame. See PDG Polarization Review for the definition of the helicity angle.

momentaTripleProduct(i, j, k)

a triple-product of three momenta of offspring in the mother rest frame: \(C_T=\vec{p}_i\cdot(\vec{p}_j\times\vec{p}_k)\). For examples, In a four-body decay M->D1D2D3D4, momentaTripleProduct(0,1,2) returns CT using the momenta of D1D2D3 particles. In other decays involving secondary decay, e.g. for M->(R->D1D2)D3D4, momentaTripleProduct(0:0,1,2) returns C_T using momenta of D1D3D4 particles.

Tracking

Here is a list of track variables. In the following descriptions, PR refers to “pattern recognition” tracks (i.e. reconstructed). And MC refers to MC tracks. This notation follows the convention of the tracking paper.

See also

For more details see: “Track finding at Belle II” Comput.Phys.Commun. 259 (2021), 107610

chi2

Returns the \(\chi^2\) of the track fit. This is actually computed based on pValue and ndf.

Note

Note that for pValue exactly equal to 0 it returns infinity.

Returns NaN if called for something other than a track-based particle, or for mdst files processed with basf2 versions older than release-05-01.

d0

Returns the tracking parameter \(d_0\), the signed distance to the point-of-closest-approach (POCA) in the \(r-\phi\) plane.

Note

Tracking parameters are with respect to the origin (0,0,0). For the POCA with respect to the measured beam interaction point, see dr (you probably want this unless you’re doing a tracking study or some debugging) and d0FromIP.

Returns NaN if called for something other than a track-based particle.

Unit:

cm

d0Err

Returns the uncertainty on \(d_0\), the signed distance to the point-of-closest-approach (POCA) in the \(r-\phi\) plane.

See also

d0, d0Pull

Returns NaN if called for something other than a track-based particle.

Unit:

cm

d0FromIP

Returns the tracking parameter \(d_0\), the signed distance to the point-of-closest-approach (POCA) in the \(r-\phi\) plane, with respect to the measured beam interaction point.

Returns NaN if called for something other than a track-based particle.

Unit:

cm

d0Pull

The pull of the tracking parameter \(d_0\) for the reconstructed pattern-recognition track, with respect to the MC track. That is:

\[\frac{d_0^\textrm{MC} - d_0^\textrm{PR}}{\sigma_{d_0; \textrm{PR}}}\]

See also

d0, d0Err

Returns NaN if no MC particle is related or if called on something other than a track-based particle.

firstCDCLayer

The first activated CDC layer associated to the track. Returns NaN if called for something other than a track-based particle.

firstPXDLayer

The first activated PXD layer associated to the track. Returns NaN if called for something other than a track-based particle.

firstSVDLayer

The first activated SVD layer associated to the track. Returns NaN if called for something other than a track-based particle.

hasExtraCDCHitsInLayer(i)

[Eventbased] Returns 1 if a non-assigned hit exists in the specified CDC layer, 0 otherwise.

Returns NaN if there is no event-level tracking information available.

hasExtraCDCHitsInSuperLayer(i)

[Eventbased] Returns 1 if a non-assigned hit exists in the specified CDC SuperLayer, 0 otherwise.

Returns NaN if there is no event-level tracking information available.

helixExtPhi(radius, z fwd, z bwd, useHighestProbMass=0)

Returns phi of extrapolated helix parameters. If useHighestProbMass=1 is set, the extrapolation will use the track fit result for the mass hypothesis with the highest pValue.

Unit:

rad

helixExtPhiOnDet(detector_surface_name, useHighestProbMass=0)

Returns phi of extrapolated helix parameters on the given detector surface. The unit of angle is rad.

If useHighestProbMass=1 is set, the extrapolation will use the track fit result for the mass hypothesis with the highest pValue. The supported detector surface names are {'CDC', 'TOP', 'ARICH', 'ECL', 'KLM'}. Also, the detector name with number of meaningful-layer is supported, e.g. 'CDC8': last superlayer of CDC, 'ECL1': mid-point of ECL.

..note:: You can find more information in modularAnalysis.calculateTrackIsolation.

helixExtTheta(radius [cm], z fwd [cm], z bwd [cm], useHighestProbMass=0)

Returns theta of extrapolated helix parameters. If useHighestProbMass=1 is set, the extrapolation will

use the track fit result for the mass hypothesis with the highest pValue.

Unit:

rad

helixExtThetaOnDet(detector_surface_name, useHighestProbMass=0)

Returns theta of extrapolated helix parameters on the given detector surface. The unit of angle is rad.

If useHighestProbMass=1 is set, the extrapolation will use the track fit result for the mass hypothesis with the highest pValue. The supported detector surface names are {'CDC', 'TOP', 'ARICH', 'ECL', 'KLM'}. Also, the detector name with number of meaningful-layer is supported, e.g. 'CDC8': last superlayer of CDC, 'ECL1': mid-point of ECL.

..note:: You can find more information in modularAnalysis.calculateTrackIsolation.

isTrackFlippedAndRefitted

Returns 1 if the charged final state particle comes from a track that has been flipped and refitted at the end of the reconstruction chain, in particular after the outer detector reconstruction.

lastCDCLayer

The last CDC layer associated to the track. Returns NaN if called for something other than a track-based particle.

mcD0

Returns the MC value of \(d_0\), the signed distance to the point-of-closest-approach (POCA) in the \(r-\phi\) plane.

See also

d0

Returns NaN if the particle is not related to any MCParticle.

Unit:

cm

mcOmega

Returns the MC value of \(\omega\), the curvature of the track.

See also

omega

Returns NaN if the particle is not related to any MCParticle.

Unit:

\(\text{cm}^{-1}\)

mcPhi0

Returns the MC value of \(\phi_0\), the angle of the transverse momentum in the \(r-\phi\) plane.

See also

phi0

Returns NaN if the particle is not related to any MCParticle.

Unit:

rad

mcTanLambda

Returns the MC value of \(\tan\lambda\), the slope of the track in the \(r-z\) plane.

See also

tanLambda

Returns NaN if the particle is not related to any MCParticle.

mcZ0

Returns the MC value of \(z_0\), the z-coordinate of the point-of-closest-approach (POCA).

See also

z0

Returns NaN if the particle is not related to any MCParticle.

Unit:

cm

nCDCHits

The number of CDC hits associated to the track. Returns NaN if called for something other than a track-based particle.

nExtraCDCHits

[Eventbased] The number of CDC hits in the event not assigned to any track.

Returns NaN if there is no event-level tracking information available.

nExtraCDCHitsPostCleaning

[Eventbased] Returns a count of the number of CDC hits in the event not assigned to any track nor very likely beam background (i.e. hits that survive a cleanup selection).

Returns NaN if there is no event-level tracking information available.

nExtraCDCSegments

[Eventbased] Returns the number of CDC segments not assigned to any track.

Returns NaN if there is no event-level tracking information available.

nPXDHits

The number of PXD hits associated to the track. Returns NaN if called for something other than a track-based particle.

nSVDHits

The number of SVD hits associated to the track. Returns NaN if called for something other than a track-based particle.

nVXDHits

The number of PXD and SVD hits associated to the track. Returns NaN if called for something other than a track-based particle.

ndf

Returns the number of degrees of freedom of the track fit.

Note

Note that this is not simply the number of hits -5 due to outlier hit rejection.

Returns NaN if called for something other than a track-based particle, or for mdst files processed with basf2 versions older than release-05-01.

omega

Returns the tracking parameter \(\omega\), the curvature of the track.

Returns NaN if called for something other than a track-based particle.

Unit:

\(\text{cm}^{-1}\)

omegaErr

Returns the uncertainty on \(\omega\), the curvature of the track.

See also

omega, omegaPull

Returns NaN if called for something other than a track-based particle.

Unit:

\(\text{cm}^{-1}\)

omegaPull

The pull of the tracking parameter \(\omega\) for the reconstructed pattern-recognition track, with respect to the MC track. That is:

\[\frac{\omega^\textrm{MC} - \omega^\textrm{PR}}{\sigma_{\omega; \textrm{PR}}}\]

See also

omega, omegaErr

Returns NaN if no MC particle is related or if called on something other than a track-based particle.

pValue

The \(\chi^2\) probability of the track fit.

Note

This is the p-value of the track-fit. It does not get updated after vertex fitting or kinematic fitting, and is meaningless for composite particles.

See chiProb (you probably want this for high-level analysis).

Returns NaN if called for something other than a track-based particle.

phi0

Returns the tracking parameter \(\phi_0\), the angle of the transverse momentum in the \(r-\phi\) plane.

Note

Tracking parameters are with respect to the origin (0,0,0). For the POCA with respect to the measured beam interaction point, see phi0FromIP.

Returns NaN if called for something other than a track-based particle.

Unit:

rad

phi0Err

Returns the uncertainty on \(\phi_0\), the angle of the transverse momentum in the \(r-\phi\) plane.

See also

phi0, phi0Pull

Returns NaN if called for something other than a track-based particle.

Unit:

rad

phi0FromIP

Returns the tracking parameter \(\phi_0\), the angle of the transverse momentum in the \(r-\phi\) plane, with respect to the measured beam interaction point.

Returns NaN if called for something other than a track-based particle.

Unit:

rad

phi0Pull

The pull of the tracking parameter \(\phi_0\) for the reconstructed pattern-recognition track, with respect to the MC track. That is:

\[\frac{\phi_0^\textrm{MC} - \phi_0^\textrm{PR}}{\sigma_{\phi_0; \textrm{PR}}}\]

See also

phi0, phi0Err

Returns NaN if no MC particle is related or if called on something other than a track-based particle.

tanLambda

Returns \(\tan\lambda\), the slope of the track in the \(r-z\) plane.

Returns NaN if called for something other than a track-based particle.

tanLambdaErr

Returns the uncertainty on \(\tan\lambda\), the slope of the track in the \(r-z\) plane.

See also

tanLambda, tanLambdaPull

Returns NaN if called for something other than a track-based particle.

tanLambdaPull

The pull of the tracking parameter \(\tan\lambda\) for the reconstructed pattern-recognition track, with respect to the MC track. That is:

\[\frac{(\tan\lambda)^\textrm{MC} - (\tan\lambda)^\textrm{PR}}{\sigma_{\tan\lambda; \textrm{PR}}}\]

See also

tanLambda, tanLambdaErr

Returns NaN if no MC particle is related or if called on something other than a track-based particle.

trackFindingFailureFlag

[Eventbased] Returns a flag set by the tracking if there is reason to assume there was a track in the event missed by the tracking, or the track finding was (partly) aborted for this event.

Returns NaN if there is no event-level tracking information available.

trackFitCovariance(i, j)

The track fit covariance matrix element corresponding to the two indices is returned. This is the association between integers and parameters:

• 0: \(d_0\)

• 1: \(\phi_0\)

• 2: \(\omega\)

• 3: \(z_0\)

• 4: \(\tan\lambda\)

Note

The covariance is returned. This means that the return value can be negative. Furthermore, it’s the squared value of the track fit error variables d0Err, etc. when selecting the diagonal entries.

trackFitHypothesisPDG

Returns the PDG code of the track hypothesis actually used for the fit. Returns NaN if called for something other than a track-based particle.

trackLength

Returns the arc length of the helix for the TrackFitResult associated with the particle. The arc length is measured from the track origin to the radius of the CDC layer in which the Track has a hit. Returns NaN if the particle has no CDC Hits.

Unit:

cm

trackNECLClusters

Returns a count of the number of ECLClusters matched to the track. This is always 0 or 1 with newer versions of ECL reconstruction.

Note

For high-level analysis it is recommended to require the presence of a matched ECL cluster along with a minimum energy requirement. A track-based particle will have a clusterE if it is matched (NaN if there is no cluster match for the track.

import modularAnalysis as ma
# minimum energy of 200 MeV
ma.fillParticleList("e+:clusters", "clusterE > 0.2", path)

# these two are equivalent
ma.fillParticleList("e+:unmatched", "isNAN(clusterE) == 1", path)
ma.fillParticleList("e+:unmatched2", "trackNECLClusters == 0", path)

Returns NaN if called for something other than a track-based particle.

trackTime

Returns the time at which the track is produced relative to the time of the collision (given by SVD EventT0). Both the time of the collision and the track time are computed using only SVD hits. Returns NaN if SVD EventT0 is NaN, or if no SVD Hits are attached to the track. For more details, see Time Extraction page.

Unit:

ns

z0

Returns the tracking parameter \(z_0\), the z-coordinate of the point-of-closest-approach (POCA).

Note

Tracking parameters are with respect to the origin (0,0,0). For the POCA with respect to the measured beam interaction point, see dz (you probably want this unless you’re doing a tracking study or some debugging) and z0FromIP.

Returns NaN if called for something other than a track-based particle.

Unit:

cm

z0Err

Returns the uncertainty on \(z_0\), the z-coordinate of the point-of-closest-approach (POCA).

See also

z0, z0Pull

Returns NaN if called for something other than a track-based particle.”

Unit:

cm

z0FromIP

Returns the tracking parameter \(z_0\), the z-coordinate of the point-of-closest-approach (POCA), with respect to the measured beam interaction point.

Returns NaN if called for something other than a track-based particle.

Unit:

cm

z0Pull

The pull of the tracking parameter \(z_0\) for the reconstructed pattern-recognition track, with respect to the MC track. That is:

\[\frac{z_0^\textrm{MC} - z_0^\textrm{PR}}{\sigma_{z_0; \textrm{PR}}}\]

See also

z0, z0Err

Returns NaN if no MC particle is related or if called on something other than a track-based particle.

V0 Tracking

Here is a list of track variables for V0 daughters:

V0Deltad0

Return the difference between d0 impact parameters of V0’s daughters with the V0 vertex point as a pivot for the track.

Unit:

cm

V0Deltaz0

Return the difference between z0 impact parameters of V0’s daughters with the V0 vertex point as a pivot for the track.

Unit:

cm

V0d0(id)

Return the d0 impact parameter of a V0’s daughter with daughterID index with the V0 vertex point as a pivot for the track.

Unit:

cm

V0z0(id)

Return the z0 impact parameter of a V0’s daughter with daughterID index with the V0 vertex point as a pivot for the track.

Unit:

cm

convertedPhotonDelR(i, j)

Discriminating variable Delta-R calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

cm

convertedPhotonDelTanLambda(i, j)

Discriminating variable Delta-TanLambda calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

convertedPhotonDelZ(i, j)

Discriminating variable Delta-Z calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

cm

convertedPhotonInvariantMass(i, j)

Invariant mass of the i-j daughter system as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

GeV/\(\text{c}^2\)

convertedPhotonPx(i, j)

Estimate of x-component of photon momentum calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

GeV/c

convertedPhotonPy(i, j)

Estimate of y-component of photon momentum calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

GeV/c

convertedPhotonPz(i, j)

Estimate of z-component of photon momentum calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

GeV/c

convertedPhotonRho(i, j)

Estimate of vertex Rho calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

cm

convertedPhotonX(i, j)

Estimate of vertex X coordinate calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

cm

convertedPhotonY(i, j)

Estimate of vertex Y coordinate calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

cm

convertedPhotonZ(i, j)

Estimate of vertex Z coordinate calculated for daughters (i,j) as defined in https://indico.belle2.org/event/3644/contributions/18622/attachments/9401/14443/Photon_vertexin_B2GM.pdf, assuming it’s a converted photon

Unit:

cm

v0DaughterCov(i, j)

j-th element of the 15 covariance matrix elements (at IP perigee) of the i-th daughter track. (0,0), (0,1) … (1,1), (1,2) … (2,2) …index order is: 0:d0, 1:phi0, 2:omega, 3:z0, 4:tanLambda

Unit:

cm, rad, \(\text{cm}^{-1}\), cm, unitless

v0DaughterD0(i)

d0 of the i-th daughter track fit

Unit:

cm

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable d0, so replace the current call with daughter(i, d0).

v0DaughterD0Error(i)

d0 error of the i-th daughter track fit

Unit:

cm

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable d0Err, so replace the current call with daughter(i, d0Err).

v0DaughterD0PullWithOriginAsPivot(i)

d0 pull of the i-th daughter track with the origin as the track pivot

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable d0Pull, so replace the current call with daughter(i, d0Pull).

v0DaughterD0PullWithTrueVertexAsPivot(i)

d0 pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughterFirstCDCLayer(i)

First activated CDC layer associated to the i-th daughter track

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable firstCDCLayer, so replace the current call with daughter(i, firstCDCLayer).

v0DaughterFirstPXDLayer(i)

First activated PXD layer associated to the i-th daughter track

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable firstPXDLayer, so replace the current call with daughter(i, firstPXDLayer).

v0DaughterFirstSVDLayer(i)

First activated SVD layer associated to the i-th daughter track

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable firstSVDLayer, so replace the current call with daughter(i, firstSVDLayer).

v0DaughterLastCDCLayer(i)

Last CDC layer associated to the i-th daughter track

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable lastCDCLayer, so replace the current call with daughter(i, lastCDCLayer).

v0DaughterNCDCHits(i)

Number of CDC hits associated to the i-th daughter track

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable nCDCHits, so replace the current call with daughter(i, nCDCHits).

v0DaughterNPXDHits(i)

Number of PXD hits associated to the i-th daughter track

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable nPXDHits, so replace the current call with daughter(i, nPXDHits).

v0DaughterNRemovedHits(i)

The number of the i-th daughter track hits removed in V0Finder. Returns 0 if called for something other than V0 daughters.

v0DaughterNSVDHits(i)

Number of SVD hits associated to the i-th daughter track

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable nSVDHits, so replace the current call with daughter(i, nSVDHits).

v0DaughterNVXDHits(i)

Number of PXD+SVD hits associated to the i-th daughter track

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable nVXDHits, so replace the current call with daughter(i, nVXDHits).

v0DaughterOmega(i)

omega of the i-th daughter track fit

Unit:

\(\text{cm}^{-1}\)

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable omega, so replace the current call with daughter(i, omega).

v0DaughterOmegaError(i)

omega error of the i-th daughter track fit

Unit:

\(\text{cm}^{-1}\)

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable omegaErr, so replace the current call with daughter(i, omegaErr).

v0DaughterOmegaPullWithOriginAsPivot(i)

omega pull of the i-th daughter track with the origin as the track pivot

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable omegaPull, so replace the current call with daughter(i, omegaPull).

v0DaughterOmegaPullWithTrueVertexAsPivot(i)

omega pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughterPValue(i)

chi2 probalility of the i-th daughter track fit

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable pValue, so replace the current call with daughter(i, pValue).

v0DaughterPhi0(i)

phi0 of the i-th daughter track fit

Unit:

rad

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable phi0, so replace the current call with daughter(i, phi0).

v0DaughterPhi0Error(i)

phi0 error of the i-th daughter track fit

Unit:

rad

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable phi0Err, so replace the current call with daughter(i, phi0Err).

v0DaughterPhi0PullWithOriginAsPivot(i)

phi0 pull of the i-th daughter track with the origin as the track pivot

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable phi0Pull, so replace the current call with daughter(i, phi0Pull).

v0DaughterPhi0PullWithTrueVertexAsPivot(i)

phi0 pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughterTanLambda(i)

tan(lambda) of the i-th daughter track fit

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable tanLambda, so replace the current call with daughter(i, tanLambda).

v0DaughterTanLambdaError(i)

tan(lambda) error of the i-th daughter track fit

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable tanLambdaErr, so replace the current call with daughter(i, tanLambdaErr).

v0DaughterTanLambdaPullWithOriginAsPivot(i)

tan(lambda) pull of the i-th daughter track with the origin as the track pivot

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable tanLambdaPull, so replace the current call with daughter(i, tanLambdaPull).

v0DaughterTanLambdaPullWithTrueVertexAsPivot(i)

tan(lambda) pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughterTau(i, j)

j-th track parameter (at IP perigee) of the i-th daughter track. j: 0:d0, 1:phi0, 2:omega, 3:z0, 4:tanLambda

Unit:

cm, rad, \(\text{cm}^{-1}\), cm, unitless

v0DaughterZ0(i)

z0 of the i-th daughter track fit

Unit:

cm

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable z0, so replace the current call with daughter(i, z0).

v0DaughterZ0Error(i)

z0 error of the i-th daughter track fit

Unit:

cm

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable z0Err, so replace the current call with daughter(i, z0Err).

v0DaughterZ0PullWithOriginAsPivot(i)

z0 pull of the i-th daughter track with the origin as the track pivot

Note

Deprecated since version light-2104-poseidon.

The same value can be calculated with the more generic variable z0Pull, so replace the current call with daughter(i, z0Pull).

v0DaughterZ0PullWithTrueVertexAsPivot(i)

z0 pull of the i-th daughter track with the true V0 vertex as the track pivot

v0DaughtersShare1stHit

flag for V0 daughters sharing the first(innermost) VXD hit. 0x1(0x2) bit represents V/z(U/r-phi)-hit share.

v0DaughtersShare1stUHit

flag for V0 daughters sharing the first(innermost) VXD U-side hit.

v0DaughtersShare1stVHit

flag for V0 daughters sharing the first(innermost) VXD V-side hit.

PID

Here is a list of particle identification variables:

Warning

The definitions of the default PID variables have changed between release-01 and release-02.

Prior to release-02-00-00 (i.e. in release-01-XX-YY) each ID was calculated against the pion likelihood alone, or the kaon in the case of the pion itself. Namely the pair probability (also known as the binary probability) was returned:

• for all particles: \(\text{<Part>ID}=\mathcal{L}_{\text{<Part>}}/\mathcal{L}_\pi\), where \(\text{<Part>}\in[e,\mu,K,p,d]\).

• for pions: \(\text{PionID}=\mathcal{L}_\pi/\mathcal{L}_K\).

In other words, pionID was sensitive only to the pion-kaon mis-id, and not to the pion-proton or pion-muon mis-identification.

binaryElectronID_noSVD_noTOP(pdgCodeTest)

(SPECIAL (TEMP) variable) Returns the binary probability for the electron mass hypothesis with respect to another mass hypothesis using all detector components, excluding the SVD and the TOP. NB: this variable must be used in place of binaryPID (pdgCode1=11) when analysing data (MC) processed (simulated) in release 5

binaryElectronID_noTOP(pdgCodeTest)

(SPECIAL (TEMP) variable) Returns the binary probability for the electron mass hypothesis with respect to another mass hypothesis using all detector components, excluding the TOP. NB: this variable must be used in place of binaryPID (pdgCode1=11) when analysing data (MC) processed (simulated) in release 6

binaryPID(pdgCode1, pdgCode2)

Returns the binary probability for the first provided mass hypothesis with respect to the second mass hypothesis using all detector components

binaryPID_noARICHwoECL(pdgCode1, pdgCode2)

Returns the binary probability for the first provided mass hypothesis with respect to the second mass hypothesis using all detector components, but ARICH info excluded for tracks without associated ECL cluster

binaryPID_noSVD(pdgCode1, pdgCode2)

Returns the binary probability for the first provided mass hypothesis with respect to the second mass hypothesis using all detector components, excluding the SVD.

deuteronID

deuteron identification probability defined as \(\mathcal{L}_d/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors

deuteronID_noSVD

(SPECIAL (TEMP) variable) deuteron identification probability defined as \(\mathcal{L}_d/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the SVD

electronID

electron identification probability defined as \(\mathcal{L}_e/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors

electronID_noSVD

(SPECIAL (TEMP) variable) electron identification probability defined as \(\mathcal{L}_e/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the SVD

electronID_noSVD_noTOP

(SPECIAL (TEMP) variable) electron identification probability defined as \(\mathcal{L}_e/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the SVD and the TOP. NB: this variable must be used in place of electronID when analysing data (MC) processed (simulated) in release 5

electronID_noTOP

(SPECIAL (TEMP) variable) electron identification probability defined as \(\mathcal{L}_e/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the TOP. NB: this variable must be used in place of electronID when analysing data (MC) processed (simulated) in release 6

isPIDAvailable

True if PID is available (for at least one of the PID detectors

isPIDAvailableFrom(detectorList)

True if PID is available for at least one of the detectors in the list)

kaonID

kaon identification probability defined as \(\mathcal{L}_K/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors

kaonIDNN

kaon identification probability as calculated from the PID neural network.

kaonID_noARICHwoECL

(SPECIAL (TEMP) variable) kaon identification probability defined as \(\mathcal{L}_K/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors but ARICH info excluded for tracks without associated ECL cluster

kaonID_noSVD

(SPECIAL (TEMP) variable) kaon identification probability defined as \(\mathcal{L}_K/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the SVD

muonID

muon identification probability defined as \(\mathcal{L}_\mu/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors

muonID_noSVD

(SPECIAL (TEMP) variable) muon identification probability defined as \(\mathcal{L}_\mu/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the SVD

nbarID

Returns MVA classifier for antineutron PID.

• 1 signal(antineutron) like

• 0 background like

• -1 invalid using this PID due to some ECL variables used unavailable

This PID is only for antineutron. Neutron is also considered as background. The variables used are clusterPulseShapeDiscriminationMVA, clusterE, clusterLAT, clusterE1E9, clusterE9E21, clusterAbsZernikeMoment40, clusterAbsZernikeMoment51, clusterZernikeMVA.

particleID

the particle identification probability under the particle’s own hypothesis, using info from all available detectors

pidChargedBDTScore(pdgCodeHyp, detector)

Returns the charged Pid BDT score for a certain mass hypothesis with respect to all other charged stable particle hypotheses. The second argument specifies which BDT training to use: based on ‘ALL’ PID detectors (NB: ‘SVD’ is currently excluded), or ‘ECL’ only. The choice depends on the ChargedPidMVAMulticlassModule’s configuration.

pidPairChargedBDTScore(pdgCodeHyp, pdgCodeTest, detector)

Returns the charged Pid BDT score for a certain mass hypothesis with respect to an alternative hypothesis. The second argument specifies which BDT training to use: based on ‘ALL’ PID detectors (NB: ‘SVD’ is currently excluded), or ‘ECL’ only. The choice depends on the ChargedPidMVAModule’s configuration.

pionID

pion identification probability defined as \(\mathcal{L}_\pi/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors

pionIDNN

pion identification probability as calculated from the PID neural network.

pionID_noARICHwoECL

(SPECIAL (TEMP) variable) pion identification probability defined as \(\mathcal{L}_\pi/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors but ARICH info excluded for tracks without associated ECL cluster

pionID_noSVD

(SPECIAL (TEMP) variable) pion identification probability defined as \(\mathcal{L}_\pi/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the SVD

protonID

proton identification probability defined as \(\mathcal{L}_p/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors

protonID_noSVD

(SPECIAL (TEMP) variable) proton identification probability defined as \(\mathcal{L}_p/(\mathcal{L}_e+\mathcal{L}_\mu+\mathcal{L}_\pi+\mathcal{L}_K+\mathcal{L}_p+\mathcal{L}_d)\), using info from all available detectors excluding the SVD

weightedDeuteronID(weightMatrixName)

weighted deuteron identification probability defined as \(\frac{\mathcal{\tilde{L}}_d}{\sum_{i=e,\mu,\pi,K,p,d} \mathcal{\tilde{L}}_i}\), where \(\mathcal{\tilde{L}}_i\) is defined as \(\log\mathcal{\tilde{L}}_i = \sum_{j={\mathrm{SVD, CDC, TOP, ARICH, ECL, KLM}}} \mathcal{w}_{ij}\log\mathcal{L}_{ij}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector. One can provide the name of the weight matrix as the argument.

weightedElectronID(weightMatrixName)

weighted electron identification probability defined as \(\frac{\mathcal{\tilde{L}}_e}{\sum_{i=e,\mu,\pi,K,p,d} \mathcal{\tilde{L}}_i}\), where \(\mathcal{\tilde{L}}_i\) is defined as \(\log\mathcal{\tilde{L}}_i = \sum_{j={\mathrm{SVD, CDC, TOP, ARICH, ECL, KLM}}} \mathcal{w}_{ij}\log\mathcal{L}_{ij}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector. One can provide the name of the weight matrix as the argument.

weightedKaonID(weightMatrixName)

weighted kaon identification probability defined as \(\frac{\mathcal{\tilde{L}}_K}{\sum_{i=e,\mu,\pi,K,p,d} \mathcal{\tilde{L}}_i}\), where \(\mathcal{\tilde{L}}_i\) is defined as \(\log\mathcal{\tilde{L}}_i = \sum_{j={\mathrm{SVD, CDC, TOP, ARICH, ECL, KLM}}} \mathcal{w}_{ij}\log\mathcal{L}_{ij}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector. One can provide the name of the weight matrix as the argument.

weightedMuonID(weightMatrixName)

weighted muon identification probability defined as \(\frac{\mathcal{\tilde{L}}_\mu}{\sum_{i=e,\mu,\pi,K,p,d} \mathcal{\tilde{L}}_i}\), where \(\mathcal{\tilde{L}}_i\) is defined as \(\log\mathcal{\tilde{L}}_i = \sum_{j={\mathrm{SVD, CDC, TOP, ARICH, ECL, KLM}}} \mathcal{w}_{ij}\log\mathcal{L}_{ij}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector. One can provide the name of the weight matrix as the argument.

weightedPionID(weightMatrixName)

weighted pion identification probability defined as \(\frac{\mathcal{\tilde{L}}_\pi}{\sum_{i=e,\mu,\pi,K,p,d} \mathcal{\tilde{L}}_i}\), where \(\mathcal{\tilde{L}}_i\) is defined as \(\log\mathcal{\tilde{L}}_i = \sum_{j={\mathrm{SVD, CDC, TOP, ARICH, ECL, KLM}}} \mathcal{w}_{ij}\log\mathcal{L}_{ij}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector. One can provide the name of the weight matrix as the argument.

weightedProtonID(weightMatrixName)

weighted proton identification probability defined as \(\frac{\mathcal{\tilde{L}}_p}{\sum_{i=e,\mu,\pi,K,p,d} \mathcal{\tilde{L}}_i}\), where \(\mathcal{\tilde{L}}_i\) is defined as \(\log\mathcal{\tilde{L}}_i = \sum_{j={\mathrm{SVD, CDC, TOP, ARICH, ECL, KLM}}} \mathcal{w}_{ij}\log\mathcal{L}_{ij}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector. One can provide the name of the weight matrix as the argument.

Basic particle information

charge

Returns electric charge of particle in units of \(e\).

chiProb

A context-dependent \(\chi^2\) probability for ‘the fit’ related to this particle.

• If this particle is track-based, then this is the pvalue of the track fit (identical to pValue).

• If this particle is cluster-based then this variable is currently unused.

• If this particle is composite and a vertex fit has been performed, then this is the \(\chi^2\) probability of the vertex fit result.

Tip

If multiple vertex fits are performed then the last one sets the chiProb overwriting all previous.

See also

pValue for tracks

flavor

Returns 1 if particle is flavored type, 0 if it is unflavored.

isFromECL

Returns true if this particle was created from an ECLCluster, false otherwise.

isFromKLM

Returns true if this particle was created from a KLMCluster, false otherwise.

isFromTrack

Returns true if this particle was created from a track, false otherwise.

isFromV0

Returns true if this particle was created from a V0, false otherwise.

isUnspecified

Returns true if the particle is marked as an unspecified object (like B0 -> @Xsd e+ e-), false otherwise

mdstIndex

Store array index (0 - based) of the MDST object from which the Particle was created. It’s 0 for composite particles.

Tip

It is not a unique identifier of particle. For example, a pion and a gamma can have the same mdstIndex: pions are created from tracks whereas gammas are created from ECL clusters; tracks and ECL clusters are stored in different arrays. A photon may be created from ECL cluster with index 0 and a pion may be created from track with index 0 will both have mdstIndex equal to 0, but they will be different particles.

Tip

Two particles of the same type can also have the same mdstIndex. This would mean that they are created from the same object. For example, if pion and kaon have the same mdstIndex it means that they are created from the same track.

Tip

If you are looking for unique identifier of the particle, please use uniqueParticleIdentifier.

nDaughters

Returns number of daughter particles

particleSource

Returns mdst source used to create the particle. The meaning of the values are

• 0: undefined

• 1: created from track

• 2: created from ECL cluster

• 3: created from KLM cluster

• 4: created from V0

• 5: MC particle

• 6: composite particle

uniqueParticleIdentifier

Returns unique identifier of final state particle. Particles created from the same object (e.g. from the same track) have different uniqueParticleIdentifier value.

PID for expert

These expert-level variables are metavariable that allow the used to access the LogLikelihood values, the binary likelihood ratios and the global likelihood ratios for any arbitrary detector combination of mass hypothesis. The accepted detector codes are SVD, TOP, CDC, ARICH, ECL, KLM and ALL.

If a likelihood is not available from the selected detector list, NaN is returned.

Warning

These variables are not to be used in physics analyses, but only by experts doing performance studies.

klmMuonIDDNN

Muon probability calculated from Neural Network with KLM information (expert use only)

pidDeltaLogLikelihoodValueExpert(pdgCode1, pdgCode2, detectorList)

returns LogL(hyp1) - LogL(hyp2) (aka DLL) for two mass hypotheses and a set of detectors.

pidIsMostLikely(ePrior=1/6, muPrior=1/6, piPrior=1/6, KPrior=1/6, pPrior=1/6, dPrior=1/6)

Returns True if the largest PID likelihood of a given particle corresponds to its particle hypothesis. This function accepts either no arguments, or 6 floats as priors for the charged particle hypotheses following the order shown in the metavariable’s declaration. Flat priors are assumed as default.

pidLogLikelihoodValueExpert(pdgCode, detectorList)

returns the log likelihood value of for a specific mass hypothesis and set of detectors.

pidLogarithmicProbabilityExpert(pdgCodeHyp, detectorList)

logarithmic equivalent of pidProbability (p) defined as log(p/(1-p)), which gives a smooth peak-like distribution

pidMissingProbabilityExpert(detectorList)

returns 1 if PID is missing for at least one of the detectors in the list, otherwise 0.

pidMostLikelyPDG(ePrior=1/6, muPrior=1/6, piPrior=1/6, KPrior=1/6, pPrior=1/6, dPrior=1/6)

Returns PDG code of the largest PID likelihood, or NaN if PID information is not available. This function accepts either no arguments, or 6 floats as priors for the charged particle hypotheses following the order shown in the metavariable’s declaration. Flat priors are assumed as default.

pidNeuralNetworkValueExpert(pdgCodeHyp, PIDNeuralNetworkName)

Probability for the particle hypothesis pdgCodeHype calculated from a neural network, which uses high-level information as inputs, such as the likelihood from the 6 subdetectors for PID for all 6 hypotheses, \(\mathcal{\tilde{L}}_{hyp}^{det}\), or the track momentum and charge

pidPairProbabilityExpert(pdgCodeHyp, pdgCodeTest, detectorList)

Pair (or binary) probability for the pdgCodeHyp mass hypothesis respect to the pdgCodeTest one, using an arbitrary set of detectors. \(\mathcal{L}_{hyp}/(\mathcal{L}_{test}+\mathcal{L}_{hyp})\)

pidProbabilityExpert(pdgCodeHyp, detectorList)

probability for the pdgCodeHyp mass hypothesis respect to all the other ones, using an arbitrary set of detectors \(\mathcal{L}_{hyp}/(\Sigma_{\text{all~hyp}}\mathcal{L}_{i})\).

pidWeightedLogLikelihoodValueExpert(weightMatrixName, pdgCode, detectorList)

returns the weighted log likelihood value of for a specific mass hypothesis and set of detectors, \(\log\mathcal{\tilde{L}}_{hyp} = \sum_{j\in\mathrm{detectorList}} \mathcal{w}_{hyp,j}\log\mathcal{L}_{hyp,j}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector.

pidWeightedPairProbabilityExpert(weightMatrixName, pdgCodeHyp, pdgCodeTest, detectorList)

Weighted pair (or binary) probability for the pdgCodeHyp mass hypothesis with respect to the pdgCodeTest one, using an arbitrary set of detectors, \(\mathcal{\tilde{L}}_{hyp}/(\mathcal{\tilde{L}}_{test}+\mathcal{\tilde{L}}_{hyp})\) where \(\mathcal{\tilde{L}}_{i}\) is defined as \(\log\mathcal{\tilde{L}}_{i} = \sum_{j\in\mathrm{detectorList}} \mathcal{w}_{i,j}\log\mathcal{L}_{i,j}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector.

pidWeightedProbabilityExpert(weightMatrixName, pdgCodeHyp, detectorList)

Weighted probability for the pdgCodeHyp mass hypothesis with respect to all the other ones, using an arbitrary set of detectors, \(\mathcal{\tilde{L}}_{hyp}/\sum_{i=e,\mu,\pi,K,p,d} \mathcal{\tilde{L}}_i\) where \(\mathcal{\tilde{L}}_{i}\) is defined as \(\log\mathcal{\tilde{L}}_{i} = \sum_{j\in\mathrm{detectorList}} \mathcal{w}_{i,j}\log\mathcal{L}_{i,j}\). The \(\mathcal{L}_{ij}\) is the original likelihood and \(\mathcal{w}_{ij}\) is the PID calibration weight of i-th particle type and j-th detector.

ECL Cluster

Here is a list of variables related to ECL cluster. All ECLCluster-based variables return NaN if no ECLCluster is found.

Note

All floating type variables in the mdst dataobject ECLCluster use ROOT Double32_t types with specific range declaration to save disk storage. This has two important consequences for a user:

• All ECL cluster variables have a limited precision. This precision is always better than the intrinsic ECL data acquisition precision. However, if these variables are histogrammed, binning effects are likely.

• All ECL cluster variables are clipped at the lower and upper boundaries: Values below (above) these boundaries will be set to the lower (upper) bound.

Lower and upper limits, and precision of these variables are mentioned inside the note box below them. One should note this in the context of binning effects.

beamBackgroundSuppression

Returns the output of an MVA classifier that uses shower-related variables to distinguish true photon clusters from beam background clusters. Class 1 is for true photon clusters while class 0 is for beam background clusters.

The MVA has been trained using MC and the features used are:

• clusterTiming

• clusterPulseShapeDiscriminationMVA

• clusterE

• clusterTheta

• clusterZernikeMVA

Both run-dependent and run-independent weights are available. For more information on this, and for usage recommendations, please see the Neutrals Performance Confluence Page.

clusterAbsZernikeMoment40

Returns absolute value of Zernike moment 40 (\(|Z_{40}|\)). (shower shape variable).

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.7\)

Precision: \(10\) bit

clusterAbsZernikeMoment51

Returns absolute value of Zernike moment 51 (\(|Z_{51}|\)). (shower shape variable).

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.2\)

Precision: \(10\) bit

clusterCellID

Returns cellId of the crystal with highest energy in the ECLCluster.

clusterClusterID

Returns ECL cluster ID of this ECL cluster within the connected region (CR) to which it belongs to.

clusterConnectedRegionID

Returns ECL cluster’s connected region ID.

clusterDeltaLTemp

Returns DeltaL for the shower shape.

A cluster comprises the energy depositions of several crystals. All these crystals have slightly different orientations in space. A shower direction can be constructed by calculating the weighted average of these orientations using the corresponding energy depositions as weights. The intersection (more precisely the point of closest approach) of the vector with this direction originating from the cluster center and an extrapolated track can be used as reference for the calculation of the shower depth. It is defined as the distance between this intersection and the cluster center.

Warning

This distance is calculated on the reconstructed level and is temporarily included to the ECL cluster MDST data format for studying purposes. If it is found that it is not crucial for physics analysis then this variable will be removed in future releases. Therefore, keep in mind that this variable might be removed in the future!

Note

Please read this first.

Lower limit: \(-250.0\)

Upper limit: \(250.0\)

Precision: \(10\) bit

Unit:

cm

clusterE

Returns ECL cluster’s energy corrected for leakage and background.

The raw photon energy is given by the weighted sum of all ECL crystal energies within the ECL cluster. The weights per crystals are \(\leq 1\) after cluster energy splitting in the case of overlapping clusters. The number of crystals that are included in the sum depends on a initial energy estimation and local beam background levels at the highest energy crystal position. It is optimized to minimize the core width (resolution) of true photons. Photon energy distributions always show a low energy tail due to unavoidable longitudinal and transverse leakage that can be further modified by the clustering algorithm and beam backgrounds.The peak position of the photon energy distributions are corrected to match the true photon energy in MC:

• Leakage correction: Using large MC samples of mono-energetic single photons, a correction factor \(f\) as function of reconstructed detector position, reconstructed photon energy and beam backgrounds is determined via \(f = \frac{\text{peak_reconstructed}}{\text{energy_true}}\).

• Cluster energy calibration (data only): To reach the target precision of \(< 1.8\%\) energy resolution for high energetic photons, the remaining difference between MC and data must be calibrated using kinematically fit muon pairs. This calibration is only applied to data and not to MC and will take time to develop.

• Energy Bias Correction module, sub-percent correction, is NOT applied on clusterE, but on photon energy and momentum. Only applied to data.

It is important to note that after perfect leakage correction and cluster energy calibration, the \(\pi^{0}\) mass peak will be shifted slightly to smaller values than the PDG average due to the low energy tails of photons. The \(\pi^{0}\) mass peak must not be corrected to the PDG value by adjusting the reconstructed photon energies. Selection criteria based on the mass for \(\pi^{0}\) candidates must be based on the biased value. Most analysis will used mass constrained \(\pi^{0}\) s anyhow.

Warning

We only store clusters with \(E > 20\,\) MeV.

Note

Please read this first.

Lower limit: \(-5\) (\(e^{-5} = 0.00674\,\) GeV)

Upper limit: \(3.0\) (\(e^3 = 20.08553\,\) GeV)

Precision: \(18\) bit

This value can be changed to a different reference frame with useCMSFrame.

Unit:

GeV

clusterE1E9

Returns ratio of energies of the central crystal, E1, and 3x3 crystals, E9, around the central crystal. Since \(E1 \leq E9\), this ratio is \(\leq 1\) and tends towards larger values for photons and smaller values for hadrons.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.0\)

Precision: \(10\) bit

clusterE9E21

Returns ratio of energies in inner 3x3 crystals, E9, and 5x5 crystals around the central crystal without corners. Since \(E9 \leq E21\), this ratio is \(\leq 1\) and tends towards larger values for photons and smaller values for hadrons.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.0\)

Precision: \(10\) bit

clusterE9E25

Deprecated - kept for backwards compatibility - returns clusterE9E21.

clusterEoP

Returns ratio of uncorrelated energy E over momentum p, a convenience alias for (clusterE / p).

clusterErrorE

Returns ECL cluster’s uncertainty on energy (from background level and energy dependent tabulation).

Unit:

GeV

clusterErrorPhi

Returns ECL cluster’s uncertainty on \(\phi\) (from background level and energy dependent tabulation).

Unit:

rad

clusterErrorTheta

Returns ECL cluster’s uncertainty on \(\theta\) (from background level and energy dependent tabulation).

Unit:

rad

clusterErrorTiming

Returns ECL cluster’s timing uncertainty that contains \(99\%\) of true photons (dt99).

The photon timing uncertainty is currently determined using MC. The resulting parametrization depends on the true energy deposition in the highest energetic crystal and the local beam background level in that crystal. The resulting timing distribution is non-Gaussian and for each photon the value dt99 is stored, where \(|\text{timing}| / \text{dt99} < 1\) is designed to give a \(99\%\) timing efficiency for true photons from the IP. The resulting efficiency is approximately flat in energy and independent of beam background levels.

Very large values of dt99 are an indication of failed waveform fits in the ECL. We remove such clusters in most physics photon lists.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1000.0\)

Precision: \(12\) bit

Warning

In real data there will be a sizeable number of high energetic Bhabha events (from previous or later bunch collisions) that can easily be rejected by timing cuts. However, these events create large ECL clusters that can overlap with other ECL clusters and it is not clear that a simple rejection is the correction strategy.

Unit:

ns

clusterHasFailedErrorTiming

Status bit for if the ECL cluster’s timing uncertainty calculation failed. Photon timing is given by the fitted time of the recorded waveform of the highest energetic crystal in a cluster; however, that fit can fail and so this variable tells the user if that has happened.

clusterHasFailedTiming

Status bit for if the ECL cluster’s timing fit failed. Photon timing is given by the fitted time of the recorded waveform of the highest energetic crystal in a cluster; however, that fit can fail and so this variable tells the user if that has happened.

clusterHasNPhotons

Returns 1.0 if cluster has the ‘N photons’ hypothesis (historically called ‘N1’), 0.0 if not, and NaN if no cluster is associated to the particle.

clusterHasNeutralHadron

Returns 1.0 if the cluster has the ‘neutral hadrons’ hypothesis (historically called ‘N2’), 0.0 if not, and NaN if no cluster is associated to the particle.

clusterHasPulseShapeDiscrimination

Status bit to indicate if cluster has digits with waveforms that passed energy and \(\chi^2\) thresholds for computing PSD variables.

clusterHighestE

Returns energy of the highest energetic crystal in the ECL cluster after reweighting.

Warning

This variable must be used carefully since it can bias shower selection towards photons that hit crystals in the center and hence have a large energy deposition in the highest energy crystal.

Note

Please read this first.

Lower limit: \(-5\) (\(e^{-5} = 0.00674\,\) GeV)

Upper limit: \(3.0\) (\(e^3 = 20.08553\,\) GeV)

Precision: \(18\) bit

Unit:

GeV

clusterKlId

Returns MVA classifier that uses ECL clusters variables to discriminate Klong clusters from em background.

• 1 for Kl

• 0 for background

clusterLAT

Returns lateral energy distribution (shower variable). It is defined as following:

\[S = \frac{\sum_{i=2}^{n} w_{i} E_{i} r^2_{i}}{(w_{0} E_{0} + w_{1} E_{1}) r^2_{0} + \sum_{i=2}^{n} w_{i} E_{i} r^2_{i}}\]

where \(E_{i} = (E_{0}, E_{1}, ...)\) are the single crystal energies sorted by energy (\(E_{0}\) is the highest energy and \(E_{1}\) the second highest), \(w_{i}\) is the crystal weight, \(r_{i}\) is the distance of the \(i\)-th digit to the shower center projected to a plane perpendicular to the shower axis, and \(r_{0} \approx 5\,cm\) is the distance between two crystals.

clusterLAT peaks around 0.3 for radially symmetrical electromagnetic showers and is larger for hadronic events, and electrons with a close-by radiative or Bremsstrahlung photon.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.0\)

Precision: \(10\) bit

clusterMdstIndex

StoreArray index(0 - based) of the MDST ECLCluster (useful for track-based particles matched to a cluster).

clusterNHits

Returns sum of weights \(w_{i}\) (\(w_{i} \leq 1\)) of all crystals in an ECL cluster. For non-overlapping clusters this is equal to the number of crystals in the cluster. In case of energy splitting among nearby clusters, this can be a non-integer value.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(200.0\)

Precision: \(10\) bit

If fractional weights are not of interest, this value should be cast to the nearest integer.

clusterNumberOfHadronDigits

Returns ECL cluster’s number of hadron digits in cluster (pulse shape discrimination variable). Weighted sum of digits in cluster with significant scintillation emission (\(> 3\,\) MeV) in the hadronic scintillation component. Computed only using cluster digits with energy \(> 50\,\) MeV and good offline waveform fit \(\chi^2\).

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(255.0\)

Precision: \(18\) bit

clusterPhi

Returns ECL cluster’s azimuthal angle \(\phi\) (this is not generally equal to a photon azimuthal angle).

The direction of a cluster is given by the connecting line of \(\,(0,0,0)\,\) and cluster centroid position in the ECL.

The cluster centroid position is calculated using up to 21 crystals (5x5 excluding corners) after cluster energy splitting in the case of overlapping clusters.

The centroid position is the logarithmically weighted average of all crystals evaluated at the crystal centers. Cluster centroids are generally biased towards the centers of the highest energetic crystal. This effect is larger for low energetic photons.

Beam backgrounds slightly decrease the position resolution, mainly for low energetic photons.

Note

Radius of a cluster is almost constant in the barrel and should not be used directly in any selection.

Unlike for charged tracks, the uncertainty (covariance) of the photon directions is not determined based on individual cluster properties but taken from on MC-based parametrizations of the resolution as function of true photon energy, true photon direction and beam background level.

Warning

Users must use the actual particle direction (done automatically in the modularAnalysis using the average IP position (can be changed if needed)) and not the ECL Cluster direction (position in the ECL measured from \((0,0,0)\)) for particle kinematics.

Note

Please read this first.

Lower limit: \(-\pi\)

Upper limit: \(\pi\)

Precision: \(16\) bit

Unit:

rad

clusterPhiID

Returns phiId of the crystal with highest energy in the ECLCluster.

clusterPulseShapeDiscriminationMVA

Returns MVA classifier that uses pulse shape discrimination to identify electromagnetic vs hadronic showers.

• 1 for electromagnetic showers

• 0 for hadronic showers

clusterR

Returns ECL cluster’s centroid distance from \((0,0,0)\).

Unit:

cm

clusterReg

Returns an integer code for the ECL region of a cluster.

• 1: forward, 2: barrel, 3: backward,

• 11: between FWD and barrel, 13: between BWD and barrel,

• 0: otherwise

clusterSecondMoment

Returns second moment \(S\). It is defined as:

\[S = \frac{1}{S_{0}(\theta)}\frac{\sum_{i=0}^{n} w_{i} E_{i} r^2_{i}}{\sum_{i=0}^{n} w_{i} E_{i}}\]

where \(E_{i} = (E_0, E_1, ...)\) are the single crystal energies sorted by energy, \(w_{i}\) is the crystal weight, and \(r_{i}\) is the distance of the \(i\)-th digit to the shower center projected to a plane perpendicular to the shower axis. \(S_{0}(\theta)\) normalizes \(S\) to 1 for isolated photons.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(40.0\)

Precision: \(10\) bit

Unit:

dimensionless

clusterTheta

Returns ECL cluster’s polar angle \(\theta\) (this is not generally equal to a photon polar angle).

The direction of a cluster is given by the connecting line of \(\,(0,0,0)\,\) and cluster centroid position in the ECL.

The cluster centroid position is calculated using up to 21 crystals (5x5 excluding corners) after cluster energy splitting in the case of overlapping clusters.

The centroid position is the logarithmically weighted average of all crystals evaluated at the crystal centers. Cluster centroids are generally biased towards the centers of the highest energetic crystal. This effect is larger for low energetic photons.

Beam backgrounds slightly decrease the position resolution, mainly for low energetic photons.

Note

Radius of a cluster is almost constant in the barrel and should not be used directly in any selection.

Unlike for charged tracks, the uncertainty (covariance) of the photon directions is not determined based on individual cluster properties but taken from on MC-based parametrizations of the resolution as function of true photon energy, true photon direction and beam background level.

Warning

Users must use the actual particle direction (done automatically in the modularAnalysis using the average IP position (can be changed if needed)) and not the ECL Cluster direction (position in the ECL measured from \((0,0,0)\)) for particle kinematics.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(\pi\)

Precision: \(16\) bit

Unit:

rad

clusterThetaID

Returns thetaId of the crystal with highest energy in the ECLCluster.

clusterTiming

In Belle II: Returns the time of the ECL cluster. It is calculated as the Photon timing minus the Event t0. Photon timing is given by the fitted time of the recorded waveform of the highest energy crystal in the cluster. After all calibrations and corrections (including Time-Of-Flight), photons from the interaction point (IP) should have a Photon timing that corresponds to the Event t0, \(t_{0}\). The Event t0 is the time of the event and may be measured by a different sub-detector (see Event t0 documentation). For an ECL cluster produced at the interaction point in time with the event, the cluster time should be consistent with zero within the uncertainties. Special values are returned if the fit for the Photon timing fails (see documentation for clusterHasFailedTiming). (For MC, the calibrations and corrections are not fully simulated).

Note

Please read this first.

Lower limit: \(-1000.0\)

Upper limit: \(1000.0\)

Precision: \(12\) bit

In Belle: Returns the trigger cell (TC) time of the ECL cluster (photon). This information is available only in Belle data since experiment 31, and not available in Belle MC. Clusters produced at the interaction point in time with the event, have TC time in the range of 9000-11000 Calculated based on the Appendix of Belle note 831.

Note

In case this variable is obtained from Belle data that is stored in Belle II mdst/udst format, it will be truncated to:

Lower limit: \(-1000.0\)

Upper limit: \(1000.0\)

Precision: \(12\) bit

Unit:

ns

clusterTrackMatch

Returns 1.0 if at least one reconstructed charged track is matched to the ECL cluster.

Every reconstructed charged track is extrapolated into the ECL. Every ECL crystal that is crossed by the track extrapolation is marked. Each ECL cluster that contains any marked crystal is matched to the track. Multiple tracks can be matched to one cluster and multiple clusters can be matched to one track. It is conceptually correct to have two tracks matched to the same cluster.

clusterUncorrE

[Expert] [Calibration] Returns ECL cluster’s uncorrected energy. That is, before leakage corrections. This variable should only be used for study of the ECL. Please see clusterE.

Unit:

GeV

clusterZernikeMVA

Returns output of a MVA using eleven Zernike moments of the cluster. Zernike moments are calculated per shower in a plane perpendicular to the shower direction via

\[|Z_{nm}| = \frac{n+1}{\pi} \frac{1}{\sum_{i} w_{i} E_{i}} \left|\sum_{i} R_{nm}(\rho_{i}) e^{-im\alpha_{i}} w_{i} E_{i} \right|\]

where n, m are the integers, \(i\) runs over the crystals in the shower, \(E_{i}\) is the energy of the i-th crystal in the shower, \(R_{nm}\) is a polynomial of degree \(n\), \(\rho_{i}\) is the radial distance of the \(i\)-th crystal in the perpendicular plane, and \(\alpha_{i}\) is the polar angle of the \(i\)-th crystal in the perpendicular plane. As a crystal can be related to more than one shower, \(w_{i}\) is the fraction of the energy of the \(i\)-th crystal associated with the shower.

More details about the implementation can be found in BELLE2-NOTE-TE-2017-001 .

More details about Zernike polynomials can be found in Wikipedia .

For cluster with hypothesisId==N1: raw MVA output.

For cluster with hypothesisId==N2: 1 - prod{clusterZernikeMVA}, where the product is on all N1 showers belonging to the same connected region (shower shape variable).

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(1.0\)

Precision: \(10\) bit

distanceToMcKl

Returns the distance to the nearest truth KL particle, extrapolated to the cluster radius. To use this variable, it is required to run getNeutralHadronGeomMatches function. Optionally, it can return negative values to indicate that the ECL cluster should be removed from the analysis to correct for data to MC difference in KL efficiency.

Unit:

cm

distanceToMcNeutron

Returns the distance to the nearest truth (anti)neutron, extrapolated to the cluster radius. To use this variable, it is required to run getNeutralHadronGeomMatches function. Optionally, it can return negative values to indicate that the ECL cluster should be removed from the analysis to correct for data to MC difference in KL efficiency.

Unit:

cm

eclClusterOnlyInvariantMass

[Expert] The invariant mass calculated from all ECLCluster daughters (i.e. photons) and cluster-matched tracks using the cluster 4-momenta.

Used for ECL-based dark sector physics and debugging track-cluster matching.

Unit:

GeV/\(\text{c}^2\)

eclExtPhi

Returns extrapolated \(\phi\) of particle track associated to the cluster (if any). Requires module ECLTrackCalDigitMatch to be executed..

Unit:

rad

eclExtPhiId

Returns extrapolated \(\phi\) ID of particle track associated to the cluster (if any). Requires module ECLTrackCalDigitMatch to be executed..

eclExtTheta

Returns extrapolated \(\theta\) of particle track associated to the cluster (if any). Requires module ECLTrackCalDigitMatch to be executed.

Unit:

rad

fakePhotonSuppression

Returns the output of an MVA classifier that uses shower-related variables to distinguish true photon clusters from fake photon clusters (e.g. split-offs, track-cluster matching failures etc.). Class 1 is for true photon clusters while class 0 is for fake photon clusters.

The MVA has been trained using MC and the features are:

• clusterPulseShapeDiscriminationMVA

• minC2TDist

• clusterZernikeMVA

• clusterE

• clusterTiming

• clusterTheta

This MVA is the same as the one used for hadronicSplitOffSuppression but that variable should not be used as it is deprecated and does not use the new weights.

Both run-dependent and run-independent weights are available. For more information on this, and for usage recommendations, please see the Neutrals Performance Confluence Page.

hadronicSplitOffSuppression

Returns the output of an MVA classifier that uses shower-related variables to distinguish true photon clusters from hadronic splitoff clusters. The classes are:

• 1 for true photon clusters

• 0 for hadronic splitoff clusters

The MVA has been trained using samples of signal photons and hadronic splitoff photons coming from MC. The features used are (in decreasing order of significance):

• clusterPulseShapeDiscriminationMVA

• minC2TDist

• clusterZernikeMVA

• clusterE

• clusterLAT

• clusterE1E9

• clusterSecondMoment

Note

Deprecated since version light-2302-genetta.

Use the variable fakePhotonSuppression instead which is maintained and uses the latest weight files.

maxWeightedDistanceFromAverageECLTime

Returns maximum weighted distance between time of the cluster of a photon and the ECL average time, amongst the clusters (neutrals) and matched clusters (charged) of daughters (of all generations) of the provided particle.

Unit:

ns

mdstIndexMcKl

Returns the mdst index of the nearest truth KL, extrapolated to the cluster radius, if it is within the matching cone. To use this variable, it is required to run getNeutralHadronGeomMatches function.

mdstIndexMcNeutron

Returns the mdst index of the nearest truth (anti)neutron, extrapolated to the cluster radius, if it is within the matching cone. To use this variable, it is required to run getNeutralHadronGeomMatches function.

minC2TDist

Returns the distance between the ECL cluster and its nearest track.

For all tracks in the event, the distance between each of their extrapolated hits in the ECL and the ECL shower position is calculated, and the overall smallest distance is returned. The track array index of the track that is closest to the ECL cluster can be retrieved using minC2TDistID.

If the calculated distance is greater than \(250.0\), the returned distance will be capped at \(250.0\). If there are no extrapolated hits found in the ECL for the event, NaN will be returned.

Note

This distance is calculated on the reconstructed level.

Note

Please read this first.

Lower limit: \(0.0\)

Upper limit: \(250.0\)

Precision: \(10\) bit

Unit:

cm

minC2TDistID

Returns the track array index of the nearest track to the ECL cluster. The nearest track is calculated using the minC2TDist variable.

minC2TDistVar(variable, particleList=pi-:all)

Returns the variable value of the nearest track to the given ECL cluster as calculated by minC2TDist. The first argument is the variable name, e.g. nCDCHits, while the second (optional) argument is the particle list name which will be used to pick up the nearest track in the calculation of minC2TDist. The default particle list used is pi-:all.

nECLClusterTrackMatches

Returns number of charged tracks matched to this cluster.

Note

Sometimes (perfectly correctly) two tracks are extrapolated into the same cluster.

• For charged particles, this should return at least 1 (but sometimes 2 or more).

• For neutrals, this should always return 0.

• Returns NaN if there is no cluster.

nECLLocalMaximums

[Eventbased] Returns the number of LocalMaximums in the ECL.

nECLLocalMaximumsBWDEndcap

[Eventbased] Returns the number of LocalMaximums in the ECL backward endcap.

nECLLocalMaximumsBarrel

[Eventbased] Returns the number of LocalMaximums in the ECL barrel.

nECLLocalMaximumsFWDEndcap

[Eventbased] Returns the number of LocalMaximums in the ECL forward endcap.

nECLOutOfTimeCrystals

[Eventbased] Returns the number of crystals (ECLCalDigits) that are out of time.

nECLOutOfTimeCrystalsBWDEndcap

[Eventbased] Returns the number of crystals (ECLCalDigits) that are out of time in the backward endcap.

nECLOutOfTimeCrystalsBarrel

[Eventbased] Returns the number of crystals (ECLCalDigits) that are out of time in the barrel.

nECLOutOfTimeCrystalsFWDEndcap

[Eventbased] Returns the number of crystals (ECLCalDigits) that are out of time in the forward endcap.

nECLShowers

[Eventbased] Returns the number of ECLShowers.

nECLShowersBWDEndcap

[Eventbased] Returns the number of ECLShowers in the backward endcap.

nECLShowersBarrel

[Eventbased] Returns the number of ECLShowers in the barrel.

nECLShowersFWDEndcap

[Eventbased] Returns the number of ECLShowers in the forward endcap.

nECLTriggerCells

[Eventbased] Returns the number of ECL trigger cells above 100 MeV.

nECLTriggerCellsBWDEndcap

[Eventbased] Returns the number of ECL trigger cells above 100 MeV in the backward endcap.

nECLTriggerCellsBarrel

[Eventbased] Returns the number of ECL trigger cells above 100 MeV in the barrel.

nECLTriggerCellsFWDEndcap

[Eventbased] Returns the number of ECL trigger cells above 100 MeV in the forward endcap.

nKLMMultistripHits

[Eventbased] Returns the number of multi-strip hits in the KLM.

nKLMMultistripHitsBWDEndcap

[Eventbased] Returns the number of multi-strip hits in the KLM backward endcap.

nKLMMultistripHitsBarrel

[Eventbased] Returns the number of multi-strip hits in the KLM barrel.

nKLMMultistripHitsFWDEndcap

[Eventbased] Returns the number of multi-strip hits in the KLM forward endcap.

nRejectedECLShowers

[Eventbased] Returns the number of showers in the ECL that do not become clusters.

nRejectedECLShowersBWDEndcap

[Eventbased] Returns the number of showers in the ECL that do not become clusters, from the backward endcap. If the number exceeds 255 (uint8_t maximum value) the variable is set to 255.

nRejectedECLShowersBarrel

[Eventbased] Returns the number of showers in the ECL that do not become clusters, from the barrel. If the number exceeds 255 (uint8_t maximum value) the variable is set to 255.

nRejectedECLShowersFWDEndcap

[Eventbased] Returns the number of showers in the ECL that do not become clusters, from the forward endcap. If the number exceeds 255 (uint8_t maximum value) the variable is set to 255.

photonHasOverlap(cutString, photonlistname, tracklistname)

Returns true if the connected ECL region of the particle’s cluster is shared by another particle’s cluster. Neutral and charged cluster are considered. A cut string can be provided to ignore cluster that do not satisfy the given criteria. By default, the ParticleList gamma:all is used for the check of neutral ECL cluster, and the ParticleList e-:all for the check of charged ECL cluster. However, one can customize the name of the ParticleLists via additional arguments. If no argument or only a cut string is provided and gamma:all or e-:all does not exist or if the variable is requested for a particle that is not a photon, NaN is returned.

weightedAverageECLTime

Returns ECL weighted average time of all clusters (neutrals) and matched clusters (charged) of daughters (of any generation) of the provided particle.

Unit:

ns

There are also some special variables related to the MC matching of ECL clusters (specifically).

clusterBestMCMatchWeight

Returns the weight of the ECLCluster -> MCParticle relation for the relation with the largest weight.

clusterBestMCPDG

Returns the PDG code of the MCParticle for the ECLCluster -> MCParticle relation with the largest weight.

clusterMCMatchWeight

Returns the weight of the ECLCluster -> MCParticle relation for the MCParticle matched to the particle. Returns NaN if: no cluster is related to the particle, the particle is not MC matched, or if there are no mcmatches for the cluster. Returns -1 if the cluster was matched to particles, but not the match of the particle provided.

clusterTotalMCMatchWeight

Returns the sum of all weights of the ECLCluster -> MCParticles relations.

clusterTotalMCMatchWeightForBestKlong

Returns the sum of all weights of the ECLCluster -> MCParticles relations when MCParticle is the same Klong or daughter of the Klong. If multiple MC Klongs are related to the ECLCluster, returns the sum of weights for the best matched Klong.

clusterTotalMCMatchWeightForKlong

Returns the sum of all weights of the ECLCluster -> MCParticles relations when MCParticle is a Klong or daughter of a Klong

Acceptance

Here is a list of variables for acceptance cuts:

inARICHAcceptance

Returns true if particle is within ARICH geometrical and kinematical acceptance, false otherwise. This variable is an alias for thetaInARICHAcceptance.

inCDCAcceptance

Returns true if particle is within CDC geometrical and kinematical acceptance, false otherwise. This variable is an alias for thetaInCDCAcceptance.

inECLAcceptance

Returns true if particle is within ECL geometrical and kinematical acceptance, false otherwise.”); This variable is a combination of thetaInEECLAcceptance, thetaInBECLAcceptance and ptInBECLAcceptance.

inKLMAcceptance

Returns true if particle is within KLM geometrical and kinematical acceptance, false otherwise. This variable is a combination of thetaInEKLMAcceptance, thetaInBKLMAcceptance and ptInBKLMAcceptance.

inTOPAcceptance

Returns true if particle is within TOP geometrical and kinematical acceptance, false otherwise. This variable is a combination of thetaInTOPAcceptance and ptInTOPAcceptance.

ptInBECLAcceptance

Returns true if particle transverse momentum \(p_t\) is within Barrel ECL acceptance, \(p_t > 0.28\) GeV, false otherwise.

ptInBKLMAcceptance

Returns true if particle transverse momentum \(p_t\) is within Barrel KLM acceptance, \(p_t > 0.6\) GeV, false otherwise.

ptInTOPAcceptance

Returns true if particle transverse momentum \(p_t\) is within TOP acceptance, \(p_t > 0.27\) GeV, false otherwise.

thetaInARICHAcceptance

Returns true if particle is within ARICH angular acceptance, false otherwise. This variable checks if the particle polar angle \(\theta\) is within the range \(14^\circ < \theta < 30^\circ\). The polar angle is computed using only the initial particle momentum.

thetaInBECLAcceptance

Returns true if particle is within Barrel ECL angular acceptance, false otherwise. This variable checks if the particle polar angle \(\theta\) is within the range \(32.2^\circ < \theta < 128.7^\circ\). The polar angle is computed using only the initial particle momentum.

thetaInBKLMAcceptance

Returns true if particle is within Barrel KLM angular acceptance, false otherwise. This variable checks if the particle polar angle \(\theta\) is within the range \(37^\circ < \theta < 130^\circ\). The polar angle is computed using only the initial particle momentum.

thetaInCDCAcceptance

Returns true if particle is within CDC angular acceptance, false otherwise. This variable checks if the particle polar angle \(\theta\) is within the range \(17^\circ < \theta < 150^\circ\). The polar angle is computed using only the initial particle momentum.

thetaInECLAcceptance

Checks if particle is within ECL angular acceptance. This variable checks if the particle polar angle \(\theta\) is within certain ranges. Return values and the corresponding \(\theta\) ranges are the following:

• 0: Outside of ECL acceptance, \(\theta < 12.4^\circ\) or \(\theta > 155.1^\circ\), or in one of the acceptance gaps at \(31.4^{\circ} < \theta < 32.2^{\circ}\) or \(128.7^{\circ} < \theta < 130.7^{\circ}\);

• 1: Forward ECL, \(12.4^\circ < \theta < 31.4^\circ\);

• 2: Barrel ECL, \(32.2^\circ < \theta < 128.7^\circ\);

• 3: Backward ECL, \(130.7^\circ < \theta < 155.1^\circ\).

The polar angle is computed using only the initial particle momentum.

thetaInEECLAcceptance

Returns true if particle is within Endcap ECL angular acceptance, false otherwise. This variable checks if the particle polar angle \(\theta\) is within the range \(12.4^\circ < \theta < 31.4^\circ\) or \(130.7^\circ < \theta < 155.1^\circ\). The polar angle is computed using only the initial particle momentum.

thetaInEKLMAcceptance

Returns true if particle is within Endcap KLM angular acceptance, false otherwise. This variable checks if the particle polar angle \(\theta\) is within the range \(18^\circ < \theta < 47^\circ\) or \(122^\circ < \theta < 155^\circ\). The polar angle is computed using only the initial particle momentum.

thetaInKLMAcceptance

Checks if particle is within KLM angular acceptance. This variable checks if the particle polar angle \(\theta\) is within certain ranges. Return values and the corresponding \(\theta\) ranges are the following:

• 0: Outside of KLM acceptance, \(\theta < 18^\circ\) or \(\theta < 155^\circ\).

• 1: Forward endcap, \(18^\circ < \theta < 37^\circ\);

• 2: Forward overlap, \(37^\circ < \theta < 47^\circ\);

• 3: Barrel, \(47^\circ < \theta < 122^\circ\);

• 4: Backward overlap, \(122^\circ < \theta < 130^\circ\);

• 5: Backward endcap, \(130^\circ < \theta < 155^\circ\).

The polar angle is computed using only the initial particle momentum.

thetaInKLMOverlapAcceptance

Returns true if particle is within the angular region where KLM barrel and endcaps overlap, false otherwise. This variable checks if the particle polar angle \(\theta\) is within the range \(37^\circ < \theta < 47^\circ\) or \(122^\circ < \theta < 130^\circ\). The polar angle is computed using only the initial particle momentum.

thetaInTOPAcceptance

Returns true if particle is within TOP angular acceptance, false otherwise. This variable checks if the particle polar angle \(\theta\) is within the range \(31^\circ < \theta < 128^\circ\). The polar angle is computed using only the initial particle momentum.

Trigger

Here is a list of trigger variables:

L1FTDL(name)

[Eventbased] Returns the FTDL (Final Trigger Decision Logic, before prescale) status (1 or 0) of the output trigger bit with the given name. Output bits are the outputs of GDL, combining different input trigger bits for final decision. For example, ty_0/1/2/3 is one of the input trigger bits meaning the number of neuro 3D tracks is one/two/three/more than three. While yyy is one of the output trigger bits meaning (ty_2 or ty_3) and !veto. Please check on the dedicated Confluence page or or the dedicated Belle II notes to find out the definition of trigger bits.

L1FTDLBit(i)

[Eventbased] Returns the FTDL (Final Trigger Decision Logic, before prescale) status (1 or 0) of i-th trigger bit.

Warning

It is recommended to use this variable only for debugging and to use L1FTDL with the explicit trigger bit name for physics analyses or performance studies.

L1Input(name)

[Eventbased] Returns the input bit status (1 or 0) of the trigger bit with the given name. Input trigger bits are predefined selections from each sub-detector, with adjustment of the delay and width, in order to fix latency on GDL. For example, ty_0/1/2/3 is one of the input trigger bits meaning the number of neuro 3D tracks is one/two/three/more than three. Please check on the dedicated Confluence page or or the dedicated Belle II notes to find out the definition of trigger bits.

L1InputBit(i)

[Eventbased] Returns the input bit status (1 or 0) of the i-th input trigger bit.

Warning

It is recommended to use this variable only for debugging and to use L1Input with the explicit trigger bit name for physics analyses or performance studies.

L1PSNM(name)

[Eventbased] Returns the PSNM (Prescale And Mask, after prescale) status (1 or 0) of the output trigger bit with the given name. For some output trigger bits, we assign a prescale factor to reduce the number of triggered events. For example, we want to keep only 1% of Bhabha events. A prescale factor of 100 is then assigned to bha_3D (Bhabha selected in 3D criteria). Prescale factor of a given output trigger bit could be different in different datasets. It is recommended to use prescaled trigger bits (L1PSNM) or un-prescaled trigger bits (L1FTDL) for your analysis. In run-independent MC, configuration of the prescales in TSIM (trigger simulation) can be different from data, so L1 FTDL is recommended. In run-dependent MC, configuration of the prescales in TSIM is consistent with data, so L1PSNM is recommended. Please check on the dedicated Confluence page or or the dedicated Belle II notes to find out the definition of trigger bits.

L1PSNMBit(i)

[Eventbased] Returns the PSNM (Prescale And Mask, after prescale) status (1 or 0) of i-th trigger bit.

Warning

It is recommended to use this variable only for debugging and to use L1PSNM with the explicit trigger bit name for physics analyses or performance studies.

L1PSNMBitPrescale(i)

[Eventbased] Returns the PSNM (prescale and mask) prescale of i-th trigger bit.

Warning

It is recommended to use this variable only for debugging and to use L1Prescale with the explicit trigger bit name for physics analyses or performance studies.

L1Prescale(name)

[Eventbased] Returns the PSNM (prescale and mask) prescale factor of the trigger bit with the given name. Definition of prescale factor is shown in a few lines before in L1PSNM. Prescale factors are usually dependent on different datasets.

L1TimeQuality

[Eventbased] Returns expected Level1 timing resolution. This flag will be used for SVD 3-point sampling in future. 0:None; 1:Coarse (sigma > x ns); 2:FINE (sigma < x ns); x has been set to about 5ns before LS1 but can be changed in future

L1TimeType

[Eventbased] Returns kind of detector which determines the Level1 trigger timing. 0:ECL, 1:TOP, 2:SELF(timing of PSNM bit), 3:CDC, 5:delayed bhabha, 7: random, 13:poisson.

L1Trigger

[Eventbased] Returns 1 if at least one PSNM L1 trigger bit is true.

isPoissonTriggerInInjectionVeto

[Eventbased] Returns 1 if the poisson random trigger is within the injection veto window.

Tip

Please see the Trigger Bits section for further details.

HighLevelTrigger

[Eventbased] True if event passes the HLT trigger, false if not

SoftwareTriggerPrescaling(triggerIdentifier)

[Eventbased] return the prescaling for the specific software trigger identifier. Please note, this prescaling is taken from the currently setup database. It only corresponds to the correct HLT prescale if you are using the online database!If the trigger identifier is not found, returns NaN.

SoftwareTriggerResult(triggerIdentifier)

[Eventbased] [Expert] returns the SoftwareTriggerCutResult, defined as reject (-1), accept (1), or noResult (0). If the trigger identifier is not found, returns NaN.

For example:

SoftwareTriggerResult(filter 1_Estargt1_GeV_cluster_no_other_cluster_Estargt0.3_GeV)

which is equivalent to

SoftwareTriggerResult(software_trigger_cut&filter&1_Estargt1_GeV_cluster_no_other_cluster_Estargt0.3_GeV)

Warning

the meanings of these change depending if using trigger or the skim stage, hence expert.

See also

b2hlt_triggers for possible triggerIdentifiers.

SoftwareTriggerResultNonPrescaled(triggerIdentifier)

[Eventbased] [Expert] returns the SoftwareTriggerCutResult, if this trigger would not be prescaled.Please note, this is not the final HLT decision! It is defined as reject (-1), accept (1), or noResult (0). Note that the meanings of these change depending if using trigger or the skim stage, hence expert.If the trigger identifier is not found, returns NaN.

Event

Here is a list of event variables:

Ecms

[Eventbased] Returns center-of-mass energy.

Unit:

GeV

EcmsMC

[Eventbased] Truth value of sqrt(s)

Unit:

GeV

IPCov(i, j)

[Eventbased] Returns (i,j)-th element of the covariance matrix of the measured interaction point.

Unit:

\(\text{cm}^2\)

IPX

[Eventbased] Returns x coordinate of the measured interaction point.

Note

For old data and uncalibrated MC files this will return 0.0.

Note

You might hear tracking and calibration people refer to this as the BeamSpot.

Unit:

cm

IPY

[Eventbased] Returns y coordinate of the measured interaction point.

Unit:

cm

IPZ

[Eventbased] Returns z coordinate of the measured interaction point.

Unit:

cm

PxHER

[Eventbased] Returns truth value of the x component of the incoming electron momentum in the laboratory frame.

Unit:

GeV/c

PxLER

[Eventbased] Returns truth value of the x component of the incoming positron momentum in the laboratory frame.

Unit:

GeV/c

PyHER

[Eventbased] Returns truth value of the y component of the incoming electron momentum in the laboratory frame.

Unit:

GeV/c

PyLER

[Eventbased] Returns truth value of the y component of the incoming positron momentum in the laboratory frame.

Unit:

GeV/c

PzHER

[Eventbased] Returns truth value of the z component of the incoming electron momentum in the laboratory frame.

Unit:

GeV/c

PzLER

[Eventbased] Returns truth value of the z component of the incoming positron momentum in the laboratory frame.

Unit:

GeV/c

beamE

[Eventbased] Returns total beam energy in the laboratory frame.

Unit:

GeV

beamPx

[Eventbased] Returns x component of total beam momentum in the laboratory frame.

Unit:

GeV/c

beamPy

[Eventbased] Returns y component of total beam momentum in the laboratory frame.

Unit:

GeV/c

beamPz

[Eventbased] Returns z component of total beam momentum in the laboratory frame.

Unit:

GeV/c

belleECLEnergy

[Eventbased][Legacy] Returns total energy in ECL in the event as used in Belle 1 analyses.

Warning

For Belle II use cases use either totalEnergyOfParticlesInList(gamma:all), or (probably better) fill a photon list with some minimal cleanup cuts and use that instead:

from variables import variables as vm
fillParticleList("gamma:cleaned", "E > 0.05 and isFromECL==1", path=path)
fillParticleList("e+:cleaned", "clusterE > 0.05", path=path)
vm.addAlias("myNeutralECLEnergy", "totalEnergyOfParticlesInList(gamma:cleaned)")
vm.addAlias("myChargedECLEnergy", "totalEnergyOfParticlesInList(e+:cleaned)")
vm.addAlias("myECLEnergy", "formula(myNeutralECLEnergy+myChargedECLEnergy)")

Unit:

GeV

date

[Eventbased] Returns the date when the event was recorded, a number of the form YYYYMMDD (in UTC).

See also

year, eventTimeSeconds, eventTimeSecondsFractionRemainder, provided for convenience.

eventTimeSeconds

[Eventbased] Time of the event (truncated down) since 1970/1/1 (Unix epoch).

Unit:

s

eventTimeSecondsFractionRemainder

[Eventbased] Remainder of the event time.

Tip

Use eventTimeSeconds + eventTimeSecondsFractionRemainder to get the total event time in seconds.

Unit:

s

evtNum

[Eventbased] Returns the event number.

expNum

[Eventbased] Returns the experiment number.

genIPX

[Eventbased] Returns x coordinate of the interaction point used for the underlying MC generation. Returns NaN for data.

Note

This is normally smeared from 0.0

Unit:

cm

genIPY

[Eventbased] Returns y coordinate of the interaction point used for the underlying MC generation. Returns NaN for data.

Unit:

cm

genIPZ

[Eventbased] Returns z coordinate of the interaction point used for the underlying MC generation. Returns NaN for data.

Unit:

cm

hasRecentInjection

[Eventbased] Returns 1 if an injection happened recently, 0 otherwise.

injectionInHER

[Eventbased] Returns 1 if injection was in HER, 0 otherwise.

isChargedBEvent

[Eventbased] Returns 1.0 if event contains a charged B-meson on generator level.

isContinuumEvent

[Eventbased] Returns 1.0 if event doesn’t contain a \(\Upsilon(4S)\) particle on generator level, 0.0 otherwise.

isMC

[Eventbased] Returns 1 if current basf2 process is running over simulated (Monte-Carlo) dataset and 0 in case of real experimental data.

isNotContinuumEvent

[Eventbased] Returns 1.0 if event does contain an \(\Upsilon(4S)\) particle on generator level and therefore is not a continuum event, 0.0 otherwise.

isUnmixedBEvent

[Eventbased] Returns 1.0 if the event contains opposite flavor neutral B-mesons on generator level, 0.0 in case of same flavor B-mesons and NaN if the event has no generated neutral B.

mcPxHER

[Eventbased] Returns x component of the electron beam momentum in the laboratory frame.

Unit:

GeV/c

mcPxLER

[Eventbased] Returns x component of the positron beam momentum in the laboratory frame.

Unit:

GeV/c

mcPyHER

[Eventbased] Returns y component of the electron beam momentum in the laboratory frame.

Unit:

GeV/c

mcPyLER

[Eventbased] Returns y component of the positron beam momentum in the laboratory frame.

Unit:

GeV/c

mcPzHER

[Eventbased] Returns z component of the electron beam momentum in the laboratory frame.

Unit:

GeV/c

mcPzLER

[Eventbased] Returns z component of the positron beam momentum in the laboratory frame.

Unit:

GeV/c

nChargeZeroTrackFits

[Eventbased] Returns number of track fits with zero charge.

Note

Sometimes, track fits can have zero charge, if background or non IP originating tracks, for example, are fit from the IP. These tracks are excluded from particle lists, but a large amount of charge zero fits may indicate problems with whole event constraints or abnominally high beam backgrounds and/or noisy events.

nInitialPrimaryMCParticles

[Eventbased] Returns number of initial primary MCParticles in the event.

nKLMClusters

[Eventbased] Returns number of KLM clusters in the event.

nMCParticles

[Eventbased] Returns number of MCParticles in the event.

nNeutralECLClusters(hypothesis)

[Eventbased] Returns number of neutral ECL clusters with a given hypothesis, 1:nPhotons, 2:NeutralHadron.

nPrimaryMCParticles

[Eventbased] Returns number of primary MCParticles in the event.

nTracks

[Eventbased] Returns the total number of tracks (unfiltered) in the event.

Warning

This variable is exceedingly background-dependent and should not really be used in any selections (other than perhaps for monitoring purposes).

See also

nCleanedTracks for a more useful variable for use in selections.

nV0s

[Eventbased] Returns number of V0s in the event.

nValidV0s

[Eventbased] Returns number of V0s consisting of pair of tracks with opposite charges.

nVirtualPrimaryMCParticles

[Eventbased] Returns number of virtual primary MCParticles in the event.

productionIdentifier

[Eventbased] Production identifier. Uniquely identifies an MC sample by the (grid-jargon) production ID. This is useful when analysing large MC samples split between more than one production or combining different MC samples (e.g. combining all continuum samples). In such cases the event numbers are sequential only within a production, so experiment/run/event will restart with every new sample analysed.

Tip

Experiment/run/event/production is unique for all MC samples. Experiment/run/event is unique for data.

See also

Where can I rely on uniqueness of the [‘__experiment__’, ‘__run__’, ‘__event__’, ‘__candidate__’] combination?

revolutionCounter2

[Eventbased] The lowest bit of revolution counter, i.e. return 0 or 1

Note

related to PXD data acquisition; PXD needs ~2 revolutions to read out one frame

runNum

[Eventbased] Returns the run number.

timeSinceLastInjectionClockTicks

[Eventbased] Time since the last injected bunch passed by the detector.

Unit:

clock ticks

timeSinceLastInjectionMicroSeconds

[Eventbased] Time since the last injected bunch passed by the detector.

Unit:

\(\mathrm{\mu s}\)

timeSinceLastInjectionSignalClockTicks

[Eventbased] Time since the last injection pre-kick signal (127MHz=RF/4 clock)

Warning

this returns the time without the delay until the injected bunch reaches the detector (which differs for HER/LER)

Unit:

clock ticks

timeSinceLastInjectionSignalMicroSeconds

[Eventbased] Time since the last injection pre-kick signal

Warning

this returns the time without the delay until the injected bunch reaches the detector (which differs for HER/LER)

Unit:

\(\mathrm{\mu s}\)

timeSincePrevTriggerClockTicks

[Eventbased] Time since the previous trigger (127MHz=RF/4 clock).

Unit:

clock ticks

timeSincePrevTriggerMicroSeconds

[Eventbased] Time since the previous trigger.

Unit:

\(\mathrm{\mu s}\)

totalEnergyMC

[Eventbased] Truth value of sum of energies of all the generated particles

Unit:

GeV

triggeredBunchNumber

[Eventbased] Number of triggered bunch ranging from 0-1279.

Note

There are a maximum of 5120 buckets, which could each carry one bunch of e+/e-, but we only have 1280 clock ticks (=5120/4) to identify the bunches

triggeredBunchNumberTTD

[Eventbased] Number of triggered bunch ranging from 0-1279.

Warning

This is the bunch number as provided by the TTD, which does not necessarily correspond to the ‘global’ SKB bunch number.

Note

There are a maximum of 5120 buckets, which could each carry one bunch of e+/e-, but we only have 1280 clock ticks (=5120/4) to identify the bunches.

year

[Eventbased] Returns the year when the event was recorded (in UTC).

Tip

For more precise event time, see eventTimeSeconds and eventTimeSecondsFractionRemainder.

Parameter Functions

Here is a list of variables that require a parameter:

NumberOfMCParticlesInEvent(pdgcode)

[Eventbased] Returns number of MC Particles (including anti-particles) with the given pdgcode in the event.

Used in the FEI to determine to calculate reconstruction efficiencies.

The variable is event-based and does not need a valid particle pointer as input.

azimuthalAngleInDecayPlane(i, j)

Azimuthal angle of i-th daughter in decay plane towards projection of particle momentum into decay plane.

First we define the following symbols:

• P: four-momentum vector of decaying particle in whose decay plane the azimuthal angle is measured

• M: “mother” of p, however not necessarily the direct mother but any higher state, here the CMS itself is chosen

• D1: daughter for which the azimuthal angle is supposed to be calculated

• D2: another daughter needed to span the decay plane

• L: normal to the decay plane (four-component vector)

L can be defined via the following relation:

\[L^{\sigma} = \delta^{\sigma\nu} \epsilon_{\mu\nu\alpha\beta} P^{\mu}D1^{\alpha}D2^{\beta}\]

The azimuthal angle is given by

\[\phi \equiv \cos^{-1} \left(\frac{-\vec{M_{\parallel}} \cdot \vec{D1}}{|\vec{M_{\parallel}}| \cdot |\vec{D1}|}\right)\]

For a frame independent formulation the three component vectors need to be written via invariant four-momentum vectors.

\[\begin{split}-\vec{M_{\parallel}} \cdot \vec{D1} &= \biggl[M - \frac{(M \cdot L)L}{L^2}\biggr] \cdot D1 - \frac{(M \cdot P)(D1 \cdot P)}{m^2_P}\\ |\vec{M_{\parallel}}| &= |\vec{M}| \sqrt{1 - \cos^2 \psi}\\ |\vec{M}| &= \sqrt{\frac{(M \cdot P)^2}{m^2_P} - m^2_M}\\ \cos \psi &= \frac{\vec{M} \cdot \vec{L}}{|\vec{M}| \cdot |\vec{L}|} = \frac{-M \cdot L}{|\vec{M}| \cdot \sqrt{-L^2}}\\ |\vec{D1}| &= \sqrt{\frac{(D1 \cdot P)^2}{m^2_P} - m^2_{D1}}\end{split}\]

Unit:

rad

constant(float i)

Returns i.

Useful for debugging purposes and in conjunction with the formula meta-variable.

daughterInvariantMass(i, j, ...)

Returns invariant mass of the given daughter particles. E.g.:

• daughterInvariantMass(0, 1) returns the invariant mass of the first and second daughter.

• daughterInvariantMass(0, 1, 2) returns the invariant mass of the first, second and third daughter.

Useful to identify intermediate resonances in a decay, which weren’t reconstructed explicitly.

Returns NaN if particle is nullptr or if the given daughter-index is out of bound (>= number of daughters).

Unit:

GeV/\(\text{c}^2\)

Note

Deprecated since version light-2203-zeus.

The variable daughterInvM provides exactly the same functionality.

daughterMCInvariantMass(i, j, ...)

Returns true invariant mass of the given daughter particles, same behaviour as daughterInvariantMass variable.

Unit:

GeV/\(\text{c}^2\)

decayAngle(i)

Angle in the mother’s rest frame between the reverted CMS momentum vector and the direction of the i-th daughter

Unit:

rad

hasAncestor(PDG, abs)

Returns a positive integer if an ancestor with the given PDG code is found, 0 otherwise.

The integer is the level where the ancestor was found, 1: first mother, 2: grandmother, etc.

Second argument is optional, 1 means that the sign of the PDG code is taken into account, default is 0.

If there is no MC relations found, -1 is returned. In case of nullptr particle, NaN is returned.

isAncestorOf(i, j, ...)

Returns a positive integer if daughter at position particle->daughter(i)->daughter(j)… is an ancestor of the related MC particle, 0 otherwise.

Positive integer represents the number of steps needed to get from final MC daughter to ancestor. If any particle or MCparticle is a nullptr, NaN is returned. If MC relations of any particle doesn’t exist, -1.0 is returned.

massDifference(i)

Difference in invariant masses of this particle and its i-th daughter

Unit:

GeV/\(\text{c}^2\)

massDifferenceError(i)

Estimated uncertainty on difference in invariant masses of this particle and its i-th daughter

Unit:

GeV/\(\text{c}^2\)

massDifferenceSignificance(i)

Signed significance of the deviation from the nominal mass difference of this particle and its i-th daughter [(massDiff - NOMINAL_MASS_DIFF)/ErrMassDiff]

pointingAngle(i)

Angle between i-th daughter’s momentum vector and vector connecting production and decay vertex of i-th daughter. This makes only sense if the i-th daughter has itself daughter particles and therefore a properly defined vertex.

Unit:

rad

randomChoice(i, j, ...)

Returns random element of given numbers.

Useful for testing purposes.

Meta Functions

Here is a list of variables that returns extra info of a given particle:

abs(variable)

Returns absolute value of the given variable. E.g. abs(mcPDG) returns the absolute value of the mcPDG, which is often useful for cuts.

acos(variable)

Returns arccosine value of the given variable. The unit of the acos() is rad

angleToClosestInList(particleListName)

Returns the angle between this particle and the closest particle (smallest opening angle) in the list provided. The unit of the angle is rad

angleToMostB2BInList(particleListName)

Returns the angle between this particle and the most back-to-back particle (closest opening angle to 180) in the list provided. The unit of the angle is rad

asin(variable)

Returns arcsine of the given variable. The unit of the asin() is rad

atan(variable)

Returns arctangent value of the given variable. The unit of the atan() is rad

averageValueInList(particleListName, variable)

[Eventbased] Returns the arithmetic mean of the given variable of the particles in the given particle list.

closestInList(particleListName, variable)

Returns variable for the closest particle (smallest opening angle) in the list provided.

clusterBestMatchedMCParticle(variable)

Returns variable output for the MCParticle that is best-matched with the ECLCluster of the given Particle. E.g. To get the energy of the MCParticle that matches best with an ECLCluster, one could use clusterBestMatchedMCParticle(E) When the variable is called for gamma and if the gamma is matched with MCParticle, it works same as matchedMC. If the variable is called for gamma that fails to match with an MCParticle, it provides the mdst-level MCMatching information abouth the ECLCluster. Returns NaN if the particle is not matched to an ECLCluster, or if the ECLCluster has no matching MCParticles

conditionalVariableSelector(cut, variableIfTrue, variableIfFalse)

Returns one of the two supplied variables, depending on whether the particle passes the supplied cut. The first variable is returned if the particle passes the cut, and the second variable is returned otherwise.

cos(variable)

Returns cosine value of the given variable.

countDaughters(cut)

Returns number of direct daughters which satisfy the cut. Used by the skimming package (for what exactly?)

countDescendants(cut)

Returns number of descendants for all generations which satisfy the cut.

countFSPDaughters(cut)

Returns number of final-state daughters which satisfy the cut.

countInList(particleList, cut='')

[Eventbased] Returns number of particle which pass given in cut in the specified particle list. Useful for creating statistics about the number of particles in a list. E.g. countInList(e+, isSignal == 1) returns the number of correctly reconstructed electrons in the event. The variable is event-based and does not need a valid particle pointer as input.

daughter(i, variable)

Returns value of variable for the i-th daughter. E.g.

• daughter(0, p) returns the total momentum of the first daughter.

• daughter(0, daughter(1, p) returns the total momentum of the second daughter of the first daughter.

Returns NaN if particle is nullptr or if the given daughter-index is out of bound (>= amount of daughters).

daughterAngle(daughterIndex_1, daughterIndex_2[, daughterIndex_3])

Returns the angle in between any pair of particles belonging to the same decay tree. The unit of the angle is rad.

The particles are identified via generalized daughter indexes, which are simply colon-separated lists of daughter indexes, ordered starting from the root particle. For example, 0:1:3 identifies the fourth daughter (3) of the second daughter (1) of the first daughter (0) of the mother particle. 1 simply identifies the second daughter of the root particle.

Both two and three generalized indexes can be given to daughterAngle. If two indices are given, the variable returns the angle between the momenta of the two given particles. If three indices are given, the variable returns the angle between the momentum of the third particle and a vector which is the sum of the first two daughter momenta.

Tip

daughterAngle(0, 3) will return the angle between the first and fourth daughter. daughterAngle(0, 1, 3) will return the angle between the fourth daughter and the sum of the first and second daughter. daughterAngle(0:0, 3:0) will return the angle between the first daughter of the first daughter, and the first daughter of the fourth daughter.

daughterClusterAngleInBetween(i, j)

Returns the angle between clusters associated to the two daughters.If two indices given: returns the angle between the momenta of the clusters associated to the two given daughters.If three indices given: returns the angle between the momentum of the third particle’s cluster and a vector which is the sum of the first two daughter’s cluster momenta.Returns nan if any of the daughters specified don’t have an associated cluster.The arguments in the argument vector must be integers corresponding to the ith and jth (and kth) daughters.

Unit:

rad

daughterCombination(variable, daughterIndex_1, daughterIndex_2 ... daughterIndex_n)

Returns a variable function only of the 4-momentum calculated on an arbitrary set of (grand)daughters.

Warning

variable can only be a function of the daughters’ 4-momenta.

Daughters from different generations of the decay tree can be combined using generalized daughter indexes, which are simply colon-separated the list of daughter indexes, starting from the root particle: for example, 0:1:3 identifies the fourth daughter (3) of the second daughter (1) of the first daughter (0) of the mother particle.

Tip

daughterCombination(M, 0, 3, 4) will return the invariant mass of the system made of the first, fourth and fifth daughter of particle. daughterCombination(M, 0:0, 3:0) will return the invariant mass of the system made of the first daughter of the first daughter and the first daughter of the fourth daughter.

daughterDiffOf(daughterIndex_i, daughterIndex_j, variable)

Returns the difference of a variable between the two given daughters. E.g. useRestFrame(daughterDiffOf(0, 1, p)) returns the momentum difference between first and second daughter in the rest frame of the given particle. (That means that it returns \(p_j - p_i\))

The daughters can be provided as generalized daughter indexes, which are simply colon-separated lists of daughter indexes, ordered starting from the root particle. For example, 0:1 identifies the second daughter (1) of the first daughter (0) of the mother particle.

daughterDiffOfClusterPhi(i, j)

Returns the difference in \(\phi\) between the ECLClusters of two given daughters. The unit of the angle is rad. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\). The function returns NaN if at least one of the daughters is not matched to or not based on an ECLCluster.

Note

Deprecated since version release-06-00-00.

The difference of the azimuthal angle \(\\phi\) of the related ECL clusters of two daughters can be calculated with the generic variable daughterDiffOf.

daughterDiffOfClusterPhiCMS(i, j)

Returns the difference in \(\phi\) between the ECLClusters of two given daughters in the CMS frame. The unit of the angle is rad. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i`\). The function returns NaN if at least one of the daughters is not matched to or not based on an ECLCluster.

Note

Deprecated since version release-06-00-00.

The difference of the azimuthal angle \(\\phi\) of the related ECL clusters of two daughters in the CMS frame can be calculated with the generic variable daughterDiffOf.

daughterDiffOfPhi(i, j)

Returns the difference in \(\phi\) between the two given daughters. The unit of the angle is rad. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\).

Note

Deprecated since version release-06-00-00.

The difference of the azimuthal angle \(\\phi\) of two daughters can be calculated with the generic variable daughterDiffOf.

daughterDiffOfPhiCMS(i, j)

Returns the difference in \(\phi\) between the two given daughters in the CMS frame. The unit of the angle is rad. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\).

Note

Deprecated since version release-06-00-00.

The difference of the azimuthal angle \(\\phi\) of two daughters in the CMS frame can be calculated with the generic variable daughterDiffOf.

daughterHighest(variable)

Returns the highest value of the given variable among all daughters. E.g. useCMSFrame(daughterHighest(p)) returns the highest momentum in CMS frame.

daughterInvM(i[, j, ...])

Returns the invariant mass adding the Lorentz vectors of the given daughters. The unit of the invariant mass is GeV/\(\text{c}^2\) E.g. daughterInvM(0, 1, 2) returns the invariant Mass \(m = \sqrt{(p_0 + p_1 + p_2)^2}\) of the first, second and third daughter.

Daughters from different generations of the decay tree can be combined using generalized daughter indexes, which are simply colon-separated daughter indexes for each generation, starting from the root particle. For example, 0:1:3 identifies the fourth daughter (3) of the second daughter (1) of the first daughter(0) of the mother particle.

Returns NaN if the given daughter-index is out of bound (>= number of daughters)

daughterLowest(variable)

Returns the lowest value of the given variable among all daughters. E.g. useCMSFrame(daughterLowest(p)) returns the lowest momentum in CMS frame.

daughterMotherDiffOf(i, variable)

Returns the difference of a variable between the given daughter and the mother particle itself. E.g. useRestFrame(daughterMotherDiffOf(0, p)) returns the momentum difference between the given particle and its first daughter in the rest frame of the mother.

daughterMotherNormDiffOf(i, variable)

Returns the normalized difference of a variable between the given daughter and the mother particle itself. E.g. daughterMotherNormDiffOf(1, p) returns the normalized momentum difference between the given particle and its second daughter in the lab frame.

daughterNormDiffOf(i, j, variable)

Returns the normalized difference of a variable between the two given daughters. E.g. daughterNormDiffOf(0, 1, p) returns the normalized momentum difference between first and second daughter in the lab frame.

daughterProductOf(variable)

Returns product of a variable over all daughters. E.g. daughterProductOf(extraInfo(SignalProbability)) returns the product of the SignalProbabilitys of all daughters.

daughterSumOf(variable)

Returns sum of a variable over all daughters. E.g. daughterSumOf(nDaughters) returns the number of grand-daughters.

deltaPhiToMostB2BPhiInList(particleListName)

Returns the abs(delta phi) between this particle and the most back-to-back particle in phi (closest opening angle to 180) in the list provided. The unit of the angle is rad

eclClusterSpecialTrackMatched(cut)

Returns if at least one Track that satisfies the given condition is related to the ECLCluster of the Particle.

eventCached(variable)

[Eventbased] Returns value of event-based variable and caches this value in the EventExtraInfo. The result of second call to this variable in the same event will be provided from the cache. It is recommended to use this variable in order to declare custom aliases as event-based. This is necessary if using the eventwise mode of variablesToNtuple).

eventExtraInfo(name)

[Eventbased] Returns extra info stored under the given name in the event extra info. The extraInfo has to be set first by another module like MVAExpert in event mode. If nothing is set under this name, NaN is returned.

exp(variable)

Returns exponential evaluated for the given variable.

extraInfo(name)

Returns extra info stored under the given name. The extraInfo has to be set by a module first. E.g. extraInfo(SignalProbability) returns the SignalProbability calculated by the MVAExpert module. If nothing is set under the given name or if the particle is a nullptr, NaN is returned. In the latter case please use eventExtraInfo if you want to access an EventExtraInfo variable.

formula(v1 + v2 * [v3 - v4] / v5^v6)

Returns the result of the given formula, where v1 to vN are variables or floating point numbers. Currently the only supported operations are addition (+), subtraction (-), multiplication (*), division (/) and power (^ or **). Parenthesis can be in the form of square brackets [v1 * v2] or normal brackets (v1 * v2). It will work also with variables taking arguments. Operator precedence is taken into account. For example

(daughter(0, E) + daughter(1, E))**2 - p**2 + 0.138

Changed in version release-03-00-00: now both, [] and () can be used for grouping operations, ** can be used for exponent and float literals are possible directly in the formula.

genParticle(index, variable)

[Eventbased] Returns the variable for the ith generator particle. The arguments of the function must be the index of the particle in the MCParticle Array, and variable, the name of the function or variable for that generator particle. If index goes beyond the length of the MCParticles array, NaN will be returned.

E.g. genParticle(0, p) returns the total momentum of the first MCParticle, which in a generic decay up to MC15 is the Upsilon(4S) and for MC16 and beyond the initial electron.

genUpsilon4S(variable)

[Eventbased] Returns the variable evaluated for the generator-level \(\Upsilon(4S)\). If no generator level \(\Upsilon(4S)\) exists for the event, NaN will be returned.

E.g. genUpsilon4S(p) returns the total momentum of the \(\Upsilon(4S)\) in a generic decay. genUpsilon4S(mcDaughter(1, p)) returns the total momentum of the second daughter of the generator-level \(\Upsilon(4S)\) (i.e. the momentum of the second B meson in a generic decay).

getVariableByRank(particleList, rankedVariableName, variableName, rank)

[Eventbased] Returns the value of variableName for the candidate in the particleList with the requested rank.

Note

The BestCandidateSelection module available via rankByHighest / rankByLowest has to be used before.

Warning

The first candidate matching the given rank is used. Thus, it is not recommended to use this variable in conjunction with allowMultiRank in the BestCandidateSelection module.

The suffix _rank is automatically added to the argument rankedVariableName, which either has to be the name of the variable used to order the candidates or the selected outputVariable name without the ending _rank. This means that your selected name for the rank variable has to end with _rank.

An example of this variable’s usage is given in the tutorial B2A602-BestCandidateSelection

grandDaughterDecayAngle(i, j)

Returns the decay angle of the granddaughter in the daughter particle’s rest frame. It is calculated with respect to the reverted momentum vector of the particle. Two arguments representing the daughter and granddaughter indices have to be provided as arguments.

Unit:

rad

grandDaughterDiffOf(i, j, variable)

Returns the difference of a variable between the first daughters of the two given daughters. E.g. useRestFrame(grandDaughterDiffOf(0, 1, p)) returns the momentum difference between the first daughters of the first and second daughter in the rest frame of the given particle. (That means that it returns \(p_j - p_i\))

Note

Deprecated since version light-2402-ocicat.

The difference between any combination of (grand-)daughters can be calculated with the more general variable daughterDiffOf by using generalized daughter indexes.

grandDaughterDiffOfClusterPhi(i, j)

Returns the difference in \(\phi\) between the ECLClusters of the daughters of the two given daughters. The unit of the angle is rad. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\). The function returns NaN if at least one of the daughters is not matched to or not based on an ECLCluster.

Note

Deprecated since version release-06-00-00.

The difference of the azimuthal angle \(\\phi\) of the related ECL clusters of two granddaughters can be calculated with the generic variable grandDaughterDiffOf.

grandDaughterDiffOfPhi(i, j)

Returns the difference in \(\phi\) between the first daughters of the two given daughters. The unit of the angle is rad. The difference is signed and takes account of the ordering of the given daughters. The function returns \(\phi_j - \phi_i\).

Note

Deprecated since version release-06-00-00.

The difference of the azimuthal angle \(\\phi\) of two granddaughters can be calculated with the generic variable grandDaughterDiffOf.

ifNANgiveX(variable, x)

Returns x (has to be a number) if variable value is nan (determined via std::isnan(double)). Useful for technical purposes while training MVAs.

invMassInLists(pList1, pList2, ...)

[Eventbased] Returns the invariant mass of the combination of particles in the given particle lists. The unit of the invariant mass is GeV/\(\text{c}^2\)

isDaughterOfList(particleListNames)

Returns 1 if the given particle is a daughter of at least one of the particles in the given particle Lists.

isDescendantOfList(particleListName[, anotherParticleListName][, generationFlag = -1])

Returns 1 if the given particle appears in the decay chain of the particles in the given ParticleLists.

Passing an integer as the last argument, allows to check if the particle belongs to the specific generation:

• isDescendantOfList(<particle_list>,1) returns 1 if particle is a daughter of the list,

• isDescendantOfList(<particle_list>,2) returns 1 if particle is a granddaughter of the list,

• isDescendantOfList(<particle_list>,3) returns 1 if particle is a great-granddaughter of the list, etc.

• Default value is -1 that is inclusive for all generations.

isGrandDaughterOfList(particleListNames)

Returns 1 if the given particle is a grand daughter of at least one of the particles in the given particle Lists.

isInList(particleListName)

Returns 1 if the particle is in the list provided, 0 if not. Note that this only checks the particle given. For daughters of composite particles, please see isDaughterOfList.

isInfinity(variable)

Returns true if variable value evaluates to infinity (determined via std::isinf(double)). Useful for debugging.

isMCDescendantOfList(particleListName[, anotherParticleListName][, generationFlag = -1])

Returns 1 if the given particle is linked to the same MC particle as any reconstructed daughter of the decay lists.

Passing an integer as the last argument, allows to check if the particle belongs to the specific generation:

• isMCDescendantOfList(<particle_list>,1) returns 1 if particle is matched to the same particle as any daughter of the list,

• isMCDescendantOfList(<particle_list>,2) returns 1 if particle is matched to the same particle as any granddaughter of the list,

• isMCDescendantOfList(<particle_list>,3) returns 1 if particle is matched to the same particle as any great-granddaughter of the list, etc.

• Default value is -1 that is inclusive for all generations.

It makes only sense for lists created with fillParticleListFromMC function with addDaughters=True argument.

isNAN(variable)

Returns true if variable value evaluates to nan (determined via std::isnan(double)). Useful for debugging.

log(variable)

Returns natural logarithm evaluated for the given variable.

log10(variable)

Returns base-10 logarithm evaluated for the given variable.

matchedMC(variable)

Returns variable output for the matched MCParticle by constructing a temporary Particle from it. This may not work too well if your variable requires accessing daughters of the particle. E.g. matchedMC(p) returns the total momentum of the related MCParticle. Returns NaN if no matched MCParticle exists.

matchedMCHasPDG(PDGCode)

Returns if the absolute value of the PDGCode of the MCParticle related to the Particle matches a given PDGCode.Returns 0/NAN/1 if PDGCode does not match/is not available/ matches

max(var1, var2)

Returns max value of two variables.

maxOpeningAngleInList(particleListName)

[Eventbased] Returns maximum opening angle in the given particle List. The unit of the angle is rad

maxPtInList(particleListName)

[Eventbased] Returns maximum transverse momentum Pt in the given particle List. The unit of the transverse momentum is GeV/c

mcDaughter(i, variable)

Returns the value of the requested variable for the i-th Monte Carlo daughter of the particle.

Returns NaN if the particle is nullptr, if the particle is not matched to an MC particle, or if the i-th MC daughter does not exist.

E.g. mcDaughter(0, PDG) will return the PDG code of the first MC daughter of the matched MC particle of the reconstructed particle the function is applied to.

The meta variable can also be nested: mcDaughter(0, mcDaughter(1, PDG)).

mcDaughterAngle(daughterIndex_1, daughterIndex_2, [daughterIndex_3])

MC matched version of the daughterAngle function. Also works if applied directly to MC particles. The unit of the angle is rad

mcDaughterDiffOf(i, j, variable)

MC matched version of the daughterDiffOf function.

mcDaughterDiffOfPhi(i, j)

MC matched version of the daughterDiffOfPhi function. The unit of the angle is rad

Note

Deprecated since version release-06-00-00.

The difference of the azimuthal angle \(\\phi\) of the MC partners of two daughters can be calculated with the generic variable mcDaughterDiffOf.

mcDaughterDiffOfPhiCMS(i, j)

MC matched version of the daughterDiffOfPhiCMS function. The unit of the angle is rad

Note

Deprecated since version release-06-00-00.

The difference of the azimuthal angle \(\\phi\) of the MC partners of two daughters in the CMS frame can be calculated with the generic variable mcDaughterDiffOf.

mcMother(variable)

Returns the value of the requested variable for the Monte Carlo mother of the particle.

Returns NaN if the particle is nullptr, if the particle is not matched to an MC particle, or if the MC mother does not exist.

E.g. mcMother(PDG) will return the PDG code of the MC mother of the matched MC particle of the reconstructed particle the function is applied to.

The meta variable can also be nested: mcMother(mcMother(PDG)).

mcParticleIsInMCList(particleListName)

Returns 1 if the particle’s matched MC particle is also matched to a particle in particleListName (or if either of the lists were filled from generator level modularAnalysis.fillParticleListFromMC.)

See also

isMCDescendantOfList to check daughters.

medianValueInList(particleListName, variable)

[Eventbased] Returns the median value of the given variable of the particles in the given particle list.

min(var1, var2)

Returns min value of two variables.

modulo(variable, n)

Returns rest of division of variable by n.

mostB2BInList(particleListName, variable)

Returns variable for the most back-to-back particle (closest opening angle to 180) in the list provided.

nCleanedECLClusters(cut)

[Eventbased] Returns the number of clean Clusters in the event Clean clusters are defined by the clusters which pass the given cut assuming a photon hypothesis.

nCleanedTracks(cut)

[Eventbased] Returns the number of clean Tracks in the event Clean tracks are defined by the tracks which pass the given cut assuming a pion hypothesis.

nParticlesInList(particleListName)

[Eventbased] Returns number of particles in the given particle List.

nTrackFitResults(particleType)

[Eventbased] Returns the total number of TrackFitResults for a given particleType. The argument can be the name of particle (e.g. pi+) or PDG code (e.g. 211).

numberOfNonOverlappingParticles(pList1, pList2, ...)

Returns the number of non-overlapping particles in the given particle listsUseful to check if there is additional physics going on in the detector if one reconstructed the Y4S

originalDaughter(i, variable)

Returns value of variable for the original particle from which the i-th daughter is copied.

The copy of particle is created, for example, when the vertex fit updates the daughters and modularAnalysis.copyParticles is called. Returns NaN if the daughter is not copied and so there is no original daughter.

Returns NaN if particle is nullptr or if the given daughter-index is out of bound (>= amount of daughters).

originalParticle(variable)

Returns value of variable for the original particle from which the given particle is copied.

The copy of particle is created, for example, when the vertex fit updates the daughters and modularAnalysis.copyParticles is called. Returns NaN if the given particle is not copied and so there is no original particle.

pValueCombination(p1, p2, ...)

Returns the combined p-value of the provided p-values according to the formula given in Nucl. Instr. and Meth. A 411 (1998) 449 . If any of the p-values is invalid, i.e. smaller than zero, -1 is returned.

particleCached(variable)

Returns value of given variable and caches this value in the ParticleExtraInfo of the provided particle. The result of second call to this variable on the same particle will be provided from the cache.

passesCut(cut)

Returns 1 if particle passes the cut otherwise 0. Useful if you want to write out if a particle would have passed a cut or not.

passesEventCut(cut)

[Eventbased] Returns 1 if event passes the cut otherwise 0. Useful if you want to select events passing a cut without looping into particles, such as for skimming.

productValueInList(particleListName, variable)

[Eventbased] Returns the product of the given variable of the particles in the given particle list.

sin(variable)

Returns sine value of the given variable.

sourceObjectIsInList(particleListName)

Returns 1 if the underlying mdst object (e.g. track, or cluster) was used to create a particle in particleListName, 0 if not.

Note

This only makes sense for particles that are not composite. Returns -1 for composite particles.

sumValueInList(particleListName, variable)

[Eventbased] Returns the sum of the given variable of the particles in the given particle list.

tan(variable)

Returns tangent value of the given variable.

totalECLEnergyOfParticlesInList(particleListName)

[Eventbased] Returns the total ECL energy of particles in the given particle List. The unit of the energy is GeV

totalEnergyOfParticlesInList(particleListName)

[Eventbased] Returns the total energy of particles in the given particle List. The unit of the energy is GeV

totalPxOfParticlesInList(particleListName)

[Eventbased] Returns the total momentum Px of particles in the given particle List. The unit of the momentum is GeV/c

totalPyOfParticlesInList(particleListName)

[Eventbased] Returns the total momentum Py of particles in the given particle List. The unit of the momentum is GeV/c

totalPzOfParticlesInList(particleListName)

[Eventbased] Returns the total momentum Pz of particles in the given particle List. The unit of the momentum is GeV/c

unmask(variable, flag1, flag2, ...)

unmask(variable, flag1, flag2, …) or unmask(variable, mask) sets certain bits in the variable to zero. For example, if you want to set the second, fourth and fifth bits to zero, you could call unmask(variable, 2, 8, 16) or unmask(variable, 26).

useAlternativeDaughterHypothesis(variable, daughterIndex_1:newMassHyp_1, ..., daughterIndex_n:newMassHyp_n)

Returns a variable calculated using new mass hypotheses for (some of) the particle’s daughters.

Warning

variable can only be a function of the particle 4-momentum, which is re-calculated as the sum of the daughters’ 4-momenta, and the daughters’ 4-momentum. This means that if you made a kinematic fit without updating the daughters’ momenta, the result of this variable will not reflect the effect of the kinematic fit. Also, the track fit is not performed again: the variable only re-calculates the 4-vectors using different mass assumptions. In the variable, a copy of the given particle is created with daughters’ alternative mass assumption (i.e. the original particle and daughters are not changed).

Warning

Generalized daughter indexes are not supported (yet!): this variable can be used only on first-generation daughters.

Tip

useAlternativeDaughterHypothesis(M, 0:K+, 2:pi-) will return the invariant mass of the particle assuming that the first daughter is a kaon and the third is a pion, instead of whatever was used in reconstructing the decay. useAlternativeDaughterHypothesis(mRecoil, 1:p+) will return the recoil mass of the particle assuming that the second daughter is a proton instead of whatever was used in reconstructing the decay.

useCMSFrame(variable)

Returns the value of the variable using the CMS frame as current reference frame. E.g. useCMSFrame(E) returns the energy of a particle in the CMS frame.

useDaughterRestFrame(variable, daughterIndex_1, [daughterIndex_2, ... daughterIndex_3])

Returns the value of the variable in the rest frame of the selected daughter particle. The daughter is identified via generalized daughter index, e.g. 0:1 identifies the second daughter (1) of the first daughter (0). If the daughter index is invalid, it returns NaN. If two or more indices are given, the rest frame of the sum of the daughters is used.

useLabFrame(variable)

Returns the value of variable in the lab frame.

Tip

The lab frame is the default reference frame, usually you don’t need to use this meta-variable. E.g. useLabFrame(E) returns the energy of a particle in the Lab frame, same as just E.

Specifying the lab frame is useful in some corner-cases. For example: useRestFrame(daughter(0, formula(E - useLabFrame(E)))) which is the difference of the first daughter’s energy in the rest frame of the mother (current particle) with the same daughter’s lab-frame energy.

useMCancestorBRestFrame(variable)

Returns the value of the variable in the rest frame of the ancestor B MC particle. If no B or no MC-matching is found, it returns NaN.

useParticleRestFrame(variable, particleList)

Returns the value of the variable in the rest frame of the first Particle contained in the given ParticleList. It is strongly recommended to pass a ParticleList that contains at most only one Particle in each event. When more than one Particle is present in the ParticleList, only the first Particle in the list is used for computing the rest frame and a warning is thrown. If the given ParticleList is empty in an event, it returns NaN.

useRecoilParticleRestFrame(variable, particleList)

Returns the value of the variable in the rest frame of recoil system against the first Particle contained in the given ParticleList. It is strongly recommended to pass a ParticleList that contains at most only one Particle in each event. When more than one Particle is present in the ParticleList, only the first Particle in the list is used for computing the rest frame and a warning is thrown. If the given ParticleList is empty in an event, it returns NaN.

useRestFrame(variable)

Returns the value of the variable using the rest frame of the given particle as current reference frame. E.g. useRestFrame(daughter(0, p)) returns the total momentum of the first daughter in its mother’s rest-frame

useTagSideRecoilRestFrame(variable, daughterIndexTagB)

Returns the value of the variable in the rest frame of the recoiling particle to the tag side B meson. The variable should only be applied to an Upsilon(4S) list. E.g. useTagSideRecoilRestFrame(daughter(1, daughter(1, p)), 0) applied on a Upsilon(4S) list (Upsilon(4S)->B+:tag B-:sig) returns the momentum of the second daughter of the signal B meson in the signal B meson rest frame.

varFor(pdgCode, variable)

Returns the value of the variable for the given particle if its abs(pdgCode) agrees with the given one. E.g. varFor(11, p) returns the momentum if the particle is an electron or a positron.

varForBestMatchedMCKlong(variable)

Returns variable output for the Klong MCParticle which has the best match with the ECLCluster of the given Particle. Returns NaN if the particle is not matched to an ECLCluster, or if the ECLCluster has no matching Klong MCParticle

varForFirstMCAncestorOfType(type, variable)

Returns requested variable of the first ancestor of the given type. Ancestor type can be set up by PDG code or by particle name (check evt.pdl for valid particle names)

varForMCGen(variable)

Returns the value of the variable for the given particle if the MC particle related to it is primary, not virtual, and not initial. If no MC particle is related to the given particle, or the MC particle is not primary, virtual, or initial, NaN will be returned. E.g. varForMCGen(PDG) returns the PDG code of the MC particle related to the given particle if it is primary, not virtual, and not initial.

veto(particleList, cut, pdgCode = 11)

Combines current particle with particles from the given particle list and returns 1 if the combination passes the provided cut. For instance one can apply this function on a signal Photon and provide a list of all photons in the rest of event and a cut around the neutral Pion mass (e.g. 0.130 < M < 0.140). If a combination of the signal Photon with a ROE photon fits this criteria, hence looks like a neutral pion, the veto-Metavariable will return 1

MC matching and MC truth

Here is a list of MC truth-related variables. For some variables, you will need to run truth matching in order to get sensible results.

from modularAnalysis import matchMCTruth
matchMCTruth("B0:myCandidates")  # for example

Variables will also work on generator-level particles:

from modularAnalysis import fillParticleListFromMC
fillParticleListFromMC("B0:generator", "") # the generator-level B particles

Eher

[Eventbased] The nominal HER energy used by the generator.

Warning

This variable does not make sense for data.

Unit:

GeV

Eler

[Eventbased] The nominal LER energy used by the generator.

Warning

This variable does not make sense for data.

Unit:

GeV

XAngle

[Eventbased] The nominal beam crossing angle in the x-z plane from generator level beam kinematics.

Warning

This variable does not make sense for data.

Unit:

rad

YAngle

[Eventbased] The nominal beam crossing angle in the y-z plane from generator level beam kinematics.

Warning

This variable does not make sense for data.

Unit:

rad

ancestorBIndex

Returns array index of B ancestor, or -1 if no B or no MC-matching is found.

genMotherID

Check the array index of a particles generated mother

genMotherID(i)

Check the array index of a particle n-th MC mother particle by providing an argument. 0 is first mother, 1 is grandmother etc.

genMotherP

Generated momentum of a particles MC mother particle

Unit:

GeV/c

genMotherPDG

Check the PDG code of a particles MC mother particle

genMotherPDG(i)

Check the PDG code of a particles n-th MC mother particle by providing an argument. 0 is first mother, 1 is grandmother etc.

genNMissingDaughter(PDG)

Returns the number of missing daughters having assigned PDG codes. NaN if no MCParticle is associated to the particle.

genNStepsToDaughter(i)

Returns number of steps to i-th daughter from the particle at generator level. NaN if no MCParticle is associated to the particle or i-th daughter. NaN if i-th daughter does not exist.

genParticleID

Check the array index of a particle’s related MCParticle

genQ2PmPd(i, j, ...)

Returns the generated four momentum transfer squared \(q^2\) calculated as \(q^2 = (p_m - p_{d_i} - p_{d_j} - ...)^2\).

Here \(p_m\) is the four momentum of the given (mother) particle, and \(p_{d_{i,j,...}}\) are the daughter particles with indices given as arguments . The ordering of daughters is as defined in the DECAY.DEC file used in the generation, with the numbering starting at \(N=0\).

Returns NaN if no related MCParticle could be found. Returns NaN if any of the given indices is larger than the number of daughters of the given particle.

Unit:

\([\text{GeV}/\text{c}]^2\)

generatorEventWeight

[Eventbased] Returns the event weight produced by the event generator

isBBCrossfeed

Returns 1 for crossfeed in reconstruction of given B meson, 0 for no crossfeed and NaN for no true B meson or failed truthmatching.

isCloneTrack

Return 1 if the charged final state particle comes from a cloned track, 0 if not a clone. Returns NAN if neutral, composite, or MCParticle not found (like for data or if not MCMatched)

isMisidentified

Return 1 if the particle is misidentified: at least one of the final state particles has the wrong PDG code assignment (including wrong charge), 0 if PDG code is fine, and NaN if no related MCParticle could be found.

isOrHasCloneTrack

Return 1 if the particle is a clone track or has a clone track as a daughter, 0 otherwise.

isPrimarySignal

1.0 if Particle is correctly reconstructed (SIGNAL) and primary, 0.0 if not, and NaN if no related MCParticle could be found

isSignal

1.0 if Particle is correctly reconstructed (SIGNAL), 0.0 if not, and NaN if no related MCParticle could be found. It behaves according to DecayStringGrammar.

isSignalAcceptBremsPhotons

1.0 if Particle is correctly reconstructed (SIGNAL), 0.0 if not, and NaN if no related MCParticle could be found. Particles with gamma daughters attached through the bremsstrahlung recovery modules are allowed.

isSignalAcceptMissing

Same as isSignal, but also accept missing particle

isSignalAcceptMissingGamma

Same as isSignal, but also accept missing gamma, such as B -> K* gamma, pi0 -> gamma gamma

isSignalAcceptMissingMassive

Same as isSignal, but also accept missing massive particle

isSignalAcceptMissingNeutrino

Same as isSignal, but also accept missing neutrino

isSignalAcceptWrongFSPs

1.0 if Particle is almost correctly reconstructed (SIGNAL), 0.0 if not, and NaN if no related MCParticle could be found. Misidentification of charged FSP is allowed.

isWrongCharge

Return 1 if the charge of the particle is wrongly assigned, 0 if it’s the correct charge, and NaN if no related MCParticle could be found.

mcCosThetaBetweenParticleAndNominalB

Cosine of the angle in CMS between momentum the particle and a nominal B particle. In this calculation, the momenta of all descendant neutrinos are subtracted from the B momentum.

mcDecayTime

The decay time of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

ns

mcE

The energy of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

GeV

mcErrors

The bit pattern indicating the quality of MC match (see MCMatching::MCErrorFlags)

mcFSR

Returns 1 if Particle is related to FSR MCParticle, 0 if Particle is related to non - FSR MCParticle ,NaN if Particle is not related to MCParticle.

mcISR

Returns 1 if Particle is related to ISR MCParticle, 0 if Particle is related to non - ISR MCParticle, NaN if Particle is not related to MCParticle.

mcInitial

Returns 1 if Particle is related to initial MCParticle, 0 if Particle is related to non - initial MCParticle, NaN if Particle is not related to MCParticle.

mcLifeTime

The life time of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

ns

mcMatchWeight

The weight of the Particle -> MCParticle relation (only for the first Relation = largest weight).

mcP

The total momentum of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

GeV/c

mcPDG

The PDG code of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

mcPT

The pt of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

GeV/c

mcPX

The px of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

GeV/c

mcPY

The py of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

GeV/c

mcPZ

The pz of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

GeV/c

mcParticleStatus

Returns status bits of related MCParticle or NaN if MCParticle relation is not set.

mcPhi

The phi of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

rad

mcPhotos

Returns 1 if Particle is related to Photos MCParticle, 0 if Particle is related to non - Photos MCParticle, NaN if Particle is not related to MCParticle.

mcPrimary

Returns 1 if Particle is related to primary MCParticle, 0 if Particle is related to non - primary MCParticle, NaN if Particle is not related to MCParticle.

mcRecoilMass

The mass recoiling against the particles attached as particle’s daughters calculated using MC truth values.

Unit:

GeV/\(\text{c}^2\)

mcSecPhysProc

Returns the secondary physics process flag, which is set by Geant4 on secondary particles. It indicates the type of process that produced the particle.

Returns NaN if the particle is not matched to a MCParticle.

Returns -1 in case of unknown process.

Returns 0 if the particle is primary, i.e. produced by the event generator and not Geant4. Particles produced by Geant4 (i.e. secondary particles) include those produced in interaction with detector material, Bremsstrahlung, and the decay products of long-lived particles (e.g. muons, pions, K_S0, K_L0, Lambdas, …).

List of possible values (taken from the Geant4 source of G4DecayProcessType, G4HadronicProcessType, G4TransportationProcessType and G4EmProcessSubType)

• 1 Coulomb scattering

• 2 Ionisation

• 3 Bremsstrahlung

• 4 Pair production by charged

• 5 Annihilation

• 6 Annihilation to mu mu

• 7 Annihilation to hadrons

• 8 Nuclear stopping

• 9 Electron general process

• 10 Multiple scattering

• 11 Rayleigh

• 12 Photo-electric effect

• 13 Compton scattering

• 14 Gamma conversion

• 15 Gamma conversion to mu mu

• 16 Gamma general process

• 21 Cerenkov

• 22 Scintillation

• 23 Synchrotron radiation

• 24 Transition radiation

• 91 Transportation

• 92 Coupled transportation

• 111 Hadron elastic

• 121 Hadron inelastic

• 131 Capture

• 132 Mu atomic capture

• 141 Fission

• 151 Hadron at rest

• 152 Lepton at rest

• 161 Charge exchange

• 201 Decay

• 202 Decay with spin

• 203 Decay (pion make spin)

• 210 Radioactive decay

• 211 Unknown decay

• 221 Mu atom decay

• 231 External decay

Note

This is what modularAnalysis.printMCParticles shows as creation process when showStatus is set to True.

mcTheta

The theta of matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

Unit:

rad

mcVirtual

Returns 1 if Particle is related to virtual MCParticle, 0 if Particle is related to non - virtual MCParticle, NaN if Particle is not related to MCParticle.

nMCDaughters

The number of daughters of the matched MCParticle, NaN if no match. Requires running matchMCTruth() on the reconstructed particles, or a particle list filled with generator particles (MCParticle objects).

nMCMatches

The number of relations of this Particle to MCParticle.

isReconstructible

Checks charged particles were seen in the SVD and neutrals in the ECL, returns 1.0 if so, 0.0 if not, NaN for composite particles or if no related MCParticle could be found. Useful for generator studies, not for reconstructed particles.

isTrackFound

works on charged stable particle list created from MCParticles, returns NaN if not ; returns 1.0 if there is a reconstructed track related to the charged stable MCParticle with the correct charge, return -1.0 if the reconstructed track has the wrong charge, return 0.0 when no reconstructed track is found.

seenInARICH

Returns 1.0 if the MC particle was seen in the ARICH, 0.0 if not, NaN for composite particles or if no related MCParticle could be found. Useful for generator studies, not for reconstructed particles.

seenInCDC

Returns 1.0 if the MC particle was seen in the CDC, 0.0 if not, NaN for composite particles or if no related MCParticle could be found. Useful for generator studies, not for reconstructed particles.

seenInECL

Returns 1.0 if the MC particle was seen in the ECL, 0.0 if not, NaN for composite particles or if no related MCParticle could be found. Useful for generator studies, not for reconstructed particles.

seenInKLM

Returns 1.0 if the MC particle was seen in the KLM, 0.0 if not, NaN for composite particles or if no related MCParticle could be found. Useful for generator studies, not for reconstructed particles.

seenInPXD

Returns 1.0 if the MC particle was seen in the PXD, 0.0 if not, NaN for composite particles or if no related MCParticle could be found. Useful for generator studies, not for reconstructed particles.

seenInSVD

Returns 1.0 if the MC particle was seen in the SVD, 0.0 if not, NaN for composite particles or if no related MCParticle could be found. Useful for generator studies, not for reconstructed particles.

seenInTOP

Returns 1.0 if the MC particle was seen in the TOP, 0.0 if not, NaN for composite particles or if no related MCParticle could be found. Useful for generator studies, not for reconstructed particles.

B0Mode

[Eventbased] It will return the decays mode of B0 particles

Bbar0Mode

[Eventbased] It will return the decays mode of anti-B0 particles

BminusMode

[Eventbased] It will return the decays mode of B- particles

BplusMode

[Eventbased] It will return the decays mode of B+ particles

Bs0Mode

[Eventbased] It will return the decays mode of B_s0 particles

Bsbar0Mode

[Eventbased] It will return the decays mode of anti-B_s0 particles

D0Mode

[Eventbased] It will return the decays mode of D0 particles

Dbar0Mode

[Eventbased] It will return the decays mode of anti-D0 particles

DminusMode

[Eventbased] It will return the decays mode of D- particles

DplusMode

[Eventbased] It will return the decays mode of D+ particles

DsminusMode

[Eventbased] It will return the decays mode of D_s- particles

DsplusMode

[Eventbased] It will return the decays mode of D_s+ particles

DstminusMode

[Eventbased] It will return the decays mode of D*- particles

DstplusMode

[Eventbased] It will return the decays mode of D*+ particles

TauminusMode

[Eventbased] It will return the decays mode of tau- particles

TauplusMode

[Eventbased] It will return the decays mode of tau+ particles

tauMinusEgstar

[Eventbased] Energy of radiated gamma from negative tau lepton in a tau pair generated event.

tauMinusMCMode

[Eventbased] Decay ID for the negative tau lepton in a tau pair generated event.

tauMinusMCProng

[Eventbased] Prong for the negative tau lepton in a tau pair generated event.

tauPlusEgstar

[Eventbased] Energy of radiated gamma from positive tau lepton in a tau pair generated event.

tauPlusMCMode

[Eventbased] Decay ID for the positive tau lepton in a tau pair generated event.

tauPlusMCProng

[Eventbased] Prong for the positive tau lepton in a tau pair generated event.

Daughter info

Here is a list of variables getting info from particle’s daughters:

hasCharmedDaughter(i)

If i = 1 is provided it checks for b -> anti-c / anti-b -> c transition and for i = -1 it checks for b -> c / anti-b -> anti-c transitions. Returns 1 if at least one of the daughters on MC truth level is a charm meson. The particle’s MC partner must be a B-meson. Returns 0 if no charmed daughter found on MC truth level and NaN if no MC partner was found or the related MC particle isn’t a B-meson.

hasCharmoniumDaughter

Returns 1 if at least one of the daughters on MC truth level is a ccbar resonance. The particle’s MC partner must be a B-meson. Returns 0 if no ccbar resonance found on MC truth level and NaN if no MC partner was found or the related MC particle isn’t a B-meson.

hasRealPhotonDaughter

Returns 1 if on MC truth level there is at least one real photon daughter, a photon that was not created by photos. Returns 0 if no real photon daughter found and NaN if the particle has no daughters.

KLM Cluster and \(K_{L}^0\) Identification

Here is a list of KLM Cluster and \(K_{L}^0\) identification variables:

Warning

Please note that these variables refer to KLMClusters, which are designed to reconstruct \(K_{L}^0\) and other neutral particles with the KLM subdetector. These variables must not be used to do particle identification of charged tracks (for example, they must not be used to identify muons), otherwise there is a serious risk to spoil a physics analysis.

For particle identification of charged tracks, please use the canonical PID variables.

klmClusterBelleECLFlag

Returns the Belle-style ECL flag.

klmClusterBelleTrackFlag

Returns the Belle-style Track flag.

klmClusterEnergy

Returns the energy of the associated KLMCluster.

Warning

This variable returns an approximation of the energy: it uses klmClusterMomentum as momentum and the hypothesis that the KLMCluster is originated by a \(K_{L}^0\) (\(E_{\text{KLM}} = \sqrt{M_{K^0_L}^2 + p_{\text{KLM}}^2}\), where \(E_{\text{KLM}}\) is this variable, \(M_{K^0_L}\) is the \(K^0_L\) mass and \(p_{\text{KLM}}\) is klmClusterMomentum). It should be used with caution, and may not be physically meaningful, especially for \(n\) candidates.

Unit:

GeV

klmClusterInnermostLayer

Returns the number of the innermost KLM layer with a 2-dimensional hit of the associated KLMCluster.

klmClusterIsBKLM

Returns 1 if the associated KLMCluster is in barrel KLM.

klmClusterIsBackwardEKLM

Returns 1 if the associated KLMCluster is in backward endcap KLM.

klmClusterIsEKLM

Returns 1 if the associated KLMCluster is in endcap KLM.

klmClusterIsForwardEKLM

Returns 1 if the associated KLMCluster is in forward endcap KLM.

klmClusterKlId

Returns the KlId classifier output associated to the KLMCluster.

klmClusterLayers

Returns the number of KLM layers with 2-dimensional hits of the associated KLMCluster.

klmClusterMomentum

Returns the momentum magnitude of the associated KLMCluster.

Warning

This variable returns an approximation of the momentum, since it is proportional to klmClusterLayers (\(p_{\text{KLM}} = 0.215 \cdot N_{\text{layers}}\), where \(p_{\text{KLM}}\) is this variable and \(N_{\text{layers}}\) is klmClusterLayers). It should be used with caution, and may not be physically meaningful.

Unit:

GeV/c

klmClusterPhi

Returns the azimuthal (\(\phi\)) angle of the associated KLMCluster.

Unit:

rad

klmClusterPositionX

Returns the \(x\) position of the associated KLMCluster.

Unit:

cm

klmClusterPositionY

Returns the \(y\) position of the associated KLMCluster.

Unit:

cm

klmClusterPositionZ

Returns the \(z\) position of the associated KLMCluster.

Unit:

cm

klmClusterTheta

Returns the polar (\(\theta\)) angle of the associated KLMCluster.

Unit:

rad

klmClusterTiming

Returns the timing information of the associated KLMCluster.

Unit:

ns

klmClusterTrackDistance

Returns the distance between the Track and the KLMCluster associated to this Particle. This variable returns NaN if there is no Track-to-KLMCluster relationship.

Unit:

cm

maximumKLMAngleCMS

Returns the maximum angle in the CMS frame between the Particle and all KLMClusters in the event.

Unit:

rad

nKLMClusterECLClusterMatches

Returns the number of ECLClusters matched to the KLMCluster associated to this Particle.

nKLMClusterTrackMatches

Returns the number of Tracks matched to the KLMCluster associated to this Particle. This variable can return a number greater than 0 for \(K_{L}^0\) or \(n\) candidates originating from KLMClusters and returns NaN for Particles with no KLMClusters associated.

nMatchedKLMClusters

Returns the number of KLMClusters matched to the particle. It only works for Particles created either from Tracks or from ECLCluster, while it returns NaN for \(K_{L}^0\) or \(n\) candidates originating from KLMClusters.

Time Dependent CPV Analysis Variables

To use most of the variables in this section on need to run vertex.TagV method:

DeltaBoost

\(\Delta z\) in the boost direction

Unit:

cm

DeltaBoostErr

Uncertainty of \(\Delta z\) in the boost direction

Unit:

cm

DeltaT

Proper decay time difference \(\Delta t\) between signal B-meson \((B_{rec})\) and tag B-meson \((B_{tag})\).

Unit:

ps

DeltaTBelle

[Legacy] \(\Delta t\), as it was used in Belle

Unit:

ps

DeltaTErr

Proper decay time difference \(\Delta t\) uncertainty

Unit:

ps

DeltaTRes

\(\Delta t\) residual, to be used for resolution function studies

Unit:

ps

DeltaZ

Difference of decay vertex longitudinal components between signal B-meson \((B_{rec})\) and tag B-meson \((B_{tag})\): \(\Delta z = z(B_{rec}) - z(B_{tag})\)

Unit:

cm

DeltaZErr

Uncertainty of the difference \(z(B_{rec}) - z(B_{tag})\)

Unit:

cm

LBoost

Returns the vertex component in the boost direction

Unit:

cm

LBoostErr

Returns the error of the vertex in the boost direction

Unit:

cm

OBoost

Returns the vertex component in the direction orthogonal to the boost

Unit:

cm

OBoostErr

Returns the error of the vertex in the direction orthogonal to the boost

Unit:

cm

TagTrackAverage(var)

return the average over the tag tracks of the variable var. var must be one of the TagTrackXXX variables, for example: TagTrackAverage(TagTrackDistanceToConstraint). The tracks that are assigned a zero weight are ignored.

TagTrackAverageSquares(var)

return the average over the tag tracks of the square of the variable var. var must be one of the TagTrackXXX variables, for example: TagTrackAverageSquares(TagTrackDistanceToConstraint). The tracks that are assigned a zero weight are ignored.

TagTrackD0(i)

Returns the d0 parameter of the ith track used in the tag vtx fit

Unit:

cm

TagTrackDistanceToConstraint(i)

Returns the measured distance between the ith tag track and the centre of the constraint.

Unit:

cm

TagTrackDistanceToConstraintErr(i)

Returns the estimated error on the distance between the ith tag track and the centre of the constraint.

Unit:

cm

TagTrackDistanceToConstraintSignificance(i)

Returns the significance of the distance between the centre of the constraint and the tag track indexed by track index (computed as distance / uncertainty)

TagTrackDistanceToTagV(i)

Returns the measured distance between the ith tag track and the tag vtx.

Unit:

cm

TagTrackDistanceToTagVErr(i)

Returns the estimated error on the distance between the ith tag track and the tag vtx.

Warning

Only the uncertainties on the track position parameters are taken into account.

Unit:

cm

TagTrackDistanceToTagVSignificance(i)

Returns the significance of the distance between the tag vtx and the tag track indexed by trackIndex (computed as distance / uncertainty)

TagTrackMax(var)

return the maximum value of the variable var evaluated for each tag track. var must be one of the TagTrackXXX variables, for example: TagTrackMax(TagTrackDistanceToConstraint). The tracks that are assigned a zero weight are ignored.

TagTrackMin(var)

return the minimum value of the variable var evaluated for each tag track. var must be one of the TagTrackXXX variables, for example: TagTrackMin(TagTrackDistanceToConstraint). The tracks that are assigned a zero weight are ignored.

TagTrackMomentum(i)

Returns the magnitude of the momentum of the ith track used in the tag vtx fit.

Unit:

GeV/c

TagTrackMomentumX(i)

Returns the X component of the momentum of the ith track used in the tag vtx fit.

Unit:

GeV/c

TagTrackMomentumY(i)

Returns the Y component of the momentum of the ith track used in the tag vtx fit.

Unit:

GeV/c

TagTrackMomentumZ(i)

Returns the Z component of the momentum of the ith track used in the tag vtx fit.

Unit:

GeV/c

TagTrackRaveWeight(i)

Returns the weight assigned by Rave to track i

TagTrackSum(var)

Returns the sum of the provided variable for all tag tracks. The variable must be one of the TagTrackXXX variables, for example TagTrackSum(TagTrackD0). The tracks that are assigned a zero weight are ignored.

TagTrackTrueDistanceToTagV(i)

Returns the true distance between the true B Tag decay vertex and the particle corresponding to the ith tag vtx track.

Unit:

cm

TagTrackTrueMomentumX(i)

Returns the X component of the true momentum of the MC particle corresponding to the ith tag vtx track.

Unit:

GeV/c

TagTrackTrueMomentumY(i)

Returns the Y component of the true momentum of the MC particle corresponding to the ith tag vtx track.

Unit:

GeV/c

TagTrackTrueMomentumZ(i)

Returns the Z component of the true momentum of the MC particle corresponding to the ith tag vtx track.

Unit:

GeV/c

TagTrackTrueOriginX(i)

Returns the X component of the true origin of the MC particle corresponding to the ith tag vtx track.

Unit:

cm

TagTrackTrueOriginY(i)

Returns the Y component of the true origin of the MC particle corresponding to the ith tag vtx track.

Unit:

cm

TagTrackTrueOriginZ(i)

Returns the Z component of the true origin of the MC particle corresponding to the ith tag vtx track.

Unit:

cm

TagTrackTrueVecToTagVX(i)

Returns the X coordinate of the vector between the mc particle corresponding to the ith tag vtx track and the true tag B decay vertex.

Unit:

cm

TagTrackTrueVecToTagVY(i)

Returns the Y coordinate of the vector between the mc particle corresponding to the ith tag vtx track and the true tag B decay vertex.

Unit:

cm

TagTrackTrueVecToTagVZ(i)

Returns the Z coordinate of the vector between the mc particle corresponding to the ith tag vtx track and the true tag B decay vertex.

Unit:

cm

TagTrackWeightedAverage(var)

return the average over the tag tracks of the variable var, weighted by weights of the tag vertex fitter. var must be one of the TagTrackXXX variables, for example: TagTrackWeightedAverage(TagTrackDistanceToConstraint).

TagTrackWeightedAverageSquares(var)

return the average over the tag tracks of the variable var, weighted by weights of the tag vertex fitter. var must be one of the TagTrackXXX variables, for example: TagTrackWeightedAverageSquares(TagTrackDistanceToConstraint).

TagTrackZ0(i)

Returns the z0 parameter of the ith track used in the tag vtx fit

Unit:

cm

TagVChi2

chi2 value of the tag vertex fit

TagVChi2IP

IP component of chi2 value of the tag vertex fit

TagVDistanceToConstraint

returns the measured distance between the tag vtx and the centre of the constraint.

Unit:

cm

TagVDistanceToConstraintErr

returns the estimated error on the distance between the tag vtx and the centre of the constraint.

Unit:

cm

TagVDistanceToConstraintSignificance

returns the significance of the distance between the tag vtx and the centre of the constraint (computed as distance / uncertainty)

TagVFitTruthStatus

Returns the status of the fit performed with the truth info. Possible values are:

• -1: no related TagVertex found

• 0: fit performed with measured parameters

• 1: fit performed with true parameters

• 2: unable to recover truth parameters

TagVLBoost

Returns the TagV component in the boost direction

Unit:

cm

TagVLBoostErr

Returns the error of TagV in the boost direction

Unit:

cm

TagVNDF

Number of degrees of freedom in the tag vertex fit

TagVNFitTracks

returns the number of tracks used by rave to fit the vertex (not counting the ones coming from Kshorts)

TagVNTracks

Number of tracks in the tag vertex

TagVOBoost

Returns the TagV component in the direction orthogonal to the boost

Unit:

cm

TagVOBoostErr

Returns the error of TagV in the direction orthogonal to the boost

Unit:

cm

TagVRollBackStatus

Returns the status of the fit performed with rolled back tracks. Possible values are:

• -1: no related TagVertex found

• 0: fit performed with measured parameters

• 1: fit performed with true parameters

• 2: unable to recover truth parameters

TagVType

Type of algorithm for the tag vertex. -1: failed (1,2: single track, deprecated), 3: standard, 4: standard_PXD, 5: no constraint

TagVpVal

Tag vertex p-Value

TagVx

Tag vertex X component

Unit:

cm

TagVxErr

Tag vertex X component uncertainty

Unit:

cm

TagVy

Tag vertex Y component

Unit:

cm

TagVyErr

Tag vertex Y component uncertainty

Unit:

cm

TagVz

Tag vertex Z component

Unit:

cm

TagVzErr

Tag vertex Z component uncertainty

Unit:

cm

cosAngleBetweenMomentumAndBoostVector

cosine of the angle between momentum and boost vector

internalTagVMCFlavor

[Expert] [Debugging] This variable is only for internal checks of the TagV module by developers. It returns the internal mc flavor information of the tag-side B provided by the TagV module.

mcDeltaBoost

True difference of decay vertex boost-direction components between signal B-meson \((B_{rec})\) and tag B-meson \((B_{tag})\): \(\Delta l = l(B_{rec}) - l(B_{tag})\)

Unit:

cm

mcDeltaT

Generated proper decay time difference (in z-difference approximation) \(\Delta t\):

\((l(B_{\rm rec}) - l(B_{\rm tag}))/\beta_{\Upsilon(4S)}\gamma_{\Upsilon(4S)}\)

Unit:

ps

mcDeltaTau

Generated proper decay time difference \(\Delta t\): \(\tau(B_{\rm rec})-\tau(B_{\rm tag})\)

Unit:

ps

mcLBoost

Returns the MC vertex component in the boost direction

Unit:

cm

mcOBoost

Returns the MC vertex component in the direction orthogonal to the boost

Unit:

cm

mcTagVLBoost

Returns the MC TagV component in the boost direction

Unit:

cm

mcTagVOBoost

Returns the MC TagV component in the direction orthogonal to the boost

Unit:

cm

mcTagVx

Generated Tag vertex X component

Unit:

cm

mcTagVy

Generated Tag vertex Y component

Unit:

cm

mcTagVz

Generated Tag vertex Z component

Unit:

cm

Flavor Tagger

Analysis variables

isRelatedRestOfEventB0Flavor

Returns -1 (1) if the RestOfEvent related to the given particle is related to a anti-B0 (B0). The MCError bit of Breco has to be 0, 1, 2, 16 or 1024. The output of the variable is 0 otherwise. If one particle in the RestOfEvent is found to belong to the reconstructed B0, the output is -2(2) for a anti-B0 (B0) on the reconstructed side.

qOutput(combinerMethod)

Returns the flavor tag \(q\) output of the flavorTagger for the given combinerMethod. The available methods are ‘FBDT’ and ‘FANN’ (category-based combiners), and ‘DNN’ (DNN tagger output).

Warning

You have to run the Flavor Tagger for this variable to be meaningful.

See also

Flavor Tagger and flavorTagger.flavorTagger().

qrOutput(combinerMethod)

Returns the output of the flavorTagger, flavor tag \(q\) times the dilution factor \(r\), for the given combiner method. The available methods are ‘FBDT’ and ‘FANN’ (category-based combiners), and ‘DNN’ (DNN tagger output).

Warning

You have to run the Flavor Tagger for this variable to be meaningful.

See also

Flavor Tagger and flavorTagger.flavorTagger().

rBinBelle(combinerMethod)

Returns the corresponding \(r\) (dilution) bin according to the Belle binning for the given combinerMethod. The available methods are ‘FBDT’ and ‘FANN’ (category-based combiners), and ‘DNN’ (DNN tagger output). The return values and the corresponding dilution ranges are the following:

• 0: \(0.000 < r < 0.100\);

• 1: \(0.100 < r < 0.250\);

• 2: \(0.250 < r < 0.500\);

• 3: \(0.500 < r < 0.625\);

• 4: \(0.625 < r < 0.750\);

• 5: \(0.750 < r < 0.875\);

• 6: \(0.875 < r < 1.000\).

Warning

You have to run the Flavor Tagger for this variable to be meaningful.

See also

Flavor Tagger and flavorTagger.flavorTagger().

Training and expert variables

B0mcErrors

[Expert] Returns MC-matching flag, see mcErrors for the particle, e.g. B0 .

BtagToWBosonVariables(requestedVariable[, maskName])

[Eventbased][Expert] Returns values of FlavorTagging-specific kinematical variables assuming a semileptonic decay with the given particle as target. The input values of requestedVariable can be the following: recoilMass in GeV/c^2 , pMissCMS in GeV/c, cosThetaMissCMS and EW90.

FSCVariables(requestedVariable)

[Eventbased][Expert] Returns values of FlavorTagging-specific kinematical variables for FastSlowCorrelated category. The input values of requestedVariable can be the following: pFastCMS in GeV/c, cosSlowFast, SlowFastHaveOpositeCharges, or cosTPTOFast.

HighestProbInCat(particleListName, extraInfoName)

[Expert] Returns the highest target track probability value for the given category, for allowed input values for extraInfoName see hasHighestProbInCat.

KaonPionVariables(requestedVariable)

[Expert] Returns values of FlavorTagging-specific kinematical variables for KaonPion category. The input values of requestedVariable can be the following: cosKaonPion, HaveOpositeCharges.

NumberOfKShortsInRoe

[Expert] Returns the number of K_S0 in the rest of event. The particle list K_S0:inRoe has to be filled beforehand.

QpOf(particleListName, outputExtraInfo, rankingExtraInfo)

[Eventbased][Expert] Returns the \(q*p\) value for a given particle list provided as the 1st argument, where \(p\) is the probability of a category stored as extraInfo, provided as the 2nd argument, allowed values are same as in hasHighestProbInCat. The particle is selected after ranking according to a flavor tagging extraInfo, provided as the 3rd argument, allowed values are same as in hasHighestProbInCat.

QpTrack(particleListName, outputExtraInfo, rankingExtraInfo)

[Expert] Returns the \(q*p\) value of the particle in a given particle list provided as the 1st argument that is originated from the same Track of given particle. where \(p\) is the probability of a category stored as extraInfo, provided as the 2nd argument, allowed values are same as in hasHighestProbInCat. The particle is selected after ranking according to a flavor tagging extraInfo, provided as the 3rd argument, allowed values are same as in hasHighestProbInCat.

ancestorHasWhichFlavor

[Expert] Checks the decay chain of the given particle upwards up to the Upsilon(4S) resonance and outputs 0 (1) if an ancestor is found to be a anti-B0 (B0), if not -2.

chargeTimesKaonLiklihood

[Expert] Returns q*(highest PID_Likelihood for Kaons), 0. otherwise.

cosTPTO

[Expert] Returns cosine of angle between thrust axis of given particle and thrust axis of ROE.

cosTPTO(maskName)

[Expert] Returns cosine of angle between thrust axis of given particle and thrust axis of ROE.

hasHighestProbInCat(particleListName, extraInfoName)

[Expert] Returns 1.0 if the given Particle is classified as target track, i.e. if it has the highest target track probability in particleListName. The probability is accessed via extraInfoName, which can have the following input values:

• isRightTrack(Electron),

• isRightTrack(IntermediateElectron),

• isRightTrack(Muon),

• isRightTrack(IntermediateMuon),

• isRightTrack(KinLepton),

• isRightTrack(IntermediateKinLepton),

• isRightTrack(Kaon),

• isRightTrack(SlowPion),

• isRightTrack(FastHadron),

• isRightTrack(MaximumPstar),

• isRightTrack(Lambda),

• isRightCategory(Electron),

• isRightCategory(IntermediateElectron),

• isRightCategory(Muon),

• isRightCategory(IntermediateMuon),

• isRightCategory(KinLepton),

• isRightCategory(IntermediateKinLepton),

• isRightCategory(Kaon),

• isRightCategory(SlowPion),

• isRightCategory(FastHadron),

• isRightCategory(MaximumPstar),

• isRightCategory(Lambda),

• isRightCategory(KaonPion),

• isRightCategory(FSC).

hasRestOfEventTracks

[Expert] Returns the number of tracks in the RestOfEvent related to the given Particle. -2 if the RestOfEvent is empty.

hasRestOfEventTracks(maskName)

[Expert] Returns the number of tracks in the RestOfEvent related to the given Particle. -2 if the RestOfEvent is empty.

hasTrueTarget(categoryName)

[Expert] Returns 1 if the given category has a target, 0 otherwise.

hasTrueTargets(categoryName)

[Expert] Returns 1 if target particles (checking only the decay chain) of the category with the given name is found in the MC particles. The allowed categories are the official Flavor Tagger Category Names.

isInElectronOrMuonCat

[Expert] Returns 1.0 if the particle has been selected as target in the Muon or Electron Category, 0.0 otherwise.

isLambda

[Expert] Returns 1.0 if particle is truth-matched to Lambda0, 0.0 otherwise.

isMajorityInRestOfEventFromB0

[Eventbased][Expert] Checks if the majority of the tracks in the current RestOfEvent are from a B0.

isMajorityInRestOfEventFromB0(maskName)

[Eventbased][Expert] Checks if the majority of the tracks in the current RestOfEvent are from a B0.

isMajorityInRestOfEventFromB0bar

[Eventbased][Expert] Check if the majority of the tracks in the current RestOfEvent are from a anti-B0.

isMajorityInRestOfEventFromB0bar(maskName)

[Eventbased][Expert] Check if the majority of the tracks in the current RestOfEvent are from a anti-B0.

isRelatedRestOfEventMajorityB0Flavor

[Expert] Returns 0 (1) if the majority of tracks and clusters of the RestOfEvent related to the given Particle are related to a anti-B0 (B0).

isRelatedRestOfEventMajorityB0Flavor(maskName)

[Expert] Returns 0 (1) if the majority of tracks and clusters of the RestOfEvent related to the given Particle are related to a anti-B0 (B0).

isRestOfEventMajorityB0Flavor

[Expert] Returns 0 (1) if the majority of tracks and clusters of the current RestOfEvent are related to a anti-B0 (B0).

isRightCategory(particleName)

[Expert] Returns 1.0 if the class track by particleName category has the same flavor as the MC target track, 0.0 otherwise. Allowed input values for particleName argument in this variable are the following:

• Electron,

• IntermediateElectron,

• Muon,

• IntermediateMuon,

• KinLepton,

• IntermediateKinLepton

• Kaon,

• SlowPion,

• FastHadron,

• KaonPion,

• MaximumPstar,

• FSC,

• Lambda,

• mcAssociated.

isRightTrack(particleName)

[Expert] Returns 1.0 if the given particle was really from a B-meson depending on category provided in particleName argument, 0.0 otherwise. Allowed input values for particleName argument in this variable are the following:

• Electron,

• IntermediateElectron,

• Muon,

• IntermediateMuon,

• KinLepton,

• IntermediateKinLepton,

• Kaon,

• SlowPion,

• FastHadron,

• Lambda,

• mcAssociated.

isTrueCategory(categoryName)

[Expert] Returns 1 if the given category tags the B0 MC flavor correctly, 0 otherwise.

isTrueFTCategory(categoryName)

[Expert] Returns 1 if the target particle (checking the decay chain) of the category with the given name is found in the MC particles, and if it provides the right flavor. The allowed categories are the official Flavor Tagger Category Names.

lambdaFlavor

[Expert] Returns 1.0 if particle is Lambda0, -1.0 in case of anti-Lambda0, 0.0 otherwise.

lambdaZError

[Expert] Returns the variance of the z-component of the decay vertex.

Unit:

\(\text{cm}^2\)

mcFlavorOfOtherB

[Expert] Returns the MC flavor (+1 or -1) of the accompanying tag-side B meson if the given particle is a correctly truth-matched B candidate, 0 otherwise. In other words, this variable checks the generated flavor of the other generated Upsilon(4S) daughter.

momentumOfSecondDaughter

[Expert] Returns the momentum of second daughter if exists, 0. otherwise.

Unit:

GeV/c

momentumOfSecondDaughterCMS

[Expert] Returns the momentum of the second daughter in the centre-of-mass system, 0. if this daughter doesn’t exist.

Unit:

GeV/c

pMissTag

[Expert] Calculates the missing momentum for a given particle on the tag side.

Unit:

GeV/c

pMissTag(maskName)

[Expert] Calculates the missing momentum for a given particle on the tag side. The unit of the missing momentum is GeV/c

pt2TracksRoe(maskName)

[Expert] Returns the transverse momentum squared of all charged tracks of the ROE related to the given particle, 0.0 if particle has no related ROE. The unit of the momentum squared is \([\text{GeV}/\text{c}]^2\)

ptTracksRoe

[Expert] Returns the transverse momentum of all charged tracks of the ROE related to the given particle, 0.0 if particle has no related ROE.

Unit:

GeV/c

ptTracksRoe(maskName)

[Expert] Returns the transverse momentum of all charged tracks of the ROE related to the given particle, 0.0 if particle has no related ROE. The unit of the momentum is GeV/c

qpCategory(categoryName)

[Expert] Returns the output \(q\) (charge of target track) times \(p\) (probability that this is the right category) of the category with the given name. The allowed categories are the official Flavor Tagger Category Names.

qrCombined

[Eventbased][Expert] Returns -1 (1) if current RestOfEvent is related to a anti-B0 (B0). The MCError bit of Breco has to be 0, 1, 2, 16 or 1024. The output of the variable is 0 otherwise. If one particle in the RestOfEvent is found to belong to the reconstructed B0, the output is -2(2) for a anti-B0 (B0) on the reconstructed side.

variableOfTarget(particleListName, inputVariable, rankingExtraInfo)

[Eventbased][Expert] Returns the value of an input variable provided as the 2nd argument for a particle selected from the given list provided as the 1st argument. The particles are ranked according to a flavor tagging extraInfo, provided as the 2nd argument, allowed values are same as in hasHighestProbInCat.

weightedQpOf(particleListName, outputExtraInfo, rankingExtraInfo)

[Eventbased][Expert] Returns the weighted \(q*p\) value for a given particle list, provided as the 1st argument, where \(p\) is the probability of a category stored as extraInfo, provided in the 2nd argument, allowed values are same as in hasHighestProbInCat. The particles in the list are ranked according to a flavor tagging extraInfo, provided as the 3rd argument, allowed values are same as in hasHighestProbInCat. The values for the three top particles is combined into an effective (weighted) output.

Rest of Event

bssMassDifference(maskName)

Bs* - Bs mass difference. The unit of the mass is \(\text{GeV/c}^2\).

currentROEIsInList(particleList)

[Eventbased] Returns 1 the associated particle of the current ROE is contained in the given list or its charge-conjugated.Useful to restrict the for_each loop over ROEs to ROEs of a certain ParticleList.

etaProb(mode)

Returns eta probability, where mode is used to specify the selection criteria for soft photon. The following strings are available.

• standard: loose energy cut and no clusterNHits cut are applied to soft photon

• tight: tight energy cut and no clusterNHits cut are applied to soft photon

• cluster: loose energy cut and clusterNHits cut are applied to soft photon

• both: tight energy cut and clusterNHits cut are applied to soft photon

You can find more details in writePi0EtaVeto function in modularAnalysis.py.

hasAncestorFromSignalSide

Returns 1 if a particle has ancestor from signal side, 0 otherwise. Requires generator information and truth-matching. One can use this variable only in a for_each loop over the RestOfEvent StoreArray.

hasCorrectROECombination

Returns 1 if there is correct combination of daughter particles between the particle that is the basis of the ROE and the particle loaded from the ROE. Returns 0 if there is not correct combination. If there is no daughter particle loaded from the ROE, returns quiet NaN.

isCloneOfSignalSide

Returns 1 if a particle is a clone of signal side final state particles, 0 otherwise. Requires generator information and truth-matching. One can use this variable only in a for_each loop over the RestOfEvent StoreArray.

isInRestOfEvent

Returns 1 if a track, ecl or klmCluster associated to particle is in the current RestOfEvent object, 0 otherwise.One can use this variable only in a for_each loop over the RestOfEvent StoreArray.

nROE_Charged(maskName, PDGcode = 0)

Returns number of all charged particles in the related RestOfEvent object. First optional argument is ROE mask name. Second argument is a PDG code to count only one charged particle species, independently of charge. For example: nROE_Charged(cleanMask, 321) will output number of kaons in Rest Of Event with cleanMask. PDG code 0 is used to count all charged particles

nROE_Composites(maskName)

Returns number of composite particles or V0s in the related RestOfEvent object that pass the selection criteria.

nROE_ECLClusters(maskName)

Returns number of ECL clusters in the related RestOfEvent object that pass the selection criteria.

nROE_KLMClusters

Returns number of all remaining KLM clusters in the related RestOfEvent object.

nROE_NeutralECLClusters(maskName)

Returns number of neutral ECL clusters in the related RestOfEvent object that pass the selection criteria.

nROE_NeutralHadrons(maskName)

Returns number of all neutral hadrons in the related RestOfEvent object, accepts 1 optional argument of ROE mask name.

nROE_ParticlesInList(pListName[, maskName])

Returns the number of particles in ROE from the given particle list. If a mask name is provided the selection criteria are applied. Use of variable aliases is advised.

nROE_Photons(maskName)

Returns number of all photons in the related RestOfEvent object, accepts 1 optional argument of ROE mask name.

nROE_RemainingTracks

Returns number of tracks in ROE - number of tracks of given particleOne can use this variable only in a for_each loop over the RestOfEvent StoreArray.

nROE_RemainingTracks(maskName)

Returns number of remaining tracks between the ROE (specified via a mask) and the given particle. For the given particle only tracks are counted which are in the RoE.One can use this variable only in a for_each loop over the RestOfEvent StoreArray.Is required for the specific FEI.

nROE_Tracks(maskName)

Returns number of tracks in the related RestOfEvent object that pass the selection criteria.

particleRelatedToCurrentROE(var)

[Eventbased] Returns variable applied to the particle which is related to the current RestOfEvent objectOne can use this variable only in a for_each loop over the RestOfEvent StoreArray.

passesROEMask(maskName)

Returns boolean value if a particle passes a certain mask or not. Only to be used in for_each path, otherwise returns quiet NaN.

pi0Prob(mode)

Returns pi0 probability, where mode is used to specify the selection criteria for soft photon. The following strings are available.

• standard: loose energy cut and no clusterNHits cut are applied to soft photon

• tight: tight energy cut and no clusterNHits cut are applied to soft photon

• cluster: loose energy cut and clusterNHits cut are applied to soft photon

• both: tight energy cut and clusterNHits cut are applied to soft photon

You can find more details in writePi0EtaVeto function in modularAnalysis.py.

printROE

For debugging, prints indices of all particles in the ROE and all masks. Returns 0.

roeCharge(maskName)

Returns total charge of the related RestOfEvent object. The unit of the charge is e

roeDeltae(maskName)

Returns energy difference of the related RestOfEvent object with respect to \(E_\mathrm{cms}/2\). The unit of the energy is GeV

roeE(maskName)

Returns energy of unused tracks and clusters in ROE, can be used with use***Frame() function. The unit of the energy is GeV

roeEextra(maskName)

Returns extra energy from ECLClusters in the calorimeter that is not associated to the given Particle. The unit of the energy is GeV

roeM(maskName)

Returns invariant mass of unused tracks and clusters in ROE. The unit of the invariant mass is \(\text{GeV/c}^2\)

roeMC_E

Returns true energy of unused tracks and clusters in ROE, can be used with use***Frame() function.

Unit:

GeV

roeMC_M

Returns true invariant mass of unused tracks and clusters in ROE

Unit:

GeV/\(\text{c}^2\)

roeMC_MissFlags(maskName)

Returns flags corresponding to missing particles on ROE side.

roeMC_P

Returns true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

Unit:

GeV/c

roeMC_PTheta

Returns polar angle of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

Unit:

rad

roeMC_Pt

Returns transverse component of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

Unit:

GeV/c

roeMC_Px

Returns x component of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

Unit:

GeV/c

roeMC_Py

Returns y component of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

Unit:

GeV/c

roeMC_Pz

Returns z component of true momentum of unused tracks and clusters in ROE, can be used with use***Frame() function.

Unit:

GeV/c

roeMbc(maskName)

Returns beam constrained mass of the related RestOfEvent object with respect to \(E_\mathrm{cms}/2\). The unit of the beam constrained mass is \(\text{GeV/c}^2\).

roeNeextra(maskName)

Returns extra energy from neutral ECLClusters in the calorimeter that is not associated to the given Particle, can be used with use***Frame() function. The unit of the energy is GeV

roeP(maskName)

Returns momentum of unused tracks and clusters in ROE, can be used with use***Frame() function. The unit of the momentum is GeV/c

roePTheta(maskName)

Returns theta angle of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function. The unit of the angle is rad

roePt(maskName)

Returns transverse component of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function. The unit of the momentum is GeV/c

roePx(maskName)

Returns x component of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function. The unit of the momentum is GeV/c

roePy(maskName)

Returns y component of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function. The unit of the momentum is GeV/c

roePz(maskName)

Returns z component of momentum of unused tracks and clusters in ROE, can be used with use***Frame() function. The unit of the momentum is GeV/c

useROERecoilFrame(variable)

Returns the value of the variable using the rest frame of the ROE recoil as current reference frame. Can be used inside for_each loop or outside of it if the particle has associated Rest of Event. E.g. useROERecoilFrame(E) returns the energy of a particle in the ROE recoil frame.

weCosThetaEll(maskName)

Returns the cosine of the angle between \(M\) and lepton in \(W\) rest frame in the decays of the type: \(M \to h_1 ... h_n \ell\), where W 4-momentum is given as

\[p_W = p_\ell + p_\nu.\]

The neutrino momentum is calculated from ROE taking into account the specified mask, and setting

\[E_{\nu} = |p_{miss}|.\]

weDeltae(maskName, opt)

Returns the energy difference of the B meson, corrected with the missing neutrino momentum (reconstructed side + neutrino) with respect to \(E_\mathrm{cms}/2\). The unit of the energy is GeV

weMbc(maskName, opt)

Returns beam constrained mass of B meson, corrected with the missing neutrino momentum (reconstructed side + neutrino) with respect to \(E_\mathrm{cms}/2\). The unit of the beam constrained mass is \(\text{GeV/c}^2\).

weMissE(maskName, opt)

Returns the energy of the missing momentum. The unit of the Energy is GeV . Possible options opt are the following:

• 0: CMS, use energy and momentum of charged particles and photons

• 1: CMS, same as 0, fix \(E_\mathrm{miss} = p_\mathrm{miss}\)

• 2: CMS, same as 0, fix \(E_\mathrm{roe} = E_\mathrm{cms}/2\)

• 3: CMS, use only energy and momentum of signal side

• 4: CMS, same as 3, update with direction of ROE momentum

• 5: LAB, use energy and momentum of charged particles and photons from whole event

• 6: LAB, same as 5, fix \(E_\mathrm{miss} = p_\mathrm{miss}`\)

• 7: CMS, correct pmiss 3-momentum vector with factor alpha so that \(d_E = 0`\) (used for \(M_\mathrm{bc}\) calculation).

weMissM2(maskName, opt)

Returns the invariant mass squared of the missing momentum (see weMissE possible options). The unit of the invariant mass squared is \([\text{GeV}/\text{c}^2]^2\).

weMissM2OverMissE(maskName)

Returns missing mass squared over missing energy. The unit of the missing mass squared is \(\text{GeV/c}^4\).

weMissP(maskName, opt)

Returns the magnitude of the missing momentum (see possible weMissE options). The unit of the magnitude of missing momentum is GeV/c

weMissPTheta(maskName, opt)

Returns the polar angle of the missing momentum (see possible weMissE options). The unit of the polar angle is rad

weMissPx(maskName, opt)

Returns the x component of the missing momentum (see weMissE possible options). The unit of the missing momentum is GeV/c

weMissPy(maskName, opt)

Returns the y component of the missing momentum (see weMissE possible options). The unit of the missing momentum is GeV/c

weMissPz(maskName, opt)

Returns the z component of the missing momentum (see weMissE possible options). The unit of the missing momentum is GeV/c

weQ2lnu(maskName, option)

Returns the momentum transfer squared, \(q^2\), calculated in CMS as \(q^2 = (p_l + p_\nu)^2\), where \(B \to H_1\dots H_n \ell \nu_\ell\). Lepton is assumed to be the last reconstructed daughter. This calculation uses constraints from dE = 0 and Mbc = Mb to correct the neutrino direction. By default, option is set to 7 (see weMissE). Unless you know what you are doing, keep this default value. The unit of the momentum transfer squared is \([\text{GeV}/\text{c}]^2\).

weQ2lnuSimple(maskName, option)

Returns the momentum transfer squared, \(q^2\), calculated in CMS as \(q^2 = (p_l + p_\nu)^2\), where \(B \to H_1\dots H_n \ell \nu_\ell\). Lepton is assumed to be the last reconstructed daughter. By default, option is set to 1 (see weMissE). Unless you know what you are doing, keep this default value. The unit of the momentum transfer squared is \([\text{GeV}/\text{c}]^2\).

weXiZ(maskName)

Returns Xi_z in event (for Bhabha suppression and two-photon scattering). The unit of this variable is 1/c

Continuum Suppression

For a detailed description of the continuum suppression, see Continuum suppression. All variables in this group require the ContinuumSuppressionBuilder module to be added to the path, and a rest of event for the candidate particles. This can be done with both the modularAnalysis.buildRestOfEvent, and the modularAnalysis.buildContinuumSuppression convenience functions.

CleoConeCS(integer[, string, string])

Returns i-th cleo cones from the continuum suppression. The allowed inputs for the integer argument are integers from 1 to 9. The second and third arguments are optional unless you have created multiple instances of the ContinuumSuppression with different ROE masks. In that case the desired ROE mask name must be provided as well. If the second argument is set to ‘ROE’, the CleoCones are calculated only from ROE particles. Otherwise, the CleoCones are calculated from all final state particles. The ROE mask name is then either the second or the third argument and must not be called ‘ROE’. The unit of the CleoConeCS is GeV/c.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

KSFWVariables(variable[, string, string])

Returns variable et in GeV/c, mm2 in (GeV/c^2)^2, or one of the 16 KSFW moments. The second and third arguments are optional unless you have created multiple instances of the ContinuumSuppression with different ROE masks. In that case the desired ROE mask name must be provided as well. If the second argument is set to ‘FS1’, the KSFW moment is calculated from the B final state daughters. Otherwise, the KSFW moment is calculated from the B primary daughters. The ROE mask name is then either the second or the third argument and must not be called ‘FS1’. Allowed input values for variable argument are the following:

• mm2, et

• hso00, hso01, hso02, hso03, hso04

• hso10, hso12, hso14

• hso20, hso22, hso24

• hoo0, hoo1, hoo2, hoo3, hoo4.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

R2

Returns reduced Fox-Wolfram R2, defined as ratio of the i-th to the 0-th order Fox Wolfram moments.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

R2(maskname)

Returns reduced Fox-Wolfram R2, defined as ratio of the i-th to the 0-th order Fox Wolfram moments.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

cosTBTO

Returns cosine of angle between thrust axis of the signal B and thrust axis of ROE.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

cosTBTO(maskname)

Returns cosine of angle between thrust axis of the signal B and thrust axis of ROE.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

cosTBz

Returns cosine of angle between thrust axis of the signal B and z-axis.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

cosTBz(maskname)

Returns cosine of angle between thrust axis of the signal B and z-axis.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

thrustBm

Returns magnitude of the signal B thrust axis.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

thrustBm(maskname)

Returns magnitude of the signal B thrust axis.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

thrustOm

Returns magnitude of the ROE thrust axis.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

thrustOm(maskname)

Returns magnitude of the ROE thrust axis.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

transformedNetworkOutput(name, low, high)

Transforms the network output \(C \to C'\) via: \(C'=\operatorname{log}((C-\mathrm{low})/(\mathrm{high}-C))\). The arguments of the metavariable are the following:

• name is the extraInfo name, where the network output \(C\) has been stored. If particle is not specified, event extraInfo is used instead;

• low, high are floating point numbers.

Returns NaN, if the extraInfo has not been found.

useBThrustFrame(variable, mode)

Returns the variable with respect to rotated coordinates, in which z lies on the specified thrust axis. If mode is set to Signal it will use the thrust axis of the reconstructed B candidate, if mode is set to ROE it will use the ROE thrust axis. If mode is set to Auto the function use the thrust axis based on Rest Of Event (ROE) particles. Like isInRestOfEvent, one has to use this metavariable in ROE loop.

Warning

You have to run the Continuum Suppression builder module for this variable to be meaningful.

See also

Continuum suppression and buildContinuumSuppression.

Event Shape

These variables are available after adding the event shape builder modules. This can be done with the function modularAnalysis.buildEventShape. For a detailed description of the event shape variables, see EventShape

aplanarity

[Eventbased] Event aplanarity, defined as the 3/2 of the third sphericity eigenvalue.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

backwardHemisphereEnergy

[Eventbased] Total energy of the particles flying in the direction opposite to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV

backwardHemisphereMass

[Eventbased] Invariant mass of the particles flying in the direction opposite to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/\(\text{c}^2\)

backwardHemisphereMomentum

[Eventbased] Total momentum of the particles flying in the direction opposite to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

backwardHemisphereX

[Eventbased] X component of the total momentum of the particles flying in the direction opposite to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

backwardHemisphereY

[Eventbased] Y component of the total momentum of the particles flying in the direction opposite to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

backwardHemisphereZ

[Eventbased] Z component of the total momentum of the particles flying in the direction opposite to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

cleoCone(i, axisName)

[Eventbased] Returns i-th order Cleo cone, calculated with respect to the axis axisName. The order i can go from 0 up to 8th, the axisName can be either ‘thrust’ or ‘collision’.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust0

[Eventbased] 0th Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust1

[Eventbased] 1st Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust2

[Eventbased] 2nd Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust3

[Eventbased] 3rd Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust4

[Eventbased] 4th Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust5

[Eventbased] 5th Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust6

[Eventbased] 6th Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust7

[Eventbased] 7th Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

cleoConeThrust8

[Eventbased] 8th Cleo cone calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

forwardHemisphereEnergy

[Eventbased] Total energy of the particles flying in the same direction as the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV

forwardHemisphereMass

[Eventbased] Invariant mass of the particles flying in the same direction as the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/\(\text{c}^2\)

forwardHemisphereMomentum

[Eventbased] Total momentum of the particles flying in the same direction as the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

forwardHemisphereX

[Eventbased] X component of the total momentum of the particles flying in the same direction as the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

forwardHemisphereY

[Eventbased] Y component of the total momentum of the particles flying in the same direction as the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

forwardHemisphereZ

[Eventbased] Z component of the total momentum of the particles flying in the same direction of the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

foxWolframH(i)

[Eventbased] Returns i-th order Fox Wolfram moment. The order i can go from 0 up to 8th.”

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

\(\text{GeV}^2\)/\(\text{c}^2\)

foxWolframR(i)

[Eventbased] Ratio of the i-th to the 0-th order Fox Wolfram moments. The order i can go from 0 up to 8th.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

foxWolframR1

[Eventbased] Ratio of the 1-st to the 0-th order Fox Wolfram moments. This is just an alias of foxWolframR(1) defined for the user’s convenience.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

foxWolframR2

[Eventbased] Ratio of the 2-nd to the 0-th order Fox Wolfram moments. This is just an alias of foxWolframR(2) defined for the user’s convenience.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

foxWolframR3

[Eventbased] Ratio of the 3-rd to the 0-th order Fox Wolfram moments. This is just an alias of foxWolframR(3) defined for the user’s convenience.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

foxWolframR4

[Eventbased] Ratio of the 4-th to the 0-th order Fox Wolfram moments. This is just an alias of foxWolframR(4) defined for the user’s convenience.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

harmonicMoment(i, axisName)

[Eventbased] Returns i-th order harmonic moment, calculated with respect to the axis axisName. The order i can go from 0 up to 8th, the axisName can be either ‘thrust’ or ‘collision’. The unit of the harmonic moment is GeV/c.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

harmonicMomentThrust0

[Eventbased] Harmonic moment of the 0th order calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

harmonicMomentThrust1

[Eventbased] Harmonic moment of the 1st order calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

harmonicMomentThrust2

[Eventbased] Harmonic moment of the 2nd order calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

harmonicMomentThrust3

[Eventbased] Harmonic moment of the 3rd order calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

harmonicMomentThrust4

[Eventbased] Harmonic moment of the 4th order calculated with respect to the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Unit:

GeV/c

sphericity

[Eventbased] Event sphericity, defined as the linear combination of the sphericity eigenvalues \(\lambda_i\): \(S = (3/2)(\lambda_2+\lambda_3)\).

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

thrust

[Eventbased] Event thrust.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

thrustAxisCosTheta

[Eventbased] Cosine of the polar angle component of the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

thrustAxisX

[Eventbased] X component of the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

thrustAxisY

[Eventbased] Y component of the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

thrustAxisZ

[Eventbased] Z component of the thrust axis.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

useThrustFrame(variable)

Evaluates a variable value in the thrust reference frame.

Warning

You have to run the Event Shape builder module for this variable to be meaningful.

See also

EventShape and modularAnalysis.buildEventShape.

Event Kinematics

These variables are available after adding the event kinematics module. This can be done with the function modularAnalysis.buildEventKinematics. The variable collection event_kinematics allows to add all of them comfortably to your ntuple.

genMissingEnergyOfEventCMS

[Eventbased] The missing energy in center-of-mass frame from generator.

Unit:

GeV

genMissingMass2OfEvent

[Eventbased] The missing mass squared from generator

Unit:

\([\text{GeV}/\text{c}^2]^2\)

genMissingMomentumOfEventCMS

[Eventbased] The magnitude of the missing momentum in center-of-mass frame from generator

Unit:

GeV/c

genTotalPhotonsEnergyOfEvent

[Eventbased] The energy in laboratory frame of all the photons. from generator.

Unit:

GeV

genVisibleEnergyOfEventCMS

[Eventbased] The visible energy in center-of-mass frame from generator.

Unit:

GeV

missingEnergyOfEventCMS

[Eventbased] The missing energy in center-of-mass frame.

Unit:

GeV

missingMass2OfEvent

[Eventbased] The missing mass squared.

Unit:

\([\text{GeV}/\text{c}^2]^2\)

missingMomentumOfEvent

[Eventbased] The magnitude of the missing momentum in laboratory frame.

Warning

You have to run the Event Kinematics builder module for this variable to be meaningful.

See also

modularAnalysis.buildEventKinematics.

Unit:

GeV/c

missingMomentumOfEventCMS

[Eventbased] The magnitude of the missing momentum in center-of-mass frame.

Unit:

GeV/c

missingMomentumOfEventCMS_Px

[Eventbased] The x component of the missing momentum in center-of-mass frame.

Unit:

GeV/c

missingMomentumOfEventCMS_Py

[Eventbased] The y component of the missing momentum in center-of-mass frame.

Unit:

GeV/c

missingMomentumOfEventCMS_Pz

[Eventbased] The z component of the missing momentum in center-of-mass frame.

Unit:

GeV/c

missingMomentumOfEventCMS_theta

[Eventbased] The theta angle of the missing momentum in center-of-mass frame.

Unit:

rad

missingMomentumOfEvent_Px

[Eventbased] The x component of the missing momentum in laboratory frame.

Unit:

GeV/c

missingMomentumOfEvent_Py

[Eventbased] The y component of the missing momentum in laboratory frame.

Unit:

GeV/c

missingMomentumOfEvent_Pz

[Eventbased] The z component of the missing momentum in laboratory frame.

Unit:

GeV/c

missingMomentumOfEvent_theta

[Eventbased] The theta angle of the missing momentum of the event in laboratory frame.

Unit:

rad

totalPhotonsEnergyOfEvent

[Eventbased] The energy in laboratory frame of all the photons.

Unit:

GeV

visibleEnergyOfEventCMS

[Eventbased] The visible energy in center-of-mass frame.

Unit:

GeV

Flight Information

Here is a list of flight time and distance variables of a (grand)daughter particle w.r.t. its (grand)mother decay vertex:

flightDistance

Returns the flight distance of particle. If a treeFit has been performed the flight distance calculated by TreeFitter is returned. Otherwise if a beam constrained rave fit has been performed the production vertex set by rave and the decay vertex are used to calculate the flight distance. If neither fit has been performed the i.p. is taken to be the production vertex.

Unit:

cm

flightDistanceErr

Returns the flight distance error of particle. If a treeFit has been performed the flight distance error calculated by TreeFitter is returned. Otherwise if a beam constrained rave fit has been performed the production vertex set by rave and the decay vertex are used to calculate the flight distance error. If neither fit has been performed the i.p. is taken to be the production vertex.

Unit:

cm

flightDistanceOfDaughter(daughterN, gdaughterN = -1)

Returns the flight distance between mother and daughter particle with daughterN index. If a treeFit has been performed the value calculated by treeFitter is returned. Otherwise the value is calculated using the decay vertices of the mother and daughter particle. If a second index granddaughterM is given the value is calculated between the mother and the Mth grandaughter (Mth daughter of Nth daughter).

Unit:

cm

flightDistanceOfDaughterErr(daughterN, gdaughterN = -1)

Returns the flight distance error between mother and daughter particle with daughterN index. If a treeFit has been performed the value calculated by treeFitter is returned. Otherwise the value is calculated using the decay vertices of the mother and daughter particle. If a second index granddaughterM is given the value is calculated between the mother and the Mth grandaughter (Mth daughter of Nth daughter).

Unit:

cm

flightTime

Returns the flight time of particle. If a treeFit has been performed the flight time calculated by TreeFitter is returned. Otherwise if a beam constrained rave fit has been performed the production vertex set by rave and the decay vertex are used to calculate the flight time. If neither fit has been performed the i.p. is taken to be the production vertex.

Unit:

ns

flightTimeErr

Returns the flight time error of particle. If a treeFit has been performed the flight time error calculated by TreeFitter is returned. Otherwise if a beam constrained rave fit has been performed the production vertex set by rave and the decay vertex are used to calculate the flight time error. If neither fit has been performed the i.p. is taken to be the production vertex.

Unit:

ns

flightTimeOfDaughter(daughterN, gdaughterN = -1)

Returns the flight time between mother and daughter particle with daughterN index. If a treeFit has been performed the value calculated by treeFitter is returned. Otherwise the value is calculated using the decay vertices of the mother and daughter particle. If a second index granddaughterM is given the value is calculated between the mother and the Mth grandaughter (Mth daughter of Nth daughter).

Unit:

ns

flightTimeOfDaughterErr(daughterN, gdaughterN = -1)

Returns the flight time error between mother and daughter particle with daughterN index. If a treeFit has been performed the value calculated by treeFitter is returned. Otherwise the value is calculated using the decay vertices of the mother and daughter particle. If a second index granddaughterM is given the value is calculated between the mother and the Mth grandaughter (Mth daughter of Nth daughter).

Unit:

ns

mcFlightDistance

Returns the MC flight distance of the particle

Unit:

cm

mcFlightDistanceOfDaughter(daughterN, gdaughterN = -1)

Returns the MC flight distance between mother and daughter particle using generated info

Unit:

cm

mcFlightTime

Returns the MC flight time of the particle

Unit:

ns

mcFlightTimeOfDaughter(daughterN, gdaughterN = -1)

Returns the MC flight time between mother and daughter particle using generated info

Unit:

ns

vertexDistance

Returns the distance between the production and decay vertex of a particle. Returns NaN if particle has no production or decay vertex.

Unit:

cm

vertexDistanceErr

Returns the uncertainty on the distance between the production and decay vertex of a particle. Returns NaN if particle has no production or decay vertex.

Unit:

cm

vertexDistanceOfDaughter(daughterN[, option])

If any integer is provided as second argument it returns the distance between the decay vertices of the particle and of its daughter with index daughterN. Otherwise, it is assumed that the particle has a production vertex (typically the IP) which is used to calculate the distance to the daughter’s decay vertex. Returns NaN in case anything goes wrong.

Unit:

cm

vertexDistanceOfDaughterErr(daughterN[, option])

If any integer is provided as second argument it returns the uncertainty on the distance between the decay vertices of the particle and of its daughter with index daughterN. Otherwise, it is assumed that the particle has a production vertex (typically the IP) with a corresponding covariance matrix to calculate the uncertainty on the distance to the daughter’s decay vertex. Returns NaN in case anything goes wrong.

Unit:

cm

vertexDistanceOfDaughterSignificance(daughterN[, option)

If any integer is provided as second argument it returns the distance between the decay vertices of the particle and of its daughter with index daughterN in units of the uncertainty on this value. Otherwise, it is assumed that the particle has a production vertex (typically the IP) with a corresponding covariance matrix and the significance of the separation to this vertex is calculated.

vertexDistanceSignificance

Returns the distance between the production and decay vertex of a particle in units of the uncertainty on this value, i.e. the significance of the vertex separation.

Vertex Information

Here is a list of production and decay vertex variables:

dcosTheta

vertex or POCA polar angle with respect to IP

distance

3D distance between the IP and the particle decay vertex, if available.

In case the particle has been created from a track, the distance is defined between the POCA and IP. If the particle is built from an ECL cluster, the decay vertex is set to the nominal IP. If the particle is created from a KLM cluster, the distance is calculated between the IP and the cluster itself.

Unit:

cm

dphi

vertex azimuthal angle of the vertex or POCA in degrees with respect to IP

Unit:

rad

dr

transverse distance with respect to IP for a vertex; track abs(d0) relative to IP for a track.

Unit:

cm

dx

vertex or POCA in case of tracks x with respect to IP

Unit:

cm

dy

vertex or POCA in case of tracks y with respect to IP

Unit:

cm

dz

vertex or POCA in case of tracks z with respect to IP

Unit:

cm

mcDecayVertexFromIPDistance

Returns the distance of the decay vertex of the matched generated particle from the IP. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcDecayVertexFromIPRho

Returns the transverse position of the decay vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcDecayVertexFromIPX

Returns the x position of the decay vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcDecayVertexFromIPY

Returns the y position of the decay vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcDecayVertexFromIPZ

Returns the z position of the decay vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcDecayVertexRho

Returns the transverse position of the decay vertex of the matched generated particle. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcDecayVertexX

Returns the x position of the decay vertex of the matched generated particle. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcDecayVertexY

Returns the y position of the decay vertex of the matched generated particle. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcDecayVertexZ

Returns the z position of the decay vertex of the matched generated particle. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcProductionVertexFromIPX

Returns the x position of the production vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcProductionVertexFromIPY

Returns the y position of the production vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcProductionVertexFromIPZ

Returns the z position of the production vertex of the matched generated particle wrt the IP. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcProductionVertexX

Returns the x position of production vertex of matched generated particle. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcProductionVertexY

Returns the y position of production vertex of matched generated particle. Returns nan if the particle has no matched generated particle.

Unit:

cm

mcProductionVertexZ

Returns the z position of production vertex of matched generated particle. Returns nan if the particle has no matched generated particle.

Unit:

cm

prodVertexCov(i, j)

Returns the ij covariance matrix component of particle production vertex, arguments i,j should be 0, 1 or 2. Returns NaN if particle has no production covariance matrix.

Unit:

\(\text{cm}^2\)

prodVertexX

Returns the x position of particle production vertex. Returns NaN if particle has no production vertex.

Unit:

cm

prodVertexXErr

Returns the x position uncertainty of particle production vertex. Returns NaN if particle has no production vertex.

Unit:

cm

prodVertexY

Returns the y position of particle production vertex.

Unit:

cm

prodVertexYErr

Returns the y position uncertainty of particle production vertex.

Unit:

cm

prodVertexZ

Returns the z position of particle production vertex.

Unit:

cm

prodVertexZErr

Returns the z position uncertainty of particle production vertex.

Unit:

cm

significanceOfDistance

significance of distance from vertex or POCA to interaction point(-1 in case of numerical problems)

x

x coordinate of vertex in case of composite particle, or point of closest approach (POCA) in case of a track

Unit:

cm

x_uncertainty

uncertainty on x (measured with respect to the origin)

Unit:

cm

y

y coordinate of vertex in case of composite particle, or point of closest approach (POCA) in case of a track

Unit:

cm

y_uncertainty

uncertainty on y (measured with respect to the origin)

Unit:

cm

z

z coordinate of vertex in case of composite particle, or point of closest approach (POCA) in case of a track

Unit:

cm

z_uncertainty

uncertainty on z (measured with respect to the origin)

Unit:

cm

KFit variables

Here is a list of variables that indicate the quality of a KFit.

FourCKFitChi2

Chi2 of four momentum-constraint kinematical fit in KFit

FourCKFitProb

Prob of four momentum-constraint kinematical fit in KFit

KFit_nTracks

number of tracks used in the vertex KFit

TracksLBoostChi2

indicator of vertex KFit quality based on accumulated change of track positions

Orca Kinematic Fitter

Warning

In order to populate these variables, you need to run the Orca kinematic fitter. I.e.

import kinfit
kinfit.fitKinematic4C(your_candidates, path=mypath) # or similar

See also

Kinematic-fitting convenience functions

OrcaKinFitChi2

The \(\chi^2\) returned by the Orca kinematic fitter. Returns NaN if Orca was not run.

Warning

this is the raw \(\chi^2\), not over ndf.

See also

Kinematic-fitting convenience functions

OrcaKinFitErrorCode

The error code returned by the Orca kinematic fitter. Returns NaN if Orca was not run.

See also

Kinematic-fitting convenience functions

OrcaKinFitProb

The p-value returned by the Orca kinematic fitter. Returns NaN if Orca was not run.

See also

Kinematic-fitting convenience functions

OrcaKinFitUnmeasuredE

The energy of the “unmeasured photon” returned by Orca kinematic fitter for specific 1C fits with the addUnmeasuredPhoton parameter set. I.e. for fits with sufficient constraints remaining to constrain a missing 3-vector. Returns NaN if Orca was not run or if the addUnmeasuredPhoton parameter was not set.

See also

Kinematic-fitting convenience functions

Unit:

GeV

OrcaKinFitUnmeasuredErrorE

The uncertainty on OrcaKinFitUnmeasuredE.

Unit:

GeV

OrcaKinFitUnmeasuredErrorPhi

The uncertainty on OrcaKinFitUnmeasuredPhi.

Unit:

rad

OrcaKinFitUnmeasuredErrorTheta

The uncertainty on OrcaKinFitUnmeasuredTheta.

Unit:

rad

OrcaKinFitUnmeasuredPhi

The azimuthal angle of the “unmeasured photon” returned by Orca kinematic fitter for specific 1C fits with the addUnmeasuredPhoton parameter set. I.e. for fits with sufficient constraints remaining to constrain a missing 3-vector. Returns NaN if Orca was not run or if the addUnmeasuredPhoton parameter was not set.

See also

Kinematic-fitting convenience functions

Unit:

rad

OrcaKinFitUnmeasuredTheta

The polar angle of the “unmeasured photon” returned by Orca kinematic fitter for specific 1C fits with the addUnmeasuredPhoton parameter set. I.e. for fits with sufficient constraints remaining to constrain a missing 3-vector. Returns NaN if Orca was not run or if the addUnmeasuredPhoton parameter was not set.

See also

Kinematic-fitting convenience functions

Unit:

rad

For fully-inclusive particles

Here is a list of useful variables to work with fully-inclusive particles, which are produced via Rest Of Event, AllParticleCombiner or other inclusive reconstruction modules:

daughterAverageOf(variable)

Returns the mean value of a variable over all daughters.

nCompositeAllGenerationDaughters(pdg)

Returns the number of all generations’ composite daughters with the provided PDG code or the numberof all generations’ composite daughters if no argument has been provided. The variable is flavor agnostic and it returns the sum of the number of particle and anti-particle.

nCompositeDaughters(pdg)

Returns the number of primary composite daughters with the provided PDG code or the numberof all primary composite daughters if no argument has been provided. The variable is flavor agnostic and it returns the sum of the number of particle and anti-particle.

nDaughterCharged(pdg)

Returns the number of charged daughters with the provided PDG code or the number of all charged daughters if no argument has been provided. The variable is flavor agnostic and it returns the sum of the number of particle and anti-particle.

nDaughterNeutralHadrons

Returns the number of K_L0 or neutrons among the final state daughters.

nDaughterPhotons

Returns the number of final state daughter photons.

Specific kinematic variables

This variables group is reserved for the variables for analyses of specific decays like, \(B \to h l \nu\), \(B \to h l^\pm l^\mp\), etc.

recMissM2

Returns the invariant mass squared of the missing momentum calculated assumings the reco B is at rest and calculating the neutrino (missing) momentum from \(p_\nu = p_B - p_{\rm had} - p_{\rm lep}\)

Unit:

\([\text{GeV}/\text{c}^2]^2\)

recQ2Bh

Returns the momentum transfer squared, \(q^2\), calculated in CMS as \(q^2 = (p_B - p_h)^2\), where p_h is the CMS momentum of all hadrons in the decay \(B \to H_1\dots H_n \ell \nu_\ell\). This calculation uses a weighted average of the B meson around the reco B cone. Based on diamond frame calculation of \(q^2\) following the idea presented in https://www.osti.gov/biblio/1442697 It will switch to use of recQ2BhSimple if absolute of cosThetaBetweenParticleAndNominalB > 1.

Unit:

\([\text{GeV}/\text{c}]^2\)

recQ2BhSimple

Returns the momentum transfer squared, \(q^2\), calculated in CMS as \(q^2 = (p_B - p_h)^2\), where p_h is the CMS momentum of all hadrons in the decay \(B \to H_1 ... H_n \ell \nu_\ell\). The B meson momentum in CMS is assumed to be 0.

Unit:

\([\text{GeV}/\text{c}]^2\)

Belle and b2bii variables

Several legacy Belle variables are provided.

Note

These are intended for studies with b2bii and for comparison between Belle and Belle II.

BelleACCQuality

[Legacy] Returns the ACC quality flag. Original definition in the panther tables: if 0 normal, if 1 the track is out of ACC acceptance. (Belle only).

BelleACCnPe

[Legacy] Returns the number of photo-electrons associated to the track in the ACC. (Belle only).

BelleFirstCDCHitX

[Legacy] Returns x component of starting point of the track near the 1st SVD or CDC hit for SVD1 data (exp. 7 - 27) or the 1st CDC hit for SVD2 data (from exp. 31). (Belle only, originally stored in mdst_trk_fit.)

Unit:

cm

BelleFirstCDCHitY

[Legacy] Returns y component of starting point of the track near the 1st SVD or CDC hit for SVD1 data (exp. 7 - 27) or the 1st CDC hit for SVD2 data (from exp. 31). (Belle only, originally stored in mdst_trk_fit.)

Unit:

cm

BelleFirstCDCHitZ

[Legacy] Returns z component of starting point of the track near the 1st SVD or CDC hit for SVD1 data (exp. 7 - 27) or the 1st CDC hit for SVD2 data (from exp. 31). (Belle only, originally stored in mdst_trk_fit.)

Unit:

cm

BelleLastCDCHitX

[Legacy] Returns x component of end point of the track near the last CDC hit. (Belle only, originally stored in mdst_trk_fit.)

Unit:

cm

BelleLastCDCHitY

[Legacy] Returns y component of end point of the track near the last CDC hit. (Belle only, originally stored in mdst_trk_fit.)

Unit:

cm

BelleLastCDCHitZ

[Legacy] Returns z component of end point of the track near the last CDC hit. (Belle only, originally stored in mdst_trk_fit.)

Unit:

cm

BellePathLength

[Legacy] Returns the track path length. This is defined from the closest point to the z-axis up to TOF counter. (Belle only).

Unit:

cm

BellePi0SigM

[Legacy] Returns the significance of the \(\pi^0\) mass used in the FEI for B2BII. The significance is calculated as the difference between the reconstructed and the nominal mass divided by the mass uncertainty:

\[\frac{m_{\gamma\gamma} - m_{\pi^0}^\textrm{PDG}}{\sigma_{m_{\gamma\gamma}}}\]

Since the \(\pi^0\)’s covariance matrix for B2BII is empty, the latter is calculated using the photon daughters’ covariance matrices.

BelleTof

[Legacy] Returns the time of flight of a track. (Belle only).

Unit:

ns

BelleTofMass

[Legacy] Returns the TOF mass calculated from the time of flight and path length. (Belle only). :Unit: GeV/\(\text{c}^2\)

BelleTofQuality

[Legacy] Returns the quality flag of the time of flight of a track. Original description from the panther table: 0 if consistency between z of hit by charge Q and corrected times, 1 if zhit from Q NOT consistent with zhit from and correct times. (Belle only).

BelleTofSigma

[Legacy] Returns the expected resolution on the time of flight of a track. (Belle only).

Unit:

ns

BelledEdx

[Legacy] Returns the dE/dx measured in the CDC. (Belle only).

Unit:

keV/cm

BelledEdxQuality

[Legacy] Returns the quality flag of the dE/dx measured in the CDC. Sadly no information about the code meaning is given in the original panther tables. (Belle only).

clusterBelleQuality

[Legacy] Returns ECL cluster’s quality indicating a good cluster in GSIM (stored in deltaL of ECL cluster object). Belle analysis typically used clusters with quality == 0 in their \(E_{\text{extra ECL}}\) (Belle only).

goodBelleGamma

[Legacy] Returns 1.0 if the photon candidate passes the simple region dependent energy selection for Belle data and MC.

\[\begin{split}E > 50 \textrm{ MeV; barrel}\\ E > 100 \textrm{ MeV; forward endcap}\\ E > 150 \textrm{ MeV; backward endcap}\end{split}\]

goodBelleKshort

[Legacy] GoodKs Returns true if a \(K_{S}^0\to\pi\pi\) candidate passes the Belle algorithm: a momentum-binned selection including requirements on impact parameter of, and angle between the daughter pions as well as separation from the vertex and flight distance in the transverse plane.

See also

BELLE2-NOTE-PH-2018-017

goodBelleLambda

[Legacy] Returns 2.0, 1.0, 0.0 as an indication of goodness of \(\Lambda^0\) candidates, based on:

• The distance of the two daughter tracks at their interception at z axis,

• the minimum distance of the daughter tracks and the IP in xy plane,

• the difference of the azimuthal angle of the vertex vector and the momentum vector,

• and the flight distance of the Lambda0 candidates in xy plane.

It reproduces the goodLambda() function in Belle.

goodBelleLambda selection 1 (selected with: goodBelleLambda>0) maximizes the signal significance after applying atcPIDBelle(4,2) > 0.6, while goodBelleLambda selection 2 (goodBelleLambda>1) is tighter and maximizes the signal significance of a \(\Lambda^0\) sample without any proton PID cut. However, it might still be beneficial to apply a proton PID cut on top of it. Which combination of proton PID cut and goodBelleLambda selection scenario is ideal, is probably analysis-dependent.

Warning

goodBelleLambda is not optimized or tested on Belle II data.

See also

• BN-684 Lambda selection at Belle. K F Chen et al.

• The FindLambda class can be found at /belle_legacy/findLambda/findLambda.h

PID for B2BII

Warning

These variables are to be used only when analysing converted Belle samples.

atcPIDBelle(i, j)

[Legacy] Returns Belle’s PID atc variable: atc_pid(3,1,5,i,j).prob(). Parameters i,j are signal and background hypothesis: (0 = electron, 1 = muon, 2 = pion, 3 = kaon, 4 = proton) Returns 0.5 in case there is no likelihood found and a factor of 0.5 will appear in the product if any of the subdetectors don’t report a likelihood (Belle behaviour).

Warning

The behaviour is different from Belle II PID variables which typically return NaN in case of error.

eIDBelle

[Legacy] Returns Belle’s electron ID eid(3,-1,5).prob() variable. Returns 0.5 in case there is no likelihood found (Belle behaviour).

Warning

The behaviour is different from Belle II PID variables which typically return NaN in case of error.

muIDBelle

[Legacy] Returns Belle’s PID Muon_likelihood() variable. Returns 0.5 in case there is no likelihood found and returns zero if the muon likelihood is not usable (Belle behaviour).

Warning

The behaviour is different from Belle II PID variables which typically return NaN in case of error.

muIDBelleQuality

[Legacy] Returns true if Belle’s PID Muon_likelihood() is usable (reliable). Returns zero/false if not usable or if there is no PID found.

Miscellaneous

Other variable that can be handy in development:

False

returns always 0, used for testing and debugging.

True

returns always 1, used for testing and debugging.

decayTypeRecoil

type of the particle decay(no related mcparticle = -1, hadronic = 0, direct leptonic = 1, direct semileptonic = 2,lower level leptonic = 3.

eventRandom

[Eventbased] Returns a random number between 0 and 1 for this event. Can be used, e.g. for applying an event prescale.

infinity

returns std::numeric_limits<double>::infinity()

mcMomTransfer2

Return the true momentum transfer to lepton pair in a B(semi -) leptonic B meson decay.

Unit:

GeV/c

minET2ETDist(detName, detLayer, referenceListName, useHighestProbMassForExt=1)

Returns the distance \(d_{\mathrm{i}}\) in [cm] between the particle and the nearest particle in the reference list at the given detector \(i\)-th layer surface. The definition is based on the track helices extrapolation.

• The first argument is the name of the detector to consider.

• The second argument is the detector layer on whose surface we search for the nearest neighbour.

• The third argument is the reference particle list name used to search for the nearest neighbour.

• The fourth (optional) argument is an integer (“boolean”) flag: if 1 (the default, if nothing is set), it is assumed the extrapolation was done with the most probable mass hypothesis for the track fit; if 0, it is assumed the mass hypothesis matching the particle lists’ PDG was used.

Note

This variable requires to run the TrackIsoCalculator module first. Note that the choice of input parameters of this metafunction must correspond to the settings used to configure the module!

minET2ETDistVar(detName, detLayer, referenceListName, variableName)

Returns the value of the variable for the nearest neighbour to this particle as taken from the reference list at the given detector \(i\)-th layer surface , according to the distance definition of minET2ETDist.

• The first argument is the name of the detector to consider.

• The second argument is the detector layer on whose surface we search for the nearest neighbour.

• The third argument is the reference particle list name used to search for the nearest neighbour.

• The fourth argument is a variable name, e.g. nCDCHits.

Note

This variable requires to run the TrackIsoCalculator module first. Note that the choice of input parameters of this metafunction must correspond to the settings used to configure the module!

minET2ETIsoScore(referenceListName, useHighestProbMassForExt, detectorList)

Returns a particle’s isolation score \(s\) defined as:

\begin{split} s &= \sum_{\mathrm{det}} 1 - \left(-w_{\mathrm{det}} \cdot \frac{\sum_{i}^{N_{\mathrm{det}}^{\mathrm{layers}}} H(i)}{N_{\mathrm{det}}^{\mathrm{layers}}}\right), \\ H(i) &= \begin{cases} 0 & d_{\mathrm{i}} > D_{\mathrm{det}}^{\mathrm{thresh}} \\ 1 & d_{\mathrm{i}} <= D_{\mathrm{det}}^{\mathrm{thresh}}, \\ \end{cases} \end{split}

where \(d_{\mathrm{i}}\) is the distance to the closest neighbour at the \(i\)-th layer of the given detector (c.f., minET2ETDist), \(N_{\mathrm{det}}^{\mathrm{layers}}\) is the number of layers of the detector, \(D_{\mathrm{det}}^{\mathrm{thresh}}\) is a threshold length related to the detector’s granularity defined in the TrackIsoCalculator module, and \(w_{\mathrm{det}}\) are (negative) weights associated to the detector’s impact on PID for this particle type, read from a CDB payload.

The score is normalised in [0, 1], where values closer to 1 indicates a well-isolated particle.

• The first argument is the reference particle list name used to search for the nearest neighbour.

• The second argument is an integer (“boolean”) flag: if 1, it is assumed the extrapolation was done with the most probable mass hypothesis for the track fit; if 0, it is assumed the mass hypothesis matching the particle lists’ PDG was used.

• The remaining arguments are a comma-separated list of detector names, which must correspond to the one given to the TrackIsoCalculator module.

Note

The PID detector weights \(w_{\mathrm{det}}\) are non-trivial only if excludePIDDetWeights=false in the TrackIsoCalculator module configuration. Otherwise \(w_{\mathrm{det}} = -1\).

Note

This variable requires to run the TrackIsoCalculator module first. Note that the choice of input parameters of this metafunction must correspond to the settings used to configure the module!

minET2ETIsoScoreAsWeightedAvg(referenceListName, useHighestProbMassForExt, detectorList)

Returns a particle’s isolation score \(s\) based on the weighted average:

\[s = 1 - \frac{\sum_{\mathrm{det}} \sum_{i}^{N_{\mathrm{det}}^{\mathrm{layers}}} w_{\mathrm{det}} \cdot \frac{D_{\mathrm{det}}^{\mathrm{thresh}}}{d_{\mathrm{i}}} }{ \sum_{\mathrm{det}} w_{\mathrm{det}}},\]

where \(d_{\mathrm{i}}\) is the distance to the closest neighbour at the \(i\)-th layer of the given detector (c.f., minET2ETDist), \(N_{\mathrm{det}}^{\mathrm{layers}}\) is the number of layers of the detector, \(D_{\mathrm{det}}^{\mathrm{thresh}}\) is a threshold length related to the detector’s granularity defined in the TrackIsoCalculator module, and \(w_{\mathrm{det}}\) are (negative) weights associated to the detector’s impact on PID for this particle type, read from a CDB payload.

The score is normalised in [0, 1], where values closer to 1 indicates a well-isolated particle.

• The first argument is the reference particle list name used to search for the nearest neighbour.

• The second argument is an integer (“boolean”) flag: if 1, it is assumed the extrapolation was done with the most probable mass hypothesis for the track fit; if 0, it is assumed the mass hypothesis matching the particle lists’ PDG was used.

• The remaining arguments are a comma-separated list of detector names, which must correspond to the one given to the TrackIsoCalculator module.

Note

The PID detector weights \(w_{\mathrm{det}}\) are non-trivial only if excludePIDDetWeights=false in the TrackIsoCalculator module configuration. Otherwise \(\lvert w_{\mathrm{det}} \rvert = 1\).

Note

This variable requires to run the TrackIsoCalculator module first. Note that the choice of input parameters of this metafunction must correspond to the settings used to configure the module!

nRemainingTracksInEvent

Number of tracks in the event - Number of tracks( = charged FSPs) of particle.

printParticle

For debugging, print Particle and daughter PDG codes, plus MC match. Returns 0.

random

return a random number between 0 and 1 for each candidate. Can be used, e.g. for picking a randomcandidate in the best candidate selection.

trackMatchType

• -1 particle has no ECL cluster

• 0 particle has no associated track

• 1 there is a matched track called connected - region(CR) track match

Warning

Deprecated since version light-2012-minos.

Use better variables like trackNECLClusters, clusterTrackMatch, and nECLClusterTrackMatches.

FEI Variables

As known by many analysts by using the isSignal flag for truth matching for the tagging B meson from the FEI there is still a peak visible for the background in e.g. the \(M_{\text{bc}}\) distribution making it hard to determine e.g. a yield there.

New variables seem to be found to address this problem.

mostcommonBTagIndex

By giving e.g. a FEI B meson candidate the B meson index on generator level is determined, where most reconstructed particles can be assigned to. If no B meson found on generator level -1 is returned.

percentageMissingParticlesBTag

Get the percentage of missing particles by using the mostcommonBTagIndex. So the number of particles not reconstructed by e.g. the FEI are determined and divided by the number of generated particles using the given index of the B meson. If no B meson found on generator level -1 is returned.

percentageWrongParticlesBTag

Get the percentage of wrong particles by using the mostcommonBTagIndex. In this context wrong means that the reconstructed particles originated from the other B meson. The absolute number is divided by the total number of generated FSP from the given B meson index. If no B meson found on generator level -1 is returned.

Beam Background Overlay

Here is a list of variables useful for studying the Beam Background Overlay events used for producing MC samples (both run-independent and run-dependent).

Warning

These variables will always return NaN when running on data.

beamBackgroundEvents

[Eventbased] Total number of the background overlay events used for producing the file.

beamBackgroundReuseRate

[Eventbased] Reuse rate of the background overlay events used for producing the file.

Calibration

There are several variables also available for calibration experts who are working on cdst format files.

Warning

Many of these will not work for- and should not be used by- normal analyses.

They have a [Calibration] pretag.

eventT0

[Eventbased][Calibration] The Event t0, is the time of the event relative to the trigger time.

Note

The event time can be measured by several sub-detectors including the SVD, CDC, ECL, and TOP. This eventT0 variable is the final combined value of all the event time measurements. Currently, only the SVD and ECL are used in this combination.

Unit:

ns

7.3.3. Collections and Lists

To avoid very long lists of variable names in variablesToNtuple, it is possible to use collections of variables or lists of variables instead.

Lists of variables are just python lists of variables names. One can use the list in the steering file as follows:

# Defining the list
my_list = ['p','E']

# Passing it as an argument to variablesToNtuple
modularAnalysis.variablesToNtuple(variables=my_list, ...)

It is also possible to create user-defined variable collections. The name of the variable collection can be treated as a variable name.

variables.utils.add_collection(list_of_variables: Iterable[str], collection_name: str) → str

The function creates variable collection from the given list of variables It wraps the VariableManager.addCollection method which is not particularly user-friendly.

Example

Defining the collection >>> variables.utils.add_collection([‘p’,’E’], “my_collection”)

Passing it as an argument to variablesToNtuple >>> modularAnalysis.variablesToNtuple(variables=[‘my_collection’], …)

Parameters:

• list_of_variables (list(str)) – list of variable names

• collection_name (str) – name of the collection

Returns:

name of the variable collection

Return type:

str

Predefined collections

We provide several predefined lists of variables. For each predefined list, there is a collection with the same name:

variables.collections.belle_track_hit = ['BelleFirstCDCHitX', 'BelleFirstCDCHitY', 'BelleFirstCDCHitZ', 'BelleLastCDCHitX', 'BelleLastCDCHitY', 'BelleLastCDCHitZ']

Belle Track CDC hit variables

variables.collections.cluster = ['clusterKlId', 'clusterPulseShapeDiscriminationMVA', 'clusterHasPulseShapeDiscrimination', 'clusterNumberOfHadronDigits', 'clusterDeltaLTemp', 'minC2TDist', 'nECLClusterTrackMatches', 'clusterZernikeMVA', 'clusterReg', 'clusterAbsZernikeMoment40', 'clusterAbsZernikeMoment51', 'clusterBelleQuality', 'clusterClusterID', 'clusterConnectedRegionID', 'clusterE1E9', 'clusterE9E21', 'clusterE9E25', 'clusterEoP', 'clusterErrorE', 'clusterErrorPhi', 'clusterErrorTheta', 'clusterErrorTiming', 'clusterHighestE', 'clusterHasFailedErrorTiming', 'clusterHasFailedTiming', 'clusterHasNPhotons', 'clusterHasNeutralHadron', 'clusterLAT', 'clusterNHits', 'clusterPhi', 'clusterR', 'clusterSecondMoment', 'clusterTheta', 'clusterTiming', 'clusterTrackMatch', 'goodBelleGamma']

Cluster-related variables

variables.collections.cluster_average = ['maxWeightedDistanceFromAverageECLTime', 'weightedAverageECLTime']

Cluster averages

variables.collections.dalitz_3body = ['daughterInvM(0, 1)', 'daughterInvM(0, 2)', 'daughterInvM(1, 2)']

Dalitz masses for three body decays

variables.collections.deltae_mbc = ['Mbc', 'deltaE']

Replacement for DeltaEMbc

variables.collections.event_kinematics = ['missingMomentumOfEvent', 'missingMomentumOfEvent_Px', 'missingMomentumOfEvent_Py', 'missingMomentumOfEvent_Pz', 'missingMomentumOfEvent_theta', 'missingMomentumOfEventCMS', 'missingMomentumOfEventCMS_Px', 'missingMomentumOfEventCMS_Py', 'missingMomentumOfEventCMS_Pz', 'missingMomentumOfEventCMS_theta', 'missingEnergyOfEventCMS', 'missingMass2OfEvent', 'visibleEnergyOfEventCMS', 'totalPhotonsEnergyOfEvent']

Variables created by event kinematics module

variables.collections.event_level_cluster = ['nECLOutOfTimeCrystals', 'nECLOutOfTimeCrystalsBWDEndcap', 'nECLOutOfTimeCrystalsBarrel', 'nECLOutOfTimeCrystalsFWDEndcap', 'nRejectedECLShowers', 'nRejectedECLShowersBWDEndcap', 'nRejectedECLShowersBarrel', 'nRejectedECLShowersFWDEndcap', 'nKLMMultistripHits', 'nKLMMultistripHitsBWDEndcap', 'nKLMMultistripHitsBarrel', 'nKLMMultistripHitsFWDEndcap', 'nECLShowers', 'nECLShowersBWDEndcap', 'nECLShowersBarrel', 'nECLShowersFWDEndcap', 'nECLLocalMaximums', 'nECLLocalMaximumsBWDEndcap', 'nECLLocalMaximumsBarrel', 'nECLLocalMaximumsFWDEndcap', 'nECLTriggerCells', 'nECLTriggerCellsBWDEndcap', 'nECLTriggerCellsBarrel', 'nECLTriggerCellsFWDEndcap']

Cluster-related event variables

variables.collections.event_level_tracking = ['nExtraCDCHits', 'nExtraCDCHitsPostCleaning', 'hasExtraCDCHitsInLayer(0)', 'hasExtraCDCHitsInLayer(1)', 'hasExtraCDCHitsInLayer(2)', 'hasExtraCDCHitsInLayer(3)', 'hasExtraCDCHitsInLayer(4)', 'hasExtraCDCHitsInLayer(5)', 'hasExtraCDCHitsInLayer(6)', 'hasExtraCDCHitsInLayer(7)', 'nExtraCDCSegments', 'trackFindingFailureFlag']

Event level tracking variables

variables.collections.event_shape = ['foxWolframR1', 'foxWolframR2', 'foxWolframR3', 'foxWolframR4', 'harmonicMomentThrust0', 'harmonicMomentThrust1', 'harmonicMomentThrust2', 'harmonicMomentThrust3', 'harmonicMomentThrust4', 'cleoConeThrust0', 'cleoConeThrust1', 'cleoConeThrust2', 'cleoConeThrust3', 'cleoConeThrust4', 'cleoConeThrust5', 'cleoConeThrust6', 'cleoConeThrust7', 'cleoConeThrust8', 'sphericity', 'aplanarity', 'thrust', 'thrustAxisCosTheta']

Event shape variables

variables.collections.extra_energy = ['roeEextra()']

Extra energy variables

variables.collections.flight_info = ['flightTime', 'flightDistance', 'flightTimeErr', 'flightDistanceErr']

Flight info variables

variables.collections.inv_mass = ['M', 'ErrM', 'SigM', 'InvM']

Replacement for InvMass tool

variables.collections.kinematics = ['px', 'py', 'pz', 'pt', 'p', 'E']

Replacement to Kinematics tool

variables.collections.klm_cluster = ['klmClusterKlId', 'klmClusterTiming', 'klmClusterPositionX', 'klmClusterPositionY', 'klmClusterPositionZ', 'klmClusterInnermostLayer', 'klmClusterLayers', 'klmClusterEnergy', 'klmClusterMomentum', 'klmClusterIsBKLM', 'klmClusterIsEKLM', 'klmClusterIsForwardEKLM', 'klmClusterIsBackwardEKLM', 'klmClusterTheta', 'klmClusterPhi', 'nKLMClusterTrackMatches', 'nMatchedKLMClusters']

KLM cluster information

variables.collections.mc_event_kinematics = ['genMissingMass2OfEvent', 'genMissingEnergyOfEventCMS', 'genMissingMomentumOfEventCMS', 'genTotalPhotonsEnergyOfEvent', 'genVisibleEnergyOfEventCMS']

Variables created by MC version of event kinematics module

variables.collections.mc_flight_info = ['mcFlightTime', 'mcFlightDistance']

MC true flight info variables

variables.collections.mc_kinematics = ['mcE', 'mcP', 'mcPT', 'mcPX', 'mcPY', 'mcPZ', 'mcPhi']

Replacement for MCKinematics tool

variables.collections.mc_tag_vertex = ['mcDeltaTau', 'mcDeltaT', 'mcDeltaBoost', 'mcTagVLBoost', 'mcTagVOBoost', 'mcLBoost', 'mcOBoost', 'mcTagVx', 'mcTagVy', 'mcTagVz']

Tag-side related MC true variables

variables.collections.mc_truth = ['isSignal', 'mcErrors', 'mcPDG']

Replacement for MCTruth tool

variables.collections.mc_variables = ['genMotherID', 'genMotherP', 'genMotherPDG', 'genParticleID', 'isCloneTrack', 'mcDecayVertexX', 'mcDecayVertexY', 'mcDecayVertexZ', 'mcDecayTime', 'mcE', 'mcErrors', 'mcInitial', 'mcP', 'mcPDG', 'mcPT', 'mcPX', 'mcPY', 'mcPZ', 'mcPhi', 'mcVirtual', 'nMCMatches']

Truth-matching related variables

variables.collections.mc_vertex = ['mcDecayVertexX', 'mcDecayVertexY', 'mcDecayVertexZ', 'mcDecayVertexFromIPDistance', 'mcDecayVertexRho', 'mcProductionVertexX', 'mcProductionVertexY', 'mcProductionVertexZ']

Replacement for MCVertex tuple tool

variables.collections.momentum_uncertainty = ['E_uncertainty', 'pxErr', 'pyErr', 'pzErr']

Replacement for MomentumUnertainty tool

variables.collections.pid = ['electronID', 'muonID', 'pionID', 'kaonID', 'protonID', 'deuteronID', 'binaryPID(11, 211)', 'binaryPID(13, 211)', 'binaryPID(211, 321)', 'binaryPID(321, 2212)', 'binaryPID(211, 2212)']

PID variables

variables.collections.reco_stats = ['nTracks']

Replacement for RecoStats tool

variables.collections.recoil_kinematics = ['pRecoil', 'eRecoil', 'mRecoil', 'pRecoilPhi', 'pRecoilTheta', 'pxRecoil', 'pyRecoil', 'pzRecoil']

Recoil kinematics related variables

variables.collections.roe_kinematics = ['roeE()', 'roeM()', 'roeP()', 'roeMbc()', 'roeDeltae()']

Rest-Of-Event kinematics

variables.collections.roe_multiplicities = ['nROE_Charged()', 'nROE_Photons()', 'nROE_NeutralHadrons()']

Replacement for ROEMultiplicities tool

variables.collections.tag_vertex = ['DeltaT', 'DeltaTErr', 'DeltaZ', 'DeltaZErr', 'DeltaBoost', 'DeltaBoostErr', 'TagVLBoost', 'TagVLBoostErr', 'TagVOBoost', 'TagVOBoostErr', 'TagVpVal', 'TagVNDF', 'TagVChi2', 'TagVChi2IP', 'TagVx', 'TagVxErr', 'TagVy', 'TagVyErr', 'TagVz', 'TagVzErr']

CPV and Tag-side related variables

variables.collections.track = ['dr', 'dx', 'dy', 'dz', 'd0', 'z0', 'pValue', 'ndf']

Tracking variables, replacement for Track tool

variables.collections.track_hits = ['nCDCHits', 'nPXDHits', 'nSVDHits', 'nVXDHits']

Replacement for TrackHits tool

variables.collections.trackfit_parameters = ['omega', 'omegaErr', 'tanLambda', 'tanLambdaErr', 'd0', 'd0Err', 'z0', 'z0Err', 'phi0', 'phi0Err', 'pValue', 'ndf']

Track fit parameters

variables.collections.vertex = ['distance', 'significanceOfDistance', 'dx', 'dy', 'dz', 'x', 'y', 'z', 'x_uncertainty', 'y_uncertainty', 'z_uncertainty', 'dr', 'dphi', 'dcosTheta', 'prodVertexX', 'prodVertexY', 'prodVertexZ', 'prodVertexXErr', 'prodVertexYErr', 'prodVertexZErr', 'chiProb']

Replacement for Vertex tuple tool

7.3.4. Operations with variable lists

It is possible to create new variable lists using meta-variables. For example, one can define list of kinematic variables in LAB frame and create another lists of kinematic variables in CMS using useCMSFrame(variable) meta-variable:

from variables.utils import create_aliases
# Replacement to Kinematics tool
kinematics = ['px', 'py', 'pz', 'pt', 'p', 'E']

# Kinematic variables in CMS
cms_kinematics = create_aliases(kinematics, "useCMSFrame({variable})", "CMS")

Now we can use the list of aliases cms_kinematics and add them to the output in one go or modify them further. The following functions are provided to help to easily create aliases.

variables.utils.create_aliases(list_of_variables: Iterable[str], wrapper: str, prefix='') → List[str]

The function creates aliases for variables from the variables list with given wrapper and returns list of the aliases.

If the variables in the list have arguments (like useLabFrame(p)) all non-alphanumeric characters in the variable will be replaced by underscores (for example useLabFrame_x) for the alias name.

>>> list_of_variables = ['M','p','matchedMC(useLabFrame(px))']
>>> wrapper = 'daughter(1,{variable})'
>>> prefix = 'pref'
>>> print(create_aliases(list_of_variables, wrapper, prefix))
['pref_M', 'pref_p', 'pref_matchedMC_useLabFrame_px']
>>> from variables import variables
>>> variables.printAliases()
[INFO] =====================================
[INFO] The following aliases are registered:
[INFO] pref_M                        --> daughter(1,M)
[INFO] pref_matchedMC_useLabFrame_px --> daughter(1,matchedMC(useLabFrame(px)))
[INFO] pref_p                        --> daughter(1,p)
[INFO] =====================================

Parameters:

• list_of_variables (list(str)) – list of variable names

• wrapper (str) – metafunction taking variables from list_of_variables as a parameter (<metafunction>(<some configs>, {variable} ,<some other configs>)

• prefix (str) – alias prefix used for wrapped variables.

Returns:

new variables list

Return type:

list(str)

variables.utils.create_aliases_for_selected(list_of_variables: List[str], decay_string: str, prefix: str | List[str] | None = None, *, use_names=True, always_include_indices=False, use_relative_indices=False) → List[str]

The function creates list of aliases for given variables so that they are calculated for particles selected in decay string. That is for each particle selected in the decay string an alias is created to calculate each variable in the list_of_variables.

If use_names=True (the default) then the names of the aliases are assigned as follows:

• If names are unambiguous, it’s semi-laconic DecayString style: The aliases will be prefixed with the names of all parent particle names separated by underscore. For example given the decay string B0 -> [D0 -> ^pi+ K-] pi0 the aliases for the pi+` will start with ``D0_pi_ followed by the variable name.

  >>> list_of_variables = ['M','p']
  >>> decay_string = 'B0 -> [D0 -> ^pi+ K-] pi0'
  >>> create_aliases_for_selected(list_of_variables, decay_string)
  ['D0_pi_M', 'D0_pi_p']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'D0_pi_M' --> 'daughter(0,daughter(0,M))'
  [INFO] 'D0_pi_p' --> 'daughter(0,daughter(0,p))'
  [INFO] =========================
  

• If names are ambiguous because there are multiple daughters with the same name these particles will be followed by their daughter index. For example given the decay string B0 -> [D0 -> ^pi+:1 ^pi-:2 ^pi0:3 ] ^pi0:4 will create aliases with the following prefixes for particle with the corresponding number as list name:

  1. D0_pi_0_

  2. D0_pi_1_

  3. D0_pi0_

  4. pi0_

  >>> list_of_variables = ['M','p']
  >>> decay_string = 'B0 -> [D0 -> ^pi+ ^pi- ^pi0] ^pi0'
  >>> create_aliases_for_selected(list_of_variables, decay_string)
  ['D0_pi_0_M', 'D0_pi_0_p', 'D0_pi_1_M', 'D0_pi_1_p',
  'D0_pi0_M', 'D0_pi0_p', 'pi0_M', 'pi0_p']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'D0_pi0_M' --> 'daughter(0,daughter(2,M))'
  [INFO] 'D0_pi0_p' --> 'daughter(0,daughter(2,p))'
  [INFO] 'D0_pi_0_M' --> 'daughter(0,daughter(0,M))'
  [INFO] 'D0_pi_0_p' --> 'daughter(0,daughter(0,p))'
  [INFO] 'D0_pi_1_M' --> 'daughter(0,daughter(1,M))'
  [INFO] 'D0_pi_1_p' --> 'daughter(0,daughter(1,p))'
  [INFO] 'D0_pi_M' --> 'daughter(0,daughter(0,M))'
  [INFO] 'D0_pi_p' --> 'daughter(0,daughter(0,p))'
  [INFO] 'pi0_M' --> 'daughter(1,M)'
  [INFO] 'pi0_p' --> 'daughter(1,p)'
  [INFO] =========================
  

• The user can select to always include the index even for unambiguous particles by passing always_include_indices=True

• The user can choose two different numbering schemes: If use_relative_indices=False the original decay string indices will be used if a index is added to a particle name.

  But if use_relative_indices=True the indices will just start at zero for each particle which is part of the prefixes. For example for B0-> e+ ^e-

  >>> create_aliases_for_selected(['M'], 'B0-> mu+ e- ^e+ ^e-', use_relative_indices=False)
  ['e_2_M', 'e_3_M']
  >>> create_aliases_for_selected(['M'], 'B0-> mu+ e- ^e+ ^e-', use_relative_indices=True)
  ['e_0_M', 'e_1_M']
  

If use_names=False the aliases will just start with the daughter indices of all parent particles prefixed with a d and separated by underscore. So for the previous example B0 -> [D0 -> ^pi+:1 ^pi-:2 ^pi0:3 ] ^pi0:4 this would result in aliases starting with

1. d0_d0_

2. d0_d1_

3. d0_d2_

4. d1_

In this case the always_include_indices and use_relative_indices arguments are ignored.

The naming can be modified by providing a custom prefix for each selected particle. In this case the parameter prefix needs to be either a simple string if only one particle is selected or a list of strings with one prefix for each selected particle.

>>> list_of_variables = ['M','p']
>>> decay_string = 'B0 -> [D0 -> ^pi+ ^pi- pi0] pi0'
>>> create_aliases_for_selected(list_of_variables, decay_string, prefix=['pip', 'pim'])
['pip_M', 'pip_p', 'pim_M', 'pim_p']
>>> from variables import variables
>>> variables.printAliases()
[INFO] =========================
[INFO] Following aliases exists:
[INFO] 'pim_M' --> 'daughter(0,daughter(1,M))'
[INFO] 'pim_p' --> 'daughter(0,daughter(1,p))'
[INFO] 'pip_M' --> 'daughter(0,daughter(0,M))'
[INFO] 'pip_p' --> 'daughter(0,daughter(0,p))'
[INFO] =========================

If the mother particle itself is selected the input list of variables will also be added to the returned list of created aliases. If custom prefixes are supplied then aliases will be created for the mother particle as well:

>>> create_aliases_for_selected(['M', 'p'], '^B0 -> pi+ ^pi-')
['M', 'p', 'pi_M', 'pi_p']
>>> create_aliases_for_selected(['M', 'p'], '^B0 -> pi+ ^pi-', prefix=['MyB', 'MyPi'])
['MyB_M', 'MyB_p', 'MyPi_M', 'MyPi_p']

Parameters:

• list_of_variables (list(str)) – list of variable names

• decay_string (str) – Decay string with selected particles

• prefix (str, list(str)) – Custom prefix for all selected particles

• use_names (bool) – Include the names of the particles in the aliases

• always_include_indices (bool) – If use_names=True include the decay index of the particles in the alias name even if the particle could be uniquely identified without them.

• use_relative_indices (bool) – If use_names=True use a relative indicing which always starts at 0 for each particle appearing in the alias names independent of the absolute position in the decay string

Returns:

new variables list

Return type:

list(str)

variables.utils.create_daughter_aliases(list_of_variables: Iterable[str], indices: int | Iterable[int], prefix='', include_indices=True) → List[str]

Create Aliases for all variables for a given daughter hierarchy

Parameters:

• list_of_variables (list(str)) – list of variables to create aliases for

• indices (int or list(int)) – index of the daughter, grand-daughter, grand-grand-daughter, and so forth

• prefix (str) – optional prefix to prepend to the aliases

• include_indices (bool) – if set to True (default) the aliases will contain the daughter indices as dX_dY_dZ…

Returns:

new variables list

Return type:

list(str)

• create aliases for the second daughter as “d1_E”, “d1_M” (daughters start at 0)

  >>> create_daughter_aliases(["E", "m"], 1)
  ['d1_E', 'd1_m']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'd1_E' --> 'daughter(1,E)'
  [INFO] 'd1_m' --> 'daughter(1,m)'
  [INFO] =========================
  

• create aliases for the first grand daughter of the second daughter, starting with “my” and without including the indices, resulting in “my_E”, “my_m”

  >>> create_daughter_aliases(["E", "m"], [1, 0], prefix="my", include_indices=False)
  ['my_E', 'my_m']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'my_E' --> 'daughter(1,daughter(0,E))'
  [INFO] 'my_m' --> 'daughter(1,daughter(0,m))'
  [INFO] =========================
  

• create aliases for the second grand grand daughter of the third grand daughter of the fifth daughter, starting with my and including the indices, resulting in “my_d4_d2_d1_E”, “my_d4_d2_d1_m”

  >>> create_daughter_aliases(["E", "m"], [4, 2, 1], prefix="my")
  ['my_d4_d2_d1_E', 'my_d4_d2_d1_m']
  >>> from variables import variables
  >>> variables.printAliases()
  [INFO] =========================
  [INFO] Following aliases exists:
  [INFO] 'my_d4_d2_d1_E' --> 'daughter(4,daughter(2,daughter(1,E))'
  [INFO] 'my_d4_d2_d1_m' --> 'daughter(4,daughter(2,daughter(1,m))'
  [INFO] =========================
  

variables.utils.create_mctruth_aliases(list_of_variables: Iterable[str], prefix='mc') → List[str]

The function wraps variables from the list with ‘matchedMC()’.

>>> list_of_variables = ['M','p']
>>> create_mctruth_aliases(list_of_variables)
['mc_M', 'mc_p']
>>> from variables import variables
>>> variables.printAliases()
[INFO] =========================
[INFO] Following aliases exists:
[INFO] 'mc_M' --> 'matchedMC(M)'
[INFO] 'mc_p' --> 'matchedMC(p)'
[INFO] =========================

Parameters:

list_of_variables (list(str)) – list of variable names

Returns:

list of created aliases

Return type:

list(str)

variables.utils.create_isSignal_alias(aliasName, flags)

Make a VariableManager alias for a customized isSignal, which accepts specified mc match errors.

See also

see Truth-matching for a definition of the mc match error flags.

The following code defines a new variable isSignalAcceptMissingGammaAndMissingNeutrino, which is same as isSignal, but also accepts missing gamma and missing neutrino

>>> create_isSignal_alias("isSignalAcceptMissingGammaAndMissingNeutrino", [16, 8])

Logically, this isSignalAcceptMissingGammaAndMissingNeutrino = isSignalAcceptMissingGamma || isSignalAcceptMissingNeutrino.

In the example above, create_isSignal_alias() creates isSignalAcceptMissingGammaAndMissingNeutrino by unmasking (setting bits to zero) the c_MissGamma bit (16 or 0b00010000) and c_MissNeutrino bit (8 or 0b00001000) in mcErrors.

For more information, please check this example script.

Parameters:

• aliasName (str) – the name of the alias to be set

• flags (list(int)) – a list of the bits to unmask

7.3.5. Miscellaneous helpers for using variables

variables.getAllTrgNames()

Return all PSNM trigger bit names

variables.std_vector(*args)

Creates an std::vector which can be passed to pyROOT

variables.printVars(changedVariableNames=None, listVars=None)

Print list of all available variables.

7.3.6. Writing your own variable

The code of VariableManager lives inside the analysis package. If you want to write your own variables you have a couple of options. You can (and should) try to make your variables general, so that they are useful for many collaborators. In this case, we recommend you make a merge request. Then your variables will be made available in a central release to many people.

In case you have something really analysis-specific that no one else will need. You can still use the VariableManager.

Below are step-by-step instructions for implementation of helicity angle for arbitrary granddaughter particle.

Step 1. Check whether your function would fit in any of the existing source files

If yes, go to the next step.

If not, create new header/source files. In case of our example, we will create AngularVariables.h and AngularVariables.cc

AngularVariables.h in analysis/VariableManager/include/:

#pragma once
// include VariableManager
#include <analysis/VariableManager/Manager.h>

// include the Belle II Particle class
#include <analysis/dataobjects/Particle.h>

// put variable in the Belle2::Variable namespace
namespace Belle2 {
  namespace Variable {

    // Your code goes here

  } // Variable namespace
} // Belle2 namespace

AngularVariables.cc in analysis/VariableManager/src/:

// Own include
#include <analysis/VariableManager/AngularVariables.h>

// put variable in the Belle2::Variable namespace
namespace Belle2 {
  namespace Variable {

    // Your code goes here
  } // Variable namespace
} // Belle2 namespace

Step 2. Add function definition in the header file

Here we define a method helicityAngle that has 3 arguments:

• pointer to a Particle

• index of the daughter Particle

• index of the granddaughter (daughter’s daughter) Particle

in the AngularVariable.h header file. The return value of every variable has to be double.

/**
  * returns cosine of the helicity angle: angle between granddaughter and this particle in the daughter's rest frame.
  * The daughter and granddaughter particles are specified with the additional parameter.
  */
double helicityAngle(const Particle* particle, const std::vector<double>& daughter_indices);

Step 3. Implement the function in the source file

• Info on getters for the Particle class

• Info on getters for the LorentzVector class

• Pictorial definition of the helicity angle

double helicityAngle(const Particle* particle, const std::vector<double>& daughter_indices) {
  // for the calculation of the helicity angle we need particle (=particle in the argument)
  // its daughter and granddaughter. The particle is given as an argument, but the daughter
  // and granddaughter are specified as the indices in the vector (second argument)
  // daughter_indices[0] = index of the daughter
  // daughter_indices[1] = index of the granddaughter

  if (!particle)
    return std::numeric_limits<float>::quiet_NaN();
  int nDaughters = particle->getNDaughters();
  if(nDaughters < 2)
    return std::numeric_limits<float>::quiet_NaN();
  if (daughter_indices.size() != 2)
    return std::numeric_limits<float>::quiet_NaN();

  // get the daughter particle
  int daughterIndex = daughter_indices[0];
  const Particle *daughter = particle->getDaughter(daughterIndex);
  nDaughters = daughter->getNDaughters();
  if(nDaughters < 2)
    return std::numeric_limits<float>::quiet_NaN();

  // get the granddaughter
  int grandDaughterIndex = daughter_indices[1];
  const Particle *grandDaughter = daughter->getDaughter(grandDaughterIndex);

  // do the calculation
  PxPyPzEVector particle4Vector = particle->get4Vector();
  PxPyPzEVector daughter4Vector = daughter->get4Vector();
  PxPyPzEVector gDaughter4Vector = grandDaughter->get4Vector();
  Boost boost2daughter(daughter4Vector.BoostToCM());
  particle4Vector = boost2daughter * particle4Vector;
  gDaughter4Vector = boost2daughter * gDaughter4Vector;
  B2Vector3D particle3Vector = particle4Vector.Vect();
  B2Vector3D gDaughter3Vector = gDaughter4Vector.Vect();
  double numerator = gDaughter3Vector.Dot(particle3Vector);
  double denominator = (gDaughter3Vector.Mag())*(particle3Vector.Mag());
  return numerator/denominator;
}

Step 4. Register the new variable

At the end of the source file, add the following lines:

VARIABLE_GROUP("AngularVariables");
REGISTER_VARIABLE("helicityAngle(i,j)", helicityAngle,
                "cosine of the angle between particle->getDaughter(i)->getDaughter(j) and this particle in the  particle->getDaughter(i) rest frame.");

Step 5. Compile

Execute scons in your local release directory

Step 6. Done!

You can check if your variable is visible to VariableManager

>>> basf2 analysis/scripts/variables.py
AngularVariables: helicityAngle(i,j) cosine of the angle between particle->getDaughter(i)->getDaughter(j) and this particle in the particle->getDaughter(i) rest frame.

You can use your variable in the same way as you use standard variables.

How to use my variable at grid?

• Prepare the environment with the b2analysis-create tool.

>>> b2analysis-create myanalysis <current central release, e.g. release-04-00-00>
>>> cd myanalysis
>>> b2setup

• Define the new variables/functions in a .cc and register them with the variable manager. This means that in the new .cc you should add:

#include <framework/core/Module.h>
#include <analysis/VariableManager/Manager.h>
#include <analysis/dataobjects/Particle.h>
namespace Belle2 {
  namespace Variable {
      double myVarFunction(const Particle* particle) { **your code** }
      VARIABLE_GROUP("CUSTOM_VARIABLES");
      REGISTER_VARIABLE("myVar", myVarFunction, "My custom variable");
  }
  // Create an empty module which does nothing at all. What it does is allowing
  // basf2 to easily find the library and load it from the steering file
  class EnableMyVariableModule: public Module {}; // And register this module to create a .map lookup file.
  REG_MODULE(EnableMyVariable);
}

Then:

• Run scons and you will get a .so and a .b2modmap files in modules/Linux_x86_64/opt.

• Load the libraries and make the variables available you need to add these lines to your steering file:

import basf2
basf2.register_module("EnableMyVariable") # This is the relevant line: now you can use your variable
from variables import variables
print(variables.getVariable("myVar").description)

These lines will add the local directory to the module search path and instantiate the module we created. This is enough to load the library and register the variables. Now you should be able to use your custom variables for your analysis and there is no need to add this module to the path, it just needs to be registered to load the library.

In the end you can run your analysis on the grid adding the .so and .map files to the input sandbox with the -f option of gbasf2:

>>> gbasf2 ./steering.py -p project -i dataset -f myanalysis.so myanalysis.b2modmap

Warning

This line implies that you already have working gbasf2 installation and gbasf2 syntax didn’t change since the moment of writing. Please refer gbasf2 documentation for more details.