Skip to content

Output File Contents

Jump to bottom
jdkio edited this page Jun 17, 2026 · 6 revisions

Output File Contents

Last revised: 2026-06-16

This page summarizes the ROOT trees written by dune-tms reconstruction output. Branch names below were checked against src/TMS_TreeWriter.cpp.

Units and conventions

dune-tms generally follows CLHEP-style conventions:

  • positions/distances: usually mm
  • energies and momenta: usually MeV
  • 4-vectors: usually [x, y, z, t] for positions and [px, py, pz, E] for momenta
  • track Length / Length_3D: areal density, not plain geometric length, in g/cm^2

In Reco_Tree, time appears explicitly in TimeSliceStartTime and TimeSliceEndTime, and implicitly as the 4th component of the stored four-position arrays such as StartPos, EndPos, and TrackHitPos.

Some timing branches come from different parts of the reconstruction/readout chain. Check the producing code if exact timing units matter for a precision study.

Main reconstruction output

Running ConvertToTMSTree.exe produces a TMS reconstruction ROOT file. The exact filename depends on the command/output path, but historical examples often look like:

*_TMS_RecoCandidates_Hough_Cluster1.root

The main trees are:

Tree Page Purpose
Reco_Tree Reco_Tree Reconstructed 3D tracks, track-hit information, charge/momentum/range estimates, Kalman information
Truth_Spill Truth_Spill Authoritative spill-level particle and vertex truth table
Truth_Info Truth_Info Slice/reco-associated truth summaries, especially matching reconstructed tracks back to Truth_Spill particles
Line_Candidates Line_Candidates Lower-level Hough line, cluster, and hit-candidate reconstruction information
Metadata Metadata dune-tms version, geometry tag/commit, geometry counts, fiducial bounds

Which tree should I use?

For reconstructed tracks

Use Reco_Tree.

This is the main analysis tree for reconstructed TMS tracks: start/end positions, hit positions, energy estimates, charge, momentum, Kalman nodes, and time-slice boundaries.

For particle and vertex truth

Use Truth_Spill.

Truth_Spill is the authoritative place for full particle-by-particle and vertex-by-vertex truth. It stores nTrueParticles, particle PDG, TrackId, Parent, VertexID, ParticleRunNo, VertexGlobalID, birth/death positions, TMS/LAr boundary information, path lengths, fiducial flags, and the TrueVtx* vertex table.

For reco-to-truth matching

Use Truth_Info, but only as the bridge between reconstruction and spill truth.

The important branches are things like:

  • RecoTrackPrimaryParticleIndex
  • RecoTrackSecondaryParticleIndex
  • RecoTrackTrueVisibleEnergy
  • RecoTrackPrimaryParticleTrueVisibleEnergy
  • RecoTrackSecondaryParticleTrueVisibleEnergy

The particle indices point into the Truth_Spill particle arrays for the same spill. New analyses should avoid relying on duplicated particle-truth payloads in Truth_Info; use Truth_Spill for the full particle record.

For debugging reconstruction internals

Use Line_Candidates.

This tree is useful for studying Hough lines, per-view candidates, clusters, and reconstructed hits before they are combined into the higher-level Reco_Tree tracks.

For geometry/version provenance

Use Metadata.

This tree records dune-tms version numbers, geometry git tag/branch/commit, number of scintillator/steel planes, and TMS fiducial boundaries.

Entry alignment

Reco_Tree, Truth_Info, and Line_Candidates are filled for reconstructed events/time slices.

Truth_Spill is filled at the spill level. It includes:

  • TruthInfoIndex: index of the corresponding first Truth_Info entry
  • TruthInfoNSlices: number of Truth_Info slices associated with that spill

Use these branches when connecting spill-level truth to slice-level reconstructed quantities.

Run and vertex provenance

For human-facing/event-level use, top-level RunNo is normalized so rock-style offsets are removed when present.

For stable truth provenance, use the raw per-particle/per-vertex run branches in Truth_Spill:

  • ParticleRunNo
  • TrueVtxRunNo
  • VertexGlobalID
  • TrueVtxGlobalID

VertexGlobalID is built from ParticleRunNo and VertexID. TrueVtxGlobalID is built from TrueVtxRunNo and TrueVtxID.

Readout output

Some workflows may also produce readout-level ROOT files, historically named like:

*_TMS_Readout.root

This page currently focuses on the reconstruction output written by TMS_TreeWriter. Readout-output documentation should be added separately after checking TMS_ReadoutTreeWriter.

Clone this wiki locally