squeleton of EMCAL documentation, partially filled
[u/mrichter/AliRoot.git] / EMCAL / doc / analysis.tex
CommitLineData
02582a78 1\section{Analysis format and code}
2
3All the reconstructed particles of all the detectors will be kept
4in a file called \textbf{AliESDs.root}. The detectors must store there
5the most relevant information which will be used in the analysis.
6Together with the AliESDs.root file, another
7file is created with some reference tags of the simulated events,
8containing for example the number of events per run. This file is
9named \textbf{Run0.Event0\_1.ESD.tag.root} (1 means that only 1 event
10was simulated).
11
12In order to do the analysis with the data contained in the ESDs, you
13only need the file \textbf{AliESDs.root} in your local directories or a grid collection. It is
14not necessary that in your working directory you keep other files
15like galice.root or EMCAL.{*}.root or any other. Anyway, we may want
16to access to the primary particles generated during the simulation,
17in that case we must have also the \textbf{galice.root} and \textbf{Kinematics.root}
18file. Also, if you want to access to some information of the detector geometry, you need
19to keep the \textbf{geometry.root} file.
20
21There are other data analysis container file created from the ESD, the
22AOD (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 not stored}.
23
24
25\subsection{Calorimeter information in ESDs/AODs}
26
27The 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.
28
29
30\subsubsection{AliVEvent (AliESDEvent, AliAODEvent)}
31
32Those are manager classes for the event information retrieval. Regarding the calorimeters they have the following access information (getter) methods (there are the equivalent setters just have a look to the header file of the class):
33\begin{itemize}
34
35\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).
36
37\item TClonesArray *GetCaloClusters() : Returns the array with CaloClusters PHOS+EMCAL, Only defined for AODs
38
39\item Int\_t GetEMCALClusters(TRefArray *clusters) ; Int\_t GetPHOSClusters(TRefArray *clusters) : Returns an array with only EMCal clusters or only with PHOS clusters.
40
41\item Int\_t GetNumberOfCaloClusters(): Returns the total number of clusters PHOS+EMCAL.
42
43\item AliVCaloCells *GetEMCALCells(); AliESDCaloCells *GetPHOSCells() : Returns the pointer with the CaloCells object for EMCal or PHOS.
44
45\item AliVCaloTrigger *GetCaloTrigger(TString calo) : Access to trigger patch information, for calo="PHOS" or calo="EMCAL"
46
47\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.
48
49
50
51\end{itemize}
52
53
54
55\subsubsection{AliVCaloCluster (AliESDCaloCluster,AliAODCaloCluster)}
56
57They 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 :
58
59\begin{itemize}
60\item General
61 \begin{itemize}
62 \item Int\_t GetID(): It returns a unique identifier number for a CaloCluster.
63
64 \item Char\_t GetClusterType():It returns kPHOSNeutral (kPHOSCharged exists but not used) or kEMCALClusterv1. Another way to get the origin of the cluster:
65
66 \item Bool\_t IsEMCAL(); Bool\_t IsPHOS().
67
68 \item void GetPosition(Float\_t *pos) : It returns a {x,y,z} array with the global positions of the clusters in centimeters.
69
70 \item Double\_t E() : It returns the energy of the cluster in GeV units.
71
72 \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.
73 \end{itemize}
74\item Shower Shape
75 \begin{itemize}
76
77 \item Double\_t GetDispersion(): Dispersion of the shower.
78
79 \item Double\_t Chi2(): Not filled.
80
81 \item Double\_t GetM20() Double\_t GetM02() : Ellipse axis.
82
83 \item UChar\_t GetNExMax() : Number or maxima in cluster. Not filled.
84
85 \item Double\_t *GetPID(): PID weights array, 10 entries corresponding to the ones defined in AliPID.h
86
87 \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
88
89 \item Double\_t GetDistanceToBadChannel() : Distance of the cluster to closest channel declared as kDead, kWarm or kHot.
90
91 \item Double\_t GetTOF() : Measured Time of Flight of the cluster.
92 \end{itemize}
93
94\item Track-Cluster matching
95 \begin{itemize}
96
97 \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.
98
99 \item Int\_t GetTrackMatchedIndex(Int\_t i): Index of track in position "i" in the list of indices stored in GetTracksMatched(). Only in ESDs
100
101 \item Int\_t GetNTracksMatched() : Total number of likely matched tracks. Size of GetTracksMatched() array.
102
103 \item Double\_t GetEmcCpvDistance() : PHOS method, not used anymore. Use instead those below.
104
105 \item Double\_t GetTrackDx(void), Double\_t GetTrackDz(void): Distance in x and z to closest track.
106
107 \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
108
109 \end{itemize}
110
111\item MonteCarlo labels:
112 \begin{itemize}
113
114 \item TArrayI * GetLabels(): List of indexes to the MonteCarlo particles that contribute to the cluster. Labels ordered in energy contribution.
115
116 \item Int\_t GetLabel(): Index of MonteCarlo particle that deposited more energy in the cluster. First entry of GetLabels() array.
117
118 \item Int\_t GetLabelAt(UInt\_t i): Index of MonteCarlo particle in position i of the array of MonteCarlo indices.
119
120 \item Int\_t GetNLabels() : Total number of MonteCarlo particles that deposited energy. Size of GetLabels() array.
121 \end{itemize}
122
123\item Cluster cells
124 \begin{itemize}
125
126 \item Int\_t GetNCells() : It returns the number of cells that contribute to the cluster.
127
128 \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().
129
130 \item Double32\_t *GetCellsAmplitudeFraction(): For cluster unfolding, it returns an array with the fraction the energy that a cell contributes to the cluster.
131
132 \item Int\_t GetCellAbsId(Int\_t i) : It returns the absolute Id number of a cell in the array between 0 and GetNCells()-1.
133
134 \item Double\_t GetCellAmplitudeFraction(Int\_t i) : It returns the amplitude fraction of a cell in the array between 0 and GetNCells()-1.
135
136 \end{itemize}
137
138 \end{itemize}
139
140
141\subsubsection{AliVCaloCells (AliESDCaloCells, AliAODCaloCells)}
142They 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.
143
144\begin{itemize}
145
146 \item Short\_t GetNumberOfCells(): Returns number of cells with some energy.
147
148 \item Bool\_t IsEMCAL(); Bool\_t IsPHOS(); Char\_t GetType(): Methods to check the origin of the AliESDCaloCell object, kEMCALCell or kPHOSCell.
149
150 \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).
151
152 \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.
153
154 \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.
155
156 \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.
157
158 \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.
159
160 \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.
161
162 \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)
163
164 \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.
165
166 \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)
167
168 \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.
169
170
171 \end{itemize}
172
173\subsubsection{AliVCaloTrigger (AliESDCaloTrigger, AliAODCaloTrigger) - Rachid)}
174
175\subsection{Macros}
176You can find example macros to run on ESDs or AODs in
177
178\$ALICE\_ROOT/EMCAL/macros/TestESD.C or TestAOD.C
179
180 All the ESDs information is filled via the AliEMCALReconstructor/AliPHOSReconstructor class, in the method FillESD(). The AODs are created via the analysis class
181
182\$ALICE\_ROOT/ANALYSIS/AliAnalysisTaskESDfilter.cxx,.h
183
184and as already mentioned, for the calorimeters it basically just copies all the information from ESD format to AOD format. In the lines below I will try to explain what is the information stored and how to retrieve it. The location of the classes that I am going to describe below is
185
186\$ALICE\_ROOT/STEER
187
188
189
190\subsection{Example code}
191
192The analysis is done using the data stored in the ESD. The macro\\
193 \textbf{\$ALICE\_ROOT/EMCAL/macros/TestESD.C}\\
194is an example of how to read the data for the calorimeters PHOS and
195EMCal (just replace where it says EMCAL by PHOS in the macro to obtain
196PHOS data). For these detectors we have to use the ESD class AliESDCaloCluster or AliESDCaloCells
197to retrieve all the calorimeters information. For the tracking detectors,
198the class is called AliESDtrack, but the way to use it is very similar
199(see {}``\$ALICE\_ROOT/STEER/AliESDtrack.{*} '' and {}``\$ALICE\_ROOT/STEER/AliESDCaloCluster{*}
200'' for more details). In AliESDCaloCluster we keep the following
201cluster information: energy, position, number of Digits that belong
202to the cluster, list of the cluster Digits indeces, shower dispersion, shower lateral axis and a few more parameters. In AliESDCaloCells we keep the following
203tower information: amplitude (GeV), time (seconds), absolute cell number.
204
205The structure of the ESD testing macro (TestESD.C) is the
206following:
207
208\begin{itemize}
209\item Lines 0-29: This macro is prepared to be compiled so it has \texttt{{}``includes''}
210to all the Root and AliRoot classes used.
211
212\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.
213
214\item Lines 40-64: Here are the methods used to load AliESDs.root , geometry or kinematics files. Also loop on ESD event is here.
215
216\item Lines 65-66 Gets the measured vertex of the collision.
217
218\item Lines 69-78 Loops on all the CaloCell entries and prints the cell amplitude, absolute number and time.
219
220\item Lines 84- end: We access the EMCAL AliESDCaloCluster array and loop on it.
221We get the different information from the CaloCluster.
222
223\item Lines 111-130: Track Matching prints. Access to the matched track stored in AliESDtrack.
224
225\item Lines 133-159: Cells in cluster prints
226
227\item Lines 161 - end: Access the stack with the MC information and prints the parameters of the particle that generated the cluster.
228
229
230\end{itemize}
231
232\subsection{Advanced utilities : Reconstruction/corrrections of cells, clusters during the analysis}
233
234\subsubsection{AliEMCALRecoUtils}
235\subsubsection{Tender : AliEMCALTenderSupply}
236