3.4.3. The Rest of Event (ROE)#

After the reconstruction of the signal particle list it is very useful to look into the the particles that are not associated to the signal particle list. In basf2 these particles are called “Rest of Event” and this is the main topic of the chapter.

The Rest of Event (ROE) can contain a lot of information: in case of B-physics, the ROE of one B-meson includes particles from the partner B-meson and in case of charm and tau analysis, the ROE of the lepton has the partner lepton.

Exercise

Find the documentation of the ROE module. What are its use cases for tagged and untagged analyses?

Hint

It’s included in the “Advanced Topics” section of the analysis module.

Solution

Documentation is here: Rest Of Event. There is quite a bit of content. For now, make sure to take a look at the Overview and the “Basic usage” sections.

Basics#

In this chapter we will continue our work on the steering file from the last lesson. Remember that you have reconstructed a \(B^0\) particle list. We now want to reconstruct the Rest of Event of the \(B^0\).

Exercise

Look up how to create a Rest Of Event for your particle list (it’s a single line of code). Add the fillWithMostLikely=True option.

Hint

You have already found the Rest Of Event chapter in the last exercise. Take a look at the basic usage example.

Solution

# build the rest of the event [S10|S30|S40]
ma.buildRestOfEvent("B0", fillWithMostLikely=True, path=main)  # [E10]

That’s it, the ROE has been reconstructed! Behind these python curtains, a RestOfEvent object is created for each particle in the \(B^0\) particle list and it includes all other charged or neutral particles, that have not been associated to the corresponding signal candidate. By default, the charged particles are assumed to be pions, and the neutral particles use the photon or \(K_L^0\) hypothesis.

ROE variables#

In principle, one can already try to use some of the Rest of Event variables.

Exercise

Find documentation for the Rest Of Event variables.

Hint

Use the search feature in the basf2 documentation, or use the offline help by typing b2help-variables in your bash terminal (for example b2help-variables | grep -i roe).

Solution

The Rest Of Event variables are in Rest Of Event section of VariableManager page, which starts from bssMassDifference variable.

Among the most universal and useful are ROE invariant mass roeM or ROE energy roeE. Also, one can call nROE_Charged or nROE_Photons to know how many charged particles or photons entered the ROE.

Remember that we were collecting all variables in the b_vars list. Let’s include the following lines to have a useful selection of them:

# ROE variables [S20|S50]
roe_kinematics = ["roeE()", "roeM()", "roeP()", "roeMbc()", "roeDeltae()"]
roe_multiplicities = [
    "nROE_Charged()",
    "nROE_Photons()",
    "nROE_NeutralHadrons()",
]
b_vars += roe_kinematics + roe_multiplicities  # [E20]

Exercise

Run your steering file and check that it completes without error.

In principle we could already start to do an analysis. However, the ROE variables that we have just defined are not quite useful yet: we first need to “clean up” the ROE. For this, we define ROE masks.

ROE masks#

The main philosophy of the ROE is to include every particle in the event, that has not been associated to the signal candidate. That is why a typical ROE contains not only the partner particle (e.g. the tag or signal B), but also all other particles, like hadron split-off particles, \(\delta\)-rays, unused radiative photons, beam-induced background particles or products of kaon or pion decays. It is up to the analyst to decide what particles actually matter for the analysis. This is called “cleaning up” the ROE. For this procedure, ROE masks are used.

ROE masks are just sets of selection cuts to be applied on the ROE particles.

For our example, let’s start by defining the following selection cut strings:

# build the rest of the event [S10|S30|S40]
ma.buildRestOfEvent("B0", fillWithMostLikely=True, path=main)  # [E10]
track_based_cuts = "thetaInCDCAcceptance and pt > 0.075 and dr < 5 and abs(dz) < 10"
ecl_based_cuts = "thetaInCDCAcceptance and E > 0.05"  # [E30]

Here we created different cuts for charged particles, like electrons or charged pions, and for photons, because of different methods of measurement used to detect these particles.

Tip

These are example cuts, please use official guidelines from Charged or Neutral Performance groups to set up your own selection in a “real” analysis.

Exercise

Create a ROE mask using the charged_cuts and photon_cuts strings with the appendROEMask or appendROEMasks function.

Hint

A mask is defined as a tuple with three values. Use appendROEMasks to “activate” it.

Solution

# build the rest of the event [S10|S30|S40]
ma.buildRestOfEvent("B0", fillWithMostLikely=True, path=main)  # [E10]
track_based_cuts = "thetaInCDCAcceptance and pt > 0.075 and dr < 5 and abs(dz) < 10"
ecl_based_cuts = "thetaInCDCAcceptance and E > 0.05"  # [E30]
roe_mask = ("my_mask", track_based_cuts, ecl_based_cuts)
ma.appendROEMasks("B0", [roe_mask], path=main)  # [E40]

Now we have created a mask with a name my_mask, that will only allow track-based particles that pass selection cuts track_based_cuts and ECL-based particles, that pass ecl_based_cuts.

The analyst can create as many ROE masks as needed and use them in different ROE-dependent algorithms or ROE variables. For ROE variables, the mask is specified as an argument, like roeM(my_mask) or roeE(my_mask).

In the last section, we defined two lists of ROE variables (roe_kinematics and roe_multiplicities). Now we want to have the same variables but with the my_mask argument. Since we’re lazy, we use a python loop to insert this argument.

Exercise

Write a for loop that runs over roe_kinematics + roe_multiplicities and replaces the () of each variable with (my_mask). Add these new variables to the b_vars list.

Hint

The variables are nothing more than a string, which has a replace method:

>>> "roeE()".replace("()", "(my_mask)")
'roeE(my_mask)'

Hint

Fill the missing bit of code:

for roe_variable in roe_kinematics + roe_multiplicities:
    roe_variable_with_mask = your_code_here
    b_vars.append(roe_variable_with_mask)

Solution

# ROE variables [S20|S50]
roe_kinematics = ["roeE()", "roeM()", "roeP()", "roeMbc()", "roeDeltae()"]
roe_multiplicities = [
    "nROE_Charged()",
    "nROE_Photons()",
    "nROE_NeutralHadrons()",
]
b_vars += roe_kinematics + roe_multiplicities  # [E20]
# Let's also add a version of the ROE variables that includes the mask:
for roe_variable in roe_kinematics + roe_multiplicities:
    # e.g. instead of 'roeE()' (no mask) we want 'roeE(my_mask)'
    roe_variable_with_mask = roe_variable.replace("()", "(my_mask)")
    b_vars.append(roe_variable_with_mask)  # [E50]

Tip

There are also KLM-based hadrons in ROE, like \(K_L^0\) or neutrons, but they are not participating in ROE 4-momentum computation, because of various temporary difficulties in KLM reconstruction. Nevertheless, one can count them using nROE_NeutralHadrons variable.

Exercise

Your steering file is now complete. Run it!

Solution

Your steering file should look like this:

#!/usr/bin/env python3

import sys
import basf2 as b2
import modularAnalysis as ma
import stdV0s
import variables.collections as vc
import variables.utils as vu

# get input file number from the command line
filenumber = sys.argv[1]

# create path
main = b2.Path()

# load input data from mdst/udst file
ma.inputMdstList(
    filelist=[b2.find_file(f"starterkit/2021/1111540100_eph3_BGx0_{filenumber}.root", "examples")],
    path=main,
)

# fill final state particle lists
ma.fillParticleList(
    "e+:uncorrected",
    "electronID > 0.1 and dr < 0.5 and abs(dz) < 2 and thetaInCDCAcceptance",
    path=main,
)
stdV0s.stdKshorts(path=main)

# combine final state particles to form composite particles
ma.reconstructDecay(
    "J/psi:ee -> e+:uncorrected e-:uncorrected", cut="dM < 0.11", path=main
)

# combine J/psi and KS candidates to form B0 candidates
ma.reconstructDecay(
    "B0 -> J/psi:ee K_S0:merged",
    cut="Mbc > 5.2 and abs(deltaE) < 0.15",
    path=main,
)

# match reconstructed with MC particles
ma.matchMCTruth("B0", path=main)

# build the rest of the event [S10|S30|S40]
ma.buildRestOfEvent("B0", fillWithMostLikely=True, path=main)  # [E10]
track_based_cuts = "thetaInCDCAcceptance and pt > 0.075 and dr < 5 and abs(dz) < 10"
ecl_based_cuts = "thetaInCDCAcceptance and E > 0.05"  # [E30]
roe_mask = ("my_mask", track_based_cuts, ecl_based_cuts)
ma.appendROEMasks("B0", [roe_mask], path=main)  # [E40]

# Create list of variables to save into the output file
b_vars = []

standard_vars = vc.kinematics + vc.mc_kinematics + vc.mc_truth
b_vars += vc.deltae_mbc
b_vars += standard_vars

# ROE variables [S20|S50]
roe_kinematics = ["roeE()", "roeM()", "roeP()", "roeMbc()", "roeDeltae()"]
roe_multiplicities = [
    "nROE_Charged()",
    "nROE_Photons()",
    "nROE_NeutralHadrons()",
]
b_vars += roe_kinematics + roe_multiplicities  # [E20]
# Let's also add a version of the ROE variables that includes the mask:
for roe_variable in roe_kinematics + roe_multiplicities:
    # e.g. instead of 'roeE()' (no mask) we want 'roeE(my_mask)'
    roe_variable_with_mask = roe_variable.replace("()", "(my_mask)")
    b_vars.append(roe_variable_with_mask)  # [E50]

# Variables for final states (electrons, positrons, pions)
fs_vars = vc.pid + vc.track + vc.track_hits + standard_vars
b_vars += vu.create_aliases_for_selected(
    fs_vars,
    "B0 -> [J/psi -> ^e+ ^e-] [K_S0 -> ^pi+ ^pi-]",
    prefix=["ep", "em", "pip", "pim"],
)
# Variables for J/Psi, KS
jpsi_ks_vars = vc.inv_mass + standard_vars
b_vars += vu.create_aliases_for_selected(jpsi_ks_vars, "B0 -> ^J/psi ^K_S0")
# Also add kinematic variables boosted to the center of mass frame (CMS)
# for all particles
cmskinematics = vu.create_aliases(
    vc.kinematics, "useCMSFrame({variable})", "CMS"
)
b_vars += vu.create_aliases_for_selected(
    cmskinematics, "^B0 -> [^J/psi -> ^e+ ^e-] [^K_S0 -> ^pi+ ^pi-]"
)

# Save variables to an output file (ntuple)
ma.variablesToNtuple(
    "B0",
    variables=b_vars,
    filename="Bd2JpsiKS.root",
    treename="tree",
    path=main,
)

# Start the event loop (actually start processing things)
b2.process(main)

# print out the summary
print(b2.statistics)

Quick plots#

Exercise

Plot ROE invariant mass and number of charged particles in ROE distributions and compare masked and unmasked ROE. Column names in the ntuple:

roeM

nROE_Charged

Unmasked ROE

roeM__bo__bc

nROE_Charged__bo__bc

ROE with my_mask

roeM__bomy_mask__bc

nROE_Charged__bomy_mask__bc

Hint: Plotting side by side

One can use matplotlib functions to plot several histograms on one figure side-by-side. Documentation is on this page, but you also saw some examples in your python training.

Hint: Outliers

Some of the distributions contain outliers, which need to be rejected in order to get meaningful plots (this means to manually set the plotting range). Proposed ranges: roeM from 0 to 10 and nROE_Charged from 0 to 15.

Hint: Styling

  • Another hint is that comparison plots look better if they are a bit transparent, which can be achieved by supplying alpha=0.6 argument to the plotting functions. Alternatively you might look into the histtype argument to only show the outlines of the distributions.

  • As we are plotting many distributions on one figure legends and axis titles are important

Hint: Fill in the blanks

import uproot
import matplotlib.pyplot as plt

plt.style.use('belle2')

var_list = ['roeM__bo__bc', 'roeM__bomy_mask__bc', 'nROE_Charged__bo__bc', 'nROE_Charged__bomy_mask__bc']
df = uproot.open('Bd2JpsiKS.root:tree').arrays(var_list, library='pd')

m_bins = 50
m_range = (0, 10)
fig, ax = plt.subplots(1,2, figsize=(15, 7))
# Left subplot of ROE mass:
ax[0].hist(...)
ax[0].hist(...)
ax[0].set_xlim(m_range)
ax[0].set_xlabel('ROE mass [GeV/$c^2$]')
# Right subplot of number of charged ROE particles:
m_bins = 15
m_range = (0, 15)
ax[1].hist(...)
ax[1].hist(...)
ax[1].set_xlim(m_range)
ax[1].set_xlabel('# of charged ROE particles')
ax[1].legend()
fig.tight_layout()
fig.savefig('roe_mask_comparison.svg')

Solution

import uproot
import matplotlib.pyplot as plt

plt.style.use('belle2')

var_list = ['roeM__bo__bc', 'roeM__bomy_mask__bc', 'nROE_Charged__bo__bc', 'nROE_Charged__bomy_mask__bc']
df = uproot.open('Bd2JpsiKS.root:tree').arrays(var_list, library='pd')

m_bins = 50
m_range = (0, 10)
fig, ax = plt.subplots(1,2, figsize=(15, 7))
# Left subplot of ROE mass:
ax[0].hist(df['roeM__bo__bc'], label='No mask',
           bins = m_bins, range=m_range, alpha=0.6)
ax[0].hist(df['roeM__bomy_mask__bc'], label='"my_mask" applied',
           bins = m_bins, range=m_range, alpha=0.6)
ax[0].set_xlim(m_range)
ax[0].set_xlabel('ROE mass [GeV/$c^2$]')
# Right subplot of number of charged ROE particles:
m_bins = 15
m_range = (0, 15)
ax[1].hist(df['nROE_Charged__bo__bc'], label='No mask',
           bins = m_bins, range=m_range, alpha=0.6)
ax[1].hist(df['nROE_Charged__bomy_mask__bc'], label='"my_mask" applied',
           bins = m_bins, range=m_range, alpha=0.6)
ax[1].set_xlim(m_range)
ax[1].set_xlabel('# of charged ROE particles')
ax[1].legend()
fig.tight_layout()
fig.savefig('roe_mask_comparison.svg')

The resulting plot should look like the figure below.

ROE mask comparison

Fig. 3.22 Distributions of ROE invariant mass (left) and number of charged ROE particles (right).#

Fig. 3.22 shows a comparison of roeM and nROE_Charged distributions for ROE with mask my_mask case and ROE with no mask applied.

Strange variable names

You might wonder where these strange variable names came from. This is because it is tried to avoid branch names (columns of your output ROOT file) that contain special characters (parentheses, spaces and so on). For example, every ( is replaced by _bo for “bracket open”. What does _bc stand for?

Exercise

Take another look at Fig. 3.22 and describe what you see. Can you explain the differences between the masked and unmasked variables?

Solution

The invariant mass distribution for masked ROE is much narrower and its mean is a little bit below nominal \(B^0\) mass, contrary to the unmasked ROE distribution. This is expected, because a generic \(B^0\) decay may produce particles, that are not accounted in ROE mass computation, like \(K_L^0\) or neutrinos.

The distribution of the number of charged particles for masked ROE has much more prominent peaks at 4 and 6 particles than its unmasked version, which corresponds to the fact that a correctly reconstructed \(B^0\) will have an even number of charged daughter particles.

This means that even a simple ROE mask like my_mask does a really good job of cleaning up the particles, which are not associated to the partner \(B^0\).

This concludes the Rest of Event setup as a middle stage algorithm to run Continuum Suppression (CS), Flavor tagging or tag Vertex fitting.

Key points

  • The ROE of a selection is build with buildRestOfEvent

  • ROE masks are added with appendROEMask or appendROEMasks. Use them to clean up beam-induced or other background particles.

  • For many analyses ROE is used as middleware to get tag vertex fit, continuum suppression or flavor tag.

  • Usage of ROE without a mask is not recommended.

Stuck? We can help!

If you get stuck or have any questions to the online book material, the #starterkit-workshop channel in our chat is full of nice people who will provide fast help.

Refer to Collaborative Tools. for other places to get help if you have specific or detailed questions about your own analysis.

Improving things!

If you know how to do it, we recommend you to report bugs and other requests with GitLab. Make sure to use the documentation-training label of the basf2 project.

If you just want to give very quick feedback, use the last box “Quick feedback”.

Please make sure to be as precise as possible to make it easier for us to fix things! So for example:

  • typos (where?)

  • missing bits of information (what?)

  • bugs (what did you do? what goes wrong?)

  • too hard exercises (which one?)

  • etc.

If you are familiar with git and want to create your first pull request for the software, take a look at How to contribute. We’d be happy to have you on the team!

Quick feedback!

Authors of this lesson

Sviatoslav Bilokin, Kilian Lieret