Merge pull request #322 from altsybee/master

move "Helper tasks" to the new top-level chapter "Analysis tools"

Author: ddobrigk

docs/analysis-tools/EventSelection.md

@@ -0,0 +1,68 @@
+---
+sort: 1
+title: Multiplicity and centrality selection
+---
+
+# Multiplicity and centrality selection in O2
+
+## Multiplicity selection concept
+
+The multiplicity and centrality selection in O2 is based on the concept of derived tables created in dedicated tasks from available AOD contents:
+
+* _o2-analysis-multiplicity-table_ task [`Common/TableProducer/multiplicityTable.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/multiplicityTable.cxx) stores relevant multiplicity values (V0A, V0C, ZNA, ZNC) and their dynamic sums (V0M) in [`Mults`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/Multiplicity.h) table joinable with _Collisions_ table.
+* _o2-analysis-multiplicity-qa_ task [`Common/Tasks/multiplicityQa.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Tasks/multiplicityQa.cxx) creates multiplicity distributions in minimum bias triggers necessary for centrality calibration.
+* _o2-analysis-centrality-table_ task [`Common/TableProducer/centralityTable.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/centralityTable.cxx) takes multiplicity values from the [`Mults`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/Multiplicity.h) table and stores centrality values in [`Cents`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/Centrality.h) table joinable with _Collisions_ table. Relevant cumulative multiplicity distributions are stored in [CCDB](http://alice-ccdb.cern.ch/browse/Centrality). The centrality calibration relies on 90% anchor points in Pb-Pb.
+* _o2-analysis-centrality-qa_ task [`Common/Tasks/centralityQa.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Tasks/centralityQa.cxx) creates centrality distributions for minimum bias triggers and can be used for control and QA purposes.
+
+Note that _o2-analysis-multiplicity-qa_ and _o2-analysis-centrality-qa_ tasks rely on the minimum bias trigger selection therefore one has to run event selection in stack with these tasks.
+
+## Multiplicity selection usage in user tasks
+
+One can check _o2-analysis-centrality-qa_ task for example usage: [`Common/Tasks/centralityQa.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Tasks/centralityQa.cxx). Usually, analysers perform event selection before the centrality selection therefore one has to consider the following steps:
+
+* add [`EventSelection.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/EventSelection.h) and [`Centrality.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/Centrality.h) headers:
+
+    ``` c++
+    #include "Common/DataModel/EventSelection.h"
+    #include "Common/DataModel/Centrality.h"
+    ```
+
+* join _Collisions_, _EvSels_ and _Cents_ tables and use corresponding iterator as an argument of the process function:
+
+    ``` c++
+    void process(soa::Join<aod::Collisions, aod::EvSels, aod::Cents>::iterator const& col, ...)
+    ```
+
+* check if your trigger alias is fired if you run over Run1 or Run2 data (or future triggered Run3 data):
+
+    ``` c++
+    if (!col.alias_bit(kINT7))
+      return;
+    ```
+
+    Bypass this check if you analyse MC or future continuous Run3 data.
+* apply further offline selection criteria:
+
+    ``` c++
+    if (!col.sel7())
+      return;
+    ```
+
+* apply centrality selection, for example:
+
+    ``` c++
+    // analyse 0-20% central events
+    if (col.centV0M()>20)
+      return;
+    ```
+
+* run your tasks in stack with timestamp, event-selection, multiplicity and centrality tasks:
+
+    ``` bash
+    o2-analysis-timestamp --aod-file AO2D.root -b | o2-analysis-event-selection -b | o2-analysis-mulitplicity-table -b | o2-analysis-centrality-table -b | o2-analysis-user-task -b
+    ```
+
+    _o2-analysis-timestamp_ task is required to create per-event timestamps necessary to access relevant CCDB objects in the event selection and/or centrality tasks.
+
+    _o2-analysis-zdc-converter_ and _o2-analysis-collision-converter_ might be also necessary for old datasets to account for changes in the data model.
+

docs/analysis-tools/MultiplicityAndCentralitySelection.md

@@ -0,0 +1,131 @@
+---
+sort: 2
+title: Particle identification (PID)
+---
+
+# Particle identification (PID)
+
+Table of contents:
+
+* [Introduction](#introduction)
+* [Usage in user tasks](#usage-in-user-tasks)
+* [Task for TOF and TPC PID](#task-for-tof-and-tpc-pid)
+* [Example of tasks that use the PID tables (and how to run them)](#example-of-tasks-that-use-the-pid-tables-and-how-to-run-them)
+
+Here are described the working principles of Particle Identification (PID) in O2 and how to get PID information (expected values, nSigma separation _et cetera_) in your analysis tasks if you plan to identify particles.
+
+## Introduction
+
+PID is handled in analysis by filling helper tables that can be joined to tracks (propagated or not).
+The parameterization of the expected detector response (e.g. signal, resolution, separation) is used in the PID tasks to fill the PID tables.
+These parameterizations are detector specific and handled by the detector experts; usually, they are shipped to the PID helper tasks from the CCDB to match the data-taking conditions.
+The interface between the detector and the Analysis Framework (i.e. your tracks) is fully enclosed in [`PIDResponse.h`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/DataModel/PIDResponse.h).
+Here are the defined tables for the PID information for all the detectors.
+
+The filling of the PID tables is delegated to dedicated tasks in [`Common/TableProducer/PID/`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/TableProducer/PID)
+Examples of these tasks can be found in [`pidTOF.cxx`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/TableProducer/PID/pidTOF.cxx) and [`pidTPC.cxx`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/TableProducer/PID/pidTPC.cxx) for TOF and TPC tables, respectively.
+
+## Usage in user tasks
+
+Tables for PID values in O2 are defined in [`PIDResponse.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/PIDResponse.h).
+You can include it in your task with:
+
+``` c++
+#include "Common/DataModel/PIDResponse.h"
+...
+
+```
+
+In the process functions, you can join the table to add the PID (per particle mass hypothesis) information to the track.
+In this case, we are using the mass hypothesis of the electron, but tables for nine (9) stable particle species are produced (`El`, `Mu`, `Pi`, `Ka`, `Pr`, `De`, `Tr`, `He`, `Al`).
+
+* For the **TOF** PID as:
+
+    ``` c++
+    void process(soa::Join<aod::Tracks, aod::pidTOFEl>::iterator const& track) {
+      track.tofNSigmaEl();
+    }
+    ```
+
+* For the **TPC** PID as:
+
+    ``` c++
+    void process(soa::Join<aod::Tracks, aod::pidTPCEl>::iterator const& track) {
+      track.tpcNSigmaEl();
+    }
+    ```
+
+* For both TOF and TPC PID information as:
+
+    ``` c++
+    void process(soa::Join<aod::Tracks, aod::pidTOFEl, aod::pidTPCEl>::iterator const& track) {
+      const float combNSigmaEl = std::sqrt( track.tofNSigmaEl() * track.tofNSigmaEl() + track.tpcNSigmaEl() * track.tpcNSigmaEl());
+    }
+    ```
+
+## Task for TOF and TPC PID
+
+**In short:** O2 tasks dedicated to the filling of the PID tables are called with
+
+* Filling TOF PID Table
+
+    ``` bash
+    o2-analysis-pid-tof
+    ```
+
+    This requires a helper class for the building of the event time information
+
+    ``` bash
+    o2-analysis-pid-tof-base
+    ```
+
+    These tasks can be configured according to the needs specified by the detector experts.
+    If you are in doubt, you can contact them or take the configuration of the Hyperloop as a reference.
+
+* Filling the TPC PID Table
+
+    ``` bash
+    o2-analysis-pid-tpc
+    ```
+
+    ``` bash
+    o2-analysis-pid-tpc-base
+    ```
+
+    These tasks can be configured according to the needs specified by the detector experts.
+    If you are in doubt, you can contact them or take the configuration of the Hyperloop as a reference.
+
+## Example of tasks that use the PID tables (and how to run them)
+
+* TOF PID task [`pidTOF.cxx`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/TableProducer/PID/pidTOF.cxx)
+    You can run the TOF spectra task with:
+
+    ``` bash
+    o2-analysis-pid-tof-qa --aod-file AO2D.root -b | o2-analysis-pid-tof -b | o2-analysis-pid-tof-base -b
+    ```
+
+* TPC PID task [`pidTPC.cxx`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/TableProducer/PID/pidTPC.cxx)
+    You can run the TPC spectra task with:
+
+    ``` bash
+    o2-analysis-pid-tpc-qa --aod-file AO2D.root -b | o2-analysis-pid-tpc -b | o2-analysis-pid-tpc-base -b
+    ```
+
+## Enabling QA histograms
+
+* QA histograms should come with the PID tasks; they can be enabled by including the QA tasks in your workflow when running locally or with the corresponding QA tasks as in:
+
+    For the **TOF** QA plots
+
+    ``` bash
+    ... | o2-analysis-pid-tof-qa | ...
+    ```
+
+    For the **TPC** QA plots
+
+    ``` bash
+    ... | o2-analysis-pid-tpc-qa | ...
+    ```
+
+    Where by `...` we mean the other tasks in your workflow.
+

docs/analysis-tools/PID.md

@@ -0,0 +1,10 @@
+---
+sort: 3
+title: Analysis tools
+---
+
+# Analysis tools
+
+This section of the documentation is intended to explain basic analysis tools:
+
+{% include list.liquid all=true %}