# 測定ワークフロー概要

このページでは、OSECHI検出器を使った宇宙線データ収集の全体的な流れを説明します。

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

---

## 📋 測定の準備

### 1. 機器のセットアップ

**必要な機材**:

- OSECHI検出器本体
- 測定用PC（macOS、Linux、またはRaspberry Pi）
- USB-Cケーブル

**オプション機材**:

- おんどとり（外部温度ロガー）: OSECHI内蔵のBME280センサーデータと比較するための参照用

**手順**:

1. PCを起動する
2. OSECHIとPCをUSB-Cケーブルで接続する
3. OSECHIの電源をONにする
4. `haniwers-v1 port list`でポートを確認する

### 2. おんどとりの記録開始（オプション）

:::{note}
おんどとりは外部温度ロガーです。
OSECHI内蔵のBME280センサー（温度・湿度・気圧）データと比較するための参照用として使用します。
測定に必須ではありません。
:::

**手順**:

1. スマホアプリを起動して、おんどとりと接続する
2. 予約記録を開始する
3. 開始時刻をランシートに記入する

---

## 🔧 閾値の設定

### 3. 閾値スキャン（初回または環境変更時）

宇宙線イベントを正しく検出するため、最適な閾値を探します。

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

**確認事項**:

- スキャンが正常に完了したか
- 各チャンネルのカウントレートが妥当か
- OSECHI本体のLEDが正常に点滅しているか

:::{caution}
**測定環境による閾値の変化**

適正な閾値は、測定環境（温度、湿度、設置場所）によって変化します。
測定場所を変更した場合は、閾値を再スキャンして動作確認することを推奨します。

LEDの光り方がおかしいと感じるときは、閾値を再測定してください。
:::

### 4. 閾値の書き込み

スキャン結果から決定した最適閾値を検出器に設定します。

```bash
# 全チャンネル一括設定
haniwers-v1 threshold write --thresholds "1:280;2:310;3:320"
```

**記録事項**:

- 設定した閾値をランシートに記入する
- OSECHI本体のLEDの光り方を確認して記録する

---

## 📊 データ収集

### 5. DAQの開始

```bash
# 標準DAQ（イベント数ベース）
haniwers-v1 daq

# 時間ベースDAQ（1時間測定）
haniwers-v1 daq --duration 3600
```

**記録事項**:

- 開始時刻をランシートに記入する
- 測定条件（閾値、モード、予定測定時間）を記録する

:::{hint}
**測定ログの重要性**

測定を開始・終了した時刻や、途中経過の時刻などチェック項目を決めておくことで、データ測定に異変がないか早めに気がつくことができます。

また、測定中に感じた違和感は、できるだけログノートに残すように心がけましょう。
きちんと言語化することは、問題や原因を考えるきっかけになります。
:::

### 6. DAQの終了

**手順**:

1. `Ctrl+C`でデータ測定を終了する
2. 終了時刻をランシートに記入する
3. 出力ファイルが正常に保存されているか確認する

:::{note}
**安全な測定中断**

中断コマンド（`Ctrl+C`）を送信することで、測定中のファイルを正常に閉じることができます。

v0.15以降のバージョンでは、ファイル名にタイムスタンプをつけて保存するように変更しました。
コマンドを実行するたびに別ファイルが作成されるため、誤操作で中断してしまった場合には、そのまますぐに再開して問題ありません。
:::

---

## 📁 データの整理と保存

### 7. おんどとりの記録停止（オプション）

**手順**:

1. スマホアプリを起動して、おんどとりと接続する
2. 現在時刻までのデータをファイルに書き出す
3. 書き出したファイルをパソコンに転送する（macの場合はAirDrop）
4. 終了時刻をランシートに記入する

### 8. 測定データの整理

**推奨ディレクトリ構造**:

```text
raw_data/
  ├── 20250101_run001/
  │   ├── osechi_data_*.csv      # OSECHI測定データ
  │   └── ondotori_*.csv          # おんどとりデータ（オプション）
  └── 20250102_run002/
      └── ...
```

**手順**:

1. 測定データのディレクトリ名を`日付_run番号`に変更する
2. おんどとりのデータをこのディレクトリの中に移動する（使用した場合）
3. ディレクトリ全体を`Googleドライブ/raw_data/`に移動する

:::{hint}
**GUI操作の推奨**

ファイル整理はGUIを使って操作すればOKです。
コマンドライン操作より、間違えにくく安全です。
:::

---

## 🔄 データの変換と解析

測定したデータを解析しやすい形式に変換します。v0では2つの変換コマンドが利用できます。

### 9a. 簡易データ変換（測定中の確認用）

測定中にデータを素早く確認したい場合は、`raw2tmp`コマンドを使用します。

```bash
# 基本的な使い方（測定中のディレクトリを指定）
haniwers-v0 raw2tmp データディレクトリ

# リサンプリング間隔を指定（デフォルト: 600秒=10分）
haniwers-v0 raw2tmp データディレクトリ --interval 300

# タイムゾーン指定
haniwers-v0 raw2tmp データディレクトリ --tz "UTC+09:00"
```

**出力ファイル**:

- `tmp_raw2tmp.csv.gz`: 全イベントの生データ（圧縮）
- `tmp_raw2tmp.csv`: リサンプリングされたデータ

:::{tip}
`raw2tmp`は測定の途中経過を素早くチェックするためのコマンドです。本格的な解析には次の`run2csv`を使用してください。
:::

### 9b. 本格的なデータ変換（解析用）

測定完了後、ランシートの情報を使って正式なデータ変換を行います。

```bash
# runs.csvの準備（ランシート情報をCSV形式で保存）
# run_id, start_time, end_time, thresholds などを記録

# プレビューモード（保存せずに確認）
haniwers-v0 run2csv 98

# 本番変換（ファイル保存）
haniwers-v0 run2csv 98 --save

# カスタム設定ファイルとデータディレクトリ指定
haniwers-v0 run2csv 98 --save --load-from runs.csv --drive ../data
```

**手順**:

1. ランシート（Googleスプレッドシート）の情報を`runs.csv`にエクスポートする
2. `run2csv`コマンドでrun_idを指定して変換する
3. `--save`オプションで解析用データを保存する

**出力ファイル**:

- `run{id}_raw.csv.gz`: 全イベントの生データ（圧縮）
- `run{id}_resampled.csv`: リサンプリングされたデータ

:::{note}
**v0とv1の違い**

データ変換コマンド（`raw2tmp`、`run2csv`）は現在v0のみで利用可能です。
v1での実装は今後予定されています。
:::

---

## 📝 記録すべき情報

測定の再現性を確保するため、以下の情報をランシートに記録してください。

:::{note}
**ランシートについて**

TanQ/FunQプロジェクトでは、測定記録をGoogleスプレッドシートで管理しています。
測定条件や結果を共同研究者と共有し、データの追跡と再現性を確保するため、必ず記録を残してください。
:::

**必須項目**:

- 測定日時（開始・終了）
- 設定した閾値（ch1、ch2、ch3）
- 測定モード（count_based / time_based）
- 出力ファイル数とイベント数

**推奨項目**:

- 測定場所と環境条件（温度、湿度）
- OSECHI本体のシリアル番号
- 使用したPC・OSのバージョン
- 異常や気づいた点

---

## 🎯 次のステップ

測定の各ステップの詳細は、以下のドキュメントを参照してください：

- [設定ファイルの作成](./config.md): 測定パラメーターの設定方法
- [ポート管理](./port.md): シリアルポートの確認と接続テスト
- [閾値スキャン](./scan.md): 最適閾値の探索方法
- [データ収集](./daq.md): 長期測定の実行方法
- [データ品質](./data-quality.md): ノイズ対処とデータ品質確認