Add optional time cluster and line seed combo hit branches

[oksuzian]

Addresses #410.

What this adds

• <name>hits branches: vector-of-vector of a new EventNtupleComboHitInfo struct (inc/ComboHitInfo.hh), parallel to each time cluster and line seed branch, e.g. timeclustershits, protonlineseedshits. Leaves: plane/panel/layer/straw, nStrawHits, nCombo, time, edep, qual, wdist, wres, tres, pos, udir.
• edep leaf on EventNtupleTimeClusterInfo and LineSeedInfo: straw-hit-weighted average hit energy deposition, so the hit branches are not needed for it. Always filled for line seeds; filled for time clusters when comboHitTags is set, -1 otherwise.
• New fcl parameters (all default to off, existing configurations are unchanged):
  • timeclusters.comboHitTags: the combo hit collection the time cluster indices refer to; one tag for all collections, or one per collection.
  • timeclusters.fillHitsFor, lineseeds.fillHitsFor: the output names to write a hit branch for.
• from_mcs-Run1B.fcl sets comboHitTags : [ "makePH" ] (so edep is filled) and leaves the hit branches off, with an example in a comment.
• Dictionary entries, ntuplehelper, regenerated doc/branches.md, and hits on the RooUtil TimeCluster.

Why per-collection rather than a single fillHits flag

Size, measured on one mcs.mu2e.CeEndpointMix1BB-KL.Run1Baw_best_v1_5 file (681 events):

configuration	ntuple size
hit branches off	13.6 MB
all seven hit branches	29.8 MB
all except tphitimeclusters	16.7 MB

tphitimeclustershits alone is 13.0 MB: TimeAndPhiClusterFinder makes ~20x the clusters of the other finders (12259 vs ~550 in this file).

Input availability

The Run-1B -KL mcs files already keep makeSH, makePH and makeSTH in full (KinematicLineOutput is built from Reconstruction.DetailedOutput, which includes LowRecoProducts), and all four time cluster finders and all three line finders run over makePH with FilterHits : false. So this works on the existing mcs files with no reco change. Line seeds carry their own hits and need no external collection.

Guarding against the wrong combo hit collection

A TimeCluster stores bare indices and does not record which collection they refer to. Pointing comboHitTags at makeSH instead of makePH keeps every index in range and silently writes unrelated hits, so besides the bounds check the helper requires the summed nStrawHits of the selected hits to equal TimeCluster::nStrawHits() (skipped if a finder leaves that at 0). With the wrong tag the job now stops with Time cluster has 10 straw hits but its indices select 6 from the combo hit collection: check timeclusters.comboHitTags.

Tests

Built against AnalysisMDC2025 v02_02_00 (Offline v13_38_00), run on the file above:

• For all seven collections (14550 objects): hit branch length equals nhits, summed hit nStrawHits equals the object nStrawHits, and the edep leaf agrees with a recomputation from the hit branch to < 1e-9. Proton time clusters average 0.0027 MeV, inside the ProtonCalTimeClusterFinder 0.002-0.005 window.
• Configuration errors fail at construction with a clear message: unknown name in fillHitsFor (both tables), fillHitsFor without comboHitTags.
• A configuration with timeclusters.fill : false still runs.
• RooUtil: TimeCluster::hits is set when the branch is present and null when it is not.

Open points

• Naming: <name>hits follows trk -> trkhits, which gives timeclustershits. Happy to change.
• Line seed hits are straw-level combo hits (nStrawHits = 1), time cluster hits are panel hits; the same struct is used for both.
• Not done here: validation histograms, pyutils, and RooUtil access to the line seed hits (RooUtil has no line seed support yet).

🤖 Generated with Claude Code

https://claude.ai/code/session_0188sbNRs537Esmwr4EPeNaF

[michaelmackenzie]

This seems to work well for Run 1B. Please turn on the target-origin electron and proton time cluster hit collections (leaving off the tz and tphi cluster hit collections and the line seed collections):

physics.analyzers.EventNtuple.timeclusters.fillHitsFor : [ "timeclusters", "protontimeclusters" ]

Will this work for Run 1A processing where makePH is not added to the output? Is there a way to use the mu2e::IndexMap produced by SelectReco or will this only work for StrawHits?