TopoAna#
Note
Credit for the package goes to Zhou Xingyu
For more information, see the
corresponding paper on arXiv.
This package is an extremely helpful tool for analyzing the topologies of Inclusive Monte Carlo simulation. Inclusive MC samples give us valuable information about the background of your analysis, as it allows you to know the true contributions to that background. If you know what components that background exists of, you can:
try to make smart cuts to remove those background components;
use a particular function that describes that background component best when applying a fit to the real data.
The problem with inclusive samples, however, is that they can include thousands of decay
modes. The topoana
package allows you to make certain selections and to generate
tables that list frequencies of particles and decay modes that are of interest to you.
All versions of the package can be found here on the IHEP server:
/besfs5/users/zhouxy/tools/topoana
Preparing initial event selection#
The topoana
package has to be run over a ROOT file that you have to prepare yourself.
The ROOT file has to contain a TTree
with specific information of the Monte Carlo
truth:
the run ID number
the event ID number
the number of particles in this event, which is necessary for loading the following arrays
an array contain the PDG code for each track in this event
an array containing the PDG code for the mother of each track (if available)
You can design a procedure to write this MC truth information yourself, but you can also use either of the following two methods:
Add the
MctruthForTopo
algorithm package (see below) to the job options of your analysis.Go through the code of the
MctruthForTopo
algorithm and take over the relevant components in your own initial event selection package, so that you can implement it within your cut procedure.Use the
CreateMCtruthCollection
andWriteMcTruthForTopoAna
in theTrackSelector
base algorithm.
The MctruthForTopo
package#
MctruthForTopo
is an example package that comes with topoana
. It can be used for
preparing a ROOT file sample that contains a TTree
as described above. See the
documentation of MctruthForTopo
for how these branches are typically called within
MctruthForTopo-00-00-06
.
Version |
Data type |
---|---|
|
No selection: all |
|
Particles that don’t come from a generator are rejected |
|
Specifically designed for \(J/\psi\) |
|
\(J/\psi\), but with bug fix for |
|
Designed for PID \(90022\) and \(80022\) (??) |
|
\(4,180\) MeV data |
See also decayFromGenerator
All versions of MctruthForTopo
can be found here on the IHEP server:
/besfs5/users/zhouxy/workarea/workarea-6.6.5/Analysis/Physics/MctruthForTopoAnaAlg
You may choose a different version of BOSS than 6.6.5
, the one used above. If you have
sourced one of these versions (using bash cmt/setup
), you can run it by adding the
following lines to your job options:
ApplicationMgr.DLLs += {"MctruthForTopoAnaAlg"};
ApplicationMgr.TopAlg += {"MctruthForTopoAna"};
Note: Using MctruthForTopoAna
is the quickest way to create a TTree
containing the
necessary data for topoana
, but it does not allow you to perform cuts: all the
events will be written to the TTree
and no cut will be applied.
Structure of the Event::McParticleCol
collection#
The TTree
containing Monte Carlo data that is needed for topoana
is created by
looping over the
Event::McParticleCol
in each event and writing the branches described above. To gain a better understanding
of what a package like MctruthForTopo
does, let’s have a look at the the contents of
the MC truth particle collection in one event:
Index |
Particle |
Index |
Mother |
||||
---|---|---|---|---|---|---|---|
|
23 |
|
\(Z^0\) |
||||
|
22 |
|
\(\gamma\) |
||||
|
4 |
|
\(c\) |
|
23 |
|
\(Z^0\) |
|
-4 |
|
\(\bar{c}\) |
|
23 |
|
\(Z^0\) |
|
91 |
|
|
-4 |
|
\(\bar{c}\) |
|
|
443 |
|
\(J/\psi\) |
|
|
||
|
11 |
|
\(e^-\) |
||||
|
421 |
|
\(D^0\) |
|
443 |
|
\(J/\psi\) |
|
333 |
|
\(\phi\) |
|
443 |
|
\(J/\psi\) |
|
-321 |
|
\(K^-\) |
|
421 |
|
\(D^0\) |
|
221 |
|
\(\pi^+\) |
|
421 |
|
\(D^0\) |
|
321 |
|
\(K^+\) |
|
333 |
|
\(\phi\) |
|
-321 |
|
\(K^-\) |
|
333 |
|
\(\phi\) |
|
-13 |
|
\(\mu^+\) |
|
321 |
|
\(K^+\) |
|
14 |
|
\(\nu_\mu\) |
|
321 |
|
\(K^+\) |
|
-11 |
|
\(e^+\) |
|
-13 |
|
\(\mu^+\) |
|
12 |
|
\(\nu_e\) |
|
-13 |
|
\(\mu^+\) |
|
-14 |
|
\(\bar{\nu}_{\mu}\) |
|
-13 |
|
\(\mu^+\) |
A few remarks about what we see here:
The structure of the decay chain is described by the index (see Event::McParticle::trackIndex). Each particle is labeled by this index and if there is a mother particle, it is ‘linked’ to its daughter by its index.
The decay chain starts with index
0
, a \(Z^0\) boson that emerges right after the \(e^+e^-\) collision, which then decays into a \(c\bar{c}\) charm pair. In the simulation, this pair is taken to be acluster
(which has code91
) or astring
(which has code92
).For
TopoAna
(or actually any physics analysis), we are only interested in what happens after the formation of the cluster. This is where the meson is created to which the beam energy is tuned, in this case \(J/\psi\). We therefore only store particles that come after either particle code 91 or 92, seeMctruthForTopoAna::execute
.From the remainder of the table, we can see that the rest of the decay chain becomes (a rather rare if not impossible decay):
The main takeaway is that topoana
requires you to store the branch with “track index”
defined above as
having an offset: the first particle is to be the initial meson (e.g. \(J/\psi\)) with
track index 0
, so that you can use the mother index as an array index. So you need to
subtract its original index from index of the the particles that come after. In
addition, the selection of MC truth particles is only to contain:
Particles that result from the initial cluster or string, that is, everything that in this case comes after \(J/\psi\).
Only particles that come from the generator. This means they are not background simulated in the detectors and that that they were included in the decay chain from the generator. (See Event::McParticle::decayFromGenerator.) In this case, this means that everything that comes after the decay of \(D^0\) and \(\phi\) is to be excluded, because the \(\mu^+\) and \(K^+\) decays take place outside the BESIII detector.
Only particles that have a mother particle (is not primaryParticle).
In table format, with these conventions, the result that should be stored for the
topoana
package would be:
Array index |
Particle |
Array index |
Mother |
||||
---|---|---|---|---|---|---|---|
|
443 |
|
\(J/\psi\) |
|
91 |
|
|
|
421 |
|
\(D^0\) |
|
443 |
|
\(J/\psi\) |
|
333 |
|
\(\phi\) |
|
443 |
|
\(J/\psi\) |
|
-321 |
|
\(K^-\) |
|
421 |
|
\(D^0\) |
|
211 |
|
\(\pi^+\) |
|
421 |
|
\(D^0\) |
|
321 |
|
\(K^+\) |
|
333 |
|
\(\phi\) |
|
-321 |
|
\(K^-\) |
|
333 |
|
\(\phi\) |
Installing topoana#
Execute
setup.sh
and see the instructions there on how to source it. If you have done this, you can use
the command topoana.exe
the output generated through the
previous step.
Format of a topoana card#
If you have
prepared a ROOT file
and installed topoana.exe, you can
analyze the output. The topoana
package will generate some tables containing
statistics of certain signal particles and signal decay modes. You can specify these
signal particles and branches through a topoana
card and run the analysis with the
command topoana.exe your_topoana.card
.
A topoana
card file (.card
extension) is a text file that defines the way in which
you execute topoana.exe
on your data set. In this file, you for instance specify the
input ROOT files that you want to analyze.
The syntax of the topoana
card is slightly reminiscent of bash
. Starting a line
with:
#
means that the line is a comment and is therefore ignored;%
means that the the line represents a field.
A opening curly brace ({
) following a %
sign means that a field block is opened. The
next line(s) contain the value(s) of that field. Close the block with a closing curly
brace (}
).
The following pages list all fields that can be used in your topoana
card:
required and
optional fields.
Tips on the results#
(From topoana
terminal output.)
Statistics of the topologies are summarized in three types files:
pdf
,tex
andtxt
. Although these are different formats, they contain the same information. Thepdf
file is the easiest to read. It has been converted from thetex
file using thepdflatex
command. If necessary, you can check the contents of thetxt
file as well (e.g. using text processing commands).Tags of the topologies are inserted in all the entries of
TTree
fortopoana
in the output ROOT file(s). The ROOT files may have been split up, in which case you should load them using aTChain
. Except for this, theTTree
fortopoana
data of the output ROOT file is entirely the same as that of the input ROOT file(s). In addition, the topology tags are identical with those listed in the txt, tex, and pdf files.
Submitting a topoana.exe
job#
Just like a BOSS job, you can submit a topoana
job to the queue. This is useful if
your data is extensive and you want to log out while the job is executed. Just write
your command in a bash
script like this:
{ topoana.exe your_topoana.card; } &> your_file.log
The pipe (>
) with the curly braces ensures that all output (including warnings) is
written to the log file (here, your_file.log
).
Make sure that you make the bash
script executable using chmod +x your_bash_file.sh
.
You can then submit your job to the queue using:
hep_sub -g physics your_bash_file.sh
and keep an eye on your jobs using:
hep_q -u $USER