Skip to content

v0.3.5 - Notebook Analysis Tools (2025-12-22)

What Changed?

This release adds comprehensive notebook analysis tools for detector event data. New notebooks provide detailed analysis of hit patterns, ADC signal distributions, and event timing characteristics. All analysis notebooks support flexible data input and produce publication-ready visualizations with statistical summaries.

What's New

Analysis Notebooks Suite

What it does: Provides three specialized Jupyter notebooks for analyzing OSECHI cosmic ray detector event data. Each notebook focuses on a specific aspect of detector performance: hit patterns across layers, ADC signal characteristics, and event timing analysis.

How to use it: Navigate to notebooks/md/ directory and open any notebook with Jupyter:

  • check_hit.md: Analyze hit patterns and hit_type distribution across detector layers
  • check_adc.md: Examine ADC signal distributions by event type (top layer measurement)
  • check_jitter.md: Study event timing precision and inter-event spacing characteristics

Features:

  • Event data loading from JSONL format with automatic filtering
  • Comprehensive statistical summaries (mean, std, min, max, percentiles)
  • Publication-ready visualizations using hvplot (histograms, box plots, violin plots)
  • Comparative analysis across event classifications
  • Log-scale and linear-scale plot options for flexible data interpretation

Installation

Quick Start

# Get the release
git checkout v0.3.5

# Setup
uv sync

# Access notebooks
jupyter notebook notebooks/nb/check_hit.ipynb
jupyter notebook notebooks/nb/check_adc.ipynb
jupyter notebook notebooks/nb/check_jitter.ipynb

What's Different from the Last Version?

✅ Added

  • notebooks/md/check_hit.md: Comprehensive hit analysis with hit_type distribution and hit count comparisons across detector layers
  • notebooks/md/check_adc.md: ADC signal analysis for top layer measurements, classified by hit_type patterns
  • notebooks/md/check_jitter.md: Event timing analysis with jitter measurements and timedelta error calculations
  • Analysis notebook visualizations: histograms, box plots, and violin plots for statistical comparison

🔧 Changed

  • Updated analysis notebooks with consistent variable naming and formatting conventions

🐛 Fixed

  • Corrected timedelta_us error calculation alignment in timing analysis (from v0.3.4)

Is It Safe to Upgrade?

Backward Compatible: Yes

  • This release adds new analysis notebooks without modifying existing CLI functionality
  • All existing features and command-line tools remain unchanged
  • No impact on data formats or device communication protocols

Tests Passed

  • ✅ Builds without errors
  • ✅ Pre-commit hooks validation passed
  • ✅ Notebook execution verified with sample data
  • ✅ Statistical calculations validated against raw data

Release Details

  • Date: 2025-12-22
  • Version: v0.3.5
  • Files Changed: 5 notebook files + version bump
  • Key Commits:
  • 680eeab - Create ADC analysis notebook
  • 0cca076 - Complete hit analysis with distributions
  • a8ce026 - Update jitter analysis

Next Steps

  • Expand analysis notebooks with additional detector performance metrics
  • Add comparative analysis tools across multiple data runs
  • Develop automated report generation from notebook analyses
  • Integrate notebook outputs into measurement workflow