]> git.uio.no Git - u/mrichter/AliRoot.git/blob - EMCAL/doc/analysis.tex
close file when reload
[u/mrichter/AliRoot.git] / EMCAL / doc / analysis.tex
1 \section{Analysis format and code}
2
3 All the reconstructed particles of all the detectors are kept
4 in a file called \textbf{AliESDs.root}. The detectors must store there
5 the most relevant information which will be used in the analysis. 
6 Together with the AliESDs.root file, another file is created with some reference tags of the simulated events, containing for example the number of events per run. This file is
7 named \textbf{Run0.Event0\_1.ESD.tag.root} (1 means that only 1 event
8 was simulated). 
9
10 In order to do the analysis with the data contained in the ESDs, the only file needed is \textbf{AliESDs.root} in the local directories or a grid collection. No other files are needed in the working directory (such as galice.root nor EMCAL.{*}.root) unless one needs to access the primary particles generated during the simulation. In that case, the files \textbf{galice.root} and \textbf{Kinematics.root} are needed locally.  Also, if one want to access to some information of the detector geometry, the \textbf{geometry.root} file is needed.
11
12 There are other data analysis containers created from the ESD, the
13 AOD (Analysis Object Data) with smaller quantity of data for most of the subsystems but for the calorimeters, where we copy all the information\footnote{until half 2012 everything but the time of the cells was stored}.
14
15
16 \subsection{Calorimeter information in ESDs/AODs}
17
18 The basic calorimeter information needed for analysis is stored in the ESDs or AODs in the form of CaloClusters and CaloCells (cell = EMCal Tower or PHOS crystal). Also there is some information stored in the AOD/ESD event classes, it will be detailed more in the lines below. Both AOD and ESD classes derive from virtual classes so that with a similar analysis code and access methods, we can read both kind of data formats.
19
20
21 \subsubsection{AliVEvent (AliESDEvent, AliAODEvent)}
22
23 Those are manager classes for the event information retrieval. Regarding the calorimeters they have the following access information (getters) methods\footnote{There are the equivalent setters just have a look to the header file of the class}:
24 \begin{itemize}
25
26 \item AliVCaloCluster *GetCaloCluster(Int\_t i) : Returns a CaloCluster listed in position "i" in the array of CaloClusters. It can be either PHOS or EMCal (PHOS list of clusters is before the EMCal list).
27
28 \item TClonesArray *GetCaloClusters() :  Returns the array with CaloClusters PHOS+EMCAL, Only defined for AODs
29
30 \item Int\_t GetEMCALClusters(TRefArray *clusters) ; Int\_t GetPHOSClusters(TRefArray *clusters) : Returns an array with only EMCal clusters or only with PHOS clusters.
31
32 \item Int\_t GetNumberOfCaloClusters(): Returns the total number of clusters PHOS+EMCAL.
33
34 \item AliVCaloCells *GetEMCALCells();  AliESDCaloCells *GetPHOSCells() : Returns the pointer with the CaloCells object for EMCal or PHOS.
35
36 \item AliVCaloTrigger *GetCaloTrigger(TString calo) : Access to trigger patch information, for calo="PHOS" or calo="EMCAL"
37
38 \item const TGeoHMatrix* GetPHOSMatrix(Int\_t i); const TGeoHMatrix* GetEMCALMatrix(Int\_t i): Get the matrices for the transformation of global to local. The transformation matrices are not stored in the AODs.
39
40
41
42 \end{itemize}
43
44
45
46 \subsubsection{AliVCaloCluster (AliESDCaloCluster,AliAODCaloCluster)}
47
48 They  contain the information of the calorimeter clusters. Note that PHOS and EMCAL CaloClusters are kept in the same TClonesArray (see above). The information stored in each CaloCluster is :
49
50 \begin{itemize}
51 \item General
52         \begin{itemize}
53         \item Int\_t GetID(): It returns a unique identifier number for a CaloCluster.
54
55         \item Char\_t GetClusterType():It returns kPHOSNeutral (kPHOSCharged exists but not used) or  kEMCALClusterv1. Another way to get the origin of the cluster:
56
57         \item Bool\_t IsEMCAL(); Bool\_t IsPHOS(). 
58
59         \item void GetPosition(Float\_t *pos) : It returns a {x,y,z} array with the global positions of the clusters in centimeters.
60
61         \item Double\_t E() : It returns the energy of the cluster in GeV units.
62
63         \item void GetMomentum(TLorentzVector\& p, Double\_t * vertexPosition ): It fills a TLorentzVector pointing to the measured vertex of the collision. It also modifies the cluster global positions to have a vector pointing to the vertex, this has to be corrected. Assumes that cluster is neutral. To be used only for analysis with clusters not matched with tracks.
64         \end{itemize}
65 \item Shower Shape
66         \begin{itemize}
67
68         \item Double\_t GetDispersion(): Dispersion of the shower.
69
70         \item Double\_t Chi2(): Not filled.
71
72         \item Double\_t GetM20()  Double\_t GetM02() : Ellipse axis.
73
74         \item UChar\_t GetNExMax() : Number or maxima in cluster. Not filled.
75
76         \item Double\_t *GetPID(): PID weights array, 10 entries corresponding to the ones defined in AliPID.h
77
78          \item enum EParticleType { kElectron = 0,  kMuon = 1, kPion = 2, kKaon = 3, kProton = 4, kPhoton = 5, kPi0 = 6, kNeutron =7, kKaon0 = 8, kEleCon = 9,kUnknown = 10}; : PID tag numbers, corresponding to the PID array
79
80         \item Double\_t GetDistanceToBadChannel() : Distance of the cluster to closest channel declared as kDead, kWarm or kHot.
81
82         \item Double\_t GetTOF() :  Measured Time of Flight of the cluster.
83         \end{itemize}
84
85 \item Track-Cluster matching
86         \begin{itemize}
87
88         \item TArrayI * GetTracksMatched(): List of indexes to the likely matched tracks. Tracks ordered in matching likeliness. If there is no match at all, by default it contains one entry with value -1. Only in ESDs.
89
90         \item Int\_t GetTrackMatchedIndex(Int\_t i): Index of track in position "i" in the list of indices stored in GetTracksMatched(). Only in ESDs
91
92         \item Int\_t GetNTracksMatched() : Total number of likely matched tracks. Size of GetTracksMatched() array.
93
94         \item Double\_t GetEmcCpvDistance() : PHOS method, not used anymore. Use instead those below.
95
96         \item Double\_t GetTrackDx(void), Double\_t GetTrackDz(void): Distance in x and z to closest track. 
97
98         \item TObject * GetTrackMatched(Int\_t i): References to the list of most likely matched tracks are stored in a TRefArray. This method retrives the one in position "i". Tracks are listed in order of likeliness. The TObject is a AliAODTrack. Only for AODs
99
100         \end{itemize}
101
102 \item MonteCarlo labels:
103         \begin{itemize}
104
105         \item TArrayI * GetLabels(): List of indexes to the MonteCarlo particles that contribute to the cluster. Labels ordered in energy contribution.
106
107         \item Int\_t GetLabel(): Index of MonteCarlo particle that deposited more energy in the cluster. First entry of GetLabels() array.
108         
109          \item Int\_t GetLabelAt(UInt\_t i): Index of MonteCarlo particle in position i of the array of MonteCarlo indices.
110
111         \item Int\_t GetNLabels() : Total number of MonteCarlo particles that deposited energy. Size of GetLabels() array.
112         \end{itemize}
113
114 \item Cluster cells
115         \begin{itemize}
116
117         \item Int\_t GetNCells() : It returns the number of cells that contribute to the cluster.
118
119         \item UShort\_t *GetCellsAbsId(): It returns the array with absolute id number of the cells contributing to the cluster. Size of the array is given by GetNCells().
120
121         \item Double32\_t *GetCellsAmplitudeFraction(): For cluster unfolding, it returns an array with the fraction the energy that a cell contributes to the cluster. 
122
123         \item Int\_t GetCellAbsId(Int\_t i) : It returns the absolute Id number of a cell in the array between 0 and GetNCells()-1. 
124
125         \item Double\_t GetCellAmplitudeFraction(Int\_t i) : It returns the amplitude fraction of a cell in the array between 0 and GetNCells()-1.
126
127         \end{itemize}
128
129  \end{itemize}
130
131
132 \subsubsection{AliVCaloCells (AliESDCaloCells, AliAODCaloCells)}
133 They   contain an array with  the amplitude or time of all the cells that fired in the calorimeter during the event. Notice that per event there will be a CaloCell object with EMCAL cells and another one with PHOS cells.
134
135 \begin{itemize}
136
137         \item Short\_t GetNumberOfCells(): Returns number of cells with some energy.
138         
139         \item Bool\_t IsEMCAL(); Bool\_t IsPHOS(); Char\_t  GetType(): Methods to check the origin of the AliESDCaloCell object, kEMCALCell or kPHOSCell.
140
141         \item Short\_t  GetCellNumber(Short\_t pos):  Given the position in the array of cells (from 0 to GetNumberOfCells()-1), it returns the absolute cell number (from 0 to NModules*NRows*NColumns - 1).
142
143         \item Double\_t GetCellAmplitude(Short\_t cellNumber): Given absolute cell number of a cell (from 0 to NModules*NRows*NColumns - 1), it returns the measured amplitude of the cell in GeV units.
144
145         \item Double\_t GetCellTime(Short\_t cellNumber):  Given absolute cell number of a cell (from 0 to NModules*NRows*NColumns - 1), it returns the measured time of the cell in second units.
146
147         \item Double\_t GetAmplitude(Short\_t pos): Given the position in the array of cells (from 0 to GetNumberOfCells()-1), it returns the amplitude of the cell in GeV units. 
148
149         \item Double\_t GetTime(Short\_t pos):  Given the position in the array of cells (from 0 to GetNumberOfCells()-1), it returns the time of the cell in second units. 
150
151         \item Double\_t GetCellMCLable(Short\_t cellNumber): Given absolute cell number of a cell (from 0 to NModules*NRows*NColumns - 1), it returns the index of the most likely MC label.
152
153         \item Double\_t GetCellEFraction(Short\_t cellNumber):  Given absolute cell number of a cell (from 0 to NModules*NRows*NColumns - 1), it returns the fraction of embedded energy from MC to real data (only for embedding)
154
155         \item  Double\_t GetMCLabel(Short\_t pos): Given the position in the array of cells (from 0 to GetNumberOfCells()-1), it returns the index of the most likely MC label.
156
157         \item Double\_t GetEFraction(Short\_t pos):  Given the position in the array of cells (from 0 to GetNumberOfCells()-1), it returns the fraction of embedded energy from MC to real data (only for embbedding)
158
159           \item Bool\_t   GetCell(Short\_t pos, Short\_t \&cellNumber, Double\_t \&amplitude, Double\_t \&time, Short\_t \&mclabel,    Double\_t  \&efrac); : For a given position of the list of cells, it fills the amplitude, time, mc lable and fraction of energy.
160           
161           
162  \end{itemize}
163
164 \subsubsection{AliVCaloTrigger (AliESDCaloTrigger, AliAODCaloTrigger) - Rachid)}
165
166 \subsection{Macros}
167 You can find example macros to run on ESDs or AODs in 
168 \begin{lstlisting}
169 $ALICE_ROOT/EMCAL/macros/TestESD.C or TestAOD.C
170 \end{lstlisting}
171
172  All the ESDs information is filled via the AliEMCALReconstructor/AliPHOSReconstructor class, in the method FillESD(). The AODs are created via the analysis class 
173
174 \begin{lstlisting}
175 $ALICE_ROOT/ANALYSIS/AliAnalysisTaskESDfilter.cxx,.h
176 \end{lstlisting}
177
178 and as already mentioned, for the calorimeters it basically just copies all the information from ESD format to AOD format. 
179
180 Below is a description of what information is stored and how to retrieve it. The location of the corresponding classes is
181 \begin{lstlisting}
182 $ALICE_ROOT/STEER
183 \end{lstlisting}
184
185
186
187 \subsection{Code example}
188
189 The analysis is done using the data stored in the ESD. The macro
190 \begin{lstlisting}
191 $ALICE_ROOT/EMCAL/macros/TestESD.C
192 \end{lstlisting}
193 is an example of how to read the data for the calorimeters PHOS and
194 EMCal (just replace where it says EMCAL by PHOS in the macro to obtain
195 PHOS data). For these detectors we have to use the ESD class AliESDCaloCluster or AliESDCaloCells to retrieve all the calorimeters information. For the tracking detectors,
196 the class is called AliESDtrack, but the way to use it is very similar
197 (see ``\$ALICE\_ROOT/STEER/AliESDtrack.*''\\ and ``\$ALICE\_ROOT/STEER/AliESDCaloCluster*'' for more details). In AliESDCaloCluster we keep the following
198 cluster information: energy, position, number of Digits that belong
199 to the cluster, list of the cluster Digits indeces, shower dispersion, shower lateral axis and a few more parameters. In AliESDCaloCells we keep the following
200 tower information: amplitude (GeV), time (seconds), absolute cell number.
201
202 The structure of the ESD testing macro (TestESD.C) is the
203 following:
204
205 \begin{itemize}
206 \item Lines 0-29: This macro is prepared to be compiled so it has ``includes'' to all the Root and AliRoot classes used.
207
208 \item Lines 30-36: This macro prints some information on screen, the kind of information is set here. We  print by default clusters information and optionally, the cells information, the matches information, the cells in the clusters information or the MonteCarlo original particle kinematics.
209
210 \item Lines 40-64: Here are the methods used to load AliESDs.root , geometry or kinematics files. Also loop on ESD event is here.
211
212 \item Lines 65-66 Gets the measured vertex of the collision.
213
214 \item Lines 69-78 Loops on all the CaloCell entries and prints the cell amplitude, absolute number and time.
215  
216 \item Lines 84- end:  We access the  EMCAL AliESDCaloCluster  array and loop on it. 
217 We get the different information from the CaloCluster.
218
219 \item Lines 111-130:  Track Matching prints. Access to the matched track stored in AliESDtrack.
220
221 \item Lines 133-159: Cells in cluster prints
222
223 \item Lines  161 - end: Access the stack with the MC information and prints the parameters of the particle that generated the cluster.
224
225
226 \end{itemize}
227
228 \subsection{Advanced utilities : Reconstruction/corrrections of cells, clusters  during the analysis}
229
230 \subsubsection{AliEMCALRecoUtils}
231 \subsubsection{Tender : AliEMCALTenderSupply}
232
233 \subsubsection{Particle Identification with the EMCal}
234
235 In the EMCal we have two different ways to obtain the PID of a given particle:
236 \begin{enumerate}
237 \item Shower shape of the cluster: Distinguish electrons/photons and $\pi^{0}$ from other particles. This is done without any track information in the class \texttt{AliEMCALPID}.
238 \item Ratio between energy of the cluster and the momentum of a matched track: Distinguish electrons from other particles. This is done in the combined PID framework by the class \texttt{AliEMCalPIDResponse}.
239 \end{enumerate}
240
241 \paragraph{AliEMCALPID (AliEMCALPIDutils)}
242
243 The idea for particle identification with EMCal clusters is that the shower shapes produced in the EMCal are different for different particle species. The long axis of the cluster ($\lambda_{0}$) is used for this purpose and parametrized for electrons/photons (should have the same electromagnetic shower), for $\pi^{0}$ (two photons merging in one cluster give a different shape than one photon), and hadrons (MIP signal).
244
245 The main method in this class is \texttt{RunPID()}, which calls \texttt{AliEMCALPIDutils::ComputePID(Double\_t energy, Double\_t lambda0)} for each cluster with cluster energy \texttt{energy} and long axis of the cluster \texttt{lambda0} in the event. Inside this method first the \texttt{energy} dependent parametrizations for the three cases (photons, $\pi^{0}$, and hadrons) are retrieved. The parametrization is done here with a combination of a Gaussian and a Landau (at the moment there are two parameter sets available: low and high flux, which can be set by \texttt{AliEMCALPID::SetLowFluxParam()} and  \texttt{AliEMCALPID::SetHighFluxParam()}). Then a conditional probability is assigned to the cluster for each of these three species depending on \texttt{lambda0}. Finally a probability for a cluster being of a certain particle species is calculated with the Bayesian approach that can be retrieved by \texttt{AliVCluster::GetPID()}.\\
246 \begin{DDbox}{\linewidth}
247 \begin{lstlisting}
248   // compute PID weights
249   if( (fProbGamma + fProbPiZero + fProbHadron)>0.){
250     fPIDWeight[0] = fProbGamma / (fProbGamma + fProbPiZero + fProbHadron);    // gamma
251     fPIDWeight[1] = fProbPiZero / (fProbGamma+fProbPiZero+fProbHadron);          // pi0
252     fPIDWeight[2] = fProbHadron / (fProbGamma+fProbPiZero+fProbHadron);        // hadron
253   }
254 ...
255   //default particles
256   fPIDFinal[AliPID::kElectron]  = fPIDWeight[0]/2; // electron
257   fPIDFinal[AliPID::kMuon]      = fPIDWeight[2]/8;
258   fPIDFinal[AliPID::kPion]      = fPIDWeight[2]/8;
259   fPIDFinal[AliPID::kKaon]      = fPIDWeight[2]/8;
260   fPIDFinal[AliPID::kProton]    = fPIDWeight[2]/8;
261   //light nuclei
262   fPIDFinal[AliPID::kDeuteron]  = 0;
263   fPIDFinal[AliPID::kTriton]    = 0;
264   fPIDFinal[AliPID::kHe3]       = 0;
265   fPIDFinal[AliPID::kAlpha]     = 0;
266   //neutral particles
267   fPIDFinal[AliPID::kPhoton]    = fPIDWeight[0]/2; // photon
268   fPIDFinal[AliPID::kPi0]       = fPIDWeight[1]  ; // pi0
269   fPIDFinal[AliPID::kNeutron]   = fPIDWeight[2]/8;
270   fPIDFinal[AliPID::kKaon0]     = fPIDWeight[2]/8;
271   fPIDFinal[AliPID::kEleCon]    = fPIDWeight[2]/8;
272   //
273   fPIDFinal[AliPID::kUnknown]   = fPIDWeight[2]/8;
274 \end{lstlisting}
275 \end{DDbox}
276
277
278
279
280
281 \paragraph{AliEMCalPIDResponse}
282
283 The idea for particle identification with EMCal clusters AND the track information is that electrons are loosing their total energy in an electromagnetic shower inside the EMCal whereas all other charged particles only part of it. The main observable is $E/p$ with the energy of the EMCal cluster ($E$) and the momentum of a matched track ($p$). This ratio is $E/p\sim1$ for electrons and $E/p< 1$ for other charged particles. 
284
285 The decision about a particle species is done within the PID framework provided by ALICE. The main classes are: \texttt{STEER/STEERBase/AliPIDCombined} and \texttt{STEER/STEERBase/AliPIDResponse}. There are two methods of usage:
286 \begin{enumerate}
287 \item $n\sigma$ method: For each detector the multiples of $\sigma$ values are given for the deviation from the expected mean value at a given $p_{\mathrm{T}}$ (assuming a Gaussian distribution). This can be done via: \texttt{AliPIDResponse::GetNumberOfSigmas(EDetector detCode, const AliVParticle *track, AliPID::EParticleType type)}
288 \item Bayesian approach: In \texttt{AliPIDCombined::ComputeProbabilities(const AliVTrack *track, const AliPIDResponse *response, Double\_t* bayesProbabilities)} for each detector (included in the analysis via\\ \texttt{AliPIDCombined::SetDetectorMask(AliPIDResponse::EDetector)}) the conditional probability for the respective detector observable is calculated for each particle species (selected via\\ \texttt{AliPIDCombined::SetSelectedSpecies(AliPID::EParticleType)}). Then the probability for a track being of a certain particle type is calculated with the Bayesian approach. The initial particle abundances (priors) can be activated via\\ \texttt{AliPIDCombined::SetEnablePriors(kTRUE)} and either own priors can be loaded\\ (\texttt{AliPIDCombined::SetPriorDistribution(AliPID::EParticleType type,TH1F *prior)}) or default ones can be chosen (\texttt{AliPIDCombined::SetDefaultTPCPriors()}).
289 \end{enumerate}
290
291 For the case of the EMCal the $n\sigma$ as well as the conditional probability are calculated in\\ \texttt{AliEMCALPIDResponse::GetNumberOfSigmas( Float\_t pt,  Float\_t eop, AliPID::EParticleType n,  Int\_t charge)} and\\
292 \texttt{AliEMCALPIDResponse::ComputeEMCALProbability(Int\_t nSpecies, Float\_t pt, Float\_t eop, Int\_t charge, Double\_t *pEMCAL)}, respectively. These methods are called from \texttt{AliPIDCombined} and \texttt{AliPIDResponse} internally, so usually the user does not use them. 
293
294 To calculate $n\sigma$ and the conditional probability a parametrization of $E/p$ for the different particle species at different momenta is needed. This was retrieved from data in a clean PID sample with the help of $V0$ decays for electrons, pions and protons ($\gamma\rightarrow e^+e^-$, $K^0\rightarrow \pi^+\pi^-$, and $\Lambda\rightarrow p+\pi^-/\bar{p}+\pi^+$ ) for different periods. Electrons are parametrized with a Gaussian distribution (mean value and $\sigma$), all other particles are parametrized with a Gaussian for $0.5 < E/p < 1.5$ and the probabilty to have a value in this $E/p$ interval (this is small, since the maximum of the distribution lies around $0.1$). Here we distinguish between protons, antiprotons (higher probabilty for higher $E/p$ values due to annihilation) and other particles (pions are used for these). At the moment this parametrization is not done for all periods so far, as default LHC11d is taken. There might be especially some centrality dependence on the $E/p$ parametrization (because of the different multiplicities of track--cluster matches).
295
296 In addition to that the purity of the electron identification can be enhanced by using shower shape cuts in addition. At the moment this can be done by getting them together with $n\sigma$:\\
297 \texttt{AliEMCALPIDResponse::NumberOfSigmasEMCAL(const AliVParticle *track,\\ 
298 AliPID::EParticleType type, Double\_t \&eop, Double\_t showershape[4])} In future, a full treatmeant inside the PID framework is planned (by combining with \texttt{AliEMCALPID}).
299
300 Some more information can be found on following TWiki pages:
301 \begin{itemize}
302 \item \href{https://twiki.cern.ch/twiki/bin/view/ALICE/AlicePIDTaskForce}{https://twiki.cern.ch/twiki/bin/view/ALICE/AlicePIDTaskForce}
303 \item
304 \href{https://twiki.cern.ch/twiki/bin/view/ALICE/PIDInAnalysis}{https://twiki.cern.ch/twiki/bin/view/ALICE/PIDInAnalysis}
305 \item \href{https://twiki.cern.ch/twiki/bin/viewauth/ALICE/EMCalPIDResponse}{https://twiki.cern.ch/twiki/bin/viewauth/ALICE/EMCalPIDResponse}
306 \end{itemize}
307
308 Here follows an example how to include the EMCal PID in an analysis task:
309
310 \begin{DDbox}{\linewidth}
311 \begin{lstlisting}
312    // in analysis header: 
313
314    AliPIDCombined fPIDCombined;                                                        
315    AliPIDResponse fPIDResponse;   
316
317
318    // in Constructor: 
319
320    fPIDCombined(0),                                                       
321    fPIDResponse(0), 
322
323
324    // in UserCreateOutputObjects 
325
326    // Set up combined PID
327    AliAnalysisManager *man=AliAnalysisManager::GetAnalysisManager();
328    AliInputEventHandler* inputHandler = (AliInputEventHandler*) (man->GetInputEventHandler());
329    fPIDResponse = (AliPIDResponse*)inputHandler->GetPIDResponse();
330
331    fPIDCombined = new AliPIDCombined;
332    fPIDCombined->SetSelectedSpecies(AliPID::kSPECIES);
333    fPIDCombined->SetDetectorMask(AliPIDResponse::kDetEMCAL);
334    fPIDCombined->SetEnablePriors(kFALSE);
335
336
337    // in UserExec: 
338
339    Double_t pEMCAL[AliPID::kSPECIES];
340    Double_t pBAYES[AliPID::kSPECIES];
341    Double_t eop;
342    Double_t ss[4];        //shower shape parameters (number of cells, M02, M20, Dispersion)
343
344    // NSigma value for electrons
345    nSigma = fPIDResponse->NumberOfSigmas(kEMCAL,track,AliPID::kElectron);
346    // or with getting also the E/p and shower shape values
347    nSigma = fPIDResponse->NumberOfSigmasEMCAL(track,AliPID::kElectron,eop,ss);
348
349    // Bayes probability
350    fPIDCombined->ComputeProbabilities(track, fPIDResponse, pBAYES);  
351 \end{lstlisting}
352 \end{DDbox}
353