Getting Started¶

This guide walks through common workflows with hipo-utils.

Basic File Inspection¶

View File Information¶

# Summary of file contents
hipo-info data.hipo

# List all bank names
hipo-info --banks-only data.hipo

# Show full schema for all banks
hipo-info --schema data.hipo

# Get statistics per bank
hipo-info --stats data.hipo

# Get per-column statistics (min/max/mean/stddev)
hipo-info --column-stats data.hipo

Interactive Exploration¶

# Launch interactive explorer
hipo-explorer data.hipo

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

In the explorer, use ? or h to show keyboard shortcuts.

Exporting Data¶

Export to CSV¶

# Export specific bank to CSV
hipo-dump -b REC::Particle -f csv data.hipo > particles.csv

# Export specific columns only
hipo-dump -b REC::Particle -c pid,px,py,pz -f csv data.hipo > momenta.csv

# Export with event indices
hipo-dump -b REC::Particle -f csv -E data.hipo > particles_with_events.csv

Export to JSON¶

hipo-dump -b REC::Particle -f json data.hipo > particles.json

Filtering Events¶

By Expression¶

# Filter events with electrons (pid == 11)
hipo-filter -e "REC::Particle.pid == 11" -o electrons.hipo data.hipo

# Filter by momentum range
hipo-filter -e "REC::Particle.p BETWEEN 0.5 AND 2.0" -o filtered.hipo data.hipo

# Multiple particle types
hipo-filter -e "REC::Particle.pid IN (11, -11)" -o leptons.hipo data.hipo

By Bank Presence¶

# Keep only events that have REC::Track data
hipo-filter -b REC::Track -o with_tracks.hipo data.hipo

See Expression Syntax for full details.

Converting to ROOT¶

# Convert to ROOT TTree
hipo2root -o output/ data.hipo

# Parallel conversion of multiple files
hipo2root -j4 -m combined.root data*.hipo

# Include only specific banks
hipo2root -I REC::Particle,REC::Calorimeter data.hipo

File Operations¶

Merge Files¶

# Combine multiple HIPO files sequentially
hipo-merge -o combined.hipo run*.hipo

# Event-by-event bank content merging
hipo-merge -o merged.hipo --merge-banks sim1.hipo sim2.hipo

Split Large Files¶

# Split into 10000-event files
hipo-split -n 10000 -o output_dir/ large.hipo

Extract Bank Subset¶

# Keep only REC banks
hipo-slice -I "REC::*" -o rec_only.hipo data.hipo

# Remove RAW banks
hipo-slice -E "RAW::*" -o no_raw.hipo data.hipo

Validation¶

# Validate file integrity
hipo-validate data.hipo

# Strict mode (warnings become errors)
hipo-validate --strict data.hipo

# Quick check with summary only
hipo-validate --summary data.hipo

Statistics and Analysis¶

# Compute column statistics
hipo-stats -b REC::Particle data.hipo

# With ASCII histograms
hipo-stats -b REC::Particle -H data.hipo

# Correlation matrix
hipo-stats -b REC::Particle -c px,py,pz -C data.hipo

Comparison¶

# Compare two files
hipo-comparator file1.hipo file2.hipo

# Compare with higher tolerance for floats
hipo-comparator -t 1e-4 file1.hipo file2.hipo

# Quick summary
hipo-comparator --summary file1.hipo file2.hipo