fit_thresholds.py

Purpose: Fit threshold scan data to determine optimal detector settings

Use case: Determining optimal threshold values, mathematical modeling of detector response

Features:

• Reads JSONL event files from the specified directory
• Counts events per threshold value for each channel
• Curve fitting using complementary error function (erfc) via SciPy
• Computes threshold values at sigma levels: 0σ, 1σ, 3σ, 5σ
• Saves results to thresholds_fitted.json
• Auto-detects threshold range from data (or user-specified via --min/--max/--step-size)
• Can also load pre-aggregated data from thresholds_scanned.jsonl via --use-summary

Required input: Data files produced by get_thresholds.py

Usage:

# Analyze a data directory (auto-detect threshold range)
uv run examples/fit_thresholds.py ./2026-03-20/

# Overwrite existing output file if it exists
uv run examples/fit_thresholds.py ./2026-03-20/ --overwrite

# Specify threshold range manually (all three required together)
uv run examples/fit_thresholds.py ./2026-03-20/ --min 280 --max 320 --step-size 2

# Use pre-aggregated summary file instead of raw event files
uv run examples/fit_thresholds.py ./2026-03-20/ --use-summary

# With verbose logging
uv run examples/fit_thresholds.py ./2026-03-20/ --verbose --log-level info

CLI Options:

Option	Default	Description
READ_FROM	(required)	Directory containing threshold measurement JSONL files
--pattern	events*.jsonl	Glob pattern to filter input files
--min	auto	Minimum threshold value for analysis (requires --max and --step-size)
--max	auto	Maximum threshold value for analysis (requires --min and --step-size)
--step-size / -ss	auto	Step size between threshold values (requires --min and --max)
--use-summary	off	Load from thresholds_scanned.jsonl instead of raw event files
--overwrite	off	Overwrite existing output file
--verbose / --quiet	--quiet	Show or suppress status messages
--log-level	error	Log level (debug/info/error)

Output file: thresholds_fitted.json

{
  "ch1": {
    "mu": 300.5,
    "sigma": 20.3,
    "0sigma": 300.5,
    "1sigma": 308.2,
    "3sigma": 363.3,
    "5sigma": 502.0
  }
}