From a9e6385d1c0643af219aa0791ab399785ef771e0 Mon Sep 17 00:00:00 2001 From: Igor Altsybeev Date: Fri, 13 Nov 2026 13:07:55 +0100 Subject: [PATCH] added description of bcOccup tables in evSel chapter; mention also crossROF for pp 2026 --- docs/analysis-tools/EventSelection.md | 84 ++++++++++++++++++++++----- 1 file changed, 69 insertions(+), 15 deletions(-) diff --git a/docs/analysis-tools/EventSelection.md b/docs/analysis-tools/EventSelection.md index 4881272f..119252a3 100644 --- a/docs/analysis-tools/EventSelection.md +++ b/docs/analysis-tools/EventSelection.md @@ -5,20 +5,31 @@ title: Event Selection # Table of contents: -* [Event selection service wagon](#event-selection-service-wagon) -* [Timestamp module](#timestamp-module) -* [Event selection module](#event-selection-module) - * [Basic usage in user tasks](#basic-usage-in-user-tasks) - * [Trigger aliases](#trigger-aliases) - * [Event selection criteria](#event-selection-criteria) - * [Time Frame and ITS ROF border cuts](#time-frame-and-its-rof-border-cuts) - * [Occupancy estimation](#occupancy-estimation) - * [Rejection of events with dead zones in ITS](#rejection-of-events-with-dead-zones-in-its) - * [Usage of RCT flags](#usage-of-rct-flags) - * [Found bunch crossings](#found-bunch-crossings) - * [Configurables](#configurables) - * [Event selection decisions for Run 2](#event-selection-decisions-for-run-2) -* [Luminosity module](#luminosity-module) +- [Table of contents:](#table-of-contents) +- [Event selection service wagon](#event-selection-service-wagon) +- [Timestamp module](#timestamp-module) +- [Event selection module](#event-selection-module) + - [Basic usage in user tasks](#basic-usage-in-user-tasks) + - [Trigger aliases](#trigger-aliases) + - [Event selection criteria](#event-selection-criteria) + - [Time Frame and ITS ROF border cuts](#time-frame-and-its-rof-border-cuts) + - [Time Frame borders](#time-frame-borders) + - [ITS Readout Frame borders](#its-readout-frame-borders) + - [Integration into event selection](#integration-into-event-selection) + - [Occupancy estimation](#occupancy-estimation) + - [Occupancy estimators](#occupancy-estimators) + - [Occupancy selection bits](#occupancy-selection-bits) + - [Occupancy wrt bunch crossings](#occupancy-wrt-bunch-crossings) + - [Discussion](#discussion) + - [Rejection of events with dead zones in ITS](#rejection-of-events-with-dead-zones-in-its) + - [Problem](#problem) + - [Using special event selection bits](#using-special-event-selection-bits) + - [Usage of RCT flags](#usage-of-rct-flags) + - [Found bunch crossings](#found-bunch-crossings) + - [Configurables](#configurables) + - [Event selection decisions for Run 2](#event-selection-decisions-for-run-2) + - [Remarks](#remarks) +- [Luminosity module](#luminosity-module) # Event selection service wagon @@ -111,6 +122,8 @@ In general, one has to follow the following steps: The `sel8` event selection bit is a logical _and_ between the `kIsTriggerTVX` bit (based on FT0A & FT0C requirement, with time-based constraints on the vertex position), and (since April 2024) `kNoTimeFrameBorder` and `kNoITSROFrameBorder` bits - see [below](#integration-into-event-selection). + > [!NOTE] + > An exception for the 2026 pp data: the `kNoITSROFrameBorder` bit was excluded from `sel8` for this period because reconstruction was performed with the ITS cross-ROF mode enabled, which should almost completely eliminate the ITS ROF border effect. Note, however, that the ROF border effect is still present for the MFT readout frames! * run your tasks in stack with event-selection-service task: ``` bash @@ -332,7 +345,7 @@ _Notes:_ - Both occupancy estimators are pre-calculated per each collision in the event selection routine, [EventSelectionModule.h](https://github.com/AliceO2Group/O2Physics/blob/daily-20251029-0000/Common/Tools/EventSelectionModule.h#L1361). - In the occupancy calculation, multiplicities of nearby collisions are "weighted" according to their time separation from a collision-of-interest, to reflect the "severity" of their influence on that collision - Estimators return `-1` if a given collision is close to Time Frame borders (so, not enough information for the occupancy calculation, while we need information within -40 µs...+100 µs time range wrt a given collision), event loss ~1.2%. - +- An additional column was added to evSel table in [Dec 2025](https://github.com/AliceO2Group/O2Physics/pull/14202) - the **median time** of occupancy from nearby events (i.e. the dt at which the counter of occupancy around a given event in a predefined time window becomes >=0.5 from the total occupancy), as discussed [here](https://indico.cern.ch/event/1568262/#1-study-of-the-tpc-occupancy-e). The getter: `occupancyMedianTime()`. ### Occupancy selection bits @@ -355,6 +368,47 @@ if (col.selection_bit(o2::aod::evsel::kNoCollInTimeRangeNarrow)) { /* do analysi ``` +### Occupancy wrt bunch crossings + +The occupancy can also be obtained per **bunch crossing** (e.g. for UPC studies), with the same estimators, time window and thresholds as for collisions (since [PR 12/11/2026](https://github.com/AliceO2Group/O2Physics/pull/18689)). Two tables are produced by the event selection service (only if subscribed to by a task): +- `aod::BcOccs`: joinable with `aod::BCs`, one row per BC of the BC table; +- `aod::BcOccsAll`: not joinable, values are calculated for every BC of the Time Frames in the dataframe (also BCs not stored in AO2D). The table is large (114048 rows per 32-orbit TF), so request it only when needed. + +The same getters and bits described for per-collision occupancy can also be used for per-BC occupancy studies. The following additional getters are available: + +| **Getter** | **Meaning** | +|------------|-------------| +| `occupancyFlags_bit(bit)` | `kNoCollInTimeRangeNarrow/Strict/Standard`, `kNoCollInRofStrict/Standard`, `kNoHighMultCollInPrevRof`, `kUpcMode` (enum `aod::bcocc::BcOccupancyFlags`) | +| `numCollsInBC()` | number of collisions found in this BC | +| `numCollsInRof()` | number of collisions found in the ITS ROF of this BC | + +**Differences from the per-collision values:** +- all collisions found in the BC are excluded from its occupancy (for a collision, only the collision itself is excluded); +- no vZ for BCs, so the close-vZ veto in `kNoCollInRofStandard` is not applied; +- the flags are stored in a separate 8-bit bitmap: bit numbers differ from `aod::evsel`; +- `kUpcMode` (filled for all BCs): the ITS ROF of this BC has no collisions, or has collisions reconstructed in the UPC mode of ITS (`Vertex::Flags::UPCMode`). + +**Usage:** + +``` c++ +// occupancy for BCs of the BC table +void process(soa::Join const& bcs) { + for (const auto& bc : bcs) { + if (bc.trackOccupancyInTimeRange() >= 0 && bc.occupancyFlags_bit(o2::aod::bcocc::kNoCollInTimeRangeNarrow)) { /* do analysis */ } + } +} +``` +For `aod::BcOccsAll`, a fast lookup by global BC is provided: +``` c++ +// occupancy for any BC of the TFs in the DF: O(1) lookup by global BC, no search and no CCDB needed +aod::bcocc::BcOccAllIndex bcOccAllIndexed(bcOccsAll); // once per dataframe +if (bcOccAllIndexed.contains(bc.globalBC())) { + auto occ = bcOccAllIndexed[bc.globalBC()]; // iterator of aod::BcOccsAll + bool isUpcModeRof = occ.occupancyFlags_bit(o2::aod::bcocc::kUpcMode); // example; other occupancy getters can be used as well +} +``` + + ### Discussion More details on occupancy in Pb-Pb can be found in the [report at the APW 2024](https://indico.cern.ch/event/1462154/#7-occupancy-effects), where the concepts and observations are explained (while some figures and indicated values might be outdated).