check_coincidence.py

Purpose: Identify coincidence events between two detectors

Use case: Two-detector coincidence analysis, muon trajectory studies

Features:

• Loads event data from two directories and finds coincidence pairs
• Uses pandas.merge_asof for timestamp-based matching within a configurable time window
• Filters by hit_type values
• Excludes rows with out-of-range BME280 values by default
• Outputs coincidence pairs as JSONL to stdout
• Optionally saves results to a Parquet file

Required input: JSONL or Parquet files from two separate detectors produced by get_events.py or get_runs.py

Usage:

# Basic coincidence check between two detector directories
uv run examples/check_coincidence.py ./20251221_detA ./20251221_detB

# Custom time window
uv run examples/check_coincidence.py ./detA ./detB --window 500us

# Filter for 3-layer hits only (hit_type=7)
uv run examples/check_coincidence.py ./detA ./detB --hit-type 7

# Filter for 2-layer and 3-layer hits
uv run examples/check_coincidence.py ./detA ./detB --hit-type 1 --hit-type 2 --hit-type 4 --hit-type 7

# Save coincidence results to Parquet
uv run examples/check_coincidence.py ./detA ./detB --write-to coincidence.parquet --verbose

# Use JSONL files with 10ms window
uv run examples/check_coincidence.py ./detA ./detB --pattern "events_*.jsonl" --window 10ms

CLI Options:

Option	Default	Description
LEFT	(required)	Directory containing event files from the left detector
RIGHT	(required)	Directory containing event files from the right detector
--window / -w	1s	Time window as pandas Timedelta string (e.g. 1ms, 500us)
--timestamp	detected_us	Timestamp column for matching (detected_us or received_us)
--hit-type	7	Filter by hit_type values (repeatable)
--pattern	run*.parquet	Glob pattern to filter input files
--include-invalid-bme280	off	Include rows where bme280_valid is False
--write-to	none	Write coincidence results to Parquet file
--verbose / --quiet	--quiet	Show or suppress status messages
--log-level	error	Log level (debug/info/error)

Output:

• stdout: Coincidence event pairs as JSONL (one pair per line)
• --write-to: Coincidence results saved as Parquet file
• stderr (with --verbose): Summary statistics