Skip to content

v0.14.8 - New check_event_rate.py Example Script (2026-03-04)

What Changed?

This release adds a new example script, check_event_rate.py, for analyzing per-hit-type event rates from run data files. The script reads JSONL or Parquet files, resamples by a configurable frequency, and plots event rates in Hz with Poisson error bands for each hit type. Several naming refinements were also made during development to align with project conventions.

What's New

Main Feature: check_event_rate.py

What it does: Reads event data files (JSONL or Parquet), resamples by a user-specified frequency, and generates a matplotlib plot of per-hit-type event rates (Hz) with Poisson error bands(+/- sqrt(N) / freq_sec).

Key design choices:

  • hit_type 1–7 only: Type 0 does not exist in the detector encoding and is excluded
  • Poisson errors: Displayed as shaded bands around each rate line
  • Flexible input: Supports .jsonl, .parquet, and .root (requires uproot) files
  • Save or display: Show interactively or save as PNG/PDF/SVG

How to use it:

# Plot all hit types from parquet files with default 10s resample frequency
uv run check_event_rate.py ./data

# Select specific hit types with 60s resample frequency
uv run check_event_rate.py ./data --resample 60s --hit-types 1 3 5 7

# Use JSONL files with received_us timestamp and save plot
uv run check_event_rate.py ./data --pattern "*.jsonl" --timestamp received_us --save

# Save as PDF
uv run check_event_rate.py ./data --save --format pdf

Code example:

# Core rate calculation
rates, errors = compute_rates(df, freq="10s", hit_types=[1, 2, 3, 4, 5, 6, 7])
plot_rates(rates, errors, hit_types=[1, 2, 3, 4, 5, 6, 7], freq="10s")

Installation

Quick Start

# Get the release
git checkout 0.14.8

# Setup
uv sync

# Run the script
uv run examples/check_event_rate.py ./data --pattern "*.parquet"

What's Different from the Last Version?

✅ Added

  • examples/check_event_rate.py: new script for per-hit-type event rate analysis
  • load_files(): glob and concatenate JSONL, Parquet, or ROOT files
  • prepare_index(): convert microsecond timestamp column to DatetimeIndex
  • compute_rates(): resample counts and compute rates(Hz) with Poisson errors
  • plot_rates(): matplotlib plot with per-hit-type rate lines and error bands
  • CLI options: READ_FROM (positional), --pattern, --resample, --hit-types, --timestamp, --format, --dpi, --save, --verbose

🔧 Changed

  • Renamed ALL_CHANNELS → HIT_TYPES, list(range(8)) → list(range(1, 8)) to exclude non-existent hit_type 0
  • Renamed CLI option --channels → --hit-types and related variables throughout
  • Renamed CLI option --interval → --resample and internal variable interval → freq
  • Changed read_from from typer.Option to typer.Argument (positional) to match other example scripts

Is It Safe to Upgrade?

Backward Compatible: Yes

  • No changes to the library API, CLI commands, or data formats
  • Only examples/check_event_rate.py was added
  • Existing scripts and workflows are unaffected

Tests Passed

  • ✅ Builds without errors
  • ✅ Script runs with Parquet and JSONL input files
  • ✅ --hit-types filtering selects correct hit_type subsets
  • ✅ --resample frequency correctly controls bin width and rate calculation
  • ✅ --save writes PNG/PDF/SVG to the input directory

Release Details

  • Date: 2026-03-04
  • Version: v0.14.8
  • Files Changed: 1 (examples/check_event_rate.py)
  • Commits: 067bf6e, 8622712, 670e9ca, 39a0230, befc608

Next Steps

  • Consider adding a moving-average rate overlay to the plot
  • Consider per-run breakdown when multiple files span different runs