# データフォーマット

`haniwers` で収集・処理されたデータの構造を理解することは、効果的なデータ解析の第一歩です。
このドキュメントでは、生データから集計データまで、各段階でのカラム（列）の定義と意味を解説します。

## データ処理パイプライン

```text
生データ (.csv)
    ↓ [前処理]
前処理後 (.csv.gz)
    ↓ [集計]
集計データ (.csv)
```

## 生データ（`.csv`）のカラム

DAQで直接取得された生データのカラム定義です。

**`datetime`**
: イベント発生時刻。ISO8601形式で記録されます。

- `YYYY-MM-DDTHH:mm:ss` (tz-naive)
- `YYYY-MM-DDTHH:mm:SSZ` (tz-aware)

使用したDAQのバージョンによって形式が異なります。

**`top`, `mid`, `btm`**
: 各シンチレーターのヒット検出。数値は光センサー（SiPM）からのシグナルの有無を表します。

- `> 0`: ヒット検出あり
- `= 0`: ヒット検出なし

> **重要**: ヒット判定は `値 > 0` で行います。値の大きさ自体は物理的な意味はありません。

**`adc`**
: 上段シンチレーターのADC値（光量に比例）

**`tmp`**
: 気温（単位: ℃）

**`atm`**
: 気圧（単位: Pa）

**`hmd`**
: 湿度（単位: %）

### データ例

```csv
datetime,top,mid,btm,adc,tmp,atm,hmd
2024-10-21T10:30:45,450,380,410,2500,23.5,101325,45.2
2024-10-21T10:30:46,0,0,0,0,23.5,101325,45.2
2024-10-21T10:30:47,520,420,480,2800,23.6,101325,45.3
```

---

## 前処理後のデータ（`.csv.gz`）のカラム

生データに対して以下の処理を適用した結果です：

**生データのカラム**
: すべての生データカラムがそのまま含まれます。

**`hit_top`, `hit_mid`, `hit_btm`**
: 各シンチレーターのヒット判定（0または1）

- `1`: `raw_value > 0` でヒット
- `0`: `raw_value = 0` でノーヒット

**`hit_type`**
: 3層シンチの同時検出パターンを8ビットで表現した十進数値

- `hit_top × 4 + hit_mid × 2 + hit_btm × 1`

### ヒットパターン一覧

| hit_type | top | mid | btm | 検出パターン |
|:---:|:---:|:---:|:---:|:---|
| 0 | 0 | 0 | 0 | ノーヒット |
| 1 | 0 | 0 | 1 | 下層のみ |
| 2 | 0 | 1 | 0 | 中層のみ |
| 3 | 0 | 1 | 1 | 中層+下層 |
| 4 | 1 | 0 | 0 | 上層のみ |
| 5 | 1 | 0 | 1 | 上層+下層 |
| 6 | 1 | 1 | 0 | 上層+中層（**宇宙線典型**） |
| 7 | 1 | 1 | 1 | 全層検出（**宇宙線典型**） |

> **解析のヒント**: `hit_type = 6` または `hit_type = 7` が宇宙線イベントの指標です。

---

## 集計データ（`.csv`）のカラム

複数のイベントを時間窓ごとに集計した統計データです。

### 基本カラム

**`time`**
: 集計時間ウィンドウの開始時刻

**`events`**
: そのウィンドウ内のイベント総数

**`hit_type`**
: ウィンドウ内での各ヒットパターンの発生回数（0～7）

**`hit_top`, `hit_mid`, `hit_btm`**
: 各シンチレーターのヒット回数

### 統計カラム

**`adc_mean`, `adc_std`**
: ADC値の平均値と標準偏差

**`tmp_mean`, `tmp_std`**
: 気温の平均値と標準偏差

**`atm_mean`, `atm_std`**
: 気圧の平均値と標準偏差

**`hmd_mean`, `hmd_std`**
: 湿度の平均値と標準偏差

### レート計算カラム

**`event_rate`**
: 全イベントのレート（イベント/秒）

**`event_rate_top`, `event_rate_mid`, `event_rate_btm`**
: 各シンチレーターのヒットレート（ヒット/秒）

### メタデータカラム

**`interval`**
: 集計時間ウィンドウの間隔（秒）

**`days`**
: 測定開始からの経過日数

**`seconds`**
: 測定開始からの経過秒数

**`runid`**
: データ取得実行の識別子

**`name`**
: 測定セッションの名前

**`description`**
: 測定条件などの説明文

---

## 解析ワークフローの例

### 1. 生データの確認

```python
import pandas as pd

# 生データを読み込み
df = pd.read_csv("osechi_data_20241021.csv")

# 基本統計
print(df.describe())

# ヒット検出の確認
print(f"Total events: {len(df)}")
print(f"Top hits: {(df['top'] > 0).sum()}")
```

### 2. 前処理後のヒットパターン分析

```python
# 前処理後データを読み込み
df_processed = pd.read_csv("osechi_data_20241021.csv.gz")

# 宇宙線の可能性が高いイベント
cosmic_rays = df_processed[df_processed['hit_type'].isin([6, 7])]

print(f"Possible cosmic ray events: {len(cosmic_rays)}")
print(f"Percentage: {len(cosmic_rays) / len(df_processed) * 100:.2f}%")
```

### 3. 時系列解析

```python
# 集計データを読み込み
df_aggregated = pd.read_csv("aggregated_data_20241021.csv")

# イベントレートの時間変化
df_aggregated['time'] = pd.to_datetime(df_aggregated['time'])
df_aggregated.set_index('time').plot(y='event_rate')
```

---

## よくある質問

**Q: `hit_type` はなぜ必要？**
A: 3層検出器の同時検出パターンから宇宙線を識別できます。バックグラウンドノイズは通常1層のみの検出（hit_type = 1, 2, 4）ですが、宇宙線は複数層の同時検出（hit_type = 6, 7）の傾向があります。

**Q: 生データと前処理後データの差は？**
A: 前処理は主にヒット判定の二値化（0/1）と `hit_type` の計算を行います。元のアナログ値（top, mid, btm, adc）は保持されるため、あとで異なる条件で再処理することも可能です。

**Q: 集計データはいつ使う？**
A: 長期間の測定データで全体的なトレンドや日次変動を分析する場合に有用です。一方、詳細なイベント解析には前処理後のデータを使用します。