# データ品質について

## はじめに

`haniwers`でデータを取得しているとき、時々「何かおかしい」と感じることがあるかもしれません。このドキュメントでは、データ品質の問題と、`haniwers`がそれにどのように対応しているかを説明します。

## よくある問題：検出器からのノイズ

### 症状

データを取得しているとき、ログに以下のようなメッセージが表示されることがあります：

```
WARNING | Skipped invalid/empty detector line (total skipped: 1)
WARNING | Skipped invalid/empty detector line (total skipped: 2)
WARNING | Skipped invalid/empty detector line (total skipped: 5)
```

### 原因

OSECHI検出器がシリアル通信で`haniwers`にデータを送るとき、ときどき以下のようなことが起こります：

- **通信ノイズ**: USB ケーブル付近の電磁ノイズが原因で、データが破損する
- **一時的な障害**: 検出器がデータを送信する途中で通信が途切れる
- **ハードウェア問題**: 検出器またはコンピューターのシリアルポートの接触不良

結果として、検出器は以下のような「不正なデータ」を送信することがあります：

```
空の行（データなし）
100 150 120 1 0      <- フィールド数が足りない（本来は7フィールド）
abc 150 120 1 0 25.5 24.8  <- 数値が入るべき位置に文字がある
```

### haniwersの対応

`haniwers`は**堅牢性（robustness）を優先**する設計になっています。不正なデータが来たとき：

1. **データを保存しない**: 不正なデータはCSVファイルに保存されず、自動的にスキップされます
2. **DAQを停止しない**: 1行のノイズで全体の測定が止まることはありません
3. **ユーザーに通知する**: 警告ログを表示して、問題があったことを通知します

つまり、**データの品質は保証され、測定の継続性も確保される**という設計です。

## ログメッセージの読み方

### 警告ログの例

```
WARNING | Skipped invalid/empty detector line (total skipped: 3)
WARNING | Skipped invalid/empty detector line (total skipped: 4)
```

### 意味

- **「Skipped invalid/empty detector line」**: 検出器から受け取ったデータが不正な形式だった
- **「total skipped: 4」**: これまでのDAQセッションでスキップされたデータは合計4行

### 問題があるかどうかの判断

| スキップ数 | 判断 | 対応 |
|-----------|------|------|
| 0～1 | 正常 | 特に何もしなくて大丈夫 |
| 2～10 | やや注意 | ケーブルの接触やノイズをチェック |
| 11～ | 要確認 | 検出器またはコンピューターの問題を調査 |

## データ品質の確認方法

### 1. ログメッセージで確認

DAQ実行中、ターミナルを見ていて警告メッセージが出ていないか確認します：

```bash
$ haniwers-v1 daq --config daq.toml
# ← ここでログメッセージを見ます
```

メッセージが出ていなければ、全てのデータが正常に受け取られています。

### 2. CSVファイルで確認

DAQが完了後、生成されたCSVファイルを確認します：

```bash
# 出力ファイルの行数を確認
wc -l 20250102/osechi_data.csv
# 出力例: 1001 20250102/osechi_data.csv （ヘッダー行 + 1000行のデータ）
```

行数が期待値より大幅に少ない場合は、通信問題の可能性があります。

### 3. データの内容で確認

```bash
# 最初の数行を確認
head -5 20250102/osechi_data.csv

# 最後の数行を確認
tail -5 20250102/osechi_data.csv
```

全てのフィールドが正常に数値で埋まっていれば、データは正常です。

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

### 問題：「Skipped invalid line」が多く表示される

#### 確認項目

1. **ケーブルの接触**
   - USB ケーブルをコンピューターとOSECHIの両方から抜いて、再度接続
   - ケーブルが破損していないか確認

2. **ケーブル周辺のノイズ**
   - USB ケーブルを他の電子機器（冷蔵庫、モニター等）から遠ざける
   - 金属机ではなく、木机で実験する

3. **ボーレート設定**
   - 現在のボーレートを確認：`cat daq.toml | grep baudrate`
   - デフォルト（115200）以外が設定されていないか確認

4. **OSECHI検出器の状態**
   - 検出器の電源がしっかり入っているか
   - 検出器のLEDが点灯しているか
   - 数分間待ってから再度試す（ウォームアップ完了を待つ）

### 問題：「haniwers port test」でエラーが出る

```bash
haniwers-v1 port test /dev/ttyUSB0
```

#### 対応方法

| エラー | 原因 | 対応 |
|--------|------|------|
| Connection timeout | 検出器がデータを送信していない | 検出器の電源確認、ケーブル接続確認 |
| Permission denied | ポートアクセス権限がない | `sudo`で実行、またはユーザー権限の設定 |
| Port not found | ポート名が間違っている | `haniwers-v1 port list`で確認 |

### 問題：「すべてのデータがスキップされた」

#### これは異常です。以下を確認してください

1. **ポート名が正しいか**
   ```bash
   haniwers-v1 port list
   ```

2. **ボーレートが正しいか**
   ```bash
   grep baudrate daq.toml
   ```

3. **OSECHI検出器が動作しているか**
   ```bash
   haniwers-v1 port test /dev/ttyUSB0
   ```

4. **タイムアウト値が短すぎないか**
   ```bash
   grep timeout daq.toml
   ```
   マイクロ秒単位の値を確認。基本的には 1.0 以上を推奨。

## ベストプラクティス

### 良いデータ取得のために

1. **測定前のチェック**
   ```bash
   # 毎回、測定開始前にポートをテスト
   haniwers-v1 port test /dev/ttyUSB0
   ```

2. **長時間の測定の前に短テストを**
   ```bash
   # 10秒程度の短いDAQで動作確認
   haniwers-v1 daq --config daq.toml --duration 10
   ```

3. **環境の最適化**
   - 金属机を避ける
   - USB ハブの使用を避ける（直接つなぐ）
   - 他の USB デバイスを外す

4. **ログをチェック**
   - 毎回のDAQ完了後、ログメッセージを確認
   - 「Skipped」メッセージが0なら完璧

### 記録とトレンド管理

複数回の測定を行う場合、各回のスキップ数を記録しましょう：

| 日時 | スキップ数 | 環境 | コメント |
|------|----------|------|---------|
| 2025-01-10 | 0 | オフィス | 良好 |
| 2025-01-11 | 2 | オフィス | ノイズあり |
| 2025-01-12 | 15 | ラボ | 要確認 |

増加傾向が見られたら、機器の不具合を疑ってください。

## よくある質問

### Q: スキップ数が1～2で大丈夫ですか？

**A**: 大丈夫です。通常のシリアル通信では、このレベルのノイズは避けられません。データ品質への影響はほぼなし。

### Q: 全てのデータをスキップしたくありません

**A**: `haniwers`は不正なデータをスキップするだけです。正常なデータは全て保存されます。スキップされるのは本当に不正なデータだけなので、ご安心を。

### Q: ケーブルを交換したら改善しました

**A**: USB ケーブルの経年劣化やノイズ影響はよくあります。新しいケーブル（シールド入り）に交換することをお勧めします。

### Q: Linux/macOS/Windows で結果が異なります

**A**: シリアル通信の実装がOS間で異なるため、同じハードウェアでも環境によってノイズの影響が変わることがあります。最適なボーレートやタイムアウト値も環境依存です。

## 参考資料

- **[ポート管理ガイド](./port.md)**: シリアルポートの確認とテスト方法
- **[DAQ設定ガイド](./daq.md)**: `daq.toml`の詳細パラメータ
- **[トラブルシューティング](../faq.md)**: より詳しい問題解決方法