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

GWpy ユーザーのための GWexpy

このページは GWpy から GWexpy へ移行するための入口 です。完全な API カタログを目指すものではありません。目的は、何がそのまま使えて、価値の高い差分がどこから始まるのかを手早く把握することです。

追加 API を差分観点で引ける一覧 が欲しい場合は GWpy 差分 API 一覧 を参照してください。GWpy 互換性に関係なく全 API を見たい場合は API リファレンス を使ってください。

プロジェクト横断の GWpy 互換性ポリシーは、対応する GWpy APIについて、既定の有限数値結果、sample 選択、軸情報、正常終了の維持を要求します。意図的に異なる数値挙動が必要な場合は、GWexpy 固有 API または明示的な opt-in optionを使用してください。このpolicyで唯一の名前付き・human-approvedの安全例外 non_intersecting_window_safety は、完全非交差の HDF5 read windowだけを対象とし、すべてのpolicy gateを満たさなければなりません。より広い差異は許可しません。

ドキュメントの版とインストール済みパッケージを照合し、移行前に既知の制限を確認してください。以下の例は、既存の cache や channels などの入力を前提にしています。外部データなしで完走できる合成データの例は、Quickstartで実行できます。

まず最初に押さえること

• 単一チャンネルのワークフローは、多くの場合これまで通りです。 TimeSeries / FrequencySeries / Spectrogram では、基本的な読み込み・プロット・スペクトル解析の多くが、import を gwexpy に差し替えるだけでまず試せます。

• 最も大きく変わるのは多チャンネル処理です。 TimeSeriesDict を手動でループする代わりに、to_matrix() で変換し、チャンネル群をバッチ解析コンテナとして扱えます。

• Field API は GWexpy 独自の拡張です。 ScalarField や FieldList / FieldDict は、空間的にインデックス付けされたデータや、複数フィールドにまたがるバッチ操作を扱います。これらは GWpy が標準層として提供していないものです。

• 一部の外部ライブラリ呼び出しは、データオブジェクト自身のメソッドになります。 代表例は .find_peaks()、.fit()、.hht()、.arima() です。

• 直接 I/O と相互運用には専用ガイドがあります。 read(..., format=...) / write(..., format=...) は ファイル I/O 対応フォーマットガイド を、to_*() / from_*() 変換は Interop / 変換ガイド を、それぞれ一次情報源として参照してください。

どこから書き換えると効果が大きいか

目的	まず見る差分	深掘り先
複数チャンネルをまとめて解析したい	TimeSeriesDict.to_matrix() → TimeSeriesMatrix	行列チュートリアル
空間軸付きデータや複数のフィールドをまとめて扱いたい	ScalarField, FieldList, FieldDict	Field API 入門, GWpy 差分 API 一覧
SciPy / Statsmodels 呼び出しを整理したい	オブジェクトメソッド化された追加 API	GWpy 差分 API 一覧
既存の単一チャネルコードを早く移したい	import だけ差し替えてから必要箇所だけ差分 API を追加	クイックスタート
結果共有の互換性を知りたい	Transparent Pickle の挙動	GWpy 差分 API 一覧

差分レシピ 1: TimeSeriesDict の手ループを TimeSeriesMatrix に寄せる

GWpy 流のコードでは、ペアごとの比較やチャンネルごとのスペクトル処理が明示的なループになりがちです。GWexpy では、to_matrix() がチャンネル群全体をバッチ解析オブジェクトとして扱う主要な入口になります。

GWpy 流

from gwpy.timeseries import TimeSeriesDict

tsd = TimeSeriesDict.read(cache, channels)
reference = tsd["H1:STRAIN"]

csd = {}
for name, ts in tsd.items():
    if name == "H1:STRAIN":
        continue
    csd[name] = ts.csd(reference, fftlength=4)

GWexpy 流

from gwexpy.timeseries import TimeSeriesDict

tsd = TimeSeriesDict.read(cache, channels)
matrix = tsd.to_matrix()
reference = tsd["H1:STRAIN"]

csm = matrix.csd(reference, fftlength=4)
csm.plot().show()

この差分が効く場面:

• ループを減らして、チャンネル集合をそのまま計算対象にしたいとき

• 多チャネル解析を TimeSeriesMatrix / FrequencySeriesMatrix へ揃えたいとき

関連ページ:

• 行列チュートリアル

• GWpy 差分 API 一覧

• TimeSeriesDict リファレンス

• TimeSeriesMatrix リファレンス

差分レシピ 2: 外部関数呼び出しをオブジェクトメソッドへ寄せる

GWpy ベースのコードでは、「配列を取り出してから SciPy や Statsmodels を直接呼ぶ」という流れが自然なパターンになりがちです。GWexpy では、そのワークフローの一部がデータオブジェクト自身のメソッドとして提供されます。

GWpy 流

import numpy as np
from scipy.signal import find_peaks
from gwpy.frequencyseries import FrequencySeries

spec = FrequencySeries(...)
peaks, props = find_peaks(np.asarray(spec.value), height=0.2)

GWexpy 流

from gwexpy.frequencyseries import FrequencySeries

spec = FrequencySeries(...)
peaks, props = spec.find_peaks(threshold=0.2)

同じ方向の差分として、gwexpy では次のような API も追加されています。

• .fit() : データオブジェクトに対するフィッティング

• .hht() : Hilbert-Huang Transform

• .arima() : 時系列予測・モデル化

関連ページ:

• GWpy 差分 API 一覧

• 周波数系列チュートリアル

• フィッティング

• HHT

• ARIMA

差分レシピ 3: 単一チャネルコードは大きく変えなくてよい

GWpy の基本クラスをすでに知っているなら、最初からすべてを設計し直す必要はありません。多くの場合、現実的な移行手順は「まず import を変え、その後 GWexpy 固有の API を役立つ箇所だけ採用する」というものです。

GWpy 流

from gwpy.timeseries import TimeSeries

ts = TimeSeries.read("data.gwf", "H1:STRAIN")
asd = ts.asd(fftlength=4)
asd.plot().show()

GWexpy 流

from gwexpy.timeseries import TimeSeries

ts = TimeSeries.read("data.gwf", "H1:STRAIN")
asd = ts.asd(fftlength=4)
asd.plot().show()

実務上の見方:

• まずは既存の単一チャネル処理をそのまま持ってくる

• 多チャネル化や追加メソッドが必要になった地点で gwexpy 固有 API を使う

関連ページ:

• クイックスタート

• チュートリアル一覧

• API リファレンス

差分レシピ 4: ScalarField を FieldList / FieldDict でまとめる

GWpy の標準的な移行対象は TimeSeries 系が中心で、空間軸を持つフィールドコンテナや、そのコレクションに対応する標準クラスはありません。 GWexpy では、単一のフィールドを ScalarField で保持し、複数のフィールドを FieldList / FieldDict で一括管理できます。

GWpy 流

import numpy as np

field_a = np.random.randn(8, 3, 3, 3)
field_b = np.random.randn(8, 3, 3, 3)

fields = {"before": field_a, "after": field_b}

# axis metadata and units must be tracked separately

GWexpy 流

import numpy as np
from gwexpy.fields import ScalarField, FieldDict

fields = FieldDict(
    {
        "before": ScalarField(np.random.randn(8, 3, 3, 3)),
        "after": ScalarField(np.random.randn(8, 3, 3, 3)),
    },
    validate=True,
)

fft_fields = fields.fft_space_all()

この差分が効く場面:

• 同じ軸・単位・ドメインを共有する複数のフィールドをまとめて扱いたいとき

• 空間方向の変換や切り出しを、フィールド単位のループではなくコレクション単位で揃えたいとき

関連ページ:

• Field API 入門

• GWpy 差分 API 一覧

• ScalarField リファレンス

• FieldList リファレンス

• FieldDict リファレンス

差分レシピ 5: Pickle 共有時の互換性を見る

GWexpy は、受け取り手が GWexpy をインストールしていない場合も含め、結果の共有を念頭に設計されています。ここで重要なのは一般的な Pickle の安全性の話ではなく、GWpy ユーザーが運用上何を期待できるかという点です。

GWpy 流

import pickle
from gwpy.timeseries import TimeSeries

ts = TimeSeries(...)

with open("result.pkl", "wb") as f:
    pickle.dump(ts, f)

# sharing assumes the receiving side can read the same object type

GWexpy 流

import pickle
from gwexpy.timeseries import TimeSeries

ts = TimeSeries(...)

with open("result.pkl", "wb") as f:
    pickle.dump(ts, f)

# the receiving side can restore it as a GWpy base object even without GWexpy

重要

Pickle は信頼できるデータだけをロードしてください。

関連ページ:

• GWpy 差分 API 一覧

• インストールガイド

差分レシピ 6: python-control との橋渡し

GWpy ベースのコードでは、control.bode() などの関数を使うために、FrequencySeries の値を numpy 配列として手動で取り出し、control.frd() に渡す必要があります。GWexpy では to_control_frd() が 1 回の呼び出しで変換を処理し、その定型コードを不要にします。

GWpy 流

import control
import numpy as np
from gwpy.frequencyseries import FrequencySeries

spec = FrequencySeries.read("data.hdf5", "H1:STRAIN_ASD")

# must manually extract numpy arrays before building the FRD object
omega = 2 * np.pi * np.asarray(spec.frequencies.value)
frd_sys = control.frd(np.asarray(spec.value), omega)

# draw Bode plot
control.bode(frd_sys)

GWexpy 流

import control
from gwexpy.frequencyseries import FrequencySeries

spec = FrequencySeries.read("data.hdf5", "H1:STRAIN_ASD")

# one-line conversion and round-trip
frd_sys = spec.to_control_frd()                      # FrequencySeries → control.FrequencyResponseData
control.bode(frd_sys)                                # pass directly to Bode / Nichols / Nyquist

spec2 = FrequencySeries.from_control_frd(frd_sys)    # control.FRD → FrequencySeries

この差分が効く場面:

• ASD / PSD スペクトルをそのまま制御系の FRD モデルとして扱いたいとき

• control.bode() / control.nichols() / control.nyquist() に渡す前の numpy 配列取り出し処理を省きたいとき

• 解析結果の FRD を GWexpy の FrequencySeries に戻して既存のプロット・統計処理パイプラインに繋げたいとき

• 多チャネルのスペクトルを FrequencySeriesDict.to_control_frd() でチャネルごとに FRD 化したいとき

関連ページ:

• Interop / 変換ガイド

• python-control API リファレンス

• アクティブ制振チュートリアル

• 周波数系列チュートリアル

GWpy 周辺の他パッケージとの位置関係

GWpy を拡張するパッケージは GWexpy だけではなく、GWexpy へ移行してもエコシステムの残りを手放すことにはなりません。spicypy は信号処理と制御系の手法を追加し、GWDama は後段の解析のためにデータを HDF5 データセットへ整理し、detector characterization 系のツールは GWpy の上にオペレータ向けワークフローを構築します。GWexpy は GWpy とそれらのワークフローの間にあるコンテナ・I/O・解析プリミティブの層を担うため、どれか一つを選ぶのではなく組み合わせて使うのが通常の形です。

GWexpy がどのプロジェクトと変換連携し、どれを意図的に対象外としているかを含む完全な比較はGW Python エコシステムにおける GWexpy の位置付けを参照してください。

I/O と外部ライブラリ連携は別ページを見る

このページは、I/O フォーマット一覧や外部ライブラリ変換一覧をあえて重複して掲載しません。一次情報源としては以下の専用ガイドを使ってください：

• 直接 I/O: ファイル I/O 対応フォーマットガイド

• 外部ライブラリ変換: Interop / 変換ガイド

次のステップ

• GWpy 差分 API 一覧 - 追加 API を差分観点で引く

• Field API 入門 - ScalarField・FieldList・FieldDict の関係を理解する

• チュートリアル一覧 - 移行レシピから実例へ進む

• ファイル I/O 対応フォーマットガイド - 対応する読み書きフォーマットを確認する

• Interop / 変換ガイド - 外部ライブラリへの橋渡しを確認する

• API リファレンス - 全 API を確認する