Examples Guide

kazunoko examples is a collection of standalone scripts for measurement workflows, data conversion, and analysis with the OSECHI cosmic ray detector.

Each script follows PEP 723 and can be run directly with uv run — no manual dependency installation required.

uv run examples/get_events.py --help

---

Script Categories

Cosmic Measurement

Collect detection events from the detector and save them to JSONL files.

Script	Description
get_events.py	Collect events as a single run
get_runs.py	Collect events across multiple files

Threshold Measurement

Scan threshold values to find optimal detector settings.

Script	Description
get_thresholds.py	Collect events at each threshold step
fit_thresholds.py	Fit scan data with an erfc curve
plot_thresholds.py	Plot fitted threshold curves

Real-time Monitor

Monitor detector data live during measurement.

Script	Description
monitor_events.py	Monitor detection events in real time
monitor_thresholds.py	Monitor threshold scan progress in real time

Data Conversion

Convert JSONL event files to analysis-friendly formats.

Script	Description
from_jsonl_to_parquet.py	Convert JSONL to Parquet
from_parquet_to_root.py	Convert Parquet to ROOT TTree
from_jsonl_to_root.py	Convert JSONL to ROOT TTree (one step)

Analysis

Analyze collected event data.

Script	Description
create_run_summary.py	Create a run summary TOML file
check_event_rate.py	Plot event rate per hit_type over time
check_bme280.py	Plot BME280 sensor time series
check_coincidence.py	Find coincidence events between two detectors

---

Typical Workflows

Cosmic Ray Measurement

graph LR
  A[get_events.py / get_runs.py] -->|JSONL| B[from_jsonl_to_parquet.py]
  B -->|Parquet| C[check_event_rate.py]
  B -->|Parquet| D[check_bme280.py]
  B -->|Parquet| E[from_parquet_to_root.py]

1. Collect events → get_events.py or get_runs.py
2. Create run summary → create_run_summary.py
3. Convert to Parquet → from_jsonl_to_parquet.py
4. Analyze event rate → check_event_rate.py

Threshold Optimization

1. Scan thresholds → get_thresholds.py
2. Fit scan data → fit_thresholds.py
3. Plot results → plot_thresholds.py

Two-detector Coincidence

1. Collect events from each detector → get_runs.py
2. Convert to Parquet → from_jsonl_to_parquet.py
3. Find coincidences → check_coincidence.py