hipo-explorer¶

Interactive terminal-based explorer for browsing HIPO file contents.

Synopsis¶

hipo-explorer [options] <file.hipo> [...]
hipo-explorer --compare <fileA.hipo> <fileB.hipo>

Description¶

hipo-explorer provides an interactive TUI (Terminal User Interface) for browsing HIPO files. It supports multi-file chains with seamless file-boundary navigation, event topology search using CLAS12 EventFilter syntax, a data quality dashboard, computed columns from math expressions, cross-bank referencing via pindex, and dual-file comparison with statistical tests.

Options¶

Layout¶

The explorer has a panel-based layout with four focus areas:

• Sidebar — Bank list with row counts; navigate with j/k, select with Enter
• Table — Event data with color-coded types; the main workspace
• Stats — Column statistics for the selected bank (min, max, mean, stddev)
• Cross-Ref — Linked bank view via pindex (toggled with R)

Press Tab to cycle focus between panels, Shift+Tab to reverse.

Interactive Controls¶

Navigation¶

Banks & Data¶

Filtering¶

Table¶

Bookmarks¶

Export & Tools¶

Multi-File Chains¶

Multiple files can be loaded as a single logical dataset. Navigation is seamless across file boundaries — the status bar shows the current file and global event index.

# Multiple positional arguments
hipo-explorer run_006616.hipo run_006617.hipo run_006618.hipo

# Shell glob
hipo-explorer /data/run_*.hipo

# File list (one path per line)
hipo-explorer -L my_runs.txt

When multiple files are loaded, the status bar displays:

[3/47] run_006618.hipo  Event 15234 / 2340000

The background scanner processes all files in the chain for statistics and histograms.

Event Topology Search¶

Press T to open the topology search dialog. This uses CLAS12 EventFilter syntax to find events by particle content.

Syntax¶

Particle PDG codes separated by colons:

11:211:-211:2212

This searches for events containing exactly: e⁻ π⁺ π⁻ p.

Wildcards¶

Matching Modes¶

• Exact (default) — Event must contain exactly the specified particles
• Inclusive (append *) — Event must contain at least the specified particles

Examples¶

The live preview shows particle symbols as you type. The topology filter composes with expression and bank-presence filters (AND logic).

Data Quality Dashboard¶

Press Q to open a full-screen data quality overview that scans all events in the chain.

Sections¶

• File Summary — Number of files, total events, bank count
• Bank Occupancy — Percentage of events where each bank has data
• Particle Rates — PDG-labeled particle counts from REC::Particle
• Multiplicity — Mean and max particle multiplicity per event
• Data Health — NaN/Inf counts, zero-momentum particles, negative beta, status=0
• Vertex Distribution — Mean, stddev, min, max of vz from REC::Particle
• Warnings — Auto-generated alerts for anomalies

Controls¶

Computed Columns¶

Press C to add custom columns computed from math expressions.

Built-in Physics Quantities¶

When the current bank has the required columns, built-in quantities are available:

Custom Expressions¶

Write expressions using column names from the current bank:

pt=sqrt(px*px+py*py)

Available functions: sqrt, sin, cos, acos, atan2, abs, log, exp, pow, pdg_mass

Cross-Reference Mode¶

Press R to toggle cross-reference mode. This links rows between banks using pindex columns — for example, following REC::Track.pindex to the corresponding row in REC::Particle.

When active, selecting a row in the table highlights the linked row in the cross-reference panel. Use arrow keys in the cross-reference panel to navigate linked rows.

Histogram View¶

Press d to view a full-screen histogram of the selected column. Data comes from the background scanner (all events) when available, or an inline sample.

Integer columns show value-frequency bar charts with PDG labels. Float columns show binned histograms.

Dual-File Comparison¶

Use --compare to open two files side-by-side with synchronized navigation and statistical comparison.

hipo-explorer --compare sim.hipo data.hipo

Layout¶

The screen is split into left (File A) and right (File B) panels, each showing a compact data table and statistics. A bottom panel shows column-by-column comparison results.

Controls¶

Statistical Comparison¶

The comparison panel shows for each column:

• Mean A / Mean B — Mean values from each file
• Diff% — Percentage difference between means
• KS — Kolmogorov-Smirnov test statistic
• Status — OK (compatible) or DIFF (significant difference)

Examples¶

Basic Usage¶

# Browse a single file
hipo-explorer data.hipo

# Start with a specific bank selected
hipo-explorer -b REC::Particle data.hipo

Multi-File Chain¶

# Glob pattern
hipo-explorer run_*.hipo

# File list
hipo-explorer -L my_runs.txt

Comparison¶

# Compare simulation vs data
hipo-explorer --compare sim.hipo data.hipo

# Compare with a specific bank
hipo-explorer --compare -b REC::Particle sim.hipo data.hipo

Typical Workflow¶

1. Launch with hipo-explorer data.hipo
2. Press b to fuzzy-search for a bank (e.g. REC::Particle)
3. Use n/p to navigate events
4. Press T and type 11:211:-211:2212 to filter for e⁻π⁺π⁻p topology
5. Press d to view column distributions
6. Press C to add computed columns (e.g. invariant mass)
7. Press R to cross-reference with linked banks
8. Press Q to check data quality across all events
9. Press e to export interesting events as CSV

See Also¶

• hipo-info - Non-interactive file information
• hipo-dump - Export data to files
• hipo-comparator - Batch file comparison
• Expression Syntax - Filter expression reference