Topology analysis
Contents
Topology analysis#
This section provides some information on the interface, repositories, and
documents of TopoAna
,
which is a generic tool for the event type analysis of inclusive MC samples in
high energy physics experiments,
and hence a powerful tool for analysts to investigate the signals and backgrounds
involved in their works.
TopoAna
is an offline tool independent of basf2
.
It can take the output root files of the Analysis module as
input.
The MC truth information for the event type analysis can be stored in the root
files with the utility MCGenTopo
in basf2
.
Thus, MCGenTopo
is the interface of basf2
to TopoAna
.
Note
Apart from the interface, this section only introduces the TopoAna
resources outside the Belle II software documentation.
Inside the documentation, please see Section 3.5.5 for the
online textbook on TopoAna
.
It is a good idea to start learning the usage of TopoAna
with this online
textbook.
Please feel free to contact Xingyu Zhou (zhouxy@buaa.edu.cn) if you have any
questions or comments on TopoAna
.
The interface#
As we mention above, MCGenTopo
is the interface of basf2
to TopoAna
.
To be specific, the interface implements the following parameter function
mc_gen_topo(n)
in the script variables/MCGenTopo.py
.
- variables.MCGenTopo.mc_gen_topo(n=200)[source]
Gets the list of variables containing the raw topology information of MC generated events. To be specific, the list including the following variables:
nMCGen
: number of MC generated particles in a given event,MCGenPDG_i
(i=0, 1, … n-2, n-1): PDG code of the \({\rm i}^{\rm th}\) MC generated particle in a given event,MCGenMothIndex_i
(i=0, 1, … n-2, n-1): mother index of the \({\rm i}^{\rm th}\) MC generated particle in a given event.
Tip
Internally,
nMCGen
,MCGenPDG_i
andMCGenMothIndex_i
are just aliases ofnMCParticles
,genParticle(i, varForMCGen(PDG))
andgenParticle(i, varForMCGen(mcMother(mdstIndex)))
, respectively.For more details on the variables, please refer to the documentations of
nMCParticles
,genParticle
,varForMCGen
,PDG
,mcMother
, andmdstIndex
.
- Parameters
n (int) – number of
MCGenPDG_i
/MCGenMothIndex_i
variables. Its default value is 200.
Note
To completely examine the topology information of the events in an MC sample, the parameter
n
should be greater than or equal to the maximum ofnMCGen
in the sample.Normally, the maximum of
nMCGen
in the MC samples at Belle II is less than 200. Hence, if you have no idea about the maximum ofnMCGen
in your own MC sample, it is usually a safe choice to use the default parameter value 200.However, an overlarge parameter value leads to unnecessary waste of disk space and redundant variables with inelegant
nan
values. Hence, if you know the maximum ofnMCGen
in your own MC sample, it is a better choice to assign the parameter a proper value.
Below are the steps to use mc_gen_topo(n)
to get the input data to TopoAna
.
Append the following statement at the beginning part of your python steering script
from variables.MCGenTopo import mc_gen_topoUse the parameter function
mc_gen_topo(n)
as a list of variables in the steering functionvariablesToNtuple
as followvariablesToNtuple(particleList, yourOwnVariableList + mc_gen_topo(n), treeName, fieName, path)Run your python steering script with
basf2
Repositories#
The following three remote repositories of TopoAna
are provided at present.
The one at Stash is most convenient to Belle II users.
Nonetheless, the two at GitHub and at GitLab of IHEP are also provided as helpful
alternatives for possible convenience.
Documents#
See also
The introduction to the documents can also be found in the file README.md
in the TopoAna
package, which should be the first document to be read on
TopoAna
.
For your convenience, a pdf and a html version of the README file are provided
in the TopoAna
package as share/README.pdf
and share/README.html
,
respectively.
The following three documents of TopoAna
are provided in its package.
A brief description of the tool is in the document:
share/quick-start_ tutorial_v*_Belle_II.pdf
All the examples in the quick-start tutorial can be found in the sub-directory
examples/in_the_quick-start_tutorial
A detailed description of the tool is in the document:
share/user_guide _v*.pdf
All the examples in the user guide can be found in the sub-directory
examples/in_the_user_guide
An essential description of the tool is in the document:
share/paper_draft_v*.pdf
All the examples in the paper draft can be found in the sub-directory
examples/in_the_paper
Note
The paper on the tool has been published by
Computer Physics Communications
. You can find this paper and the preprint corresponding to it in the links Comput. Phys. Commun. 258 (2021) 107540 and arXiv:2001.04016, respectively. If the tool really helps your researches, we would appreciate it very much if you could cite the paper in your publications.
As for the three documents, the quick-start tutorial is the briefest, the user guide is the most detailed, and the paper draft is composed of the essential and representative parts of the user guide.
Tip
It is a good practice to learn how to use the tool via the examples in the quick-start tutorial, user guide, and paper draft, in addition to the online textbook in Section 3.5.5.
Use cases at Belle II#
At the end of this section, we list two use cases of TopoAna
at Belle II:
one for semitauonic analyses and the other for charm analyses.
You can refer to them if you work in the related analysis groups.
Using TopoAna with the semitauonic framework by Hannah Marie Wakeling
TopoAna Wrapper for Charm Analysis by Guanda Gong