ST Vetra Analysis

This page contains all information about the STVetraAnalysis package v3r2 version, for older version please read LHCbSTVetraAnalysisOld.

If you want to know how to build a ST Vetra conditions database from scratch and how make it useful for TELL1 configuration, have a look at the STVetraCondHowTo.

This package is designed to determine the ST TELL1s thresholds, pedestal values and masks and the disabled beetles and beetle ports. Scripts are provided to handle the different outputs and write the obtained values in the database(s). Finally, a set of python scripts allow to compare the values in different databases.

Here is the list of required packages (be sure you're using the head version) :

• ST/STVetraAnalysis
• ST/STTELL1Event
• Det/DetDesc
• Det/DetCond
• Det/STDet
• ST/STKernel
• Tell1/VetraKernel

STVetraAnalysis contains the following algorithms :

• Noise per sector computation (produce xml that goes into DDDB).
• Header correction values computation (by Jeroen).
• Pedestal extraction and formatting.
• Dumping the Vetra Cond DB in a xml file.
• Noise cluster rate.

The brand new Configuration.py file allows you to configure common tasks in a very easy way!

The package contains also python scripts, which allow you to :

• create a dummy DB-like xml file,
• compare a given set of databases (DDDB, LHCBCOND, Vetra Cond DB),
• use the noise values from LHCBCOND to update the thresholds in Vetra Cond DB

Finally, some perl scripts are included in the package as well :

• one that makes comparison between any pair of xml files
• one to configure the DB comparison
• one to rewrite the Vetra Cond DB xml file in a more user-friendly look.

I added an 'options' directory, containing a default options file, which is copied and modified when you are comparing DBs. The directory contains also a Config.xml file, used to produce the data structure and the TTrees used to compare DBs.

In order to run any Vetra Analysis algorithm, the data have to be decoded first, using STFullDecoding (ST/STOnline). You'll also need a condition DataBase, follow the basic instruction given by Tomasz here or Anne here. If you want to get noise and cluster rate, the Emulator has to be run as well.

ST condition database

First, you need to create the xml files, using write_st_xml_cond for both IT and TT. Then source the two following bash scripts : create_it_sqlite_file_from_xml.sh and create_tt_sqlite_file_from_xml.sh. Now your database is ready. Note that the condition path you have to give to the Emulator is just "CondDB". For intance, if you want to run on IT data, the DB-related options are :

#include "$DDDBROOT/options/DDDB.opts"

CondDBCnvSvc.CondDBReader = "CondDBLayeringSvc";
CondDBLayeringSvc.Layers = {"CondDBAccessSvc/COND",
                            "CondDBDispatcherSvc"};

COND.ConnectionString = "sqlite_file:$VETRAROOT/VetraCondDB/ITCOND.db/COND";

All you have to change when running on TT data is the connection string (replace "IT" with "TT").

The Algorithms

STScanner

This algorithm counts the number of found clusters and gives the cluster rate (based on the EventInfo, may thus be wrong if the PCN is bugged).

ApplicationMgr.TopAlg = { "STFullDecoding", "ProcessPhase/Emulator", "ProcessPhase/Reco", "STScanner/Scan" };

Emulator.DetectorList += { "ST" };
EmulatorSTSeq.Members += { "STTELL1PedestalSubtractor", "STTELL1LCMS", "STTELL1ClusterMaker" }; 

Reco.DetectorList+={"TT"};
RecoTTSeq.Members += {"RawBankToSTClusterAlg/Clustering"};
Clustering.detType            = "TT";
Clustering.rawEventLocation   = "Emu/RawEvent";
Clustering.clusterLocation    = "Emu/TT/Clusters";
Clustering.readoutTool        = "TTReadoutTool";


Scan.DetType = "TT"; 

The cluster rate and number are printed. Histograms are produced :

• one containing the number of cluster per event (1D histo, called clusternbr)
• one containing the size of each found cluster (1D histo, called clustersize)
• one containing the number of n-strip clusters per TELL1 board (2D histo, called strip)
• one per TELL1, containing the number of n-strip cluster per channel (2D histo, called ChanXY)

STPedestalWriter

This algorithm updates the pedestal values in the memory (these values are managed by STVetraCfg tool). Once the update is done, STVetraCondDBWriter must be ran in order to dump the update values into a xml file.

STNoiseMonitor

This algorithm computes the noise as a double value. The noise values are then updated via the STReadoutTool and written by WriteSTNoiseConditions in a xml file.

The python scripts

write_st_xml_cond python script

I added a python script that creates a DB-like xml file, containing dummy values (ie all Hit thresholds are 6, etc). It can create the xml file for both IT or TT. The chosen detector as to be passed in argument :

./write_st_xml_cond.py IT 

The file will be written in the default DataBase location, but the path can be changed by editing line 22

XmlFileName = ... 

An alias has also been added, and you can run the script with

write_st_xml_cond 

CompareDBs python script

The script will create a root file containing the comparison between all the possible pairs of databases you've given as arguments. The mandatory arguments are the tags for the database, which are not the actual tag of the DB version, but will be used to know what DB we are talking about. Dummy example are Old, New, Custom, ... You can specify the tag names with the --tag (or -t) option. Another mandatory field is the sub-detector type, specified by --sub (or -s).

The databases you can compare are DDDB, LHCBCOND and Vetra Cond DB. You can choose to compare different version of only one slice. For instance, if you only want to compare the noise value per strip, the only needed DB is LHCBCOND, the script will let the default DDDB and Vetra Cond DB. The different slices can be specify by --dddb (-d), --cond (-c) and --vetra (-v). The number of DB you give to the script must be equal to the number of tags, and if you give more than one slice, the numbers have to be equal.

You can give file names (two will be produced), with --file (-f) option. The first file will contain one TTree per DB, the second one one TTree containing compared values per pair of DB.

The script uses Utils.py module, included in the package to create a C++ struct and TBranch definitions. An option file is written (from options/DefaultDB.opts, included as well) and a second python script is called, which will read on DB and fill a TTree. The second script is called once per set of databases. Once all the DBs are read, CompareDBs will produce one TTree per possible comparison (if 2 DBs => 1, 3 => 2, ...).

If you want some other values to be read and compared, please modify options/Config.xml. You can add branches. The name will be the name of the leaf and of the structure field. The type is the data type (int or float), and you can decide whether the value will be compared (for instance you want to compare noise) or not (you don't want to compare TELL1 source ID, but you want to keep this information). The data field is the method used to get the value. The method in which this will be included has the following arguments :

• stTool, the STReadoutTool
• vetraTool, the VetraCfg tool
• mSector, the presently processed DeSTSector
• tell1ID, the TELL1 source ID (unsigned int)
• strip, the strip number in the sector (from 1 to nStrip())
• channel, the TELL1 strip number (from 0 to 3071)
• svcBox, a flat number constructed from the service box name
• stChanID, the STChannelID of the strip, which allows you to access the station, detector region, etc..
• vals, the list were all the fields you need will be stored before they are written the structure of type Data

For instance, if you want to compare the changes applied to the disabled beetles, add the line

<branch name="DisBeetle" type="int" comparison="yes"> vCond.disableLinksPerBeetle().at( channel / 128 ) </branch>

Note that you don't need to retrieve the STVetraCondition yourself : a STVetraCondition named vCond is provided automatically.

UpdateVetraCondFromLHCBCOND python script

This script reads the LHCBCOND and updates Vetra Cond DB with new thresholds and pedestal masks. It is configured by command-line options, -x option :

Long option prefix	Short option prefix	action
--cond	-c	path string to LHCBCOND file (optional), the tag to be used can also be given
--vetra	-v	path string to ST Vetra Cond DB file (mandatory)
--file	-f	name of output file (mandatory)
--sub	-s	subdetector type : either IT or TT (mandatory)
--help	-h	print some help

The threshold and the strips to be masked are tuned via a python module, ConfigUpdate.py. In this small python file two arrays are defined : MaskFromDB, which contains the status of the strips that will be masked and ThresholdsAndValues. The latter array has a specific syntax. The elements are somehow grouped by block of three. Each of these blocks has a string member, which is the name of the threshold, then a double, which is the multiplication factor applied to the noise in order to get the threshold value, and finally a integer number, which is the number of threshold for one TELL1. Here below is an example that sets the hit threshold to 3 times the noise, the CMS threshold to 4 times the noise (one threshold per strip) and the confirmation threshold to 5 times the noise and the spill over threshold to 10 times the noise (one threshold per processing channel ie 64 strips) :

ThresholdsAndValues = [ "cms_threshold"         ,  4., 3072,
                        "hit_threshold"         ,  3., 3072,
                        "confirmation_threshold",  5., 48,
                        "spill_over_threshold"  , 10., 48 ]

Perl scripts

DumpNoiseIntoConditions perl script

Allows you to put a file produced with STNoiseMonitor in its right place, taking care of the non-present sectors. The syntax is

DumpNoiseIntoConditions input_file output_file

GetDBChanges perl script

Allows to compare two versions of the same file (xml or txt). The file is not requested to contain only one parameter (ie you can process TELL1Cond.xml for instance) you have ot specify the files names of course, the xml tag you want to compare and a tolerance. You can also specify a logfile name (the default one is "log"). The syntax is :

GetDBChanges.pl oldfile newfile tagname [epsilon] [logfile]

It's important to know which file is the old and the new one, since the logfile will tell you what was removed from the old and what was added to the new one. The tagname can be whatever you want ("Pedestal_mask", "Hit_threshold", ...). The espilon is used to do comparison : the default value is 0. The logfile will contain all the information. For help use the "-h" or "--help" option.

WriteUtils perl script

Allows to customise the database comparison. It reads the Config.xml file (in options directory) and produce as an output a modified version of Utils.py.

DBCosmetics perl script

Allows to make the output of STVetraCondDBWriter easier to read : the original file has each condition on one line! The script takes a xml file as argument and creates a new file (which name corresponds to the input filename with a ".new" append). This new file has one parameter (param or paramVector) per line.

Job options

Shared job options

The following options are common to all algorithms :

Option Name	Default value
DetType	"IT"
InputLocation	"Raw/IT/LCMSADCs"
OuputFileName	"Thresholds.txt"
WaintingTill	1000
ProduceFile	false
UnwantedTELL1s	{}
ConditionLocation	"CondDB/TELL1Board"

• DetType can be set to "IT" ot "TT", a wrong value will stop the algorithm's execution.
• InputLocation is the name of the TELL1 container.
• WaitingTill acts as ConvergenceLimit in the Emulator, use the same value as you put in the Emulator.
• ProduceFile toggle on/off the creation of the output file.
• If the file you're using contains some TELL1 you don't care about, just add the TELL1 IDs in UnwantedTELL1s in the following way :

   ST.UnwantedTELL1s = { 8, 49}; 

• The ConditionLocation is the path to the condition DB, which shouldn't need to be changed.

All the options related to location are now STConfigProperties, ie you don't have to set them if the only change is running over TT instead pf IT. The base class will do it automatically for you.

Header correction options

Option Name	Default value
HeaderThreshold	129
SubtractCM	true
NumChannels	6

The HeaderThreshold is the threshold under (resp. above) which the header is considered to be negative (resp. positive). The SubtractCM enables a common mode subtraction (warning, this is not the way the TELL1 is doing the CM subtraction!!). NumChannels specifies the number of strips you want to correct. Please don't change the value unless you really know what you're doing!

Scanner options

For this algorithm we have only one option :

 ClusterLocation 

which default value is "Emu/IT/Clusters". This is the location in TES where the clusters are stored.

Pedestal writer options

There is no specific options.

Noise monitoring options

This is the list of options :

Option Name	Default value
ConstantFactor	776.
SlopeFactor	47.9
NbrDigits	2
ElectronsPerADC	false

• The constant and slope factors are used to compute the number of electrons due to noise from the capacitance C ie :
  
  where the constant factor is b and the slope is a.
• The number of digits is the number of decimals that will be stored in the DB.
• The ElectronsPerADC bool value toggles on / off the production of the ElectronPerADC value in the output file.

The configurable

The configurable was designed to make common tasks easier. With this configurable you can :

1. update Vetra Cond DB with new pedestal values.
2. update Vetra Cond DB with new header correction values.
3. update LHCBCOND with new noise values.

The options are given in the table below.

Option Name	Meaning	Default value
EvtMax	Maximum number of events to process	-1
SkipEvents	Number of events to skip	0
PrintFreq	The frequency at which to print event numbers	1
OutputLevel	The printout level to use	INFO
EmulatorOutLvl	The printout level to use for the emulator algorithms	INFO
VetraOutLvl	The printout level to use for ST Vetra processing algorithms	INFO
WriterOutLvl	The printout level to use for writing algorithms	INFO
PrintErrors	Don't print the errors from STFullDecoding	False
DatasetName	String used to build output file names	"STVetra"
DDDBtag	Tag for DDDB	""
CondDBtag	Tag for Cond DB	""
VetraCondDB	Path to ST Vetra Cond DB	""
DetType	Detector type, can be one of [ 'IT', 'TT' ]	"IT"
Process	Chosen action, can be one of self.KnownProcesses	"Noise"
Convergence	Convergence limit, used to get pedestal convergence	10000
MainSequence	List of main sequences	""
XMLAuthor	Author of the xml file (to be filled!)	""
XMLTag	'Tag' of the xml file, which is not supposed to be a real tag (to be filled!)	""
XMLDescription	Please put here something that helps to know what are the input 'conditions', like run nbr, ... (to be filled!)	""

When you want to update the pedestal values, the meaning of "Convergence" option is a bit changed : it's the first event from which the tool will try to write the values. Once the values are written for all the TELL1s, the algorithm won't do anything more. If the used file contains only NZS, a reasonable value is the total number of events minus 5. The XMLAuthor, XMLTag and XMLDescription are mandatory! If one of them is not set, the job won't begin. The VetraCondDB is also mandatory, since the default LHCbApp doesn't know anything about it!

-- JohanLuisier - 28 Apr 2009
Latex rendering error!! dvi file was not created.