Skip to content

Commit 0e37bb8

Browse files
njacazionjacazio
committed
Add dyn cols
1 parent 9071208 commit 0e37bb8

File tree

1 file changed

+114
-12
lines changed

1 file changed

+114
-12
lines changed

‎docs/analysis-tools/PID.md‎

Lines changed: 114 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,16 @@ Table of contents:
1010
- [Particle identification (PID)](#particle-identification-pid)
1111
- [Introduction](#introduction)
1212
- [Usage in user tasks](#usage-in-user-tasks)
13-
- [Task for TOF, TPC and ITS PID](#task-for-tof-tpc-and-its-pid)
13+
- [Available PID Information](#available-pid-information)
14+
- [Supported Particle Species](#supported-particle-species)
15+
- [Additional TOF-Specific Information](#additional-tof-specific-information)
16+
- [Usage in analysis tasks](#usage-in-analysis-tasks)
17+
- [Tasks for TOF, TPC and ITS PID](#tasks-for-tof-tpc-and-its-pid)
1418
- [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)
1519
- [Enabling QA histograms](#enabling-qa-histograms)
20+
- [Advanced features](#advanced-features)
21+
- [Dynamic Columns for TOF Beta and Mass](#dynamic-columns-for-tof-beta-and-mass)
22+
- [Dynamic Columns for nSigma Calculations](#dynamic-columns-for-nsigma-calculations)
1623

1724
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.
1825

@@ -30,19 +37,62 @@ The ITS PID columns are only dynamical and do not need a task to produce them, h
3037

3138
## Usage in user tasks
3239

33-
Tables for PID values in O2 are defined in [`PIDResponseITS.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/PIDResponseITS.h), [`PIDResponseTPC.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/PIDResponseTPC.h) and [`PIDResponseTOF.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/PIDResponseTOF.h).
34-
You can include it in your task with:
40+
Tables for PID values in O2 are defined in the following header files:
3541

36-
``` c++
37-
#include "Common/DataModel/PIDResponseITS.h" // ITS PID information
38-
#include "Common/DataModel/PIDResponseTPC.h" // TPC PID information
39-
#include "Common/DataModel/PIDResponseTOF.h" // TOF PID information
40-
...
42+
| Detector | Header File | Usage | Description |
43+
|----------|-------------|----|---------|
44+
| ITS | [`PIDResponseITS.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/PIDResponseITS.h) | `#include "Common/DataModel/PIDResponseITS.h"` | ITS PID information |
45+
| TPC | [`PIDResponseTPC.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/PIDResponseTPC.h) | `#include "Common/DataModel/PIDResponseTPC.h"` | TPC PID information |
46+
| TOF | [`PIDResponseTOF.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/PIDResponseTOF.h) | `#include "Common/DataModel/PIDResponseTOF.h"` | TOF PID information |
4147

42-
```
48+
49+
## Available PID Information
50+
51+
The following table shows the available PID methods for each detector and particle species:
52+
53+
| Information Type | Description | TOF Methods | TPC Methods | ITS Methods |
54+
|------------------|-------------|-------------|-------------|-------------|
55+
| **nSigma** | Nsigma separation value | `tofNSigmaXX()` | `tpcNSigmaXX()` | `itsNSigmaXX()` |
56+
| **Expected Signal** | Expected detector signal | `tofExpSignalXX()` | `tpcExpSignalXX()` | `expSignal<PID::XX>()` |
57+
| **Expected Resolution** | Expected detector resolution | `tofExpSigmaXX()` | `tpcExpSigmaXX()` | `expResolution<PID::XX>()` |
58+
| **Signal Difference** | Difference between measured and expected | `tofExpSignalDiffXX()` | `tpcExpSignalDiffXX()` | - |
59+
60+
61+
#### Supported Particle Species
62+
63+
Where `XX` represents the particle species: `El` (electron), `Mu` (muon), `Pi` (pion), `Ka` (kaon), `Pr` (proton), `De` (deuteron), `Tr` (triton), `He` (helium3), `Al` (alpha, i.e. helium4).
64+
65+
| Symbol | Particle | Mass Hypothesis |
66+
|--------|----------|----------------|
67+
| `El` | Electron | e⁻ |
68+
| `Mu` | Muon | μ⁻ |
69+
| `Pi` | Pion | π± |
70+
| `Ka` | Kaon | K± |
71+
| `Pr` | Proton | p |
72+
| `De` | Deuteron | d |
73+
| `Tr` | Triton | t |
74+
| `He` | Helium-3 | ³He |
75+
| `Al` | Alpha | α (⁴He) |
4376

4477
In the process functions, you can join the table to add the PID (per particle mass hypothesis) information to the track.
45-
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`).
78+
In this case, we are using the mass hypothesis of the electron (and only for the **NSigma** information), but tables for nine (9) stable particle species are produced (`El`, `Mu`, `Pi`, `Ka`, `Pr`, `De`, `Tr`, `He`, `Al`).
79+
80+
### Additional TOF-Specific Information
81+
82+
The TOF detector provides additional specialized information beyond the standard PID methods:
83+
84+
| Information Type | Description | TOF Methods | Notes |
85+
|------------------|-------------|-------------|-------|
86+
| **Beta** | Velocity as fraction of speed of light | `beta()`, `tofBeta()` | β = v/c, fundamental for mass calculation |
87+
| **Beta Error** | Uncertainty on beta measurement | `betaerror()` | Statistical uncertainty on β |
88+
| **TOF Mass** | Reconstructed particle mass | `mass()`, `tofMass()` | Calculated from momentum and β |
89+
| **Event Time** | Collision time for TOF measurement | `tofEvTime()` | Event collision time used for PID |
90+
| **Event Time Error** | Uncertainty on event time | `tofEvTimeErr()` | Error on collision time determination |
91+
| **TOF Signal** | Raw TOF signal | `tofSignal()` | Direct detector measurement |
92+
93+
> **Note**: For advanced TOF features including dynamic columns for beta, mass, nSigma calculations, see the [Advanced Features](#advanced-features) section.
94+
95+
### Usage in analysis tasks
4696

4797
- For the **TOF** PID as:
4898

@@ -60,7 +110,7 @@ In this case, we are using the mass hypothesis of the electron, but tables for n
60110
}
61111
```
62112

63-
- For both TOF and TPC PID information as:
113+
- For both **TOF** and **TPC** PID information as:
64114

65115
``` c++
66116
void process(soa::Join<aod::Tracks, aod::pidTOFEl, aod::pidTPCEl>::iterator const& track) {
@@ -83,7 +133,7 @@ In this case, we are using the mass hypothesis of the electron, but tables for n
83133
```
84134

85135

86-
## Task for TOF, TPC and ITS PID
136+
## Tasks for TOF, TPC and ITS PID
87137

88138
**In short:** O2 tasks dedicated to the filling of the PID tables are called with
89139

@@ -145,3 +195,55 @@ In this case, we are using the mass hypothesis of the electron, but tables for n
145195
```
146196

147197
Where by `...` we mean the other tasks in your workflow.
198+
199+
200+
## Advanced features
201+
202+
Beyond the basic PID functionality, the O2 Analysis Framework provides several advanced features for sophisticated particle identification workflows.
203+
204+
#### Dynamic Columns for TOF Beta and Mass
205+
206+
The TOF beta and mass can also be calculated dynamically using the following columns:
207+
208+
| Dynamic Column | Method | Description |
209+
|----------------|--------|-------------|
210+
| **TOF Beta** | `tofBeta()` | Dynamically calculated β value |
211+
| **TOF Mass** | `tofMass()` | Dynamically calculated mass |
212+
213+
#### Dynamic Columns for nSigma Calculations
214+
215+
For more advanced use cases, nSigma values can also be computed dynamically for all detectors:
216+
217+
| Detector | Dynamic Column | Method | Description |
218+
|----------|----------------|--------|-------------|
219+
| **TOF** | `TOFNSigmaDynXX` | `tofNSigmaDynXX()` | On-the-fly nSigma calculation |
220+
| **TPC** | `TPCNSigmaDynXX` | `tpcNSigmaDynXX()` | On-the-fly nSigma calculation |
221+
| **ITS** | `ITSNSigmaXX` | `itsNSigmaXX()` | On-the-fly nSigma calculation |
222+
223+
Where `XX` represents the particle species (`El`, `Mu`, `Pi`, `Ka`, `Pr`, `De`, `Tr`, `He`, `Al`).
224+
225+
**Dynamic nSigma advantages:**
226+
- Use the most current detector calibrations
227+
- Avoid pre-computed table storage requirements
228+
- Allow for real-time parameter adjustments
229+
- Enable detector-specific tuning on-the-fly
230+
231+
These tasks do not need a dedicated task apart from the computation of the `tofSignal` and `tofEvTime`.
232+
233+
234+
235+
236+
**Example usage with dynamic columns:**
237+
```c++
238+
// For TOF Beta
239+
using TOFBeta = o2::aod::TOFBeta;
240+
void process(soa::Join<aod::Tracks, TOFBeta>::iterator const& track) {
241+
float beta = track.tofBeta();
242+
}
243+
244+
// For TOF Mass
245+
using TOFMass = o2::aod::TOFMass;
246+
void process(soa::Join<aod::Tracks, TOFMass>::iterator const& track) {
247+
float mass = track.tofMass();
248+
}
249+
```

0 commit comments

Comments
 (0)