haniwers.preprocess

haniwers.preprocess#

Data Preprocessing and Cleaning for Raw Detector Data.

This module converts raw detector output files into clean, structured data that’s ready for analysis. It handles parsing, validation, and transformation of cosmic ray event data.

What Does This Module Do?

The preprocessing module:

  1. Reads raw detector data files (CSV or DAT format)

  2. Parses the raw data fields into meaningful quantities

  3. Validates data integrity and handles missing values

  4. Adds derived quantities (hit patterns, event types)

  5. Saves cleaned data in standard formats

Data Processing Pipeline

Raw File → Parse → Add Fields → Validate → Clean Data

Example flow:

  • Raw detector sends: 255,120,0,512,25.5,101325,65

  • Parsed as: top=255, mid=120, btm=0, adc=512, tmp=25.5, atm=101325, hmd=65

  • Added fields: hit_top=1 (because 255>threshold), hit_pattern=3

  • Output: Clean CSV with all fields ready for analysis

Key Functions

get_fnames() : Find data files matching a search pattern read_data_with_pandas() : Load multiple data files into a DataFrame add_hit() : Add binary hit indicators (detected or not detected) add_hit_type() : Add event type classification based on hit pattern preprocess() : Run complete preprocessing pipeline

File Format Support

  • .csv: Comma-separated values (preferred)

  • .dat: Raw detector format (automatically converted)

Example Usage

from haniwers.config import RunData
from haniwers.preprocess import preprocess

run = RunData(run_id=1, read_from="data/run001/")
data = preprocess(run)  # Get cleaned data
print(f"Processed {len(data)} events")
print(data.columns)  # See available data fields

Module Contents#

Functions#

get_fnames

測定データの一覧を取得

read_data_with_pandas

pd.DataFrameに変換

read_data_with_polars

pl.DataFrameに変換

read_data

測定データをデータフレームに変換

add_time

timeカラムを追加

add_hit

hitカラムを追加

add_hit_type

hit_typeカラムを追加

resample_data

測定データをリサンプル

resample_data_with_hit_type

測定データをリサンプル

preprocess_data

測定データを前処理する

raw2csv

測定データを指定してデータフレームに変換する

run2csv

ランを指定してデータフレームに変換する

API#

haniwers.preprocess.get_fnames(read_from: str, search_pattern: str) → list[pathlib.Path]#

測定データの一覧を取得

測定データのファイル名の一覧を取得します。 ファイル名はPathオブジェクトに変換しています。 リストはファイル名で昇順ソートします。

Args:

  • read_from (str): 測定データがあるパス

  • search_pattern (str): ファイル名の検索パターン

Returns:

  • fnames (list[Path]): 測定データの一覧

Example:

fnames = get_fnames(
    read_from="../data/raw_data/20240601_run80",
    search_pattern="osechi_data_*.csv")
haniwers.preprocess.read_data_with_pandas(fnames: list[pathlib.Path]) → pandas.DataFrame#

pd.DataFrameに変換

複数の測定ファイルを読み込んでpd.DataFrameに変換します。 測定ファイルの拡張子は.datと.csvに限定しています。

Args:

  • fnames (list[Path]): 測定データのファイル名のリスト

Exception:

  • .dat / .csv以外の拡張子の場合は中断（break）

Returns:

  • merged (pd.DataFrame): 結合したデータフレーム

haniwers.preprocess.read_data_with_polars(fnames: list[pathlib.Path]) → pandas.DataFrame#

pl.DataFrameに変換

複数のファイルを読み込んでpl.DataFrameに変換します。 polarsで読み込んだ方が、少し処理が速くなります。

ただし、そのままpl.DataFrameを返すと、あとの処理がうまくいかないので、 最後にpl.DataFrameからpd.DataFrameに変換しています。

Args:

  • fnames (list[Path]): 測定データのファイル名のリスト

Returns:

  • merged (pd.DataFrame): 結合したデータフレーム

haniwers.preprocess.read_data(fnames: list[pathlib.Path]) → pandas.DataFrame#

測定データをデータフレームに変換

read_data_with_polarsを使ってデータフレームに変換します。

Example:

fnames = get_fnames(
    read_from=...,
    search_pattern=".csv"
    )
data = read_data(fnames)
haniwers.preprocess.add_time(data: pandas.DataFrame, offset: int, timezone: str) → pandas.DataFrame#

timeカラムを追加

測定データのデータフレームにtimeカラムを追加します。 timeカラムはdatetimeカラムをタイムゾーン付き日時オブジェクトに変換したものです。 また、offset（秒）の分、測定時刻を正しい時刻に修正します。

Args:

  • data (pd.DataFrame): 測定データ

  • offset (int): 測定時刻のオフセット（秒）

Returns:

  • data (pd.DataFrame): timeカラムを追加した測定データ

Example:

data = read_data(fnames)
data = add_time(data)

注意

Raspberry Pi 4はRTCを内蔵していません。電源を切ると時計がストップします。 測定を開始する前に、ネットワークに接続してNTPから時刻を自動取得するか、 dateコマンドなどで時刻を手動設定する必要があります。 その作業を忘れてしまった場合のために、offsetオプションがあります。

haniwers.preprocess.add_hit(data: pandas.DataFrame) → pandas.DataFrame#

hitカラムを追加

各シンチのレイヤーにヒットがあったかどうかを確認し、hit_レイヤー名カラムを追加します。 ヒットがある場合は1、ヒットがない場合は0です。

Args:

  • data (pd.DataFrame): 測定データ

Returns:

  • data (pd.DataFrame): hitカラムを追加したデータフレーム

Example:

data = read_data(fnames)
data = add_time(data)
data = add_hit(data)
haniwers.preprocess.add_hit_type(data: pandas.DataFrame) → pandas.DataFrame#

hit_typeカラムを追加

レイヤーごとのヒット情報から、ヒットの種類を計算します。 ヒット情報が計算できてない場合は、警告を表示し、元のデータを返します。

Args:

  • data (pd.DataFrame): add_hitしたあとの測定データ

Returns:

  • data (pd.DataFrame): hit_typeを追加したデータフレーム

Example:

data = read_data(fnames)
data = add_time(data)
data = add_hit(data)
data = add_hit_type(data)
haniwers.preprocess.resample_data(data: pandas.DataFrame, interval: int)#

測定データをリサンプル

dataに指定した測定データをpandas.DataFrame.resampleでリサンプルします。 データは前処理済みのデータを指定してください。 再集計したデータをさらに、再集計することもできます。

Note:

  • 入力データに必要なカラム: ["time", "hit_type", "hit_top", "hit_mid", "hit_btm", "adc", "tmp", "atm", "hmd"]

  • 出力データに追加されるカラム: ["interval", "event_rate", "event_rate_top", "event_rate_mid", "event_rate_btm"]

Args:

  • data (pd.DataFrame): 前処理済みのデータフレーム

  • interval (int): リサンプル間隔（秒）

Returns:

  • merged (pd.DataFrame): 再集計後のデータフレーム

haniwers.preprocess.resample_data_with_hit_type(data: pandas.DataFrame, interval: int) → pandas.DataFrame#

測定データをリサンプル

ヒット種類（hit_type）ごとにリサンプルします。

Args:

  • data (pd.DataFrame): hit_typeを持つデータフレーム

  • interval (int): リサンプルの間隔（秒）

Returns:

  • resampled (pd.DataFrame): hit_typeごとにリサンプルしたデータフレーム

haniwers.preprocess.preprocess_data(data: pandas.DataFrame, interval: int, datetime_offset: int, timezone: str) → tuple[pandas.DataFrame, pandas.DataFrame]#

測定データを前処理する

Args:

  • data (pd.DataFrame): 測定データ

  • interval (int): リサンプル間隔（秒）

  • datetime_offset (int): 時刻のオフセット（秒）

  • timezone (str): タイムゾーン情報

Returns:

  • data (pd.DataFrame): 前処理したあとのデータ

  • resampled (pd.DataFrame): リサンプルしたデータ

haniwers.preprocess.raw2csv(fnames: list[pathlib.Path], interval: int, datetime_offset: int, timezone: str) → tuple[pandas.DataFrame, pandas.DataFrame]#

測定データを指定してデータフレームに変換する

Args:

  • fnames (list[Path]): 前処理するファイル名のリスト

  • interval (int): リサンプル間隔（秒）

  • datetime_offset (int): 時刻のオフセット（秒）

  • timezone (str): タイムゾーン情報

Returns:

  • data (pd.DataFrame): 前処理したあとのデータ

  • resampled (pd.DataFrame): リサンプルしたデータ

haniwers.preprocess.run2csv(run: haniwers.config.RunData) → tuple[pandas.DataFrame, pandas.DataFrame]#

ランを指定してデータフレームに変換する

Args:

  • run (RunData): RunDataオブジェクト

Returns:

  • data (pd.DataFrame): 前処理したあとのデータ

  • resampled (pd.DataFrame): リサンプルしたデータ

Example:

run = RunData(...)
data, resampled = run2csv(run)
print(f"gzip={len(data)}")
print(f"csv ={len(resampled)}")
目次