TPC: add ITS-TPC combined-momentum sampling trigger

[miranov25]

Hello @matthias-kleiner and @shahor02,

Here is a pull request I discussed last week in the TPC distortion meeting. @matthias-kleiner, are you on holidays now, or could you run one small test at GSI?

===
Add a third sampling trigger bit for tracks with matched ITS–TPC combined momentum. The new trigger applies the Tsallis sampling function to the combined-track pT instead of the TPC-only pT and stores the corresponding weight as weight_ITSTPC.

This extends the existing trigger mask scheme:
0x1: minimum-bias sampling
0x2: Tsallis sampling using TPC-only track pT
0x4: Tsallis sampling using ITS–TPC combined-track pT

The output condition is updated so that tracks selected by the new ITS–TPC sampling path are written even when they are not selected by the existing TPC-only or minimum-bias triggers.

Motivation:
Sampling only on TPC-only momentum can bias correlated observables such as qpt_TPC - qpt_Comb. The new trigger provides a dedicated sampled stream for combined-track performance studies while preserving the existing TPC-only and minimum-bias sampling streams.

[miranov25]

PHASE_13_11_DF v2.5 — TPCTimeSeries combined-momentum Tsallis trigger

Subproject: samplingAI / O2 TPC skimmed time-series sampling interface
Reviewer / drafter: GPT3:sampling
Status: PROPOSED PATCH — for review and approval before production use
Target file: Detectors/TPC/workflow/src/TPCTimeSeriesSpec.cxx
Patch file: PHASE_13_11_DF_v2_5_TPCTimeSeries_combined_trigger.patch

1. Motivation

Current skimmed unbinned output has two trigger-mask bits relevant for sampling:

Bit	Meaning before this patch
0x1	flat minimum-bias stream, controlled by factorMinBias = 0.1 * sampling-factor
0x2	Tsallis downsampling stream using the TPC-only track momentum, tracksTPC[iTrk].getPt()

The current bias investigation needs a third stream: a Tsallis sampling decision based on the combined ITS-TPC track momentum. This provides a direct comparison channel for the correlated-observable problem:

qpt_TPC - qpt_Comb  vs  qpt_Comb

where sampling only on the TPC-only quantity can bias the observed joint distribution and residual structure.

2. Proposed change

Add trigger-mask bit 0x4 for tracks accepted by a Tsallis sampling decision evaluated on the matched ITS-TPC combined track momentum:

tracksITSTPC[idxITSTPC.front()].getPt()

The patch keeps the existing 0x1 and 0x2 semantics unchanged.

New trigger-mask contract:

Bit	Meaning after this patch
0x1	flat minimum-bias stream
0x2	Tsallis stream sampled with TPC-only pT
0x4	Tsallis stream sampled with ITS-TPC combined pT

3. Output schema change

The existing branch

weight

remains the correction weight associated with the TPC-only Tsallis decision (0x2).

The patch adds a new branch:

weight_ITSTPC

This is the correction weight associated with the combined ITS-TPC Tsallis decision (0x4).

For analyses using triggerMask & 0x4, the corresponding sampling weight is weight_ITSTPC, not the legacy weight branch.

4. Selection behavior

Before the patch, a track was written when:

writeData || minBiasOk

After the patch, a track is written when:

writeData || writeDataITSTPC || minBiasOk

where:

• writeData is the existing TPC-only Tsallis decision.
• writeDataITSTPC is the new ITS-TPC combined-momentum Tsallis decision.
• minBiasOk is the existing flat minimum-bias decision.

The new combined trigger is evaluated only if hasITSTPC is true. Tracks without an ITS-TPC match cannot fire bit 0x4.

5. Backward-compatibility notes

1. Existing bits 0x1 and 0x2 are unchanged.
2. Existing branch weight is unchanged.
3. The new branch weight_ITSTPC is additive.
4. When sample-unbinned-tsallis=false, the code preserves the current full-write behavior via writeData=true; the new 0x4 bit is not populated in that mode. The combined trigger is therefore meaningful for Tsallis-sampled skim production.

6. Validation requested before production

Minimum checks:

1. Compile TPCTimeSeriesSpec.cxx in the O2 build.
2. Run a short skim production with --sample-unbinned-tsallis true.
3. Confirm that the output tree contains triggerMask, weight, and weight_ITSTPC.
4. Check trigger counts:

triggerMask & 0x1   // MB stream
triggerMask & 0x2   // TPC-only Tsallis stream
triggerMask & 0x4   // combined ITS-TPC Tsallis stream

5. Verify that all entries with triggerMask & 0x4 have hasITSTPC == true.
6. Compare the diagnostic maps:

qpt_TPC - qpt_Comb  vs  qpt_Comb

for:

• MB/reference stream (0x1),
• TPC-only Tsallis stream (0x2),
• combined-momentum Tsallis stream (0x4).

7. Known limitation / deliberate non-change

This patch uses the same sampling-factor / factorPt for the TPC-only and combined-momentum Tsallis triggers. It does not introduce a separate option such as sampling-factor-combined.

A separate factor can be added later if the validation shows that the combined stream needs an independent rate.

8. Approval question - answered by the team

Approve this as the first C++-side test patch for the sampling-bias study?

Suggested approval scope:

[ ] Approve for local emulation / test production only - done by AI team and Matthias
[ ] Approve for wider validation production - test at GSI requested
[ ] Request changes before applying