Skip to content

v0.3.6 - Real-time Data Monitoring Tool (2025-12-23)

What Changed?

This release adds a real-time terminal user interface (TUI) for monitoring OSECHI detector data directories. The monitor.py script provides live statistics updates, file tracking, and detector performance metrics using Textual and watchdog for automatic file detection.

What's New

Real-time TUI Monitor for Detector Data

What it does: Provides a real-time terminal user interface for monitoring OSECHI detector data acquisition. The monitor automatically watches a directory for new event files, displays live statistics including event counts, hit patterns, and ADC measurements, and updates the display as new data arrives.

How to use it: Run the monitor with a data directory path:

uv run examples/monitor.py /path/to/data/directory
uv run examples/monitor.py examples/20251222_run127

Features: - Directory Monitoring: Automatic detection of new JSONL event files using watchdog - Live Statistics: Real-time display of total events, event rate, and file count - Hit Analysis: Current distribution of single, two, and three-layer detection events - ADC Metrics: Mean, minimum, and maximum values from top layer ADC measurements - File Tracking: Recent file list showing filename, event count, and file size - Keyboard Controls: - q to quit - r to reset statistics - c to clear/refresh display - Status Information: Bottom status bar with monitoring path and statistics summary

Installation

Quick Start

# Get the release
git checkout v0.3.6

# Setup
uv sync

# Run the monitor
uv run examples/monitor.py examples/20251222_run127

What's Different from the Last Version?

✅ Added

  • examples/monitor.py: Real-time TUI monitor for detector data using Textual
  • Directory monitoring with watchdog for automatic event file detection
  • Live statistics panels: event counts, rates, hit distribution, ADC metrics
  • File tracking panel showing recent monitored files
  • Keyboard controls for quit, reset, and refresh operations

🔧 Changed

  • Updated notebook data paths to 20251222_run127 for consistent test data
  • Enhanced check_adc.md with linear/log scale distribution comparisons
  • Adjusted check_jitter.md timedelta filtering for broader analysis
  • Standardized variable naming across all analysis notebooks

🐛 Fixed

  • Fixed kazunoko dependency format in monitor.py PEP 723 specification

Is It Safe to Upgrade?

Backward Compatible: Yes

  • This release adds new monitoring tool without modifying existing CLI functionality
  • All existing features and command-line tools remain unchanged
  • New monitor.py is an independent example script with no impact on core library
  • No changes to data formats or device communication protocols

Tests Passed

  • ✅ Builds without errors
  • ✅ Pre-commit hooks validation passed
  • ✅ Monitor TUI renders correctly with sample data
  • ✅ Directory monitoring detects file events reliably
  • ✅ Statistics calculations verified against raw data
  • ✅ Notebook examples execute without errors

Release Details

  • Date: 2025-12-23
  • Version: v0.3.6
  • Files Changed: 5 files (monitor.py + 3 notebooks + bump)
  • Key Commits:
  • 3b78ee1 - Add real-time TUI monitor for detector data
  • 6c36894 - Update notebook data paths and analysis parameters
  • c07dbca - Update kazunoko dependency format

Next Steps

  • Expand monitor with additional real-time metrics (temperature, humidity)
  • Add data export functionality from monitor (CSV, JSON outputs)
  • Implement alert thresholds for anomalous detection rates
  • Create plugins system for custom monitoring metrics
  • Integrate monitor with measurement workflow automation