データ前処理ガイド

目次

データ前処理ガイド#

このページでは、haniwers で収集した生データをCVS形式に変換・前処理するための preprocess コマンドの使い方を解説します。

概要#

preprocess コマンドは、生データから以下の2つの出力ファイルを生成します：

  1. 前処理済みデータ (processed.csv.gz) - 生データにヒット判定・hit_type計算を追加

  2. 集計データ (resampled.csv) - 時間窓ごとに統計量を集計

コマンド一覧#

2つのコマンドが利用可能です：

  • raw2csv - フル機能の前処理（推奨：細かい制御が必要な場合）

  • raw2tmp - クイック変換（推奨：高速処理と v0 互換性重視）

raw2csv: フル前処理パイプライン#

最も汎用的な前処理コマンドです。タイムゾーン、時間オフセット、集計間隔をカスタマイズできます。

基本的な使い方#

haniwers-v1 preprocess raw2csv <データディレクトリ> --save

例#

1. 最も簡単な使い方#

# ディレクトリ内のすべての CSV ファイルを処理
haniwers-v1 preprocess raw2csv sandbox/test_data/20240611_run93 --save

出力:

  • processed.csv.gz - 前処理済みデータ

  • resampled.csv - 10分単位（デフォルト）の集計データ

2. 集計間隔をカスタマイズ#

# 5分単位の集計
haniwers-v1 preprocess raw2csv data/ --interval 300 --save

# 1時間単位の集計
haniwers-v1 preprocess raw2csv data/ --interval 3600 --save

3. タイムゾーンを変更#

# JST（日本標準時）を指定
haniwers-v1 preprocess raw2csv data/ --tz UTC+09:00 --save

# IANA タイムゾーン形式
haniwers-v1 preprocess raw2csv data/ --tz Asia/Tokyo --save

4. 時間オフセットを適用#

測定時刻にズレがある場合、秒単位でオフセットを指定できます：

# すべてのタイムスタンプに 30秒を加算
haniwers-v1 preprocess raw2csv data/ --offset 30 --save

# 1分を減算（負の値）
haniwers-v1 preprocess raw2csv data/ --offset -60 --save

5. ファイルパターンを指定#

デフォルトでは *.csv にマッチするファイルを処理します。 別のパターンを指定できます：

# "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. 詳細ログを表示#

# 処理中の詳細情報を表示
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 で統一

基本的な使い方#

haniwers-v1 preprocess raw2tmp <データディレクトリ>

例#

1. 最も簡単な使い方#

haniwers-v1 preprocess raw2tmp sandbox/test_data/20240611_run93

自動で以下のファイルが保存されます:

  • tmp_raw2tmp.csv.gz - 前処理済みデータ

  • tmp_raw2tmp.csv - 10分単位の集計データ

2. 集計間隔を変更#

# 5分単位
haniwers-v1 preprocess raw2tmp data/ --interval 300

# 1時間単位
haniwers-v1 preprocess raw2tmp data/ --interval 3600

3. ファイルパターンを指定#

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 を追加したもの。すべてのイベント情報を保持：

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
...

詳細は データフォーマット を参照してください。

集計データ (resampled.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: 新しいデータセットを素早く確認#

# 高速処理（raw2tmp推奨）
haniwers-v1 preprocess raw2tmp raw_data/

パターン2: 詳細な解析前に精密処理#

# フル機能（raw2csv推奨）
haniwers-v1 preprocess raw2csv raw_data/ --interval 600 --verbose --save

パターン3: 異なるタイムゾーンでの処理#

# ローカルタイムゾーンでタイムスタンプを再計算
haniwers-v1 preprocess raw2csv raw_data/ --tz Asia/Tokyo --save

パターン4: 複数の集計単位で比較#

# 5分単位の細粒度データ
haniwers-v1 preprocess raw2csv raw_data/ --interval 300 --save

# 別の出力ディレクトリで 1時間単位の粗粒度データ
cd aggregated_1h/
haniwers-v1 preprocess raw2csv ../raw_data/ --interval 3600 --save

データ構造の確認コマンド#

前処理前後のデータを確認するための便利なシェルコマンドを紹介します。

生データ（.csv）の確認#

ファイル情報#

# ファイルサイズを確認
ls -lh osechi_data_*.csv

# ファイルの行数を確認
wc -l osechi_data_*.csv

# 複数ファイルの合計行数
cat osechi_data_*.csv | wc -l

データの先頭を確認#

# 最初の5行を表示
head -5 osechi_data_2024-06-11T06h32m14s_0000000.csv

# カラム名を確認（ヘッダーがない場合は最初のデータ行が表示）
head -1 osechi_data_2024-06-11T06h32m14s_0000000.csv

データの統計情報#

# ファイルの概要を表示
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

特定のカラムを確認#

# 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 に置き換えてください。

ファイル情報#

# 圧縮ファイルのサイズを確認
ls -lh processed.csv.gz

# 圧縮前のサイズを確認
gunzip -l processed.csv.gz

# 行数を確認（フルスキャン）
zcat processed.csv.gz | wc -l

データの先頭を確認#

# 最初の5行を表示
zcat processed.csv.gz | head -5

# カラム名を確認
zcat processed.csv.gz | head -1

# データを整形して表示
zcat processed.csv.gz | head -3 | column -t -s','

カラム構成の確認#

# カラム数をカウント
zcat processed.csv.gz | head -1 | tr ',' '\n' | nl

# カラム名と型の一覧
zcat processed.csv.gz | head -1 | tr ',' '\n' | awk '{print NR": "$0}'

特定カラムのデータ確認#

# 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

データの整合性を確認#

# 圧縮ファイルが正常か確認（エラーがなければ何も表示されない）
gzip -t processed.csv.gz && echo "✓ ファイルは正常"

# 重複した datetime がないか確認
zcat processed.csv.gz | cut -d',' -f1 | sort | uniq -d | wc -l

集計データ（.csv）の確認#

ファイル情報#

# ファイルサイズを確認
ls -lh resampled.csv

# 行数を確認（集計時間ウィンドウの数）
wc -l resampled.csv

# カラム数を確認
head -1 resampled.csv | tr ',' '\n' | wc -l

データの先頭と末尾を確認#

# 最初の5行を表示
head -5 resampled.csv

# カラム名を確認
head -1 resampled.csv | tr ',' '\n' | nl

# データを整形して表示
head -3 resampled.csv | column -t -s','

集計期間の確認#

# 時間ウィンドウの開始と終了を確認
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)"

イベント統計の確認#

# イベント数の合計
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}'

データ検証スクリプト#

前処理の結果を素早く確認するワンライナー：

# 前処理前後のデータ比較
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 のインストール#

# macOS
brew install xan

# Linux / その他
cargo install xan

xan の基本的な使い方#

生データ（.csv）の検査#

# ファイルの基本情報
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 で解凍する必要がありません。

# 行数を確認（圧縮ファイルから直接）
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）の検査#

# ウィンドウ数を確認
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”#

ファイルパターンが正しいか確認してください：

# ファイル一覧を確認
ls -la /path/to/data/

# 正しいパターンを指定
haniwers-v1 preprocess raw2csv /path/to/data/ --pattern "osechi_data_*.csv" --save

処理が遅い#

大量のファイルを処理している可能性があります。以下の対策を試してください：

# 1. 不要なファイルを除外
haniwers-v1 preprocess raw2csv data/ --pattern "osechi_data_*.csv" --save

# 2. 粗い集計間隔を使用（メモリ削減）
haniwers-v1 preprocess raw2csv data/ --interval 3600 --save

タイムゾーンエラー#

タイムゾーン指定が無効の場合、エラーが表示されます：

# 正しい形式を使用
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（形式が無効）

参考資料#

目次