Skip to content

v0.3.3 - create_run_summary improvements (2025-12-22)

What Changed?

This release improves the create_run_summary.py example script with better code organization, cleaner architecture, and new hit_type rate analysis. The build_toml() function extracts TOML structure generation for improved maintainability. A new [hit_rate] section provides event distribution statistics by hit type (1-7).

What's New

Main Feature: Hit Rate Analysis

What it does: The [hit_rate] section now includes event distribution statistics for each detector hit type (1 through 7). This helps users quickly understand the composition of detected events.

How to use it: After running create_run_summary.py, the generated TOML file contains:

[hit_rate]
hit_type1 = 0.45  # 45% of events with hit_type == 1
hit_type2 = 0.36  # 36% of events with hit_type == 2
hit_type3 = 0.0   # 0% of events with hit_type == 3
hit_type4 = 0.19  # 19% of events with hit_type == 4
hit_type5 = 0.0
hit_type6 = 0.0
hit_type7 = 0.0

Code Refactoring

What improved:

  • Extracted build_toml() function for cleaner separation of concerns
  • Removed redundant dictionary initialization
  • Consolidated timezone conversion logic (JST conversion)
  • Eliminated DRY violations with single output_rel calculation
  • Better code readability with clear comment sections

Installation

Quick Start

# Get the release
git checkout v0.3.3

# Setup
uv sync

# Run the script
uv run examples/create_run_summary.py ./events_directory/

What's Different from the Last Version?

✅ Added

  • [hit_rate] section in run_summary.toml with hit_type1 through hit_type7 distribution rates
  • build_toml() function for TOML structure generation

🔧 Changed

  • Refactored main() function for better code organization
  • Improved separator comments (Validate → Load → Log → Build → Verify → Display)
  • Hit type counting now uses explicit range(1, 8) for clarity

🐛 Fixed

  • Removed TOML key type error (integers → strings)
  • Eliminated redundant path calculations

Is It Safe to Upgrade?

Backward Compatible: Yes

  • The create_run_summary.py script behavior remains unchanged for existing users
  • New [hit_rate] section is added automatically without affecting other sections
  • All existing sections (overview, device, description, location, files) remain unchanged

Tests Passed

  • ✅ Script runs without errors on real event data (1800 files, 52432 events)
  • ✅ TOML file generation and validation
  • ✅ All 7 hit_type rates computed and written correctly
  • ✅ Edge cases handled (0 events in a hit_type → rate = 0.0)

Release Details

  • Date: 2025-12-22
  • Version: v0.3.3
  • Files Changed: 4 (create_run_summary.py, pyproject.toml, __init__.py, CHANGELOG.md)
  • Commits:
  • 6ec533d: bump: version 0.3.2 → 0.3.3
  • 313abea: refactor: change hit_rate calculation to count events by hit_type (1-7)
  • 2e70a21: fix: add hit_rate section with event rates by hit_type
  • 2a494bb: refactor: extract build_toml function and improve create_run_summary clarity

Next Steps

  • Consider adding threshold analysis to the run summary
  • Explore additional event statistics (timing, ADC distributions)
  • Enhance documentation with more example run summaries