Skip to main content

Quick start

This is a five-minute tour. It assumes you have hipoq on your PATH (see installation) and a file to point it at — the examples use rec.hipo.

Command grammar

Every invocation is hipoq <command> <FILE> [options] — the command comes first, then the input. FILE can be a single file, a directory, or a glob like "run/*.hipo" (quote it so the shell doesn't expand it).

1. See what's in the file​

hipoq info rec.hipo
input:   rec.hipo
files:   1
events:  100000
records: 42
schemas: 18

on disk: 24.1 MiB

Then list the banks that actually carry data, and how many rows they have:

hipoq banks rec.hipo --max 5000     # sample the first 5000 events

2. Look at the first few events​

hipoq head rec.hipo -n 3

Each line shows which banks are present in that event and their row counts (REC::Particle(4), REC::Calorimeter(9), …). Add --bank to also print that bank's rows:

hipoq head rec.hipo -n 3 --bank REC::Particle

3. Project columns​

scan is the workhorse — pick a bank and some columns across an event range:

hipoq scan rec.hipo --bank REC::Particle --cols pid,px,py,pz --events 0..100

Add computed columns with --expr (a NAME=EXPRESSION, or a bare preset like p or theta_deg):

hipoq scan rec.hipo --bank REC::Particle --cols pid --expr p --expr theta_deg

Decode particle ids to symbols with --pdg, and switch output format for piping:

hipoq scan rec.hipo --bank REC::Particle --cols pid,px,py,pz --pdg
hipoq scan rec.hipo --bank REC::Particle --cols pid,px --format ndjson | jq .

4. Ask a question​

count with a --where cut answers "how many events…":

# events with at least two electrons
hipoq count rec.hipo --where "count(REC::Particle.pid == 11) >= 2"

# events with a > 1.5 GeV electron whose calorimeter deposit exceeds 1.5 GeV
hipoq count rec.hipo --where "REC::Particle.pid == 11 && p() > 1.5 && REC::Calorimeter.energy > 1.5"

5. Make a smaller file​

Extract the events you care about into a new HIPO file with skim:

hipoq skim rec.hipo electrons.hipo --where "REC::Particle.pid == 11"

Or take a quick subsample / split for batch jobs:

hipoq sample rec.hipo small.hipo --fraction 0.01   # ~1% of events
hipoq split  rec.hipo chunks/ --chunks 8           # 8 files for 8 workers

6. Browse interactively​

When you want to click around instead of query, open the terminal UI:

hipoq tui rec.hipo

Arrow keys page through events, Tab switches panes, / filters live, and x opens the pindex cross-reference panel.

Next steps​