v1.5.0 (2025-10-29)#

このリリースは、Threshold Fitter（閾値フィッティング）の機能拡張に焦点を当てた重要なアップデートです。スキャン結果の最適化と可視化、品質検証機能を追加することで、コスミックレイ検出の精度向上と実験の効率化を実現しました。

✨ v1.5.0 での改善点#

このマイルストーンは、以下を実現します。

Threshold Fitter 強化: スキャン結果から最適閾値を計算する機能の拡張
品質検証システム: --verify オプションによるフィット結果の自動検証
対話型可視化: hvplot を活用した interactive HTML グラフの自動生成
フィット結果モデル: ThresholdFitResult NamedTuple による型安全なデータモデル
パラメータ柔軟化: グローバル・チャネル別の2つのパラメータ形式をサポート
エラーハンドリング向上: フィット失敗時の詳細なエラー情報と推奨値

🎯 User Story 1 - Threshold Fitter の基本機能#

新機能: 最適閾値の自動計算#

fit_thresholds() 関数: スキャン結果から最適閾値を計算

from haniwers.v1.threshold.fitter import fit_thresholds

# スキャン結果を読み込み
scan_data = pd.read_csv('scan_results.csv')

# 最適閾値を計算（複数チャネル対応）
thresholds = fit_thresholds(
    scan_data,
    channels=[1, 2, 3],
    params=[10, 300, 1, 1]  # [height, mean, sigma, offset]
)

# 推奨閾値（3σ）を取得
print(thresholds[['ch', '3sigma']])

Complementary Error Function (erfc) フィッティング: 統計的に正確な閾値推定
- S字カーブのフィッティング
- 複数σレベル（0σ, 1σ, 3σ, 5σ）での閾値推奨
- 3σレベルが最適な検出効率を実現
複数チャネルの並列処理: 効率的な計算
- チャネル1-3を独立して処理
- 各チャネルの特性に最適な値を計算

柔軟なパラメータ指定#

# グローバルパラメータ形式（すべてのチャネルに同じ値）
haniwers-v1 threshold fit ./scan_data --parameters "10,300,1,1"

# チャネル別パラメータ形式（チャネルごとに異なる値）
haniwers-v1 threshold fit ./scan_data --parameters "1:10,300,1,1;2:15,280,0.8,1;3:12,320,1.2,1"

# デフォルト値を使用
haniwers-v1 threshold fit ./scan_data

ThresholdFitResult モデル#

from haniwers.v1.threshold.fitter import ThresholdFitResult

# フィット結果を型安全に取得
result = ThresholdFitResult(
    ch=1,                           # チャネル番号
    timestamp="2025-10-29T...",     # フィット実行時刻
    mean=822.5,                     # 中心値（0σ）
    sigma=32.8,                     # σパラメータ
    sigma_0=822,                    # 0σ推奨閾値
    sigma_1=855,                    # 1σ推奨閾値
    sigma_3=921,                    # 3σ推奨閾値（推奨）
    sigma_5=987,                    # 5σ推奨閾値
)

🎯 User Story 2 - フィット結果の品質検証#

新機能: `--verify` オプション#

# フィット結果を自動検証
haniwers-v1 threshold fit ./scan_data --verify

# 出力例:
# [INFO] Verification results:
# ✓ Channel 1: All checks passed (σ0=822, σ3=887)
# ⚠ Channel 2: Low event reduction (0.0%) - flat response
# ⚠ Channel 3: Low event reduction (0.0%) - flat response

検証項目#

閾値範囲チェック: スキャンデータの範囲内であることを確認

Check: Threshold values within scan range (150-1000)
Channel 1: ✓ Valid (0σ=822, 3σ=887, 5σ=930)

合理性チェック: 検出可能な範囲（100-1000 mV）内であることを確認

Check: Reasonable threshold values (100-1000 range)
Channel 1: ✓ All thresholds in reasonable range

イベント分布分析: 閾値が信号を適切に分離しているか確認

Check: Event reduction percentage
Channel 1: ✓ Good reduction (89.7% from baseline)
Channel 2: ⚠ Low reduction (0.0%) - indicates flat response

データ品質チェック: 十分なデータポイント数があることを確認
```
Check: Minimum data points
Channel 1: ✓ 156 data points (>= 20 required)
```

検証結果の解釈#

結果	意味	対応
✓ All checks passed	フィット品質が良好	そのまま使用可能
⚠ Warning	パラメータは有効だが注意が必要	実験的に確認推奨
✗ Error	致命的な問題あり	パラメータを調整して再実行

🎯 User Story 3 - フィット結果の対話型可視化#

新機能: `--plot` オプション#

# フィット結果の可視化を生成
haniwers-v1 threshold fit ./scan_data --plot

# 出力ファイル:
# workspace/threshold_plots/
#   ├── threshold_fit_ch1.html  (180KB)
#   ├── threshold_fit_ch2.html  (180KB)
#   └── threshold_fit_ch3.html  (180KB)

可視化の特徴#

スキャンデータポイント: 実測値をスキャッタープロット表示
- 各閾値での測定イベント数
- ホバーツールで詳細値を表示
フィット曲線: complementary error function の理論曲線
- 測定データとの比較で品質判定
- 赤色で強調表示

閾値参照線: 4つのσレベルを色分け表示

オレンジ (─ ─ ─): 0σ推奨値（中心）
金色 (─ ─ ─):     1σ推奨値
緑色 (─ ─ ─):     3σ推奨値（推奨）
紫色 (─ ─ ─):     5σ推奨値

対話型機能: Bokeh による高速インタラクション
- ズーム: マウスホイールで領域拡大
- パン: ドラッグで画面移動
- 凡例: クリックで系列表示/非表示
- ホバー: マウスで詳細値表示

使用例#

# 検証と可視化を同時実行
haniwers-v1 threshold fit ./scan_data --verify --plot

# 出力:
# [INFO] Fitted Threshold Values: (3 channels)
# [INFO] Performing verification checks...
# ✓ Channel 1: All checks passed
# [INFO] Generating visualizations...
# [INFO] Visualizations created:
#   Channel 1: threshold_fit_ch1.html (156 data points, 3σ threshold: 887)
#   Channel 2: threshold_fit_ch2.html (156 data points, 3σ threshold: 284)
#   Channel 3: threshold_fit_ch3.html (156 data points, 3σ threshold: 296)

📊 API の新規追加#

fitter.py の新関数#

# フィット実行
fit_thresholds(
    data: pd.DataFrame,
    channels: list[int],
    params: list[float]
) -> pd.DataFrame

# 品質検証
verify_fit_quality(
    scan_data: pd.DataFrame,
    fit_results: pd.DataFrame,
    verbose: bool = False
) -> dict

# 可視化生成
plot_fit_results(
    scan_data: pd.DataFrame,
    fit_results: pd.DataFrame,
    output_dir: Path = None,
    verbose: bool = False
) -> dict

CLI の新オプション#

haniwers-v1 threshold fit [OPTIONS] READ_FROM

Options:
  --pattern TEXT              # ファイル検索パターン (default: "*.csv")
  --parameters TEXT           # フィット初期パラメータ
  --verify                    # フィット結果の品質検証を実行
  --plot                      # 対話型グラフを生成
  --workspace PATH            # 出力ディレクトリ
  --verbose -v                # 詳細ログ出力

🧪 テスト強化#

テストカバレッジ#

テストスイート	状態	詳細
v1 ユニットテスト全体	✅ パス	Fitter 新機能対応
フィッティング関数	✅ 100%	基本機能・エッジケース・エラー処理
品質検証	✅ 100%	すべての検証チェック項目
CLI 統合	✅ 100%	オプションパーサ・エラーハンドリング
コード品質	✅ Pass	ruff format, pre-commit OK
テストカバレッジ	✅ 80%+	新機能と既存機能をカバー

削除・修正されたテスト#

統合テスト修正 (test_mock_acquisition.py):
- --output-dir → --workspace に統一
- --prefix → --filename-prefix に統一
- 最新の CLI オプション名に対応
インポートエラー修正 (test_write_with_device.py):
- ThresholdResult → ThresholdWriteResult に修正
- 正確な型情報で型チェック強化

🔧 内部実装の改善#

Dependencies#

hvplot >= 0.11.0: 対話型グラフ生成
holoviews: 複雑な可視化サポート
bokeh: レンダリングバックエンド ※ これらは既に pyproject.toml に含まれています

パフォーマンス最適化#

二段階フィッティング: 収束性向上
1. 初期パラメータで第1次フィット
2. 得られた値で第2次フィット（精緻化）
メモリ効率: フィット曲線点はnp.arange(..., 0.1) で適度に生成
- 過度な精度で CPU/メモリ消費を避ける
- 視覚的には十分な滑らかさを実現

TODO と既知の制限#

OptimizeWarning (scipy): Demo データ特有の警告
```
OptimizeWarning: Covariance of the parameters could not be estimated
```
- 原因: Demo データの信号変動が小さい
- 対応: 実際の宇宙線データでは自然に解消される見込み
- 詳細: fitter.py のコメント参照（TODO記載）

📦 インストール#

pip install haniwers==1.5.0

または最新版：

pip install --upgrade haniwers

🔗 関連リンク#

リリース担当: shotakaha リリース日: 2025-10-29 バージョン: 1.5.0 (MINOR update) 実装期間: 1日 (2025-10-29)

v1.5.0 (2025-10-29)

目次