+Corresponding [JIRA tickets](https://its.cern.ch/jira/issues/?jql=project%20%3D%20PWG-HF%20AND%20%22Run%203%20analysis%22%20%3D%20Yes) ## Framework structure -Simplified graph of the workflows and tasks involved in a single HF analysis is shown in the following picture. +A simplified graph of the workflows and tasks involved in a single HF analysis is shown in the following picture. Individual components are described in the next section below.
@@ -59,9 +65,8 @@ Individual components are described in the next section below.
### Track index skimming
-Workflow | File | Type
-------------------------------------------|-----------------------------|------------------------------------
-`o2-analysis-hf-track-index-skim-creator` | `trackIndexSkimCreator.cxx` | direct 2/3-prong and cascade decays
+Workflow: `o2-analysis-hf-track-index-skim-creator`
+File: [`trackIndexSkimCreator.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/PWGHF/TableProducer/trackIndexSkimCreator.cxx) #### Track and event selection @@ -81,14 +86,9 @@ together with a flag indicating for which decay channel(s) the candidate was sel ### Candidate creation and MC matching -Workflow | File | Type --------------------------------------------|-------------------------------|------------------------------------------------------------------------ -`o2-analysis-hf-candidate-creator-2prong` | `candidateCreator2Prong.cxx` | direct 2-prong decays -`o2-analysis-hf-candidate-creator-3prong` | `candidateCreator3Prong.cxx` | direct 3-prong decays -`o2-analysis-hf-candidate-creator-cascade` | `candidateCreatorCascade.cxx` | cascade decays with V0 daughters (Λc±) -`o2-analysis-hf-candidate-creator-xicc` | `candidateCreatorXicc.cxx` | Ξcc±± → Ξc± π± -`o2-analysis-hf-candidate-creator-x` | `candidateCreatorX.cxx` | X(3872) → J/ψ π± π∓ -`o2-analysis-hf-candidate-creator-bplus` | `candidateCreatorBplus.cxx` | B± → D0(bar) π± +Workflows: `o2-analysis-hf-candidate-creator-`
+Files: `candidateCreator.cxx`
+Directories: [`PWGHF/TableProducer`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/TableProducer), `PWGHF/*/TableProducer` #### Candidate creation @@ -111,17 +111,9 @@ Derived tables with MC flags used for the estimation of the signal efficiencies ### Candidate selection -Workflow | File | Type -------------------------------------------------------|-------------------------------------|---------------------------------------------------------------------- -`o2-analysis-hf-candidate-selector-d0` | `candidateSelectorD0.cxx` | D0(bar) → π± K∓ -`o2-analysis-hf-candidate-selector-jpsi` | `candidateSelectorJpsi.cxx` | J/ψ → e+ e−/μ+ μ− -`o2-analysis-hf-candidate-selector-x-to-jpsi-pi-pi` | `candidateSelectorXToJpsiPiPi.cxx` | X(3872) → J/ψ π± π∓ -`o2-analysis-hf-candidate-selector-dplus-to-pi-k-pi` | `candidateSelectorDplusToPiKPi.cxx` | D± → π± K∓ π± -`o2-analysis-hf-candidate-selector-lc` | `candidateSelectorLc.cxx` | Λc± → p(bar) K∓ π± -`o2-analysis-hf-candidate-selector-lc-to-k0s-p` | `candidateSelectorLcToK0sP.cxx` | Λc± → p(bar) KS0 -`o2-analysis-hf-candidate-selector-xic-to-p-k-pi` | `candidateSelectorXicToPKPi.cxx` | Ξc± → p(bar) K∓ π± -`o2-analysis-hf-candidate-selector-xicc-to-p-k-pi-pi` | `candidateSelectorXiccToPKPiPi.cxx` | Ξcc±± → Ξc± π± -`o2-analysis-hf-candidate-selector-bplus-to-d0-pi` | `candidateSelectorBplusToD0Pi.cxx` | B± → D0(bar) π± +Workflows: `o2-analysis-hf-candidate-selector-`
+Files: `candidateSelector.cxx`
+Directories: [`PWGHF/TableProducer`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/TableProducer), `PWGHF/*/TableProducer` In a dedicated selector task, tailored for each decay channel, accurate analysis level selection criteria based on decay topology and PID are applied to the reconstructed candidates. @@ -130,20 +122,9 @@ The selection results are stored in a column of a new dedicated table that is la ### Analysis tasks -Workflow | File | Type ------------------------------------------|-----------------------------|------------------------------------------------------------------------- -`o2-analysis-hf-task-d0` | `taskD0.cxx` | D0(bar) → π± K∓ -`o2-analysis-hf-task-jpsi` | `taskJpsi.cxx` | J/ψ → e+ e−/μ+ μ− -`o2-analysis-hf-task-dplus` | `taskDplus.cxx` | D± → π± K∓ π± -`o2-analysis-hf-task-lc` | `taskLc.cxx` | Λc± → p(bar) K∓ π± -`o2-analysis-hf-task-lc-to-k0s-p` | `taskLcToK0sP.cxx` | Λc± → p(bar) KS0 -`o2-analysis-hf-task-xic` | `taskXic.cxx` | Ξc± → p(bar) K∓ π± -`o2-analysis-hf-task-xicc` | `taskXicc.cxx` | Ξcc±± → Ξc± π± -`o2-analysis-hf-task-bplus` | `taskBplus.cxx` | B± → D0(bar) π± -`o2-analysis-hf-task-x` | `taskX.cxx` | X(3872) → J/ψ π± π∓ -`o2-analysis-hf-correlator-d0-d0bar` | `correlatorD0D0bar.cxx` | D0–D0bar correlations -`o2-analysis-hf-correlator-dplus-dminus` | `correlatorDplusDminus.cxx` | D+–D− correlations -`o2-analysis-hf-task-correlation-d-dbar` | `taskCorrelationDDbar.cxx` | D0–D0bar, D+–D− correlations +Workflows: `o2-analysis-hf-task-`
+Files: `task.cxx`
+Directories: [`PWGHF/Tasks`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/Tasks), `PWGHF/*/Tasks` #### Real-data analysis @@ -153,26 +134,40 @@ In the user analysis task, histograms needed for the analysis are filled with pr For MC events, histograms with quantities of generated MC particles and MC-matched candidates are produced. +### Tree creation + +Candidate tables and other related derived tables are exported to disk as ROOT trees for +post-processing with external tools, e.g. for selection optimisation with machine learning techniques. + +Workflows: `o2-analysis-hf-tree-creator-`
+Files: `treeCreator.cxx`
+Directories: [`PWGHF/TableProducer`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/TableProducer), `PWGHF/*/TableProducer` + +### Derived-data creation + +Derived-data creators are a better alternative to tree creators, because they are more flexible and +can produce light self-contained interlinked tables which are independent from the parent AO2D files +and can therefore be stored as derived datasets on AliHyperloop as well as processed locally. + +Workflows: `o2-analysis-hf-derived-data-creator-`
+Files: `derivedDataCreator.cxx`
+Directories: [`PWGHF/TableProducer`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/TableProducer), `PWGHF/*/TableProducer` + ### QA and helper workflows Workflow | File | Type ---------------------------------------|---------------------------|---------------------------------------------------------------------------- +`o2-analysis-hf-pid-creator` | `pidCreator.cxx` | creation of tables combining *σ* from TPC and TOF for track selection `o2-analysis-hf-task-mc-validation` | `taskMcValidation.cxx` | validation of HF MC distributions -`o2-analysis-task-qa-pid-rejection` | `taskQaPidRejection.cxx` | PID selection performance `o2-analysis-hf-task-sel-optimisation` | `taskSelOptimisation.cxx` | preselection optimisation `o2-analysis-hf-refit-pv-dummy` | `refitPvDummy.cxx` | creation of a dummy table with primary-vertex position (for converted data) -### Tree creation +### Postprocessing scripts and macros -Candidate tables and other related derived tables are exported to disk as ROOT trees for -post-processing with external tools, e.g. for optimisation with Machine Learning techniques. +Python scripts and ROOT macros which process the O2Physics output files. +In general, Python scripts are preferred over ROOT macros. -Workflow | File | Type -------------------------------------------------|-------------------------------|---------------------------------------------------------------------- -`o2-analysis-hf-tree-creator-d0-to-k-pi` | `treeCreatorD0ToKPi.cxx` | D0(bar) → π± K∓ -`o2-analysis-hf-tree-creator-lc-to-p-k-pi` | `treeCreatorLcToPKPi.cxx` | Λc± → p(bar) K∓ π± -`o2-analysis-hf-tree-creator-x-to-jpsi-pi-pi` | `treeCreatorXToJpsiPiPi.cxx` | X(3872) → J/ψ π± π∓ -`o2-analysis-hf-tree-creator-xicc-to-p-k-pi-pi` | `treeCreatorXiccToPKPiPi.cxx` | Ξcc±± → Ξc± π± +Directories: [`PWGHF/D2H/Macros`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/D2H/Macros) ## Contribute @@ -181,13 +176,44 @@ Workflow | File - Follow the [O2 coding guidelines](https://github.com/AliceO2Group/CodingGuidelines) (especially the [naming](https://rawgit.com/AliceO2Group/CodingGuidelines/master/naming_formatting.html) and [commenting](https://rawgit.com/AliceO2Group/CodingGuidelines/master/comments_guidelines.html) rules). -- Sort O2Physics `#include`s alphabetically and keep `PWGHF/...` at the end. +- Respect the alphabetic order and groups in `CMakeLists.txt` when adding a new workflow. +- Link only necessary libraries in `CMakeLists.txt`. +- Avoid code duplication and reuse existing code (e.g. `RecoDecay`, table columns, constants). +- Define variables for repeatedly used objects (histogram types, axes, strings, calculated values). +- Explicitly state when using the `std` namespace (e.g. `std::abs`, `std::array`, `std::vector`). +- Do not use ROOT features unnecessarily (e.g. `TMath::Abs` → `std::abs`, `Double_t` → `double`). + - Use of macros for [bit manipulations](https://root.cern/doc/master/Rtypes_8h_source.html#l00083) (`BIT`, `SETBIT`, `TESTBIT`, `CLRBIT`) is encouraged. +- Do not use `M_PI`. Instead, use `PI`, `TwoPI`, `PIHalf`, `PIThird`, `PIQuarter` from the `o2::constants::math` namespace. +- Use `LOG`, `LOGF`, `LOGP` macros for logging (instead of `Printf`, `printf`, `std::cout`). + - Use the right logging level: + - `debug` for technical information useful for debugging and development, + - `info` for information about what the code is doing that is useful to report at every execution, + - `warn` for conditions that are likely to affect the expected behaviour of the code, + - `error` for problems that lead to an unwanted behaviour of the code, + - `fatal` for critical problems that make further running of the code impossible or useless. +- Include only needed headers but do not rely on implicitly included headers. +- Organise `#include`s into groups (separated by a blank line) in the following order: + - C++ + - other external headers + - ROOT + - O2 + - O2Physics + - PWG other than HF + - PWGHF + - Put PAG headers after the common ones. +- Sort `#include`s alphabetically within a group. +- Avoid using hard-coded PDG codes. Use their `enum` names instead + (from [`PDG_t`](https://root.cern/doc/master/TPDGCode_8h.html) or + [`o2::constants::physics::Pdg`](https://github.com/AliceO2Group/AliceO2/blob/dev/Common/Constants/include/CommonConstants/PhysicsConstants.h)). + See also [Magic numbers](https://rawgit.com/AliceO2Group/CodingGuidelines/master/coding_guidelines.html?showone=Magic_numbers#Magic_numbers). +- Use `Type const&` for table subscriptions in function arguments. +- Declare iterators in range-based `for` loops over tables with `const auto&`. - Test your code before making a pull request. - - Propagate your changes into the Run3Analysisvalidation configuration. - - Check that your branch compiles. + - Check that your branch compiles without warnings. + - Propagate your changes into the [Run3Analysisvalidation](https://github.com/AliceO2Group/Run3Analysisvalidation/tree/master/codeHF#add-a-new-workflow) configuration. - Check that your code works and runs without errors and warnings. - Make sure your code is compatible with the expected input (Run 2/3/5, real/MC data, p–p/Pb–Pb). - - Check that your changes do not alter unexpectedly the control plots produced by the validation framework. + - Check that your changes do not alter unexpectedly the control plots produced by the [validation framework](https://github.com/AliceO2Group/Run3Analysisvalidation/tree/master/codeHF#run-the-example). - Make sure your tasks can be fully configured from Run3Analysisvalidation and AliHyperloop. #### `struct` members @@ -205,13 +231,16 @@ Organising the code in a well defined structure makes it easier to navigate thro - other members (constants, objects) - `using` declarations - `Filter` + - `Preslice` - `Partition` - `ConfigurableAxis` - `AxisSpec` - `HistogramRegistry` - output declarations (`OutputObj`,...) - `init` function + - helper functions - `process` function(s) + - Put one process function argument per line. - `PROCESS_SWITCH` follows immediately after the function definition. ### Naming conventions @@ -237,7 +266,8 @@ Organising the code in a well defined structure makes it easier to navigate thro - `RecBg` - reconstruction level quantity of a reconstructed background candidate The names of the source file, the executable and the task(s) should match.
-Note: The device name of a task is automatically generated from the name of the corresponding `struct` by replacing uppercase letters with lowercase letters preceded with a hyphen unless defined explicitly using `TaskName`, which should be avoided if not necessary.
+Note: The device name of a task is automatically generated from the name of the corresponding `struct` by replacing uppercase letters with lowercase letters preceded with a hyphen. +The device name can be explicitly defined using `TaskName` only when several instances of a templated task need to be defined.
Example: - source file name: `taskXY.cxx` @@ -245,27 +275,11 @@ Example: - main task (`struct`) name: `HfTaskXY` (results in the generated device name `hf-task-x-y`) - auxiliary-task name: `HfTaskXY` (results in the generated device name `hf-task-x-y-`)
-### Git
-
-- If your changes consist of several independent steps, keep them separate in several commits.
-- Give your commits meaningful titles.
- - If needed, add more details in the commit message (separated by a blank line from the commit title).
-- Keep your feature branch up to date with the upstream main branch (`git pull --rebase upstream master`).
-
### Pull requests (PR)
- Update your branch and test it before creating a PR.
-- Create one PR per feature (i.e. do not mix big unrelated code changes).
- Give your PR a short meaningful title.
- Add the “PWGHF: ” prefix in the title of your PR. (It helps to search for PWGHF-related PRs in the commit history of the main branch.)
- Note: If your PR has only one commit, add the prefix also in the commit title (because that is the title that will appear in the history after merging, unless the person merging the PR changes it by hand).
- Give further useful details about your changes in the PR description.
- Add links to all related PRs (e.g. O2Physics, O2, AliPhysics, Run3Analysisvalidation) in the PR description.
-
-#### PR review
-
-- When you implement changes during the review, push them into your branch as new separate commits with meaningful titles.
-- Do not amend, squash or rebase existing commits in the PR. It would break the links between the code and the review comments.
- - If you need to update your branch with the changes in the main branch while the PR is under review, use `git merge upstream/master` (instead of `rebase`) to preserve the commit history.
-- Fix formatting issues by merging the PRs created automatically by the CI tests in your fork repository.
-- If you need more time to implement further changes in your PR, convert it to a draft to avoid unnecessary build tests and mark it as ready for review again when you're done.
diff --git a/docs/advanced-specifics/pwgje.md b/docs/advanced-specifics/pwgje.md
index 6698eef5..a2c7a4aa 100644
--- a/docs/advanced-specifics/pwgje.md
+++ b/docs/advanced-specifics/pwgje.md
@@ -1,5 +1,5 @@
---
-sort: 7
+sort: 8
title: PWG-JE
---
diff --git a/docs/advanced-specifics/pwglf.md b/docs/advanced-specifics/pwglf.md
index c7bd96dc..8d3ce24c 100644
--- a/docs/advanced-specifics/pwglf.md
+++ b/docs/advanced-specifics/pwglf.md
@@ -1,5 +1,5 @@
---
-sort: 8
+sort: 9
title: PWGLF
---
@@ -7,7 +7,46 @@ title: PWGLF
## Get started
-## Contact
+A number of tasks are included in `O2Physics` at the moment and can be consulted in the codebase.
+
+## Strangeness building
+
+In many analyses - not only PWG-LF exclusively - V0s and cascades are required. The new O2Physics data format stores only track index pairs or triplets for these objects, and all analysis-related properties have to be constructed from these indices. In order to take care of that centrally, `strangeness builders` are provided. They are:
+
+* `lambdakzerobuilder`: this task takes track index pairs and constructs the analysis information related to the V0, which can then be queried conveniently from the `V0Data` table.
+* `cascadebuilder`: this task takes track index triples and constructs the analysis information related to cascades, which can then be queried conveniently from the `CascData` table.
+
+Optionally, both builders can also produce covariance matrices (`V0Covs` or `CascCovs`) that are particularly useful to reconstruct decay chains that involve weakly decaying particles.
+
+The logical elements in these two tasks are outlined in the figure below:
+
+ nSigmaForTimeCompat{"nSigmaForTimeCompat", 4.f, "number of sigmas for time compatibility"};
+Configurable timeMargin{"timeMargin", 0.f, "time margin in ns added to uncertainty because of uncalibrated TPC"};
+Configurable includeUnassigned{"includeUnassigned", false, "consider also tracks which are not assigned to any collision"};
+Configurable fillTableOfCollIdsPerTrack{"fillTableOfCollIdsPerTrack", false, "fill additional table with vector of collision ids per track"};
+Configurable bcWindowForOneSigma{"bcWindowForOneSigma", 115, "BC window to be multiplied by the number of sigmas to define maximum window to be considered"};
+```
+
+Definition of the configurables:
+
+`float nSigmaForTimeCompat` : in how many sigmas we want to match the collision and the track, with
+
+- $$\sigma$$ = RMS of gaussian-like time resolutions of track and collision, for tracks with a gaussian-like time resolution, and
+- $$\sigma$$= gaussian standard deviation of the collision time for tracks with box-like errors
+
+`float timeMargin` the time margin in ns added to the uncertainty on the collision time because of uncalibrated TPC
+
+`bool includeUnassigned` if set to kTRUE, the tracks which were assigned to no collision in AO2D files are also reprocessed, meaning we try again to associate these tracks to collisions
+
+`bool fillTableOfCollIdsPerTrack` if set to kTRUE, a table is filled containing for each track a list of the collision global indexes it can be time-associated to. This table can then be joined with the track table and allows further selections on the different compatible collisions.
+
+`int bcWindowForOneSigma` sets the BC window around which we look for possible compatible collisions for one track. Needs to be greater than half of the track time window in case of tracks with box-like errors. It has been tuned to 115BC for MFT tracks with a ROF length of 198BC , which is 1.16$$\times \frac{ROF_{length}}{2}$$
+One could then apply conservatively a factor 1.3 for higher ROF lengths.
+
+## Description of the collision association procedure
+
+[CollisionAssociation.h](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/CollisionAssociation.h) loops over each track, and for each track it loops over all collisions $$coll$$. For efficiency purposes, a hard cut is applied if the collision is too far (in time) from the track.
+
+Let's define $$BC_{track}$$ the BC of the middle of the readout window of the track, and $$BC_{coll}$$ the BC of the collision $$coll$$.
+
+In the AO2D files, $$BC_{track}$$ = `track.collision().bc() + track.trackTime() / o2::constants::lhc::LHCBunchSpacingNS;`
+
+The cut applied on the BC difference $$\lvert BC_{track}-$BC_{coll} \rvert$$
+is the following:
+
+$$\lvert BC_{track}-$BC_{coll} \rvert$$ < `bcWindowForOneSigma * nSigmaForTimeCompat + timeMargin / o2::constants::lhc::LHCBunchSpacingNS;`
+
+With `bcWindowForOneSigma`, `nSigmaForTimeCompat` and `timeMargin` being configurable variables.
+
+These variables must be cautiously configured to avoid eliminating possible time-compatible collisions with the track, and to avoid looping on numerous collisions that are very far from the track in time.
+
+If $$coll$$ passes this cut, then a stricter cut on the time difference between the collision and the track is applied, as will be described below.
+
+The cut is different for tracks which come from detectors with readout windows and for detectors that detect track with a gaussian-like time precision.
+
+For detectors that collect tracks in readout windows such as the ITS and the MFT, $$t_{track}$$ is the middle of the track readout window in $$ns$$. Its associated time uncertainty is $$\sigma_{track}=\frac{\text{readout window duration}}{2}$$. $$t_{track}$$ is then associated to a box-like time error, and meaning that the track crossed the detector in the time range $$[t_{track}-\sigma_{track}, t_{track}+\sigma_{track}]$$
+
+ name = std::nullopt)
```
-They differ in the way the axis bins are defined. In the first version a vector of bin edges is provided, which allows for bins of different widths, whereas in the second case the edges of the equally wide bins are computed with the provided number of bins and the range of the axis, defined by binMin and binMax.
+They differ in the way the axis bins are defined. In the first version a vector of bin edges is provided, which allows bins of different widths, whereas in the second case the edges of the equally wide bins are computed with the provided number of bins and the range of the axis, defined by binMin and binMax.
-By-the-way, there is in fact a third version of the AxisSpec constructor, which is similar to the first version, but takes as first argument a ConfigurableAxis (= [Configurable](#configurables)<std::vector<double>>) instead of a std::vector<double>.
+By-the-way, there is in fact a third version of the AxisSpec constructor, which is similar to the first version, but takes as first argument a ConfigurableAxis (= [Configurable](../basics-usage/HelperTasks.md#configurables)<std::vector<double>>) instead of a std::vector<double>.
## Adding histograms
-A HistogramRegistry can be created together with the histograms it contains. It can however also be created empty and the histograms can be added later with the add method of which there a three versions.
+A HistogramRegistry can be created together with the histograms it contains. It can however also be created empty and the histograms can be added later with the add method of which there are three versions.
```cpp
void add(const HistogramSpec& histSpec);
@@ -193,5 +197,4 @@ std::shared_ptr& get(const H& histName)
Again HIST("histname") must be provided as argument to get the histogram with name = histname.
Practical examples of histogram manipulations in O2 can be found in the
-tutorials [Histograms](../tutorials/histograms.md) and [Histogram
-Registry](../tutorials/histogramRegistry.md).
+tutorials [Histograms](../tutorials/histograms.md) and [Histogram Registry](../tutorials/histogramRegistry.md).
diff --git a/docs/basics-tasks/CombiningData.md b/docs/basics-tasks/CombiningData.md
index ba76a6a4..6c2a38ae 100644
--- a/docs/basics-tasks/CombiningData.md
+++ b/docs/basics-tasks/CombiningData.md
@@ -168,6 +168,12 @@ combinations(combinationPolicy)
You can see some combinations examples in the tracksCombinations.cxx tutorial.
+```warning
+The tracks in dataset might be implicitly ordered. As a result, for example, you can observe slight asymmetries in same-event 2-particle correlations obtained with `StrictlyUpperIndexPolicy`. The recommended solutions are:
+1. Randomly swap tracks in pairs or
+2. Use `FullIndexPolicy` and apply additional condition to exclude pairs with the same element repeated ((0, 0), (1, 1), and so on). At the end, you need to apply proper statistic corrections in your analysis, as you count each unique pair twice.
+```
+
## Weighted combinations
You might need to calculate weights for your event mixing. You can get useful variables:
diff --git a/docs/basics-tasks/FilteringPartitioning.md b/docs/basics-tasks/FilteringPartitioning.md
index 78f18cd2..d04fa885 100644
--- a/docs/basics-tasks/FilteringPartitioning.md
+++ b/docs/basics-tasks/FilteringPartitioning.md
@@ -23,7 +23,9 @@ filters upfront you can not only simplify your code, but allow the framework to
optimize the processing. To do so, we provide two helpers: `Filter` and
`Partition`.
-*Note: Filters cannot be used on dynamic columns.*
+```note
+Filters cannot be used on dynamic columns.
+```
## Upfront filtering
@@ -32,34 +34,65 @@ properties passes a certain criteria. This can be specified with the `Filter` he
```cpp
struct MyTask : AnalysisTask {
- Filter ptFilter = track::pt > 1;
+ Filter ptFilter = track::pt > 1.f;
- void process(Tracks const &filteredTracks) {
+ void process(soa::Filtered const &filteredTracks) {
for (auto& track : filteredTracks) {
}
}
};
```
-filteredTracks will contain only the tracks in the table which pass the condition `track::pt > 1`.
-
-You can specify multiple filters which will be applied in a sequence effectively resulting in the intersection of all them.
+filteredTracks will contain only the tracks in the table which pass the condition `track::pt > 1.f`.
+
+Filter is automatically associated with a compatible table, i.e. table that has all the columns that are present in the filter expression.
+It is currently impossible to have a filter that uses columns from more than one table.
+If there are several filters declared, that are compatible with a single table, they are combined with logical "and".
+
+### Expressions
+`Filters` and `Partitions` are defined using `expressions`, as in the example above, which are C++ expressions that can contain _columns_, numerical and boolean _constants_, single-valued _configurables_, a limited set of special _functions_ and _branching_ conditions. The expressions are compiled on-the-fly to be applied and therefore require _explicit_ types to be used. For example in the expression `track::pt > 1.f` the numerical constant is marked to be `float`, while a simple `1` would be parsed as `int` and `1.` would be parsed as `double`.
+
+`Filters` and `Partitions` require the expression result to be `boolean`.
+
+The following funcitons and operations are permitted in expressions. Each `expr1` and `expr2` can be a single column, constant, configurable, condition, or a valid expression. Previously defined filters can also be used by name. Parentheses can be used as usual.
+
+| Operation | Syntax | Description |
+|:----------|:----------|:----------|
+| Logical "and" | `expr1 && expr2` | logical multiplication of two expressions (both boolean) |
+| Logical "or" | `expr1 \|\| expr2` | logical addition of two expressions (bothboolean) |
+| Addition | `expr1 + expr2` | Addition of two expressions (compatible types) |
+| Subtraction | `expr1 - expr2` | Subtraction of two expressions (compatible types) |
+| Division | `expr1 / expr2` | Division of two expressions (compatibel types) |
+| Multiplication | `expr1 * expr2` | Multiplication of two expressions (compatible types) |
+| Bitwise "and" | `expr1 & expr2` | Bitwise logical multiplication (equally-sized integer types) |
+| Bitwise "or" | `expr1 \| expr2` | Bitwise logical addition (equally-sized integer types) |
+| Bitwise "xor" | `expr1 ^ expr2` | Bitwise exclusive logical multiplication (equally-sized integer types) |
+| Less than | `expr1 < expr2` | Comparison (compatible types) |
+| Less than or equal | `expr1 <= expr2` | -- |
+| Greater than | `expr1 > expr2` | -- |
+| Greater than or equal | `expr1 >= expr2` | -- |
+| Equal | `expr1 == expr2` | -- |
+| Not equal | `expr1 != expr2` | -- |
+| Atan2 | `natan2(expr1, expr2)` | 2-argument arctangent function |
+| Power | `npow(expr, constant)` | Exponentiation |
+| Square root | `nsqrt(expr)` | Square root function |
+| Exponent | `nexp(expr)` | Exponent function |
+| Logarithm | `nlog(expr)` | Natural logarithm function |
+| Base-10 logarithm | `nlog10(expr)` | Base-10 logarithm function |
+| Sine | `nsin(expr)` | Sine function |
+| Cosine | `ncos(expr)` | Cosine function |
+| Tangent | `ntan(expr)` | Tangent function |
+| Arcsine | `nasin(expr)` | Arcsine function |
+| Arccosine | `nacos(expr)` | Arccosine function |
+| Arctangent | `natan(expr)` | Arctangent function |
+| Absolute value | `nabs(expr)` | Absolute value function |
+| Rounding | `nround(expr)` | Rounding function |
+| Bitwise "not" | `bitwise_not(expr)` | Bitwise logical "not" (integers) |
+| Branching condition | `ifnode(expr_condition, expr_if_true, expr_if_false)` | Conditional expression, depending if the `expr_condition` is true or false, the result of this expression is either `expr_if_true` or `expr_if_false` |
+
+Note that while normal function can be used in expressions, they are **evaluated on construction** so they are equivalent to numerical constants. All the specially declared functions that can act on `expressions` start with `n`.
-You can also specify filters on associated quantities:
-```cpp
-struct MyTask : AnalysisTask {
- Filter collisionFilter = max(track::pt) > 1;
-
- void process(Collisions const &filteredCollisions) {
- for (auto& collision: filteredCollisions) {
- ...
- }
- }
-};
-```
-
-will process all the collisions which have at least one track with `pt > 1`.
## Partitioning your inputs
@@ -73,39 +106,57 @@ struct MyTask : AnalysisTask {
Partition rightTracks = track::eta >= 0;
void process(Tracks const &tracks) {
- for (auto& left : leftTracks(tracks)) {
- for (auto& right : rightTracks(tracks)) {
+ for (auto& left : leftTracks) {
+ for (auto& right : rightTracks) {
...
}
}
+ for (auto& track : tracks) {
+ ...
+ }
}
};
```
-i.e. `Filter` is applied to the objects before passing them to the `process` method, while `Select` objects can be used to do further reduction inside the `process` method itself.
+`Filter` is applied to the objects before passing them to the `process` method, while `Partitions` exist independently.
## Filtering and partitioning together
-Of course it should be possible to filter and partition data in the same task. The way this works is that multiple `Filter`s are logically ANDed together and then they will get anded with the OR of all the `Select` specified selections.
+It is possible to use filters and partition data in the same task. Filters are applied as usual, combined with logical "and", therefore `tracks` table will only have entries that satisfy the filter conditions. The partitions, however, are _independent_ and _not grouped_ (by collision, in this example).
-## Configuring filters
+One can also define a partition _over a filtered type_, `Partition> part = nabs(track::eta) < 1.f`. Doing this will put the partition selection on top of whatever filter selections are also present in the same task.
+```cpp
+using namespace o2::aod;
-One of the features of the current framework is the ability to customize on the fly cuts and selection. The idea is to allow that by having a `configurable("mnemonic-name-of-the-parameter")` helper which can be used to refer to configurable options. The previous example will then become:
+using MyCompleteTracks = soa::Join;
-```cpp
-struct MyTask : AnalysisTask {
- Filter collisionFilter = max(track::pt) > configurable("my-pt-cut");
+struct partandfiltexample {
+ Partition leftTracks = track::eta < 0;
+ Partition rightTracks = track::eta >= 0;
+ Filter etaFilter = nabs(track::eta) < 0.5f;
+ Filter trackQuality = track::tpcNClsFindable - track::tpcNClsFindableMinusCrossedRows >= 70;
+ Filter trackDCA = nabs(track::dcaXY) <= .2;
- void process(Collisions const &filteredCollisions) {
- for (auto& collision: filteredCollisions) {
+ void process(Collision const& collision, soa::Filtered const& tracks)
+ {
...
- }
}
};
```
-```todo
-- Complete list of methods related to filters and partitions
+## Configuring filters
+
+One of the features of the current framework is the ability to customize on the fly cuts and selection. Single-valued configurabled can be used in filter expressions directly, with some caveats. Configurables are defined to be implicitly convertable to their underlying type, however you do not want that to happen in your filter expressions as it would substitute its default value. It is possible to use the `.node()` method of the configurable in the expression, to ensure that it creates a placeholder node.
+
+```cpp
+struct MyTask : AnalysisTask {
+ Configurable myPtCut{"my-pt-cut", 10.f, "pt cut"};
+ Filter trackFilter = track::pt >= myPtCut;
+
+ void process(Collision const& collision, soa::Filtered const& filteredTracks) {
+
+ }
+};
```
-See also tutorials [Data Selection](../tutorials/dataSelection).
+See also tutorials [Data Selection](../tutorials/dataSelection.md).
diff --git a/docs/basics-tasks/IntroductionTables.md b/docs/basics-tasks/IntroductionTables.md
index 354eeb84..65b2a3d1 100644
--- a/docs/basics-tasks/IntroductionTables.md
+++ b/docs/basics-tasks/IntroductionTables.md
@@ -22,11 +22,11 @@ For **each** index in a table, there is a method to get the corresponding object
```
```note
-Be aware that tables can be [joined](../framework/framework.md#processing-related-tables) and be [extended](../framework/framework.md#expression-columns) with extra colums.
+Be aware that tables can be [joined](../basics-task/SubscribingToData.md#processing-related-tables) and be [extended](../tutorials/extendedTables.md) with extra colums.
```
In order to process the data, analysis task objects have to be written and have to subscribe to tables - i.e., they
have to tell the framework that a certain table is of interest and will be processed by the task.
-In what folows, we will explain the basics regarding analysis tasks and the subscription to data.
+In what follows, we will explain the basics regarding analysis tasks and the subscription to data.
If you are interested in a reference guide that covers all the basic content of the tables that
-are currently in O2Physics, please refer to the automatically generated [Appendix: Data model reference](../09-appendix-fulldatatables/).
+are currently in O2Physics, please refer to the automatically generated [Appendix: Data model reference](../datamodel/README.md).
diff --git a/docs/basics-tasks/SubscribingToData.md b/docs/basics-tasks/SubscribingToData.md
index 8fb371ae..9e7c1007 100644
--- a/docs/basics-tasks/SubscribingToData.md
+++ b/docs/basics-tasks/SubscribingToData.md
@@ -77,7 +77,7 @@ This means that each subsequent argument is associated to all the one preceding
## Processing related tables
-For performance reasons, sometimes it's a good idea to split data in separate tables, so that once can request only the subset which is required for a given task. For example, so far the track related information is split in three tables: `Tracks`, `TracksCov`, `TracksExtra`.
+For performance reasons, sometimes it's a good idea to split data in separate tables, so that one can request only the subset which is required for a given task. For example, so far the track related information is split in three tables: `Tracks`, `TracksCov`, `TracksExtra`.
However you might need to get all the information at once. This can be done by asking for a `Join` table in the process method:
diff --git a/docs/basics-usage/HelperTasks.md b/docs/basics-usage/HelperTasks.md
index 409519d3..ef793b38 100644
--- a/docs/basics-usage/HelperTasks.md
+++ b/docs/basics-usage/HelperTasks.md
@@ -5,11 +5,20 @@ title: Helper tasks
# Helper tasks
+Table of contents:
+
+* [Timestamp](#timestamp)
+* [Event selection](#event-selection)
+* [Multiplicity and centrality selection in O2](#multiplicity-and-centrality-selection-in-o2)
+* [Particle identification (PID)](#particle-identification-pid)
+* [Track Selection](#track-selection)
+* [Track Propagation](#track-propagation)
+
## Timestamp
-The timestamp task is needed to fill the table [Timestamps](../datamodel/helperTaskTables.html#o2-analysis-timestamp). Timestamp contains the time of a bunch crossing since the start of the run. This time is often needed to retrieve objects in the CCDB (see Tutorial [CCDB](../tutorials/workingWithCCDB.html#ccdb)).
+The timestamp task is needed to fill the table with timestamps. Timestamp contains the time of a bunch crossing since the start of the run. This time is often needed to retrieve objects in the CCDB (see Tutorial [CCDB](https://aliceo2group.github.io/analysis-framework/docs/tutorials/workingWithCCDB.html)).
-Since the Timestamps table has an entry per bunch crossing it can be joined with table BC. The join is defined by o2::aod::BCsWithTimestamps (see list of defined [joins and iterators](../datamodel/joinsAndIterators.html#list-of-defined-joins-and-iterators)).
+Since the Timestamps table has an entry per bunch crossing it can be joined with table BC. The join is defined by o2::aod::BCsWithTimestamps (see list of defined [joins and iterators](https://aliceo2group.github.io/analysis-framework/docs/datamodel/joinsAndIterators.html#list-of-joins-and-iterators)).
## Event selection
@@ -70,7 +79,7 @@ In general, one has to follow the following steps:
* check if your trigger alias is fired if you run over Run1 or Run2 data (or future triggered Run3 data):
``` c++
- if (!col.alias()[kINT7]) {
+ if (!col.alias_bit(kINT7)) {
return;
}
```
@@ -105,6 +114,8 @@ In general, one has to follow the following steps:
_o2-analysis-timestamp_ task [`Common/TableProducer/timestamp.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/timestamp.cxx) is required to create per-event timestamps necessary to access relevant CCDB objects in the event selection task.
+ _o2-analysis-zdc-converter_ and _o2-analysis-collision-converter_ might be also necessary for old datasets to account for changes in the data model.
+
### Trigger aliases
Direct selection on trigger class names in O2 is rather complicated. In contrast to Run 2 AODs, there is no way to get the list of fired classes in a string-like format. Instead one has to check bits corresponding to trigger class ids either in ```triggerMask``` column in ```BCs``` table or ```triggerMaskNext50``` in ```Run2BCInfos``` table (for Run 2 if the trigger class id is larger than 50). This approach is complicated since trigger class ids for the same class vary from run to run.
@@ -115,20 +126,39 @@ To simplify trigger checks, we use trigger alias approach. Fired trigger classes
* alias bits do not change from run to run in contrast to trigger class ids
The list of available trigger alises can be found in [`Common/CCDB/TriggerAliases.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/CCDB/TriggerAliases.h). The mapping between trigger classes (and their indices) and trigger aliases is stored in [`CCDB`](http://alice-ccdb.cern.ch/browse/EventSelection/TriggerAliases) run-by-run in dedicated _TriggerAliases_ objects.
-Current mapping can be checked in [upload_trigger_aliases.C](https://github.com/AliceO2Group/O2Physics/blob/master/Common/CCDB/macros/upload_trigger_aliases.C#L24) macro:
+Current mapping can be checked in [upload_trigger_aliases.C](https://github.com/AliceO2Group/O2Physics/blob/master/Common/CCDB/macros/upload_trigger_aliases.C#L24) macro for Run2:
``` c++
- mAliases[kINT7] = "CINT7-B-NOPF-CENT,CV0L7-B-NOPF-CENT,CINT7-B-NOPF-CENTNOTRD,CINT7ZAC-B-NOPF-CENTNOPMD";
- mAliases[kEMC7] = "CEMC7-B-NOPF-CENTNOPMD,CDMC7-B-NOPF-CENTNOPMD";
+ mAliases[kINT7] = "CINT7-B-NOPF-CENT,CINT7-B-NOPF-FAST,CV0L7-B-NOPF-CENT,CINT7-B-NOPF-CENTNOTRD,CINT7ZAC-B-NOPF-CENTNOPMD,CINT7-B-NOPF-ALLNOTRD,CINT7-I-NOPF-ALLNOTRD,CINT7-S-NOPF-ALLNOTRD,CMBAC-B-NOPF-ALL,CMBACS2-B-NOPF-ALLNOTRD,CMBACS2-B-NOPF-ALL";
+ mAliases[kEMC7] = "CEMC7-B-NOPF-CENTNOPMD,CEMC7-B-NOPF-CENT,CEMC7-B-NOPF-CENTNOTRD,CEMC7-B-NOPF-ALLNOTRD,CEMC7-S-NOPF-ALLNOTRD";
mAliases[kINT7inMUON] = "CINT7-B-NOPF-MUFAST";
- mAliases[kMuonSingleLowPt7] = "CMSL7-B-NOPF-MUFAST";
- mAliases[kMuonUnlikeLowPt7] = "CMUL7-B-NOPF-MUFAST";
- mAliases[kMuonLikeLowPt7] = "CMLL7-B-NOPF-MUFAST";
- mAliases[kMuonSingleHighPt7] = "CMSH7-B-NOPF-MUFAST";
+ mAliases[kMuonSingleLowPt7] = "CMSL7-B-NOPF-MUFAST,CMSL7-B-NOPF-MUON,CMSL7-S-NOPF-MUON,CMSL7-SC-NOPF-MUON,CPBI1MSL-B-NOPF-MUON,CMUS7-B-NOPF-MUON";
+ mAliases[kMuonUnlikeLowPt7] = "CMUL7-B-NOPF-MUFAST,CMUL7-B-NOPF-MUON,CMUL7-S-NOPF-MUON,CMUL7-S-NOPF-ALLNOTRD,CPBI1MUL-B-NOPF-MUON,CMUU7-B-NOPF-MUON,CMUU7-B-NOPF-ALLNOTRD";
+ mAliases[kMuonLikeLowPt7] = "CMLL7-B-NOPF-MUFAST,CMLL7-B-NOPF-MUON,CMLL7-S-NOPF-MUON,CPBI1MLL-B-NOPF-MUON";
+ mAliases[kMuonSingleHighPt7] = "CMSH7-B-NOPF-MUFAST,CMSH7-B-NOPF-MUON,CMSH7-S-NOPF-MUON,CMSH7-S-NOPF-ALLNOTRD,CPBI1MSH-B-NOPF-MUON,CMUSH7-B-NOPF-MUON";
mAliases[kCUP8] = "CCUP8-B-NOPF-CENTNOTRD";
mAliases[kCUP9] = "CCUP9-B-NOPF-CENTNOTRD";
mAliases[kMUP10] = "CMUP10-B-NOPF-MUFAST";
mAliases[kMUP11] = "CMUP11-B-NOPF-MUFAST";
+ mAliases[kINT1] = "CINT1B-ABCE-NOPF-ALL,CINT1-B-NOPF-ALLNOTRD,CINT1-B-NOPF-ALLNOTRD";
+ mAliases[kUnbiased] = "CBEAMB-ABCE-NOPF-ALL,CBEAMB-B-NOPF-ALLNOTRD,CTRUE-B-NOPF-ALLNOTRD,CTRUE-S-NOPF-ALLNOTRD,CTRUE-B-NOPF-CENTNOTRD";
+ mAliases[kDMC7] = "CDMC7-B-NOPF-CENTNOPMD,CDMC7-B-NOPF-CENT,CDMC7-B-NOPF-CENTNOTRD,CDMC7-B-NOPF-ALLNOTRD";
+ mAliases[kEG1] = "CINT7EG1-B-NOPF-CENTNOPMD,CEMC7EG1-B-NOPF-CENT,CEMC7EG1-B-NOPF-CENTNOTRD,CEMC7EG1-B-NOPF-CENTNOPMD,CEMC7EG1-B-NOPF-ALLNOTRD,CEMC7EGA-B-NOPF-CENTNOTRD,CEMC7EGA-S-NOPF-CENTNOTRD,CEMC7EGA-S-NOPF-ALLNOTRD,CPBI2EGA-B-NOPF-CENTNOTRD";
+ mAliases[kEJ1] = "CINT7EJ1-B-NOPF-CENTNOTRD,CEMC7EJ1-B-NOPF-CENT,CEMC7EJ1-B-NOPF-CENTNOTRD,CEMC7EJ1-B-NOPF-CENTNOPMD,CEMC7EJ1-B-NOPF-ALLNOTRD,CEMC7EJE-B-NOPF-CENTNOTRD,CEMC7EJE-S-NOPF-CENTNOTRD,CEMC7EJE-S-NOPF-ALLNOTRD,CPBI2EJE-B-NOPF-CENTNOTRD";
+ mAliases[kEG2] = "CINT7EG2-B-NOPF-CENTNOPMD,CEMC7EG2-B-NOPF-CENT,CEMC7EG2-B-NOPF-CENTNOTRD,CEMC7EG2-B-NOPF-CENTNOPMD,CEMC7EG2-B-NOPF-ALLNOTRD,CEMC7EG2PER-B-NOPF-CENTNOPMD";
+ mAliases[kEJ2] = "CINT7EJ2-B-NOPF-CENTNOPMD,CEMC7EJ2-B-NOPF-CENT,CEMC7EJ2-B-NOPF-CENTNOTRD,CEMC7EJ2-B-NOPF-CENTNOPMD,CEMC7EJ2-B-NOPF-ALLNOTRD";
+ mAliases[kDG1] = "CINT7DG1-B-NOPF-CENTNOPMD,CDMC7DG1-B-NOPF-CENT,CDMC7DG1-B-NOPF-CENTNOTRD,CDMC7DG1-B-NOPF-CENTNOPMD";
+ mAliases[kDJ1] = "CINT7DJ1-B-NOPF-CENTNOPMD,CDMC7DJ1-B-NOPF-CENT,CDMC7DJ1-B-NOPF-CENTNOTRD,CDMC7DJ1-B-NOPF-CENTNOPMD";
+ mAliases[kDG2] = "CINT7DG2-B-NOPF-CENTNOPMD,CDMC7DG2-B-NOPF-CENT,CDMC7DG2-B-NOPF-CENTNOTRD,CDMC7DG2-B-NOPF-CENTNOPMD,CDMC7DG2PER-B-NOPF-CENTNOPMD";
+ mAliases[kDJ2] = "CINT7DJ2-B-NOPF-CENTNOPMD,CDMC7DJ2-B-NOPF-CENT,CDMC7DJ2-B-NOPF-CENTNOTRD,CDMC7DJ2-B-NOPF-CENTNOPMD";
+```
+
+and in [upload_trigger_aliases_run3.C](https://github.com/AliceO2Group/O2Physics/blob/master/Common/CCDB/macros/upload_trigger_aliases_run3.C#L25) for Run 3:
+
+``` c++
+ mAliases[kTVXinTRD] = "CMTVX-B-NOPF-TRD,minbias_TVX";
+ mAliases[kTVXinEMC] = "C0TVX-B-NOPF-EMC,minbias_TVX_L0";
+ mAliases[kTVXinPHOS] = "C0TVX-B-NOPF-PHSCPV,minbias_TVX_L0";
```
This list of trigger aliases and classes is not complete but it should be enough for tests in various PWGs. New trigger classes and aliases can be added upon request (contact Evgeny Kryshen).
@@ -139,33 +169,41 @@ Full list of event selection criteria can be found in [`Common/CCDB/EventSelecti
``` c++
enum EventSelectionFlags {
- kIsBBV0A = 0, // cell-averaged time in V0A in beam-beam window
- kIsBBV0C, // cell-averaged time in V0C in beam-beam window (for Run 2 only)
- kIsBBFDA, // cell-averaged time in FDA (or AD in Run2) in beam-beam window
- kIsBBFDC, // cell-averaged time in FDC (or AD in Run2) in beam-beam window
- kNoBGV0A, // cell-averaged time in V0A in beam-gas window
- kNoBGV0C, // cell-averaged time in V0C in beam-gas window (for Run 2 only)
- kNoBGFDA, // cell-averaged time in FDA (AD in Run2) in beam-gas window
- kNoBGFDC, // cell-averaged time in FDC (AD in Run2) in beam-gas window
- kIsBBT0A, // cell-averaged time in T0A in beam-beam window
- kIsBBT0C, // cell-averaged time in T0C in beam-beam window
- kIsBBZNA, // time in common ZNA channel in beam-beam window
- kIsBBZNC, // time in common ZNC channel in beam-beam window
- kIsBBZAC, // time in ZNA and ZNC in beam-beam window - circular cut in ZNA-ZNC plane
- kNoBGZNA, // time in common ZNA channel is outside of beam-gas window
- kNoBGZNC, // time in common ZNC channel is outside of beam-gas window
- kNoV0MOnVsOfPileup, // no out-of-bunch pileup according to online-vs-offline VOM correlation
- kNoSPDOnVsOfPileup, // no out-of-bunch pileup according to online-vs-offline SPD correlation
- kNoV0Casymmetry, // no beam-gas according to correlation of V0C multiplicities in V0C3 and V0C012
- kIsGoodTimeRange, // good time range
- kNoIncompleteDAQ, // complete event according to DAQ flags
- kNoTPCLaserWarmUp, // no TPC laser warm-up event (used in Run 1)
- kNoTPCHVdip, // no TPC HV dip
- kNoPileupFromSPD, // no pileup according to SPD vertexer
- kNoV0PFPileup, // no out-of-bunch pileup according to V0 past-future info
- kNoSPDClsVsTklBG, // no beam-gas according to cluster-vs-tracklet correlation
- kNoV0C012vsTklBG, // no beam-gas according to V0C012-vs-tracklet correlation
- kNsel // counter
+ kIsBBV0A = 0, // cell-averaged time in V0A in beam-beam window
+ kIsBBV0C, // cell-averaged time in V0C in beam-beam window (for Run 2 only)
+ kIsBBFDA, // cell-averaged time in FDA (or AD in Run2) in beam-beam window
+ kIsBBFDC, // cell-averaged time in FDC (or AD in Run2) in beam-beam window
+ kIsBBT0A, // cell-averaged time in T0A in beam-beam window
+ kIsBBT0C, // cell-averaged time in T0C in beam-beam window
+ kNoBGV0A, // cell-averaged time in V0A in beam-gas window
+ kNoBGV0C, // cell-averaged time in V0C in beam-gas window (for Run 2 only)
+ kNoBGFDA, // cell-averaged time in FDA (AD in Run2) in beam-gas window
+ kNoBGFDC, // cell-averaged time in FDC (AD in Run2) in beam-gas window
+ kNoBGT0A, // cell-averaged time in T0A in beam-gas window
+ kNoBGT0C, // cell-averaged time in T0C in beam-gas window
+ kIsBBZNA, // time in common ZNA channel in beam-beam window
+ kIsBBZNC, // time in common ZNC channel in beam-beam window
+ kIsBBZAC, // time in ZNA and ZNC in beam-beam window - circular cut in ZNA-ZNC plane
+ kNoBGZNA, // time in common ZNA channel is outside of beam-gas window
+ kNoBGZNC, // time in common ZNC channel is outside of beam-gas window
+ kNoV0MOnVsOfPileup, // no out-of-bunch pileup according to online-vs-offline VOM correlation
+ kNoSPDOnVsOfPileup, // no out-of-bunch pileup according to online-vs-offline SPD correlation
+ kNoV0Casymmetry, // no beam-gas according to correlation of V0C multiplicities in V0C3 and V0C012
+ kIsGoodTimeRange, // good time range
+ kNoIncompleteDAQ, // complete event according to DAQ flags
+ kNoTPCLaserWarmUp, // no TPC laser warm-up event (used in Run 1)
+ kNoTPCHVdip, // no TPC HV dip
+ kNoPileupFromSPD, // no pileup according to SPD vertexer
+ kNoV0PFPileup, // no out-of-bunch pileup according to V0 past-future info
+ kNoSPDClsVsTklBG, // no beam-gas according to cluster-vs-tracklet correlation
+ kNoV0C012vsTklBG, // no beam-gas according to V0C012-vs-tracklet correlation
+ kNoInconsistentVtx, // no inconsistency in SPD and Track vertices
+ kNoPileupInMultBins, // no pileup according to multiplicity-differential pileup checks
+ kNoPileupMV, // no pileup according to multi-vertexer
+ kNoPileupTPC, // no pileup in TPC
+ kIsTriggerTVX, // FT0 vertex (acceptable FT0C-FT0A time difference) at trigger level
+ kIsINT1, // SPDGFO >= 1 || V0A || V0C
+ kNsel // counter
};
```
@@ -178,7 +216,7 @@ Technically there are three types of criteria:
Decisions on inidividual selection criteria are stored in _selection_ array ```BcSels``` and ```EvSels``` tables. E.g. one can check if a given collision passed _kIsBBV0A_ selection:
``` c++
- bool isBBV0Apassed = col.selection()[evsel::kIsBBV0A];
+ bool isBBV0Apassed = col.selection_bit(evsel::kIsBBV0A);
```
### Event selection decisions
@@ -257,7 +295,7 @@ Selection mask _applySelection_ is obtained from CCDB in [eventSelection.cxx](ht
```
Then _sel7_ decision is constructed from active checks:
-[Common/TableProducer/eventSelection.cxx#L321](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/eventSelection.cxx#L321)
+[Common/TableProducer/eventSelection.cxx](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/eventSelection.cxx#L438)
``` c++
bool sel7 = 1;
@@ -270,8 +308,6 @@ Then _sel7_ decision is constructed from active checks:
One of the main goals of the event selection task in Run 3 is to find the original bunch crossing for each collision. The basic approach is to start from estimated collision bc and search for closest BC containing FT0 entries in a +/-4 sigma window where sigma corresponds to the estimated collision time resolution from ```col.collisionTimeRes()```. Implementation details can be found in [eventSelection.cxx#L348](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/eventSelection.cxx#L348).
-There is a possibility to set custom search window using _customDeltaBC_ configurable. At the moment we use _customDeltaBC_ set to 300 bunch crossings.
-
Users can access found bunch crossings and FT0 entries using _foundBC_ or _foundFT0_ indices stored in the _EvSels_ table:
``` c++
@@ -302,16 +338,10 @@ Event selection task supports several configurables:
Configurable muonSelection{"muonSelection", 0, "0 - barrel, 1 - muon selection with pileup cuts, 2 - muon selection without pileup cuts"};
```
-* _customDeltaBC_ allows to set custom search window for FIT-collision matching in Run 3, see [Found bunch crossings](#found-bunch-crossings) section.
-
- ``` c++
- Configurable customDeltaBC{"customDeltaBC", 300, "custom BC delta for FIT-collision matching"};
- ```
-
* _isMC_ allows to suppress several checks for Run 2 MC, see [Event selection decisions](#event-selection-decisions):
``` c++
- Configurable isMC{"isMC", 0, "0 - data, 1 - MC"};
+ Configurable isMC{"isMC", 0, "-1 - autoset, 0 - data, 1 - MC"};
```
Note that one has to enable _isRun2MC_ flag in the timestamp task in this case:
@@ -343,30 +373,29 @@ One can set other configurables in the json file. This json file has to be provi
* One has to apply offline selections in O2 explicitly in contrast to AliPhysics where these selections were applied together with trigger alias selection.
* EvSel table might be also useful in user tasks relying on beam-beam and beam-gas decisions in forward detectors, e.g. in UPC tasks.
-* Trigger class aliases for Run 3 are not available yet (pilot beam data taking was focused on continuous readout)
## Multiplicity and centrality selection in O2
-### Concept
+### 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 [`Analysis/Tasks/multiplicityTable.cxx`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/Tasks/multiplicityTable.cxx) stores relevant multiplicity values (V0A, V0C, ZNA, ZNC) and their dynamic sums (V0M) in [`Mults`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/DataModel/include/Analysis/Multiplicity.h) table joinable with _Collisions_ table.
-* _o2-analysis-multiplicity-qa_ task [`Analysis/Tasks/multiplicityQa.cxx`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/Tasks/multiplicityQa.cxx) creates multiplicity distributions in minimum bias triggers necessary for centrality calibration.
-* _o2-analysis-centrality-table_ task [`Analysis/Tasks/centralityTable.cxx`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/Tasks/centralityTable.cxx) takes multiplicity values from the [`Mults`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/DataModel/include/Analysis/Multiplicity.h) table and stores centrality values in [`Cents`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/DataModel/include/Analysis/Centrality.h) table joinable with _Collisions_ table. Relevant cumulative multiplicity distributions are stored in [CCDB](http://ccdb-test.cern.ch:8080/browse/Multiplicity/CumMultV0M). At the moment, centrality calibration objects are available only for LHC15o. The centrality calibration relies on 90% anchor points but doesn't take into account vertex dependence yet. The difference with AliPhysics centrality calibration doesn't exceed 0.5%.
-* _o2-analysis-centrality-qa_ task [`Analysis/Tasks/centralityQa.cxx`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/Tasks/centralityQa.cxx) creates centrality distributions for minimum bias triggers and can be used for control and QA purposes.
+* _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, see [here](evsel.md) for more details.
+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.
-### Usage in user tasks
+### Multiplicity selection usage in user tasks
-One can check _o2-analysis-centrality-qa_ task for example usage: [`Analysis/Tasks/centralityQa.cxx`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/Tasks/centralityQa.cxx). Usually, analysers perform event selection before the centrality selection therefore one has to consider the following steps:
+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/AliceO2/blob/dev/Analysis/DataModel/include/Analysis/EventSelection.h) and [`Centrality.h`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/DataModel/include/Analysis/Centrality.h) headers:
+* 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 "Analysis/EventSelection.h"
- #include "Analysis/Centrality.h"
+ #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:
@@ -378,7 +407,7 @@ One can check _o2-analysis-centrality-qa_ task for example usage: [`Analysis/Tas
* check if your trigger alias is fired if you run over Run1 or Run2 data (or future triggered Run3 data):
``` c++
- if (!col.alias()[kINT7])
+ if (!col.alias_bit(kINT7))
return;
```
@@ -404,26 +433,33 @@ One can check _o2-analysis-centrality-qa_ task for example usage: [`Analysis/Tas
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 [`Analysis/Tasks/timestamp.cxx`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/Tasks/timestamp.cxx) is required to create per-event timestamps necessary to access relevant CCDB objects in the event selection and/or centrality tasks.
+ _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.
-## Particle identification
+ _o2-analysis-zdc-converter_ and _o2-analysis-collision-converter_ might be also necessary for old datasets to account for changes in the data model.
-Here are described the PID working principles in O2 as well as how to get PID information (expected values, separation et cetera) in your task.
+## Particle identification (PID)
-### Introduction
+Table of contents:
-PID is handled in O2 via the reimplementation of base classes found in [`Common/Core/PID/`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/Core/PID).
+* [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)
-The parametrization of the expected detector response (e.g. signal, resolution, separation) is handled in the classes derived from [`Common/Core/PID/ParamBase.h`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/Core/PID/ParamBase.h).
-Examples of these derived classes can be found in [`PIDTOF.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/PID/PIDTOF.h), in this example the the TOF resolution response is implemented.
+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
-The interface between the detector and the Analysis Framework is fully enclosed in [`DetectorResponse.h`](https://github.com/AliceO2Group/O2Physics/tree/master/Common/Core/PID/DetectorResponse.h).
-Here are defined the tables for the PID.
+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.
+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 tasks
+### 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:
@@ -434,31 +470,38 @@ You can include it in your task with:
```
-In the process functions you can join the table to add the PID (per particle mass hypothesis) information to the track.
+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:
+* For the **TOF** PID as:
``` c++
- void process(aod::Collision const& collision, soa::Join const& tracks)
+ void process(soa::Join::iterator const& track) {
+ track.tofNSigmaEl();
+ }
```
-* For the TPC PID as:
+* For the **TPC** PID as:
``` c++
- void process(aod::Collision const& collision, soa::Join const& tracks)
+ void process(soa::Join::iterator const& track) {
+ track.tpcNSigmaEl();
+ }
```
-* For both TOF and TPC PID as:
+* For both TOF and TPC PID information as:
``` c++
- void process(aod::Collision const& collision, soa::Join const& tracks)
+ void process(soa::Join::iterator const& track) {
+ const float combNSigmaEl = std::sqrt( track.tofNSigmaEl() * track.tofNSigmaEl() + track.tpcNSigmaEl() * track.tpcNSigmaEl());
+ }
```
-### Task for PID spectra (and to fill PID tables!)
+### Task for TOF and TPC PID
-O2 tasks dedicated to the filling of the PID tables are called with
+**In short:** O2 tasks dedicated to the filling of the PID tables are called with
-* TOF PID Table
+* Filling TOF PID Table
``` bash
o2-analysis-pid-tof
@@ -470,45 +513,61 @@ O2 tasks dedicated to the filling of the PID tables are called with
o2-analysis-pid-tof-base
```
- This can be configured according to needs
+ 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.
-* TPC PID Table
+* 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-spectra-tof --aod-file AO2D.root -b | o2-analysis-pid-tof -b | o2-analysis-pid-tof-base -b
+ 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-spectra-tpc --aod-file AO2D.root -b | o2-analysis-pid-tpc -b
+ 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 with the option `--add-qa 1` when running locally or with the corresponding QA tasks as in:
+* 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 -b --add-qa 1
+ ... | o2-analysis-pid-tof-qa | ...
+ ```
+
+ For the **TPC** QA plots
- ... | o2-analysis-pid-tpc -b --add-qa 1
+ ``` bash
+ ... | o2-analysis-pid-tpc-qa | ...
```
+ Where by `...` we mean the other tasks in your workflow.
+
## Track Selection
The track selection in the O2 analysis framework is provided in form of a stand-alone workflow that you can run in front of your analysis:
-```
+``` bash
o2-analysis-trackselection | o2-analysis-myTask
```
@@ -585,7 +644,7 @@ void process(soa::FilteredT1.1 | 0.0105 * 0.035 / pT1.1 |
- | cluster requirement ITS | at least one hit in SPD (*) | no hit in SPD and hit in first SDD layer |
- | pT range | 0.1 - 1e10 | 0.1 - 1e10 |
- | η range | -0.8 - 0.8 | -0.8 - 0.8 |
+ | Cuts | globalTrack | globalTrackSDD |
+ |------------------------------------------------------|------------------------------------------------------------------------|----------------------------------------------|
+ | min number of crossed rows TPC | 70 | 70 |
+ | min ratio of crossed rows over findable clusters TPC | 0.8 | 0.8 |
+ | max chi2 per cluster TPC | 4.0 | 4.0 |
+ | max chi2 per cluster ITS | 36.0 | 36.0 |
+ | require TPC refit | true | true |
+ | require ITS refit | true | true |
+ | max DCA to vertex z | 2.0 | 2.0 |
+ | max DCA to vertex xy | 0.0105 * 0.035 / pT1.1 | 0.0105 * 0.035 / pT1.1 |
+ | cluster requirement ITS | Run 2 (Run 3): at least one hit in SPD (in 3 innermost ITS layers) [*] | no hit in SPD and hit in first SDD layer |
+ | pT range | 0.1 - 1e10 | 0.1 - 1e10 |
+ | η range | -0.8 - 0.8 | -0.8 - 0.8 |
+
+```note
+[*]
+
+_RUN2 data/MC analyses_ (`isRun3 == false`)
+The default set of global-track selections requires at least 1 hit between the two innermost ITS layers (function `getGlobalTrackSelection` in [`TrackSelectionDefaults.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/TrackSelectionDefaults.h)).
+This is a Run 1, 2 refuse when the SPD was equipped, and currently this is enabled ONLY for analyses on Run2 converted data (`isRun3 == false`).
+
+_RUN3 data/MC analyses_ (`isRun3 == true`)
+The same set of global-track selections, but with different ITS requirements for Run3 data are available in [`trackselection.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/trackselection.cxx). This is possible thanks to the `getGlobalTrackSelectionITSMatch` in [`TrackSelectionDefaults.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/TrackSelectionDefaults.h), which can be enabled with different ITS requirements via the integer configurable `itsMatching` in [`trackselection.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/trackselection.cxx). The available configurations are the following:
+
+* `itsMatching == 0`: at least one hit between the two innermost ITS layers (default for `isRun3 == false`).
+ IMPORTANT: in case `isRun3 == true`, then `itsMatching == 0` enables `itsMatching == 1` automatically (a WARNING is dumped at runtime);
+* `itsMatching == 1`: at least one hit among the three innermost ITS layers (`Run3ITSibAny`, default for `isRun3 == true`);
+* `itsMatching == 2`: at least one hit among all the ITS layers (`Run3ITSallAny`);
+* `itsMatching == 3`: one hit on all the ITS layers (`Run3ITSall7Layers`);
+```
The goal of the track selection task is to provide the most common selections for all analyses.
-If you really require a completely different set of tracks not covered by the standard filter bits, you can create your own TrackSelection object (see [`TrackSelection.h`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/Core/include/Analysis/TrackSelection.h) and [`TrackSelectionTables.cxx`](https://github.com/AliceO2Group/AliceO2/blob/dev/Analysis/Core/src/TrackSelection.cxx)) :
+If you really require a completely different set of tracks not covered by the standard filter bits, you can create your own TrackSelection object (see [`TrackSelectionTables.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/DataModel/TrackSelectionTables.h) and [`trackselection.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/trackselection.cxx)) :
``` c++
@@ -648,14 +724,7 @@ mySelection = myTrackSelection();
bool isSelected = mySelection.IsSelected(track)
```
-(*) The default set of global-track selections requires at least 1 hit between the two innermost ITS layers (function `getGlobalTrackSelection` in [`TrackSelectionDefaults.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/TrackSelectionDefaults.h)). This is a Run 1, 2 refuse when the SPD was equipped. The same set of global-track selections, but with different ITS requirements are available in [`trackselection.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/trackselection.cxx). This is possible thanks to the `getGlobalTrackSelectionITSMatch` in [`TrackSelectionDefaults.h`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/TrackSelectionDefaults.h), which can be enabled with different ITS requirements via the integer configurable `itsMatching` in [`trackselection.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/trackselection.cxx). The available configurations are the following:
-
-* `itsMatching == 0`: at least one hit between the two innermost ITS layers (default);
-* `itsMatching == 1`: at least one hit among the three innermost ITS layers (`Run3ITSibAny`);
-* `itsMatching == 2`: at least one hit among all the ITS layers (`Run3ITSallAny`);
-* `itsMatching == 3`: one hit on all the ITS layers (`Run3ITSall7Layers`);
-
-### Remarks
+### Remarks on track selection
Please note that this documentation only represents the status quo of the track selection implementation and many things can and will change.
In particular the cut values will most likely change with the 'new' detector in Run 3 and some of the legacy cuts will be removed or only available for converted Run 2 data.
@@ -683,3 +752,58 @@ The overall table flow is illustrated here:
+
+
+### TrackTuner
+The `TrackTuner` class ([Common/Tools/TrackTuner.h](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Tools/TrackTuner.h)) allows to smear the reconstructed track parameters.
+Such tool is primarely conceived to smear the parameters of tracks reconstructed in MC simulations according to the discrepancy between data and MC of the dcaXY and dcaZ.
+```note
+This task was called `improver-task` in the Run 2 jargon
+```
+The smearing is done on the `y`, `z` parameters of each reconstructed track in MC evaluated at the associated particle production point. The smearing is based on the discrepancy between resolution, mean and pull ratio of dcaXY, dcaZ w.r.t. primary vertex measured in data and MC.
+The performance of such parameters is evaluated vs. global-track pt and stored into `.root` files, which can be read from CCDB at runtime.
+
+An instance of the `TrackTuner` class is present as data-member in the `trackPropagation` workflow, and it can be enabled via
+```c++
+Configurable useTrackTuner{"useTrackTuner", false, "Apply Improver/DCA corrections to MC"};
+```
+```note
+The `TrackTuner` can be enabled only if the `processCovarianceMc` process function in the `trackPropagation` workflow is used
+```
+This object can be configured through the `Configurable trackTunerParams` in the `trackPropagation` workflow. This configuration `std::string` must define the following parameters:
+* `bool debugInfo`: flag to switch on/off some debug outputs
+* `bool updateTrackDCAs`: flag to switch on/off the smearing of the dcaXY, dcaZ
+* `bool updateTrackCovMat`: flag to enable the update of the track covariance matrix, propagating the scaling on the dca resolution
+* `bool updatePulls`: flag to enable the update of the track covariance matrix updating also the pulls (if `updateTrackCovMat == true`)
+* `std::string pathInputFile`: path to browse to find the correction file for the dca smearing
+* `std::string nameInputFile`: name of the correction file for the dca smearing
+* `bool isInputFileFromCCDB`: the `pathInputFile/nameInputFile` is searched in CCDB if this flag is `true`, otherwise in the local file system (debug purposes)
+* `bool usePvRefitCorrections`: if this flag is `true`, the track smearing is performed using mean, resolution and pulls parametrizations vs. pt of dcaXY, dcaZ calculated w.r.t. primary collision vertex refitted w/o the current track, if this was originally a PV contributor
+```note
+In pp collisions, one should use `usePvRefitCorrections == true`
+This is not relevant in Pb-Pb collisions.
+```
+* `std::string pathFileQoverPt`: path to browse to find the correction file for the `q/pt` smearing
+* `std::string nameFileQoverPt`: name of the correction file for the `q/pt` smearing
+* `bool updateCurvature`: flag to enable the update of the track curvature, i.e. `q/pt`, at the particle production point
+* `bool updateCurvatureIU`: flag to enable the update of the track curvature, i.e. `q/pt`, at the innermost update (IU) point
+* `float oneOverPtMC` (MC) and `float oneOverPtData` (data): the ratio `oneOverPtData/oneOverPtMC` defines the scaling factor to the `q/pt` residual to smear the track pt
+* `fillTrackTunerTable`: flag to enable the filling of a new table containing for each track the smeared `q/pt` at the IU point
+
+```note
+* The `TrackTuner` allows also to smear the `q/pt` if only one between `updateCurvature` and `updateCurvatureIU` is `true`
+* By default, the variables `oneOverPtData` and `oneOverPtMC` are initialized to `-1`
+* If at least one between`qOverPtMCq` and `OverPtData` is negative, the `q/pt` correction is done wuering the file from CCDB. Otherwise, the input values of `qOverPtMC` and `qOverPtData` are used to defined the factor `oneOverPtData/oneOverPtMC`, which is a constant factor flat in transverse momentum.
+```
+The string `trackTunerParams` must follow the format: `=|=` (see the default configuration [here](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/trackPropagation.cxx#L62) as reference).
+
+
+The dcaXY, dcaZ parametrization currently available are the following:
+* proxy for pp @ 13.6 TeV: [trackTuner_DataLHC23fPass1_McLHC23k4b_run535085.root](http://alice-ccdb.cern.ch/browse/Users/m/mfaggin/test/inputsTrackTuner/pp2023)
+ Data: LHC23f apass1, run 535085.
+ MC: LHC23k4b, run 535085.
+ Slides [here](https://docs.google.com/presentation/d/1_bsxzgB1DdVu-mxRwhpZ-U65c4J9iL2IH8xUEP3tv4Q/edit?usp=sharing).
+* proxy for Pb-Pb @ 5.36 TeV: [trackTuner_DataLHC22sPass5_McLHC22l1b2_run529397.root](http://alice-ccdb.cern.ch/browse/Users/m/mfaggin/test/inputsTrackTuner/PbPb2022)
+ Data: LHC22s apass5, run 529397.
+ MC: LHC22l1b2, run 529397.
+ Slides [here](https://docs.google.com/presentation/d/1sIXWMckaPZJir3gNLeDnB2TorNJrjXKcGJvyTvz5V8s/edit?usp=sharing).
diff --git a/docs/basics-usage/JsonConfigs.md b/docs/basics-usage/JsonConfigs.md
index 5f26dd6a..23ef2e17 100644
--- a/docs/basics-usage/JsonConfigs.md
+++ b/docs/basics-usage/JsonConfigs.md
@@ -20,7 +20,7 @@ that one wishes to execute.
"start-value-enumeration": "0",
"end-value-enumeration": "-1",
"step-value-enumeration": "1",
- "aod-file": "@inputs-sim.txt"
+ "aod-file-private": "@inputs-sim.txt"
},
"internal-dpl-aod-spawner": "",
"internal-dpl-aod-index-builder": "",
@@ -43,7 +43,7 @@ that one wishes to execute.
"syst": "pp",
"muonSelection": "0",
"customDeltaBC": "300",
- "isMC": "true",
+ "isMC": "1",
"processRun2": "false",
"processRun3": "true"
},
@@ -67,7 +67,7 @@ that one wishes to execute.
In the above example of json file, in the `pseudorapidity-density` section (line 37 to 44), you can see the different values of the configurables, `maxDCAZ` is now 3.2 for instance. You can also specify the type of data you are processing with the flags `processRun2` `processRun3` and `isMC`.
-Another very useful thing is that inside this file you can provide a list of aod files to analyse, as you can see the line 10 `"aod-file": "@inputs-sim.txt"` means that the workflow will analyse the all the files contained in the txt file `inputs-sim.txt`, with one file name per line.
+Another very useful thing is that inside this file you can provide a list of aod files to analyse, as you can see the line 10 `"aod-file-private": "@inputs-sim.txt"` means that the workflow will analyse the all the files contained in the txt file `inputs-sim.txt`, with one file name per line.
## How to give this json file to the workflow
@@ -77,4 +77,6 @@ For example the above json file is well adapted for the task `o2-analysis-mm-dnd
`o2-analysis-timestamp --configuration json://config-file.json | o2-analysis-event-selection --configuration json://config-file.json | o2-analysis-trackextension --configuration json://config-file.json | o2-analysis-mm-dndeta --configuration json://config-file.json`
-*N.B. : You should provide the json file to each workflow separated by a pipe.*
+```note
+You should provide the json file to each workflow separated by a pipe.
+```
diff --git a/docs/basics-usage/ReadingTablesFromFile.md b/docs/basics-usage/ReadingTablesFromFile.md
index 8603e7ab..3833d146 100644
--- a/docs/basics-usage/ReadingTablesFromFile.md
+++ b/docs/basics-usage/ReadingTablesFromFile.md
@@ -10,7 +10,7 @@ The internal-dpl-aod-reader reads trees from root files and provides them as arr
* --aod-file
* --aod-reader-json
-### --aod-file
+## ‐‐aod-file
aod-file takes a string as option value, which either is the name of the input root file or, if starting with an `@`-character, is an ASCII-file which contains a list of input files.
@@ -23,7 +23,7 @@ aod-file takes a string as option value, which either is the name of the input r
```
-#### --aod-reader-json
+### ‐‐aod-reader-json
aod-reader-json is a string and specifies a json file, which contains the
customization information for the internal-dpl-aod-reader. An example file is
@@ -82,7 +82,7 @@ Example json file for the internal-dpl-aod-reader
When the internal-dpl-aod-reader receives the request to fill a given table tablename it searches in the provided InputDirector for the corresponding InputDescriptor and proceeds as defined there. However, if there is no corresponding InputDescripto` it falls back to the information provided by the resfiles and fileregex options of the InputDirector and uses the tablename as treename.
-### Some practical comments
+## Some practical comments
The json-file option allows to setup the reading of tables in a rather
flexible way. Here a few presumably practical cases are discussed:
@@ -92,44 +92,44 @@ processed together. Table tableA was previously saved as tree tableA to file
tableAResults.root and tableB was saved as tree tableB to tableBResults.root.
The following json-file could be used to read these tables:
-```csh
-{
- # file resfiles.txt lists all tableAResults.root and tableBResults.root files.
-
- "InputDirector": {
- "resfiles": "@resfiles.txt",
- "InputDescriptors": [
- {
- "table": "AOD/tableA/0",
- "fileregex": "(tableAResult)(.*)"
- },
- {
- "table": "AOD/tableB/0",
- "fileregex": "(tableBResult)(.*)"
- }
- ]
- }
-```
+ ```csh
+ {
+ # file resfiles.txt lists all tableAResults.root and tableBResults.root files.
+
+ "InputDirector": {
+ "resfiles": "@resfiles.txt",
+ "InputDescriptors": [
+ {
+ "table": "AOD/tableA/0",
+ "fileregex": "(tableAResult)(.*)"
+ },
+ {
+ "table": "AOD/tableB/0",
+ "fileregex": "(tableBResult)(.*)"
+ }
+ ]
+ }
+ ```
2. In this case several tables need to be provided. All tables can be read from files tableResults_x.root, except for one table, namely tableA, which is saved as tree treeA in files tableAResults_x.root.
-```csh
- # file resfiles.txt lists all tableResults_x.root and tableAResults_x.root files.
+ ```csh
+ # file resfiles.txt lists all tableResults_x.root and tableAResults_x.root files.
- "InputDirector": {
- "resfiles": "@resfiles.txt",
- "fileregex": "(tableResult)(.*)"
- "InputDescriptors": [
- {
- "table": "AOD/tableA/0",
- "treename": "treeA",
- "fileregex": "(tableAResult)(.*)"
- }
- ]
- }
-```
+ "InputDirector": {
+ "resfiles": "@resfiles.txt",
+ "fileregex": "(tableResult)(.*)"
+ "InputDescriptors": [
+ {
+ "table": "AOD/tableA/0",
+ "treename": "treeA",
+ "fileregex": "(tableAResult)(.*)"
+ }
+ ]
+ }
+ ```
-### Limitations
+## Limitations
1. It is required that all InputDescriptors have the same number of selected input files. This is internally checked and the processing is stopped if it turns out that this is not the case.
2. The internal-dpl-aod-reader loops over the selected input files in the order as they are listed. It is the duty of the user to make sure that the order is correct and that the order in the file lists
@@ -138,7 +138,7 @@ of the various InputDescriptors are corresponding to each other.
See also tutorial [Table IO](../tutorials/tablesIO.md).
-### Possible ideas
+## Possible ideas
We could add a template ` reshuffle()` method to the Table class which allows you to reduce the number of columns or attach new dynamic columns. A template wrapper could
even be used to specify if a given dynamic column should be precalculated (or not). This would come handy to optimize the creation of a RowView, which could bind only the required (dynamic) columns. E.g.:
diff --git a/docs/basics-usage/SavingTablesToFile.md b/docs/basics-usage/SavingTablesToFile.md
index d95db156..759c3d61 100644
--- a/docs/basics-usage/SavingTablesToFile.md
+++ b/docs/basics-usage/SavingTablesToFile.md
@@ -7,7 +7,9 @@ title: Saving tables to a file
Produced tables can be saved to file as TTrees. This process is customized by various command line options of the internal-dpl-aod-writer. The options allow to specify which columns of which table are saved to which tree in which file.
-**Please be aware, that the functionality of these options is preliminary and might change in future.**
+```note
+Please be aware, that the functionality of these options is preliminary and might change in future.
+```
The options to consider are:
@@ -16,7 +18,7 @@ The options to consider are:
* --aod-writer-ntfmerge
* --aod-writer-json
-## --aod-writer-keep
+## ‐‐aod-writer-keep
aod-writer-keep is a comma-separated list of DataOuputDescriptors.
@@ -63,15 +65,15 @@ sub-string of it). In this case all dangling output tables are saved. For the
parameters tree, columns, and file the default values ([see table
below](#priorities)) are used.
-## --aod-writer-ntfmerge
+## ‐‐aod-writer-ntfmerge
aod-writer-ntfmerge specifies the number of data frames which are merged into a given root directory. By default this value is set to 1. The actual directory name is DF_y directory with y = ntfmerge * (uint64_t)(x / ntfmerge) and x the actual data frame the table belongs to.
-## --aod-writer-resfile
+## ‐‐aod-writer-resfile
aod-writer-resfile specifies the default name of the result file. If in any of the DataOutputDescriptor the file value is missing it will be set to this default value.
-## ----aod-writer-json
+## ‐‐‐‐aod-writer-json
--aod-writer-json specifies the name of a json-file which contains the full information needed to customize the behavior of the internal-dpl-aod-writer. It can replace the other three options completely. Nevertheless, currently all options are supported ([see also discussion below](#redundancy)).
diff --git a/docs/basics-usage/SettingUp.md b/docs/basics-usage/SettingUp.md
index 87191d5b..289b16ec 100644
--- a/docs/basics-usage/SettingUp.md
+++ b/docs/basics-usage/SettingUp.md
@@ -22,19 +22,19 @@ workflow.
A simple example is the histogram tutorial which you can run (on Run 2 converted data) with:
-```
+```bash
o2-analysistutorial-histograms --aod-file AO2D.root
```
-In case you try the same on Run 3 data or MC, you also need the [track propagation task](../helperTasks/trackPropagation.md):
+In case you try the same on Run 3 data or MC, you also need the [track propagation task](HelperTasks.md#track-propagation):
-```
+```bash
o2-analysis-timestamp | o2-analysis-track-propagation | o2-analysistutorial-histograms --aod-file AO2D.root
```
Single task executables are combined with the pipe ( | ) operator, e.g.
-```
+```bash
o2-analysis-timestamp | o2-analysis-event-selection | o2-analysis-trackextension
| o2-analysis-trackselection | o2-analysis-ud-mytask --aod-file AO2D.root
```
diff --git a/docs/datamodel/.DS_Store b/docs/datamodel/.DS_Store
deleted file mode 100644
index 5008ddfc..00000000
Binary files a/docs/datamodel/.DS_Store and /dev/null differ
diff --git a/docs/datamodel/ao2dTables.md b/docs/datamodel/ao2dTables.md
index e063a4dc..17a6f09e 100644
--- a/docs/datamodel/ao2dTables.md
+++ b/docs/datamodel/ao2dTables.md
@@ -8,20 +8,19 @@ title: AO2D tables
The tables which are extracted from the AO2D files are declared in Framework/AnalysisDataModel.h and listed below. They are available by default when using an AO2D file as input to an analysis work flow.
+
Click on the labels to display the table content. Click buttons to
/ all tables.
-#### AO2D files
-For better overview the tables are grouped into the following categories: | [General](#cat_General) | [Tracks](#cat_Tracks) | [Detectors](#cat_Detectors) | [Strangeness](#cat_Strangeness) | [Indices](#cat_Indices) | [MonteCarlo](#cat_MonteCarlo) | [Run2](#cat_Run2) | [Others](#cat_Others) |
-
-
+File: [`trackIndexSkimCreator.cxx`](https://github.com/AliceO2Group/O2Physics/blob/master/PWGHF/TableProducer/trackIndexSkimCreator.cxx) #### Track and event selection @@ -81,14 +86,9 @@ together with a flag indicating for which decay channel(s) the candidate was sel ### Candidate creation and MC matching -Workflow | File | Type --------------------------------------------|-------------------------------|------------------------------------------------------------------------ -`o2-analysis-hf-candidate-creator-2prong` | `candidateCreator2Prong.cxx` | direct 2-prong decays -`o2-analysis-hf-candidate-creator-3prong` | `candidateCreator3Prong.cxx` | direct 3-prong decays -`o2-analysis-hf-candidate-creator-cascade` | `candidateCreatorCascade.cxx` | cascade decays with V0 daughters (Λc±) -`o2-analysis-hf-candidate-creator-xicc` | `candidateCreatorXicc.cxx` | Ξcc±± → Ξc± π± -`o2-analysis-hf-candidate-creator-x` | `candidateCreatorX.cxx` | X(3872) → J/ψ π± π∓ -`o2-analysis-hf-candidate-creator-bplus` | `candidateCreatorBplus.cxx` | B± → D0(bar) π± +Workflows: `o2-analysis-hf-candidate-creator-
+Files: `candidateCreator
+Directories: [`PWGHF/TableProducer`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/TableProducer), `PWGHF/*/TableProducer` #### Candidate creation @@ -111,17 +111,9 @@ Derived tables with MC flags used for the estimation of the signal efficiencies ### Candidate selection -Workflow | File | Type -------------------------------------------------------|-------------------------------------|---------------------------------------------------------------------- -`o2-analysis-hf-candidate-selector-d0` | `candidateSelectorD0.cxx` | D0(bar) → π± K∓ -`o2-analysis-hf-candidate-selector-jpsi` | `candidateSelectorJpsi.cxx` | J/ψ → e+ e−/μ+ μ− -`o2-analysis-hf-candidate-selector-x-to-jpsi-pi-pi` | `candidateSelectorXToJpsiPiPi.cxx` | X(3872) → J/ψ π± π∓ -`o2-analysis-hf-candidate-selector-dplus-to-pi-k-pi` | `candidateSelectorDplusToPiKPi.cxx` | D± → π± K∓ π± -`o2-analysis-hf-candidate-selector-lc` | `candidateSelectorLc.cxx` | Λc± → p(bar) K∓ π± -`o2-analysis-hf-candidate-selector-lc-to-k0s-p` | `candidateSelectorLcToK0sP.cxx` | Λc± → p(bar) KS0 -`o2-analysis-hf-candidate-selector-xic-to-p-k-pi` | `candidateSelectorXicToPKPi.cxx` | Ξc± → p(bar) K∓ π± -`o2-analysis-hf-candidate-selector-xicc-to-p-k-pi-pi` | `candidateSelectorXiccToPKPiPi.cxx` | Ξcc±± → Ξc± π± -`o2-analysis-hf-candidate-selector-bplus-to-d0-pi` | `candidateSelectorBplusToD0Pi.cxx` | B± → D0(bar) π± +Workflows: `o2-analysis-hf-candidate-selector-
+Files: `candidateSelector
+Directories: [`PWGHF/TableProducer`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/TableProducer), `PWGHF/*/TableProducer` In a dedicated selector task, tailored for each decay channel, accurate analysis level selection criteria based on decay topology and PID are applied to the reconstructed candidates. @@ -130,20 +122,9 @@ The selection results are stored in a column of a new dedicated table that is la ### Analysis tasks -Workflow | File | Type ------------------------------------------|-----------------------------|------------------------------------------------------------------------- -`o2-analysis-hf-task-d0` | `taskD0.cxx` | D0(bar) → π± K∓ -`o2-analysis-hf-task-jpsi` | `taskJpsi.cxx` | J/ψ → e+ e−/μ+ μ− -`o2-analysis-hf-task-dplus` | `taskDplus.cxx` | D± → π± K∓ π± -`o2-analysis-hf-task-lc` | `taskLc.cxx` | Λc± → p(bar) K∓ π± -`o2-analysis-hf-task-lc-to-k0s-p` | `taskLcToK0sP.cxx` | Λc± → p(bar) KS0 -`o2-analysis-hf-task-xic` | `taskXic.cxx` | Ξc± → p(bar) K∓ π± -`o2-analysis-hf-task-xicc` | `taskXicc.cxx` | Ξcc±± → Ξc± π± -`o2-analysis-hf-task-bplus` | `taskBplus.cxx` | B± → D0(bar) π± -`o2-analysis-hf-task-x` | `taskX.cxx` | X(3872) → J/ψ π± π∓ -`o2-analysis-hf-correlator-d0-d0bar` | `correlatorD0D0bar.cxx` | D0–D0bar correlations -`o2-analysis-hf-correlator-dplus-dminus` | `correlatorDplusDminus.cxx` | D+–D− correlations -`o2-analysis-hf-task-correlation-d-dbar` | `taskCorrelationDDbar.cxx` | D0–D0bar, D+–D− correlations +Workflows: `o2-analysis-hf-task-
+Files: `task
+Directories: [`PWGHF/Tasks`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/Tasks), `PWGHF/*/Tasks` #### Real-data analysis @@ -153,26 +134,40 @@ In the user analysis task, histograms needed for the analysis are filled with pr For MC events, histograms with quantities of generated MC particles and MC-matched candidates are produced. +### Tree creation + +Candidate tables and other related derived tables are exported to disk as ROOT trees for +post-processing with external tools, e.g. for selection optimisation with machine learning techniques. + +Workflows: `o2-analysis-hf-tree-creator-
+Files: `treeCreator
+Directories: [`PWGHF/TableProducer`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/TableProducer), `PWGHF/*/TableProducer` + +### Derived-data creation + +Derived-data creators are a better alternative to tree creators, because they are more flexible and +can produce light self-contained interlinked tables which are independent from the parent AO2D files +and can therefore be stored as derived datasets on AliHyperloop as well as processed locally. + +Workflows: `o2-analysis-hf-derived-data-creator-
+Files: `derivedDataCreator
+Directories: [`PWGHF/TableProducer`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/TableProducer), `PWGHF/*/TableProducer` + ### QA and helper workflows Workflow | File | Type ---------------------------------------|---------------------------|---------------------------------------------------------------------------- +`o2-analysis-hf-pid-creator` | `pidCreator.cxx` | creation of tables combining *σ* from TPC and TOF for track selection `o2-analysis-hf-task-mc-validation` | `taskMcValidation.cxx` | validation of HF MC distributions -`o2-analysis-task-qa-pid-rejection` | `taskQaPidRejection.cxx` | PID selection performance `o2-analysis-hf-task-sel-optimisation` | `taskSelOptimisation.cxx` | preselection optimisation `o2-analysis-hf-refit-pv-dummy` | `refitPvDummy.cxx` | creation of a dummy table with primary-vertex position (for converted data) -### Tree creation +### Postprocessing scripts and macros -Candidate tables and other related derived tables are exported to disk as ROOT trees for -post-processing with external tools, e.g. for optimisation with Machine Learning techniques. +Python scripts and ROOT macros which process the O2Physics output files. +In general, Python scripts are preferred over ROOT macros. -Workflow | File | Type -------------------------------------------------|-------------------------------|---------------------------------------------------------------------- -`o2-analysis-hf-tree-creator-d0-to-k-pi` | `treeCreatorD0ToKPi.cxx` | D0(bar) → π± K∓ -`o2-analysis-hf-tree-creator-lc-to-p-k-pi` | `treeCreatorLcToPKPi.cxx` | Λc± → p(bar) K∓ π± -`o2-analysis-hf-tree-creator-x-to-jpsi-pi-pi` | `treeCreatorXToJpsiPiPi.cxx` | X(3872) → J/ψ π± π∓ -`o2-analysis-hf-tree-creator-xicc-to-p-k-pi-pi` | `treeCreatorXiccToPKPiPi.cxx` | Ξcc±± → Ξc± π± +Directories: [`PWGHF/D2H/Macros`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/D2H/Macros) ## Contribute @@ -181,13 +176,44 @@ Workflow | File - Follow the [O2 coding guidelines](https://github.com/AliceO2Group/CodingGuidelines) (especially the [naming](https://rawgit.com/AliceO2Group/CodingGuidelines/master/naming_formatting.html) and [commenting](https://rawgit.com/AliceO2Group/CodingGuidelines/master/comments_guidelines.html) rules). -- Sort O2Physics `#include`s alphabetically and keep `PWGHF/...` at the end. +- Respect the alphabetic order and groups in `CMakeLists.txt` when adding a new workflow. +- Link only necessary libraries in `CMakeLists.txt`. +- Avoid code duplication and reuse existing code (e.g. `RecoDecay`, table columns, constants). +- Define variables for repeatedly used objects (histogram types, axes, strings, calculated values). +- Explicitly state when using the `std` namespace (e.g. `std::abs`, `std::array`, `std::vector`). +- Do not use ROOT features unnecessarily (e.g. `TMath::Abs` → `std::abs`, `Double_t` → `double`). + - Use of macros for [bit manipulations](https://root.cern/doc/master/Rtypes_8h_source.html#l00083) (`BIT`, `SETBIT`, `TESTBIT`, `CLRBIT`) is encouraged. +- Do not use `M_PI`. Instead, use `PI`, `TwoPI`, `PIHalf`, `PIThird`, `PIQuarter` from the `o2::constants::math` namespace. +- Use `LOG`, `LOGF`, `LOGP` macros for logging (instead of `Printf`, `printf`, `std::cout`). + - Use the right logging level: + - `debug` for technical information useful for debugging and development, + - `info` for information about what the code is doing that is useful to report at every execution, + - `warn` for conditions that are likely to affect the expected behaviour of the code, + - `error` for problems that lead to an unwanted behaviour of the code, + - `fatal` for critical problems that make further running of the code impossible or useless. +- Include only needed headers but do not rely on implicitly included headers. +- Organise `#include`s into groups (separated by a blank line) in the following order: + - C++ + - other external headers + - ROOT + - O2 + - O2Physics + - PWG other than HF + - PWGHF + - Put PAG headers after the common ones. +- Sort `#include`s alphabetically within a group. +- Avoid using hard-coded PDG codes. Use their `enum` names instead + (from [`PDG_t`](https://root.cern/doc/master/TPDGCode_8h.html) or + [`o2::constants::physics::Pdg`](https://github.com/AliceO2Group/AliceO2/blob/dev/Common/Constants/include/CommonConstants/PhysicsConstants.h)). + See also [Magic numbers](https://rawgit.com/AliceO2Group/CodingGuidelines/master/coding_guidelines.html?showone=Magic_numbers#Magic_numbers). +- Use `Type const&` for table subscriptions in function arguments. +- Declare iterators in range-based `for` loops over tables with `const auto&`. - Test your code before making a pull request. - - Propagate your changes into the Run3Analysisvalidation configuration. - - Check that your branch compiles. + - Check that your branch compiles without warnings. + - Propagate your changes into the [Run3Analysisvalidation](https://github.com/AliceO2Group/Run3Analysisvalidation/tree/master/codeHF#add-a-new-workflow) configuration. - Check that your code works and runs without errors and warnings. - Make sure your code is compatible with the expected input (Run 2/3/5, real/MC data, p–p/Pb–Pb). - - Check that your changes do not alter unexpectedly the control plots produced by the validation framework. + - Check that your changes do not alter unexpectedly the control plots produced by the [validation framework](https://github.com/AliceO2Group/Run3Analysisvalidation/tree/master/codeHF#run-the-example). - Make sure your tasks can be fully configured from Run3Analysisvalidation and AliHyperloop. #### `struct` members @@ -205,13 +231,16 @@ Organising the code in a well defined structure makes it easier to navigate thro - other members (constants, objects) - `using` declarations - `Filter` + - `Preslice` - `Partition` - `ConfigurableAxis` - `AxisSpec` - `HistogramRegistry` - output declarations (`OutputObj`,...) - `init` function + - helper functions - `process` function(s) + - Put one process function argument per line. - `PROCESS_SWITCH` follows immediately after the function definition. ### Naming conventions @@ -237,7 +266,8 @@ Organising the code in a well defined structure makes it easier to navigate thro - `RecBg` - reconstruction level quantity of a reconstructed background candidate The names of the source file, the executable and the task(s) should match.
-Note: The device name of a task is automatically generated from the name of the corresponding `struct` by replacing uppercase letters with lowercase letters preceded with a hyphen unless defined explicitly using `TaskName`, which should be avoided if not necessary.
+Note: The device name of a task is automatically generated from the name of the corresponding `struct` by replacing uppercase letters with lowercase letters preceded with a hyphen. +The device name can be explicitly defined using `TaskName` only when several instances of a templated task need to be defined.
Example: - source file name: `taskXY.cxx` @@ -245,27 +275,11 @@ Example: - main task (`struct`) name: `HfTaskXY` (results in the generated device name `hf-task-x-y`) - auxiliary-task name: `HfTaskXY
+
+
+
+There are three relevant devices (subtasks) inside each of the builders, each with different configurations that are of interest to the users. They are:
+
+* `preselectors` allow the user to pre-filter the V0s or cascades that will be built, possibly selecting on MC truth (MC-exclusive), TPC dE/dx or both. This is done via the choice of process function: `processBuildAll` will have all V0s passing topological selections to be built and stored, while `processBuildMCAssociated` will configure the builder to build only MC true candidates of the desired (configurable) type and `processBuildValiddEdx` will configure the builder to only construct candidates for which the TPC dE/dx is compatible with one of the (configurable) hypotheses of interest. Finally, `processBuildValiddEdxMCAssociated` allows for both MC truth and TPC dE/dx to be preselected on.
+* `builders` take the tags from the preselectors and build those V0s or cascades that the user is interested in. Builders have configurables that control the topological selections of the desired V0 and cascade candidates and also allow for topological selection autodetect (more below).
+* `label builders` run after the building has been done and provide indices to mcparticles for all analysis tables (`V0Datas` and `CascDatas`) via the two tables `MCV0Labels` and `MCCascLabels`, joinable with `V0Datas` and `CascDatas`, respectively. In order to switch label building on, the process functions `processBuildV0Labels` or `processBuildCascadeLabels` have to be used. This function is naturally only possible in simulations. .
+
+### Topological selection autodetect in strangeness builders
+
+In order to make analysis more convenient and efficient, the strangeness builders have an option called `d_UseAutodetectMode` that, if enabled, will make the builders go through all user tasks set to run together with it and look for variables with the following names:
+
+* `v0setting_cospa` (V0 builder)
+* `v0setting_dcav0dau` (V0 builder)
+* `v0setting_dcapostopv` (V0 builder)
+* `v0setting_dcanegtopv` (V0 builder)
+* `v0setting_radius` (V0 builder)
+* `cascadesetting_cospa` (cascade builder)
+* `cascadesetting_dcacascdau` (cascade builder)
+* `cascadesetting_dcabachtopv` (cascade builder)
+* `cascadesetting_cascradius` (cascade builder)
+* `cascadesetting_v0masswindow` (cascade builder)
+* `cascadesetting_mindcav0topv` (cascade builder)
+
+If found, the values of these 11 basic topological variables will then be the ones that the builders will use. If more than one task has specified desired topological selections, the builders will automatically configure for the loosest among the multiple selections requested, such that all tasks in the analysis chain get their requests adequately fulfilled. Please note that, because of this loosening in case of multiple requests, it is expected that analysis tasks also additionally select on these variables when processing data.
## Code
diff --git a/docs/advanced-specifics/pwgmm.md b/docs/advanced-specifics/pwgmm.md
index 4b46df10..93b06a76 100644
--- a/docs/advanced-specifics/pwgmm.md
+++ b/docs/advanced-specifics/pwgmm.md
@@ -1,5 +1,5 @@
---
-sort: 9
+sort: 10
title: PWG-MM
---
diff --git a/docs/advanced-specifics/pwgud.md b/docs/advanced-specifics/pwgud.md
index e73c4c96..66043687 100644
--- a/docs/advanced-specifics/pwgud.md
+++ b/docs/advanced-specifics/pwgud.md
@@ -1,5 +1,5 @@
---
-sort: 10
+sort: 11
title: PWG-UD
---
diff --git a/docs/advanced-specifics/trackToCollAssoc.md b/docs/advanced-specifics/trackToCollAssoc.md
new file mode 100644
index 00000000..60674ac1
--- /dev/null
+++ b/docs/advanced-specifics/trackToCollAssoc.md
@@ -0,0 +1,88 @@
+---
+sort: 1
+title: Track to collision association
+---
+# Track to collision association
+
+In Run 3, due to the increased interaction rate, a track time window can overlap in time with multiple collisions. For example, the standalone ITS has a default track time window (also called Read-Out Frame (ROF)) of 198 bunch crossings (BC) $$\approx$$ 4.95 $$\mu s$$. With an interaction rate of 500 kHz, there is approximately one collision every 2 $$\mu s$$, meaning that a standalone ITS track readout window overlaps with 2.5 collisions on average.
+
+Knowing approximate time at which the track crossed the detector and the time of the different collisions, one can then associate a track to the different collisions it is time-compatible to.
+
+In O2Physics this association is done using two different tasks for the different types of tracks:
+
+- [o2-analysis-track-to-collision-associator](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/trackToCollisionAssociator.cxx) for central tracks
+- [o2-analysis-fwdtrack-to-collision-associator](https://github.com/AliceO2Group/O2Physics/blob/master/Common/TableProducer/fwdtrackToCollisionAssociator.cxx) for muons and MFT tracks
+
+Both of the tasks are based on the same code [CollisionAssociation.h](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/CollisionAssociation.h) and use several configurables.
+
+For a brief description of the configurables, one can have a look at the section below, and for a deeper dive into what this code does one can read the section **Description of the collision association procedure**.
+Reading the description of the code is strongly recommended for the analysers that are piping this task to their workflow.
+
+## fwdtrack-to-collision-associator
+
+```cpp
+Configurable
+
+
+
+
+For other detectors, the time resolution of the track is gaussian-like, meaning that the track has crossed the detector around the time $$t_{track}$$, with a gaussian standard deviation $$\sigma_{track}$$.
+
+
+
+
+
+
+Defining $$t_{coll}$$ the time of the collision $$coll$$ and its associated gaussian time uncertainty $$\sigma_{coll}$$, one can then compute the time difference between the track and the collision as $$\Delta_t = \lvert t_{track}-t_{coll} \rvert$$
+
+The collision $$coll$$ is considered compatible in time with the track if $$\Delta_t <$$ thresholdTime.
+
+- thresholdTime = $$\sigma_{track}$$+nSigmaForTimeCompat $$\times ~\sigma_{coll}$$ + timeMargin,
+for tracks with a box-like error.
+
+- thresholdTime = nSigmaForTimeCompat $$\times ~\sqrt{\sigma_{track}^2+\sigma_{coll}^2}$$ + timeMargin,
+for tracks with a gaussian-like error.
diff --git a/docs/basics-tasks/BasicAnalysisTask.md b/docs/basics-tasks/BasicAnalysisTask.md
index 8b132e2e..cd9242dc 100644
--- a/docs/basics-tasks/BasicAnalysisTask.md
+++ b/docs/basics-tasks/BasicAnalysisTask.md
@@ -38,9 +38,13 @@ defineDataProcessing() {
>
> `AnalysisTask` will not actually provide any virtual method, as the `adaptAnalysis` helper relies on template argument matching to discover the properties of the task. It will come clear in the next paragraph how this allow is used to avoid the proliferation of data subscription methods.
-```todo
-Define minimum requirements for a complet task
-```
+## Minimum requirements for a complete task
+
+- License agreement
+- Required header files
+- O2 basic name spaces
+- Struct comprising an init and a process function
+- Defined Workflow
See also tutorial [Analysis Task](../tutorials/analysistask.md).
@@ -115,7 +119,7 @@ HistogramConfigSpec(HistType type,
uint8_t nSteps = 1)
```
-HistType specifies the type of the histogram. The supported hstograms types are listed in HistogramSpec.h. The vector of AxisSpec describe the axes of the histogram. nSteps is only used for histograms of type StepTHn.
+HistType specifies the type of the histogram. The supported histogram types are listed in HistogramSpec.h. The vector of AxisSpec describes the axes of the histogram. nSteps is only used for histograms of type StepTHn.
Histogram axes are realized by AxisSpec which has two constructors.
@@ -131,15 +135,15 @@ AxisSpec(int nBins,
std::optional
+
+For better overview the tables are grouped into the following categories: \| [General](#cat_General) \| [Tracks](#cat_Tracks) \| [Detectors](#cat_Detectors) \| [Strangeness](#cat_Strangeness) \| [Indices](#cat_Indices) \| [MonteCarlo](#cat_MonteCarlo) \| [Run2](#cat_Run2) \| [Others](#cat_Others) \|
-
General
+ +## General
-
+
-
+
-
Root of data model for tables pointing to a bunch crossing
@@ -29,10 +28,57 @@ For better overview the tables are grouped into the following categories: | [Gen
+
+
+
+
+
+
Header file: Framework/Core/include/Framework/AnalysisDataModel.h
+ | Name | ++ | Getter | +Type | +Comment | +
|---|---|---|---|---|
| o2::soa::Index | +GI | +globalIndex | +int64_t | ++ |
| o2::aod::bc::RunNumber | ++ | runNumber | +int | +Run number | +
| o2::aod::bc::GlobalBC | ++ | globalBC | +uint64_t | +Bunch crossing number (globally unique in this run) | +
| o2::aod::bc::TriggerMask | ++ | triggerMask | +uint64_t | +CTP trigger mask | +
+
@@ -71,6 +117,13 @@ For better overview the tables are grouped into the following categories: | [Gen
@@ -107,7 +160,7 @@ For better overview the tables are grouped into the following categories: | [Gen
+ Root of data model for tables pointing to a bunch crossing, version 1
+
+
+ Header file: Framework/Core/include/Framework/AnalysisDataModel.h
+
Is used in:
-
-
- o2::aod::BC = o2::aod::BCs::iterator -
- o2::aod::BCsWithTimestamps = soa::Join
- o2::aod::BCs = o2::aod::BCs_001
| uint64_t | CTP trigger mask | +|||
| o2::aod::bc::InputMask | ++ | inputMask | +uint64_t | +CTP input mask | +
Time and vertex information of collision
@@ -115,13 +168,6 @@ For better overview the tables are grouped into the following categories: | [Gen
+
+
+
Header file: Framework/Core/include/Framework/AnalysisDataModel.h
- Is used in:
-
-
-
- o2::aod::Collision = o2::aod::Collisions::iterator -
- o2::aod::CollisionMatchedRun2Sparse = soa::Join
- o2::aod::CollisionMatchedRun3Sparse = soa::Join
| Name | @@ -245,8 +291,146 @@ For better overview the tables are grouped into the following categories: | [Gen
|---|
+
+
+
+
+ Time and vertex information of collision
+
+
+ Header file: Framework/Core/include/Framework/AnalysisDataModel.h
+
+ Is used in:
+
+ -
+
- o2::aod::Collisions = o2::aod::Collisions_001 +
| Name | ++ | Getter | +Type | +Comment | +
|---|---|---|---|---|
| o2::soa::Index | +GI | +globalIndex | +int64_t | ++ |
| o2::aod::collision::BCId | +I | +bcId | +int32 | +Most probably BC to where this collision has occured | +
| o2::aod::collision::PosX | ++ | posX | +float | +X Vertex position in cm | +
| o2::aod::collision::PosY | ++ | posY | +float | +Y Vertex position in cm | +
| o2::aod::collision::PosZ | ++ | posZ | +float | +Z Vertex position in cm | +
| o2::aod::collision::CovXX | ++ | covXX | +float | +Vertex covariance matrix | +
| o2::aod::collision::CovXY | ++ | covXY | +float | +Vertex covariance matrix | +
| o2::aod::collision::CovYY | ++ | covYY | +float | +Vertex covariance matrix | +
| o2::aod::collision::CovXZ | ++ | covXZ | +float | +Vertex covariance matrix | +
| o2::aod::collision::CovYZ | ++ | covYZ | +float | +Vertex covariance matrix | +
| o2::aod::collision::CovZZ | ++ | covZZ | +float | +Vertex covariance matrix | +
| o2::aod::collision::Flags | ++ | flags | +uint16_t | +Run 2: see CollisionFlagsRun2 | Run 3: see Vertex::Flags | +
| o2::aod::collision::Chi2 | ++ | chi2 | +float | +Chi2 of vertex fit | +
| o2::aod::collision::NumContrib | ++ | numContrib | +uint16_t | +Number of tracks used for the vertex | +
| o2::aod::collision::CollisionTime | ++ | collisionTime | +float | +Collision time in ns relative to BC stored in bc() | +
| o2::aod::collision::CollisionTimeRes | ++ | collisionTimeRes | +float | +Resolution of collision time | +
Tracks
+ +## Tracks
@@ -267,7 +451,15 @@ For better overview the tables are grouped into the following categories: | [Gen
o2::aod::Track = o2::aod::Tracks::iterator
o2::aod::FullTracks = soa::Join
o2::aod::FullTrack = soa::Join::iterator
- o2::aod::BigTracks = soa::Join
+ o2::aod::TracksWCov = soa::Join
+ o2::aod::TracksWDca = soa::Join
+ o2::aod::TracksWExtra = soa::Join
+ o2::aod::TracksWCovDca = soa::Join
+ o2::aod::TracksWCovExtra = soa::Join
+ o2::aod::TracksWDcaExtra = soa::Join
+ o2::aod::TracksWCovDcaExtra = soa::Join
+ o2::aod::TracksWMc = soa::Join
+ o2::analysis::TracksWExt = soa::Join