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

数値的安定性と精度#

注釈

このページを読むべき方：次の場合に、この詳細ガイドを参照してください。

  • プロット結果に NaN や Inf による「穴」や「異常な色」が現れた場合

  • 数値パラメータや描画スケールを選びにくいダイナミックレンジのデータを扱っている。

  • 解析アルゴリズムの数値的な挙動を深く理解し、詳細パラメータ（eps, tol）を調整したい場合

gwexpy は、whitening や対数変換などの操作向けに、限定された安定化ユーティリティを提供します。動作と限界は使用する API に依存します。

まず結論だけ知りたい方へ#

  • 通常の解析では、まず gwexpy のデフォルト設定をそのまま使ってください。

  • プロット前に + 1e-20 のような手動オフセットを足す必要はありません。

  • 調整が必要なのは、NaN / Inf が見える、極端に小さい信号を扱う、アルゴリズム検証をしたい場合に限られます。

可視化における安定化の効果 (Before & After)#

標準的な手法（単純な log10 や 固定 eps）と、gwexpy の数値安定化アルゴリズムを適用した結果の比較です。

数値安定化の比較：NaN/Inf アーティファクトを含むノイズの多い可視化（左）と、クリーンな重力波信号（右）

項目

一般的な経路

GWexpy の経路

ゼロ値の扱い

log10(0) は -inf を生成するため、呼び出し側で扱う必要があります

safe_log_scale() は、dB へ変換する前にデータ依存の下限を適用します

小さい分母

固定の eps はデータスケールに適さない場合があります

ドキュメントに記載した whitening エントリポイントは eps="auto" を受け付けます

非有限の入力

数値演算が未定義になる場合があります

各 API は、文書化された契約に従って入力を検証または拒否します

主な安定化手法と API#

メソッド

対象 API

解決する問題

設定のヒント

適応ホワイトニング

TimeSeriesMatrix.whiten_channels()、whiten_matrix()、gwexpy.signal.preprocessing.whiten()

小さい分母

このパラメータをサポートする API では eps="auto" を使用します

安全な対数変換

gwexpy.numerics.safe_log_scale()

dB 変換でゼロ値から生じる -inf

目的の表示範囲に合わせて dynamic_range_db を設定します

データスケールに応じた epsilon

gwexpy.numerics.safe_epsilon()

データスケールから epsilon を選択する

既定値が操作に合わない場合は rel_tol と abs_tol を指定します

各機能の解説とコード例#

1. Adaptive Whitening#

目的: 固定 eps による信号消失を避ける。 入力: 極小信号を含む TimeSeries。 出力: 自動スケーリングされたホワイトニング結果。

標準的なホワイトニングは、ゼロ除算を防ぐために固定の正規化パラメータ（eps）を使用しますが、これが大きすぎると微小な信号が埋もれます。

❌ 悪い例: 固定 eps による信号消失#

# A fixed eps of 1e-12 rounds a 1e-21 signal to zero
whitened = data / (asd + 1e-12)

✅ 良い例: GWexpy の eps="auto"#

gwexpy は eps をデータのレンジに応じて動的にスケーリングし、特異点には SAFE_FLOOR（1e-50）を使用します。適応的な eps は、チャンネル白色化のエントリポイントである TimeSeriesMatrix.whiten_channels()、関数版の whiten_matrix()、および gwexpy.signal.preprocessing.whiten() で利用できます。

from gwexpy.timeseries import TimeSeriesMatrix
import numpy as np

tsm = TimeSeriesMatrix(np.random.randn(3, 1, 1000) * 1e-21, sample_rate=1024)
whitened, model = tsm.whiten_channels(eps="auto")  # adaptive eps (returns matrix + model)

2. Safe Logarithmic Scaling (Safe Log)#

目的: ゼロが存在する場合の -inf 値と描画破綻を防ぐ。 入力: ゼロや静穏区間を含む ASD/PSD 系データ。 出力: 動的フロア付きの安定した可視化。

スペクトログラムや、ゼロ・静穏区間を含む PSD を可視化する際の -inf の発生を防ぎます。

❌ 悪い例: 手動変換による数値エラー#

asd_db = 10 * np.log10(asd)  # Zeros become -inf, breaking the plot

✅ 良い例：明示的な安全対数変換#

safe_log_scale() は、有限なデータ最大値と指定したダイナミックレンジから下限を計算し、デシベル値を返します。

from gwexpy.numerics import safe_log_scale

asd_db = safe_log_scale(asd.value, dynamic_range_db=120.0)

ユーザーへの推奨事項#

  • dB 変換では明示的な下限を使う：ゼロ値や静かな領域を含み得るデータを変換するときは、safe_log_scale() を呼び出します。

  • whitening パラメータは API 境界で選ぶ：eps="auto" は、これを文書化した whitening エントリポイントだけで使用し、科学的用途に照らして結果を確認します。

  • API 契約を確認する：検証、有限値の扱い、許容誤差は、単一の全体方針ではなく操作ごとに実装されています。

次に読む#