# 測定ワークフロー

ここでは、`haniwers`を使った宇宙線データ収集の標準的なワークフローを解説します。

:::{tip}
**はじめての方へ**: まず[設定ファイルの作成](./config.md)で基本設定を行ってから、以下のワークフローに進んでください。
:::

---

## 📋 ワークフローの全体像

宇宙線データ収集は、以下の5つのステップで進めます。

```{mermaid}
graph LR
    A[0. ポート確認] --> B[1. 閾値スキャン]
    B --> C[2. 最適値フィット]
    C --> D[3. 閾値設定]
    D --> E[4. データ収集]
    E --> F[データ解析]
```

### ステップ0: ポート確認 (`port`)

**目的**: OSECHI検出器がPCに正しく接続されているか確認する

**実行コマンド**:

```bash
# 利用可能なシリアルポート一覧
haniwers-v1 port list

# 接続テスト
haniwers-v1 port test /dev/cu.usbserial-140
```

**詳細**: [ポート管理ガイド](./port.md)

---

### ステップ1: 閾値スキャン (`scan`)

**目的**: 検出器の最適な閾値（threshold）を見つけるため、電圧を変化させながら宇宙線のカウントレートを測定する

**実行コマンド**:

```bash
# 単一チャンネルスキャン（hnw.tomlから設定読み込み）
haniwers-v1 scan serial --thresholds 1:300

# 全チャンネル同時スキャン
haniwers-v1 scan serial --thresholds "1:300;2:310;3:320"

# スキャン範囲とステップ指定
haniwers-v1 scan serial --thresholds 1:300 --nsteps 10 --step 5

# カスタム設定ファイル使用
haniwers-v1 scan serial --config custom.toml --thresholds 1:300
```

**詳細**: [閾値スキャンガイド](./scan.md)

---

### ステップ2: 最適値フィット (`fit`) 🚧 WIP

**目的**: スキャン結果を統計的に解析し、検出効率が50%となる最適な閾値を推定する

**実行コマンド**:

```bash
# フィット実行（v0コマンド - v1では未実装）
haniwers fit --input scan_results.csv
```

:::{note}
`fit`コマンドは現在v0のみで利用可能です。v1での実装は今後予定されています。
:::

**詳細**: [フィットガイド](./fit.md)

---

### ステップ3: 閾値設定 (`threshold write`)

**目的**: 推奨された閾値をOSECHI検出器に書き込む

**実行コマンド**:

```bash
# 全チャンネル一括設定（hnw.tomlから設定読み込み）
haniwers-v1 threshold write --thresholds "1:280;2:310;3:320"

# 単一チャンネル設定
haniwers-v1 threshold write --thresholds 1:280

# リトライ回数と履歴ログ指定
haniwers-v1 threshold write --thresholds "1:280;2:310;3:320" \
  --max-retry 5 --history threshold_ops.csv
```

:::{note}
`--load-from`オプションは現在v1では未実装です。CSVファイルからの一括読み込み機能は今後追加予定です。
:::

**詳細**: [閾値設定ガイド](./vth.md)

---

### ステップ4: データ収集 (`daq`)

**目的**: 設定した閾値で長期間の宇宙線イベントを収集する

**実行コマンド**:

```bash
# 標準DAQ（イベント数ベース、hnw.tomlから設定読み込み）
haniwers-v1 daq

# 時間ベースDAQ
haniwers-v1 daq --duration 3600

# ポート指定（設定ファイルと異なるポート使用時）
haniwers-v1 daq --port /dev/cu.usbserial-140
```

**詳細**: [データ収集ガイド](./daq.md)

---

## 🎯 クイックスタート

はじめて測定する方は、以下の順序で進めてください：

1. **[設定ファイルの作成](./config.md)**: 測定パラメーターを設定
2. **[ポート管理](./port.md)**: 検出器接続を確認
3. **[閾値スキャン](./scan.md)**: 最適閾値を探索
4. **[データ収集](./daq.md)**: 宇宙線イベントを記録

---

## 📚 詳細ドキュメント

各ステップの詳しい使い方は、以下のドキュメントを参照してください。

### 基本操作

- **[概要](./overview.md)**: ワークフロー全体の詳細説明
- **[設定ファイルの作成](./config.md)**: `config.toml`の作成方法とパラメーター説明
- **[ポート管理 (`port`)](./port.md)**: シリアルポートの確認と接続テスト

### 測定フロー

- **[閾値スキャン (`scan`)](./scan.md)**: 最適閾値の探索方法
- **[フィット (`fit`)](./fit.md)**: スキャン結果の統計解析
- **[閾値設定 (`vth`)](./vth.md)**: 検出器への閾値書き込み
- **[データ収集 (`daq`)](./daq.md)**: 長期測定の実行方法

### トラブルシューティング

- **[データ品質について](./data-quality.md)**: 検出器ノイズの対処方法とデータ品質の確認方法

---

## ❓ よくある質問

### 初回測定で何から始めればよいですか？

1. インストール後、まず`haniwers-v1 config init`で設定ファイルを生成
2. `haniwers-v1 port list`で検出器のポートを確認
3. `hnw.toml`の`device.port`を編集
4. 閾値スキャンから測定開始

### スキャンとDAQの違いは？

- **スキャン**: 閾値を変えながら短時間測定（最適値探索）
- **DAQ**: 固定閾値で長時間測定（データ収集）

### 設定ファイルは毎回必要ですか？

いいえ、一度作成した`hnw.toml`は再利用できます。測定条件が変わる場合のみ編集してください。

:::{note}
`haniwers-v1`コマンドは、デフォルトで`hnw.toml`を読み込みます。
別の設定ファイルを使いたい場合のみ`--config`オプションを指定してください。
:::

```{toctree}
---
maxdepth: 1
hidden:
---
overview
config
port
workflows
workflows-daq
workflows-scan
workflows-fit
scan
fit
vth
daq
data-quality
```