Index: trunk/paper/notes.tex
===================================================================
--- trunk/paper/notes.tex	(revision 144)
+++ trunk/paper/notes.tex	(revision 145)
@@ -996,48 +996,50 @@
 \subsection{Getting the \textsc{Delphes} information}
  
-\subsubsection{Contents of the \textsc{Delphes} \textsc{root} trees}
- 
-As said upwards, the \textsc{Delphes} \textsc{root} file is subdivided into three \textsc{trees}. All the branches available in those \textsc{trees} together with the reconstructed objects they correspond to are summarised here:
- 
+\subsubsection{Contents of the \textsc{Delphes} ROOT trees}
+ 
+The \textsc{Delphes} output file (\texttt{*.root}) is subdivided into three \textit{trees}, corresponding to generator-level data, analysis object data and trigger output. These \textsc{trees} are structures that organise the output data into \textit{branches} containing data (or \textit{leaves}) related with each others, like the kinematics properties ($E$, $p_x$, $\eta$, $\ldots$) of a given particle.
+
+Here is the exhaustive list of \textit{branches} availables in these \textit{trees}, together with their corresponding physical objet and \texttt{ExRootAnalysis} class:
 \begin{quote}
 \begin{tabular}{lll}
 {\bf GEN \textsc{tree}} & &\\
-Particle & generator particles from \textsc{hepevt}     & {\verb TRootGenParticle }\\
+~~~Particle & generator particles from \textsc{hepevt}     & {\verb TRootGenParticle }\\
+& & \\
 {\bf Analysis \textsc{tree}} & & \\
-Jet        & Jet collection                             & {\verb TRootJet }\\
-TauJet     & Collection of jets tagged as $\tau$-jets   & {\verb TRootTauJet }\\
-Electron   & Collection of electrons                    & {\verb TRootElectron }\\
-Muon       & Collection of muons                        & {\verb TRootMuon }\\
-Photon     & Collection of photons                      & {\verb TRootPhoton }\\
-Tracks     & Tracker tracks                             & {\verb TRootTracks }\\
-ETmis      & Transverse missing energy information      & {\verb TRootETmis }\\
-CaloTower  & Calorimetric towers                        & {\verb TRootCalo }\\
-ZDChits    & ?????                                      & {\verb TRootZdcHits }\\
-RP220hits  & ?????                                      & {\verb TRootRomanPotHits }\\
-FP420hits  &?????                                       & {\verb TRootRomanPotHits }\\
+~~~Tracks     & Collection of tracks                       & {\verb TRootTracks }\\
+~~~CaloTower  & Calorimetric towers                        & {\verb TRootCalo }\\
+~~~Electron   & Collection of electrons                    & {\verb TRootElectron }\\
+~~~Photon     & Collection of photons                      & {\verb TRootPhoton }\\
+~~~Muon       & Collection of muons                        & {\verb TRootMuon }\\
+~~~Jet        & Collection of jets                            & {\verb TRootJet }\\
+~~~TauJet     & Collection of jets tagged as $\tau$-jets   & {\verb TRootTauJet }\\
+~~~ETmis      & Transverse missing energy information      & {\verb TRootETmis }\\
+~~~ZDChits    & Hits in the Zero Degree Calorimeters       & {\verb TRootZdcHits }\\
+~~~RP220hits  & Hits in the first proton taggers           & {\verb TRootRomanPotHits }\\
+~~~FP420hits  & Hits in the next proton taggers            & {\verb TRootRomanPotHits }\\
+& & \\
 {\bf Trigger  } & &\\
-TrigResult & Acceptance of different trigger bits       & {\verb TRootTrigger }\\
+~~~TrigResult & Acceptance of different trigger bits       & {\verb TRootTrigger }\\
 \end{tabular}
 \end{quote}
- 
-The third column shows the names of the corresponding classes to be written in a \textsc{root} tree. All classes except the {\verb TRootTrigger }, the {\verb TRootETmis } and the {\verb TRootRomanPotHits } inherit from the class {\verb TRootParticle} which includes the following member functions for accessing the components:
- 
-\begin{quote}
-\begin{verbatim}
- 
+The third column shows the names of the corresponding classes to be written in a \textsc{root} tree. 
+All classes except \texttt{TRootTrigger}, \texttt{TRootETmis} and \texttt{TRootRomanPotHits} inherit from the class \texttt{TRootParticle} which includes the following data members (stored as \textit{leaves} in \textit{branches} of the \textit{trees}):
+\begin{quote}
+\begin{verbatim}
  float E;  // particle energy in GeV
  float Px; // particle momentum vector (x component) in GeV
  float Py; // particle momentum vector (y component) in GeV
  float Pz; // particle momentum vector (z component) in GeV
- 
  float PT; // particle transverse momentum in GeV
- float Eta; // particle pseudorapidity  float Phi; // particle azimuthal angle in rad
-\end{verbatim}
-\end{quote}
- 
-In addition to their four-momentum and related quantities, additional properties are available for specific objects. Those are summarised in the following table:
+ float Eta; // particle pseudorapidity  
+ float Phi; // particle azimuthal angle in rad
+\end{verbatim}
+\end{quote}
+ 
+In addition to their kinematics, some additional properties are available for specific objects: 
 \begin{quote}
 \begin{tabular}{ll}
-{\bf \texttt{Particle} leave } &\\    \texttt{  int PID;      }&\texttt{ // particle HEP ID number }\\
+{\bf leaves in the \texttt{Particle} branch} &\\    
+   \texttt{  int PID;      }&\texttt{ // particle HEP ID number }\\
    \texttt{  int Status;   }&\texttt{ // particle status }\\
    \texttt{  int M1;       }&\texttt{ // particle 1st mother }\\
@@ -1045,17 +1047,23 @@
    \texttt{  int D1;       }&\texttt{ // particle 1st daughter }\\
    \texttt{  int D2;       }&\texttt{ // particle 2nd daughter }\\
-   \texttt{  float Charge; }&\texttt{ // electrical charge }\\
-   \texttt{  float T;      }&\texttt{ // particle vertex position (t component) }\\
-   \texttt{  float X;      }&\texttt{ // particle vertex position (x component) }\\
-   \texttt{  float Y;      }&\texttt{ // particle vertex position (y component) }\\
-   \texttt{  float Z;      }&\texttt{ // particle vertex position (z component) }\\
-   \texttt{  float M;      }&\texttt{ // particle mass }\\
-{\bf \texttt{Electron} and \texttt{Muon} leaves } &\\
+   \texttt{  float Charge; }&\texttt{ // electrical charge in units of e}\\
+   \texttt{  float T;      }&\texttt{ // particle vertex position (t component, in mm/c) }\\
+   \texttt{  float X;      }&\texttt{ // particle vertex position (x component, in mm) }\\
+   \texttt{  float Y;      }&\texttt{ // particle vertex position (y component, in mm) }\\
+   \texttt{  float Z;      }&\texttt{ // particle vertex position (z component, in mm) }\\
+   \texttt{  float M;      }&\texttt{ // particle mass in GeV}\\
+\end{tabular}
+\end{quote}
+\begin{quote}
+\begin{tabular}{ll}
+{\bf Additional leaves in \texttt{Electron} and \texttt{Muon} branches} &\\
    \texttt{ int Charge } &\\
    \texttt{ bool IsolFlag } &\\
-{\bf \texttt{Jet} leave }  &\\
+& \\
+{\bf Additional leaf in the \texttt{Jet} branch }  &\\
    \texttt{ bool Btag } &\\
-{\bf \texttt{ZDChits} leave } &\\
-   \texttt{float T;        }&\texttt{ // time of flight [s] }\\
+& \\
+{\bf Additional leaves in the \texttt{ZDChits} branch } &\\
+   \texttt{float T;        }&\texttt{ // time of flight  in s }\\
    \texttt{ int side;      }&\texttt{ // -1 or +1 }\\
 \end{tabular}
@@ -1064,5 +1072,73 @@
 \subsection{Running an analysis on your \textsc{Delphes} events}
  
-To analyse the {\verb Root } {\verb TTree } ntuple  of \textsc{Delphes}, the simplest way is to use the {\verb Analysis_Ex.cpp } code which is coming in the {\verb Examples } repository of \textsc{Delphes}. Note that all of this is optional and done to facilitate the analysis, as the output from \textsc{Delphes} is viewable with the standard TBrowser or \textsc{root} and can be analysed using the MakeClass facility. To run the {\verb Examples/Analysis_Ex.cpp } code, the two following arguments are required: a text file containing the input \textsc{Delphes} root files to run, and the name of the output root file. To run the code:
+To analyse the \textsc{root} ntuple produced by \textsc{Delphes}, the simplest way is to use the {\verb Analysis_Ex.cpp } code which is coming in the {\verb Examples } repository of \textsc{Delphes}. Note that all of this is optional and done to facilitate the analyses, as the output from \textsc{Delphes} is viewable with the standard \textsc{root} \texttt{TBrowser} and can be analysed using the \texttt{MakeClass} facility. 
+As an example, here is a simple overview of a \texttt{myoutput.root} file created by \textsc{Delphes}:
+\begin{quote}
+\begin{verbatim}
+me@mylaptop:~$ root -l myoutput.root
+root [0]
+Attaching file myoutput.root as _file0...
+root [1] .ls
+TFile**         myoutput.root
+ TFile*         myoutput.root
+  KEY: TTree    GEN;1   Analysis tree
+  KEY: TTree    Analysis;1      Analysis tree
+  KEY: TTree    Trigger;1       Analysis tree
+root [2] TBrowser t;
+root [3] Analysis->GetEntries()
+(const Long64_t)200
+root [4] GEN->GetListOfBranches()->ls()
+OBJ: TBranchElement     Event   Event_ : 0 at: 0x9108f30
+OBJ: TBranch    Event_size      Event_size/I : 0 at: 0x910cfd0
+OBJ: TBranchElement     Particle        Particle_ : 0 at: 0x910c6b0
+OBJ: TBranch    Particle_size   Particle_size/I : 0 at: 0x9111c58
+root [5] Trigger->GetListOfLeaves()->ls()
+OBJ: TLeafElement       TrigResult_     TrigResult_ : 0 at: 0x90f90a0
+OBJ: TLeafElement       TrigResult.Accepted     Accepted[TrigResult_] : 0 at: 0x90f9000
+OBJ: TLeafI     TrigResult_size TrigResult_size : 0 at: 0x90fb860
+\end{verbatim}
+\end{quote}
+The \texttt{.ls} command lists the current keys available and in particular the three \textit{tree} names.
+\texttt{TBrowser t} launches a browser and the \texttt{GetEntries()} method outputs the number of data in the corresponding \textit{tree}.
+The list of \textit{branches} or \textit{leaves} can be displayed with the \texttt{GetListOfBranches()} and \texttt{GetListOfLeaves()} methods, pointing to the \texttt{ls()} one. In particular, it is possible to shown only parts of the output, using wildcard characters (\texttt{*}):
+\begin{quote}
+\begin{verbatim}
+root [6] Analysis->GetListOfLeaves()->ls("*.E")
+OBJ: TLeafElement       Jet.E   E[Jet_] : 0 at: 0xa08bc68
+OBJ: TLeafElement       TauJet.E        E[TauJet_] : 0 at: 0xa148910
+OBJ: TLeafElement       Electron.E      E[Electron_] : 0 at: 0xa1d8a50
+OBJ: TLeafElement       Muon.E  E[Muon_] : 0 at: 0xa28ac80
+OBJ: TLeafElement       Photon.E        E[Photon_] : 0 at: 0xa33cd88
+OBJ: TLeafElement       Tracks.E        E[Tracks_] : 0 at: 0xa3cced0
+OBJ: TLeafElement       CaloTower.E     E[CaloTower_] : 0 at: 0xa4ba188
+OBJ: TLeafElement       ZDChits.E       E[ZDChits_] : 0 at: 0xa54a3c8
+OBJ: TLeafElement       RP220hits.E     E[RP220hits_] : 0 at: 0xa61e648
+OBJ: TLeafElement       FP420hits.E     E[FP420hits_] : 0 at: 0xa6d0920
+\end{verbatim}
+\end{quote}
+
+To draw a particular leaf, either double-click on the corresponding name in the \texttt{TBrowser} or use the \texttt{Draw} method of the corresponding \textit{tree}.
+\begin{quote}
+\begin{verbatim}
+root [7] Trigger->Draw("TrigResult.Accepted");
+\end{verbatim}
+\end{quote}
+Mathematical operations on several \textit{leaves} are possible within a given \textit{tree}:
+\begin{quote}
+\begin{verbatim}
+root [8] Analysis->Draw("Muon.Px * Muon.Px");
+root [9] Analysis->Draw("sqrt(pow(Muon.E,2) -  pow(Muon.Pz,2) + pow(Muon.PT,2))");
+\end{verbatim}
+\end{quote}
+Finally, to prepare an deeper analysis, the \texttt{MakeClass} method is useful:
+\begin{quote}
+\begin{verbatim}
+root [10] Trigger->MakeClass()
+Info in <TTreePlayer::MakeClass>: Files: Trigger.h and 
+        Trigger.C generated from TTree: Trigger
+\end{verbatim}
+\end{quote}
+
+To run the \texttt{Examples/Analysis\_Ex.cpp} code, the two following arguments are required: a text file containing the input \textsc{Delphes} \textsc{root} files to run, and the name of the output \textsc{root} file. 
  \begin{quote}
 \begin{verbatim}
@@ -1071,8 +1147,9 @@
  \end{quote}
  
- 
- 
-\subsubsection{sdflksdjf}
-The \texttt{Examples/Trigger\_Only.cpp} code permits to run the trigger selection separately from the general detector simulation on output \textsc{Delphes} root files. An input \textsc{Delphes} root file is mandatory as argument. The new tree containing the trigger information will be added in these file. The trigger datacard is also necessary. To run the code:
+\subsubsection{Adding the trigger information}
+The \texttt{Examples/Trigger\_Only.cpp} code permits to run the trigger selection separately from the general detector simulation on output \textsc{Delphes} root files. 
+A \textsc{Delphes} root file is mandatory as an input argument for the \texttt{Trigger\_Only} routine. 
+The new \textit{tree} containing the trigger result data will be appended to this file. 
+The trigger datacard is also necessary. To run the code:
  \begin{quote}
 \begin{verbatim}
@@ -1084,6 +1161,6 @@
  
 \begin{itemize}
-\item If the { \verb FLAG_frog } was switched on, two files were created during the run of \textsc{Delphes}: {\verb DelphesToFrog.vis } and {\verb DelphesToFrog.geom }. They contain all the needed information to run frog.
-\item To display the events and the geometry, you first need to compile \textsc{Frog}. Go to the {\verb Utilities/FROG } and type {\verb make }.
+\item If the { \verb FLAG_frog } was switched on in the smearing card, two files has been created during the run of \textsc{Delphes}: {\verb DelphesToFrog.vis } and {\verb DelphesToFrog.geom }. They contain all the needed information to run \textsc{frog}.
+\item To display the events and the geometry, you first need to compile \textsc{Frog}. Go to the {\verb Utilities/FROG } and type {\verb make }. This compilation is done once for all, with this geometry (i.e. as long as the \texttt{*vis} and \texttt{*geom} files do not change)
 \item Go back into the main directory and type {\verb ./Utilities/FROG/frog }.
 \end{itemize}
