PWGCF/FLOW/Documentation/FlowPackageManual.tex

   1 \documentclass[a4paper]{book}
   2 \usepackage[nottoc,numbib]{tocbibind}
   3 \usepackage[english]{babel}
   4 \usepackage[pdftex]{graphics} %enable pdfgraphics support necessary for pdflatex
   5 \usepackage{graphicx}
   6 \usepackage{tikz}
   7 \usepackage[small,bf]{caption}
   8 \usepackage{footmisc}
   9 \usepackage{sidecap}
  10 \usepackage{fancyvrb}
  11 \usepackage{color}
  12 \usepackage{rotating}
  13 \makeatletter
  14 \setlength{\@fptop}{0pt}
  15 \setlength{\@fpsep}{5pt}
  16 \makeatother
  17 \renewcommand{\dotfill}{\leaders\hbox to 5pt{\hss.\hss}\hfill}
  18 \usepackage[hmargin=1.2cm,vmargin=1.5cm]{geometry} %set custom margins
  19 \usepackage{fancyhdr} %enable hyperlinking, highlight page numbers
  20 \usepackage{amsmath}
  21 \usepackage{amssymb}
  22 \numberwithin{equation}{subsection}
  23 \usepackage{amsfonts}
  24 \usepackage{mathrsfs}
  25 \usepackage{tabularx}
  26 \usepackage{lastpage}
  27 \usepackage{subfigure}
  28 \usepackage{multicol}
  29 \usepackage{lipsum}
  30 \usepackage{xspace}
  31 \usepackage{latexsym}
  32 \usepackage{verbatim}
  33 \usepackage{listings}
  34 \usepackage{color}
  35 \usepackage[usenames,dvipsnames]{xcolor}
  36 \definecolor{listinggray}{gray}{0.9}
  37 \definecolor{lbcolor}{rgb}{0.9,0.9,0.9}
  38 \usepackage{listings}
  39 \usepackage{color}
  40
  41 \definecolor{mygreen}{rgb}{0,0.6,0}
  42 \definecolor{mygray}{rgb}{0.5,0.5,0.5}
  43 \definecolor{mymauve}{rgb}{0.58,0,0.82}
  44
  45 \lstset{ %
  46    backgroundcolor=\color{white},   % choose the background color; you must add \usepackage{color} or \usepackage{xcolor}
  47    basicstyle=\footnotesize,        % the size of the fonts that are used for the code
  48    breakatwhitespace=false,         % sets if automatic breaks should only happen at whitespace
  49    breaklines=true,                 % sets automatic line breaking
  50 %   captionpos=b,                    % sets the caption-position to bottom
  51    commentstyle=\color{mygreen},    % comment style
  52    deletekeywords={...},            % if you want to delete keywords from the given language
  53    escapeinside={\%*}{*)},          % if you want to add LaTeX within your code
  54    extendedchars=true,              % lets you use non-ASCII characters; for 8-bits encodings only, does not work with UTF-8
  55    frame=single,                    % adds a frame around the code
  56    keepspaces=true,                 % keeps spaces in text, useful for keeping indentation of code (possibly needs columns=flexible)
  57    keywordstyle=\color{blue},       % keyword style
  58    language=C,                 % the language of the code
  59    morekeywords={*,...},            % if you want to add more keywords to the set
  60    numbers=left,                    % where to put the line-numbers; possible values are (none, left, right)
  61    numbersep=5pt,                   % how far the line-numbers are from the code
  62    numberstyle=\tiny\color{mygray}, % the style that is used for the line-numbers
  63    rulecolor=\color{black},         % if not set, the frame-color may be changed on line-breaks within not-black text (e.g. comments (green here))
  64    showspaces=false,                % show spaces everywhere adding particular underscores; it overrides 'showstringspaces'
  65    showstringspaces=false,          % underline spaces within strings only
  66    showtabs=false,                  % show tabs within strings adding particular underscores
  67    stepnumber=1,                    % the step between two line-numbers. If it's 1, each line will be numbered
  68    stringstyle=\color{mymauve},     % string literal style
  69    tabsize=2,                       % sets default tabsize to 2 spaces
  70 %   title=\lstname                   % show the filename of files included with \lstinputlisting; also try caption instead of title
  71 % in the end language and linenumbres will be called for each block, otherwise html conversion doesn't pick up on the proper markup ...
  72 }
  73 % tweak the the style a little bit
  74 \lstdefinestyle{customc}{
  75 %   belowcaptionskip=1\baselineskip,
  76    breaklines=true,
  77    frame=single,
  78    xleftmargin=\parindent,
  79    language=C,
  80 %   showstringspaces=false,
  81    basicstyle=\footnotesize\ttfamily,
  82    keywordstyle=\bfseries\color{green!40!black},
  83    commentstyle=\itshape\color{mygray},
  84    identifierstyle=\color{blue},
  85    stringstyle=\color{orange},
  86    framexleftmargin=5mm,
  87 }
  88
  89 \lstset{escapechar=@,style=customc}
  90 \usepackage[sort&compress,numbers]{natbib}
  91
  92 \pagestyle{fancy} %enable custom headeres
  93 \fancyhead{}
  94 \fancyfoot{} %clear predefined headers, then create your own:
  95 \lhead{\footnotesize AliROOT Flow Package manual and documentation}
  96 \rhead{\footnotesize The FLOW team}
  97 \rfoot{\footnotesize Page \thepage\ of \pageref{LastPage}}
  98 \lfoot{\footnotesize \rightmark}
  99 \usepackage[bookmarks=true,
 100             bookmarksopen=true,
 101             bookmarksnumbered=true, pdftex,
 102             hyperindex=true,linktocpage]{hyperref}
 103 \hypersetup{
 104     bookmarks=true,         % show bookmarks bar?
 105     unicode=false,          % non-Latin characters in Acrobatâ\80\99s bookmarks
 106     pdftoolbar=true,        % show Acrobatâ\80\99s toolbar?
 107     pdfmenubar=true,        % show Acrobatâ\80\99s menu?
 108     pdffitwindow=false,     % window fit to page when opened
 109     pdfstartview={FitH},    % fits the width of the page to the window
 110     pdftitle={AliROOT Flow Package manual and documentation},    % title
 111     pdfauthor={Redmer Alexander Bertens},     % author
 112     pdfsubject={AliROOT Flow Package manual and documentation},   % subject of the document
 113     pdfcreator={Redmer Alexander Bertens},   % creator of the document
 114     pdfproducer={Redmer Alexander Bertens}, % producer of the document
 115     pdfkeywords={ALICE} {AliROOT} {ROOT} {manual} {flow} {package} {software}, % list of keywords
 116     pdfnewwindow=true,      % links in new window
 117     colorlinks=true,       % false: boxed links; true: colored links
 118     linkcolor=blue,          % color of internal links
 119     citecolor=green,        % color of links to bibliography
 120     filecolor=blue,      % color of file links
 121     urlcolor=blue           % color of external links
 122 }
 123 \usepackage{lineno}
 124 \usepackage{makeidx}
 125 \makeindex
 126
 127 \sloppy
 128 \fancypagestyle{plain}
 129  {
 130  \fancyhead{}
 131  \fancyfoot{}
 132  } % clear header and footer of plain page because of ToC
 133
 134  % tikxstyle for integration of tikz graphics
 135  % for if in the future i'll find time for making a flowchart ...
 136 \tikzstyle{every node}=[font=\tiny]
 137 \tikzstyle{decision} = [rectangle, draw, fill=yellow!20,
 138     rounded corners, minimum height=1.5em, minimum width=2.5em, inner sep=3pt]
 139 \tikzstyle{decision2} = [rectangle, draw, fill=red!20,
 140     rounded corners, minimum height=1.5em, minimum width=2.5em, inner sep=3pt]
 141 \tikzstyle{decision3} = [rectangle, draw, fill=green!20,
 142     rounded corners, minimum height=1.5em, minimum width=2.5em, inner sep=3pt]
 143 \tikzstyle{block} = [rectangle, draw, fill=blue!20,
 144     rounded corners, minimum height=1.5em, minimum width=2.5em, inner sep=3pt]
 145 \tikzstyle{line} = [draw, -latex']
 146 \tikzstyle{cloud} = [draw, ellipse,fill=red!20,
 147     minimum height=2em]
 148 \tikzstyle{sdecision} = [rectangle, draw, fill=yellow!20,
 149     rounded corners, minimum height=1.5em, minimum width=2.5em, inner sep=3pt]
 150 \tikzstyle{sblock} = [rectangle, draw, fill=blue!20,
 151     rounded corners, minimum height=1.5em, minimum width=2.5em, inner sep=3pt]
 152 \tikzstyle{scloud} = [draw, ellipse,fill=red!20,
 153     minimum height=2em]
 154 \tikzstyle{ycloud} = [draw, ellipse,fill=yellow!20,
 155     minimum height=2em]
 156
 157 \renewcommand{\thefootnote}{\fnsymbol{footnote}}
 158 \frontmatter
 159
 160 \linenumbers
 161 \begin{document}
 162
 163 \noindent
 164 \begin{center}
 165         \vspace*{1.5cm}
 166         {\LARGE \bf The FLOW Analysis Package}\\
 167
 168         \vspace{1.5cm}
 169         \begin{figure}[hbt]
 170                 \includegraphics[width=1.\textwidth]{figs/daVinci.png}
 171         \end{figure}
 172
 173         \vspace{1.5cm}
 174         \noindent
 175         {\large \bf a short manual}\\
 176         \today\\
 177 \vfill
 178 \noindent
 179 Redmer Alexander Bertens \\ (\texttt{rbertens @ cern.ch}) \\
 180 with excerpts from other manuals, authors of those are mentioned in text
 181 \end{center}
 182
 183 \clearpage
 184 \thispagestyle{empty}
 185 \pagenumbering{roman}
 186 \tableofcontents
 187 \renewcommand{\thefootnote}{\alph{footnote}}
 188 \mainmatter
 189 \chapter{Introduction}
 190 The \texttt{ALICE flow package}\index{flow package}\index{ALICE flow package|see{flow package}}\footnote{The \texttt{ALICE} flow package is part of \texttt{AliROOT}\index{AliROOT}, the ALICE extension of the \texttt{ROOT} framework, which can be obtained from \href{http://git.cern.ch/pub/AliRoot}{http://git.cern.ch/pub/AliRoot}. The flow package itself is located in the folder \texttt{\$ALICE\_ROOT/PWG/FLOW/}, where \texttt{\$ALICE\_ROOT} refers to the source directory of \texttt{AliROOT}.} contains most known flow analysis methods. The package itself consists of two parts
 191 \begin{enumerate}
 192     \item The `tasks' library, which can be considered to be the \texttt{ALICE} interface to the package and takes care of e.g. track cuts, event cuts, etc;
 193     \item The `base' library, which is the core of the package and contains the actual implementation of flow analysis methods such as the scalar product method, Q-cumulant method, etc. This part of the package has no dependencies other than \texttt{ROOT} and can be used on any type of input data.
 194 \end{enumerate}
 195 \section{This manual}
 196 This manual is designed to get you started with using the flow package. It is written in the following way:
 197 \begin{itemize}
 198     \item Chapter \ref{sec:onthefly} is designed to get you started on a short Monte Carlo example. In this example you will use the flow package to generate toy Monte Carlo events and analyze them;
 199     \item Chapter \ref{sec:program} describes the flow package itself in detail. This includes a brief discussion on the structure of the package, sections on track and event cuts, an explanation of some relevant code sections and ending with an example analysis of $v_2(p_t)$ of charged pions with the Q-cumulant method. Most of this chapter pertains to the `tasks (the \texttt{AliROOT})' part of the flow package (i.e. event cuts, track cuts, PID, etc), but it is also explained how to do flow analysis in \texttt{ROOT} only on a \texttt{TTree}\index{TTree};
 200     \item Chapter \ref{sec:methods} gives an overview of the available flow analysis methods. For the theory behind the methods references to papers are given. Settings relevant to the specific implementation are given as well.
 201     \item Lastly, chapter \ref{sec:exotic} explains how the flow package can be put to use in more `exotic' environments, such as an invariant mass method estimate of flow of rapidly decaying particles.
 202     \end{itemize}
 203 \section{Disclaimer}
 204 What this manual is \emph{not} designed for is letting the analyzer use the flow package as a `black box'. It is supposed to be a starting point, to give an overview of the design of the software and point you to relevant classes, but in the end, the analyzer is responsible for understanding what is happening and using the software in a proper way. Configurations of the package which may work on a technical level (i.e. produce output) do not necessarily mean that the output is what you expect it to be! Always make sure that you understand what you are doing, and when in doubt, browse through the source code or consult an expert. The package is not a static entity, users are encouraged to make additions, be it track cuts, bug fixes, additional analysis methods, etc, etc. If you have suggestions, questions, commit requests, send an email to the flow-pag mailing list or to \texttt{rbertens @ cern}.
 205 \chapter{A Quick Start}\label{sec:onthefly}
 206 We'll begin with a hands-on exercise in which you'll get acquainted with some aspects of the flow package in a few minutes. We'll do this by generating a few simple toy Monte Carlo events and performing a flow analysis on these simulated events without writing them (the events) to disk, a so called `flow analysis on-the-fly'\footnote{In this example the \texttt{AliFlowEventSimple} class will be used to generate toy events (which is described in detail in section \ref{sec:program}). Another on-the-fly routine is available in the \texttt{AliFlowEventSimpleMakerOnTheFly}, the original on-the-fly manual for that class is reprinted in the appendix (see \ref{sec:ante}) of this document.}.
 207 \section{On the fly - getting started on a Toy MC}
 208 The steps which will be followed in this example will be the same as the steps we take when performing an analysis on data\footnote{In data, some of these steps are actually taken care of by an analysis task, but this will be described in more detail in the next chapter.}:
 209 \begin{enumerate}
 210 \item Prepare your \texttt{(Ali)ROOT} session by loaded the necessary libraries
 211 \item Create the analysis method objects
 212 \item Initialize the methods (which creates their histograms)
 213 \item Define track cuts
 214 \item Create flow events, which is a container class holding all necessary information (e.g. tracks) for the flow analysis of an event (collision) and actually do the analysis
 215 \item Finish the analysis, which will calculate the final $v_n$ values
 216 \item Write the results to an output file
 217 \end{enumerate}
 218 In this Monte Carlo exercise, the flow event class will not receive data from a detector, but instead generate toy events itself.
 219
 220 We will now go through these step one-by-one. All the code that is used can also be found in the macro \texttt{runFlowOnTheFlyExample.C}\index{On the fly}\index{runFlowOnTheFlyExample.C}\footnote{In aliroot, this macro can be found at \\ \texttt{\$ALICE\_ROOT/PWGCF/FLOW/Documentation/examples/manual/runFlowOnTheFlyExample}}.
 221 \begin{enumerate}
 222         \item To use the flow code the flow library needs to be loaded. In\index{libraries, AliROOT} \texttt{AliROOT}:
 223         \begin{lstlisting}[language=C, numbers=left]
 224 gSystem->Load("libPWGflowBase");\end{lstlisting}
 225         In \texttt{root} additional libraries need to be loaded\index{libraries, ROOT}:
 226         \begin{lstlisting}[language=C, numbers=left]
 227 gSystem->Load("libGeom");
 228 gSystem->Load("libVMC");
 229 gSystem->Load("libXMLIO");
 230 gSystem->Load("libPhysics");
 231 gSystem->Load("libPWGflowBase");\end{lstlisting}
 232         \item We need to instantiate the flow analysis methods which we want to use. In this example we will
 233             instantiate two methods: one which calculates the flow versus the Monte Carlo event plane (this our reference value: as the event plane orientation is known by this method, the $v_2$ value we retrieve should be equal to the input $v_2$ by definition) and as a second method the so called Q-cumulant analysis.
 234 \begin{lstlisting}[language=C, numbers=left]
 235 AliFlowAnalysisWithMCEventPlane *mcep = new AliFlowAnalysisWithMCEventPlane();
 236 AliFlowAnalysisWithQCumulants *qc = new AliFlowAnalysisWithQCumulants();\end{lstlisting}
 237         \item Each of the methods needs to be initialized\index{initialize methods} (e.g. to define the histograms):
 238 \begin{lstlisting}[language=C, numbers=left]
 239 mcep->Init();
 240 qc->Init();\end{lstlisting}
 241         \item To define the particles we are going to use as Reference Particles\index{reference particles} \index{RP|see{reference particles}} (RP's, particles
 242         used for the {\bf Q} vector) and the Particles Of Interest\index{particles of interest} \index{POI|see{particles of interest}} (POI's, the particles of which we calculate the differential flow) we have to define two track cut objects\index{track cut object, simple}:
 243         \begin{lstlisting}[language=C, numbers=left]
 244 AliFlowTrackSimpleCuts *cutsRP = new AliFlowTrackSimpleCuts();
 245 AliFlowTrackSimpleCuts *cutsPOI = new AliFlowTrackSimpleCuts();
 246 cutsPOI->SetPtMin(0.2);
 247 cutsPOI->SetPtMax(2.0); \end{lstlisting}
 248 Particles will be selected as either POI or RP depending on whether or not they pass these cuts.
 249         \item Now we are ready to start the analysis. For a quick start we create a toy Monte Carlo event, tag the reference particles and particles of interest (which means that, if a particle passes the POI or RP cuts, it is flagged as `POI' or `RP')  and pass it to the two flow methods.
 250
 251         Since we want to analyze more than one event, this step is performed in loop. First define the number of events that need to be created, their multiplicity, and a value $v_2$ value, which can either be supplied as a fixed number (no $p_t$ dependence) of a function (to generate $p_t$ differential flow\footnote{The on the fly event generator is not limited to the generation of the second harmonic $v_2$, but to get started, this is a nice example.}
 252
 253         \begin{lstlisting}[language=C, numbers=left]
 254 Int_t nEvents = 1000;   // generate 1000 events
 255 Int_t mult = 2000;              // use track multiplicity of 2000
 256 Double_t v2 = .05;              // 5 pct integrated flow
 257 // or sample differential flow
 258 TF1* diffv2 = new TF1("diffv2", "((x<1.)*(0.1/1.)*x+(x>=1.)*0.1)", 0., 20.); \end{lstlisting}
 259
 260 Now we have all the ingredients to our first flow analysis
 261
 262         \begin{lstlisting}[language=C, numbers=left]
 263 for(Int_t i=0; i<nEvents; i++) {
 264     // make an event with mult particles
 265     AliFlowEventSimple* flowevent = AliFlowEventSimple(mult,AliFlowEventSimple::kGenerate);
 266     // modify the tracks adding the flow value v2
 267     flowevent->AddV2(diffv2);
 268     // select the particles for the reference flow
 269     flowevent->TagRP(cutsRP);
 270     // select the particles for differential flow
 271     flowevent->TagPOI(cutsPOI);
 272     // do flow analysis with various methods:
 273     mcep->Make(flowevent);
 274     qc->Make(flowevent);
 275     // delete the event from memory
 276     delete flowevent;
 277 } \end{lstlisting}
 278         \item To fill the histograms which contain the final results we have to call Finish for each method:
 279         \begin{lstlisting}[language=C, numbers=left]
 280 mcep->Finish();
 281 qc->Finish(); \end{lstlisting}
 282         \item This concludes the analysis and now we can write the results into a file. Two options for writing the input to a file are available:
 283      \begin{itemize}
 284      \item Create a new output file and write the output to this file
 285      \begin{lstlisting}[language=C, numbers=left]
 286 TFile *outputFile = new TFile("outputMCEPanalysis.root","RECREATE");
 287 mcep->WriteHistograms();
 288 TFile *outputFile = new TFile("outputQCanalysis.root","RECREATE");
 289 qc->WriteHistograms();\end{lstlisting}
 290
 291 Please note that this will create a new output file, and overwrite any existing file called \texttt{AnalysisResults.root}.
 292
 293 \item  To write the output of multiple analyses into sub-directories of one file, one can do the following:
 294 \begin{lstlisting}[language=C, numbers=left]
 295 TFile *outputFile = new TFile("AnalysisResults.root","RECREATE");
 296 TDirectoryFile* dirQC = new TDiretoryFile("outputQCanalysis", "outputQCanalysis");
 297 qc->WriteHistograms(dirQC);
 298 TDirectoryFile* dirMCEP = new TDiretoryFile("outputMCEPanalysis", "outputMCEPanalysis");
 299 mcep->WriteHistograms(dirMCEP);
 300 \end{lstlisting}
 301 \end{itemize}
 302
 303 Note that \texttt{AnalysisResults.root} \index{AnalysisResults.root} is the default name given to analyses in \texttt{AliROOT}. Many macros in \texttt{AliROOT} will expect a file \texttt{AnalyisResults.root} as input, so for most users it will be convenient to follow this convention.
 304
 305 When done with running the analysis, do not forget to write the file to disk by calling
 306 \begin{lstlisting}[language=C, numbers=left]
 307 TFile::Close(); // write the buffered file to disk \end{lstlisting}
 308 \end{enumerate}
 309
 310 \section{What is in the output file ?}
 311 \index{output file} Now we have written the results into a file, but what is in there?
 312
 313 Although the output of different flow analysis techniques might differ slightly as a result of their different approaches at estimating $v_2$, the output files containers are always constructed in a similar way.
 314
 315 \subsection{AliFlowCommonHists - Output objects}\label{sec:commonhists}
 316 Objects of two types are stored in the output of the flow analysis\footnote{Make sure that \texttt{libPWGflowBase.so} is loaded in your \texttt{(Ali)ROOT} session, otherwise these objects will be unknown.}
 317 \begin{enumerate}
 318 \item \texttt{AliFlowCommonHist}\index{AliFlowCommonHist}, which is a class that contains common histograms for the flow analysis (e.g. QA histograms and histograms that contain the analysis flags which were used). Depending on the type of flow analysis that was used, this object contains histograms from the following list:
 319 \begin{lstlisting}[language=C, numbers=left]
 320   Bool_t    fBookOnlyBasic;       // book and fill only control histos needed for all methods
 321   TH1F*     fHistMultRP;          // multiplicity for RP selection
 322   TH1F*     fHistMultPOI;         // multiplicity for POI selection
 323   TH2F*     fHistMultPOIvsRP;     // multiplicity for POI versus RP
 324   TH1F*     fHistPtRP;            // pt distribution for RP selection
 325   TH1F*     fHistPtPOI;           // pt distribution for POI selection
 326   TH1F*     fHistPtSub0;          // pt distribution for subevent 0
 327   TH1F*     fHistPtSub1;          // pt distribution for subevent 1
 328   TH1F*     fHistPhiRP;           // phi distribution for RP selection
 329   TH1F*     fHistPhiPOI;          // phi distribution for POI selection
 330   TH1F*     fHistPhiSub0;         // phi distribution for subevent 0
 331   TH1F*     fHistPhiSub1;         // phi distribution for subevent 1
 332   TH1F*     fHistEtaRP;           // eta distribution for RP selection
 333   TH1F*     fHistEtaPOI;          // eta distribution for POI selection
 334   TH1F*     fHistEtaSub0;         // eta distribution for subevent 0
 335   TH1F*     fHistEtaSub1;         // eta distribution for subevent 1
 336   TH2F*     fHistPhiEtaRP;        // eta vs phi for RP selection
 337   TH2F*     fHistPhiEtaPOI;       // eta vs phi for POI selection
 338   TProfile* fHistProMeanPtperBin; // mean pt for each pt bin (for POI selection)
 339   TH2F*     fHistWeightvsPhi;     // particle weight vs particle phi
 340   TH1F*     fHistQ;               // Qvector distribution
 341   TH1F*     fHistAngleQ;          // distribution of angle of Q vector
 342   TH1F*     fHistAngleQSub0;      // distribution of angle of subevent 0 Q vector
 343   TH1F*     fHistAngleQSub1;      // distribution of angle of subevent 1 Q vector
 344   TProfile* fHarmonic;            // harmonic
 345   TProfile* fRefMultVsNoOfRPs;    // <reference multiplicity> versus # of RPs
 346   TH1F*     fHistRefMult;         // reference multiplicity distribution
 347   TH2F*     fHistMassPOI;         // mass distribution for POI selection \end{lstlisting}
 348   This information is from the header file of the AliFlowCommonHist object\footnote{The headers of both output objects can be found in \texttt{\$ALICE\_ROOT/PWG/FLOW/Base/}.}
 349   \item \texttt{AliFlowCommonHistResults}\index{AliFlowCommonHistResults} is an object designed to hold the common results of the flow analysis\footnote{The word common here is used to indicate histograms that hold observables which are evaluated in all flow analysis methods. Specific analysis methods may however store additional histograms which are not covered in this list!}. The possible common histograms stored in this object are
 350   \begin{lstlisting}[language=C, numbers=left]
 351   TH1D* fHistIntFlow; // reference flow
 352   TH1D* fHistChi;     // resolution
 353   // RP = Reference Particles:
 354   TH1D* fHistIntFlowRP;     // integrated flow of RPs
 355   TH1D* fHistDiffFlowPtRP;  // differential flow (Pt) of RPs
 356   TH1D* fHistDiffFlowEtaRP; // differential flow (Eta) of RPs
 357   // POI = Particles Of Interest:
 358   TH1D* fHistIntFlowPOI;     // integrated flow of POIs
 359   TH1D* fHistDiffFlowPtPOI;  // differential flow (Pt) of POIs
 360   TH1D* fHistDiffFlowEtaPOI; // differential flow (Eta) of POIs \end{lstlisting}
 361
 362   \end{enumerate}
 363   The titles of the histograms in the output object differ from the names of the pointers given in the two lists printed above, but the lists give an overview of what is available; the easiest way however of getting acquainted with where to find histograms in the output is browsing them in \texttt{ROOT's TBrowser}\index{TBrowser} (see figure \ref{fig:browserExample}).
 364   \begin{lstlisting}[language=C, numbers=left]
 365   new TBrowser(); \end{lstlisting}
 366 \begin{SCfigure}
 367  \includegraphics[width=0.70\textwidth]{figs/browserExample.png}
 368  \caption[TBrowser with output file]{Example of output file opened in a TBrowser, results of differential $v_2$ analysis with second order Q-cumulant analysis are shown.}
 369  \label{fig:browserExample}
 370 \end{SCfigure}
 371
 372 The \texttt{AliFlowCommonHist} and \texttt{AliFlowCommonHistResults} classes are derived from the generic \texttt{TNamed}\index{TNamed} \texttt{ROOT} object and can be written to a \texttt{ROOT} file. The flow analysis tasks will, as output, write the complete \texttt{AliFlowCommonHist} and \texttt{AliFlowCommonHistResults} objects to file at the end of an analysis. To read the content of these objects, the \texttt{libPWGflowBase} library must be loaded in your \texttt{ROOT} session.
 373
 374 \subsubsection{Comparing flow results}
 375 A convenient way of comparing the results of the different flow analysis strategies that have been used is invoking the macro \texttt{compareFlowResults.C}\footnote{\texttt{\$ALICE\_ROOT/PWGCF/FLOW/macros/compareFlowResults.C}}\index{compareFlowResults}.  This macro will read the analysis output file \texttt{AnalysisResults.root}, extract the requested results from it and plot them. For a full overview of what can be done with the macro, the reader is referred to the macro itself and its ample documentation. To run the macro on the data-set that we have just generated, simply do
 376 \begin{lstlisting}[language=C, numbers=left]
 377 .L compareFlowResults.C
 378 compareFlowResults(TSring(""))  // the empty suffix indicates on the fly events \end{lstlisting}
 379
 380 \begin{SCfigure}
 381  \includegraphics[width=0.70\textwidth]{figs/compareFlowResults.png}
 382  \caption[Comparing on the fly flow results]{Example of inspecting the output file of the on the fly analysis with the \texttt{compareFlowResults.C macro}.}
 383  \label{fig:browserExample}
 384 \end{SCfigure}
 385
 386
 387 \chapter{The Program}\label{sec:program}
 388 The basic idea behind the flow package is that from whatever input you have, a \emph{flow event}\index{flow event} is constructed, which is then passed to one or more flow analysis methods\index{flow analysis method} (e.g. the scalar product method\index{scalar product} or Q-cumulant\index{Q-cumulant} method). The flow event is a collection of \emph{flow tracks}\index{flow track}, which are simple objects carrying only the kinematic information that is necessary to do flow analysis. By setting up the flow package in this way, the flow analysis methods can analyze input from various sources, be it ALICE data, Monte Carlo events, STAR data, etc, etc, as long as the flow event is properly filled\index{STAR input} \index{Monte Carlo input}. This might all sound a bit abstract at this point; this chapter however will explain all details and relevant classes in detail. For those who are impatient and prefer seeing the flow package in action, section \ref{sec:example} gives a step-by-step example of doing a $\pi^{\pm}$ $v_2$ analysis in the \texttt{AliROOT} analysis framework.
 389
 390 \section{Overview}
 391 \begin{figure}
 392 \begin{center}
 393 \includegraphics[width=.75\textwidth]{figs/flowChart.png}
 394 \caption{Schematic presentation of the organization of the flow package. Input, which can come from any kind of source, is converted to a generic \texttt{AliFlowEventSimple} object, which in turn is passed to the analysis methods.}
 395 \label{fig:flowchart}
 396 \end{center}
 397 \end{figure}
 398 Figure \ref{fig:flowchart} gives a simple schematic representation\index{flowchart} of the flow package. Input events (in the case of the figure this is either ESDs or AODs) pass a set of event cuts (the common cuts) and are then converted to a flow event (stored as an \texttt{AliFlowEventSimple}\index{AliFlowEventSimple} object). This flow event holds a collection of flow tracks (\texttt{AliFlowTrackSimple}\index{AliFlowTrackSimple} objects) which are passed to flow analysis methods. The only steps of this flow chart which depend on \texttt{AliROOT} libraries are the ones handling \texttt{ALICE} data types (the ESDs or AODs). The rest of the analysis chain (the \texttt{AliFlowEventSimle} and the analysis methods) have no specific \texttt{AliROOT} dependence and are just simple \texttt{c++} objects. Therefore, the flow package is split into two libraries
 399 \begin{description}
 400     \item [libPWGflowBase] \index{libPWGflowBase}The base library, which has no specific \texttt{AliROOT} dependencies. This library holds objects such as the \texttt{AliFlowEventSimple} and \texttt{AliFlowTrackSimple}, and analysis methods classes. The analysis methods classes follow the naming scheme: \texttt{AliFlowAnalysisWith$\ast$} where $\ast$ denotes a specific analysis method. All classes which end up in the \text{libPWGflowBase.so} shared object can be found in \texttt{\$ALICE\_ROOT/PWG/FLOW/Base};
 401     \item [libPWGflowTasks] \index{libPWGflowTasks} The tasks library, which has specific \texttt{AliROOT} dependencies. Contrary to what the name suggests, this library does not just hold tasks, but actually comprises all classes of the flow package which need to include \texttt{AliROOT} specific classes. This ranges from classes to read the AOD or ESD input data (important examples are the \texttt{AliFlowEvent}\index{AliFlowEvent} and \texttt{AliFlowTrackCuts}\index{AliFlowTrackCuts}, which will be discussed later on in this chapter) and the \texttt{AliAnalysisTask$\ast$} classes, which are analysis tasks, derived from \texttt{AliAnalysisTaskSE} which can be used in the \texttt{AliROOT} analysis framework and are actually just interface classes to the underlying flow analysis methods of libPWGflowBase. The classes which are bundled into the \text{libPWGflowTasks.so} shared object can be found in \texttt{\$ALICE\_ROOT/PWG/FLOW/Tasks};
 402 \end{description}
 403 Some tools, such as the flow event or track cuts, have a `base' component which name ends with the suffix `simple', and an `tasks' (\texttt{AliROOT}) component which does not have this suffix. The `tasks' class in these cases inherits from the `base' class.
 404
 405 Every flow analysis in the flow package starts with the flow event. As mentioned earlier, the flow event is a simple container class which holds a collection of flow tracks, which are in turn fed to the flow analysis methods. In the next section it will be explained how the flow event can be filled with \texttt{ALICE} data in the \texttt{AliROOT} analysis framework. The section after that will explain how the flow event can be filled with \emph{any} type of data using just \texttt{ROOT}
 406
 407 \section{Analysis in the ALICE analysis framework}\index{flow event}
 408 In this section, you will see how a flow analysis can be performed in the \texttt{AliROOT} analysis framework.
 409
 410 \subsection{Input data}\index{input data}
 411 Before passing the flow event to the flow analysis methods, it needs to be filled with a set of flow tracks. In general, a distinction is made between \emph{reference particles} (or \emph{RP's}), which are particles that are used to build the \textbf{Q} vector(s), and \emph{particles of interest} (or \emph{POI's}), which are the particles of which you'll calculate the differential flow. The flow event and the flow analysis methods are designed to keep track of which flow tracks are POI's, RP's (or even both at the same time), which is important to avoid auto-correlation effects which can distort the $v_n$ measurement. The user of the flow package however is responsible for properly setting up the analysis!
 412
 413 The flow event can be filled with input from many sources. In the second chapter of this manual, a simple method has been shown where the flow event (the \texttt{AliFlowEventSimple} object) fills itself by generating a set of Monte Carlo tracks by sampling kinematic variables from supplied p.d.f.'s. Using this method is a very effective tool for testing and developing new flow analysis methods (if you generate events with a certain $v_2(p_t)$ and then retrieve the same $v_2(p_t)$ from your flow analysis method, you can use that as a tool to proof the validation of your analysis method) but if you want to do a data analysis, a somewhat more advanced - but not difficult - approach is necessary.
 414
 415 Filling a flow event from data can be performed either `by-hand' (which is covered in section \ref{sec:exotic} on more exotic analyses), but the most commonly used method of filling a flow event in the \texttt{AliROOT} analysis framework is using the dedicated task \texttt{AliAnalysisTaskFlowEvent}\index{AliAnalysisTaskFlowEvent}.
 416
 417 The idea behind this is the following:
 418 \begin{enumerate}
 419 \item Setup the \texttt{AliAnalysisTaskFlowEvent} task to receive input events (e.g. \texttt{AODs}, \texttt{ESDs}, \texttt{MC}, $\ldots$;
 420 \item Define two sets of track selection criteria (colloquially referred to as \emph{track cuts}), one for POI's and one for RP's;
 421 \item Pass these two sets of track cuts to the \texttt{AliAnalysisTaskFlowEvent};
 422 \item The \texttt{AliAnalysisTaskFlowEvent} will convert the tracks  of each input event to a set of \texttt{AliFlowSimpleTracks}. Depending on whether or not a track passes the track selection for POI's or RP's, the \texttt{AliFlowSimpleTrack} is labeled as a POI or RP (or both. In the case where a track does not meet any of the track selection criteria, it is omitted from the \texttt{AliFlowSimpleTrack} collection and not added to the flow event);
 423 \item All the \texttt{AliFlowSimpleTracks} are added to the flow event which is passed to the flow analysis methods.
 424 \end{enumerate}
 425
 426 \subsection{Event selection}\index{event selection}
 427 When using the \texttt{AliAnalysisTaskFlowEvent} task to create your flow event, the \texttt{AliAnalysisTaskFlowEvent} task is responsible for ensuring that only good quality tracks enter into your analysis by making sensible track selections. The first step however at safeguarding track quality is making sure that the events that are accepted by \texttt{AliAnalysisTaskFlowEvent} pass sane event selection criteria.
 428
 429 \subsubsection{Trigger selection}\index{event selection!trigger selection}
 430 A certain combination a of detector signals (a \emph{trigger}) is required for an event to be written to storage. Different types of analyses might require different types of events, and hence, different types of triggers.
 431
 432 You can set a trigger by calling
 433 \begin{lstlisting}[language=C, numbers=left]
 434 AliAnalysisTaskFlowEvent::SelectCollisionCandidates(UInt_t offlineTriggerMask);\end{lstlisting}
 435 where \texttt{offlineTriggerMask} is the trigger mask corresponding to the desired trigger. A list of all available triggers, with a short descrption, can be found in the header file of the \texttt{AliVEvent} class\footnote{\texttt{\$ALICE\_ROOT/...}}. This function, however, is not implement in the \texttt{AliAnalysisTaskFlowEvent} itself, but rather in the base class of which most of the analysis task classes within \texttt{AliROOT} are derived: the \texttt{AliAnalysisTaskSE} class (which is designed to handle a single event, hence the suffix `SE'). For each event that is written from a file, but function \texttt{AliAnalysisTaskSE::Exec()} is called, which - among other things - checks if an event passes the requested trigger selection, and if so, calls the \texttt{UserExec()} function of your analysis task. In the case of the \texttt{AliAnalysisTaskFlowEvent} this is the \texttt{AliAnalysisTaskFlowEvent::UserExec()}, which creates \texttt{AliFlowSimpleTracks} and fills the flow event.
 436
 437 A general remark about trigger selection in flow analyses is that the non-uniform acceptance correction methods that are implemented in the flow package assume a flat \textbf{Q} vector distribution. Specific triggers (e.g. EMCal triggers) result in a \textbf{Q} vector bias which should \emph{not} be corrected as they invalidate that assumption. A safe approach is therefore using a minimum bias trigger for your analysis (such as \texttt{AliVEvent::kMB}), other triggers selections will not a-priori lead to problems, but use them with caution!
 438
 439 \subsubsection{Event cuts}\index{event selection!event cuts}
 440 In addition to trigger selection, generally one wants to perform additional event (quality) selection. The flow package contains an event cuts class which can be used to perform event selection, the \texttt{AliFlowEventCuts} object\footnote{\texttt{\$ALICE\_ROOT/PWG/FLOW/Tasks/AliFlowEventCuts.cxx}}. \index{AliFlowEventCuts}
 441
 442 To use the event cuts object in combination with the \texttt{AliAnalysisTaskFlowEvent} task, simply create the event cuts object, configure it and pass it to the \texttt{AliAnalysisTaskFlowEvent}:
 443 \begin{lstlisting}[language=C, numbers=left]
 444   AliFlowEventCuts* cutsEvent = new AliFlowEventCuts("EventCuts");
 445   // configure some event cuts, e.g. centrality
 446   cutsEvent->SetCentralityPercentileRange(20., 30.);
 447   // pass it to the flow event task via the setter
 448   AliAnalysisTaskFlowEvent::SetCutsEvent(cutsEvent);\end{lstlisting}
 449
 450   The available cut parameters in the flow event cuts object are\index{event selection!parameters}
 451 \begin{lstlisting}[language=C, numbers=left]
 452   Bool_t fCutNumberOfTracks;//cut on # of tracks
 453   Int_t fNumberOfTracksMax;  //limits
 454   Int_t fNumberOfTracksMin;  //limits
 455   Bool_t fCutRefMult; //cut on refmult
 456   refMultMethod fRefMultMethod; //how do we calculate refmult?
 457   Bool_t fUseAliESDtrackCutsRefMult; //use AliESDtrackCuts for refmult calculation
 458   AliESDtrackCuts::MultEstTrackType fRefMultMethodAliESDtrackCuts;
 459   Int_t fRefMultMax; //max refmult
 460   Int_t fRefMultMin; //min refmult
 461   AliFlowTrackCuts* fRefMultCuts; //cuts
 462   AliFlowTrackCuts* fMeanPtCuts; //mean pt cuts
 463   AliFlowTrackCuts* fStandardTPCcuts; //Standard TPC cuts
 464   AliFlowTrackCuts* fStandardGlobalCuts; //StandardGlobalCuts
 465   Bool_t fCutPrimaryVertexX; //cut on x of prim vtx
 466   Double_t fPrimaryVertexXmax; //max x prim vtx
 467   Double_t fPrimaryVertexXmin; //min x prim vtx
 468   Bool_t fCutPrimaryVertexY; //cut on y of prim vtx
 469   Double_t fPrimaryVertexYmax; //max y prim vtx
 470   Double_t fPrimaryVertexYmin; //min y prim vtx
 471   Bool_t fCutPrimaryVertexZ; //cut on z of prim vtx
 472   Double_t fPrimaryVertexZmax; //max z prim vtx
 473   Double_t fPrimaryVertexZmin; //min z prim vtx
 474   Bool_t fCutNContributors; //cut on number of contributors
 475   Int_t fNContributorsMax; //maximal number of contrib
 476   Int_t fNContributorsMin; //minimal number of contrib
 477   Bool_t fCutMeanPt; //cut on mean pt
 478   Double_t fMeanPtMax; //max mean pt
 479   Double_t fMeanPtMin; //min mean pt
 480   Bool_t fCutSPDvertexerAnomaly; //cut on the spd vertexer anomaly
 481   Bool_t fCutSPDTRKVtxZ; //require compatibility between SPDvertexz TRKvertexz
 482   Bool_t fCutTPCmultiplicityOutliers; //cut TPC multiplicity outliers
 483   Bool_t fCutTPCmultiplicityOutliersAOD; // cut TPC outliers in 10h or 11h aod
 484   Bool_t fUseCentralityUnchecked; //use the unchecked method
 485   refMultMethod fCentralityPercentileMethod; //where to get the percentile from
 486   Bool_t fCutZDCtiming;   //cut on ZDC timing
 487   AliTriggerAnalysis fTrigAna; //trigger analysis object
 488   Bool_t fCutImpactParameter; //cut on impact parameter (MC header)
 489   Double_t fImpactParameterMin; // min impact parameter
 490   Double_t fImpactParameterMax; // max impact parameter
 491   TH2F *fhistTPCvsGlobalMult; //!correlation between TPCMult and GlobalMult
 492   Bool_t fData2011; //2011 data is used\end{lstlisting}
 493   all of which are accessible via dedicated setters\index{event selection!setters},
 494 \begin{lstlisting}[language=C, numbers=left]
 495   void SetNumberOfTracksMax(Int_t value) {fNumberOfTracksMax=value;fCutNumberOfTracks=kTRUE;}
 496   void SetNumberOfTracksMin(Int_t value) {fNumberOfTracksMin=value;fCutNumberOfTracks=kTRUE;}
 497   void SetNumberOfTracksRange(Int_t min, Int_t max) {fNumberOfTracksMin=min;fNumberOfTracksMax=max;fCutNumberOfTracks=kTRUE;}
 498   void SetRefMultMax(Int_t value) {fRefMultMax=value;fCutRefMult=kTRUE;}
 499   void SetRefMultMin(Int_t value) {fRefMultMin=value;fCutRefMult=kTRUE;}
 500   void SetRefMultRange(Int_t min, Int_t max) {fRefMultMin=min;fRefMultMax=max;fCutRefMult=kTRUE;}
 501   void SetImpactParameterMax(Double_t value) {fImpactParameterMax=value;fCutImpactParameter=kTRUE;}
 502   void SetImpactParameterMin(Double_t value) {fImpactParameterMin=value;fCutImpactParameter=kTRUE;}
 503   void SetImpactParameterRange(Double_t min, Double_t max) {fImpactParameterMin=min;fImpactParameterMax=max;fCutImpactParameter=kTRUE;}
 504   void SetPrimaryVertexXrange(Double_t min, Double_t max)
 505   void SetPrimaryVertexYrange(Double_t min, Double_t max)
 506   void SetPrimaryVertexZrange(Double_t min, Double_t max)
 507   void SetNContributorsRange(Int_t min, Int_t max=INT_MAX)
 508   void SetMeanPtRange(Double_t min, Double_t max) {fCutMeanPt=kTRUE; fMeanPtMax=max; fMeanPtMin=min;}
 509   void SetCutSPDvertexerAnomaly(Bool_t b=kTRUE) {fCutSPDvertexerAnomaly=b;}
 510   void SetCutZDCtiming(Bool_t c=kTRUE) {fCutZDCtiming=c;}
 511   void SetCutSPDTRKVtxZ(Bool_t b=kTRUE) {fCutSPDTRKVtxZ=b;}
 512   void SetCutTPCmultiplicityOutliers(Bool_t b=kTRUE) {fCutTPCmultiplicityOutliers=b;}
 513   void SetCutTPCmultiplicityOutliersAOD(Bool_t b=kTRUE) {fCutTPCmultiplicityOutliersAOD=b;}
 514   void SetRefMultMethod(refMultMethod m) {fRefMultMethod=m;}
 515   void SetRefMultMethod(AliESDtrackCuts::MultEstTrackType m) { fRefMultMethodAliESDtrackCuts=m;
 516   void SetRefMultCuts( AliFlowTrackCuts* cuts ) {fRefMultCuts=static_cast<AliFlowTrackCuts*>(cuts->Clone());}
 517   void SetMeanPtCuts( AliFlowTrackCuts* cuts ) {fMeanPtCuts=static_cast<AliFlowTrackCuts*>(cuts->Clone());}
 518   void SetQA(Bool_t b=kTRUE) {if (b) DefineHistograms();}
 519   void SetCentralityPercentileMethod( refMultMethod m) {fCentralityPercentileMethod=m;}
 520   void SetUseCentralityUnchecked(Bool_t b=kTRUE) {fUseCentralityUnchecked=b;}
 521   void SetUsedDataset(Bool_t b=kTRUE) {fData2011=b;}    // confusing name, better use different interface
 522   void SetLHC10h(Bool_t b=kTRUE) {fData2011=(!b);}      // TODO let cut object determine runnumber and period
 523   void SetLHC11h(Bool_t b=kTRUE) {fData2011=b;}         // use this only as 'manual override'\end{lstlisting}
 524
 525 \subsubsection{Caveats and remarks}
 526 Some caveats\index{event selection!caveats} and remarks about using the event cuts object
 527 \begin{description}
 528 \item[Default behavior] By default, the event cuts object accepts all events. All desired cuts have to be set by the user. This is also reflected in the design of the setters: most of the setters will, when called, set a \texttt{Bool\_t} to true which enables a cut on a certain parameter;
 529 \item[Applicability of cuts to different data types] \index{event selection!data types}Not all the cuts can be applied to all input data types. In e.g. the process of filtering \texttt{AODs} from \texttt{ESDs}, `technical' event cuts are made and not all events are stored in the \texttt{AOD} format. Because of this, information that can be required from \texttt{ESDs} might not be available (as it is not necessary) in \texttt{AODs}. To see whether or not a cut you set is actually applied to the data type you're using, take a look at
 530 \begin{lstlisting}[language=C, numbers=left]
 531 Bool_t AliFlowEventCuts::PassesCuts(AliVEvent *event, ALIMCEvent *mcevent)\end{lstlisting}
 532 This function determines whether or not an event is accepted: it starts by converting the virtual event type that is passed as argument to either an \texttt{ESD} or \texttt{AOD} event, and goes through selection criteria accordingly.
 533 \item[Event cuts outside of the \texttt{AliAnalysisTaskFlowEvent} class]
 534 When you perform a flow analysis without using the \texttt{AliAnalysisTaskFlowEvent} class (which is done e.g. in the analyses explained in section \ref{sec:exotic}), you can still use the event cuts class by creating an instance of the object, passing it to your analysis class and `manually' checking the return value of the function
 535 \begin{lstlisting}[language=C, numbers=left]
 536 Bool_t AliFlowEventCuts::PassesCuts(AliVEvent *event, ALIMCEvent *mcevent)\end{lstlisting}
 537 \item[Data taking period] Most event cuts will be tuned specifically to the LHC10h or LHC11h data taking periods. The event cuts class might need to be updated to accommodate specific cuts for different periods - do not hesitate write patches for this!
 538 \end{description}
 539 for e.g. each event that is passed to your \texttt{::UserExec()} function.
 540
 541 \subsection{Track cuts and the track cuts object}\index{track selection}
 542 As explained in the previous subsection, flow events are filled with tracks which fulfill certain track selection criteria. These criteria are checked using the \texttt{AliFlowTrackCuts} class. The \texttt{AliFlowTrackCuts} class can handle different types of input from different data-types (e.g. \texttt{ESD} or \texttt{AOD}) and information from different sub-detector systems. All input is in the end converted to \texttt{AliFlowSimpleTracks} which are added to the flow event. To understand how the \texttt{AliFlowTrackCuts}\index{AliFlowTrackCuts} object works and how it should be configured, it is good to make a few distinctions and remarks.
 543
 544 The term `track' is generally used for reconstructed particle trajectories which are constructed from information coming from the tracking detectors in central barrel of the \texttt{ALICE} detector (more specifically from information from the \texttt{ITS} and \texttt{TPC} detectors). Tracks are the most commonly used data source, and the translation from `track' to \texttt{AliFlowTrackSimple} is trivial, as it merely comprises copying  kinematic information ($p_t$, $\varphi$, $\eta$) from the barrel track to the \texttt{AliFlowTrackSimple} object.
 545
 546 When using information that is not coming from tracking detectors, e.g. information from the \texttt{VZERO}\index{VZERO} system, this procedure of simply copying variables is not suitable as the \texttt{VZERO} system does not measure $p_t$, $\varphi$, $\eta$ of particles, but is an array of scintillators with limited spatial resolution. Nevertheless, the \texttt{AliFlowTrackCuts} class converts the \texttt{VZERO} signal to \texttt{AliFlowTrackSimples} which are, to the flow event, indistinguishable from barrel tracks. As the procedure of accepting these tracks is very different from the procedure of accepting barrel tracks, they will be treated separately in the following subsections.
 547
 548 \subsubsection{ESD tracks as data source}\index{track selection!ESD tracks}
 549 The safest and most convenient way of using \texttt{ESD} tracks as a data source is by using one of the pre-defined track cuts sets that are available in the \texttt{AliFlowTrackCuts} class. These sets of track cuts mimic the cuts that are defined in the \texttt{AliESDtrackCuts} class\footnote{\texttt{\$ALICE\_ROOT/ANALYSIS/AliESDtrackCuts.cxx}}. The following default track cuts sets are available:
 550 \begin{lstlisting}[language=C, numbers=left]
 551   static AliFlowTrackCuts* GetStandardTPCStandaloneTrackCuts();
 552   static AliFlowTrackCuts* GetStandardTPCStandaloneTrackCuts2010();
 553   static AliFlowTrackCuts* GetStandardGlobalTrackCuts2010();
 554   static AliFlowTrackCuts* GetStandardITSTPCTrackCuts2009(Bool_t selPrimaries=kTRUE);
 555   static AliFlowTrackCuts* GetStandardMuonTrackCuts(Bool_t isMC=kFALSE, Int_t passN=2);
 556   \end{lstlisting}
 557 All these are static methods which create a new track cuts object and configure it properly, so to use these track cuts it suffices to type e.g.
 558 \begin{lstlisting}[language=C, numbers=left]
 559 AliFlowTrackCuts* myCuts = AliFlowTrackCuts::GetStandardGlobalTrackCuts2010();\end{lstlisting}
 560 To get a better understanding of what the \texttt{AliFlowTrackCuts} class actually does, let's take a look at what how the cut object is configured in this case:
 561 \begin{lstlisting}[language=C, numbers=left]
 562 AliFlowTrackCuts* AliFlowTrackCuts::GetStandardGlobalTrackCuts2010()
 563 {
 564   //get standard cuts
 565   AliFlowTrackCuts* cuts = new AliFlowTrackCuts("standard Global tracks");
 566   cuts->SetParamType(kGlobal);
 567   cuts->SetPtRange(0.2,5.);
 568   cuts->SetEtaRange(-0.8,0.8);
 569   cuts->SetMinNClustersTPC(70);
 570   cuts->SetMinChi2PerClusterTPC(0.1);
 571   cuts->SetMaxChi2PerClusterTPC(4.0);
 572   cuts->SetMinNClustersITS(2);
 573   cuts->SetRequireITSRefit(kTRUE);
 574   cuts->SetRequireTPCRefit(kTRUE);
 575   cuts->SetMaxDCAToVertexXY(0.3);
 576   cuts->SetMaxDCAToVertexZ(0.3);
 577   cuts->SetAcceptKinkDaughters(kFALSE);
 578   cuts->SetMinimalTPCdedx(10.);
 579   return cuts;
 580 }\end{lstlisting}
 581 The configuration falls into three categories:
 582 \begin{enumerate}
 583 \item A number of track quality cuts is set;
 584 \item Some kinematic cuts are set;
 585 \item The parameter type\index{track selection!parameter type} is set by calling \texttt{AliFlowTrackCuts::SetParamType()} (in this case to \texttt{AliFlowTrackCuts::kGlobal}). This last step is of particular importance as it takes care disentangling the POI and RP selection and removing a $v_n$ bias due to auto-correlations. When the flow event is filled (the relevant piece of code is printed under section \ref{sec:fill}), a check is done to see if the POI's and RP's are of the same type. If not, a track cannot be a POI and RP at the same time (as they are from different sources). However, if POI's and RP's originate from the same source, an \texttt{AliFlowTrackSimple} can be both a POI and RP at the same time if it satisfies both the POI and RP track selection criteria. By specifying the parameter type by calling \texttt{AliFlowTrackCuts::SetParamType()} the flow event is configured to properly deal with overlapping or exclusive POI and RP selections. A wrongly configured parameter type can lead to double counting of tracks and nonsensical analysis results! The following list of track parameter types is available as an \texttt{enum} in \texttt{AliFlowTrackCuts.h}
 586 \begin{lstlisting}[language=C, numbers=left]
 587   enum trackParameterType { kMC,
 588                             kGlobal,
 589                             kTPCstandalone,
 590                             kSPDtracklet,
 591                             kPMD,
 592                             kV0,    //neutral reconstructed v0 particle
 593                             kVZERO, //forward VZERO detector
 594                             kMUON,
 595                             kKink,
 596                             kAODFilterBit,
 597                             kUserA,     // reserved for custom cuts
 598                             kUserB      // reserved for custom cuts
 599                           };\end{lstlisting}
 600 Note that \texttt{kV0} is reserved to denote a decay vertex of a neutral particle, and \texttt{kVZERO} is used to indicate the VZERO detector system. kUserA and kUserB are additional flags which can selected for `custom' track selection sets.
 601 \end{enumerate}
 602
 603 \subsubsection{AOD tracks as data source}\index{track selection!AOD tracks}
 604 \texttt{AOD} tracks are derived from \texttt{ESD} tracks via process called `filtering'. If an \texttt{ESD} track meets a pre-defined set of track cuts, it is converted to an \texttt{AOD} track which is stored in an \texttt{AOD} event. The \texttt{AOD} track carries a specific flag (called \texttt{filterbit}) which corresponds to the specific set of cuts that was applied to create accept the track. A full list of track selection criteria corresponding to distinct filterbits can be found \href{}{here}. Note that different \texttt{AOD} productions might have different filterbit definitions!
 605
 606 In \texttt{AOD} analysis it generally suffices to select tracks of a certain filterbit, instead of checking quality criteria `by-hand' as is done in \texttt{ESD} analyses (some variables which one would cut on in \texttt{ESD} tracks might not even be available in the \texttt{AOD} tracks as the \texttt{AOD} is designed to be a light-weight `end-user' data format). To get an instance of the \texttt{AliFlowTrackCuts} object which only selects tracks based on a specific filterbit\index{track selection!AOD filterbit}\index{filterbit}, one can call
 607 \begin{lstlisting}[language=C, numbers=left]
 608  static AliFlowTrackCuts* GetAODTrackCutsForFilterBit(UInt_t bit = 1);\end{lstlisting}
 609  which is defined as
 610  \begin{lstlisting}[language=C, numbers=left]
 611  AliFlowTrackCuts* AliFlowTrackCuts::GetAODTrackCutsForFilterBit(UInt_t bit)
 612 {
 613   // object which in its default form only cuts on filterbit (for AOD analysis)
 614   AliFlowTrackCuts* cuts = new AliFlowTrackCuts(Form("AOD fitlerbit %i", (int)bit));
 615   cuts->SetMinimalTPCdedx(-999999999);
 616   cuts->SetAODfilterBit(bit);
 617   cuts->SetParamType(AliFlowTrackCuts::kAODFilterBit);
 618   return cuts;
 619 }  \end{lstlisting}
 620 The \texttt{SetMinimalTPCdedx(-999999999);} is kept here for backward-compatibility.
 621
 622 Note that also in the case of \text{AOD} analyses the parameter type is set to (if necessary) decouple POI and RP selections.
 623
 624 \subsection{Additional options}
 625 As stated, input data needn't necessarily come in the form of barrel tracks - we can use other detector systems as well. When dealing with barrel tracks, quality criteria might not be the only thing you want to select your tracks on: perhaps you want to do analysis on identified particles. The following sub-sections explain how the \texttt{AliFlowTrackCuts} object can be used to achieve this.
 626
 627 \subsubsection{Identified particles}\index{track selection!particle identification}\index{particle identification}
 628 The \texttt{AliFlowTrackCuts} object can do particle selection for a number of particles that are defined in the AliPID\footnote{\texttt{\$ALICE\_ROOT/STEER/STEERBas/AliPID.h}}. To enable
 629 particle identification as a selection criterion, call the function
 630 \begin{lstlisting}[language=C, numbers=left]
 631 void AliFlowTrackCuts::SetPID(
 632     AliPID::EParticleType pid,
 633     PIDsource s=kTOFpid,
 634     Double_t prob=0.9)
 635 {fParticleID=pid; fPIDsource=s; fParticleProbability=prob; fCutPID=kTRUE; InitPIDcuts();
 636 }\end{lstlisting}
 637 The first argument specifies the particle species that will be selected via the \texttt{EParticleType} enum. The total list of particles as defined in the  \texttt{AliPID} class reads
 638 \begin{lstlisting}[language=C, numbers=left]
 639   enum EParticleType {
 640     kElectron = 0,
 641     kMuon = 1,
 642     kPion = 2,
 643     kKaon = 3,
 644     kProton = 4,
 645
 646     kDeuteron = 5,
 647     kTriton = 6,
 648     kHe3 = 7,
 649     kAlpha = 8,
 650
 651     kPhoton = 9,
 652     kPi0 = 10,
 653     kNeutron = 11,
 654     kKaon0 = 12,
 655     kEleCon = 13,
 656
 657     kUnknown = 14
 658   };\end{lstlisting}
 659   Note that not all these particles may be available for selection via \texttt{AliFlowTrackCuts}!
 660
 661   The second argument tells the \texttt{AliFlowTrackCuts} class which particle identification method\index{particle identification!methods} should be used. The available methods are
 662   \begin{lstlisting}[language=C, numbers=left]
 663     enum PIDsource {
 664                    kTPCpid,      // default TPC pid (via GetTPCpid)
 665                    kTOFpid,      // default TOF pid (via GetTOFpid)
 666                    kTOFbayesian, // TOF bayesian pid (F.Noferini)
 667                    kTOFbeta,     // asymmetric cuts of TOF beta signal
 668                    kTPCdedx,      // asymmetric cuts of TPC dedx signal
 669                    kTOFbetaSimple, //simple TOF only cut
 670                    kTPCbayesian, //bayesian cutTPC
 671                    kTPCNuclei,   // added by Natasha for Nuclei
 672                    kTPCTOFNsigma // simple cut on combined tpc tof nsigma
 673                    };\end{lstlisting}
 674
 675 The third argument (with a default value of 0.9) gives the analyzer control over the purity of the particle sample by setting a lower bound on the probability that a particle is of a certain species (where 0 would mean no selection and 1 -theoretically - means a 100\% pure sample). To see how - and if - this parameter is used in a certain identification routine, take a look at the source code.
 676
 677 The best way of understanding how particles are identified is by just browsing the relevant pieces of the code in the \texttt{AliFlowTrackCuts.cxx} file (look at the list of \texttt{Passes$\ast$Cuts()}, but to give a very short overview:
 678 \begin{description}
 679 \item[kTPCpid] Return particle identity as stored in the \texttt{AliESDtrack}, TPC information only;
 680 \item[kTOFpid] Return particle identify as stored in the \texttt{AliESDtrack}, TOF information only;
 681 \item[kTOFbayesian] Combined TPC and TOF Bayesian PID method;
 682 \item[kTOFbeta] PID based on asymmetric TOF $\beta$ cut;
 683 \item[kTPCdedx] PID cut using TPC $\frac{dE}{dx}$ measurements stored in the \texttt{AliESDtrack},
 684 \item[kTOFbetaSimple] PID cut based on TOF time stored in the \texttt{AliESDtrack};
 685 \item[kTPCbayesian] Bayesian cut based on TPC or TOF signal;
 686 \item[kTPCNuclei] PID selection for heavy nuclei;
 687 \item[kTPCTOFNsigma]  Cut based in a simple combined cut on the $n$-$\sigma$ signal from TPC and TOF, requires PID response object. The PID response object is created by the PID response task, and thus requires that the PID response task runs in an analysis train \emph{before} the \texttt{AliFlowTrackCuts} class does its selection. To enable the PID response task, add the following lines to your run macro:
 688 \begin{lstlisting}[language=C, numbers=left]
 689 gROOT->LoadMacro("ANALYSIS/macros/AddTaskPIDResponse.C");
 690 AddTaskPIDResponse();\end{lstlisting}
 691 The default value for $n$-$\sigma$ is 3, but it can be set to a different
 692 value using
 693 \begin{lstlisting}[language=C, numbers=left]
 694 void AliFlowTrackCuts::SetNumberOfSigmas(Float_t val);\end{lstlisting}
 695 \end{description}
 696
 697 \subsubsection{Caveats and notes}
 698 \index{particle identification!caveats}
 699 \begin{description}
 700 \item[Applicability of cuts to different data types] Just as not all event and track cuts that are available for all data types. For the track quality cuts this has been explained in the previous subsections, but one has to realize that in addition, not all particle identification methods are available for all types of data. At the time of writing, the \texttt{ESD} particle identification is more elaborate than the \texttt{AOD} counterpart. To see which PID methods exist for the different data types, check the \texttt{AliFlowTrackCuts::Passes$\ast$pidCut()} functions,  printed below for your convenience.
 701
 702 \begin{lstlisting}[language=C, numbers=left]
 703 Bool_t AliFlowTrackCuts::PassesAODpidCut(const AliAODTrack* track )
 704 {
 705      if(!track->GetAODEvent()->GetTOFHeader()){
 706           AliAODPid *pidObj = track->GetDetPid();
 707           if (!pidObj) fESDpid.GetTOFResponse().SetTimeResolution(84.);
 708           else{
 709             Double_t sigmaTOFPidInAOD[10];
 710             pidObj->GetTOFpidResolution(sigmaTOFPidInAOD);
 711             if(sigmaTOFPidInAOD[0] > 84.){
 712               fESDpid.GetTOFResponse().SetTimeResolution(sigmaTOFPidInAOD[0]); // use the electron TOF PID sigma as time resolution (including the T0 used)
 713           }
 714         }
 715      }
 716
 717  //check if passes the selected pid cut for ESDs
 718   Bool_t pass = kTRUE;
 719   switch (fPIDsource)
 720   {
 721    case kTOFbeta:
 722       if (!PassesTOFbetaCut(track)) pass=kFALSE;
 723       break;
 724   case kTOFbayesian:
 725       if (!PassesTOFbayesianCut(track)) pass=kFALSE;
 726       break;
 727   case kTPCbayesian:
 728       if (!PassesTPCbayesianCut(track)) pass=kFALSE;
 729       break;
 730   case kTPCTOFNsigma:
 731       if (!PassesTPCTOFNsigmaCut(track)) pass = kFALSE;
 732       break;
 733   default:
 734     return kTRUE;
 735     break;
 736  }
 737   return pass;
 738
 739 }
 740 //-----------------------------------------------------------------------
 741 Bool_t AliFlowTrackCuts::PassesESDpidCut(const AliESDtrack* track )
 742 {
 743   //check if passes the selected pid cut for ESDs
 744   Bool_t pass = kTRUE;
 745   switch (fPIDsource)
 746   {
 747     case kTPCpid:
 748       if (!PassesTPCpidCut(track)) pass=kFALSE;
 749       break;
 750     case kTPCdedx:
 751       if (!PassesTPCdedxCut(track)) pass=kFALSE;
 752       break;
 753     case kTOFpid:
 754       if (!PassesTOFpidCut(track)) pass=kFALSE;
 755       break;
 756     case kTOFbeta:
 757       if (!PassesTOFbetaCut(track)) pass=kFALSE;
 758       break;
 759     case kTOFbetaSimple:
 760       if (!PassesTOFbetaSimpleCut(track)) pass=kFALSE;
 761       break;
 762     case kTPCbayesian:
 763       if (!PassesTPCbayesianCut(track)) pass=kFALSE;
 764       break;
 765     case kTOFbayesian:
 766       if (!PassesTOFbayesianCut(track)) pass=kFALSE;
 767       break;
 768     case kTPCNuclei:
 769       if (!PassesNucleiSelection(track)) pass=kFALSE;
 770       break;
 771     case kTPCTOFNsigma:
 772       if (!PassesTPCTOFNsigmaCut(track)) pass = kFALSE;
 773       break;
 774     default:
 775       printf("AliFlowTrackCuts::PassesCuts() this should never be called!\n");
 776       pass=kFALSE;
 777       break;
 778   }
 779   return pass;
 780 }\end{lstlisting}
 781 In general, particle identification is not a trivial procedure, and one needs to find a balance between purity and efficiency. Which particle identification to choose depends heavily on the desired outcome of the analysis. In case of e.g. a high-precision measurement of $\pi$ $v_2$, a method which has a very high purity but low efficiency can be chosen: $\pi$'s are an abundant particle species and high precision requires high purity. On the other hand, if one does selection for kaons to reconstruct $\varphi$-mesons, loose cuts with high efficiency can be chosen, as the $\varphi$-meson is a rare probe and invariant mass requirements on the kaon pairs will take care of mis-identifications.
 782
 783 To get access to QA information on track selection \emph{before} and \emph{after} PID cuts, the QA mode of the \texttt{AliFlowTrackCuts} can be selected.
 784
 785 \item[Track cuts outside of the \texttt{AliAnalysisTaskFlowEvent} class] Just as the flow event cuts can be used outside of the \texttt{AliAnalysisTaskFlowEvent} class, one can use the \texttt{AliFlowTrackCuts} class in a similar way, by calling, for each track,
 786 \begin{lstlisting}[language=C, numbers=left]
 787 Bool_t AliFlowTrackCuts::IsSelected(TObject* obj, Int_t id)\end{lstlisting}
 788 or directly one of the \texttt{PassesCuts($\ast$)} functions which \texttt{IsSelected()} calls.
 789 \end{description}
 790
 791 \subsubsection{VZERO}\index{track selection!VZERO}\index{VZERO}
 792 Now that the barrel tracks have been explained, let's continue to the treatment of VZERO information. The VZERO detector consists of two scintillator arrays at opposite sides of the interaction point (VZEROA and VZEROC) each containing 32 readout channels. To convert the VZERO information to \texttt{AliFlowTrackCuts}, two steps are taken:
 793 \begin{enumerate}
 794 \item A `track' is built from a VZERO tile by taking the geometric mean of the tile as the track direction (from which $\eta$ and $\varphi$ can be constructed);
 795 \item The VZERO analogue signal strength within a VZERO tile (which is proportional to charge deposition) is taken as a weight when evaluating the total \textbf{Q} vector.
 796 \end{enumerate}
 797 As there is no straightforward way to convert VZERO multiplicity to $p_t$, the VZERO signal can in principle not be used as POI in the flow analysis, neither can a $p_t$ range be selected when using the VZERO as RP selection. In addition to this, the `raw' VZERO signal itself cannot be used directly for flow analysis  but needs to be calibrated tile-by-tile. To understand how this calibration is performed in the flow package, we need to go into a little bit of detail on how to build a \textbf{Q} vector.
 798
 799 In general, a \textbf{Q} vector is defined as
 800 \begin{equation}\label{qvzero}
 801 \mbox{\textbf{Q}} = \sum_{\mbox{tracks}} w_i \exp \left( i n \varphi \right)
 802 \end{equation}
 803 where $w_i$ is a track weight, $n$ is the harmonic, and $\varphi$ is the azimuthal angle of a track.  As explained, in the case of VZERO tiles, $\varphi$ is derived from the position of the VZERO tile and $w_i$ is the VZERO signal which is proportional to multiplicity. However, not all VZERO tiles are equally sensitive, and the sensitivity (can have) a run-number dependence, which results in a non-flat VZERO \textbf{Q} vector distribution. As this effect might be different run-by-run, it cannot be corrected by applying a non-uniform acceptance correction at the end of your analysis, as an analysis generally comprises running over multiple run-numbers and the non-uniform acceptance correction corrects only for non-uniformity which is equal for all runs. Hence, the VZERO non-uniformity needs to be corrected\index{VZERO!calibration} at the time of the construction of the \textbf{Q} vectors.
 804
 805 The functions in the flow package which are responsible for building the \textbf{Q} vectors (or sub-event \textbf{Q} vectors, the use of which will be described in subsection \ref{sec:scalar_product}) are
 806 \begin{lstlisting}[language=C, numbers=left]
 807 // Q-vector  calculation
 808 AliFlowVector AliFlowEventSimple::GetQ(
 809     Int_t n,                            // harmonic
 810     TList *weightsList,                 // weight list
 811     Bool_t usePhiWeights,       // use phi weights?
 812     Bool_t usePtWeights,        // use pt weights?
 813     Bool_t useEtaWeights        // use eta weights?
 814     )
 815
 816 // Q-vectors of sub-events
 817 void AliFlowEventSimple::Get2Qsub(
 818         AliFlowVector* Qarray,  // array with q-vectors
 819     Int_t n,
 820     TList *weightsList,
 821     Bool_t usePhiWeights,
 822     Bool_t usePtWeights,
 823     Bool_t useEtaWeights
 824     )
 825
 826 // overloaded implementation of Q-vectors of sub-events for VZERO information
 827 void AliFlowEvent::Get2Qsub(
 828         AliFlowVector* Qarray,
 829         Int_t n,
 830         TList *weightsList,
 831         Bool_t usePhiWeights,
 832         Bool_t usePtWeights,
 833         Bool_t useEtaWeights
 834         )\end{lstlisting}
 835 These functions are called by the flow analysis tasks and generally not by the user directly, but it is good to know where they can be found. The first two functions merely loop over all tracks in a flow event and fill the \textbf{Q} vector. The last function is designed for building a \textbf{Q} vector from VZERO information, applying a calibration step to the VZERO signal. To make life complicated, the calibration of the VZERO \textbf{Q} vector in LHC10h is not the same as the calibration of the VZERO \textbf{Q} vector LHC11h data. Let's start by taking a look at the LHC10h case.
 836 \begin{description}
 837     \item [LHC10h]\index{VZERO!calibration!LHC10h}
 838 The calibration of LHC10h data is a two-step procedure.
 839 \begin{itemize}
 840 \item The first step is evaluating the \textbf{Q} vector using equation \ref{qvzero}. However, the VZERO signal of each tile is \emph{re-weighted} before it is used as a weight in equation \ref{qvzero}. The re-weighting comprises
 841 \begin{enumerate}
 842 \item Taking a \texttt{TProfile} with average multiplicity per cell (these profiles are stored in a \texttt{OADB} file for each run-number)
 843 \item Fitting a constant line per disc (or ring) $y = a$ (see next slide for example)
 844 \item Evaluating the track weight for each VZERO cell is now calculated in a second iteration as
 845 \begin{equation}
 846 \mbox{track weight} = \frac{\mbox{cell multiplicity} * a}{\mbox{average multiplicity in a cell}}
 847 \end{equation}
 848 \end{enumerate}
 849 \item After the \textbf{Q} vectors have been built, they are re-centered. Re-centering is basically a small adjustment of the components of the \textbf{Q} vector, changing its angle event-by-event so that on average a flat \textbf{Q} vector distribution is obtained. The steps that are taken for re-centering are the following:
 850 \begin{enumerate}
 851 \item Retrieve the average mean and spread of the \textbf{Q} vector distribution from a database file;
 852 \item The corrected \textbf{Q} vectors can now be obtained by doing
 853 \begin{equation}
 854 Q_n \longrightarrow \frac{Q_n - \langle Q_n \rangle }{\sigma_{Q_n}}
 855 \end{equation}
 856 where brackets denote the one-run average, and $\sigma_{Q_n}$ the standard deviation of $Q_n$ in the sample
 857 \end{enumerate}
 858 \end{itemize}
 859 Note that the calibration is only available for $n=2$ and $n=3$. For higher harmonics, the flow package will use the equalized VZERO multiplicity
 860 \begin{lstlisting}[language=C, numbers=left]
 861 AliVEvent::GetVZEROEqMultiplicity(Int_t i);\end{lstlisting}
 862 to build the \textbf{Q} vectors, whether this is satisfactory for an analysis, or if non-uniform acceptance effects can be reverted by performing a correction on a run-by-run basis is up to the analyzer. The \textbf{Q} vector distributions of total \textbf{Q} vectors and sub-event vectors can always be checked via the \texttt{AliFlowCommonHists} classes (see section \ref{sec:commonhists}) via
 863 \begin{lstlisting}[language=C, numbers=left]
 864   TH1F*     GetHistQ()               {return fHistQ; } ;
 865   TH1F*     GetHistAngleQ()          {return fHistAngleQ; }
 866   TH1F*     GetHistAngleQSub0()      {return fHistAngleQSub0; }
 867   TH1F*     GetHistAngleQSub1()      {return fHistAngleQSub1; }\end{lstlisting}
 868 \item [LHC11h]\index{VZERO!calibration!LHC11h} The calibration of the LHC11h VZERO information is not performed by the flow package, but by an external class, name the VZEROEPselection task, which will store the corrected \textbf{Q} vectors in the AliVEvent header, from which they are retrieved by the \textbf{AliFlowTrackCuts} class. To use this method, make sure that you run this VZEROEPselection task \emph{before} your flow analysis tasks in an analysis train. To enable this task, add the following lines to your analysis macro
 869 \begin{lstlisting}[language=C, numbers=left]
 870 gROOT->LoadMacro("$ALICE_ROOT/ANALYSIS/macros/AddTaskVZEROEPSelection.C");
 871 AddTaskVZEROEPSelection();\end{lstlisting}
 872 \end{description}
 873 Note that for LHC11h data, calibration is performed only for the second harmonic ($n=2$). For higher harmonics, the flow package uses equalized VZERO multiplicity to build \textbf{Q} vectors (as indicated for the LHC10h data).
 874
 875 After describing how and why calibration is performed, it is now time to indicate how to set up this calibration routine. Just as selecting barrel tracks, this can be done by creating an \texttt{AliFlowTrackCuts} object via a \texttt{static} access method,
 876 \begin{lstlisting}[language=C, numbers=left]
 877 AliFlowTrackCuts* cutsVZERO = GetStandardVZEROOnlyTrackCuts();\end{lstlisting}
 878 At run-time, the flow package will detector whether LHC10h or LHC11h data is used by reading the analyzed events' run-number. This can be convenient when having these cuts defined in a script which is designed to run on multiple types of input data. However, one can also call the LHC10h or LHC11h specific cuts directly via dedicated functions, which are reprinted here as the comments are important
 879
 880 \begin{lstlisting}[language=C, numbers=left]
 881 AliFlowTrackCuts* AliFlowTrackCuts::GetStandardVZEROOnlyTrackCuts2010()
 882 {
 883   //get standard VZERO cuts
 884   //DISCLAIMER: LHC10h VZERO calibration consists (by default) of two steps
 885   //1) re-weigting of signal
 886   //2) re-centering of q-vectors
 887   //step 2 is available only for n==2 and n==3, for the higher harmonics the user
 888   //is repsonsible for making sure the q-sub distributions are (sufficiently) flat
 889   //or a sensible NUA procedure is applied !
 890   AliFlowTrackCuts* cuts = new AliFlowTrackCuts("standard vzero flow cuts");
 891   cuts->SetParamType(AliFlowTrackCuts::kVZERO);
 892   cuts->SetEtaRange( -10, +10 );
 893   cuts->SetEtaGap(-1., 1.);
 894   cuts->SetPhiMin( 0 );
 895   cuts->SetPhiMax( TMath::TwoPi() );
 896   // options for the reweighting
 897   cuts->SetVZEROgainEqualizationPerRing(kFALSE);
 898   cuts->SetApplyRecentering(kTRUE);
 899   // to exclude a ring , do e.g.
 900   // cuts->SetUseVZERORing(7, kFALSE);
 901   // excluding a ring will break the re-centering as re-centering relies on a
 902   // database file which tuned to receiving info from all rings
 903   return cuts;
 904 }
 905 //-----------------------------------------------------------------------
 906 AliFlowTrackCuts* AliFlowTrackCuts::GetStandardVZEROOnlyTrackCuts2011()
 907 {
 908   //get standard VZERO cuts for 2011 data
 909   //in this case, the vzero segments will be weighted by
 910   //VZEROEqMultiplicity,
 911   //if recentering is enableded, the sub-q vectors
 912   //will be taken from the event header, so make sure to run
 913   //the VZERO event plane selection task before this task !
 914   //DISCLAIMER: recentering is only available for n==2
 915   //for the higher harmonics the user
 916   //is repsonsible for making sure the q-sub distributions are (sufficiently) flat
 917   //or a sensible NUA procedure is applied !
 918   //recentering replaces the already evaluated q-vectors, so
 919   //when chosen, additional settings (e.g. excluding rings)
 920   //have no effect. recentering is true by default
 921   //
 922   //NOTE user is responsible for running the vzero event plane
 923   //selection task in advance, e.g. add to your launcher macro
 924   //
 925   //  gROOT->LoadMacro("$ALICE_ROOT/ANALYSIS/macros/AddTaskVZEROEPSelection.C");
 926   //  AddTaskVZEROEPSelection();
 927   //
 928   AliFlowTrackCuts* cuts = new AliFlowTrackCuts("standard vzero flow cuts 2011");
 929   cuts->SetParamType(kVZERO);
 930   cuts->SetEtaRange( -10, +10 );
 931   cuts->SetEtaGap(-1., 1.);
 932   cuts->SetPhiMin( 0 );
 933   cuts->SetPhiMax( TMath::TwoPi() );
 934   cuts->SetApplyRecentering(kTRUE);
 935   cuts->SetVZEROgainEqualizationPerRing(kFALSE);
 936  return cuts;
 937 }\end{lstlisting}
 938
 939 \subsubsection{Caveats and remarks}\index{VZERO!caveats}
 940 Using the VZERO as reference detector in a flow analysis certainly has its benefits (such as suppressing the non-flow contribution to the $v_n$ signal) but a few remarks have to be made
 941 \begin{description}
 942 \item[Applicability to flow analysis methods] As the calibration affects the information that is returned by the function
 943 \begin{lstlisting}[language=C, numbers=left]
 944 void AliFlowEvent::Get2Qsub()\end{lstlisting}
 945 only flow analysis methods which call this function (and thus use sub-events) can use the calibrated VZERO signal. Most notably, this is the scalar product method. In combination with this, one should keep in mind that the two VZERO detectors have different $\eta$ coverage. For the recent \texttt{ALICE} paper on the flow of identified particles, the scalar product method with VZERO sub-events was used, where the two VZERO detectors comprised the two sub-events. For more information on this, take a look at the description of the scalar product method in subsection \ref{sec:scalar_product}.
 946 \item[VZERO as RP source] The VZERO signal should only be used as source for reference flow. Although technically there is no objection to using the VZERO signal as POI's (you will probably get output) there is no guarantee that this makes sense from a `physics' viewpoint;
 947 \item[Tuning of the calibration] The calibration in the LHC11h data is taken from an external class and therefore, as far as the flow package is considered, as-is (although the calibration can be disabled). The LHC10h calibration however is done within the package, and can be tuned quite a bit.
 948
 949 Tuning the calibration is done by functions of the \texttt{AliFlowTrackCuts} class. Some of these functions apply to both LHC10h and LHC11h data but can have slightly different effects:
 950 \begin{lstlisting}[language=C, numbers=left]
 951   // to either enable or disable the recentering
 952   // (for 11h this will mean that no calibration is performed,
 953   // for 10h it will result in only doing a re-weighting)
 954   void SetApplyRecentering(Bool_t r)
 955   // to enable a per-ring instead of per-disc gain equalization (=re-weighting)
 956   // (for 11h this has no effect)
 957   void SetVZEROgainEqualizationPerRing(Bool_t s)
 958   // exclude vzero rings: 0 through 7 can be excluded by calling this setter multiple times
 959   // 0 corresponds to segment ID 0 through 7, etc
 960   // disabled vzero rings get weight 0
 961   // with this function you can omit information from entire vzero rings
 962   // might be useful for runs where there is a bad signal in one of the tiles
 963   // (sometimes referred to as 'clipping')
 964   void SetUseVZERORing(Int_t i, Bool_t u)\end{lstlisting}
 965 Be warned however: the databases which are read during the calibration however are tuned to the combination of re-weighting of all rings with re-centering. Changing this combination might lead to biases in the \textbf{Q} vector distribution, so: playing with the calibration settings might be interesting for e.g. evaluating systematic uncertainties, but keep an eye on the control histograms!
 966 \end{description}
 967
 968 \subsubsection{Track weights}\index{track weights}\label{sec:weights}
 969 When it is a-priori know that a track sample needs to be weighted in $\varphi$, $\eta$ or $p_t$ (e.g. to correct for a non-uniform acceptance bias in azimuth by using weight which are inversely proportional to the azimuthal track distribution) histograms with weight distributions can be supplied to the flow package. The weights are supplied to flow analysis tasks, which then apply these weights by passing them to the \texttt{Q} vector calculation functions which are printed in the previous subsection.
 970
 971 The weights have to be supplied as \texttt{TH1F} objects (or objects which can be dynamically cast to a \texttt{TH1F} encapsulated in \texttt{TList}. The histograms have to have specific names: \texttt{"phi\_weights"} for $\varphi$ weights, \texttt{"pt\_weights"} for $p_t$ weights and \texttt{"eta\_weights"} for $\eta$ weights. The binning of the histograms is not important, as long as bins are of equal width. The weights are disabled by default and have to be passed to specific flow analysis tasks (as not all tasks support weights) via
 972 \begin{lstlisting}[language=C, numbers=left]
 973 // set weight list
 974 AliFlowAnalysisWith*::SetWeightsList(TList* const)
 975 // toggle phi weights on / off
 976 AliFlowAnalysisWith*::SetUsePhiWeights(Bool_t const)
 977 // toggle eta weighs on / off
 978 AliFlowAnalysisWith*::SetUseEtaWeights(Bool_t const)
 979 // toggle pt weights on / off
 980 AliFlowAnalysisWith*::SetUsePtWeights(Bool_t const)\end{lstlisting}
 981 and are applied to total \texttt{Q} vectors and sub-event \texttt{Q} vectors.
 982
 983 The tasks which support weights are
 984 \begin{itemize}
 985 \item AliFlowAnalysisWithNestedLoops
 986 \item AliFlowAnalysisWithScalarProduct
 987 \item AliFlowAnalysisWithQCumulants
 988 \item AliFlowAnalysisTemplate
 989 \item AliFlowAnalysisWithFittingQDistribution
 990 \item AliFlowAnalysisWithCumulants
 991 \item AliFlowAnalysisWithMixedHarmonics
 992 \end{itemize}
 993 For details on how the weighting is implemented (and defined) the user is referred to the specific \texttt{Q} vector evaluation functions given in the previous subsection.
 994
 995 \subsubsection{AliFlowCommonConstants - The Common Constants class}\index{AliFlowCommonConstants}
 996 All flow analysis use a common output container to store their histograms. To set the configuration for the histograms in these containers - e.g. the $p_t$ ranges of histograms, the number of bins, etc, etc - all flow analysis methods initialize their output containers using variables from a static (global) instance of the \texttt{AliFlowCommonConstants}\index{AliFlowCommonConstants} class. This object, which can be obtained via the a static function
 997 \begin{lstlisting}[language=C, numbers=left]
 998 static AliFlowCommonConstants* GetMaster(); \end{lstlisting}
 999 can be tuned to the  user's liking by requesting a pointer to it via the static access method, and using the available setter functions, e.g. the following
1000 \begin{lstlisting}[language=C, numbers=left]
1001 AliFlowCommonConstants* cc = AliFlowCommonConstants::GetMaster();
1002 cc->SetNbinsPt(100);
1003 cc->SetPtMin(0);
1004 cc->SetPtMax(10); \end{lstlisting}
1005 will result in an analysis which is performed in 100 $p_t$ bins of 0.1 GeV/$c$ width. The full set of histogram sizes and limits that can be set is
1006
1007 \begin{lstlisting}[language=C, numbers=left]
1008  //histogram sizes
1009   Int_t  fNbinsMult; // histogram size
1010   Int_t  fNbinsPt;   // histogram size
1011   Int_t  fNbinsPhi;  // histogram size
1012   Int_t  fNbinsEta;  // histogram size
1013   Int_t  fNbinsQ;    // histogram size
1014   Int_t  fNbinsMass; // histogram size
1015
1016   // Histograms limits
1017   Double_t  fMultMin;  // histogram limit
1018   Double_t  fMultMax;  // histogram limit
1019   Double_t  fPtMin;    // histogram limit
1020   Double_t  fPtMax;    // histogram limit
1021   Double_t  fPhiMin;     // histogram limit
1022   Double_t  fPhiMax;   // histogram limit
1023   Double_t  fEtaMin;     // histogram limit
1024   Double_t  fEtaMax;     // histogram limit
1025   Double_t  fQMin;         // histogram limit
1026   Double_t  fQMax;     // histogram limit
1027   Double_t  fMassMin;  // histogram limit
1028   Double_t  fMassMax;  // histogram limit
1029   Double_t  fHistWeightvsPhiMin; // histogram limit
1030   Double_t  fHistWeightvsPhiMax; // histogram limit\end{lstlisting}
1031
1032   via the setters
1033
1034   \begin{lstlisting}[language=C, numbers=left]
1035     void SetNbinsMult( Int_t i ) { fNbinsMult = i; }
1036   void SetNbinsPt( Int_t i )   { fNbinsPt = i; }
1037   void SetNbinsPhi( Int_t i )  { fNbinsPhi = i; }
1038   void SetNbinsEta( Int_t i )  { fNbinsEta = i; }
1039   void SetNbinsQ( Int_t i )    { fNbinsQ = i; }
1040   void SetNbinsMass( Int_t i ) { fNbinsMass = i; }
1041   void SetMultMin( Double_t i ) { fMultMin = i; }
1042   void SetMultMax( Double_t i ) { fMultMax = i; }
1043   void SetPtMin( Double_t i )   { fPtMin = i; }
1044   void SetPtMax( Double_t i )   { fPtMax = i; }
1045   void SetPhiMin( Double_t i )  { fPhiMin = i; }
1046   void SetPhiMax( Double_t i )  { fPhiMax = i; }
1047   void SetEtaMin( Double_t i )  { fEtaMin = i; }
1048   void SetEtaMax( Double_t i )  { fEtaMax = i; }
1049   void SetQMin( Double_t i )    { fQMin = i; }
1050   void SetQMax( Double_t i )    { fQMax = i; }
1051   void SetMassMin( Double_t i )    { fMassMin = i; }
1052   void SetMassMax( Double_t i )    { fMassMax = i; }
1053   void SetHistWeightvsPhiMax( Double_t d ) {fHistWeightvsPhiMax=d;}
1054   void SetHistWeightvsPhiMin( Double_t d ) {fHistWeightvsPhiMin=d;}\end{lstlisting}
1055
1056 Note that the common constants object is \texttt{static}, meaning that, within a process (e.g. an analysis train) just \emph{one} instance of the object is created. The histogram limits and sizes that are set via the common constants object therefore affect \emph{all} histograms within an analysis chain.
1057
1058 \subsubsection{AliFlowCommonHist and AliFlowCommonHistResults - details}\index{AliFlowCommonHist!details}\index{AliFlowCommonHistResults!details}
1059 Both the \texttt{AliFlowCommonHist} and \texttt{AliFlowCommonHistResults} classes do not only contain (pointers to) histograms and profiles, but also have a collection of `getters'\footnote{A `getter' in this manual will be used to describe a function of the form \texttt{Get$\ast$()} which returns a (pointer to) a member of a class and is used to interface with the class.} which you can use to retrieve histograms of profiles using the \texttt{ROOT} command line in stead of the \texttt{TBrowser}, which may come in handy when one needs to read the output of the flow analysis tasks in a macro.
1060
1061 Using the output file that was generated in the example given in the previous sections of this chapter, reading the objects of the common histogram classes is done in the following way. First, start an \texttt{(Ali)ROOT} session, and load the prerequisite libraries,
1062 \begin{lstlisting}[language=C, numbers=left]
1063 gSystem->Load("libPWGflowBase");\end{lstlisting}
1064 Then, open the analysis file and grab the common histogram objects
1065 \begin{lstlisting}[language=C, numbers=left]
1066 // open the file
1067 TFile f("AnalysisResults.root");
1068 // get the qc analysis output directory
1069 TDirectoryFile* dir = (TDirectoryFile*)f.Get("outputQCanalysis");
1070 // and retrieve the output list of the analysis
1071 TList* outputList = (TList*)dir->Get("cobjQC")\end{lstlisting}
1072 The \texttt{TList} that you have just obtained holds not only the common histogram objects, but can also hold additional information that has been added to the analysis output by a specific flow analysis task. To read the entire content of the \texttt{TList}, you can type
1073 \begin{lstlisting}[language=C, numbers=left]
1074 outputList->ls();\end{lstlisting}
1075 However, in this example we want to retrieve the common histogram objects. To do so, type
1076 \begin{lstlisting}[language=C, numbers=left]
1077 // get common histogram object from the TList
1078 AliFlowCommonHist* commonHist = (AliFlowCommonHist*)outputList->FindObject("AliFlowCommonHistQC");
1079 // get the results for the 2 particle cumulant from the TList
1080 AliFlowCommonHistResults* commonHistResults2 = (AliFlowCommonHistResults*)outputList->FindObject("AliFlowCommonHistResults2ndOrderQC");\end{lstlisting}
1081 Once you have retrieved the pointers to the \texttt{AliFlowCommonHist} or \texttt{AliFlowCommonHistResults} objects, you can use the getters to retrieve a histogram. To e.g. draw the $\eta$ distribution of POI's, type
1082 \begin{lstlisting}[language=C, numbers=left]
1083  commonHist->GetHistEtaPOI()->Draw();\end{lstlisting}
1084
1085  The following getters are available in \texttt{AliFlowCommonHist}
1086  \begin{lstlisting}[language=C, numbers=left]
1087   Double_t GetEntriesInPtBinRP(Int_t iBin);   //gets entries from fHistPtRP
1088   Double_t GetEntriesInPtBinPOI(Int_t iBin);  //gets entries from fHistPtPOI
1089   Double_t GetEntriesInEtaBinRP(Int_t iBin);  //gets entries from fHistEtaRP
1090   Double_t GetEntriesInEtaBinPOI(Int_t iBin); //gets entries from fHistEtaPOI
1091   Double_t GetMeanPt(Int_t iBin);             //gets the mean pt for this bin from fHistProMeanPtperBin
1092   TH1F*     GetHistMultRP()          {return fHistMultRP; } ;
1093   TH1F*     GetHistMultPOI()         {return fHistMultPOI; } ;
1094   TH2F*     GetHistMultPOIvsRP()     {return fHistMultPOIvsRP; } ;
1095   TH1F*     GetHistPtRP()            {return fHistPtRP; } ;
1096   TH1F*     GetHistPtPOI()           {return fHistPtPOI; } ;
1097   TH1F*     GetHistPtSub0()          {return fHistPtSub0; } ;
1098   TH1F*     GetHistPtSub1()          {return fHistPtSub1; } ;
1099   TH1F*     GetHistPhiRP()           {return fHistPhiRP; } ;
1100   TH1F*     GetHistPhiPOI()          {return fHistPhiPOI; } ;
1101   TH1F*     GetHistPhiSub0()         {return fHistPhiSub0; } ;
1102   TH1F*     GetHistPhiSub1()         {return fHistPhiSub1; } ;
1103   TH1F*     GetHistEtaRP()           {return fHistEtaRP; } ;
1104   TH1F*     GetHistEtaPOI()          {return fHistEtaPOI;  } ;
1105   TH1F*     GetHistEtaSub0()         {return fHistEtaSub0;  } ;
1106   TH1F*     GetHistEtaSub1()         {return fHistEtaSub1;  } ;
1107   TH2F*     GetHistPhiEtaRP()        {return fHistPhiEtaRP;  } ;
1108   TH2F*     GetHistPhiEtaPOI()       {return fHistPhiEtaPOI;  } ;
1109   TProfile* GetHistProMeanPtperBin() {return fHistProMeanPtperBin; } ;
1110   TH2F*     GetHistWeightvsPhi()     {return fHistWeightvsPhi; } ;
1111   TH1F*     GetHistQ()               {return fHistQ; } ;
1112   TH1F*     GetHistAngleQ()          {return fHistAngleQ; }
1113   TH1F*     GetHistAngleQSub0()      {return fHistAngleQSub0; }
1114   TH1F*     GetHistAngleQSub1()      {return fHistAngleQSub1; }
1115   TProfile* GetHarmonic()            {return fHarmonic; } ;
1116   TProfile* GetRefMultVsNoOfRPs()    {return fRefMultVsNoOfRPs; } ;
1117   TH1F*     GetHistRefMult()         {return fHistRefMult; } ;
1118   TH2F*     GetHistMassPOI()         {return fHistMassPOI; }
1119   TList*    GetHistList()            {return fHistList;} ;  \end{lstlisting}
1120   and in \texttt{AliFlowCommonHistResults}
1121   \begin{lstlisting}[language=C, numbers=left]
1122   TH1D* GetHistChi(){return fHistChi;};
1123   TH1D* GetHistIntFlow(){return fHistIntFlow;};
1124   TH1D* GetHistIntFlowRP(){return fHistIntFlowRP;};
1125   TH1D* GetHistDiffFlowPtRP(){return fHistDiffFlowPtRP;};
1126   TH1D* GetHistDiffFlowEtaRP(){return fHistDiffFlowEtaRP;};
1127   TH1D* GetHistIntFlowPOI(){return fHistIntFlowPOI;};
1128   TH1D* GetHistDiffFlowPtPOI(){return fHistDiffFlowPtPOI;};
1129   TH1D* GetHistDiffFlowEtaPOI(){return fHistDiffFlowEtaPOI;};
1130   TList* GetHistList(){return fHistList;};  \end{lstlisting}
1131
1132   \subsubsection{Afterburner}\index{afterburner}
1133 To e.g. test your analysis setup, an `afterburner' can be called which adds  user-defined flow to (isotropic) events. Two afterburner techniques are implemented.
1134 \begin{description}
1135 \item[Differential $v_2$] The first technique injects differential $v_2$ into events, using the following steps: As a starting point, an isotropic distribution of tracks is used
1136 \begin{equation}
1137     \frac{dN}{d\varphi_0} = \frac{1}{2 \pi}.
1138 \end{equation}
1139 Adding a periodic azimuthal modulation, this is translated to
1140 \begin{equation}
1141     \frac{dN}{d\varphi} = \frac{1}{2\pi}\left( 1 + v_2 \cos \left[ 2 \left( \varphi - \Psi \right) \right] \right)
1142 \end{equation}
1143 which can be re-written as
1144 \begin{equation}
1145     \frac{dN}{d\varphi} = \frac{dN}{d\varphi_0}\frac{d\varphi_0}{d\varphi} = \frac{1}{2\pi}\frac{d\varphi_0}{d\varphi}
1146 \end{equation}
1147 so that for each track the following equation can be solved by Newton-Raphson iteration
1148 \begin{equation}
1149     \varphi = \varphi_0 - v_2 \sin \left[ 2 \left( \varphi - \Psi \right) \right].
1150 \end{equation}
1151 \item[Integrated $v_n$] The second option is adding integrated $v_n$ by sampling the azimuthal distribution of an event from a Fourier series
1152 \begin{equation}
1153 \frac{dN}{d\varphi} \propto 1 + \frac{1}{2} \sum_n v_n \left( n \Delta \varphi \right).
1154 \end{equation}
1155 \end{description}
1156 In the `quick start' of this manual you have already see how you can generate flow events with a certain $v_n$ value by generating flow events by hand. The afterburner routine can also be called from the \texttt{AliAnalysisTaskFlowEvent} via the functions
1157 \begin{lstlisting}[language=C, numbers=left]
1158  // setters for adding by hand flow values (afterburner)
1159
1160  // toggle the afterburner on / off
1161   void SetAfterburnerOn(Bool_t b=kTRUE) {fAfterburnerOn=b;}
1162  // set differential v2 via a TF1
1163   void SetPtDifferentialV2( TF1 *gPtV2) {fDifferentialV2 = gPtV2;}
1164   // set integrated flow (used when the gPtV2 = NULL)
1165   void SetFlow( Double_t v1, Double_t v2, Double_t v3=0.0, Double_t v4=0.0, Double_t v5=0.0)
1166                {fV1=v1;fV2=v2;fV3=v3;fV4=v4;fV5=v5;}\end{lstlisting}
1167 To introduce non-flow effects to using the afterburner, tracks can be cloned. To clone, for each event, a given number $n$ of tracks, enable the afterburner and call
1168 \begin{lstlisting}[language=C, numbers=left]
1169   void SetNonFlowNumberOfTrackClones(Int_t n) {fNonFlowNumberOfTrackClones=n;}\end{lstlisting}
1170 Effectively this will result in $n$ tracks appearing twice in the track sample, mimicking the effects of e.g. resonance decays of track splitting on $v_n$.
1171
1172 \subsection{Relevant pieces of code}
1173 The best way of getting familiar with the flow package is perhaps browsing the source code, but it can be difficult to find a good starting point for this. Two relevant pieces of code have been selected here which are at the heart of the flow package:
1174 \begin{enumerate}\index{AliAnalysisTaskFlowEvent::UserExec()}
1175 \item The AliAnalysisTaskFlowEvent::UserExec() function, which is called for each event that enters an analysis train;
1176 \item AliFlowEvent::Fill(), which selects POI's and RP's following the track selection criteria and fills the flow event which is passed to the analysis methods. The functions are shortened and simplified and provided with additional lines of comments.
1177 \end{enumerate}
1178 \subsubsection{AliAnalysisTaskFlowEvent::UserExec()}
1179 This function is called for each event.
1180 \begin{lstlisting}[language=C, numbers=left]
1181 void AliAnalysisTaskFlowEvent::UserExec(Option_t *)
1182 {
1183   // Main loop
1184   // Called for each event
1185   //delete fFlowEvent;
1186   AliMCEvent*  mcEvent = MCEvent();                              // from TaskSE
1187   AliESDEvent* myESD = dynamic_cast<AliESDEvent*>(InputEvent()); // from TaskSE
1188   AliAODEvent* myAOD = dynamic_cast<AliAODEvent*>(InputEvent()); // from TaskSE
1189
1190   // the rp and poi cuts will be used to fill the flow event
1191   // so they have to be defined here
1192   if (!(fCutsRP&&fCutsPOI&&fCutsEvent))
1193   {
1194     AliError("cuts not set");
1195     return;
1196   }
1197
1198   //DEFAULT - automatically takes care of everything
1199   // the flow package will determine the datatype that you are using
1200   if (fAnalysisType == "AUTOMATIC")
1201   {
1202     //check event cuts
1203     if (InputEvent() && !fCutsEvent->IsSelected(InputEvent(),MCEvent()))
1204       return;
1205
1206     //first attach all possible information to the cuts
1207     // the track cuts will make the track selection, so they
1208     // have to be supplied with the current event
1209     // the mc event is NULL unless it is retrieved by AliAnalysisTaskSE
1210     fCutsRP->SetEvent( InputEvent(), MCEvent() );  //attach event
1211     fCutsPOI->SetEvent( InputEvent(), MCEvent() );
1212
1213     //then make the event
1214     // this function will fill the flow event with selected poi's and rp's
1215     // the implementation is printed below
1216     fFlowEvent->Fill( fCutsRP, fCutsPOI );
1217
1218     // pass some event info to the flow event
1219     fFlowEvent->SetReferenceMultiplicity(fCutsEvent->GetReferenceMultiplicity(InputEvent(),mcEvent));
1220     fFlowEvent->SetCentrality(fCutsEvent->GetCentrality(InputEvent(),mcEvent));
1221     if (mcEvent && mcEvent->GenEventHeader()) fFlowEvent->SetMCReactionPlaneAngle(mcEvent);
1222   }
1223
1224   // a lot of code is omitted here //
1225
1226   //////////////////////////////////////////////////////////////////////////////
1227   ///////////////////////////AFTERBURNER
1228   if (fAfterburnerOn)
1229   {
1230     //if reaction plane not set from elsewhere randomize it before adding flow
1231     if (!fFlowEvent->IsSetMCReactionPlaneAngle())
1232       fFlowEvent->SetMCReactionPlaneAngle(gRandom->Uniform(0.0,TMath::TwoPi()));
1233
1234     if(fDifferentialV2)
1235       fFlowEvent->AddV2(fDifferentialV2);
1236     else
1237       fFlowEvent->AddFlow(fV1,fV2,fV3,fV4,fV5);     //add flow
1238     fFlowEvent->CloneTracks(fNonFlowNumberOfTrackClones); //add nonflow by cloning tracks
1239   }
1240   //////////////////////////////////////////////////////////////////////////////
1241
1242   //tag subEvents
1243   // some flow analysis methods (such as the scalar product)
1244   // use sub-events. by calling this function, all tracks in the
1245   // flow event are tagged as belonging to either sub-event a or b
1246   fFlowEvent->TagSubeventsInEta(fMinA,fMaxA,fMinB,fMaxB);\end{lstlisting}
1247
1248   \subsubsection{AliFlowEvent::Fill()}\label{sec:fill}\index{AliFlowEvent::Fill()}
1249   This function fills the flow event with \texttt{AliFlowSimpleTracks}. One important thing to notice here, is that both POI's and RP's are stored in a common array of flow tracks, internally only referred to as POI's. What distinguishes the POI's and RP's is their \emph{type}: RP's are stored as type 0 POI's, and POI's are stored as non-zero type POI's (where nonzero means 1, 2, 3 ...).
1250 \begin{lstlisting}[language=C, numbers=left]
1251 //-----------------------------------------------------------------------
1252 void AliFlowEvent::Fill( AliFlowTrackCuts* rpCuts,
1253                          AliFlowTrackCuts* poiCuts )
1254 {
1255   //Fills the event from a vevent: AliESDEvent,AliAODEvent,AliMCEvent
1256   //the input data needs to be attached to the cuts
1257   //we have two cases, if we're cutting the same collection of tracks
1258   //(same param type) then we can have tracks that are both rp and poi
1259   //in the other case we want to have two exclusive sets of rps and pois
1260   //e.g. one tracklets, the other PMD or global - USER IS RESPOSIBLE
1261   //FOR MAKING SURE THEY DONT OVERLAP OR ELSE THE SAME PARTICLE WILL BE
1262   //TAKEN TWICE
1263
1264   // remove the previous event
1265   ClearFast();
1266   if (!rpCuts || !poiCuts) return;
1267   // check the source of rp's
1268   AliFlowTrackCuts::trackParameterType sourceRP = rpCuts->GetParamType();
1269   // and ditto for the poi's
1270   AliFlowTrackCuts::trackParameterType sourcePOI = poiCuts->GetParamType();
1271
1272   AliFlowTrack* pTrack=NULL;
1273
1274   // if the source for rp's or poi's is the VZERO detector, get the calibration
1275   // and set the calibration parameters
1276   if (sourceRP == AliFlowTrackCuts::kVZERO) {
1277       SetVZEROCalibrationForTrackCuts(rpCuts);
1278       if(!rpCuts->GetApplyRecentering()) {
1279           // if the user does not want to recenter, switch the flag
1280           fApplyRecentering = -1;
1281       }
1282       // note: this flag is used in the overloaded implementation of Get2Qsub()
1283       // and tells the function to use as Qsub vectors the recentered Q-vectors
1284       // from the VZERO oadb file or from the event header
1285   }
1286   if (sourcePOI == AliFlowTrackCuts::kVZERO) {
1287       // probably no-one will choose vzero tracks as poi's ...
1288       SetVZEROCalibrationForTrackCuts(poiCuts);
1289   }
1290
1291
1292   if (sourceRP==sourcePOI)
1293   {
1294     //loop over tracks
1295     Int_t numberOfInputObjects = rpCuts->GetNumberOfInputObjects();
1296     for (Int_t i=0; i<numberOfInputObjects; i++)
1297     {
1298       //get input object (particle)
1299       TObject* particle = rpCuts->GetInputObject(i);
1300
1301       Bool_t rp = rpCuts->IsSelected(particle,i);
1302       Bool_t poi = poiCuts->IsSelected(particle,i);
1303
1304       if (!(rp||poi)) continue;
1305
1306       //make new AliFlowTrack
1307       if (rp)
1308       {
1309         pTrack = rpCuts->FillFlowTrack(fTrackCollection,fNumberOfTracks);
1310         if (!pTrack) continue;
1311         pTrack->Tag(0); IncrementNumberOfPOIs(0);
1312         if (poi) {pTrack->Tag(1); IncrementNumberOfPOIs(1);}
1313         if (pTrack->GetNDaughters()>0) fMothersCollection->Add(pTrack);
1314       }
1315       else if (poi)
1316       {
1317         pTrack = poiCuts->FillFlowTrack(fTrackCollection,fNumberOfTracks);
1318         if (!pTrack) continue;
1319         pTrack->Tag(1); IncrementNumberOfPOIs(1);
1320         if (pTrack->GetNDaughters()>0) fMothersCollection->Add(pTrack);
1321       }
1322       fNumberOfTracks++;
1323     }//end of while (i < numberOfTracks)
1324   }
1325   else if (sourceRP!=sourcePOI)
1326   {
1327     //here we have two different sources of particles, so we fill
1328     //them independently
1329     //POI
1330     for (Int_t i=0; i<poiCuts->GetNumberOfInputObjects(); i++)
1331     {
1332       TObject* particle = poiCuts->GetInputObject(i);
1333       Bool_t poi = poiCuts->IsSelected(particle,i);
1334       if (!poi) continue;
1335       pTrack = poiCuts->FillFlowTrack(fTrackCollection,fNumberOfTracks);
1336       if (!pTrack) continue;
1337       pTrack->Tag(1);
1338       IncrementNumberOfPOIs(1);
1339       fNumberOfTracks++;
1340       if (pTrack->GetNDaughters()>0) fMothersCollection->Add(pTrack);
1341     }
1342     //RP
1343     Int_t numberOfInputObjects = rpCuts->GetNumberOfInputObjects();
1344     for (Int_t i=0; i<numberOfInputObjects; i++)
1345       {
1346       TObject* particle = rpCuts->GetInputObject(i);
1347       Bool_t rp = rpCuts->IsSelected(particle,i);
1348       if (!rp) continue;
1349       pTrack = rpCuts->FillFlowTrack(fTrackCollection,fNumberOfTracks);
1350       if (!pTrack) continue;
1351       pTrack->Tag(0);
1352       IncrementNumberOfPOIs(0);
1353       fNumberOfTracks++;
1354       if (pTrack->GetNDaughters()>0) fMothersCollection->Add(pTrack);
1355     }
1356   }
1357 }\end{lstlisting}
1358
1359 \subsection{Some words on the ALICE analysis framework}
1360 Many of the classes which are described in the previous section deal with \texttt{ALICE} data (e.g. event and track selection). Generally, this data is analyzed in \texttt{ALICE} analysis framework. This framework is setup in the following way
1361 \begin{enumerate}
1362 \item An analysis manager \texttt{analysis manager} is created;
1363 \item The manager is connected to a source of input data (this can be data that is stored on your local machine, but more often data comes in the form of \texttt{.xml}\index{xml} files which point to data on \texttt{GRID} storage elements);
1364 \item A number of analysis tasks is initialized, configured, and added to the analysis manager (so that you construct an `analysis train')\index{analysis train};
1365 \item The analysis is performed, which in effect means that the manager reads an event, passes it to the analysis tasks (who analyze it sequentially), and repeats this until all events are read. In this way, an event can be analyzed by many tasks whilst reading it from file just once;
1366 \item The analysis outputs are gathered by the manager and written to an output file.
1367 \end{enumerate}
1368 In this case of the flow package, the most common way of using this framework is
1369 \begin{itemize}
1370 \item Creating flow events using the dedicated flow event task \texttt{AliAnalysisTaskFlowEvent};
1371 \item Analyzing these events using the \texttt{AliROOT} interface to the generic flow analysis tasks.
1372 \end{itemize}
1373
1374 \subsubsection{AliAnalysisTaskSE}
1375 All analysis tasks that are called by the analysis manager have to be derived from a common class, the \texttt{AliAnalysisTaskSE}\footnote{This section is very brief an incomplete, but keep in mind that this is a flow package manual, and not an \texttt{AliROOT} tutorial.} (where the suffix `SE' stands for `single event'). \texttt{AliAnalysisTaskSE} has a few virtual functions which can be called in user tasks by the analysis manager at specific times. Most notably these are
1376 \begin{description}
1377 \item[UserCreateOutputObjects] \index{UserCreateOutputObjects}This function is called \emph{before} the analysis starts;
1378 \item[UserExec] \index{UserExec}This function is called for each event;
1379 \item[Terminate] \index{Terminate}Called at the end of the analysis (after the last event has been processed).
1380 \end{description}
1381 So, why is this important for the flow package? As said, the analysis manager can only handle tasks that derive from \texttt{AliAnalysisTaskSE}. Therefore, all flow analysis in the flow package consist of \emph{two} classes:
1382 \begin{description}
1383 \item[AliAnalysisTask$\ast$] These can be found in the `tasks' directory of the flow package and are derived of \texttt{AliAnalysisTaskSE}. These classes interface with \texttt{AliROOT};
1384 \item[AliFlowAnalysisWith$\ast$] These can be found in the `base' folder of the flow package and perform the actual flow analysis.
1385 \end{description}
1386 In chapter \ref{sec:onthefly} of this manual, you have seen that, using just the \texttt{AliFlowAnalysisWith$\ast$} class, a flow analysis basically follows the path
1387 \begin{enumerate}
1388 \item \texttt{Init()}: called once to initialize the task and histograms;
1389 \item \texttt{Make()}: called for each event, does the analysis;
1390 \item \texttt{Finish()}: wrap up the analysis.
1391 \end{enumerate}
1392 When doing the analysis in the analysis framework, you will not use the \texttt{AliFlowAnalysisWith$\ast$} class, but instead use the \texttt{AliAnalysisTask$\ast$} which calls the \texttt{AliFlowAnalysisWith$\ast$} class for you via the calls from \texttt{AliAnalysisTaskSE}. To be more specific:
1393 \begin{enumerate}
1394 \item \texttt{Init()} is called in \texttt{UserCreateOutputObjects()};
1395 \item \texttt{Make()} is called in \texttt{UserExec()};
1396 \item \texttt{Finish()} is called in \texttt{Terminate()}.
1397 \end{enumerate}
1398 All of this may still seem a bit abstract at this point, but in principle you now know all you need to know about the structure of the flow package. It is recommended however that you take a look at the example in \ref{sec:example}, to get a step-by-step explanation of how these things work in the real world.
1399
1400 \subsubsection{Analysys on grid: redoFinish.C}
1401 As explained in \ref{sec:onthefly} and in the previous subsection, a flow analysis is finished by a call to \texttt{Finish()}. Although the exact implementation of \texttt{Finish()} is different for each flow analysis method, the general principle method in most methods is that calculations on event-averaged values are performed to end up with a final value for an observable.
1402
1403 \index{redoFinish.C} When an analysis is run in parallel on many nodes (e.g. when running on \texttt{GRID}\index{GRID}) the output of the flow analysis tasks in \texttt{AnalysisResults.root} is typically wrong, as merging files via \texttt{ROOT's} \texttt{TFileMerger}\index{TFileMerger} will trivially sum up results in all histograms.
1404
1405 The \texttt{redoFinish.C}\footnote{\texttt{\$ALICE\_ROOT/PWGCF/FLOW/macros/refoFinish.C}} macro re-evaluates all output that cannot trivially be merged and re-calls the \texttt{Finish()} method. To use \texttt{redoFinish.C}, make sure your analysis output file is called \texttt{mergedAnalysisResults.root} and simply run the macro
1406 \begin{lstlisting}[language=C, numbers=left]
1407 .L redoFinish.C
1408 redoFinish(); \end{lstlisting}
1409 \texttt{redoFinish.C} will produce a new \texttt{AnalysisResults.root} file with the corrected results by calling the \texttt{::Finish()}\index{Finish()} function on all known output structures in the \texttt{mergedAnalysisResults.root}\index{mergedAnalysisResults} file. Additionally \texttt{redoFinish.C} can be used to repeat the call to \texttt{::Finish()} with different settings, which might alter the outcome of the flow analysis (e.g. use a different strategy to correct for non-uniform acceptance).
1410
1411 The macro itself is well documented and lists several options that are available at the time of running:
1412 \begin{lstlisting}[language = C, numbers=left]
1413 // Macro redoFinish.C is typically used after the merging macros (mergeOutput.C or
1414 // mergeOutputOnGrid.C) have been used to produce the merged, large statistics
1415 // file of flow analysis. Results stored in merged file are WRONG because after
1416 // merging the results from small statistics files are trivially summed up in all
1417 // histograms. This is taken into account and corrected for with macro redoFinish.C.
1418 // Another typical use of the macro redoFinish.C is to repeat the call to Finish()
1419 // in all classes, but with different values of some settings which might modify
1420 // the final results (Example: redo the Finish() and apply correction for detector
1421 // effects in QC code because by default this correction is switched off).
1422
1423 // Name of the merged, large statistics file obtained with the merging macros:
1424 TString mergedFileName = "mergedAnalysisResults.root";
1425 // Final output file name holding correct final results for large statistics sample:
1426 TString outputFileName = "AnalysisResults.root";
1427
1428 Bool_t bApplyCorrectionForNUA = kFALSE; // apply correction for non-uniform acceptance
1429 Bool_t bApplyCorrectionForNUAVsM = kFALSE; // apply correction for non-uniform acceptance in each multiplicity bin independently
1430 Bool_t bPropagateErrorAlsoFromNIT = kFALSE; // propagate error also from non-isotropic terms
1431 Bool_t bMinimumBiasReferenceFlow = kTRUE; // store in CRH for reference flow the result obtained wihout rebinning in multiplicity (kTRUE)
1432 Bool_t checkForCommonHistResults = kTRUE; // check explicitely if the TList AliFlowCommonHistResults is available in the output\end{lstlisting}
1433
1434 Flow analysis output is recognized by keywords in output list names (e.g. a Q-cumulant output needs to have the letters `QC' somewhere in the name to be recognized).
1435
1436 When your analysis output is in the form of a merged file, \emph{always} run \texttt{redoFinish.C} to get your results!
1437
1438 \subsection{Example: $\pi^{\pm}$ $v_n$}\label{sec:example}\index{example}
1439 As an example of how to do a flow analysis using the flow package within the \texttt{AliROOT} analysis framework\index{analysis framework}, this section will guide you through the process of measuring $\pi^{\pm}$ $v_2$, $v_3$ and $v_4$ step-by-step, using the Q-vector cumulant flow analysis method.
1440
1441 Generally, doing an analysis in the \texttt{AliROOT} is a `two-file process', where one runs a run.C\index{run.C}\index{steering macro} script in \texttt{AliROOT} (coloquially referred to as `steering macro'), which sets up the analysis framework and takes care of the interface to the analysis \texttt{GRID}, and calls an \texttt{AddTask$\ast$.C}\index{AddTask macro} macro which in turn creates and configures instances of the relevant analysis tasks. In this example, the distinction will not be so clear, but mentioned in the text. In practice of course, you would copy these steps into macros and launch the macros from the \texttt{AliROOT} command line when doing analysis. We will not run this test on \texttt{GRID}, but assume that you have some \texttt{AliAOD.root} files available on your local system. Note that this example is a guideline, there are many ways leading to Rome, and many ways of setting up an analysis. Some of the variables that are set in the code examples below are actually also set by default. This may seem a little bit redundant, but it is done to make the reader aware of the fact that they exist.
1442
1443 A script which contains all the steps described below and should work `out-of-the-box' can be found at \texttt{\$ALICE\_ROOT/PWGCF/FLOW/Documentation/examples/manual/runFlowOnDataExample.C}.
1444 \begin{description}
1445 \item [Preparing the session] First, we need to prepare the framework and root session (these steps would go into your run.C macro). Launch \texttt{AliROOT} and load the necessary libraries
1446 \begin{lstlisting}[language=C, numbers=left]
1447   // load libraries
1448   gSystem->Load("libCore.so");
1449   gSystem->Load("libGeom.so");
1450   gSystem->Load("libVMC.so");
1451   gSystem->Load("libPhysics.so");
1452   gSystem->Load("libTree.so");
1453   gSystem->Load("libSTEERBase.so");
1454   gSystem->Load("libESD.so");
1455   gSystem->Load("libAOD.so");
1456   gSystem->Load("libANALYSIS.so");
1457   gSystem->Load("libANALYSISalice.so");
1458   gSystem->Load("libEventMixing.so");
1459   gSystem->Load("libCORRFW.so");
1460   gSystem->Load("libPWGTools.so");
1461   gSystem->Load("libPWGCFebye.so");
1462   gSystem->Load("libPWGflowBase.so");
1463   gSystem->Load("libPWGflowTasks.so"); \end{lstlisting}
1464   \item [Creating the manager and connecting input data]
1465       Create an analysis manager\index{analysis manager}\index{AliAnalysisManager} and create a \texttt{TChain}\index{TChain} which we will point to the data you have stored locally on your machine
1466 \begin{lstlisting}[language=C, numbers=left]
1467   // create the analysis manager
1468   AliAnalysisManager* mgr = new AliAnalysisManager("MyManager");
1469   // create a tchain which will point to an aod tree
1470   TChain* chain = new TChain("aodTree");
1471   // add a few files to the chain
1472   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0003/AliAOD.root");
1473   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0003/AliAOD.root");
1474   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0004/AliAOD.root");
1475   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0005/AliAOD.root");
1476   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0006/AliAOD.root");
1477   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0007/AliAOD.root");
1478   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0008/AliAOD.root");
1479   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0009/AliAOD.root");
1480   chain->Add("/home/rbertens/Documents/CERN/ALICE_DATA/data/2010/LHC10h/000139510/ESDs/pass2/AOD086/0010/AliAOD.root");
1481   // create an input handler
1482   AliVEventHandler* inputH = new AliAODInputHandler();
1483   // and connect it to the manager
1484   mgr->SetInputEventHandler(inputH);\end{lstlisting}
1485   Great, at this point we have created an analysis manager, which will read events from a chain of AliAOD.root files. \index{AliVEventHandler}\index{AliVEventHandler!AliAODInputHandler}
1486
1487 The next step will be adding specific analyses to the analysis manager. This is usually done by calling an \texttt{AddTask$\ast$.C} macro, which creates instances of analysis tasks, connects input (events from the analysis manager) to these tasks, and then connects output from the task back to the analysis manager (which will take care of writing the analysis to a common output file). These next steps show what would be in your \texttt{AddTask$\ast$.C} macro.
1488
1489 The heart of our flow analysis will be the flow event. To fill a flow event from the input AOD events, we will use the \texttt{AliAnalysisTaskFlowEvent}\index{example!AliAnalysisTaskFlowEvent} class. The AOD input events have to be supplied by the analysis manager, so first things first, retrieve the manager to which you will connect your flow analysis tasks\footnote{In the example macro this is a not necessary as you already have a pointer to the manager in your macro. However, if you split the macro into a steering macro and AddTask macro, the AddTask macro needs to retrieve a pointer to the manager which is created in the steering macro.}:
1490
1491 \begin{lstlisting}[language=C, numbers=left]
1492   // the manager is static, so get the existing manager via the static method
1493   AliAnalysisManager *mgr = AliAnalysisManager::GetAnalysisManager();
1494   if (!mgr) {
1495       printf("No analysis manager to connect to!\n");
1496       return NULL;
1497   }
1498
1499   // just to see if all went well, check if the input event handler has been connected
1500   if (!mgr->GetInputEventHandler()) {
1501       printf("This task requires an input event handler!\n");
1502       return NULL;
1503     }\end{lstlisting}
1504     \item [Setting up the flow event task]
1505 The manager and input data are present, so we can create the flow event task and do some basic configuration
1506 \begin{lstlisting}[language=C, numbers=left]
1507   // create instance of the class. because possible qa plots are added in a second ouptut slot,
1508   // the flow analysis task must know if you want to save qa plots at the time of class construction
1509   Bool_t doQA = kTRUE;
1510   // craete instance of the class
1511   AliAnalysisTaskFlowEvent* taskFE = new AliAnalysisTaskFlowEvent("FlowEventTask", "", doQA);
1512   // add the task to the manager
1513   mgr->AddTask(taskFE);
1514   // set the trigger selection
1515   taskFE->SelectCollisionCandidates(AliVEvent::kMB);\end{lstlisting}
1516 Note that in the last step you have set the trigger configuration\index{example!trigger selection}. Always make sure that you run on a trigger that makes sense for your analysis. A general remark is that the non-uniform acceptance correction methods that are implemented in the flow package, assume a flat \textbf{Q} vector distribution. Specific triggers (e.g. EMCal triggers) result in a \textbf{Q} vector bias which should \emph{not} be corrected as they invalidate that assumption\footnote{The actual event selection based on triggers is done in the \texttt{AliAnalysisTaskSE} class (to be specific, the trigger is checked in \texttt{AliAnalysisTaskSE::Exec()}) from which the \texttt{AliAnalysisTaskFlowEvent} is derived. The full set of available triggers can be found in the virtual event header \texttt{AliVEvent.h}. }.
1517
1518 In addition to the trigger selection, one might want to do some more event selection\index{example!event selection}. The flow package has a common event selection class, which we will add to your flow event
1519
1520 \begin{lstlisting}[language=C, numbers=left]
1521   // define the event cuts object
1522   AliFlowEventCuts* cutsEvent = new AliFlowEventCuts("EventCuts");
1523   // configure some event cuts, starting with centrality
1524   cutsEvent->SetCentralityPercentileRange(20., 30.);
1525   // method used for centrality determination
1526   cutsEvent->SetCentralityPercentileMethod(AliFlowEventCuts::kV0);
1527   // vertex-z cut
1528   cutsEvent->SetPrimaryVertexZrange(-10.,10.);
1529   // enable the qa plots
1530   cutsEvent->SetQA(doQA);
1531   // explicit multiplicity outlier cut
1532   cutsEvent->SetCutTPCmultiplicityOutliersAOD(kTRUE);
1533   cutsEvent->SetLHC10h(kTRUE);
1534
1535
1536   // and, last but not least, pass these cuts to your flow event task
1537   taskFE->SetCutsEvent(cutsEvent);\end{lstlisting}
1538
1539 \item [Track selection]\index{example!track selection}
1540 Now that the flow event task has been created and some basic configuration has been done, it's time to specify the POI and RP selection. This is done by defining sets of track selection criteria for both POI's and RP's: tracks in an event that pass the track selection criteria are used as POI or RP. The track selection is defined in \texttt{AliFlowTrackCuts} objects which are passed to the \texttt{AliAnalysisTaskFlowEvent} task which does the actual selection based on the passed criteria. So, let's create some track selection objects!
1541
1542 Starting with the RP's, for which we'll just use a uniform selection of charged tracks,
1543 \begin{lstlisting}[language=C, numbers=left]
1544   //create the track cuts object using a static function of AliFlowTrackCuts
1545   AliFlowTrackCuts* cutsRP = AliFlowTrackCuts::GetAODTrackCutsForFilterBit(1, "RP cuts");
1546   // specify the pt range
1547   cutsRP->SetPtRange(0.2, 5.);
1548   // specify eta range
1549   cutsRP->SetEtaRange(-0.8, 0.8);
1550   // specify track type
1551   cutsRP->SetParamType(AliFlowTrackCuts::kAODFilterBit);
1552   // enable saving qa histograms
1553   cutsRP->SetQA(kTRUE);\end{lstlisting}
1554
1555 The particles in this example of which we want to measure the differential $v_2$ (the POI's) are the charged pions. To measure the $v_2$ of charged pions, one must of course identify tracks are pions: for this we will use the \texttt{AliFlowTrackCuts} class. First, we do the basic setup, creating the cut object and setting some kinematic variables:
1556
1557 \begin{lstlisting}[language=C, numbers=left]
1558   //create the track cuts object using a static function of AliFlowTrackCuts
1559   AliFlowTrackCuts* cutsPOI = AliFlowTrackCuts::GetAODTrackCutsForFilterBit(1, "pion selection");
1560   // specify the pt range
1561   cutsPOI->SetPtRange(0.2, 5.);
1562   // specify eta range
1563   cutsPOI->SetEtaRange(-0.8, 0.8);
1564   // specify the track type
1565   cutsRP->SetParamType(AliFlowTrackCuts::kAODFilterBit);
1566   // enable saving qa histograms
1567   cutsPOI->SetQA(kTRUE);\end{lstlisting}
1568
1569 Once this is done, the particle identification routine is defined. In this example, the particle identification will be done using a Bayesian approach, combining the signals from the TPC and TOF detectors.
1570 \begin{lstlisting}[language=C, numbers=left]
1571   // which particle do we want to identify ?
1572   AliPID::EParticleType particleType=AliPID::kPion;
1573   // specify the pid method that we want to use
1574   AliFlowTrackCuts::PIDsource sourcePID=AliFlowTrackCuts::kTOFbayesian;
1575   // define the probability (between 0 and 1)
1576   Double_t probability = .9;
1577   // pass these variables to the track cut object
1578   cutsPOI->SetPID(particleType, sourcePID, probability);
1579   // the bayesian pid routine uses priors tuned to an average centrality
1580   cutsPOI->SetPriors(35.);\end{lstlisting}
1581
1582 Now that the track cuts for both POI's and RP's are defined, we can connect them to the flow event task,
1583 \begin{lstlisting}[language=C, numbers=left]
1584   // connect the RP's to the flow event task
1585   taskFE->SetCutsRP(cutsRP);
1586   // connect the POI's to the flow event task
1587   taskFE->SetCutsPOI(cutsPOI);\end{lstlisting}
1588
1589   \item [Connecting input and output]\index{InputContainer}\index{OutputContainer}\index{ExchangeContainer}\index{example!connecting containers}\index{connecting containers}
1590   At this point, the event and track cuts have been set and connected to the flow event task. The next step will be connecting the flow event task to the analysis manager (so that it can receive input events) and subsequently connecting the flow event task to flow analysis tasks, so that the flow events can be analyzed by our favorite flow analysis methods.
1591
1592 \begin{lstlisting}[language=C, numbers=left]
1593   // get the default name of the output file ("AnalysisResults.root")
1594   TString file = GetCommonFileName();
1595   // get the common input container from the analysis manager
1596   AliAnalysisDataContainer *cinput = mgr->GetCommonInputContainer();
1597    // create a data container for the output of the flow event task
1598    // the output of the task is the AliFlowEventSimle class which will
1599    // be passed to the flow analysis tasks. note that we use a kExchangeContainer here,
1600    // which exchanges data between classes of the analysis chain, but is not
1601    // written to the output file
1602   AliAnalysisDataContainer *coutputFE = mgr->CreateContainer(
1603       "FlowEventContainer",
1604       AliFlowEventSimple::Class(),
1605       AliAnalysisManager::kExchangeContainer);
1606   // connect the input data to the flow event task
1607   mgr->ConnectInput(taskFE,0,cinput);
1608   // and connect the output to the flow event task
1609   mgr->ConnectOutput(taskFE,1,coutputFE);
1610   // create an additional container for the QA output of the flow event task
1611   // the QA histograms will be stored in a sub-folder of the output file called 'QA'
1612   TString taskFEQAname = file;
1613   taskFEQAname += ":QA";
1614   AliAnalysisDataContainer* coutputFEQA = mgr->CreateContainer(
1615       "FlowEventContainerQA",
1616        TList::Class(),
1617        AliAnalysisManager::kOutputContainer,
1618        taskFEQAname.Data()
1619        );
1620   // and connect the qa output container to the flow event.
1621   // this container will be written to the output file
1622   mgr->ConnectOutput(taskFE,2,coutputFEQA);\end{lstlisting}
1623   \item [Flow analysis tasks]
1624 Now that the flow event task is connected to input data, the flow analysis tasks can be set up:
1625 \begin{lstlisting}[language=C, numbers=left]
1626   // declare necessary pointers
1627   AliAnalysisDataContainer *coutputQC[3];
1628   AliAnalysisTaskQCumulants *taskQC[3];
1629
1630   // the tasks will be created and added to the manager in a loop
1631   for(Int_t i = 0; i < 3; i++) {
1632       // create the flow analysis tasks
1633       taskQC[i] = new AliAnalysisTaskQCumulants(Form("TaskQCumulants_n=%i", i+2));
1634       // set thei triggers
1635       taskQC[i]->SelectCollisionCandidates(AliVEvent::kMB);
1636       // and set the correct harmonic n
1637       taskQC[i]->SetHarmonic(i+2);
1638
1639       // connect the task to the analysis manager
1640       mgr->AddTask(taskQC[i]);
1641
1642       // create and connect the output containers
1643       TString outputQC = file;
1644       // create a sub-folder in the output file for each flow analysis task's output
1645       outputQC += Form(":QC_output_for_n=%i", i+2);
1646       /// create the output containers
1647       coutputQC[i] = mgr->CreateContainer(
1648           outputQC.Data(),
1649           TList::Class(),
1650           AliAnalysisManager::kOutputContainer,
1651           outputQC);
1652       // connect the output of the flow event task to the flow analysis task
1653       mgr->ConnectInput(taskQC[i], 0, coutputFE);
1654       // and connect the output of the flow analysis task to the output container
1655       // which will be written to the output file
1656       mgr->ConnectOutput(taskQC[i], 1, coutputQC[i]);
1657   }\end{lstlisting}
1658       \item[Launching the analysis]
1659           With this, the \texttt{AddTask$\ast$.C} is concluded. The only thing that is left to do, is (from the \texttt{run.C} macro) see if all tasks and containers are properly connected and initialized and launch the analysis locally\index{example!launch analysis}:
1660 \begin{lstlisting}[language=C, numbers=left]
1661   // check if we can initialize the manager
1662   if(!mgr->InitAnalysis()) return;
1663   // print the status of the manager to screen
1664   mgr->PrintStatus();
1665   // print to screen how the analysis is progressing
1666   mgr->SetUseProgressBar(1, 25);
1667   // start the analysis locally, reading the events from the tchain
1668   mgr->StartAnalysis("local", chain);\end{lstlisting}
1669 \end{description}
1670
1671 \section{Flow analysis in ROOT: Using TTree's and TNTuples}
1672 As stated at the beginning of this chapter, every flow analysis in the flow package starts by filling the flow event. The flow event base class, \texttt{AliFlowEventSimple}\index{AliFlowEventSimple}, is a class in \texttt{libPWGflowBase} which has no dependencies other than some \texttt{ROOT} libraries; the same is true for the implementation of the flow analysis methods. This means that when you do not need the \texttt{AliROOT} interface for e.g. track and event selection, the flow package can be used by just invoking the \texttt{libPWGflowBase.so} library in \texttt{ROOT}\footnote{A makefile to compile the \texttt{libPWGflowBase.so} library from the command line will be added to \texttt{\$ALICE\_ROOT/PWGCF/FLOW/macros/ ...}}. The steps that are necessary to use the flow package in a bare \texttt{ROOT} environment are similar to those explained in chapter \ref{sec:onthefly}, with the exception that instead of generating events on-the-fly, we need to fill the flow event with information from the source of data which we want to analyze. In the next two subsections we will take a look at how to do a flow analysis on generic data in just \texttt{ROOT}. To start, pseudo-code of how to setup an analysis on a \texttt{TTree} will filled with particles be given. This example can be used as a starting point for running the flow package on any kind of input data. After this, we will work through an example of reading and analyzing \texttt{STAR} data. The last subsection of this chapter will point you to a fully working starting point for doing flow analysis on \texttt{TTree}'s, which firstly converts data to a \texttt{TTree} and after this reads the stored \texttt{TTree} from file and performs flow analysis in it in \texttt{ROOT}.
1673
1674 \subsection{A custom class derived from AliFlowEventSimple}
1675 In this example, an analysis on a \texttt{TTree} is performed by deriving a class from the flow event class \textt{AliFlowEventSimple}, \texttt{MyFlowEvent}, which can read a specific input format (in this case a branch\texttt{TTree!branch} of a \texttt{TTree}) and fills the flow event from this input. Of course you can design your task in a different way, but in this section we will stick to that example. Note that the following suggestions are all written in pseudo-code, so copy-pasting it will lead to nothing ...
1676
1677 Let's start with writing an an event loop. In this example the assumption is made that you have a \texttt{TTree} with events, called `myTree', which contains a branch holding a \texttt{TClonesArray}\index{TClonesArray} of `myParticle' objects, which contain kinematic information. The `myParticle' class could look a bit like
1678 \begin{lstlisting}[language=C, numbers=left]
1679 class myParticle : public TObject
1680 {
1681 public:
1682         myParticle(Float_t eta, Float_t phi, Float_t pt, Int_t charge) : fEta(eta), fPhi(phi), fpT(pt), fCharge(charge) {  }
1683     ~myParticle() {}
1684     virtual Double_t P()                const { return fp; }
1685     virtual Double_t Pt()               const { return fpT; }
1686     virtual Double_t Phi()              const { return fPhi; }
1687     virtual Double_t Eta()              const { return fEta; }
1688     virtual Int_t Charge()              const { return fCharge; }
1689 private:
1690     Float_t                             fEta;      // eta
1691     Float_t                             fPhi;      // phi
1692     Float_t                             fpT;       // pT
1693     Int_t                               fCharge;   // charge
1694     ClassDef(myParticle, 1); // example class
1695 };\end{lstlisting}
1696 Note that the members of this class ($p_t$, $\eta$, $\varphi$, charge) are all the information that an \texttt{AliFlowTrackSimple} needs to hold.
1697
1698 In the event loop, we'll retrieve the track array from the \texttt{TTree} and pass it to your derived flow event class. As we have seen in earlier examples, tracks in a flow event are classified as POI's or RP's via track cuts objects. We'll initialize these classes as well.
1699 \begin{lstlisting}[language=C, numbers=left]
1700   // first, define a set of simple cuts (the kinematic cuts)
1701   // which will define our poi and rp selection
1702   AliFlowTrackSimpleCuts *cutsRP = new AliFlowTrackSimpleCuts();
1703   AliFlowTrackSimpleCuts *cutsPOI = new AliFlowTrackSimpleCuts();
1704   cutsPOI->SetPtMin(0.2);
1705   cutsPOI->SetPtMax(2.0);
1706   // get number of entries from your ttree
1707   Int_t nEvents = myTree->GetEntries();
1708   // loop over all entries
1709   for(Int_t i = 0; i < nEvents; i++) {
1710       // get the track array from the ttree
1711       TClonesArray* particleArray = 0x0;
1712       // get the branch address by name
1713       myTree->SetBranchAddress("myParticles", &particleArray);
1714       // switch to the tree's i-th entry
1715       myTree->GetEntry(i);
1716       // now we do some magic: with a dedicated inherited class
1717       // we construct a flow event from your ttree
1718       AliFlowEventSimple* flowEvent = new MyFlowEvent(particleArray, cutsPOI, cutsRP);
1719       // and from here we know how to proceed: connect the flow event
1720       // to the flow analysis classes, and do the analysis
1721       qc->Make(flowEvent);
1722       // memory management
1723       delete flowEvent;
1724       }
1725   qc->Finish();
1726   }\end{lstlisting}
1727 So what is `the magic'? This is filling your flow event from the \texttt{TTree}. As we have seen in the previous sections, filling means that need to select our tracks, tag them as POI's and RP's, and add them to the flow event. Our derived class, AliFlowEventSimple::MyFlowEvent will take care of this. A possible constructor for this class, which performs the `magic', could look like the following piece of pseudo-code:
1728
1729 \begin{lstlisting}[language=C, numbers=left]
1730 // class constructor of an example class which reads a ttree,
1731 // selects poi's and rp's and fills a flow event.
1732 // this class is derived from the flow event simple class
1733 // and therefore can be passed to the flow analysis methods
1734
1735 // we'll feed to class with your custom particles,
1736 // so this include will be necessary
1737 #include myParticle.h
1738
1739 // this is the class constructor
1740 MyFlowEvent::MyFlowEvent(
1741     // start with the input tracks
1742     TClonesArray* particleArray,
1743     // and pass the poi and rp cuts
1744     const AliStarTrackCuts* cutsRP,
1745     const AliStarTrackCuts* cutsPOI) :
1746   // derived from AliFlowEventSimple, initialized to hold a certain number of
1747   // tracks
1748   AliFlowEventSimple(particleArray->GetEntries())
1749 {
1750   // the next step will be filling the flow event
1751   // with POI's and RP's according to our
1752   // POI and RP cuts
1753
1754   for (Int_t i = 0; i < particleArray->GetEntries(); i++)
1755   {
1756     // get a particle from the particle array
1757     const myParticle* part = static_cast<myParticle*>particleArray->At(i);
1758     if (!myParticle) continue;
1759
1760     // build flow track simple (for the flow event)
1761     AliFlowTrackSimple* flowtrack = new AliFlowTrackSimple();
1762     // copy the kinematic information from the star track
1763     flowtrack->SetPhi(part->Phi());
1764     flowtrack->SetEta(part->Eta());
1765     flowtrack->SetPt(part->Pt());
1766     flowtrack->SetCharge(part->Charge());
1767     // see if the track is a reference track
1768     if (cutsRP)
1769     {
1770       Bool_t pass = rpCuts->PassesCuts(flowtrack);
1771       flowtrack->TagRP(pass); //tag RPs
1772       if (pass) IncrementNumberOfPOIs(0);
1773     }
1774     // see if the track is a particle of interest
1775     if (poiCuts)
1776     {
1777       flowtrack->TagPOI(poiCuts->PassesCuts(flowtrack));
1778     }
1779     // add the track to the flow event
1780     AddTrack(flowtrack);
1781   }
1782 }\end{lstlisting}
1783 That's it! Following (variations on) these steps, you'll be able to connect any type of input data to the flow package. Note that compiling the scripts in which you define these steps will be much faster than running your code in the interpreter mode of \texttt{ROOT}. The next subsection will show these steps in action in the for of a flow analysis on \texttt{STAR} data.
1784
1785 \subsection{A realistic example: flow package analysis on STAR data}
1786 The following section will show you how to use non-\texttt{ALICE} data in a realistic example, using events from the \texttt{STAR} experiment at \texttt{RHIC}. \texttt{STAR} data is stored in a \texttt{TTree}. To use the flow package for flow analysis on this data, the information from the \texttt{TTree} needs to be converted into an \texttt{AliFlowEventSimple}. In the specific case of the \texttt{STAR} data, things are a bit more complicated than in the pseudo-code example given in the previous section. Event- and track-level cuts still have to be applied to the \texttt{STAR} data, therefore a \texttt{reader} class is written which reads data from file, applies track and event cuts and converts the \texttt{STAR} data to `star flow events'. This reading is left to a dedicated class, \texttt{AliStarEventReader}\index{AliStarEventReader}, which reads a \texttt{TTree} and for each event creates an \texttt{AliStarEvent}\index{AliStarEvent}. The \texttt{AliStarEvent} is a derived class which inherits from \texttt{AliFlowEventSimple} (similar to the \texttt{MyFlowEvent} class from the example in the previous subsection). To understand this process a bit better, we'll take a look at a few code snippets from the relevant classes and macros which are currently present in \texttt{AliROOT}. A macro which reads \texttt{STAR} data and performs a flow analysis can be found at \texttt{\$ALICE\_ROOT/PWGCF/FLOW/macros/runStarFlowAnalysis.C}.
1787 \index{runStarFlowAnalysis.C}
1788
1789 \begin{lstlisting}[language=C, numbers=left]
1790   // connect the class which can read and understand your ttree to
1791   // the input data
1792   AliStarEventReader starReader(inputDataFiles) ;
1793   // loop as long as there are events
1794   while ( starReader.GetNextEvent() )                                // Get next event
1795   {
1796     // read a star event from the ttree
1797     AliStarEvent* starEvent = starReader.GetEvent();
1798     // see if the event meets event cuts (of course these are
1799     // specific for STAR analysis, whether or not your ttree would
1800     // need such a cut is up to you
1801     if ( !starEventCuts->PassesCuts(starEvent) ) continue;
1802
1803     // this is where flow package comes into play.
1804     // at this moment, a star event has been read from a ttree,
1805     // and is stored as a 'AliStarEvent'
1806     // in the next step, we'll create an AliFlowEventSimple from
1807     // this star event using the AliFlowEventStar class, which is derived
1808     // from the AliFlowEventSimple class.
1809     // as input, the AliFlowEventStar class receives the star event,
1810     // and a set of poi and rp cuts
1811     AliFlowEventSimple* flowEvent = new AliFlowEventStar(starEvent,rpCuts,poiCuts);  // make a flow event from a star event (aka "the magic")
1812     // for the scalar product method, we need to tag subevents
1813     flowEvent->TagSubeventsInEta(minA, maxA, minB, maxB );
1814
1815     qc->Make(flowEvent);
1816     delete flowEvent;
1817   }\end{lstlisting}
1818 The most important piece of the code snippet printed here is the routine where the \texttt{AliFlowEventSimple} is formed from the \texttt{AliStarEvent}. What happens in the  \texttt{AliFlowEventStar} class is the following:
1819
1820 \begin{lstlisting}[language=C, numbers=left]
1821 // class constructor
1822 AliFlowEventStar::AliFlowEventStar( const AliStarEvent* starevent,
1823                                     const AliStarTrackCuts* rpCuts,
1824                                     const AliStarTrackCuts* poiCuts ):
1825   // derived from AliFlowEventSimple, initialized to hold a certain number of
1826   // tracks
1827   AliFlowEventSimple(starevent->GetNumberOfTracks())
1828 {
1829   //construct the flow event from the star event information
1830   SetReferenceMultiplicity(starevent->GetRefMult());
1831   // track loop
1832   for (Int_t i=0; i<starevent->GetNumberOfTracks(); i++)
1833   {
1834     // get star track from the star event
1835     const AliStarTrack* startrack = starevent->GetTrack(i);
1836     if (!startrack) continue;
1837     // build flow track simple (for the flow event)
1838     AliFlowTrackSimple* flowtrack = new AliFlowTrackSimple();
1839     // copy the kinematic information from the star track
1840     flowtrack->SetPhi(startrack->GetPhi());
1841     flowtrack->SetEta(startrack->GetEta());
1842     flowtrack->SetPt(startrack->GetPt());
1843     flowtrack->SetCharge(startrack->GetCharge());
1844     // see if the track is a reference track
1845     if (rpCuts)
1846     {
1847       Bool_t pass = rpCuts->PassesCuts(startrack);
1848       flowtrack->TagRP(pass); //tag RPs
1849       if (pass) IncrementNumberOfPOIs(0);
1850     }
1851     // see if the track is a particle of interest
1852     if (poiCuts)
1853     {
1854       flowtrack->TagPOI(poiCuts->PassesCuts(startrack)); //tag POIs
1855     }
1856     // add the track to the flow event
1857     AddTrack(flowtrack);
1858   }
1859 }\end{lstlisting}
1860
1861 \subsection{Getting started yourself}
1862 To get started with flow analysis on \texttt{TTree's} yourself, a set of example macros and classes is provided at \texttt{\$ALICE\_ROOT/PWGCF/FLOW/Documentation/examples/manual/ttree}. These classes and macros will guide you through creating a \texttt{TTree} with data from \texttt{ALICE} events in the analysis framework, and performing a flow analysis on them using only \texttt{ROOT}. The example is set up as follows:
1863 \begin{itemize}
1864 \item There are two macros (in macros folder)
1865 \begin{itemize}
1866 \item run: runs (in \texttt{AliROOT}) and fills a \text{TTree} with kinematic info from \texttt{AliVEvent}
1867 \item read: reads (in just \texttt{ROOT}) the \text{TTree} info and performs a flow analysis with the flow package
1868 \end{itemize}
1869 \item There are two analysis classes
1870 \begin{itemize}
1871 \item  \texttt{AliAnalysisTaskTTreeFilter}\index{AliAnalysisTaskTTreeFilter}, an analysis task for AliROOT which converts input events to a \texttt{TTree}
1872 \item \texttt{AliFlowEventSimpleFromTTree}\index{AliFlowEventSimpleFromTTree} a task for ROOT, fills flow events with \texttt{TTree} input
1873 \end{itemize}
1874 \item and lastly two helper classes which should serve as a starting point
1875 \begin{itemize}
1876 \item \texttt{AliFlowTTreeEvent}\index{AliFlowTTreeEvent}, a simple event class
1877 \item \texttt{AliFlowTTreeTrack}\index{AliFlowTTreeTrack}, a simple track class
1878 \end{itemize}
1879 \end{itemize}
1880 As these are helper classes designed to get the user started, they are not compiled by default. The run and read macro will them compile on-the-fly.
1881
1882 \chapter{Methods}\index{flow analysis methods}\index{methods}
1883 \label{sec:methods}
1884 The flow package aims at providing the user with most of the known flow analysis methods. Detailed theoretical overview of the methods can be found in the following papers, which are included in the folder \texttt{\$ALICE\_ROOT/PWGCF/FLOW/Documentation/otherdocs/}
1885 \begin{itemize}
1886         \item Scalar Product Method \\ \hspace*{1cm} \texttt{EventPlaneMethod/FlowMethodsPV.pdf}
1887         \item Generating Function Cumulants \\ \hspace*{1cm} \texttt{GFCumulants/Borghini\_GFCumulants\_PracticalGuide.pdf}
1888         \item Q-vector Cumulant method \\ \hspace*{1cm} \texttt{QCumulants/QCpaperdraft.pdf}
1889         \item Lee-Yang Zero Method \\ \hspace*{1cm} \texttt{LeeYangZeroes/Borghini\_LYZ\_PracticalGuide.pdf}
1890         \item Lee-Yang Zero Method \\ \hspace*{1cm} \texttt{LeeYangZeroesEP/LYZ\_RP.pdf}
1891 \end{itemize}
1892 The structure of this  chapter is as follows: of each of the available methods a short description is given in the \texttt{theory} subsection (for more detailed information, see the papers listed above) followed by details which are specific to the implementation in the subsection \texttt{implementation}. Caveats, possible issues, etc, are listed in the \texttt{caveats} subsections.
1893 %-----------------------------------------------------------------------
1894
1895  \section{AliFlowAnalysisWithMCEventPlane}\index{AliFlowAnalysisWithMCEventPlane}\index{methods!AliFlowAnalysisWithLYZEventPlane}
1896 \label{sec:MC}
1897 \subsection{Theory}
1898 From the \texttt{.cxx} of the task:
1899 \begin{lstlisting}[language=C, numbers=left]
1900 // Description: Maker to analyze Flow from the generated MC reaction plane.
1901 //              This class is used to get the real value of the flow
1902 //              to compare the other methods to when analysing simulated events.\end{lstlisting}
1903 This method can be used to check what $v_n$ was generated in an on-the-fly flow study or using the \texttt{AliAnalysisTaskFlowEvent} with afterburner.
1904 \subsection{Implementation}
1905 There is no specific information on the implementation here, for details the reader is referred to the source code.
1906
1907 \section{AliFlowAnalysisWithQCumulants}\label{sec:QC}\index{AliFlowAnalysisWithQCumulants}\index{methods!AliFlowAnalysisWithQCumulants}
1908 \subsection{Implementation}
1909 \emph{A how-to of the QC method in the flow-package is written by the author of the analysis software and is available on the FLOW-PAG twiki page} (\href{https://twiki.cern.ch/twiki/bin/view/ALICE/FlowPackageHowto}{https://twiki.cern.ch/twiki/bin/view/ALICE/FlowPackageHowto}). \emph{This section is copied from the twiki page (and may therefore overlap with other parts of this manual).}
1910
1911  To get the first feeling how the FLOW package and QC output are organized, perhaps you can just trivially execute one 'on-the-fly' example
1912
1913  Essentially, you have to do two things:
1914         \begin{lstlisting}[language=C, numbers=left]
1915 cp $ALICE_ROOT/PWGCF/FLOW/macros/runFlowAnalysisOnTheFly.C .
1916 aliroot runFlowAnalysisOnTheFly.C \end{lstlisting}
1917
1918  In the analysis on-the-fly particles are sampled from hardwired Fourier-like p.d.f, so input vn harmonics are completely under control. Please have a look at the steering macro runFlowAnalysisOnTheFly.C and corresponding class AliFlowEventSimpleMakerOnTheFly.cxx in the FLOW package, which are easily written (no fancy C++ features in my code!), and well documented.
1919
1920  If you have landed successfully, you will get an output AnalysisResults.root, where the results from each method are structured in directories.
1921
1922  To make a size of the file lighter (which matters a lot during merging!), you may want not to use all the methods. You can make your selection of the methods via:
1923         \begin{lstlisting}[language=C, numbers=left]
1924 Bool_t MCEP = kTRUE; // Monte Carlo Event Plane
1925 Bool_t SP = kTRUE; // Scalar Product (a.k.a 'flow analysis with eta gaps')
1926 Bool_t GFC = kTRUE; // Generating Function Cumulants
1927 Bool_t QC = kTRUE; // Q-cumulants
1928 Bool_t FQD = kTRUE; // Fitted q-distribution
1929 Bool_t LYZ1SUM = kTRUE; // Lee-Yang Zero (sum generating function), first pass over the data
1930 Bool_t LYZ1PROD = kTRUE; // Lee-Yang Zero (product generating function), first pass over the data
1931 Bool_t LYZ2SUM = kFALSE; // Lee-Yang Zero (sum generating function), second pass over the data
1932 Bool_t LYZ2PROD = kFALSE; // Lee-Yang Zero (product generating function), second pass over the data
1933 Bool_t LYZEP = kFALSE; // Lee-Yang Zero Event Plane
1934 Bool_t MH = kFALSE; // Mixed Harmonics (used for strong parity violation studies)
1935 Bool_t NL = kFALSE; // Nested Loops (neeed for debugging, only for developers)  \end{lstlisting}
1936  Next important remark, if you want to browse through AnalysisResults.root, make sure that in AliROOT prompt you have loaded the FLOW library:
1937         \begin{lstlisting}[language=C, numbers=left]
1938 root [0] gSystem->Load("libPWGflowBase");       \end{lstlisting}
1939  In the AnalysisResults.root, the QC output is stored in "outputQCanalysis". Just browse there, browse in "cobjQC", and you will see the directory structure.
1940  "Integrated Flow" $\Rightarrow$ contains all results needed for reference flow. Browse in, and explore the directory (in fact, TList) "Results". The names of the histos should be self-explanatory;
1941  "Differential Flow" $\Rightarrow$ browse further into "Results", and you will find a bunch of things that you can explore. For instance, in the directory "Differential Q-cumulants (POI,p$_{T}$)" you will find histos holding differential QC\{2\} vs pt, QC\{4\} vs p$_{T}$, etc. On the other hand, the flow estimates themselves, namely differential vn\{2\} vs pt, vn\{4\} vs pt you can fetch from TList "Differential Flow (POI,p$_{T}$)"
1942  I hope that the names for all other things you might need are self-explanatory.
1943  You configure QC method in the steering macro via setters:
1944         \begin{lstlisting}[language=C, numbers=left]
1945 qc->SetHarmonic(2);
1946 qc->SetCalculateDiffFlow(kTRUE);
1947 qc->SetCalculate2DDiffFlow(kFALSE); // vs (pt,eta)
1948 qc->SetApplyCorrectionForNUA(kFALSE);
1949 qc->SetFillMultipleControlHistograms(kFALSE);
1950 qc->SetMultiplicityWeight("combinations"); // default (other supported options are "unit" and "multiplicity")
1951 qc->SetCalculateCumulantsVsM(kFALSE);
1952 qc->SetCalculateAllCorrelationsVsM(kFALSE); // calculate all correlations in mixed harmonics "vs M"
1953 qc->SetnBinsMult(10000);
1954 qc->SetMinMult(0);
1955 qc->SetMaxMult(10000);
1956 qc->SetBookOnlyBasicCCH(kFALSE); // book only basic common control histograms
1957 qc->SetCalculateDiffFlowVsEta(kTRUE); // if you set kFALSE only differential flow vs pt is calculated
1958 qc->SetCalculateMixedHarmonics(kFALSE); // calculate all multi-partice mixed-harmonics correlators      \end{lstlisting}
1959  You can make QC output lighter by setting
1960         \begin{lstlisting}[language=C, numbers=left]
1961 qc->SetBookOnlyBasicCCH(kTRUE); \end{lstlisting}
1962 (to book only basic control histograms, and disabling lot of 2D beasts), and
1963         \begin{lstlisting}[language=C, numbers=left]
1964 qc->SetCalculateDiffFlowVsEta(kFALSE);  \end{lstlisting}
1965 (if not interested in differential flow vs eta $\Rightarrow$ this will make the final output smaller)
1966  In the "cobjQC" you might also consider "AliFlowCommonHistQC" to be useful thing, which contains a lot of trivial but still important control histograms (eg multiplicity distribution of RPs, POIs, etc).
1967  I think this is the best and fastest way for you to get familiar with the FLOW package => once you send the QC code over the real data, you get the output organized in the very same way. I will send you shortly an example set of macros which get be used for the analysis on Grid over the real data.
1968  Differential QC\{2\} and QC\{4\} implementation is generic. You can tag as RP and POI whatever you want, and it will give you results automatically decoupled from any autocorrelation effects. For this reason, it is important that if you have certain particles which is classified both as RP and POI, to be explicitly tagged also as RPs and POI once you are building the "flow event".
1969  The basic feature in the FLOW package is that from whichever input you start, we have to build the same intermediate step called "flow event", with which than we feed all methods (SP, QC, etc) in the very same way.
1970  To see what "flow event" does, and what does it need as an input, you may want to consult task AliAnalysisTaskFlowEvent.cxx and classes needed there-in.
1971
1972 \section{AliFlowAnalysisWithScalarProduct}\index{AliFlowAnalysisWithScalarProduct}\index{methods!AliFlowAnalysisWithScalarProduct}
1973 \label{sec:SP}\label{sec:scalar_product}
1974 \subsection{Theory}
1975 \begin{lstlisting}[language=C, numbers=left]
1976 /////////////////////////////////////////////////////////////////////////////
1977 // Description: Maker to analyze Flow from the Event Plane method.
1978 //              Adaptation based on Scalar Product
1979 // authors: Naomi van del Kolk
1980 //          Ante Bilandzic
1981 // mods:    Carlos Perez
1982 /////////////////////////////////////////////////////////////////////////////
1983 \end{lstlisting}
1984 \subsubsection{The scalar product method}
1985 The scalar product method estimates $v_n$ directly from \textbf{Q} vectors:
1986 \begin{equation}\label{sp_func}
1987 v_n = \frac{\langle u \cdotp Q \rangle }{\sqrt{\langle Q_A \cdotp Q_B \rangle}}
1988 \end{equation}
1989 The denominator of equation \ref{sp_func} consists of two sub-event \textbf{Q} vectors, \textbf{Q}$_{A}$ and \textbf{Q}$_{B}$. Sub-events are built from RP's. These sub-event vectors are in the flow package defined as coming from different $\eta$ ranges.
1990
1991 To setup the different $\eta$ ranges, one can use the \texttt{AliAnalysisTaskFlowEvent} directly by calling
1992 \begin{lstlisting}[language=C, numbers=left]
1993 AliAnalysisTaskFlowEvent:: void SetSubeventEtaRange(Double_t minA, Double_t maxA, Double_t minB, Double_t maxB)
1994     {this->fMinA = minA; this->fMaxA = maxA; this->fMinB = minB; this->fMaxB = maxB; }\end{lstlisting}
1995 Sub-events can be re-tagged using the filter task, which will be described in section \ref{sec:exotic}.
1996 Internally, the tagging is performed by the function
1997 \begin{lstlisting}[language=C, numbers=left]
1998 AliFlowEventSimple::TagSubEventsInEta(Double_t etaMinA, Double_t etaMaxA, Double_t etaMinB, Double_t etaMaxB);\end{lstlisting}
1999 which should be called when you fill your flow events `by-hand' and want to tag sub-events.
2000
2001
2002 The numerator of equation \ref{sp_func} is the correlator of the POI \textbf{Q} vector ($u$) and a sub-event \textbf{Q} vector which is generally referred to as the reference detector. In the flow package, this sub-event \textbf{Q} vector is called `total q-vector'. The user of the task needs to specify what part of the RP selection (that is, which sub-events) are used as total \textbf{Q} vector. Passing this information to the scalar product task is done in the following way
2003 \begin{lstlisting}[language=C, numbers=left]
2004 AliAnalysisTaskScalarProduct:: void SetTotalQvector(const char *tqv) {*this->fTotalQvector = tqv;}; \end{lstlisting}
2005 where the following options are available
2006 \begin{lstlisting}[language=C, numbers=left]
2007   TString   *fTotalQvector;      // total Q-vector is: "QaQb" (means Qa+Qb), "Qa"  or "Qb" \end{lstlisting}
2008 In general, one has to be a bit careful with setting up sub-events. Make sure that the combination of reference detector and sub-events is mathematically sound! An example of how to deal with complex setups is given in the VZERO scalar product subsection (\ref{sec:vzerp_sp}).
2009
2010 \subsubsection{VZERO scalar product}\label{sec:vzerp_sp}
2011
2012 The VZEROA and VZEROC detectors have different $\eta$ coverage w.r.t the TPC, so to evaluate $v_2$ from VZERO-SP, do
2013 \begin{equation}
2014 v_n = \sqrt{\frac{\langle u_i \cdotp Q_A \rangle }{\sqrt{\langle Q_A \cdotp Q_B \rangle}} \cdotp \frac{\langle u_j \cdotp Q_B \rangle }{\sqrt{\langle Q_A \cdotp Q_B \rangle}}}
2015 \end{equation}
2016 \begin{itemize}
2017 \item $Q_A$ and $Q_B$ are the VZEROC and VZEROA RP's
2018 \end{itemize}
2019 What is up for debate is the following: how do we defined the POI's?
2020 \begin{itemize}
2021 \item Take $u$ = full TPC = $u_j$ = $u_i$, or do $u_j$ = $\eta < 0$, $u_i$ = $\eta > 0$ ?
2022 \end{itemize}
2023 In the elliptic flow analysis of identified particles, majority vote has yielded the following:
2024 \begin{itemize}
2025 \item $u$ = full TPC = $u_j$ = $u_i$
2026 \end{itemize}
2027 so that in the end the published points were obtained using
2028 \begin{equation}
2029 v_n = \sqrt{\frac{\langle u \cdotp Q_A \rangle }{\sqrt{\langle Q_A \cdotp Q_B \rangle}} \cdotp \frac{\langle u \cdotp Q_B \rangle }{\sqrt{\langle Q_A \cdotp Q_B \rangle}}}
2030 \end{equation}
2031 Note that this requires running \emph{two} scalar product tasks in the flow package (one for each reference detector) the output $v_2$ of which was in turn multiplied point-by-point in $p_t$.
2032
2033 \subsubsection{Extension to Event Plane method}
2034 By normalizing the \textbf{Q} vectors, the scalar product method is essentially reduced to the `classic' event plane method. Normalization of the \textbf{Q} vectors can be set using
2035 \begin{lstlisting}[language=C, numbers=left]
2036 AliAnalysisTaskScalarProduct::SetBehaveAsEP()\end{lstlisting}
2037
2038 \section{AliFlowAnalysisWithCumulants}\index{AliFlowAnalysisWithCumulants}\index{methods!AliFlowAnalysisWithCumulants}
2039 \subsection{Theory}
2040 \begin{lstlisting}[language=C, numbers=left]
2041 /*************************************************
2042  * Flow analysis with cumulants. In this class   *
2043  * cumulants are calculated by making use of the *
2044  * formalism of generating functions proposed by *
2045  * Ollitrault et al.                             *
2046  *                                               *
2047  *      Author: Ante Bilandzic                   *
2048  *************************************************/ \end{lstlisting}
2049
2050 \subsection{Implementation}
2051 There is no specific information on the implementation here, for details the reader is referred to the source code. Do not confuse this method with the often used Q-cumulant method!
2052 \section{AliFlowAnalysisWithMixedHarmonics}\index{AliFlowAnalysisWithMixedHarmonics}\index{methods!AliFlowAnalysisWithMixedHarmonics}
2053 \subsection{Theory}
2054 There is no specific information on the theory here, for details the reader is referred to the source code.
2055 \subsection{Implementation}
2056 There is no specific information on the implementation here, for details the reader is referred to the source code.
2057
2058 \section{AliFlowAnalysisWithFittingQDistribution}\index{AliFlowAnalysisWithFittingQDistribution}\index{methods!AliFlowAnalysisWithFittingQDistribution}
2059 \subsection{Theory}
2060 \begin{lstlisting}[language=C, numbers=left]
2061 /********************************
2062  * estimating reference flow by *
2063  *   fitting q-distribution     *
2064  *                              *
2065  * author: Ante Bilandzic       *
2066  *                              *
2067  *  based on the macro written  *
2068  *     by Sergei Voloshin       *
2069  *******************************/  \end{lstlisting}
2070 \subsection{Implementation}
2071 There is no specific information on the implementation here, for details the reader is referred to the source code.
2072
2073
2074 \section{AliFlowAnalysisWithMultiparticleCorrelations}\index{AliFlowAnalysisWithMultiparticleCorrelations}\index{methods!AliFlowAnalysisWithMultiparticleCorrelations}
2075 \subsection{Theory}
2076 \begin{lstlisting}[language=C, numbers=left]
2077 /**********************************************************
2078  * In this class azimuthal correlators in mixed harmonics *
2079  * are implemented in terms of Q-vectors. This approach   *
2080  * doesn't require evaluation of nested loops. This class *
2081  * can be used to:                                        *
2082  *                                                        *
2083  *  a) Extract subdominant harmonics (like v1 and v4);    *
2084  *  b) Study flow of two-particle resonances;             *
2085  *  c) Study strong parity violation.                     *
2086  *                                                        *
2087  * Author: Ante Bilandzic                                 *
2088  *********************************************************/ \end{lstlisting}
2089 \subsection{Implementation}
2090 There is no specific information on the implementation here, for details the reader is referred to the source code.
2091
2092 \section{AliFlowAnalysisWithLeeYangZeros}\index{AliFlowAnalysisWithLeeYangZeros}\index{methods!AliFlowAnalysisWithLeeYangZeros}
2093 \subsection{Theory}
2094 \begin{lstlisting}[language=C, numbers=left]
2095 ////////////////////////////////////////////////////////////////////
2096 // Description: Maker to analyze Flow by the LeeYangZeros method
2097 //              One needs to do two runs over the data;
2098 //              First to calculate the integrated flow
2099 //              and in the second to calculate the differential flow
2100 // Author: Naomi van der Kolk
2101 //////////////////////////////////////////////////////////////////// \end{lstlisting}
2102 \subsection{Implementation}
2103 There is no specific information on the implementation here, for details the reader is referred to the source code.
2104 This method requires two passes over the data. You can take a look at the on-the-fly analysis example macro to see how these two steps can be set up:
2105 \begin{lstlisting}
2106 Bool_t LYZ1SUM = kTRUE; // Lee-Yang Zero (sum generating function), first pass over the data
2107 Bool_t LYZ1PROD = kTRUE; // Lee-Yang Zero (product generating function), first pass over the data
2108 Bool_t LYZ2SUM = kFALSE; // Lee-Yang Zero (sum generating function), second pass over the data
2109 Bool_t LYZ2PROD = kFALSE; // Lee-Yang Zero (product generating function), second pass over the data\end{lstlisting}
2110 \section{AliFlowAnalysisWithLYZEventPlane}\index{AliFlowAnalysisWithLYZEventPlane}\index{methods!AliFlowAnalysisWithLYZEventPlane}
2111 \subsection{Theory}
2112 \begin{lstlisting}[language=C, numbers=left]
2113 // AliFlowAnalysisWithLYZEventPlane:
2114 // Class to do flow analysis with the event plane
2115 // from the LYZ method
2116 \end{lstlisting}
2117 \subsection{Implementation}
2118 There is no specific information on the implementation here, for details the reader is referred to the source code.
2119
2120 \section{Developing your own task}
2121 Of course this list of flow analysis methods could be extended. Adding a new flow analysis method means developing two classes: a `base' class where the method is implemented and a `tasks' class to interface with the analysis manager. As a starting point, `templates' have been developed, which are just empty base and task classes in the flow package. You can find these at
2122 \begin{description}
2123 \item[base] \texttt{\$ALICE\_ROOT/PWG/FLOW/Base/AliFlowAnalysisTemplate.cxx (h)}
2124 \item[tasks] \texttt{\$ALICE\_ROOT/PWG/FLOW/Tasks/AliAnalysisTaskTemplate.cxx (h)}
2125 \end{description}
2126
2127
2128 \chapter{More exotic uses}\label{sec:exotic}
2129 This chapter deals with more `exotic' uses of the flow package.
2130 \section{Flow analysis in the LEGO framework: re-tagging your POI and RP selections}\index{LEGO framework}\index{AliAnalysisTaskFilterFE}
2131 To save resources, it is beneficial to construct analysis trains in which just one flow event is created which is passed to multiple analysis tasks. This can be inconvenient when the different analysis tasks require different POI and RP selections\footnote{A notable example of this is doing an invariant mass analysis, which will briefly be touched in the next section.}. To overcome this, a filter task, \texttt{AliAnalysisTaskFilterFE}, has been developed, which can run between the \texttt{AliAnalysisTaskFlowEvent} and a specific flow analysis task, and can re-tag POI's and RP's. The re-tagging is performed by looping over all tracks in an event and checking whether or not these tracks pass a selection of simple cuts. The filter task can only re-tag existing tracks in the flow event, it cannot add new tracks to the flow event. To illustrate the functionality of the filtertask, we'll take the example of section \ref{sec:example} but perform the analysis using different $\vert \eta \vert$ windows for RP's.
2132
2133 The first step towards filtering is setting up the filtering criteria. These are defined using the \texttt{AliFlowTrackSimpleCuts}\index{AliFlowTrackSimpleCuts} object:
2134 \begin{lstlisting}[language=C, numbers=left]
2135 // create the simple cuts object
2136 AliFlowTrackSimpleCuts* filterRP = new AliFlowTrackSimpleCuts("filterRP");
2137 // specify a rapidity interval
2138 filterRP->SetEtaMin(-0.4);
2139 filterRP->SetEtaMax(0.4);\end{lstlisting}
2140
2141 All available filtering options in \texttt{AliFlowTrackSimpleCuts} are:
2142 \begin{lstlisting}[language=C, numbers=left]
2143   //setters
2144   void SetPtMax(Double_t max)   {this->fPtMax = max; fCutPt=kTRUE; }
2145   void SetPtMin(Double_t min)   {this->fPtMin = min; fCutPt=kTRUE;  }
2146   void SetEtaMax(Double_t max)  {this->fEtaMax = max; fCutEta=kTRUE; }
2147   void SetEtaMin(Double_t min)  {this->fEtaMin = min; fCutEta=kTRUE; }
2148   void SetEtaGap(Double_t min, Double_t max)
2149         {fEtaGapMin = min, fEtaGapMax = max, fCutEtaGap = kTRUE; }
2150   void SetPhiMax(Double_t max)  {this->fPhiMax = max; fCutPhi=kTRUE; }
2151   void SetPhiMin(Double_t min)  {this->fPhiMin = min; fCutPhi=kTRUE; }
2152   void SetPID(Int_t pid)        {this->fPID = pid; fCutPID=kTRUE; }
2153   void SetCharge(Int_t c)       {this->fCharge = c; fCutCharge=kTRUE; }
2154   void SetMassMax(Double_t max) {this->fMassMax = max; fCutMass=kTRUE; }
2155   void SetMassMin(Double_t min) {this->fMassMin = min; fCutMass=kTRUE; }\end{lstlisting}
2156 All cuts are disabled by default.
2157
2158 The second step is constructing the filter class object itself:
2159 \begin{lstlisting}[language=C, numbers=left]
2160 // create the filter task object. note that the desired cuts have to be passed
2161 // in the constructor, the 0x0 that is passed means that POI's will not be filtered
2162 AliAnalysisTaskFilterFE* filterTask = AliAnalysisTaskFilterFE("filter task", filterRP, 0x0);\end{lstlisting}
2163 Sub-events can also be re-defined using the filter task. To do so, call
2164 \begin{lstlisting}[language=C, numbers=left]
2165 AliAnalysisTaskFilterFE::SetSubeventEtaRange(Double_t minA, Double_t maxA, Double_t minB, Double_t maxB)
2166     {this->fMinA = minA; this->fMaxA = maxA; this->fMinB = minB; this->fMaxB = maxB; }\end{lstlisting}
2167 If yo use the filter task for a flow analysis method which uses sub-events, make sure that you set the correct $\eta$ ranges! Otherwise, the default values will be used, which may (or may not) be correct for your analysis.
2168
2169 The \texttt{UserExec()} of the filter task is as follows:
2170 \begin{lstlisting}[language=C, numbers=left]
2171 void AliAnalysisTaskFilterFE::UserExec(Option_t *)
2172 {
2173   // Main loop
2174   fFlowEvent = dynamic_cast<AliFlowEventSimple*>(GetInputData(0)); // from TaskSE
2175   if (!fFlowEvent) return;
2176   if(fCutsRFP) fFlowEvent->TagRP(fCutsRFP);
2177   if(fCutsPOI) fFlowEvent->TagPOI(fCutsPOI);
2178   fFlowEvent->TagSubeventsInEta(fMinA,fMaxA,fMinB,fMaxB);
2179   PostData(1,fFlowEvent);
2180 }\end{lstlisting}
2181
2182 Now that the filter task has been configured, it needs to be added to the analysis chain. As stated, the task needs to be put \emph{in between} the flow event task and the flow analysis method.
2183 \begin{lstlisting}[numbers=left, language=C]
2184 // get the analysis manager
2185 AliAnalysisManager *mgr = AliAnalysisManager::GetAnalysisManager();
2186 // add the fitler task to the manager (should be done before the
2187 // analysis task is added!)
2188 mgr->AddTask(filterTask);
2189 // create a temporary container which the filter task will pass to the
2190 // analysis task
2191 AliAnalysisDataContainer *coutputFilter = mgr->CreateContainer(
2192    "FilterContainer",
2193    AliFlowEventSimple::Class(),
2194    AliAnalysisManager::kExchangeContainer);
2195 // connect the output of the flow analysis task as input to the filter task
2196 mgr->ConnectInput(filterTask, 0, coutputFE);
2197 // and connect the filter container as output
2198 mgr->ConnectOutput(filterTask, 1, coutputFilter);
2199 // pass the filter task output to the analysis method
2200 // (this is assuming you already have setup the analysis task as
2201 // explained in the example in section 3.4.3
2202 mgr->ConnectInput(taskQC[i], 0, coutputFilter);\end{lstlisting}
2203 \subsection{Caveats}
2204 Note that the filter task will change the tags of the flow tracks in the flow event. \emph{Every} analysis task that runs after the filter task in an analysis train will therefore be affected by the re-taggging that is performed by the filter task. Often it can be useful to run multiple filter tasks with different configurations in an analysis train.
2205
2206 \section{Flow analysis of resonances}
2207 One notable case in which the filter task is useful, is the flow analysis of rapidly decaying particles via the invariant mass method. If a particle decays to daughter particles, e.g.
2208 \begin{equation}
2209 \Lambda \longrightarrow \pi + \mbox{p}
2210 \end{equation}
2211 one can do an invariant mass flow analysis, which basically comprises
2212 \begin{enumerate}
2213 \item Take all the $\pi + \mbox{p}$ pairs in an event and plot their invariant mass
2214 \item Extract the signal yield \alert{$N^S$} and total yield \alert{$N^T$} from this distribution
2215 \item Measure $v_2$ of all $\pi + \mbox{p}$ pairs
2216 \end{enumerate}
2217 Under the assumption that signal and background flow are additive, their contributions can be disentangled by solving
2218 \begin{equation}
2219 v_2^{T}(m_{inv})  = v_2^{S} \frac{N^{S} }{N^{S} + N^{B}}(m_{inv})  + v_2^{B}(m_{inv}) \frac{ N^{B}}{N^{S} + N^{B}}(m_{inv})
2220 \end{equation}
2221 for $v_2^{S}$. To do so, $v_2^{T}(m_{inv})$ must be measured. This can be done by measuring the $v_2$ of all possible $\pi + \mbox{p}$ pairs in different invariant mass intervals. When a flow event is filled by-hand with $\pi + \mbox{p}$ pairs, the filter task can then be in turn be used to split the flow event into invariant mass intervals and perform flow analysis on those separately, thereby extracting all necessary information. Examples of such analyses are e.g. the $\varhi$-meson flow analysis (\texttt{\$ALICE\_ROOT/PWG/FLOW/Tasks/AliAnalylsisTaskPhiFlow}) or the $\Lambda$ and $K^0$ flow task (\texttt{\$ALICE\_ROOT/PWG/FLOW/Tasks/AliAnalysisTaskFlowStrange}).
2222
2223 \section{Non-uniform acceptance correction}\index{NUA} \index{non uniform acceptance}
2224 In practice a detector can have inefficiencies which result in a non-uniform acceptance which might bias the measured $v_n$ signal. One way of compensating for this is using track weights (as explained in section \ref{sec:weights}. Another way of correcting for these effects is by adjusting the \texttt{Q} vectors based on the assumption that the underlying \texttt{Q} vector distribution itself is flat.
2225
2226 By default all necessary information to perform such a correction is stored when running a flow analysis task. The actual correction itself is performed when
2227 \texttt{Finish()} is called, depending whether or not the flag to perform the correction is set to \texttt{kTRUE}.
2228
2229 The effects of the acceptance correction can always be checked by running the \texttt{redoFinish.C} macro, by toggling the flag
2230 \begin{lstlisting}[language=C, numbers=left]
2231 Bool_t bApplyCorrectionForNUA = kFALSE; // apply correction for non-uniform acceptance\end{lstlisting}
2232 to either false or true.
2233 \subsection{Caveats}
2234 The non-uniform acceptance correction is based on the assumption that the physical \texttt{Q} vector distribution in your event sample is flat. This works for minimum bias events, but might not work for e.g. triggered events or for event samples where the detector efficiency varies event-by-event. Details pertaining to the implementation can be found in the \texttt{Finish()} methods of the various flow analysis tasks.
2235
2236 \chapter{Summary}
2237 After reading the documentation, you should have a general feeling of how the flow package is organized and be able to do a standard flow analysis. This however is just where the fun begins! Connect your classes, write a new method, add new routines $\cdots$ and publish your paper!
2238
2239
2240         \begin{thebibliography}{99}
2241         \bibliographystyle{apsrev}
2242
2243
2244                 \bibitem{Ollitrault:1992bk}
2245                 J.~Y.~Ollitrault,
2246                 %``Anisotropy as a signature of transverse collective flow,''
2247                 Phys.\ Rev.\ D {\bf 46} (1992) 229.
2248                 %%CITATION = PHRVA,D46,229;%%
2249
2250                 \bibitem{Danielewicz:1999vh}
2251                 P.~Danielewicz,
2252                 %``Flow and equation of state in heavy-ion collisions,''
2253                 Nucl.\ Phys.\ A {\bf 661} (1999) 82.
2254                 %  [arXiv:nucl-th/9907098].
2255                 %%CITATION = NUCL-TH 9907098;%%
2256
2257                 \bibitem{Rischke:1996nq}
2258                 D.~H.~Rischke,
2259                 %``Hydrodynamics and collective behavior in relativistic nuclear
2260                 %collisions,''
2261                 Nucl.\ Phys.\ A {\bf 610} (1996) 88C.
2262                 %  [arXiv:nucl-th/9608024].
2263                 %%CITATION = NUCL-TH 9608024;%%
2264
2265                 \bibitem{Ollitrault:1997vz}
2266                 J.~Y.~Ollitrault,
2267                 %``Flow systematics from SIS to SPS energies,''
2268                 Nucl.\ Phys.\ A {\bf 638} (1998) 195.
2269                 %  [arXiv:nucl-ex/9802005].
2270                 %%CITATION = NUCL-EX 9802005;%%
2271
2272                 \bibitem{Voloshin:1994mz}
2273                 S.~Voloshin and Y.~Zhang,
2274                 %``Flow study in relativistic nuclear collisions by Fourier expansion of
2275                 %Azimuthal particle distributions,''
2276                 Z.\ Phys.\ C {\bf 70} (1996) 665.
2277                 %  [arXiv:hep-ph/9407282].
2278                 %%CITATION = HEP-PH 9407282;%%
2279
2280                 %\cite{Ackermann:2000tr}
2281                 \bibitem{Ackermann:2000tr}
2282                 K.~H.~Ackermann {\it et al.}  [STAR Collaboration],
2283                 %``Elliptic flow in Au + Au collisions at s(N N)**(1/2) = 130-GeV,''
2284                 Phys.\ Rev.\ Lett.\  {\bf 86} (2001) 402
2285                 %[arXiv:nucl-ex/0009011].
2286                 %%CITATION = NUCL-EX 0009011;%%
2287
2288                 %\cite{Adler:2001nb}
2289                 \bibitem{Adler:2001nb}
2290                 C.~Adler {\it et al.}  [STAR Collaboration],
2291                 % ``Identified particle elliptic flow in Au + Au collisions at
2292                 %s(NN)**(1/2) =  130-GeV,''
2293                 Phys.\ Rev.\ Lett.\  {\bf 87} (2001) 182301
2294                 %[arXiv:nucl-ex/0107003].
2295                 %%CITATION = NUCL-EX 0107003;%%
2296
2297                 %%% theory RHIC discoveries %%%
2298                 %\cite{Gyulassy:2004zy}
2299                 \bibitem{RHIC_Discoveries}
2300                 T.D.~Lee {\it et al.},
2301                 New Discoveries at RHIC: Case for the Strongly Interacting
2302                 Quark-Gluon Plasma.
2303                 Contributions from the RBRC Workshop held May 14-15, 2004.
2304                 Nucl.\ Phys.\ A {\bf 750} (2005) 1-171
2305                 %%% end theory white-papers
2306
2307
2308         \end{thebibliography}
2309
2310 \appendix
2311         \chapter{About this document}
2312         \section{Specifics and webpage}
2313         Typeset using \LaTeX, converted to HTML using \texttt{pandoc} via \texttt{pandoc -r latex -w html -S -s -m -N --toc --highlight-style tango --indented-code-classes numberLines --self-contained -o FlowPackageManual.html FlowPackageManual.tex}
2314
2315         \chapter{Flow analysis `on-the-fly'}\label{sec:ante}
2316                 The original `on-the-fly' manual by Ante Biland\v zi\'c is reprinted here in this appendix
2317
2318         \section{Introduction}
2319 Flow analysis `on the fly' is a feature in the \textit{ALICE flow package}\footnote{\texttt{http://alisoft.cern.ch/viewvc/trunk/PWG2/FLOW/?root=AliRoot .}} which can serve both as a demo for the potential users of the package and as an important debugging tool for the core flow code developers. Underlying idea is very simple: To simulate events of interest for flow analysis (in what follows we shall refer to such events as \textit{flow events}) in the computers memory and than pass them `on the fly' to the implemented methods for flow analysis. Benefits of this approach include:
2320 %
2321 \begin{enumerate}
2322 \item No need to store data on disk (storing only the output files with the final results and not the simulated events themselves);
2323 \item Enormous gain in statistics;
2324 \item Speed (no need to open the files from disk to read the events);
2325 \item Random generators initialized with the same and random seed (if the same seed is used simulations are reproducible)\,.
2326 \end{enumerate}
2327 %
2328 In Section~\ref{kickStart} we indicate how the user can immediately in a few simple steps start flow analysis `on the fly' with the default settings both within AliRoot and Root. In Section~\ref{makingYourOwnFlowEvents} we explain how the user can modify the default settings and create `on the fly' different flow events by following the guidance of his own taste.
2329
2330 \section{Kickstart}
2331 \label{kickStart}
2332 We divide the potential users of ALICE flow package into two groups, namely the users which are using AliRoot (default) and the users which are using only Root.
2333
2334 \subsection{AliRoot users}
2335 To run flow analysis `on the fly' with the default settings within AliRoot and to see the final results obtained from various implemented methods for flow analysis, the user should execute the following steps:
2336 %
2337 \begin{list}{}{}
2338 \item \textbf{Step 1:} Turn off the lights ...
2339 \item \textbf{Step 2:} ... take a deep breath ...
2340 \item \textbf{Step 3:} ... start to copy macros
2341 \texttt{runFlowAnalysisOnTheFly.C} and \\ \texttt{compareFlowResults.C} from
2342 \texttt{AliRoot/PWG2/FLOW/macros} to your favorite directory slowly.
2343 \item \textbf{Step 4:} Once you have copied those macros in your favorite directory simply go to that directory and type
2344 %
2345 \begin{center}
2346 \texttt{aliroot runFlowAnalysisOnTheFly.C}
2347 \end{center}
2348 %
2349 \item \textbf{Step 5:} If you have a healthy AliRoot version the flow analysis `on the fly' will start. Once it is finished in your directory you should have the following files:
2350 %
2351 \begin{center}
2352 \begin{tabular}[t]{l}
2353 \texttt{runFlowAnalysisOnTheFly.C} \\
2354 \texttt{compareFlowResults.C} \\
2355 \texttt{outputLYZ1PRODanalysis.root} \\
2356 \texttt{outputQCanalysis.root} \\
2357 \texttt{outputFQDanalysis.root} \\
2358 \texttt{outputLYZ1SUManalysis.root} \\
2359 \texttt{outputSPanalysis.root} \\
2360 \texttt{outputGFCanalysis.root} \\
2361 \texttt{outputMCEPanalysis.root}
2362 \end{tabular}
2363 \end{center}
2364 %
2365 Each implemented method for flow analysis produced its own output file holding various output histograms. The final flow results are stored in the common histogram structure implemented in the class \texttt{AliFlowCommonHistResults}.
2366 \item \textbf{Step 6:} To access and compare those final flow results automatically there is a dedicated macro available, so execute
2367 %
2368 \begin{center}
2369 \begin{tabular}[t]{l}
2370 \texttt{> aliroot} \\
2371 \texttt{root [0] .x compareFlowResults.C("")}
2372 \end{tabular}
2373 \end{center}
2374 %
2375 \item \textbf{Step 7:} If you want to rerun and get larger statistics modify
2376 %
2377 \begin{center}
2378 \begin{tabular}[t]{l}
2379 \texttt{Int\_t nEvts=440}
2380 \end{tabular}
2381 \end{center}
2382 %
2383 in the macro \texttt{runFlowAnalysisOnTheFly.C}\,.
2384 \item \textbf{Step 8:} Have fun!
2385 \end{list}
2386 In the next section we outline the steps for the Root users.
2387
2388 \subsection{Root users}
2389 To be written at Nikhef...
2390 \section{Making your own flow events}
2391 \label{makingYourOwnFlowEvents}
2392 This section is common both for AliRoot and Roor users. In this section we outline the procedure the user should follow in order to simulate `on the fly' the events with his own settings by making use of the available setters. Those setters are implemented in the class \texttt{AliFlowEventSimpleMakerOnTheFly} and user shall use them in the macro \texttt{runFlowAnalysisOnTheFly.C}.
2393
2394 \subsection{$p_T$ spectra}
2395 Transverse momentum of particles is sampled from the predefined Boltzmann distribution
2396 %
2397 \begin{equation}
2398 \frac{dN}{dp_T} = Mp_T\exp\left(-\frac{\sqrt{m^2+p_T^2}}{T}\right)\,,
2399 \label{Boltzmann}
2400 \end{equation}
2401 %
2402 where $M$ is the multiplicity of the event, $T$ is ``temperature'' and $m$ is the mass of the particle. By increasing the parameter $T$ one is increasing the number of high $p_T$ particles and this parameter is the same for all events. On the other hand, multiplicity $M$ will in general vary from event to event. In the macro \texttt{runFlowAnalysisOnTheFly.C} one can modify distribution (\ref{Boltzmann}) by using setter for ``temperature'' $T$ and various setters for multiplicity $M$.
2403
2404 \vspace{0.5cm}
2405 \noindent\textbf{Example:} \textit{If one wants to increase/decrease the number of high $p_T$ particles, one should modify the line}
2406 %
2407 \begin{center}
2408 \texttt{Double\_t dTemperatureOfRP = 0.44;}
2409 \end{center}
2410 %
2411 \textit{Examples of $p_T$ spectra for two different values of $T$ are shown in Figures~\ref{temperature020} and \ref{temperature050}}.
2412 \vspace{0.5cm}
2413
2414 \begin{figure}
2415 \begin{minipage}[t]{0.5\linewidth} % A minipage that covers half the page
2416 \centering
2417 \includegraphics[width=7.5cm]{figures/temperature020.pdf}
2418 \caption{$T=0.2$ GeV/$c$\,.}
2419 \label{temperature020}
2420 \end{minipage}
2421 \hspace{0.5cm} % To get a little bit of space between the figures
2422 \begin{minipage}[t]{0.5\linewidth}
2423 \centering
2424 \includegraphics[width=7.5cm]{figures/temperature050.pdf}
2425 \caption{$T=0.5$ GeV/$c$\,.}
2426 \label{temperature050}
2427 \end{minipage}
2428 \end{figure}
2429
2430 \noindent What is shown in Figures~\ref{temperature020} and \ref{temperature050} is only one example of the so called \textit{common control histograms}. They are the histograms organized in the same structure and implemented in the class \texttt{AliFlowCommonHist}. In output file of each method one can access those histograms with \texttt{TBrowser}.
2431
2432 When it comes to multiplicity $M$, one has a choice to sample it event-by-event from two different distributions before plugging its value into Eq. (\ref{Boltzmann}) which than will be used to sample transverse momenta of $M$ particles in that event.
2433
2434 \vspace{0.5cm}
2435 \noindent\textbf{Example:} \textit{If one wants to sample multiplicity event-by-event from Gaussian distribution with mean 500 and spread 10, one should have the following relevant settings}
2436 %
2437 \begin{center}
2438 \begin{tabular}[t]{l}
2439 \texttt{Bool\_t bMultDistrOfRPsIsGauss = kTRUE;} \\
2440 \texttt{Int\_t iMultiplicityOfRP = 500;} \\
2441 \texttt{Double\_t dMultiplicitySpreadOfRP = 10;}
2442 \end{tabular}
2443 \end{center}
2444 %
2445 \textit{Example plot for multiplicity distribution with these settings is shown in Figure~\ref{multiplicityGauss}}.
2446 \vspace{0.5cm}
2447
2448 \noindent Another way to sample multiplicity event-by-event is by using uniform distribution.
2449
2450 \vspace{0.5cm}
2451 \noindent\textbf{Example:} \textit{If one wants to sample multiplicity event-by-event from uniform distribution in the interval [400,600], one must have the following relevant settings}
2452 %
2453 \begin{center}
2454 \begin{tabular}[t]{l}
2455 \texttt{Bool\_t bMultDistrOfRPsIsGauss = kFALSE;} \\
2456 \texttt{Int\_t iMinMultOfRP = 400;} \\
2457 \texttt{Int\_t iMaxMultOfRP = 600;}
2458 \end{tabular}
2459 \end{center}
2460 %
2461 \textit{Example plot for multiplicity distribution with these settings is shown in Figure~\ref{multiplicityUniform}}.
2462 \vspace{0.5cm}
2463
2464 \begin{figure}
2465 \begin{minipage}[t]{0.5\linewidth} % A minipage that covers half the page
2466 \centering
2467 \includegraphics[width=7.5cm]{figures/multiplicityGauss.pdf}
2468 \caption{Gaussian multiplicity distribution.}
2469 \label{multiplicityGauss}
2470 \end{minipage}
2471 \hspace{0.5cm} % To get a little bit of space between the figures
2472 \begin{minipage}[t]{0.5\linewidth}
2473 \centering
2474 \includegraphics[width=7.5cm]{figures/multiplicityUniform.pdf}
2475 \caption{Uniform multiplicity distribution.}
2476 \label{multiplicityUniform}
2477 \end{minipage}
2478 \end{figure}
2479
2480 \noindent One can also fix multiplicity to be the same for each event.
2481
2482 \vspace{0.5cm}
2483 \noindent\textbf{Example:} \textit{If one wants to have the same fixed multiplicity of 500 for each event one can use the following settings:}
2484 %
2485 \begin{center}
2486 \begin{tabular}[t]{l}
2487 \texttt{Bool\_t bMultDistrOfRPsIsGauss = kTRUE;} \\
2488 \texttt{Int\_t iMultiplicityOfRP = 500;} \\
2489 \texttt{Double\_t dMultiplicitySpreadOfRP = 0;}
2490 \end{tabular}
2491 \end{center}
2492 %
2493 \vspace{0.5cm}
2494
2495 \noindent These are all manipulations available at the moment with $p_T$ spectra given in Eq. (\ref{Boltzmann}).
2496
2497 \subsection{Azimuthal distribution}
2498 If the anisotropic flow exists, it will manifest itself in the anisotropic azimuthal distribution of outgoing particles measured with respect to the reaction plane:
2499 %
2500 \begin{equation}
2501 E\frac{d^3 N}{d^3 \vec{p}} = \frac{1}{2\pi} \frac{d^2 N}{p_T dp_T d\eta} \left( 1+\sum_{n=1}^{\infty}2v_n(p_T, \eta) \cos\left( n\left( \phi-\Psi_{\rm RP}\right) \right) \right)\,.
2502 \label{azimuthalDistributionGeneral}
2503 \end{equation}
2504 %
2505 Flow harmonics $v_n$ quantify anisotropic flow and are in general function of transverse momentum $p_T$ and pseudorapidity $\eta$. Orientation of reaction plane $\Psi_{\rm RP}$ fluctuates randomly event-by-event and cannot be measured directly. In the implementation `on the fly' reaction plane is sampled uniformly event-by-event from the interval $[0^{\rm o},360^{\rm o}]$. When it comes to flow harmonics, there are two modes which we outline next.
2506
2507 \subsubsection{Constant flow harmonics}
2508 In this mode all flow harmonics are treated as a constant, event-wise quantities, meaning that for a particular event azimuthal angles of all particles will be sampled from the same azimuthal distribution in which flow harmonics appear just as fixed parameters. The implemented most general azimuthal distribution for this mode reads
2509 %
2510 \begin{equation}
2511 \frac{dN}{d\phi} = 1+2v_1\cos(\phi-\Psi_{\rm RP})+2v_2\cos(2(\phi-\Psi_{\rm RP}))+2v_4\cos(4(\phi-\Psi_{\rm RP}))\,.
2512 \label{azimuthalDistributionOnlyPhi}
2513 \end{equation}
2514 %
2515 In the macro \texttt{runFlowAnalysisOnTheFly.C} one can use the dedicated setters and have handle on the flow harmonics $v_1$, $v_2$ and $v_4$. The most important harmonic is $v_2$, the so called \textit{elliptic flow}, so we start with it first.
2516
2517 \vspace{0.5cm}
2518 \noindent\textbf{Example:} \textit{If one wants to sample particle azimuthal angles from azimuthal distribution parameterized only with constant elliptic flow of 5\%, namely}
2519 %
2520 \begin{equation}
2521 \frac{dN}{d\phi} = 1+2\cdot 0.05\cdot\cos(2(\phi-\Psi_{\rm RP}))\,,
2522 \end{equation}
2523 %
2524 \textit{then one should use the following settings}
2525 %
2526 \begin{center}
2527 \begin{tabular}[t]{l}
2528 \texttt{Bool\_t bConstantHarmonics = kTRUE;} \\
2529 \texttt{Bool\_t bV2DistrOfRPsIsGauss = kTRUE;} \\
2530 \texttt{Double\_t dV2RP = 0.05;} \\
2531 \texttt{Double\_t dV2SpreadRP = 0.0;} \\
2532 \texttt{Double\_t dV1RP = 0.0;} \\
2533 \texttt{Double\_t dV1SpreadRP = 0.0;} \\
2534 \texttt{Double\_t dV4RP = 0.0;} \\
2535 \texttt{Double\_t dV4SpreadRP = 0.0;}
2536 \end{tabular}
2537 \end{center}
2538 %
2539 \vspace{0.5cm}
2540
2541 \noindent In this mode the flow coefficients are constant for all particles within particular event, but still the flow coefficients can fluctuate event-by-event.
2542
2543 \vspace{0.5cm}
2544 \noindent\textbf{Example:} \textit{If one wants to sample particle azimuthal angles from azimuthal distribution parameterized only with elliptic flow which fluctuates event-by-event according to Gaussian distribution with mean 5\% and spread 1\%, than one should use the following settings}
2545 %
2546 \begin{center}
2547 \begin{tabular}[t]{l}
2548 \texttt{Bool\_t bConstantHarmonics = kTRUE;} \\
2549 \texttt{Bool\_t bV2DistrOfRPsIsGauss = kTRUE;} \\
2550 \texttt{Double\_t dV2RP = 0.05;} \\
2551 \texttt{Double\_t dV2SpreadRP = 0.01;} \\
2552 \texttt{Double\_t dV1RP = 0.0;} \\
2553 \texttt{Double\_t dV1SpreadRP = 0.0;} \\
2554 \texttt{Double\_t dV4RP = 0.0;} \\
2555 \texttt{Double\_t dV4SpreadRP = 0.0;}
2556 \end{tabular}
2557 \end{center}
2558 %
2559 \vspace{0.5cm}
2560
2561 \noindent On can also study uniform flow fluctuations.
2562
2563 \vspace{0.5cm}
2564 \noindent\textbf{Example:} \textit{If one wants to sample particle azimuthal angles from azimuthal distribution parameterized only with elliptic flow which fluctuates event-by-event according to uniform distribution in interval [4\%,6\%], than one should use the following settings}
2565 %
2566 \begin{center}
2567 \begin{tabular}[t]{l}
2568 \texttt{Bool\_t bConstantHarmonics = kTRUE;} \\
2569 \texttt{Bool\_t bV2DistrOfRPsIsGauss = kFALSE;} \\
2570 \texttt{Double\_t dMinV2RP = 0.04;} \\
2571 \texttt{Double\_t dMinV2RP = 0.06;} \\
2572 \texttt{Double\_t dV1RP = 0.0;} \\
2573 \texttt{Double\_t dV1SpreadRP = 0.0;} \\
2574 \texttt{Double\_t dV4RP = 0.0;} \\
2575 \texttt{Double\_t dV4SpreadRP = 0.0;}
2576 \end{tabular}
2577 \end{center}
2578 %
2579 \vspace{0.5cm}
2580
2581 \noindent It is of course possible to simulate simultanously nonvanishing $v_1$, $v_2$ and $v_4$.
2582
2583
2584 \vspace{0.5cm}
2585 \noindent\textbf{Example:} \textit{If one wants to sample particle azimuthal angles from azimuthal distribution parameterized by harmonics $v_1=2\%$, $v_2=5\%$ and $v_4=1\%$, namely}
2586 %
2587 \begin{eqnarray}
2588 \frac{dN}{d\phi} &=& 1+2\cdot 0.02\cdot\cos(\phi-\Psi_{\rm RP})+2\cdot 0.05\cdot\cos(2(\phi-\Psi_{\rm RP}))\nonumber\\
2589 &+&2\cdot 0.01\cdot\cos(4(\phi-\Psi_{\rm RP}))
2590 \end{eqnarray}
2591 %
2592 \textit{then one should use the following settings}
2593 %
2594 \begin{center}
2595 \begin{tabular}[t]{l}
2596 \texttt{Bool\_t bConstantHarmonics = kTRUE;} \\
2597 \texttt{Bool\_t bV2DistrOfRPsIsGauss = kTRUE;} \\
2598 \texttt{Double\_t dV2RP = 0.05;} \\
2599 \texttt{Double\_t dV2SpreadRP = 0.0;} \\
2600 \texttt{Double\_t dV1RP = 0.02;} \\
2601 \texttt{Double\_t dV1SpreadRP = 0.0;} \\
2602 \texttt{Double\_t dV4RP = 0.01;} \\
2603 \texttt{Double\_t dV4SpreadRP = 0.0;}
2604 \end{tabular}
2605 \end{center}
2606 %
2607 \vspace{0.5cm}
2608
2609 \noindent In the next section we outline the procedure for simulating flow events with $p_T$ dependent flow harmonics.
2610
2611 \subsubsection{$p_T$ dependent flow harmonics}
2612 In this mode the functional dependence of flow harmonics on transverse momentum is treated as an event-wise quantity, while within the particular event the flow harmonics will change from particle to particle depending on its transverse momentum. The implemented azimuthal distribution for this case reads
2613 %
2614 \begin{equation}
2615 \frac{dN}{d\phi} = 1+2v_2(p_T)\cos(2(\phi-\Psi_{\rm RP}))\,,
2616 \label{azimuthalDistributionOnlyPtDependent}
2617 \end{equation}
2618 %
2619 and the functional dependence $v_2(p_T)$ is implemented as follows:
2620 %
2621 \begin{equation}
2622 v_2(p_T) = \left\{
2623 \begin{array}{ll}
2624 v_{\rm max}(p_T/p_{\rm cutoff}) & p_T < p_{\rm cutoff}\,, \\
2625 v_{\rm max} & p_T \geq p_{\rm cutoff}\,. \\
2626 \end{array}
2627 \right.
2628 \label{v(pt)parametrization}
2629 \end{equation}
2630 %
2631 In the macro \texttt{runFlowAnalysisOnTheFly.C} one can have the handle on the parameters $v_{\rm max}$ and $p_{\rm cutoff}$.
2632
2633 \vspace{0.5cm}
2634 \noindent\textbf{Example:} \textit{If one wants to set $v_{\rm max} = 0.2$ and $p_{\rm cutoff} = 2$ GeV/$c$, than one should use the following settings:}
2635 %
2636 \begin{center}
2637 \begin{tabular}[t]{l}
2638 \texttt{Bool\_t bConstantHarmonics = kFALSE;} \\
2639 \texttt{Double\_t dV2RPMax = 0.20;} \\
2640 \texttt{Double\_t dPtCutOff = 2.0;}
2641 \end{tabular}
2642 \end{center}
2643 %
2644 \textit{Example plot is given in Figure~\ref{vVsPt}}.
2645 \vspace{0.5cm}
2646
2647 %
2648 \begin{figure}
2649 \begin{center}
2650   \includegraphics[width=7.5cm,angle=0]{figures/vVsPt.pdf}
2651   \caption{$p_T$ dependent elliptic flow.}
2652 \label{vVsPt}
2653 \end{center}
2654 \end{figure}
2655 %
2656
2657 (Remark: Add further explanation here.)
2658
2659 \subsection{Nonflow}
2660 One can simply simulate strong 2-particle nonflow correlations by taking each particle twice.
2661
2662 \vspace{0.5cm}
2663 \noindent\textbf{Example:} \textit{If one wants to simulate strong 2-particle nonflow correlations one should simply set}
2664 %
2665 \begin{center}
2666 \texttt{Int\_t iLoops = 2;}
2667 \end{center}
2668 %
2669 \vspace{0.5cm}
2670
2671 \subsection{Detector inefficiencies}
2672 In reality we never deal with a detector with uniform azimuthal coverage, hence a need for a thorough studies of the systematic bias originating from the non-uniform acceptance.
2673
2674 \vspace{0.5cm}
2675 \noindent\textbf{Example:} \textit{One wants to simulate a detector whose acceptance is uniform except for the sector which spans the azimuthal interval $[60^{\rm o},120^{\rm o}]$. In this sector there are some issues, so only half of the particles are reconstructed. To simulate this acceptance one should use the following settings:}
2676 %
2677 \begin{center}
2678 \begin{tabular}[t]{l}
2679 \texttt{Bool\_t uniformAcceptance = kFALSE;} \\
2680 \texttt{Double\_t phimin1 = 60;} \\
2681 \texttt{Double\_t phimax1 = 120;} \\
2682 \texttt{Double\_t p1 = 1/2.;} \\
2683 \texttt{Double\_t phimin2 = 0.0;} \\
2684 \texttt{Double\_t phimax2 = 0.0;} \\
2685 \texttt{Double\_t p2 = 0.0;}
2686 \end{tabular}
2687 \end{center}
2688 %
2689 \textit{The resulting azimuthal profile is shown in Figure~(\ref{azimuthalAcceptanceOneSector})}.
2690 \vspace{0.5cm}
2691
2692 \noindent One can also simulate two problematic sectors.
2693
2694 \vspace{0.5cm}
2695 \noindent\textbf{Example:} \textit{One wants to simulate a detector whose acceptance is uniform except for the two sectors which span azimuth $[60^{\rm o}, 120^{\rm o}]$ and $[270^{\rm o}, 330^{\rm o}]$, respectively. In the first sector only 1/2 of the particles are reconstructed and only 1/3 of the particles are reconstructed in the second. To simulate this acceptance one should use the following settings:}
2696 %
2697 \begin{center}
2698 \begin{tabular}[t]{l}
2699 \texttt{Bool\_t uniformAcceptance = kFALSE;} \\
2700 \texttt{Double\_t phimin1 = 60;} \\
2701 \texttt{Double\_t phimax1 = 120;} \\
2702 \texttt{Double\_t p1 = 1/2.;} \\
2703 \texttt{Double\_t phimin2 = 270.0;} \\
2704 \texttt{Double\_t phimax2 = 330.0;} \\
2705 \texttt{Double\_t p2 = 1/3.;}
2706 \end{tabular}
2707 \end{center}
2708 %
2709 \textit{The resulting azimuthal profile is shown in Figure~(\ref{azimuthalAcceptanceTwoSectors})}.
2710 \vspace{0.5cm}
2711
2712 \begin{figure}
2713 \begin{minipage}[t]{0.5\linewidth} % A minipage that covers half the page
2714 \centering
2715 \includegraphics[width=7.5cm]{figures/azimuthalAcceptanceOneSector.pdf}
2716 \caption{Non-uniform acceptance.}
2717 \label{azimuthalAcceptanceOneSector}
2718 \end{minipage}
2719 \hspace{0.5cm} % To get a little bit of space between the figures
2720 \begin{minipage}[t]{0.5\linewidth}
2721 \centering
2722 \includegraphics[width=7.5cm]{figures/azimuthalAcceptanceTwoSectors.pdf}
2723 \caption{Non-uniform acceptance.}
2724 \label{azimuthalAcceptanceTwoSectors}
2725 \end{minipage}
2726 \end{figure}
2727 \printindex
2728 \end{document}