Introduction New features Summary
TbMon offline analysis framework:
Getting started, newly added features
Kyrre Ness Sjøbæk1
University of Oslo / ATLAS 3D Pixel R&D Collaboration
3D/PPS Eudet Software Tutorial,
7. June 2010, CERN
1
k.n.sjobak (a-with-pig’s-tail) fys.uio.no
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
1 / 21
Introduction New features Summary
Outline
1 Introduction to the TbMon offline analysis framework
Introduction
Installing and configuring
Analysis classes
2 New features
Simple key-value command line interface
Command line usage
Implementing new keys
Simulation extensions
3 Summary
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
2 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
The TbMon offline analysis framework: What is it?
A skeleton program for making it easier to extract useful
information from testbeam data – So that you can do your analysis
without thinking (so much) about technicalities like loading the
data, skipping bad data, looping over discontinuous sets of data,
finding clusters, etc.
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
3 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Data from one
experiment
event
Run
event
event
event
Each event contains:
● Digits from DUTs
● Track information from telescope
● Timing information from HPTDC
● etc.
Results:
99,6 %
efficiency
...
event
Run
event
event
event
event
er
ov
op ts
Lo even
...
event
event
...
...
File handling
Run
event
TbMon:
Unpacking
&
formatting
Quality cuts,
cluster finding,
etc.
Analysis
Analysis
Analysis
...
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
4 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Short glossary of TbMon
Configuration A set of data files from one experiment, and a list of
the EventBuilders needed to handle them
EventBuilder Class that formats data, makes quality cuts, finds
clusters etc; preparing the data for analysis
Analysis Class that receives nicely formatted data, and makes
plots etc. One instance is created per active DUT.
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
5 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Downloading and installing TbMon
Warning:
UNIX operating system with working ROOT installation assumed
1
cd to a suitable folder
2
Checkout from SVN:
svn co svn+ssh://<CERN-USER>@svn.cern.ch/reps/
atlas3dpix/tbonline/trunk
Source-code now stored in new subfolder trunk
3
Get the data for your experiment
4
Configure for your setup (see next slide)
5
Compile: run make in trunk folder
Don’t check things to back into the SVN tree
that isn’t working or is site-specific!
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
6 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Downloading and installing TbMon
Warning:
UNIX operating system with working ROOT installation assumed
1
cd to a suitable folder
2
Checkout from SVN:
svn co svn+ssh://<CERN-USER>@svn.cern.ch/reps/
atlas3dpix/tbonline/trunk
Source-code now stored in new subfolder trunk
3
Get the data for your experiment
4
Configure for your setup (see next slide)
5
Compile: run make in trunk folder
Don’t check things to back into the SVN tree
that isn’t working or is site-specific!
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
6 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Downloading and installing TbMon
Warning:
UNIX operating system with working ROOT installation assumed
1
cd to a suitable folder
2
Checkout from SVN:
svn co svn+ssh://<CERN-USER>@svn.cern.ch/reps/
atlas3dpix/tbonline/trunk
Source-code now stored in new subfolder trunk
3
Get the data for your experiment
4
Configure for your setup (see next slide)
5
Compile: run make in trunk folder
Don’t check things to back into the SVN tree
that isn’t working or is site-specific!
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
6 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Configure your setup
TbMon needs to know where you have stored the data. This is
done with the file siteconfig.h, stored in the trunk folder.
1
2
Copy siteconfig.h.example to siteconfig.h
In siteconfig.h, you will find a lot of “blocks” like this:
#define SITEEUDET2009_SET
void siteEudet2009(TbConfig &config) {
trySet(config.dataPath, (char*) "/home/haavagj/pixel/tb2009/eudet/results");
}
3
4
5
6
For the configurations (experiments) you have data from and
want to use:
Change the path to the folder containing the .root files
For the configurations you are not interested in:
Comment out the line containing the #define.
Take a look at the function siteconfig(...);
it defines default output paths etc.
Save your newly created siteconfig.h ^
¨
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
7 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Compile and test
• If everything has been done correctly, and you have the
dependencies and tools installed, and there is a full moon:
Compile it by running make in the trunk folder.
• If it compiles successfully, you can try to run it:
$ mkdir anaDemo_outdata
$ ./tbmon -c may2009 -l runlists/may2009-boff-a0
-i 164 -o anaDemo_outdata/ -a beamprofile sumtot
efficiency
• This should produce a lot of output in the subfolder
anaDemo_outdata (see next slide)
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
8 / 21
Introduction New features Summary
Kyrre Ness Sjøbæk
Introduction Installing and configuring Analysis classes
TbMod analysis framework
June 2010 EUDET tutorial
9 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Doing analysis with TbMon:
The anatomy of an analysis class
An analysis class is an implementation of the interface class
TbAnalysis, which defines the following functions:
init(TbConfig &config)
Stuff to be done before anything else
initRun(const TbConfig &config)
Stuff to be done at the beginning of each run
event(const TbConfig &config, const Event &event)
How to process an event
finalizeRun(const TbConfig &config)
Stuff to be done at the end of each run
finalize(const TbConfig &config)
Stuff to be done after all events have been processed
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
10 / 21
Introduction New features Summary
Introduction Installing and configuring Analysis classes
Doing analysis with TbMon:
Implementing an analysis class
1
Create .h and .cc files in folders trunk/analysis/include
and trunk/analysis/src
2
In the header: Include “tbanalysis.h”, and define a class
inheriting from TbAnalysis, implementing its virtual
methods. Remember header guards!
3
In the .cc file: Include the header, and implement the class.
4
In driver.cc: Include the header file, and add the analysis in
the method allAnalyses(...)
5
In the Makefile: Add your analysis to the end of the line
starting with ANALYSIS
6
Compile, run with ./tbmon (blahblah) -a yourAnalysis
Look to already existing analysis for inspiration,
such as clusize.h/.cc and beamprofile.h/.cc.
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
11 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Simple key-value command line interface
Why:
Make it simple to pass configurations to an analysis or eventBuilder
Usage:
New “family” of command line arguments to TbMon:
$ ./tbmon <blah blah> -P:<key> <value>
Example
Set the track χ2 cut value to 10.0:
$ ./tbmon <blah blah> -P:G_chi2cut 10
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
12 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Simple key-value command line interface
Why:
Make it simple to pass configurations to an analysis or eventBuilder
Usage:
New “family” of command line arguments to TbMon:
$ ./tbmon <blah blah> -P:<key> <value>
Example
Set the track χ2 cut value to 10.0:
$ ./tbmon <blah blah> -P:G_chi2cut 10
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
12 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Simple key-value command line interface
At the beginning of processing, TbMon writes out currently used
keys, together with their current value and a short description:
[ TbConfig ]; Parameter arguments pushed onto cmdLineExtras:
KEY
VALUE
DESCRIPTION
B_simDutRunner_model
Full3D_Vadim
Name of model wanted. Leave to default ("passt
B_simTruthBuilder_truthTrack
False
Use truth info for position estimation in devi
G_chi2cut
3
Mark tracks with chi2 > this value as bad
SD_Full3D_Vadim_R_bias
5
Radius of bias electrodes
[u
SD_Full3D_Vadim_R_readout
5
Radius of readout electrodes
[u
SD_Full3D_Vadim_S_bias
0.5
Efficiency fall-off distance around bias
[u
SD_Full3D_Vadim_S_readout
0.5
Efficiency fall-off distance around readout [u
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
13 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
The TbConfig class provides a set of functions use to get
arguments of different kinds, or just set the default:
Get double data:
double cmdLineExtras_argGetter(string key,
double defaultValue, string describeText);
Get string data:
string cmdLineExtras_argGetter(string key,
string defaultValue, string describeText);
Get bool data:
bool
cmdLineExtras_argGetter(string key,
bool defaultValue, string describeText);
The data and description text is stored in hash maps
TbConfig::cmdLineExtras and TbConfig::cmdLineExtras_help
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
14 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
The TbConfig class provides a set of functions use to get
arguments of different kinds, or just set the default:
Get double data:
double cmdLineExtras_argGetter(string key,
double defaultValue, string describeText);
Get string data:
string cmdLineExtras_argGetter(string key,
string defaultValue, string describeText);
Get bool data:
bool
cmdLineExtras_argGetter(string key,
bool defaultValue, string describeText);
The data and description text is stored in hash maps
TbConfig::cmdLineExtras and TbConfig::cmdLineExtras_help
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
14 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
The TbConfig class provides a set of functions use to get
arguments of different kinds, or just set the default:
Get double data:
double cmdLineExtras_argGetter(string key,
double defaultValue, string describeText);
Get string data:
string cmdLineExtras_argGetter(string key,
string defaultValue, string describeText);
Get bool data:
bool
cmdLineExtras_argGetter(string key,
bool defaultValue, string describeText);
The data and description text is stored in hash maps
TbConfig::cmdLineExtras and TbConfig::cmdLineExtras_help
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
14 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
As shown on the previous slide, there are currently implemented
three overloaded argGetter functions for simple datatypes.
Warning:
To use the the string argument getter, make sure to explicitly pass
a string input argument:
string myVar=cmdLineExtras_argGetter("A_myAna_myKey",
string("MyDefault"), "describeText")
Else it will end up selecting
bool cmdLineExtras_argGetter (char*,bool,char*)
because of C++ datatype rules.
If you want to implement more argGetters, look at tbconfig.cc
source-code. Histogram support range would be nice ^
¨
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
15 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
As shown on the previous slide, there are currently implemented
three overloaded argGetter functions for simple datatypes.
Warning:
To use the the string argument getter, make sure to explicitly pass
a string input argument:
string myVar=cmdLineExtras_argGetter("A_myAna_myKey",
string("MyDefault"), "describeText")
Else it will end up selecting
bool cmdLineExtras_argGetter (char*,bool,char*)
because of C++ datatype rules.
If you want to implement more argGetters, look at tbconfig.cc
source-code. Histogram support range would be nice ^
¨
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
15 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
As shown on the previous slide, there are currently implemented
three overloaded argGetter functions for simple datatypes.
Warning:
To use the the string argument getter, make sure to explicitly pass
a string input argument:
string myVar=cmdLineExtras_argGetter("A_myAna_myKey",
string("MyDefault"), "describeText")
Else it will end up selecting
bool cmdLineExtras_argGetter (char*,bool,char*)
because of C++ datatype rules.
If you want to implement more argGetters, look at tbconfig.cc
source-code. Histogram support range would be nice ^
¨
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
15 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
Example
Getting/setting the χ2 -cut for chi2builder:
cutVal = c o n f i g . cmdLineExtras_argGetter ( " G_chi2cut " ,
chi2default ,
" Mark t r a c k s w i t h c h i 2 > t h i s v a l u e a s bad " ) ;
Naming rules for keys (avoiding clashes):
Builders: B_<builderName>_<variableName>
Analysis: A_<analysisName>_<variableName>
SimDuts: SD_<modelName>_<variableName>
Global: G_<variableName>
Globals must only by read/set once in the code, but where might
be depending on configuration: Both BAT and EUDET data can
use a χ2 cut, but might do this in different places.
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
16 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
Example
Getting/setting the χ2 -cut for chi2builder:
cutVal = c o n f i g . cmdLineExtras_argGetter ( " G_chi2cut " ,
chi2default ,
" Mark t r a c k s w i t h c h i 2 > t h i s v a l u e a s bad " ) ;
Naming rules for keys (avoiding clashes):
Builders: B_<builderName>_<variableName>
Analysis: A_<analysisName>_<variableName>
SimDuts: SD_<modelName>_<variableName>
Global: G_<variableName>
Globals must only by read/set once in the code, but where might
be depending on configuration: Both BAT and EUDET data can
use a χ2 cut, but might do this in different places.
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
16 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Key-value command line interface: Implement your own!
Example
Getting/setting the χ2 -cut for chi2builder:
cutVal = c o n f i g . cmdLineExtras_argGetter ( " G_chi2cut " ,
chi2default ,
" Mark t r a c k s w i t h c h i 2 > t h i s v a l u e a s bad " ) ;
Naming rules for keys (avoiding clashes):
Builders: B_<builderName>_<variableName>
Analysis: A_<analysisName>_<variableName>
SimDuts: SD_<modelName>_<variableName>
Global: G_<variableName>
Globals must only by read/set once in the code, but where might
be depending on configuration: Both BAT and EUDET data can
use a χ2 cut, but might do this in different places.
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
16 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
A few words on the TbMon simulation extensions
Actual experiment hardware
Tracks
Entries
Mean
RMS
123745
58.83
22.35
3500
3000
2500
2000
1500
1000
Beam
500
Digits
Detectors
tbreco:
Allignment
and
reconstruction
Simulation
Energy
deposits
0
0
20
40
60
80
100
120
140
Cluster charge [ToT]
DAQ/trigger
TbAna:
Simulation of
trigger,
detector responce,
and DAQ
Digits
ntuples
tbmon:
Analysis
framework
Simulation−
extensions:
Truth and
DUT model testing
TestBeamSim (Geant4)
Energy deposits, Truth
• Enables access to raw simulation data from TbMon analysis
(charge clusters and particle track truth)
• Enables testing of DUT models
(efficiency functions, charge-sharing etc.)
• BUT: Currently the simulation covers BAT telescope only. . .
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
17 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
A few words on the TbMon simulation extensions
Actual experiment hardware
Tracks
Entries
Mean
RMS
123745
58.83
22.35
3500
3000
2500
2000
1500
1000
Beam
500
Digits
Detectors
tbreco:
Allignment
and
reconstruction
Simulation
Energy
deposits
0
0
20
40
60
80
100
120
140
Cluster charge [ToT]
DAQ/trigger
TbAna:
Simulation of
trigger,
detector responce,
and DAQ
Digits
ntuples
tbmon:
Analysis
framework
Simulation−
extensions:
Truth and
DUT model testing
TestBeamSim (Geant4)
Energy deposits, Truth
• Enables access to raw simulation data from TbMon analysis
(charge clusters and particle track truth)
• Enables testing of DUT models
(efficiency functions, charge-sharing etc.)
• BUT: Currently the simulation covers BAT telescope only. . .
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
17 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Files and variables for simulation: A reference
General rule
Anything with a name starting with “sim” is related to simulation
Configuration: Additions to siteconfig
Setting a new DataPath,
which specifies where to find extra sim data:
t r y S e t ( c o n f i g . simDataPath , ( c h a r ∗ ) " / p a t h / t o / s i m R a w H i t s " )
Flag for specifying that this configuration has extra sim data:
c o n f i g . i s S i m u l a t i o n = true
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
18 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Files and variables for simulation: A reference
General rule
Anything with a name starting with “sim” is related to simulation
Configuration: Additions to siteconfig
Setting a new DataPath,
which specifies where to find extra sim data:
t r y S e t ( c o n f i g . simDataPath , ( c h a r ∗ ) " / p a t h / t o / s i m R a w H i t s " )
Flag for specifying that this configuration has extra sim data:
c o n f i g . i s S i m u l a t i o n = true
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
18 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Files and variables for simulation: A reference
Configuration: TbConfig
A few new variables added for pointing to data paths,
synchronizing event numbers etc.
Event object
A few things has been added,
mostly inside its own “auxilary” object
simDataKeeper* Event::simData which is NULL for real data.
In addition to this, there is a “goodness” flag fSimSync, which is
kGood if SimBaseBuilder was successful in syncing
reconstructed- and raw-data.
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
19 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Files and variables for simulation: A reference
Configuration: TbConfig
A few new variables added for pointing to data paths,
synchronizing event numbers etc.
Event object
A few things has been added,
mostly inside its own “auxilary” object
simDataKeeper* Event::simData which is NULL for real data.
In addition to this, there is a “goodness” flag fSimSync, which is
kGood if SimBaseBuilder was successful in syncing
reconstructed- and raw-data.
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
19 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Files and variables for simulation: A reference
EventBuilders
Three eventbuilders is used for getting simulation data:
simBaseBuilder Finds the data folders, synchronizes pre- and postreconstruction event numbers
simTruthBuilder Gets truth data (impact position etc.)
simPixelEdepBuilder Gets charge cluster data
Additionally, there is one builder called “simDutRunner” that
executes simDuts and insert their output (simulated pixel digits)
into the events.
SimDuts
These classes contains models of DUTs (efficiency functions,
charge sharing, timing etc.).
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
20 / 21
Introduction New features Summary
Key-value command line interface Simulation extensions
Files and variables for simulation: A reference
EventBuilders
Three eventbuilders is used for getting simulation data:
simBaseBuilder Finds the data folders, synchronizes pre- and postreconstruction event numbers
simTruthBuilder Gets truth data (impact position etc.)
simPixelEdepBuilder Gets charge cluster data
Additionally, there is one builder called “simDutRunner” that
executes simDuts and insert their output (simulated pixel digits)
into the events.
SimDuts
These classes contains models of DUTs (efficiency functions,
charge sharing, timing etc.).
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
20 / 21
Introduction New features Summary
Summary
• The TbMon framework is useful for analyzing testbeam data
• Re-read this presentation for getting started
• Some new features have been added:
• Key-value command line interface to builders and analyses
• Simulation extensions
• If you can’t get it to work, try asking Håvar Gjersdal2 or me.
2
hgjersdal (a-with-pig’s-tail) gmail.com
Kyrre Ness Sjøbæk
TbMod analysis framework
June 2010 EUDET tutorial
21 / 21