Skip to content

v0.17.0 - Coincidence Detection Example (2026-03-04)

What Changed?

This release adds check_coincidence.py, a new example script for identifying coincidence events between two OSECHI detectors using timestamp proximity matching. It also unifies the load_events() function signature across example scripts for a consistent developer experience.

What's New

New Script: check_coincidence.py

Analyzes event data from two detectors and identifies coincidence pairs within a configurable time window using pd.merge_asof.

How to use it:

# Basic coincidence check (default: 1s window, hit_type=7, run*.parquet)
uv run check_coincidence.py ./detA ./detB

# Custom time window and hit_type filter
uv run check_coincidence.py ./detA ./detB --window 500ms --hit-types 3 5 6 7

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

Output (stdout): Coincidence pairs as JSONL, one record per line:

{"event_a": {"detected_us": 1234567, "hit_type": 7, ...}, "event_b": {"detected_us": 1234568, "hit_type": 7, ...}, "delta_us": 1}

Key features:

  • Supports JSONL, Parquet, and ROOT input formats
  • Configurable time window via --window (pandas Timedelta string)
  • Optional --hit-types filter (e.g. 7 for 3-layer hits only)
  • Warns when left and right detectors have different column schemas
  • --write-to: save merged results as Parquet instead of JSONL stdout
  • --verbose: summary statistics including coincidence rate and delta_us distribution

Installation

Quick Start

# Get the release
git checkout v0.17.0

# Setup
uv sync

# Run CLI
uv run kazunoko --help

What's Different from the Last Version?

✅ Added

  • check_coincidence.py: new example script for two-detector coincidence analysis

🔧 Changed

  • check_event_rate.py: renamed load_files() → load_events() with unified signature (read_from, pattern, on=None, hit_types=None, verbose=False)
  • check_coincidence.py: load_events() parameter renamed directory → read_from for consistency
  • check_coincidence.py: CLI arguments left/right typed as Path (was str)
  • check_coincidence.py: find_coincidences() parameters renamed df_a/df_b → left/right
  • check_coincidence.py: column schema mismatch between detectors now always warns to stderr

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All changes are additive (new script) or internal refactoring
  • check_event_rate.py behavior is unchanged; load_events() is a drop-in rename of load_files()

Tests Passed

  • ✅ Builds without errors
  • ✅ uvx ruff check src/ passes with no issues

Release Details

  • Date: 2026-03-04
  • Version: v0.17.0
  • Files Changed: 2
  • Commits: b6de9d2, 7088d1d, 2b838bf, 97fab6a, 2ea65d3

Next Steps

  • Add tests for kazunoko.workspace functions
  • Consider extracting shared load_events() into a common helper module for example scripts