Skip to main content

Counting & statistics

Three commands turn a file into numbers: how many events match a cut, the summary statistics of a column, and its distribution.

count​

Count events, optionally under a --where cut. This is the parallel command — it uses the -j worker threads.

hipoq count rec.hipo                                   # total events
hipoq count rec.hipo --where "REC::Particle.pid == 11" # events with an electron
FlagMeaning
--where Ecount only events passing the cut (repeatable, ANDed)

Multiplicity cuts​

Because the expression language has count(...), you can count events by how many rows match a per-row condition:

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

# exclusive topology: exactly one electron and exactly one proton
hipoq count rec.hipo --where "count(REC::Particle.pid==11)==1 && count(REC::Particle.pid==2212)==1"

Interaction with --require​

A global -r/--require drops events lacking the named banks before the cut, and count reports the number of events actually yielded — so any such drop is visible rather than silent:

hipoq count "skim/*.hipo" -r REC::Particle -r REC::Event

Getting the matching indices out — --list​

hipoq count run.hipo --where "REC::Particle.pid == 11" --list > electrons.txt

Prints the global index of every matching event, one per line, instead of the count. Feed it back with skim --events-from: the search is the expensive pass, and this is how you pay for it once.

Global — the space dump --events and tail address, not the filtered position that streaming enumerates. A list produced one way and consumed the other would name different events while looking perfectly valid, so --list walks indices sequentially and applies -r itself.

stats​

Min / max / mean / std / count for one column across the whole chain — one value per row, so either a scalar or a single element of an array column.

hipoq stats rec.hipo --col REC::Particle.chi2pid
hipoq stats rec.hipo --col REC::Track.cov[0]        # one element of an array
REC::Particle.chi2pid
  count  412883
  min    -8.9971
  max     9.4210
  mean   -0.0132
  std     1.8875
FlagMeaning
--col C(required) the scalar column, BANK.COLUMN or a bare name
--bank Bthe bank — needed only when --col is a bare name

--col BANK.COLUMN is the spelling --where uses and the one this command prints as its own heading, so the output can go straight back in. --bank REC::Particle --col chi2pid still works; passing both is an error only when they name different banks.

The count is over rows (values), not events — a bank with several rows per event contributes several values.

hist​

An ASCII histogram of one scalar column — a distribution at a glance, no plot window needed.

hipoq hist rec.hipo --col REC::Particle.chi2pid --bins 60 --range -5,5
REC::Particle.chi2pid   [-5, 5]   412883 entries
     -5.0000 | #                                                  1204
     -3.3333 | ####                                               9871
     -1.6667 | ###################################                71402
      0.0000 | ################################################## 99310
      1.6667 | #########                                          18244
      3.3333 | ##                                                 3517

The header carries the range and the number of values binned; each row is a bin's lower edge, a bar scaled to the tallest bin, and that bin's count.

Values outside an explicit --range are counted as under/overflow on the header line rather than folded into the end bins, so a range that hides most of the distribution says so instead of piling up against the edges:

REC::Particle.px   [0.1, 0.3]   1571 entries   (1000 under, 1426 over, of 3997 total)
FlagMeaning
--col C(required) the scalar column, BANK.COLUMN or a bare name
--bank Bthe bank — needed only when --col is a bare name
--bins Nnumber of bins (default 40)
--range lo,hifix the axis range instead of auto min..max

Fixing --range makes histograms of different files directly comparable (same axis), and clips outliers that would otherwise squash the interesting region.

Terminal plots

hist is 1-D and text-only by design — it's meant to be fast and pipe-safe. Richer 1-D/2-D terminal plots are a natural future extension.

Array columns​

stats, hist and dist all take one value per row, so a fixed-length array column (cov/F#6) is addressed one element at a time — the same [N] spelling --where uses:

hipoq stats rec.hipo --bank REC::Track --col "cov[0]"
hipoq hist  rec.hipo --bank REC::Track --col "cov[3]" --bins 40

Quote it in a shell that would otherwise glob [0].

Naming the array without an element is refused rather than guessed, and the index is checked against the schema before any file is read:

column "cov" is an array (length 6); pick an element, e.g. `cov[0]`
column "cov" has 6 elements, so the index must be 0..5; got [9]
column "p" is a scalar, so `p[0]` has no meaning; drop the index

To see a whole vector instead of one element, use dump or scan, which emit arrays intact, or press v in the TUI.