# データ前処理ガイド このページでは、`haniwers` で収集した生データをCVS形式に変換・前処理するための `preprocess` コマンドの使い方を解説します。 ## 概要 `preprocess` コマンドは、生データから以下の2つの出力ファイルを生成します： 1. **前処理済みデータ** (`processed.csv.gz`) - 生データにヒット判定・hit_type計算を追加 2. **集計データ** (`resampled.csv`) - 時間窓ごとに統計量を集計 ## コマンド一覧 2つのコマンドが利用可能です： - **`raw2csv`** - フル機能の前処理（推奨：細かい制御が必要な場合） - **`raw2tmp`** - クイック変換（推奨：高速処理と v0 互換性重視） ## raw2csv: フル前処理パイプライン 最も汎用的な前処理コマンドです。タイムゾーン、時間オフセット、集計間隔をカスタマイズできます。 ### 基本的な使い方 ```bash haniwers-v1 preprocess raw2csv <データディレクトリ> --save ``` ### 例 #### 1. 最も簡単な使い方 ```bash # ディレクトリ内のすべての CSV ファイルを処理 haniwers-v1 preprocess raw2csv sandbox/test_data/20240611_run93 --save ``` **出力:** - `processed.csv.gz` - 前処理済みデータ - `resampled.csv` - 10分単位（デフォルト）の集計データ #### 2. 集計間隔をカスタマイズ ```bash # 5分単位の集計 haniwers-v1 preprocess raw2csv data/ --interval 300 --save # 1時間単位の集計 haniwers-v1 preprocess raw2csv data/ --interval 3600 --save ``` #### 3. タイムゾーンを変更 ```bash # JST（日本標準時）を指定 haniwers-v1 preprocess raw2csv data/ --tz UTC+09:00 --save # IANA タイムゾーン形式 haniwers-v1 preprocess raw2csv data/ --tz Asia/Tokyo --save ``` #### 4. 時間オフセットを適用 測定時刻にズレがある場合、秒単位でオフセットを指定できます： ```bash # すべてのタイムスタンプに 30秒を加算 haniwers-v1 preprocess raw2csv data/ --offset 30 --save # 1分を減算（負の値） haniwers-v1 preprocess raw2csv data/ --offset -60 --save ``` #### 5. ファイルパターンを指定 デフォルトでは `*.csv` にマッチするファイルを処理します。 別のパターンを指定できます： ```bash # "osechi_data_*.csv" ファイルのみ処理 haniwers-v1 preprocess raw2csv data/ --pattern "osechi_data_*.csv" --save # "scan_*.csv" ファイルのみ処理 haniwers-v1 preprocess raw2csv data/ --pattern "scan_*.csv" --save ``` #### 6. 詳細ログを表示 ```bash # 処理中の詳細情報を表示 haniwers-v1 preprocess raw2csv data/ --save --verbose ``` ### オプション一覧 | オプション | デフォルト | 説明 | |:---|:---|:---| | `--save` | なし（出力なし） | ファイルに保存するかどうか | | `--interval` | 600 | 集計時間ウィンドウ（秒） | | `--offset` | 0 | タイムスタンプのオフセット（秒） | | `--tz` | UTC+09:00 | タイムゾーン | | `--pattern` | `*.csv` | ファイルマッチングパターン | | `--verbose` | なし | 詳細ログを表示 | --- ## raw2tmp: クイック変換（v0互換） 高速な前処理が必要な場合、または v0 との互換性を重視する場合に使用します。 ### 特徴 - **常に自動保存**: `--save` フラグ不要 - **固定設定**: タイムゾーンは UTC+09:00、オフセットなし - **v0互換出力**: ファイル名が `tmp_raw2tmp.csv.gz`, `tmp_raw2tmp.csv` で統一 ### 基本的な使い方 ```bash haniwers-v1 preprocess raw2tmp <データディレクトリ> ``` ### 例 #### 1. 最も簡単な使い方 ```bash haniwers-v1 preprocess raw2tmp sandbox/test_data/20240611_run93 ``` **自動で以下のファイルが保存されます:** - `tmp_raw2tmp.csv.gz` - 前処理済みデータ - `tmp_raw2tmp.csv` - 10分単位の集計データ #### 2. 集計間隔を変更 ```bash # 5分単位 haniwers-v1 preprocess raw2tmp data/ --interval 300 # 1時間単位 haniwers-v1 preprocess raw2tmp data/ --interval 3600 ``` #### 3. ファイルパターンを指定 ```bash haniwers-v1 preprocess raw2tmp data/ --pattern "osechi_data_*.csv" ``` ### オプション一覧 | オプション | デフォルト | 説明 | |:---|:---|:---| | `--interval` | 600 | 集計時間ウィンドウ（秒） | | `--pattern` | `*.csv` | ファイルマッチングパターン | --- ## 処理の流れ 両コマンドは、以下のパイプラインで処理されます： ``` 生データ (.csv) ↓ [ステップ1] ファイルを読み込み・統合 ↓ [ステップ2] タイムスタンプをパース（タイムゾーン・オフセット適用） ↓ [ステップ3] ヒット判定を計算（hit_top, hit_mid, hit_btm） ↓ [ステップ4] hit_type を計算（3層の同時検出パターン） ↓ [ステップ5] 時間ウィンドウで集計 ↓ [ステップ6] 統計量を計算（平均、標準偏差、レート） ↓ 前処理済みデータ (.csv.gz) ← 保存 集計データ (.csv) ← 保存 ``` --- ## 出力ファイルの解説 ### 前処理済みデータ (`processed.csv.gz`) 元の生データにヒット判定と hit_type を追加したもの。すべてのイベント情報を保持： ```csv datetime,top,mid,btm,adc,tmp,atm,hmd,time,hit_top,hit_mid,hit_btm,hit_type 2024-06-11 06:32:24.755250+09:00,0,2,0,0,30.12,100161.0,42.26,2024-06-11 06:32:24.755250+09:00,0,1,0,2 2024-06-11 06:32:30.976835+09:00,0,0,5,0,30.07,100160.33,42.29,2024-06-11 06:32:30.976835+09:00,0,0,1,1 ... ``` 詳細は [データフォーマット](./data-format.md) を参照してください。 ### 集計データ (`resampled.csv`) 指定した時間ウィンドウごとに統計量を集計したデータ： ```csv time,hit_type,events,adc_mean,adc_std,tmp_mean,tmp_std,atm_mean,atm_std,hmd_mean,hmd_std,event_rate,event_rate_top,event_rate_mid,event_rate_btm 2024-06-11 06:30:00+09:00,1,32,0.0,0.0,30.17,0.053,100157.5,3.76,42.27,0.081,0.053,0.0,0.0,0.018 2024-06-11 06:40:00+09:00,6,128,0.0,0.0,30.21,0.042,100159.2,2.45,42.31,0.076,0.213,0.067,0.080,0.045 ... ``` --- ## よくある使用パターン ### パターン1: 新しいデータセットを素早く確認 ```bash # 高速処理（raw2tmp推奨） haniwers-v1 preprocess raw2tmp raw_data/ ``` ### パターン2: 詳細な解析前に精密処理 ```bash # フル機能（raw2csv推奨） haniwers-v1 preprocess raw2csv raw_data/ --interval 600 --verbose --save ``` ### パターン3: 異なるタイムゾーンでの処理 ```bash # ローカルタイムゾーンでタイムスタンプを再計算 haniwers-v1 preprocess raw2csv raw_data/ --tz Asia/Tokyo --save ``` ### パターン4: 複数の集計単位で比較 ```bash # 5分単位の細粒度データ haniwers-v1 preprocess raw2csv raw_data/ --interval 300 --save # 別の出力ディレクトリで 1時間単位の粗粒度データ cd aggregated_1h/ haniwers-v1 preprocess raw2csv ../raw_data/ --interval 3600 --save ``` --- ## データ構造の確認コマンド 前処理前後のデータを確認するための便利なシェルコマンドを紹介します。 ### 生データ（`.csv`）の確認 #### ファイル情報 ```bash # ファイルサイズを確認 ls -lh osechi_data_*.csv # ファイルの行数を確認 wc -l osechi_data_*.csv # 複数ファイルの合計行数 cat osechi_data_*.csv | wc -l ``` #### データの先頭を確認 ```bash # 最初の5行を表示 head -5 osechi_data_2024-06-11T06h32m14s_0000000.csv # カラム名を確認（ヘッダーがない場合は最初のデータ行が表示） head -1 osechi_data_2024-06-11T06h32m14s_0000000.csv ``` #### データの統計情報 ```bash # ファイルの概要を表示 head -3 osechi_data_2024-06-11T06h32m14s_0000000.csv | column -t -s',' # データのユニークな日時範囲を確認 head -1 osechi_data_*.csv | cut -d',' -f1 tail -1 osechi_data_*.csv | cut -d',' -f1 ``` #### 特定のカラムを確認 ```bash # top カラムの値を確認（最初の10個） cut -d',' -f2 osechi_data_2024-06-11T06h32m14s_0000000.csv | head -10 # adc カラムの統計（値がすべて数値か確認） cut -d',' -f5 osechi_data_2024-06-11T06h32m14s_0000000.csv | sort -n | tail -5 ``` --- ### 前処理済みデータ（`.csv.gz`）の確認 > **注記**: `zcat` コマンドは `gunzip --decompress --stdout` と同等です。`zcat` が使えない環境では `gunzip -d -c processed.csv.gz` に置き換えてください。 #### ファイル情報 ```bash # 圧縮ファイルのサイズを確認 ls -lh processed.csv.gz # 圧縮前のサイズを確認 gunzip -l processed.csv.gz # 行数を確認（フルスキャン） zcat processed.csv.gz | wc -l ``` #### データの先頭を確認 ```bash # 最初の5行を表示 zcat processed.csv.gz | head -5 # カラム名を確認 zcat processed.csv.gz | head -1 # データを整形して表示 zcat processed.csv.gz | head -3 | column -t -s',' ``` #### カラム構成の確認 ```bash # カラム数をカウント zcat processed.csv.gz | head -1 | tr ',' '\n' | nl # カラム名と型の一覧 zcat processed.csv.gz | head -1 | tr ',' '\n' | awk '{print NR": "$0}' ``` #### 特定カラムのデータ確認 ```bash # hit_type のユニーク値を確認（0-7のみ含まれるか） zcat processed.csv.gz | cut -d',' -f13 | sort | uniq -c # time カラムの範囲を確認 zcat processed.csv.gz | cut -d',' -f9 | head -1 zcat processed.csv.gz | cut -d',' -f9 | tail -1 # adc カラムのヒストグラム（簡易版） zcat processed.csv.gz | cut -d',' -f5 | tail -n +2 | sort -n | tail -10 ``` #### データの整合性を確認 ```bash # 圧縮ファイルが正常か確認（エラーがなければ何も表示されない） gzip -t processed.csv.gz && echo "✓ ファイルは正常" # 重複した datetime がないか確認 zcat processed.csv.gz | cut -d',' -f1 | sort | uniq -d | wc -l ``` --- ### 集計データ（`.csv`）の確認 #### ファイル情報 ```bash # ファイルサイズを確認 ls -lh resampled.csv # 行数を確認（集計時間ウィンドウの数） wc -l resampled.csv # カラム数を確認 head -1 resampled.csv | tr ',' '\n' | wc -l ``` #### データの先頭と末尾を確認 ```bash # 最初の5行を表示 head -5 resampled.csv # カラム名を確認 head -1 resampled.csv | tr ',' '\n' | nl # データを整形して表示 head -3 resampled.csv | column -t -s',' ``` #### 集計期間の確認 ```bash # 時間ウィンドウの開始と終了を確認 head -2 resampled.csv | cut -d',' -f1 tail -1 resampled.csv | cut -d',' -f1 # 総測定時間を計算 echo "Total rows: $(tail -n +2 resampled.csv | wc -l)" echo "Interval (seconds): $(head -1 resampled.csv | tr ',' '\n' | grep -n interval | cut -d: -f1)" ``` #### イベント統計の確認 ```bash # イベント数の合計 tail -n +2 resampled.csv | cut -d',' -f3 | awk '{sum+=$1} END {print "Total events: " sum}' # hit_type の分布 tail -n +2 resampled.csv | cut -d',' -f2 | sort | uniq -c # イベントレートの範囲 tail -n +2 resampled.csv | cut -d',' -f12 | sort -n | awk 'NR==1 || NR==NF {print}' ``` --- ### データ検証スクリプト 前処理の結果を素早く確認するワンライナー： ```bash # 前処理前後のデータ比較 echo "=== 生データ情報 ===" wc -l osechi_data_*.csv | tail -1 echo "=== 前処理済みデータ ===" zcat processed.csv.gz | wc -l echo "=== 集計データ（ウィンドウ数） ===" tail -n +2 resampled.csv | wc -l echo "=== hit_type の分布 ===" zcat processed.csv.gz | cut -d',' -f13 | tail -n +2 | sort | uniq -c echo "=== イベント総数 ===" tail -n +2 resampled.csv | cut -d',' -f3 | awk '{sum+=$1} END {print sum}' ``` --- ## 高度なデータ検査：xan を使用 大規模なデータセットを効率的に検査する場合、**xan** (CSV parser) の使用をお勧めします。 ### xan のインストール ```bash # macOS brew install xan # Linux / その他 cargo install xan ``` ### xan の基本的な使い方 #### 生データ（`.csv`）の検査 ```bash # ファイルの基本情報 xan count osechi_data_2024-06-11T06h32m14s_0000000.csv # 最初の5行を表示 xan cat osechi_data_2024-06-11T06h32m14s_0000000.csv | head -5 # 特定カラムのみ表示 xan select datetime,top,mid,btm osechi_data_2024-06-11T06h32m14s_0000000.csv | head -5 # 統計情報を表示（カラムごと） xan stats osechi_data_2024-06-11T06h32m14s_0000000.csv ``` #### 前処理済みデータ（`.csv.gz`）の検査 **重要な利点**: `xan` は `.csv.gz` ファイルを直接読み込めます。`gunzip` で解凍する必要がありません。 ```bash # 行数を確認（圧縮ファイルから直接） xan count processed.csv.gz # 最初の5行を表示 xan cat processed.csv.gz | head -5 # 特定カラムのみ表示 xan select time,events,hit_type processed.csv.gz | head -5 # 統計情報を表示 xan stats processed.csv.gz # hit_type のカラムのみを確認 xan select hit_type processed.csv.gz | head -10 ``` #### 集計データ（`.csv`）の検査 ```bash # ウィンドウ数を確認 xan count resampled.csv # イベント統計を表示 xan select time,events,hit_type resampled.csv | head -5 # すべての統計情報 xan stats resampled.csv ``` ### xan の利点 ✅ `.csv.gz` ファイルを直接読み込める（解凍不要） ✅ 大規模ファイルで高速（Rust製） ✅ カラム選択が直感的 ✅ シンプルな構文 ✅ パイプライン処理に対応 ### xan vs シェルコマンド | 用途 | シェルコマンド | xan コマンド | |:---|:---|:---| | 行数カウント | `gunzip -d -c processed.csv.gz \| wc -l` | `xan count processed.csv.gz` | | 最初の5行 | `gunzip -d -c processed.csv.gz \| head -5` | `xan cat processed.csv.gz \| head -5` | | 統計情報 | 複数コマンドの組み合わせ | `xan stats processed.csv.gz` | | カラム選択 | `cut -d',' -f9` | `xan select time processed.csv.gz` | --- ## トラブルシューティング ### "No files matching pattern found" ファイルパターンが正しいか確認してください： ```bash # ファイル一覧を確認 ls -la /path/to/data/ # 正しいパターンを指定 haniwers-v1 preprocess raw2csv /path/to/data/ --pattern "osechi_data_*.csv" --save ``` ### 処理が遅い 大量のファイルを処理している可能性があります。以下の対策を試してください： ```bash # 1. 不要なファイルを除外 haniwers-v1 preprocess raw2csv data/ --pattern "osechi_data_*.csv" --save # 2. 粗い集計間隔を使用（メモリ削減） haniwers-v1 preprocess raw2csv data/ --interval 3600 --save ``` ### タイムゾーンエラー タイムゾーン指定が無効の場合、エラーが表示されます： ```bash # 正しい形式を使用 haniwers-v1 preprocess raw2csv data/ --tz UTC+09:00 --save # OK haniwers-v1 preprocess raw2csv data/ --tz Asia/Tokyo --save # OK haniwers-v1 preprocess raw2csv data/ --tz JST --save # NG（形式が無効） ``` --- ## 参考資料 - [データフォーマット](./data-format.md) - 前処理前後のデータ構造 - [データ解析](./analysis.md) - 前処理後のデータを使った解析方法 - [チュートリアル](./tutorial.md) - 実践的な解析例