check_event_rate.py

Purpose: Calculate and plot event rates per hit_type

Use case: Verifying detector stability, monitoring cosmic ray flux over time

Features:

• Reads JSONL or Parquet event files from a directory
• Resamples events by configurable frequency (e.g. 10s, 1min)
• Plots event rate [Hz] with Poisson error bands for each hit_type
• Excludes rows with out-of-range BME280 values by default
• Timestamps displayed in local timezone (configurable via KAZUNOKO_TZ)
• Supports PNG, PDF, and SVG output formats

Required input: JSONL or Parquet files produced by get_events.py, get_runs.py, or from_jsonl_to_parquet.py

Usage:

# Plot all hit_types from Parquet files with 10s resample
uv run examples/check_event_rate.py ./20251221_run126/

# Custom resample frequency and specific hit_types
uv run examples/check_event_rate.py ./20251221_run126/ --resample 60s --hit-type 1 --hit-type 2 --hit-type 4 --hit-type 7

# Use JSONL files with received_us timestamp
uv run examples/check_event_rate.py ./20251221_run126/ --pattern "events*.jsonl" --timestamp received_us

# Save plot as PDF
uv run examples/check_event_rate.py ./20251221_run126/ --save --format pdf

# Include rows with invalid BME280 readings
uv run examples/check_event_rate.py ./20251221_run126/ --include-invalid-bme280

CLI Options:

Option	Default	Description
READ_FROM	(required)	Directory containing data files
--pattern	run*.parquet	Glob pattern to filter input files
--resample	10s	Resample frequency as pandas offset string
--hit-type	all (1–7)	hit_type values to display (repeatable)
--timestamp	detected_us	Timestamp column (detected_us or received_us)
--format / -f	png	Output format (png, pdf, svg)
--dpi	150	Resolution for PNG output (50–600)
--include-invalid-bme280	off	Include rows where bme280_valid is False
--save	off	Save plot to READ_FROM directory
--verbose / --quiet	--quiet	Show or suppress status messages
--log-level	error	Log level (debug/info/error)

Environment Variables:

Variable	Default	Description
KAZUNOKO_TZ	system timezone	IANA timezone name for plot timestamps (e.g. Asia/Tokyo)