Output Files

LARDON writes reconstruction results to HDF5 files using the PyTables library. Each run produces one file per subfile processed.

Filename Convention

{detector}_{run}_{sub}{flow_writer_suffix}{outname}.h5

{detector} — detector name (e.g. pdvd, pdhd, cbbot)
{run} — zero-padded run number
{sub} — zero-padded subfile number
{flow_writer_suffix} — encodes the flow and writer numbers (e.g. _40 for flow 4, writer 0)
{outname} — the value passed to -out, prefixed with _ (omitted if not specified)

Examples (from the README):

# lardon -det pdvd -run 39229 -sub 24 -flow 4 -writer 0 -serv 5 -event 11 -out one_event -trk
$LARDON_RECO/pdvd_39229_24_40_s5_one_event.h5

# lardon -det pdvd -run 39246 -sub 6 -flow 0 -writer 0 -out full_example -trk
$LARDON_RECO/pdvd_39246_00_full_example.h5

# lardon -det cbbot -run 37040 -sub 23 -n 10 -trk -out few_events
$LARDON_RECO/cbbot_37040_23_few_events.h5

When running in -job mode, files are written to the current working directory instead of $LARDON_RECO.

HDF5 Table Reference

The file schema is defined in src/lardon/store.py. Tables are created at the root level /.

Always Present

infos — Run metadata

One row per file. Contains basic metadata about the run configuration.

Column	Type	Description
`run`	uint64	Run number
`sub`	string(6)	Subfile identifier
`elec`	string(3)	Electronics type
`n_evt`	uint32	Number of events processed
`process_date`	uint32	Unix timestamp of processing
`n_channels`	uint16	Total number of TPC channels
`sampling`	float32[n_modules]	Sampling rate per module (MHz)
`n_samples`	float32[n_modules]	Number of time samples per module
`n_view`	uint8	Number of wire views
`view_nchan`	float32[n_view]	Number of channels per view
`e_drift`	float32[n_modules]	Drift electric field per module (kV/cm)
`t_lar`	float32[n_modules]	LAr temperature per module (K)

reco — Reconstruction parameters group

A nested HDF5 group (not a table) storing the full contents of reco_parameters.json used for this reconstruction, enabling reproducibility. Stored by save_reco_param() in store.py.

event — Per-event metadata

One row per processed event.

Column	Type	Description
`trigger_nb`	uint32	Hardware trigger number
`trigger_type`	uint16	Trigger type identifier
`time_s`	uint64	Event timestamp (seconds)
`time_ns`	uint64	Event timestamp (nanoseconds)
`charge_time`	float64[n_modules]	Charge readout timestamp per module
`pds_stream_time`	float64	PDS stream start timestamp
`pds_trig_time`	float64	PDS trigger timestamp
`n_sample`	uint32[n_modules]	Number of samples used per module
`n_hits`	uint32[n_view, n_modules]	Number of hits found per view and module
`n_tracks2D`	uint32[n_view]	Number of 2D tracks per view
`n_tracks3D`	uint32	Total number of 3D tracks
`n_single_hits`	uint32	Number of single hits (blips)
`n_ghosts`	uint32	Number of ghost tracks

pedestals — Per-channel pedestal and noise

One row per event. Stores mean and RMS for all TPC channels in global channel ordering.

Column	Type	Description
`raw_mean`	float32[n_tot_channels]	Raw pedestal mean per channel (ADC)
`raw_rms`	float32[n_tot_channels]	Raw pedestal RMS per channel (ADC)
`filt_mean`	float32[n_tot_channels]	Post-filter pedestal mean per channel (ADC)
`filt_rms`	float32[n_tot_channels]	Post-filter pedestal RMS per channel (ADC)

noisestudy — Noise characterization

One row per event. Contains additional noise characterization quantities.

Column	Type	Description
`delta_mean`	float32[n_tot_channels]	Mean shift between pedestal passes
`rms`	float32[n_tot_channels]	RMS from noise study

debug — Per-step timing and memory

One row per event. Records wall-clock time and memory usage for each reconstruction step, useful for profiling.

Column	Type	Description
`event`	uint32	Event number
`trigger`	uint32	Trigger number
`read_data`	float64[n_modules]	Time for raw data reading
`ped_1` / `ped_2` / `ped_3`	float64[n_modules]	Time for each pedestal pass
`fft`	float64[n_modules]	Time for FFT noise filter
`cnr`	float64[n_modules]	Time for coherent noise removal
`hit_f`	float64[n_modules]	Time for hit finding
`trk2D_1` / `trk2D_2`	float64[n_modules]	Time for 2D tracking passes
`stitch2D`	float64[n_modules]	Time for 2D track stitching
`trk3D`	float64[n_modules]	Time for 3D tracking
`stitch3D`	float64	Time for 3D track stitching
`single`	float64[n_modules]	Time for single-hit finding
`output`	float64	Time for output writing
`mem_mod`	float64[n_modules]	Memory usage per module (MB)
`time_mod`	float64[n_modules]	Total time per module (s)
`mem_tot`	float64	Total memory usage (MB)
`time_tot`	float64	Total processing time (s)

TPC Reconstruction Tables (`-trk`)

hits — Reconstructed hits

One row per hit. Hits are the fundamental reconstruction objects — contiguous signal regions on a single wire.

Column	Type	Description
`event`	uint32	Event number
`trigger`	uint32	Trigger number
`ID`	uint32	Global hit identifier
`module`	uint8	Detector module index
`view`	uint8	Wire view index
`channel`	uint16	View-channel number
`daq_channel`	uint16	DAQ channel number
`is_collection`	bool	`True` if this is a collection-view hit
`tdc_start`	int32	Hit start tick
`tdc_stop`	int32	Hit end tick
`tdc_max`	int32	Tick of maximum ADC (positive peak)
`tdc_min`	int32	Tick of minimum ADC (negative peak, induction)
`tdc_zero`	int32	Tick of zero-crossing (induction)
`z`	float32	Drift coordinate of hit (cm, lardon convention)
`x`	float32	Wire position of hit (cm, lardon convention)
`fC_max`	float32	Positive peak amplitude (fC)
`fC_min`	float32	Negative peak amplitude (fC)
`charge_pos`	float32	Integrated positive charge (fC)
`charge_neg`	float32	Integrated negative charge (fC)
`is_free`	bool	`True` if hit is not yet assigned to any track
`match_3D`	int32	ID of matched 3D track (−1 if none)
`match_2D`	int32	ID of matched 2D track (−1 if none)
`match_dray`	int32	ID of matched delta-ray track (−1 if none)
`match_ghost`	int32	ID of matched ghost track (−1 if none)
`match_sh`	int32	ID of matched single hit (−1 if none)

tracks2d — 2D track objects

One row per 2D track. Also includes variable-length arrays trk2d_v0, trk2d_v1, … (one per view) storing the track path points as (x, z, charge, hit_ID) tuples.

Column	Type	Description
`event`	uint32	Event number
`trigger`	uint32	Trigger number
`ID`	uint32	Track identifier
`match_3D`	int32	ID of matched 3D track (−1 if none)
`matched`	int32[n_view]	Matching flags per view
`view`	uint8	View this track was found in
`pos_ini`	float32	Wire position at track start (cm)
`pos_end`	float32	Wire position at track end (cm)
`z_ini`	float32	Drift coordinate at track start (cm)
`z_end`	float32	Drift coordinate at track end (cm)
`chi2_fwd`	float32	Forward-fit chi-squared
`chi2_bwd`	float32	Backward-fit chi-squared
`n_hits_track`	uint16	Number of hits on track
`n_hits_dray`	uint16	Number of delta-ray hits
`dray_total_charge`	float32	Total charge from delta rays (fC)
`slope_ini`	float32	Track slope at start
`slope_end`	float32	Track slope at end
`slope_ini_err`	float32	Uncertainty on start slope
`slope_end_err`	float32	Uncertainty on end slope
`len_straight`	float32	Straight-line track length (cm)
`len_path`	float32	Path-integrated track length (cm)
`track_total_charge`	float32	Total track charge (fC)

tracks3d — 3D track objects

One row per 3D track. Also includes variable-length arrays trk3d_v0, trk3d_v1, … (one per view) storing path points as (x, y, z, dq, ds, hit_ID) tuples.

Column	Type	Description
`event`	uint32	Event number
`trigger`	uint32	Trigger number
`ID`	uint32	Track identifier
`matched_2D`	int32[n_modules, n_view]	Matched 2D track IDs per module and view
`n_matched`	uint32	Number of matched 2D components
`module_ini` / `module_end`	int32	Module index at track start and end
`x_ini`, `y_ini`, `z_ini`	float32	Start-point coordinates (cm)
`t_ini`	int32	Start tick
`x_end`, `y_end`, `z_end`	float32	End-point coordinates (cm)
`t_end`	int32	End tick
`chi2`	float32[n_view]	Fit chi-squared per view
`theta_ini` / `theta_end`	float32	Polar angle at start and end (rad)
`phi_ini` / `phi_end`	float32	Azimuthal angle at start and end (rad)
`n_hits`	uint16[n_view]	Number of hits per view
`len_straight`	float32[n_view]	Straight-line length per view (cm)
`len_path`	float32[n_view]	Path length per view (cm)
`total_charge`	float32[n_view]	Integrated charge per view (fC)
`z0_corr`	float64	Drift position correction from t0 (cm)
`t0_corr`	float32	t0 correction (µs)
`z0_light`	float64	Drift correction from PDS matching (cm)
`t0_light`	float32	t0 from PDS (µs)
`timestamp_light`	float32	PDS cluster timestamp (µs)
`d_match`	float32	Distance used for TPC–PDS matching (cm)
`timestamp`	float64	Event timestamp (µs)
`cluster_ID`	int32	Matched PDS cluster ID (−1 if none)
`is_cathode_crosser`	bool	Whether track crosses the cathode
`is_module_crosser`	bool	Whether track crosses a module boundary
`is_anode_crosser`	bool	Whether track exits through the anode
`exit_point`	float32[3]	Extrapolated anode-exit point (cm)

single_hits — Isolated charge depositions (blips)

One row per single hit (blip) candidate — isolated charge depositions matched across views but not assigned to any track.

Column	Type	Description
`event`	uint32	Event number
`ID`	uint32	Single-hit identifier
`module`	uint8	Module index
`n_hits`	uint32[n_view]	Number of wire hits per view
`hit_IDs`	int32[n_view, max_per_view]	Hit IDs per view
`charge_pos`	float32[n_view]	Positive charge per view (fC)
`charge_neg`	float32[n_view]	Negative charge per view (fC)
`tdc_start` / `tdc_stop`	int32[n_view]	Time extent per view (ticks)
`x`, `y`, `z`	float64	3D position (cm)
`d_bary_max`	float64	Max barycenter distance (cm)
`d_track_3D`	float64	Distance to nearest 3D track (cm)
`d_track_2D`	float64	Distance to nearest 2D track (cm)
`timestamp`	float64	Event timestamp (µs)
`cluster_ID`	int32	Matched PDS cluster ID (−1 if none)
`Z_light`	float64	Drift position from light timing (cm)

ghost — Ghost track objects

One row per ghost track, with an associated variable-length array ghost_tracks storing path points as (x, y, z, dq, ds, hit_ID) tuples.

Column	Type	Description
`event`	uint32	Event number
`match_3D`	uint32	ID of the real 3D track this ghost corresponds to
`match_2D`	uint32	ID of the 2D track this ghost was found from
`x_anode`, `y_anode`, `z_anode`	float32	Anode position (cm)
`theta` / `phi`	float32	Track angles (rad)
`n_hits`	uint16	Number of hits
`total_ghost_charge`	float32	Charge on ghost track (fC)
`total_track_charge`	float32	Charge on parent real track (fC)
`z0_corr` / `t0_corr`	float64 / float32	Drift correction from t0
`d_min`	float32	Minimum distance to parent track (cm)

PDS Reconstruction Tables (`-pds`)

pds_infos — PDS run metadata

One row per file. Parallel to the TPC infos table but for the photon detection system.

Column	Type	Description
`run`	uint16	Run number
`sub`	string(6)	Subfile identifier
`n_evt`	uint32	Number of events processed
`n_channels`	uint16	Total number of PDS channels
`sampling`	float32	PDS sampling rate (MHz)
`n_samples`	float32	Number of samples per event
`e_drift`	float32[n_modules]	Drift field per module (kV/cm)
`t_lar`	float32[n_modules]	LAr temperature per module (K)

pds_event — PDS per-event data

One row per event.

Column	Type	Description
`event`	uint32	Event number
`trigger_nb`	uint32	Trigger number
`stream_time`	float64	PDS stream start time
`trig_time`	float64	PDS trigger time
`n_sample`	uint32	Number of PDS samples
`n_peak`	uint32[n_pds_channels]	Number of peaks per channel
`n_cluster`	uint32	Number of PDS clusters
`chan_time_offset`	float64[n_pds_channels]	Per-channel timing offset (µs)

pds_pedestals — PDS pedestal and noise

One row per event.

Column	Type	Description
`raw_mean` / `raw_rms`	float32[n_pds_channels]	Pre-filter pedestal mean and RMS
`filt_mean` / `filt_rms`	float32[n_pds_channels]	Post-filter pedestal mean and RMS

pds_peaks — Reconstructed PDS peaks

One row per peak.

Column	Type	Description
`event`	uint32	Event number
`ID`	uint32	Peak identifier
`glob_ch`	uint32	Global PDS channel number
`channel`	uint32	Local channel number
`start` / `stop`	int32	Peak time window (PDS ticks)
`max_t`	int32	Tick of peak maximum
`charge`	float64	Integrated charge (ADC·ticks)
`max_adc`	float64	Peak ADC amplitude
`cluster_ID`	int32	Matched PDS cluster ID (−1 if none)
`timestamp`	float64	Peak timestamp (µs)

pds_clusters — PDS light clusters

One row per cluster, plus variable-length arrays pds_peakID_clusters listing the peak IDs in each cluster, and charge_pds_match_vol<N> per drift volume storing TPC–PDS matching results as

(PeakID, glob_ch, distance, charge, max_adc, x_impact, y_impact, z_impact, x_closest, y_closest, z_closest, closestIsExtrapolated)

Column	Type	Description
`event`	uint32	Event number
`ID`	uint32	Cluster identifier
`size`	uint32	Number of peaks in cluster
`start_t` / `stop_t`	int32	Cluster time window (PDS ticks)
`timestamp`	float64	Cluster timestamp (µs)
`match_trk3D`	int32[n_drift_volumes]	Matched 3D track ID per volume
`match_single`	int32	Matched single hit ID (−1 if none)

Charge Pulsing Tables (`-pulse`)

pulse — Pulse fit results

One row per channel per event, storing the number of positive and negative pulses found.

Column	Type	Description
`event`	uint32	Event number
`view` / `channel` / `daq_channel`	uint8 / uint16 / uint16	Channel identifiers
`n_pulse_pos`	uint16	Number of positive pulses found
`n_pulse_neg`	uint16	Number of negative pulses found

Also includes variable-length arrays pos_pulse and neg_pulse storing fit parameters as (start, tmax, vmax, A, Aerr, tau, tauerr, area, fit_area, rchi2) per pulse.

waveform — Averaged pulse waveforms

One row per channel. Stores mean and standard deviation of aligned pulse waveforms (60-sample windows) for positive and negative pulses.

Column	Type	Description
`view` / `channel` / `daq_channel`	uint8 / uint16 / uint16	Channel identifiers
`pos_mean` / `pos_std`	float32[60]	Mean and std of positive pulse shape
`neg_mean` / `neg_std`	float32[60]	Mean and std of negative pulse shape

Coordinate System in Output

By default, LARDON stores positions in lardon coordinates (see Coordinate Conventions). This is controlled by the "store": {"coord": "lardon"} key in reco_parameters.json.

"store": {
    "coord": "lardon"
}

The coord parameter can also be set to produce LArSoft-compatible coordinates when integrating with other DUNE software tools.

Get Started

Configuration

Running LARDON

Reconstruction Pipeline

Visualization & Output

Filename Convention

HDF5 Table Reference

Always Present

TPC Reconstruction Tables (`-trk`)

PDS Reconstruction Tables (`-pds`)

Charge Pulsing Tables (`-pulse`)

Coordinate System in Output

Build docs developers (and LLMs) love

Get Started

Configuration

Running LARDON

Reconstruction Pipeline

Visualization & Output

​Filename Convention

​HDF5 Table Reference

​Always Present

​TPC Reconstruction Tables (-trk)

​PDS Reconstruction Tables (-pds)

​Charge Pulsing Tables (-pulse)

​Coordinate System in Output

Build docs developers (and LLMs) love

Filename Convention

HDF5 Table Reference

Always Present

TPC Reconstruction Tables (`-trk`)

PDS Reconstruction Tables (`-pds`)

Charge Pulsing Tables (`-pulse`)

Coordinate System in Output