ファイル I/O 対応フォーマットガイド#
gwexpy の利用者向け I/O ガイドです。 このページでは、ユーザーが直接使う .read() / .write() / fetch() 系 API による読み書き・取得だけを扱います。
このページは to_*() / from_*() の変換や、xarray・ROOT オブジェクト・Zarr 配列へのオブジェクトブリッジは扱いません。「このオブジェクトを別のライブラリやコンテナに変換するには？」という問いであれば、それは interop に属します。それらの話題については interop チュートリアル と interop API リファレンス を参照してください。
警告
セキュリティ警告: Pickle 形式の取り扱い
Pickle (:term:Pickle) は便利ですが、信頼できないソースから受け取った Pickle ファイルを読み込むことは危険です。悪意のあるファイルにより、実行環境で任意のコードが実行される可能性があります。
共同研究者との共有や長期保存には、HDF5、GWF、Zarr のような構造化された形式を優先してください。
まず最初に: 判断ルール#
まず保存形式を選ぶなら、GW 系データは HDF5、観測網の既存資産は MiniSEED / SAC / WIN / ATS、汎用交換は CSV / NetCDF4 / Zarr、ロガー固有データは GBD / TDMS / SDB / WAV / Audio を起点に考えると整理しやすいです。MTH5 については、現時点の public direct-I/O は
ats.mth5の単一路だけ で、汎用の standaloneformat="mth5"はまだ公開していません。自動判別でよいのは、拡張子から reader が一意に決まる場合です。
GWpy-backed の
TimeSeriesとTimeSeriesDictは、.h5/.hdf5の native HDF5 を自動判別します。構造が NDScope に一致するファイルは、汎用の native 経路より先に選択されます。その他の曖昧な HDF5 ファミリ、または GWexpy-only のクラスではformat="hdf5"を明示してください。format=を明示するのは、.xmlのように経路が複数ありうる場合、独自拡張子を使っている場合、または実験データで自動判別が不安な場合です。timezoneを必ず指定するのは、ファイル内に UTC/GPS がなくローカル時刻だけを持つ形式です。現時点でユーザーが明示必須なのは GBD です。読み込み・書き込みの対応を確認する：表の
○ / ×は「読み込み可能、書き込み不可」を意味します。Series 以外の direct I/O では、まず HDF5 の
Spectrogram/Histogram/EventTableを基準に考えてください。Field 系の direct.read()/.write()はまだ監査中で、このページでは安定契約として公開していません。
ジャンプリンク#
クイック判定表#
グループ |
まず見る場面 |
最初の形式 |
このページで扱う形式 |
|---|---|---|---|
A. GW標準 |
GW 系の標準保存、共有、取得経路を使いたい |
HDF5 |
GWF, HDF5, hdf.ndscope, xml.diaggui, NDS2, GWOSC |
B. 地震・地球物理観測 |
既存の地震・電磁気観測フォーマットを読む |
mseed |
mseed, SAC, GSE2, K-NET, WIN / WIN32, ATS, ATS.MTH5（MTH5 standalone は状況注記のみ） |
C. 汎用・解析用 |
汎用保存、外部解析、交換をしたい |
CSV / TXT または Zarr |
CSV / TXT, NetCDF4, Zarr, ROOT |
D. 計測機器・ロガー |
ロガーや機材固有の時系列を読む |
GBD または TDMS |
GBD、TDMS、SDB、WAV、MP3、FLAC、OGG、M4A |
注：
NDS2とGWOSCはファイル形式ではありません。一般的な GW データの入口であるため、A. GW Standards に含めています。以下の表ではnetwork pathとして表示されます。
.read() / .write() / fetch() の基本#
目的: 形式ごとの細かい違いを見る前に、direct I/O の基本入口を確認する
入力: ファイルパス、必要に応じた
format=、またはネットワーク取得の問い合わせ出力:
TimeSeries、TimeSeriesDictなどの direct I/O の返り値
from gwexpy.timeseries.collections import TimeSeriesDict
from gwexpy.timeseries import TimeSeries
# Auto-detect from extension
tsd = TimeSeriesDict.read("path/to/data.mseed")
# Explicit format
tsd = TimeSeriesDict.read("path/to/data.dat", format="mseed")
# Write out
tsd.write("output.h5", format="hdf5")
# Network path
ts = TimeSeries.fetch_open_data("H1", 1126259446, 1126259478)
.read()/.write()は gwpy の I/O レジストリを利用します。.xmlは用途が曖昧なので、DiagGUI XML ではformat="xml.diaggui"を明示してください。NDS2とGWOSCはファイルではないため、.read()ではなくfetch()/fetch_open_data()を使います。
対応クラスの早見表#
「単一チャネルなのか、複数チャネルなのか」で入口を迷いやすい形式を先に整理すると、次のようになります。
形式 / 系統 |
単一 |
複数 |
そのほかの対応 |
|---|---|---|---|
GWF / mseed / SAC / GSE2 / K-NET / WIN / WIN32 / ATS / SDB / WAV / Audio |
|
|
end-user 向け direct I/O の基本形 |
CSV |
|
|
|
TXT |
|
|
複数チャネルの direct I/O は collection directory を使う |
nc / Zarr / GBD / TDMS |
|
|
行列系まで含む direct I/O |
HDF5 |
|
|
|
hdf.ndscope |
- |
|
ndscope 互換スキーマ。alias: |
xml.diaggui |
- |
|
|
NDS2 / GWOSC |
|
- |
|
ATS.MTH5 |
|
- |
一部対応の単一路 |
ROOT |
|
- |
EventTable の直 I/O のみ |
まず迷ったら
TimeSeriesとTimeSeriesDictを基準に考えてください。TimeSeriesMatrixが出てくるのは主にNetCDF4,Zarr,GBD,TDMSです。Series 以外もまとめて保持したい 場合は、まず HDF5 を検討してください。
オプション依存関係の対応表#
多くの direct I/O 経路は GWexpy の基本インストールで利用できます。次の形式は optional package または optional metadata helper に依存します。
形式 / 系統 |
オプション依存関係 |
GWexpy extra |
未導入時の挙動 |
|---|---|---|---|
WAV メタデータ |
|
|
|
MP3 / FLAC / OGG / M4A |
|
|
音声の読み書きは |
TDMS |
|
|
reader は必要な |
mseed / SAC / GSE2 / K-NET |
|
|
登録済みの reader / writer は必要な |
WIN / WIN32 |
|
|
条件付き登録です。ObsPy がない環境では |
ATS.MTH5 |
|
|
reader は必要な |
nc / NetCDF4 |
|
|
reader / writer は必要な |
Zarr |
|
|
reader / writer は必要な |
A. GW標準#
GW 系の標準保存・交換・取得経路です。 迷ったらまず HDF5、外部標準との互換が必要なら GWF、診断ツール出力なら DTTXML を見てください。
形式 / 経路 |
読 / 書 |
主な入口 |
適したデータ |
注意事項 |
|---|---|---|---|---|
GWF ( |
○ / ○ |
|
LIGO/KAGRA の標準交換 |
標準形式。gwpy 経由 |
HDF5 ( |
○ / ○ |
|
長期保存、メタデータ保持 |
native time-series HDF5 は自動判別。その他のファミリは明示を推奨 |
hdf.ndscope ( |
○ / ○ |
|
ndscope 互換 |
|
xml.diaggui ( |
○ / × |
|
DiagGUI / DTT 出力 |
|
NDS2 |
○ / × |
|
検出器データサーバ取得 |
ネットワーク経由 |
GWOSC |
○ / × |
|
オープンデータ取得 |
ネットワーク経由 |
目的: GW 系で代表的な direct I/O とネットワーク取得の入口を比較する
入力: HDF5, GWF, DTTXML, または検出器 / オープンデータ取得の条件
出力:
TimeSeries,TimeSeriesDict, または取得した open data
from gwexpy.timeseries.collections import TimeSeriesDict
from gwexpy.timeseries import TimeSeries
tsd = TimeSeriesDict.read("data.h5") # native HDF5 auto-identification
frame = TimeSeriesDict.read("data.gwf", format="gwf")
merged = TimeSeriesDict.read(["part0.gwf", "part1.gwf"], "H1:STRAIN", pad=float("nan"))
dtt = TimeSeriesDict.read("diag.xml", format="xml.diaggui", products="TS")
open_data = TimeSeries.fetch_open_data("H1", 1126259446, 1126259478)
HDF5 は安全で構造化しやすく、GW 系で最も無難な保存先です。
GWF は
TimeSeriesとTimeSeriesDictで.gwfファイルの list / tuple 入力に対応します。ファイルは時刻 span 順で結合されます。連続 span はそのまま結合し、ギャップは既定で失敗します。pad=<値>またはgap="pad"で埋められ、gap="ignore"では埋めずに連結します。オーバーラップする span は既定またはgap="raise"で失敗しますが、gap="ignore"では span 順に連結し、オーバーラップの連結を許可します。start/endが実データの外側に伸びる場合も、既定のgap="raise"では失敗します。外側区間を埋めるにはpad=<値>またはgap="pad"を使ってください。gap="ignore"は内部ギャップも外側のstart/end区間も padding しません。複数ファイル読み込みで channel 名を指定しない場合、自動検出は先頭ファイルを使い、残りのファイルにも互換 channel がある前提です。DTTXML は
productsによって出力型が変わります。public direct read はTimeSeriesDict.read(..., format="xml.diaggui", products=...)に揃えます。周波数領域の DTTXML direct shim と registry adapter は implementation-only で、public direct-I/O contract には含めません。複素 transfer function を扱う高度な内部利用では
native=Trueを優先できます。NDS2 / GWOSC はファイル形式ではないため、ページ中では A に置きつつ備考で
ネットワーク経由と明示します。
B. 地震・地球物理観測#
地震観測・電磁気観測の既存フォーマットです。 既存資産をまず読めることが重要なグループで、MiniSEED を起点に考えると分かりやすいです。
形式 |
読 / 書 |
主な入口 |
適したデータ |
注意事項 |
|---|---|---|---|---|
mseed ( |
○ / ○ |
|
地震波形の標準交換 |
|
SAC ( |
○ / ○ |
|
地震波形解析 |
ObsPy 経由 |
GSE2 ( |
○ / ○ |
|
地震波形交換 |
ObsPy 経由 |
K-NET ( |
○ / × |
|
K-NET 強震記録 |
読み込み専用 |
WIN / WIN32 ( |
○ / × |
|
国内 WIN データ |
改良版 parser、読み込み専用 |
ATS ( |
○ / × |
|
Metronix 観測データ |
ネイティブ binary reader |
ATS.MTH5 ( |
○ / × |
|
MTH5 経由の単一路 |
一部対応 |
MTH5 standalone ( |
対応中 |
専用 |
今後の汎用 MTH5 direct I/O |
現時点では public direct-I/O 対応ではありません。使える direct path は |
目的: 地震・地球物理系 reader の違いを、MTH5 を過大評価せずに比較する
入力: MiniSEED, WIN/WIN32, または限定公開中の
ats.mth5経路出力: reader に応じた
TimeSeriesまたはTimeSeriesDict
from gwexpy.timeseries.collections import TimeSeriesDict
from gwexpy.timeseries import TimeSeries
tsd = TimeSeriesDict.read("data.mseed", format="mseed", gap="pad")
win = TimeSeriesDict.read("data.cnt", format="win32")
ats = TimeSeries.read("data.atss", format="ats.mth5")
MiniSEED はギャップがある場合、既定では
NaNパディングされます。gap="raise"で失敗させることもできます。K-NET, WIN / WIN32 は表のとおり読み込み専用です。
ATS.MTH5 は利用経路が限定される current direct path です。
MTH5 standalone は設計・公開整理中です。「MTH5 は対応済み」ではなく、「
ats.mth5のみ一部対応」 と読んでください。
C. 汎用・解析用#
解析ノート、外部解析、交換に向いた形式です。 このグループでは「保存形式として選ぶ話」と「他ライブラリへ変換する話」を混ぜないのが重要です。
形式 |
読 / 書 |
主な入口 |
適したデータ |
注意事項 |
|---|---|---|---|---|
CSV ( |
○ / ○ |
|
軽量な交換、目視確認 |
|
TXT ( |
○ / ○ |
|
プレーンテキスト交換 |
複数チャネルの direct I/O は collection directory を使う |
nc ( |
○ / ○ |
|
時系列系の科学データ保存 |
direct I/O は TimeSeries 系中心。旧 format alias: |
Zarr ( |
○ / ○ |
|
chunked 保存、並列処理 |
direct I/O は TimeSeries 系中心 |
ROOT ( |
○ / ○ |
|
EventTable の入出力 |
|
目的: 汎用交換向けの direct I/O を、interop 専用の橋渡しと混同せず整理する
入力: CSV, Zarr, ROOT などの汎用形式
出力:
TimeSeriesDict,TimeSeriesMatrix, またはEventTable
from gwexpy.timeseries.collections import TimeSeriesDict
from gwexpy.table import EventTable
ascii_data = TimeSeriesDict.read("data.csv")
chunked = TimeSeriesDict.read("data.zarr", format="zarr")
events = EventTable.read("events.root")
CSV は素朴ですが、共有や確認には依然として有用です。単純な CSV ファイルは metadata-light と考えてください。
name、channel、unitまで保持したい場合は HDF5、GWF、Zarr、NetCDF、または manifest 付き collection directory を使います。CSV component column は naive civil time であり、設定した
timezoneを使います。daylight-saving の曖昧な fold と存在しない gap は行番号付きのValueErrorになり、reader が暗黙に offset を選ぶことはありません。numeric timestamp は absolute、生成された sample-index route は relative であり、どちらも top-level read ごとに 1 回の warning を出してtimezoneを無視します。CSV は数値時刻と設定済み component 列の cadence を resampling 前に検証し、UTC component には連続 GPS instant を使います。不正または不規則な入力と、丸め誤差または spacing が cadence の半分未満ではない絶対 float64 軸を拒否します。
resample=は要求された channel だけに適用され、10,000,000個の上限は top-level の単一または multi-file read 全体で allocation 前に全 resampled value を数えます。不正な source row には物理行番号が含まれます。有限かつ正の
sample_rateは source cadence を宣言し、single-row input に使われます。指定がなければ従来の 1 秒 fallback が残ります。表現可能なsecond=60row なしで leap second をまたぐ component stream は、missing sample として fail closed します。CSV の数値時刻は従来どおり GPS 秒として解釈します。v0.1.14 では
time_scale=とtime_unit=を追加しないため、他の time scale は読み込み前に変換してください。TXT の direct I/O はより限定的で、単一 series は
format="txt"明示、複数チャネルは collection directory 前提です。Pickle の可搬性メモは各クラスの reference に残していますが、このページでは Pickle を public direct
.read()/.write()形式としては扱いません。NetCDF4 / Zarr はこのページでは TimeSeries 系の direct I/O としてだけ扱います。Field と xarray の橋渡しは interop 側を見てください。NetCDF の
netcdf4はncの旧 format token alias であり、.netcdf4は公開された自動判定 extension alias ではありません。Zarr の direct I/O では、配列ごとの timing metadata を明示的に要求します。
sample_rateを優先し、dtは fallback として受け付けます。どちらも無い場合はValueErrorを送出し、legacy store を意図的に救済したい場合だけsample_rate_override=...またはdt_override=...を指定してください。ROOT の object-level 変換はここでは扱いません。I/O ガイドでは
uprootを必要とする EventTable の直 I/O のみ扱います。
D. 計測機器・ロガー#
ロガーや機材固有の時系列です。 時刻の扱い、単位、音声の t0 など、フォーマットごとの注意点が比較的重要です。
形式 |
読 / 書 |
主な入口 |
適したデータ |
注意事項 |
|---|---|---|---|---|
GBD ( |
○ / × |
|
GRAPHTEC ロガー |
public read では |
TDMS ( |
○ / × |
|
National Instruments |
読み込み専用。 |
SDB ( |
○ / × |
|
WeeWX 等の蓄積データ |
読み込み専用。存在する場合、すべての |
WAV ( |
○ / ○ |
|
非圧縮音声 |
公開の書き込み API は単一時系列のみ対応。絶対時刻は保持しない |
MP3 / FLAC / OGG / M4A |
○ / ○ |
|
圧縮音声 |
|
目的: ロガー系・音声系 format で注意すべき条件をまとめる
入力: logger data、SDB archive、または audio file
出力:
TimeSeries,TimeSeriesDict, またはTimeSeriesMatrix
from gwexpy.timeseries.collections import TimeSeriesDict
logger = TimeSeriesDict.read("data.gbd", timezone="Asia/Tokyo")
weather = TimeSeriesDict.read("archive.sdb", format="sdb")
audio = TimeSeriesDict.read("sound.flac", format="flac")
GBD は
timezoneを省略できません。TDMS は optional dependency の
nptdmsが必要です。MP3 / FLAC / OGG / M4A は optional dependency の
pydubが必要で、MP3/M4A はffmpegも必要になることが多いです。SDB には canonical な
.sdbextension とformat="sdb"名を使います。WAV / 圧縮音声形式 は絶対時刻を持たないため、読み込み時は便宜上
t0=0.0として扱います。「絶対時刻がある」という意味ではありません。
開発者向け補足#
ほとんどのユーザーはこのセクションを読み飛ばして構いません。このセクションは寄稿者向けに実装状況を追跡するためのもので、動作するもののまだ公開の対応表では目立たせていないフォーマットと、将来の実装のために予約されたフォーマットトークンをまとめています。
設計上は管理するが、公開ページでは主表示しないもの#
形式 |
状態 |
注意事項 |
|---|---|---|
|
実装済み（未掲載） |
|
|
実装済み（一部対応） |
MTH5 経由の current public direct path |
|
対応中 |
専用 |
実装予定のフォーマットトークン#
以下の項目は FrequencySeries 固有の contributor tracking だけを対象にします。上に示した、別途対応する WIN、WIN32、SDB の TimeSeries と TimeSeriesDict route を説明するものではありません。
時系列 stub#
形式 |
状態 |
|---|---|
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
周波数系列 stub#
形式 |
状態 |
|---|---|
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
|
対応予定 |
次に読む#
相互運用と変換ガイド：
to_*()/from_*()による連携とオブジェクト単位の変換I/O ワークフローでタイムゾーンや GPS 時刻の扱いが必要なら GPS 時刻ユーティリティ関数
フォーマットのバックエンドを使う前にオプション依存が必要なら インストールガイド