Update PWG-HF documentation

Author: vkucera

docs/advanced-specifics/pwghf.md

@@ -7,14 +7,24 @@ title: PWG-HF
 
 ## Get started
 
-- See the materials from the [HF O2 hackathon](https://indico.cern.ch/event/1101005/)
-(includes introduction to O2, O2 HF, tutorials,...) and watch the
-[Zoom recordings of the sessions](https://videos.cern.ch/deposit/project/cbe4869a27f749b7b45ea66577ca8a9f) (7, 9 Dec 2021).
-- See the [presentation on HF vertexing and analysis](https://indico.cern.ch/event/1200252/timetable/#10-hf-vertexing-and-analysis)
+See the presentations and materials from the HF session of the latest [O2 Analysis Tutorial](../tutorials/README.md#tutorial-events).
+
+### Archive
+
+- [HF O2 hackathon](https://indico.cern.ch/event/1101005/)
+(introduction to O2, O2 HF, tutorials,...),
+[Zoom recordings of the sessions](https://videos.cern.ch/deposit/project/cbe4869a27f749b7b45ea66577ca8a9f) (7, 9 Dec 2021)
+- [Presentation on HF vertexing and analysis](https://indico.cern.ch/event/1200252/timetable/#10-hf-vertexing-and-analysis)
 and the [HF analysis example](https://indico.cern.ch/event/1200252/timetable/#23-hands-on-session-4-analysis)
-from the [O2 Analysis Tutorial](https://indico.cern.ch/event/1200252/) (13–14 Oct 2022).
-- See the [HF hands-on session](https://indico.cern.ch/event/1267433/timetable/#b-504545-parallel-hands-on-pwg)
-from the [O2 Analysis Tutorial 2.0](https://indico.cern.ch/event/1267433/) (17-28 Apr 2023).
+at the O2 Analysis Tutorial (1.0) (14 Oct 2022)
+- [HF session](https://indico.cern.ch/event/1267433/timetable/#b-504545-parallel-hands-on-pwg)
+at the O2 Analysis Tutorial 2.0 (27 Apr 2023)
+- [HF session](https://indico.cern.ch/event/1326201/timetable/#b-528200-pwg-hf-the-heavy-flav)
+at the O2 Analysis Tutorial 3.0 (8 Nov 2023)
+- [HF session](https://indico.cern.ch/event/1425820/timetable/#b-571495-pwg-hf-the-heavy-flav)
+at the O2 Analysis Tutorial 4.0 (16 Oct 2024)
+- [HF session](https://indico.cern.ch/event/1574136/timetable/#b-629951-pwg-hf-pwg-hf-tutoria)
+at the O2 Analysis Tutorial 5.0 (12 Nov 2025)
 
 ## Contact
 
@@ -24,12 +34,16 @@ Mattermost channel: [hf-o2-analysis](https://mattermost.web.cern.ch/alice/channe
 
 - Code used by the heavy-flavour analysis framework is in the
 [`PWGHF`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF) directory.
-  - Tables produced by skimming and candidate creators are defined in
+  - Tables produced by the track index skim creator are defined in
+[`TrackIndexSkimmingTables.h`](https://github.com/AliceO2Group/O2Physics/blob/master/PWGHF/DataModel/TrackIndexSkimmingTables.h).
+  - Tables produced by candidate creators are defined in
 [`CandidateReconstructionTables.h`](https://github.com/AliceO2Group/O2Physics/blob/master/PWGHF/DataModel/CandidateReconstructionTables.h).
   - Tables produced by candidate selectors are defined in
 [`CandidateSelectionTables.h`](https://github.com/AliceO2Group/O2Physics/blob/master/PWGHF/DataModel/CandidateSelectionTables.h).
   - Tables produced by derived-data creators are defined in
 [`DerivedTables.h`](https://github.com/AliceO2Group/O2Physics/blob/master/PWGHF/DataModel/DerivedTables.h).
+  - Constants for MC flagging of HF decay channels are defined in
+[`DecayChannels.h`](https://github.com/AliceO2Group/O2Physics/blob/master/PWGHF/Core/DecayChannels.h).
   - Default parameters used in the selection of single tracks, track-index skims and candidates are defined in
 [`SelectorCuts.h`](https://github.com/AliceO2Group/O2Physics/blob/master/PWGHF/Core/SelectorCuts.h).
   - Machine learning response classes are implemented in [`HfMlResponse(...).h`](https://github.com/AliceO2Group/O2Physics/tree/master/PWGHF/Core) files.
@@ -41,7 +55,7 @@ Mattermost channel: [hf-o2-analysis](https://mattermost.web.cern.ch/alice/channe
 [`RecoDecay`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/RecoDecay.h) class.
 - Selection of tracks based on the particle identification (PID) detectors is performed via the
 [`TrackSelectorPID`](https://github.com/AliceO2Group/O2Physics/blob/master/Common/Core/TrackSelectorPID.h) class.
-- The validation framework for easy local execution, testing and validation of O2Physics code can be found in the
+- The validation framework for easy local execution, testing, and validation of O2Physics code can be found in the
 [Run3AnalysisValidation](https://github.com/AliceO2Group/Run3AnalysisValidation) repository.
 
 ## AliHyperloop
@@ -50,15 +64,15 @@ Mattermost channel: [hf-o2-analysis](https://mattermost.web.cern.ch/alice/channe
 [AliHyperloop analyses](https://alimonitor.cern.ch/hyperloop/all-analyses)
 <!-- markdown-link-check-enable -->
 (Type "PWGHF" in the field "JIRA" to filter.)<br>
-Corresponding [JIRA tickets](https://its.cern.ch/jira/issues/?jql=project%20%3D%20PWG-HF%20AND%20%22Run%203%20analysis%22%20%3D%20Yes)
+Corresponding [JIRA tickets](https://its.cern.ch/jira/issues/?jql=project%20%3D%20PWGHF%20AND%20%22Run%203%20analysis%22%20%3D%20Yes%20ORDER%20BY%20created%20ASC)
 
 ## Framework structure
 
 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.
 
 <div align="center">
-<img src="../images/pwghf_graph.svg" width="800px" alt="PWGHF analysis framework">
+<img src="../images/graph_o2_hf_simple.svg" width="800px" alt="PWGHF analysis framework">
 </div>
 
 ## Framework components
@@ -192,7 +206,7 @@ Directories: [`PWGHF/D2H/Macros`](https://github.com/AliceO2Group/O2Physics/tree
     - `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. See [Include What You Use](https://github.com/AliceO2Group/O2Physics/issues/8357).
-- Sort `#include`s from most specific to least specific and organise them into groups (separated by a blank line) in the following order (can be done automatically with [clang-format](../tools/README.md#pre-commit-hooks)):
+- Sort `#include`s from most specific to least specific and organise them into groups (separated by a blank line) in the following order (done automatically by [clang-format](../tools/README.md#pre-commit-hooks)):
 
   1. Main module
   2. Local-like file
@@ -212,7 +226,7 @@ Directories: [`PWGHF/D2H/Macros`](https://github.com/AliceO2Group/O2Physics/tree
      - C++ standard library
      - C standard library
 
-- Sort `#include`s alphabetically within a group.
+- Sort `#include`s alphabetically within a group (done automatically by [clang-format](../tools/README.md#pre-commit-hooks)).
 - 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)).
@@ -259,7 +273,7 @@ Organising the code in a well defined structure makes it easier to navigate thro
 
 ### Naming conventions
 
-- Use the `<object><attribute>` (or `<general><specific>`) naming scheme, so that names of the same kind of objects start with same string and the different attributes follow.
+- Use the `<object><attribute>` (or `<general><specific>`) naming scheme, so that names of the same kind of objects start with same string and the different attributes follow (imagine a tree hierarchy).
   This scheme makes names more readable, searchable and sortable.
   - Example: `ptTrackMin`, `etaTrackMax`, `trackPos`, `trackNeg` is more readable and sortable than `minTrackPt`, `maxTrackEta`, `posTrack`, `negTrack`.
 - Word-like strings (acronyms, abbreviations, particle names, mathematical variables) are treated as words; i.e. capitalise only the first letter.

docs/images/graph_o2_hf_simple.gv

@@ -0,0 +1,194 @@
+// Graph of the PWG-HF analysis framework simplified for an analysis of one decay channel.
+
+// Draw with Graphviz using: dot -Tsvg <name>.gv -o <name>.svg
+
+digraph hf {
+  label="PWG-HF analysis framework"
+  labelloc=t
+  overlap=false
+  splines=true
+  sep=0.1
+  fontname=Helvetica
+  fontsize=30
+  //rankdir=LR // left to right
+  //ranksep=1.
+  ratio=2
+  node [style="filled,rounded",fillcolor=white,shape=box,fontname=Helvetica,fontsize=30]
+
+  subgraph tables_aod {
+    label="tables_aod"
+    node [fillcolor=lemonchiffon,style=filled]
+    tables_aod_legend [label="AOD\ntable"]
+    Collisions [label="collisions"]
+    McCollisions [label="MC collisions"]
+    BCs [label="bunch\ncrossings"]
+    Tracks [label="tracks"]
+    McTrackLabels [label="MC track\nlabels"]
+    McParticles [label="MC particles"]
+  }
+
+  subgraph tables_derived {
+    label="tables_derived"
+    node [fillcolor=lightgrey,style=filled]
+    tables_derived_legend [label="derived\ntable"]
+    HfTrackSel [label="track\nflags"]
+    EvSels [label="trigger\nflags"]
+    HfCollSel [label="collision\nflags"]
+    join_collisions [label="flagged\ncollisions"]
+    {Collisions HfCollSel} -> join_collisions
+    HfTracks [label="flagged\ntracks"]
+    {HfTrackSel Tracks} -> HfTracks
+    TrackPids [label="track\nPID"]
+    {Tracks TrackPids} -> TracksWPid
+    {Tracks McTrackLabels} -> TracksWMc
+    HfTrackIndexProngN [label="track index\npairs/triplets"]
+    HfCand [label="reconstructed\ncandidates"]
+    HfCandMcRec [label="MC rec.\nflags"]
+    HfPartMcGen [label="MC gen.\nflags"]
+    HfCandSel [label="candidate\nflags"]
+    join_cand_real [label="filtered\ncandidates"]
+    {HfCand HfCandSel} -> join_cand_real
+    join_cand_mc_rec [label="MC-flagged\nfiltered\ncandidates"]
+    {HfCand HfCandSel HfCandMcRec} -> join_cand_mc_rec
+    join_part_mc_gen [label="flagged\nMC particles"]
+    {McParticles HfPartMcGen} -> join_part_mc_gen
+    HfCandTree [label="HF\ncandidates"]
+    HfCollTree [label="HF\nevents"]
+    HfPartTree [label="HF\nparticles"]
+    HfDerivedTable [label="derived\nHF tables"]
+  }
+
+  subgraph output {
+    label="output"
+    node [fillcolor=lightblue]
+    output_legend [label="output"]
+    histograms
+    trees
+  }
+
+  subgraph code {
+    label="code"
+    node [fillcolor=springgreen]
+    code_legend [label="processing"]
+
+    // PID
+    PidTask [label="PID"]
+    {Collisions Tracks} -> PidTask -> TrackPids
+
+    // event selection
+    EventSelectionTask [label="event\nselection"]
+    {Collisions BCs Tracks} -> EventSelectionTask -> EvSels
+    HfTagSelCollisions [label="event\nselector"]
+    {Collisions EvSels} -> HfTagSelCollisions -> HfCollSel
+
+    // track selection
+    HfTagSelTracks [label="track\nselector"]
+    {Tracks Collisions} -> HfTagSelTracks -> HfTrackSel
+
+    // index skimming
+    HfTrackIndexSkimsCreator [label="track index\nskim creator"]
+    {HfTracks BCs join_collisions} -> HfTrackIndexSkimsCreator -> HfTrackIndexProngN
+
+    // candidate creator
+    HfCandidateCreator [label="candidate\ncreator"]
+    {Collisions HfTrackIndexProngN Tracks} -> HfCandidateCreator -> HfCand
+
+    // candidate creator MC
+    HfCandidateCreatorMc [label="MC matching"]
+    {HfCand TracksWMc McParticles} -> HfCandidateCreatorMc -> {HfCandMcRec HfPartMcGen}
+
+    // candidate selector
+    HfCandidateSelector [label="candidate\nselector"]
+    {HfCand TracksWPid} -> HfCandidateSelector -> HfCandSel
+
+    // analysis task
+    TaskData [label="process data"]
+    {Collisions join_cand_real} -> TaskData -> histograms
+
+    // analysis task MC
+    TaskMc [label="process MC"]
+    {McCollisions TracksWMc join_cand_mc_rec join_part_mc_gen} -> TaskMc -> histograms
+
+    // tree creator
+    {Collisions McCollisions TracksWPid join_cand_real join_cand_mc_rec join_part_mc_gen} -> HfTreeCreator -> {HfCandTree HfCollTree HfPartTree} -> trees
+    HfTreeCreator [label="tree creator"]
+
+    // derived-data creator
+    {Collisions McCollisions TracksWPid join_cand_real join_cand_mc_rec join_part_mc_gen} -> DerivedDataCreator -> HfDerivedTable
+    DerivedDataCreator [label="derived-data creator"]
+  }
+
+  subgraph cluster_skim {
+    label="track index skimming"
+    color=papayawhip //peachpuff //powderblue
+    style="filled,rounded"
+    HfTagSelTracks
+    HfTagSelCollisions
+    HfTrackSel
+    HfCollSel
+    HfTracks
+    join_collisions
+    HfTrackIndexSkimsCreator
+    HfTrackIndexProngN
+  }
+
+  subgraph cluster_cand {
+    label="candidate reconstruction\nand MC matching"
+    color=papayawhip //peachpuff //powderblue
+    style="filled,rounded"
+    HfCandidateCreator
+    HfCandidateCreatorMc
+    HfCand
+    HfCandMcRec
+    HfPartMcGen
+  }
+
+  subgraph cluster_selector {
+    label="candidate\nfiltering"
+    color=papayawhip //peachpuff //powderblue
+    style="filled,rounded"
+    HfCandidateSelector
+    HfCandSel
+  }
+
+  subgraph cluster_task {
+    label="analysis"
+    color=papayawhip //peachpuff //powderblue
+    style="filled,rounded"
+    TaskData
+    TaskMc
+    histograms
+  }
+
+  subgraph cluster_tree {
+    label="table export"
+    color=papayawhip //peachpuff //powderblue
+    style="filled,rounded"
+    HfTreeCreator
+    HfCandTree
+    HfCollTree
+    HfPartTree
+    trees
+  }
+
+  subgraph cluster_derived {
+    label="derived data"
+    color=papayawhip //peachpuff //powderblue
+    style="filled,rounded"
+    DerivedDataCreator
+    HfCandTree
+    HfCollTree
+    HfPartTree
+    HfDerivedTable
+  }
+
+  subgraph cluster_legend {
+    label="legend"
+    color=black
+    style=rounded
+    tables_aod_legend -> code_legend -> tables_derived_legend -> output_legend
+    tables_aod_legend -> tables_derived_legend
+    code_legend -> output_legend
+  }
+
+}