Skip to content

v0.1.59 - Advanced Threshold Analysis and Visualization (2025-12-17)

What Changed?

This release adds comprehensive threshold analysis and visualization capabilities with two new Python scripts: fit_thresholds.py for detector calibration via curve fitting and plot_thresholds.py for visualizing response curves. These tools enable scientists to perform advanced threshold analysis without modifying the core library. The release also includes extensive documentation, shell script wrappers, and quality improvements across example scripts.

What's New

Main Feature 1: Threshold Fitting Script (fit_thresholds.py)

What it does: Analyzes threshold measurement data from get_thresholds.py and performs complementary error function (erfc) curve fitting to determine optimal threshold values for detector calibration. Outputs fitted parameters (μ, σ) and computed values at 0σ, 1σ, 3σ, and 5σ levels for production use.

How to use it:

# Run with threshold values and measurement data directory
uv run fit_thresholds.py "1:200;2:200;3:200" measurements/ --save

# Display results to stdout (default)
uv run fit_thresholds.py "1:200;2:200;3:200" measurements/

# With custom step size for fitting
uv run fit_thresholds.py "1:200;2:200;3:200" measurements/ --nsteps 20 --step-size 5

Features:

  • Complementary error function curve fitting for detector response modeling
  • Fit quality metrics (R², reduced χ², parameter uncertainties)
  • Sigma level computations (0σ, 1σ, 3σ, 5σ) for operating point selection
  • JSON output with fitted parameters and computed values
  • Continuous run_id numbering for sequential measurements
  • Error handling for missing thresholds with automatic padding

Main Feature 2: Threshold Visualization Script (plot_thresholds.py)

What it does: Creates publication-quality plots of detector response curves with measured data points and sigma level markers. Reads fitted data from fit_thresholds.py and generates individual plots for each channel showing the fitted curve, data points, and sigma reference lines.

How to use it:

# Generate and display plots
uv run plot_thresholds.py fitted_thresholds.json

# Save plots to file
uv run plot_thresholds.py fitted_thresholds.json --save

# Custom output format and resolution
uv run plot_thresholds.py fitted_thresholds.json --save --format pdf --dpi 300

Features:

  • Fitted complementary error function curves (smooth visualization)
  • Measured data points as scatter plot overlay
  • Sigma level markers and annotations (0σ, 1σ, 3σ, 5σ)
  • Multiple output formats: PNG, PDF, SVG
  • Configurable DPI for high-resolution output
  • Per-channel visualization with clear labeling

Supporting Features

Shell Script Wrappers:

  • get_thresholds.sh - Automated threshold scanning with serial and parallel modes
  • get_runs.sh - Multi-run measurement session manager
  • get_events.sh - Event collection wrapper with auto-generated filenames

Documentation:

  • Comprehensive examples README with terminology, guidelines, and execution patterns
  • Japanese translation (README.ja.md) for regional accessibility
  • Detailed docstrings and usage examples in all new scripts

Installation

Quick Start

# Get the release
git checkout v0.1.59

# Setup
task env:setup

# Run CLI
uv run kazunoko --help

# Try threshold analysis workflow
uv run get_thresholds.py --help
uv run fit_thresholds.py --help
uv run plot_thresholds.py --help

Complete Workflow Example

# 1. Collect threshold measurement data
uv run get_thresholds.py "1:150;2:150;3:150" measurements/ --mock --generate-count 100

# 2. Fit the collected data
uv run fit_thresholds.py "1:150;2:150;3:150" measurements/ --save

# 3. Visualize the results
uv run plot_thresholds.py measurements/fitted_thresholds.json --save

What's Different from the Last Version?

✅ Added

  • fit_thresholds.py - Full-featured threshold curve fitting with complementary error function
  • plot_thresholds.py - Publication-quality visualization of detector response curves
  • get_thresholds.sh - Shell script wrapper for automated threshold scanning
  • get_runs.sh - Shell script wrapper for multi-run measurements
  • get_events.sh - Shell script wrapper for event collection
  • examples/README.ja.md - Japanese documentation for examples
  • Comprehensive fit quality metrics (R², reduced χ², parameter uncertainties)
  • Sigma level computations at 0σ, 1σ, 3σ, 5σ
  • Auto-generated filename support with MAC address and timestamps
  • Continuous run_id numbering for sequential threshold measurements
  • Next steps guidance in script output

🔧 Changed

  • Refactored threshold range calculation with helper functions
  • Simplified channel loop processing in measurement scripts
  • Improved variable naming for clarity (read_from instead of output_dir)
  • Output filename handling with optional --save flag
  • Renamed fitted_threshold.json to fitted_thresholds.json (plural for consistency)
  • JSONL output formatting with proper soft wrapping
  • Removed excessive error handling in standalone scripts
  • Updated Examples README with detailed sections on terminology and guidelines
  • Major refactoring in get_thresholds.py: _run_sessions() now accepts device instance instead of Measure, with fresh Measure setup per session for cleaner session management
  • Simplified device connection lifecycle management with independent per-session Measure instances

🐛 Fixed

  • Global variable declarations in get_runs.py and get_events.py
  • JSONL output line wrapping issues with soft_wrap=True
  • Filename generation logic (only generate when --save flag used)
  • Sigma level key naming in plot_thresholds.py (replaced σ symbol with text)
  • Threshold range calculation simplification

✨ Improved

  • Code quality across all example scripts
  • Error handling in fit_thresholds.py for missing thresholds
  • Documentation with MkDocs Mermaid diagrams for architecture visualization
  • CLI consistency in option naming and behavior
  • Examples organization with clear terminology and use cases
  • Backward compatibility maintained for all library APIs

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • No changes to core library APIs (device.py, parser.py, command.py, etc.)
  • All example scripts are independent tools, not used by the library
  • Existing code using kazunoko library continues to work unchanged
  • MockDevice auto-loading feature (from v0.1.58) now has broader testing coverage
  • Pure additions to documentation and examples

Tests Passed

  • ✅ Builds without errors
  • ✅ All example scripts run with --help successfully
  • ✅ fit_thresholds.py correctly fits mock threshold data
  • ✅ plot_thresholds.py generates plots from fitted data
  • ✅ Shell script wrappers execute without errors
  • ✅ JSONL output formatting with proper line wrapping
  • ✅ Mock device event generation works with new scripts
  • ✅ Code quality: ruff checks pass

Release Details

  • Date: 2025-12-17
  • Version: v0.1.59
  • Files Changed: 26
  • New: fit_thresholds.py, plot_thresholds.py, get_thresholds.sh, get_runs.sh, get_events.sh
  • Updated: get_thresholds.py, get_events.py, get_runs.py, template_minimal.py
  • Documentation: examples/README.md, examples/README.ja.md, CLAUDE.md, docs/api/
  • Removed: Obsolete scripts (serial_scan.sh, parallel_scan.sh, analyze_scan.py, etc.)
  • Commits: 51 commits
  • 15 feature additions
  • 7 bug fixes
  • 18 refactorings
  • 13 documentation updates
  • 8 maintenance/cleanup commits

Key Commits

  • 1b60442 - feat: add threshold fitting script for detector calibration
  • 03af261 - feat: add plot_thresholds.py script for visualization
  • 09052e1 - refactor: extract threshold range calculation into helper function
  • 134a09b - refactor: pass device instance instead of Measure for cleaner session management
  • da282a9 - feat: add get_thresholds.sh shell script for threshold scanning
  • f48f5a9 - refactor: implement continuous run_id numbering in get_thresholds.py
  • f5c2989 - docs: update CLAUDE.md for v0.1.58 and remove outdated version history
  • dde014f - docs: add Mermaid diagrams for response formatting architecture to formatter.md

Next Steps

Potential future enhancements:

  • Implement additional fitting models (Gaussian, Poisson) for different measurement scenarios
  • Add interactive plotting with plotly for web-based visualization
  • Support batch analysis of multiple measurement campaigns
  • Implement statistical error propagation in threshold computations
  • Add export to measurement management systems (LIMS, database backends)
  • Consider GPU acceleration for large-scale fitting operations
  • Expand documentation with real detector calibration case studies