# 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()` 関数**: スキャン結果から最適閾値を計算
  ```python
  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を独立して処理
  - 各チャネルの特性に最適な値を計算

### 柔軟なパラメータ指定

```bash
# グローバルパラメータ形式（すべてのチャネルに同じ値）
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 モデル

```python
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` オプション

```bash
# フィット結果を自動検証
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` オプション

```bash
# フィット結果の可視化を生成
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 による高速インタラクション
  - **ズーム**: マウスホイールで領域拡大
  - **パン**: ドラッグで画面移動
  - **凡例**: クリックで系列表示/非表示
  - **ホバー**: マウスで詳細値表示

### 使用例

```bash
# 検証と可視化を同時実行
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 の新関数

```python
# フィット実行
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 の新オプション

```bash
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記載）

## 📦 インストール

```bash
pip install haniwers==1.5.0
```

または最新版：

```bash
pip install --upgrade haniwers
```

## 🔗 関連リンク

- [完全な変更ログ](../../CHANGELOG.md#150-2025-10-29)
- [実装の詳細](../../src/haniwers/v1/threshold/fitter.py)
- [ドキュメント](https://qumasan.gitlab.io/haniwers/docs/)
- [Issues](https://gitlab.com/qumasan/haniwers/-/issues)
- [リリースタグ](https://gitlab.com/qumasan/haniwers/-/tags/1.5.0)

---

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