 |
KaliVeda
Toolkit for HIC analysis
|
|
KaliVeda
Toolkit for HIC analysis
|
Here are some guidelines for analysing data. Data can either be raw experimental data, reconstructed experimental data, or simulated data, either filtered with a given experimental setup (in which case it is again reconstructed data) or not.
Each data analysis requires a user analysis class to define the tasks to be performed, histograms/trees to fill etc. The user's analysis class is piloted by a class derived from KVDataAnalyser which handles opening the data files requested by the user and setting up the necessary environment for the analysis to proceed.
Two graphical interfaces are provided for analysing data: KaliVedaGUI and kaliveda-sim. Both interfaces are capable of generating example analysis classes for the data you want to analyse. This is the recommended method for creating a new analysis class, which you can then modify according to your needs.
N.B. In the case of experimental data, the exact inheritance required for your analysis class to work may depend on the dataset being analysed. This is handled automatically when generating a new class with
KaliVedaGUI
When analysing experimental data with KaliVedaGUI, different analysis tasks appear in the drop-down menu depending on the types of available data. Here is a brief explanation of each task.
raw data is data written during the experiment, i.e. the files produced by the DAQ system. Several analysis tasks are possible:
Analysis() method (see below) is called after each event is read from the DAQ file. It is the user's responsibility to test whether any useful information was actually present in the event by testing gMultiDetArray->HandledRawData() before proceeding with any analysis (in case the data being read comes from several independent detector arrays, this method returns kTRUE if at least one of the arrays in the set-up found data it could handle; you can test individual arrays with gMultiDetArray->GetArray([name])->HandledRawData() - see class KVExpSetUp). Values of acquisition parameters etc. will be set in the detectors of the array(s) which fired in the event. Other useful information may be stored in the KVNameValueList returned by gMultiDetArray->GetReconParameters() (or the equivalent for one of the individual arrays in case of a multi-array setup).recon data files from raw data (no user analysis is possible). Event reconstruction is handled by the KVEventReconstructor class which manages a set of KVGroupReconstructor-derived objects which may be specialised for particle reconstruction in the groups of each multidetector array (a group corresponds to the largest subset of detectors which can be treated independently of all others in the array - see Using Detector Array Geometries). The reconstructed events are written in a ROOT TTree in a new file. The generated data can be analysed using the reconstructed data analysis tasks presented below.Analysis() method is called. It is the user's responsibility to test whether any useful information was actually present in the event by testing gMultiDetArray->HandledRawData() : if it returns kTRUE then the reconstructed event can be accessed using method GetReconstructedEvent().Reconstructed data is contained in ROOT TTrees generated by the Event reconstruction from raw data task presented above. Specifically, for each DAQ event a KVReconstructedEvent is filled with KVReconstructedNucleus objects which are deduced from the detector hits and the array geometry.
User Class list select [NEW]. You will be asked to provide a name for your new analysis class, then the newly-generated template files will be opened in your favourite text editor.New simulated analysis class or New filtered analysis class, depending on which kind of data you want to analyse. You will be asked to provide a name for your new analysis class, which you can then open in your favourite text editor (it isn't automatic).Whatever kind of data you wish to analyse, you will now have a more-or-less complete example of an analysis class contained in the files MyClass.h and MyClass.cpp (assuming you replied MyClass when asked for a name for the class). The exact heritage of this class will depend on the kind of data being analysed, but in all cases it will have the following 5 methods:
InitAnalysis() and EndAnalysis() are executed once only at the beginning and end, respectively, of the analysis. InitRun() and EndRun() are called at the beginning and end, respectively, of each data file which is being analysed. Analysis() is called for each and every event read from the files. Each of these methods in your MyClass.cpp file should contain useful comments and/or examples of use.
It should be noted that for all except raw data analysis (i.e. for all data stored in ROOT trees), the analysis classes inherit from KVEventSelector which allows them to be used with PROOF on multi-core machines. It is important to read the guidelines given in the KVEventSelector class reference for this to work.
The user's analysis class can acces the KVDataAnalyser object which is running the analysis through the gDataAnalyser global pointer (see below).
This is the place to create/open any ROOT files, histograms, trees etc. you require in order to store the output of your analysis. Also the place to define any Global Variables needed for the analysis: see the dedicated chapter for more details. Also see the examples given and comments in the example analysis classes.
If you are analysing reconstructed experimental/simulated data, do not try to access the experimental set-up (gMultiDetArray, etc.) associated with the data you want to analyse here - it will not be defined until InitRun().
Called once at the beginning of each new data file. In case of analysing experimental reconstructed data you can access the experimental set-up (gMultiDetArray, system being analysed, run number, etc.) associated with the data here if you need to:
For reconstructed data of either experimental or filtered simulated type, you can access the kinematics of the collision system being analysed like so:
When analysing reconstructed data, InitRun() is the place to modify or fine-tune if you require the selections which will be applied to the particles of each event in order to include them in or exclude them from the analysis. These are the particles which will be used for the calculation of any global variables declared in InitAnalysis(), and those which will be labelled as "OK" (for example when iterating over the event).
The first selection applied is to consider "OK" only those particles which have acceptable identification codes (KVReconstructedNucleus::GetIDCode()) and calibration codes (KVReconstructedNucleus::GetECode()). For each multidetector array, default values of the acceptable codes are defined using configuration variables such as
where [name] is the name of the array and optionally the values can be dataset dependent.
To change the default acceptable codes for particles reconstructed by a given array to be used in your analysis, use
using the same format for the lists of codes as in the configuration variable example given above. If analysing data for a set-up consisting of several different detector arrays, you should use
replacing [name] by the appropriate array name.
For any other selections which need to be applied to exclude 'bad' particles from the analysis, you can use the KVParticleCondition class to define any number of selections based on particle properties which will be applied to all particles which passed the identification/calibration code selections.
Note that you cannot 'retrieve' a particle which has been excluded due to bad identification or calibration codes using a KVParticleCondition selection
These selections are then added to the analysis selection criteria using the SetParticleConditions() method:
See the example analysis classes for more examples. See the class reference for KVParticleCondition for usage.
This method is called once for each event to analyse. Implement the event-by-event analysis here.
During reconstructed data analysis, when this method is called
OK or not according to the criteria set in InitRun();OK particles, the CM centre-of-mass reference frame is defined;InitAnalysis() have been calculated using all OK particlesTo iterate over all or a subset of the particles of the event, see here.
There is usually no need to implement these methods.
1.9.1