開発版ドキュメント · 0.2.3 30c2f8ba · 入門例の検証対象 0.2.3 · 版情報 · 既知の制限

Interop / 変換ガイド#

このページは gwexpy の専用 interop ガイドです。 ここでの interop とは、to_*() / from_*() API を中心とした変換とブリッジを意味します。

このページで扱うもの:

  • to_*() / from_*() によるオブジェクト変換

  • 外部ライブラリや外部データモデルへの橋渡し

  • object 単位の file-bridge helper

  • 対称でない変換 API

  • 一部クラスにしか適用されない変換

このページで扱わないもの:

  • Class.read(..., format=...)

  • obj.write(..., format=...)

  • ローカルファイル形式の採用判断そのもの

ローカルファイルの .read() / .write() / fetch() 系の入口は ファイル I/O 対応フォーマットガイド を参照してください。

直接 I/O 名#

以下は gwexpy で使う direct I/O の正規名です。 移行期間中は旧 alias も使えますが、新しい例では下の正規名を優先してください。

正規名

旧 alias

代表的な direct I/O 入口

外部パッケージ / スキーマ

mseed

miniseed

TimeSeriesDict.read(..., format="mseed"), .write(..., format="mseed")

ObsPy

nc

netcdf4

TimeSeries.read(..., format="nc"), TimeSeriesDict.read(..., format="nc"), TimeSeriesMatrix.read(..., format="nc")

netCDF4, xarray

hdf.ndscope

ndscope-hdf5, ndscope_hdf5, ndscopehdf5

TimeSeriesDict.read(..., format="hdf.ndscope"), .write(..., format="hdf.ndscope")

ndscope HDF5 スキーマ

xml.diaggui

dttxml

TimeSeriesDict.read(..., format="xml.diaggui", products="...")

DiagGUI / DTT XML

このページの読み方#

  • 手元のオブジェクトを保存形式やコンテナに写したいなら A を見てください。

  • pandas / xarray / astropy / dask のような解析オブジェクトに写したいなら B を見てください。

  • PyTorch / TensorFlow / JAX / CuPy に渡したいなら C を見てください。

  • ROOT / ObsPy / LAL / PyCBC などの分野別ライブラリに接続したいなら D を見てください。

  • Field を xarray / NetCDF4 / Zarr に to_*() / from_*() で渡したい場合は、I/O ではなく interop として扱います。

S. 基盤レイヤー#

このレイヤーは、このページの他の項目へ数値計算と重力波解析の文脈を与えるライブラリを示します。利用統計による順位ではありません。

ライブラリ

GWexpy エコシステムでの役割

Interop に関する注記

GWpy

時系列と周波数系列の基盤エコシステム

GWexpy は、これを任意の変換先として扱うのではなく、そのオブジェクトモデルを拡張します。

NumPy / SciPy

配列表現と数値計算ルーチン

多くの公開 API の基盤です。専用の往復変換 API があることを意味しません。

Astropy

単位、時刻、天文学向けオブジェクトの規約

明示的な to_astropy_timeseries() と from_astropy_timeseries() の変換は B に示します。

LALSuite

重力波の時系列と周波数系列の規約

明示的な LAL 変換 API は D に示します。

状態ラベル#

  • 公開済み: 実装があり、reference/api/interop から到達できる

  • 実装済み: 実装はあるが、このページ上の導線や参照整理がまだ残っている

  • 実装済み（一部経路は対応中）: 主経路は使えるが、一部変換経路の完成度が不足している

  • 対応中: 専用の実装面または公開面の整理が未完

  • 対応予定: 設計対象として明示するが、まだ実装がない

オプション依存関係の方針#

Interop bridge は runtime optional backend を遅延 import します。runtime backend が未導入の場合、import gwexpy の時点ではなく、該当 bridge を呼び出した時点でインストール案内付きの ImportError を送出します。

import 中心の adapter の一部は、外部 package が生成した object や dict を受け取りますが、その producer package 自体は import しません。たとえば from_pyoma_results(), from_mtspec(), from_mtspec_array(), from_uff_dataset55(), from_uff_dataset58(), from_sdynpy_*(), from_metpy_dataarray(), from_wrf_variable(), from_harmonica_grid() は、呼び出し側が渡す pyOMA, multitaper, mtspec, pyuff, SDynPy, MetPy, wrf-python, Harmonica 形式の object を消費します。これらの package は source object を作る必要がある場合に導入してください。adapter が直接 import するためではありません。

方針

依存関係

インストール案内

GWexpy extras で宣言済み

zarr, netCDF4, xarray, obspy, mth5, lalsuite, gwinc, control, pydub

インストールガイド の説明に従い、対応する extra を PyPI からインストールしてください（例：pip install "gwexpy[control]"）。

個別 package install

ROOT, polars, dask, torch, tensorflow, jax, cupy, pycbc, finesse, simpeg, mne, neo, quantities, pyroomacoustics, specutils, pyspeckit, PySpice, skrf, pyOMA, multitaper, mtspec, pyuff, sdynpy, metpy, wrf-python, harmonica, emg3d, meshio

bridge が直接 import する場合、または受け渡す source object を作る必要がある場合に、該当 backend を個別に導入してください。

gwexpy[all] は GWexpy が宣言している extra をまとめて導入するための convenience bundle です。すべての public interop backend を導入するもの ではありません。個別 package install の行にある backend は、bridge が直接 import する場合や受け渡す source object を作る場合に、個別に導入してください。

xarray 系の interop bridge は、GWexpy が独立した xarray extra を公開していないため netcdf4 extra を案内します。メモリ上の xarray 変換だけが必要で netCDF4 を入れたくない場合は、xarray を個別に導入してください。

A. 保存形式・コンテナ変換#

このセクションは、変換先がファイル形式・コンテナ・ストレージ表現である変換を扱います。 「どのストレージ表現にブリッジするか？」という問いのときに使います。

  • 目的: 保存表現を相手にする object-level bridge の入口を見分ける

  • 入力: gwexpy オブジェクトと、保存先のコンテナやストレージ表現

  • 出力: to_*() / from_*() による変換結果や保存向けオブジェクト

連携先

API / 入口

状態

注意事項

詳細

HDF5

to_hdf5(), from_hdf5()

公開済み

object-level 変換

Interop API リファレンス

HDF5 FrequencySeries

to_hdf5_frequencyseries(), from_hdf5_frequencyseries()

公開済み

FrequencySeries HDF5 ヘルパー

Interop API リファレンス

JSON

to_json(), from_json()

公開済み

JSON 文字列との相互変換

Interop API リファレンス

Python dict

to_dict(), from_dict()

公開済み

dict との相互変換

—

SQLite

to_sqlite(), from_sqlite()

公開済み

オブジェクト単位のブリッジ

Interop API リファレンス

Zarr

to_zarr(), from_zarr()

公開済み

配列／ストアのブリッジ

Interop API リファレンス

NetCDF4

to_netcdf4(), from_netcdf4()

公開済み

オブジェクト単位のブリッジ

Interop API リファレンス

B. 解析ライブラリ・オブジェクト変換#

このセクションは、変換先がストレージ形式ではなく Python オブジェクトモデルである変換を扱います。 「どの解析ライブラリのオブジェクトにブリッジするか？」という問いのときに使います。

  • 目的: 解析ライブラリ向けの橋渡し先を選ぶ

  • 入力: gwexpy オブジェクト、または pandas / xarray / astropy などの外部オブジェクト

  • 出力: 解析ライブラリのオブジェクト、または gwexpy に戻したオブジェクト

連携先

API / 入口

状態

注意事項

詳細

NumPy

専用 to_*() / from_*() API なし

実装済み（基盤対応）

内部配列表現として広く利用

—

pandas

to_pandas_series(), from_pandas_series(), to_pandas_dataframe(), from_pandas_dataframe()

公開済み

Series / DataFrame

Interop API リファレンス

pandas FrequencySeries

to_pandas_frequencyseries(), from_pandas_frequencyseries()

公開済み

FrequencySeries ⇔ pandas.Series

Interop API リファレンス

polars

to_polars_series(), from_polars_series(), to_polars_dataframe(), from_polars_dataframe(), to_polars_frequencyseries(), to_polars_dict(), from_polars_dict()

公開済み

Series / DataFrame / dict / FrequencySeries

Interop API リファレンス

xarray

to_xarray(), from_xarray()

公開済み

DataArray / Dataset

Interop API リファレンス

xarray Field

to_xarray_field(), from_xarray_field()

公開済み

ScalarField / VectorField

Interop API リファレンス

xarray FrequencySeries

to_xarray_frequencyseries(), from_xarray_frequencyseries()

公開済み

FrequencySeries ⇔ xarray.DataArray

Interop API リファレンス

astropy

to_astropy_timeseries(), from_astropy_timeseries()

公開済み

astropy.timeseries.TimeSeries

Interop API リファレンス

dask

to_dask(), from_dask()

公開済み

dask 配列のブリッジ

Interop API リファレンス

C. 科学計算、信号処理、機械学習、配列バックエンド#

このセクションは、高速計算および ML 指向のブリッジを扱います。 配列のペイロードのみが移動するのか、メタデータも再構築できるのかを確認してください。

  • 目的: ML や GPU 配列への橋渡しで、何が保持されるかを見極める

  • 入力: gwexpy オブジェクトと、PyTorch / TensorFlow / JAX / CuPy などの連携先

  • 出力: Tensor や高速化配列、場合によっては gwexpy へ戻すための経路

連携先

API / 入口

状態

注意事項

詳細

PyTorch

to_torch(), from_torch()

公開済み

Tensor 変換

Interop API リファレンス

PyTorch Dataset

TimeSeriesWindowDataset, to_torch_dataset(), to_torch_dataloader()

公開済み

トレーニングループ用ウィンドウデータセット

Interop API リファレンス

TensorFlow

to_tf(), from_tf()

公開済み

Tensor 変換

Interop API リファレンス

JAX

to_jax(), from_jax()

公開済み

JAX array 変換

Interop API リファレンス

CuPy

to_cupy(), from_cupy(), is_cupy_available()

公開済み

GPU array 変換

Interop API リファレンス

librosa

to_librosa()

公開済み

音響特徴量のエクスポート。解析オブジェクトと機械学習ワークフローの中間に位置しますが、主に後者のためにここへ分類します。

Interop API リファレンス

pyroomacoustics

to_pyroomacoustics_source(), to_pyroomacoustics_stft(), from_pyroomacoustics_rir(), from_pyroomacoustics_mic_signals(), from_pyroomacoustics_source(), from_pyroomacoustics_stft(), from_pyroomacoustics_field()

公開済み

室内音響シミュレーションとアレイ処理のワークフロー

API

D. 物理・ドメイン特化ライブラリ#

この節では、分野特化ライブラリと特殊なオブジェクトを扱います。ステータスを確認してください。完全な往復変換の対象、主にインポート経路の対象、公開整理中の対象があります。材料科学と生命科学の項目は価値の低い分野ではありません。将来の手法移植や、材料熱雑音の研究などへの経路を提供します。

  • 目的: 分野別ライブラリとの橋渡しを、直 I/O と混同せずに整理する

  • 入力: gwexpy オブジェクト、または ObsPy / ROOT / LAL / PyCBC などの外部オブジェクト

  • 出力: 連携先ライブラリのオブジェクト、import 結果、または限定的な往復変換

連携先

API / 入口

状態

注意事項

詳細

ROOT

to_tgraph(), to_th1d(), to_th2d(), to_tmultigraph(), from_root(), write_root_file()

実装済み（一部経路は対応中）

TH1 -> non-Histogram は未完

Interop API リファレンス

ObsPy

to_obspy(), from_obspy(), to_obspy_trace(), from_obspy_trace()

公開済み

地震データのブリッジ

Interop API リファレンス

LALSuite

to_lal_timeseries(), from_lal_timeseries(), to_lal_frequencyseries(), from_lal_frequencyseries()

公開済み

GW 時系列 / 周波数系列

Interop API リファレンス

PyCBC

to_pycbc_timeseries(), from_pycbc_timeseries(), to_pycbc_frequencyseries(), from_pycbc_frequencyseries()

公開済み

GW 時系列 / 周波数系列

Interop API リファレンス

GWINC

from_gwinc_budget()

公開済み

バジェットのインポート

Interop API リファレンス

Finesse

from_finesse_frequency_response(), from_finesse_noise()

公開済み

光学／応答

Interop API リファレンス

python-control

to_control_frd(), from_control_frd(), from_control_response()

公開済み

FRD / response。control extra が必要です（例：pip install "gwexpy[control]"）。FRD 変換は FrequencySeries / FrequencySeriesDict から利用でき、時間応答の取り込みは TimeSeries.from_control() / TimeSeriesDict.from_control() で行えます。

Interop API リファレンス

SimPEG

to_simpeg(), from_simpeg()

公開済み

地球物理

Interop API リファレンス

MTH5

to_mth5(), from_mth5()

公開済み

地磁気地電流（MT）

Interop API リファレンス

MTpy

専用 to_*() / from_*() API は対応中

対応中

MTH5 周辺との整理が未完

—

MNE-Python

to_mne(), from_mne(), to_mne_rawarray(), from_mne_raw()

公開済み

EEG／生体信号

Interop API リファレンス

Neo

to_neo(), from_neo()

公開済み

電気生理

Interop API リファレンス

Elephant

専用 to_*() / from_*() API は対応中

対応中

Neo / quantities 周辺との整理が未完

—

quantities

to_quantity(), from_quantity()

公開済み

物理量のブリッジ

Interop API リファレンス

pydub

to_pydub(), from_pydub()

公開済み

音声オブジェクトのブリッジ

Interop API リファレンス

specutils

to_specutils(), from_specutils()

公開済み

天文スペクトル

Interop API リファレンス

pyspeckit

to_pyspeckit(), from_pyspeckit()

公開済み

スペクトル解析

Interop API リファレンス

PySpice

from_pyspice_transient(), from_pyspice_ac(), from_pyspice_noise(), from_pyspice_distortion()

公開済み

import 中心

Interop API リファレンス

scikit-rf

to_skrf_network(), from_skrf_network(), from_skrf_impulse_response(), from_skrf_step_response()

公開済み

RF ネットワーク解析

Interop API リファレンス

pyOMA

from_pyoma_results()

公開済み

import 中心

Interop API リファレンス

multitaper

from_mtspec()

公開済み

import 中心

Interop API リファレンス

mtspec

from_mtspec_array()

公開済み

import 中心

Interop API リファレンス

pySDy

from_uff_dataset55(), from_uff_dataset58()

公開済み

import 中心

Interop API リファレンス

SDynPy

from_sdynpy_frf(), from_sdynpy_shape(), from_sdynpy_timehistory()

公開済み

import 中心

Interop API リファレンス

Meep

from_meep_hdf5()

公開済み

import 中心

Interop API リファレンス

openEMS

from_openems_hdf5(), DUMP_TYPE_MAP

公開済み

import 中心

Interop API リファレンス

emg3d

to_emg3d_field(), from_emg3d_field(), from_emg3d_h5()

公開済み

EM 場の入出力

Interop API リファレンス

meshio

from_meshio(), from_fenics_xdmf(), from_fenics_vtk()

公開済み

import 中心

Interop API リファレンス

MetPy

from_metpy_dataarray()

公開済み

import 中心

Interop API リファレンス

WRF

from_wrf_variable()

公開済み

import 中心

Interop API リファレンス

Harmonica

from_harmonica_grid()

公開済み

import 中心

Interop API リファレンス

Exudyn

from_exudyn_sensor()

公開済み

import 中心

Interop API リファレンス

OpenSees

from_opensees_recorder()

公開済み

import 中心

Interop API リファレンス

次に読む#