Workbook for BaBar Offline Users - Beta: the Analysis Package
Beta is an analysis toolkit for use with BaBar data. It forms the
basic interface to the complete reconstruction of BaBar data. The
primary goal of Beta is to provide a simple, common basis for writing
detailed physics analysis programs. It provides for particle
identification, vertexing, tagging, and so forth. This chapter will
cover the mechanics of using Beta to perform user analysis. More advanced
uses of Beta for analysis tasks are in the
Analysis section of Advanced Analysis in the Workbook.
The most important Beta package for most users is BetaMiniUser.
BetaMiniUser is a package that has been created to facilitate a
user's interaction with the larger-scale Beta package. The
BetaMiniUser package, which makes the BetaMiniApp executable,
is where an individual can develop their own analysis. The information
in this section will be focused on using Beta through the
BetaMiniUser package. This package contains various self-contained
examples of simple analysis jobs.
To see a list of Beta packages, just look for files beginning
with the word "Beta":
> ls $BFDIST/releases/analysis-30/Beta[TAB]
Beta BetaMicroAdapter BetaMiniUser
BetaBogus BetaMicroBase BetaPid
BetaBuildPidEnv BetaMicroTruth BetaPidCalib
BetaCoreTools BetaMini BetaReco
BetaEvent BetaMiniData BetaRecoAdapter
BetaExamples BetaMiniEnvSequences BetaSequences
BetaIfrPidCalib BetaMiniModules BetaTools
BetaLumi BetaMiniQA BetaUser
BetaMC BetaMiniRooEnvSequences
BetaMicro BetaMiniSequences
As you can see, Beta is a system of many packages, including:
Beta
- Base classes, candidate classes, etc.
BetaExamples
- Example analysis modules. A good resource
for modules to experiment with, and code to look at for
new ideas and techniques.
BetaMC, BetaReco, BetaRecoAdapter
- Interface packages for running on reconstructed data
BetaSequences
- Sequences and .tcl files used by Beta to run in
various modes
BetaTools
- Analysis-level tools that you might want to use in
your program. For example, this package include general
two-body and three-body decay finders.
BetaMiniUser
- The sample package on which
you can build your analysis. "Mini" refers to the Mini database.
BetaUser
- An old version of BetaMiniUser, used to access the
old (obsolete) "Micro" database.
In general, you will want to work with packages beginning with
"BetaMini", because these are the ones designed for the new Mini
database. Packages beginning with
"BetaMicro" access the Micro database, and will not work with current
analysis code releases.
The BetaMini packages include (see also BAD 508):
BetaMiniUser
- For many analyses, this will be the only package that the user had to
modify. It contains the example analysis modules, AppUserBuilds and
sample scripts that the user can copy and modify in order to access and
analyze the Mini data through the Beta interface.
BetaMiniSequences
- This core package contains the sequences, tcl scripts and TCL parameter definitions
needed to create the BtaCandidate lists from the Mini database.
BetaMini
- This package creates the basic lists of charged and neutral BtaCandidates from the information stored on the Mini database. It contains lots of mini-specific packages like LoadMiniBtaCandidates, BtaMiniTrkQual, BtaMiniCalQual, BtaMiniIfrQual, and
BtaMiniPidInfo.
BetaMiniModules and BetaMiniQA
- These packages contain classes to display and validate the information stored on the Mini database. BetaMiniQA receives contributions from the component subsystems; BetaMiniModules is maintained by the core mini developers.
BetaMiniData- This core package provides classes which uniquely identify each BtaCandidate on the mini and maps between the identifiers and BtaCandidates.
Again, though, while there are many BetaMini packages, you will probably work
only with BetaMiniUser and possibly one or two others.
Like most BaBar executables, BetaMiniApp is run only from the workdir
directory, due to needed data files for reconstruction. You will need
the workdir package checked out in your test release directory to
perform analysis with the BetaMiniUser package.
The workdir package is used to run a variety of applications in
addition to Beta jobs. Consequently is contains some files that are
either not directly used or not used at all by Beta packages. The most
important files in the workdir package are symbolic links to the areas
where library and executable files are stored.
For a discussion of the workdir package and its role in
running Beta applications, see The
workdir Package chapter of the workbook; specifically the Beta section.
The BetaMiniUser package contains several tcl files that
accommodate a variety of BetaMiniApp applications. Of those many
files the following were used in the QuickTour analysis.
AppUserBuild.cc, AppUserBuildRoo.cc, AppUserBuildBase.cc
- implementation for AppUserBuild class
btaMini.tcl
- tcl file for setting up analysis path to the Mini database
MyMiniAnalysis.tcl
- tcl file for a general user analysis sequence
NTrkExample (.cc and .hh)
- code to plot a trks/event histogram
The Beta package itself contains the candidate classes and base
classes. For standard analysis editing the BetaMiniUser package should be
sufficient, while the Beta package should be consulted for further
definitions of event quantities and functions.
The Beta software packages exist in modular form. That is, the Beta
software has been split into building blocks of code that can be
assembled to form customized BetaXXXApp applications (BetaApp,
BetaMiniApp, BetaMiniQAApp...). For example, a block of Beta
code for reading from the production database can be put together
with simulation and reconstruction blocks to form an executable.
The advantage of this modular scheme is that when you use only the
code you need for your application, you save compilation and
linking time.
(Warning: A perfect modular system would have no dependencies between
modules. But sometimes Beta's modular structure is less than perfect,
so there may be intermodular dependencies.)
A set of variables are used to control what modules gets linked into
a Beta[Something]App application. Each variable has a default value determined
by the software release. For release analysis-30 the default settings are
as follows (again taken from
BAD508):
Table:
BetaMiniUser TCL configuration parameters.
| TCL parameter |
Allowed values |
Default |
Comments |
| levelOfDetail |
micro, cache, extend, refit, rebuild |
cache |
See Table 1. The list of allowed levelOfDetail values are stored
in the variable BetaMiniLevels. |
| ConfigPatch |
Run1, Run2, MC |
Run2 |
Specifies the
data taking period of the input. Run2 now encompasses all data taking
periods. MC specifies Monte Carlo simulated data. |
| MCTruth |
true, false |
false if ConfigPatch is not equal to MC, else true |
true means construct the MCTruth BtaCandidates and maps to reco candidates |
| inputList |
|
|
Space-delimited list of input
collections. The format of the input data, Bdb or Kan, is specified by
the variable BetaMiniReadPersistence. |
| BetaMiniReadPersistence |
Kan, Bdb |
Kan |
The
persistence format of the input data |
| BetaMiniTuple |
hbook, root |
hbook |
Determines the type
of output histogram file to create. This parameter will enable RooTupleEnv
(HbkTupleEnv) module and disable HbkTupleEnv
(RooTupleEnv) module if this parameter is set to root (
hbook). |
| histFileName |
|
BetaMini.
${BetaMiniTuple} |
Name of ntuple file. |
| BetaMiniSystems |
Eid Tag Trk Emc Ifr Pid
G3 G4 Reco Svt Dch Drc L1Glt
L1Fct L3T BtaMini |
|
The list of systems to be read,
constructed by BetaMiniSequences/BetaMiniDefineSystems.tcl. A subset of systems may be explicitly specified but must
account for system interdependencies. |
| BetaMiniReadComponents |
Esd, Cnd, Aod, Tru, Tag, Sim |
Dependent on levelOfDetail |
The components which can be configured in a BetaMiniUser job. |
| BetaMiniReclusterComponents |
|
Esd Sim |
Defines which components are written into which root file. All components
except those specified in BetaMiniReclusterComponents
are written into the first (header) file. |
Setting these variables appropriately can greatly reduce compile time.
However, this also means that the settings of these variables can
limit what tcl scripts, and therefore what type of data, you can use
at run time.
In the Quicktour analysis you used your snippet.tcl file to set
some of these variables:
set ConfigPatch MC
set levelOfDetail cache
set BetaMiniTuple root
set histFileName myHistogram.root
You can see that you did not really have to set the levelofDetail,
since "cache" (the one you want) is the default. But it doesn't hurt.
The program flow of analysis job is best explained with a concrete
example. The following information will explicitly discuss using the
BetaMiniUser application to perform analysis, as done in the QuickTour
analysis. Most of the details pertain to any general analysis.
Any source code (specifically user-definted module class header
and implemantation files, .cc and .hh files) located in the
your test release will be compiled and linked by the gmake
all command. Compiling and linking the code in the BetaMiniUser
package produces an executable named BetaMiniApp.
In the Quicktour analysis you ran the executable by calling the
executable BetaMiniApp in the workdir package.
ana30/workdir> BetaMiniApp snippet.tcl
The last chapter of the workbook described how to interact with
the framework, but not how the framework gets created or how long
it lasts. The framework is implemented as a class, and an executable
like BetaMiniApp is needed to create it. Every time you run an executable
it instantiates (creates) a framework object. The framework is
effectively the program that is run. It is the main function of an analysis
executable. What the framework is given to work with and what it is
asked to do differentiates analysis applications.
The main function of your executable does two
things, it instantiates the framework and then creates an object
of the AppUserBuild class. The AppUserBuild class is used to
create the modules required by your analysis application and
make them available to the framework. The framework contains a data
member that is a list of modules. Initially this list is empty. The
constructor for the AppUserBuild class can create module class objects
and add them to the framework's list. Once a module is in this list it
can be accessed and used by the framework in analysis
applications. Here is an annotated copy of the AppUserBuildBase.cc file that you used in
the Quicktour analysis (comments are in blue).
After the executable performs these two initial actions it sources the
"tickle" runfile with which it was run. In the Quicktour analysis
the tcl file was snippet.tcl. This tcl file
sources a number of secondary tcl files that create sequences in the
framework and define what modules make up those sequences. Also, the
script creates a path in the framework and appends the sequences in
the appropriate order. These sequences are created by ready-made
scripts to shield the user from their details.
The snippet.tcl file passes the job to MyMiniAnalysis.tcl, which in
turn passes it to btaMini.tcl, the main tcl file. After the
btaMini.tcl script has been run the executable returns the
framework prompt, '>'. While the executable is running, a framework
prompt is given whenever user input is allowed or required. Then you
get to act like a tcl file. All legal commands that you issue at
the '>' prompt are translated into calls to framework member functions.
The framework interfaces between you and the analysis application
that you have defined within the context of the framework.
At this point you can get started with analysis. You can issue the
command to begin event analysis (ev begin), control the
name of output files, change parameters, change input, and so
forth. This is how you use the framework to manipulate your
application.
When you exit the framework you terminate the BetaMiniApp executable and
are returned to your usual unix shell prompt.
Summary
When you compile and link (gmake all)
the C++ code (.cc and .hh files), you create a BetaMiniApp executable,
which is basically a program. When you run the job, the BetaMiniApp
executable creates a framework and an AppUserBuild object, which loads
the framework with modules. Then the tcl files (or you, acting like
a tcl file) tell the framework what to do. In particular, the tcl
files (or you) set configuration variables and tell the framework
where to get data and how much to analyze.
Input and output is controlled by tcl scripts. For each
supported input data type an associated tcl file is included in the
BetaMiniUser package. Each script will create an analysis path with an
appropriate input module and initial analysis sequence. The
standard set is btaMiniPhysics.tcl, but you can get more
(btaMiniPhysProdSequence.tcl) or less (btaMini.tcl) if you want.
There are several ways to give input to the framework.
The best way is to use BbkDatasetTcl to make a tcl file full of
"lappend inputList collection_name" commands, and then add a
"source INPUTFILE.tcl" command in your controlling tcl file (in this case,
snippet.tcl or MyMiniAnalysis.tcl). This tells the framework where to get the
given collections.
The second way is to run the job interactively and act like
the tcl file yourself. This means that when you get your framework
prompt, you have to "mod talk" to an input module, usually
KanEventInput:
> mod talk KanEventInput
KanEventInput> input add collection_name_1
KanEventINput> input add collection_name_2
...
KanEventInput> input add collection_name_N
KanEventInput> exit
>
This adds the N collections to the framework's list of
data to run on. Once you do you "ev beg -nev NEvents"
command, the framework will run on the first NEvents
in this list of collections.
The output is written to a .root file (or an .hbook
file if you set BtaMiniTuple to "hbook"). You set
the file name in your snippet.tcl:
Otherwise you would have gotten the default name in
MyMiniAnalysis.tcl, namely MyMiniAnalysis.root.
This file is created in the workdir directory since
this is where the BetaMiniApp executable is run from.
See the workbook section Finding
Data for information about on finding data to run analysis jobs on.
A Beta Candidate is a representation of what is known or
assumed about an (alleged, thus candidate) particle. Candidates can
represent various levels of processing, various data types: a
reconstructed object, a combination of candidates, a transformation of
a candidate for a few examples. Candidates are represented by the
BtaCandidate class. Lists, specifically
HepALists, of BtaCandidates are stored
in an event (type AbsEvent). Possible lists in an
event may be of charged tracks or of muon candidates.
Some basic information about a candidate may be accessed directly via
the accessor member functions of the BtaCandidate
class. A list (not exhaustive) follows.
- double charge() const
- double energy() const
- double mass() const
- double p() const
- Hep3Vector p3() const
- Hep4Vector p4() const
These values are for the candidate at the origin/decay vertex.
More
member functions of the BtaCandidate class are contained in the
Workbook Event Store information on Kinematic
Variables and EventParameters,
and the full list of member functions of the BtaCandidate class is
contained in the source code, which can be viewed here.
Most/all information is either directly in or accessible from the
BtaCandidate class. The core of any analysis module will consist of
accessing data from BtaCandidate lists in events and
manipulation of BtaCandidates. This will involve writing
or at least modifying existing C++ code and is thus postponed to Analysis which follows the Editing Code section of the
workbook. For a complete listing of member functions consult the
BtaCandidate header file.
Interactive Beta
Interactive Beta enables the user to re-use Beta code interactively
while running an analysis session in ROOT. See the Workbook sections ROOT I, ROOT II and ROOT III for more information about ROOT.
General Related Documents:
Author:
Tracey Marsh
Contributors:
Joseph Perl
Charlie
Young
Jenny Williams
Last updated:
Jenny Williams
Last modification: 7 June 2005
Last significant update: 7 June 2005
|
