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

GPS 時刻ユーティリティ (`gwexpy.time`)#

GWexpy は GWpy の時刻ユーティリティを拡張し、標準的な文字列・datetime のスカラーに加えて、pandas Series・NumPy ndarray・Astropy Time オブジェクトに対するベクトル演算をサポートします。

from gwexpy.time import to_gps, from_gps, tconvert, LIGOTimeGPS

クイックガイド: 重要な注意事項 (FAQ)#

変換を行う前に、以下の基本特性を理解しておくことが重要です。

閏秒 (Leap Seconds) の扱い#

GPS 時刻: 1980年1月6日 00:00:00 UTC を起点とし、閏秒を含まない連続した秒数としてカウントされます。
変換: UTC との変換時には、astropy.time が保持する IERS 閏秒テーブルが自動的に適用されます。
注意: 未来の時刻や、直近で追加された閏秒を含む変換を行う場合は、astropy のデータ更新や最新の IERS テーブルが必要になる場合があります。

タイムゾーンのない文字列の扱い#

"2015-09-14 09:50:45" のようにタイムゾーンが指定されていない文字列を to_gps や tconvert に渡すと、デフォルトで UTC として解釈されます。
ローカル時刻として確実に変換したい場合は、必ずタイムゾーン名（例: "Asia/Tokyo"）を文字列に含めるか、タイムゾーン付きの datetime オブジェクトを渡してください。

よくある失敗とエラー条件#

to_gps("not-a-time") や tconvert("not-a-time") のように日時として解釈できない文字列は、ValueError で失敗します。
from_gps("abc") のように GPS 秒として数値化できない入力は、ValueError で失敗します。
to_gps(..., timezone="Asia/Tokyo") のような未対応キーワード引数は、現在の実装では受け付けず TypeError になります。タイムゾーンは文字列本体または timezone-aware datetime で指定してください。
naive な datetime 入力は UTC として扱われます。ローカルの時刻を表したい場合は、timezone-aware datetime を使ってください。
夏時間の切替などで曖昧になるローカル時刻について、このページは自動解決を保証しません。境界となる時刻では、明示的な UTC オフセットまたは timezone-aware datetime を推奨します。

関数選択早見表#

目的に応じて最適な関数を選択してください。

目的	使う関数	主な入力型	返り値	主要引数
日時 → GPS秒	`to_gps`	`str`, `datetime`, `Time`, `Series`	`LIGOTimeGPS` / `f8 ndarray`	—
GPS秒 → 日時	`from_gps`	`int`, `float`, `LIGOTimeGPS`, `ndarray`	`datetime` / `astropy.time.Time`	—
相互変換 (自動判定)	`tconvert`	上記すべて + `"now"`	文脈に応じた型 (Scalar 優先)	—
高精度オブジェクト	`LIGOTimeGPS`	`seconds`, `nanoseconds`	`LIGOTimeGPS` (秒+ナノ秒保持)	—

基本的な使用例 (Examples)#

1. Simple Conversion#

目的: 1 つの日時文字列と GPS 秒の相互変換を確認する
入力: UTC 文字列と GPS 秒スカラー
出力: LIGOTimeGPS / datetime / tconvert の返り値

from gwexpy.time import to_gps, from_gps, tconvert

# Convert date string to GPS seconds (default UTC)
gps = to_gps("2015-09-14 09:50:45.391")
# → 1126259462.391

# Convert GPS seconds back to datetime object
dt = from_gps(1126259462.391)
# → datetime.datetime(2015, 9, 14, 9, 50, 45, ...)

# Automatic type detection via tconvert
tconvert("now")     # Current GPS time
tconvert(1126259462) # Formatted string ("September 14 2015, ...")

2. Vectorized Operations#

リストや NumPy 配列を渡すと、内部的に最適化されたベクトル変換が行われます。

目的: 複数時刻をまとめて変換する
入力: 日時文字列のリストや GPS 秒の NumPy 配列
出力: numpy.ndarray または astropy.time.Time 配列

import numpy as np

# Convert lists or arrays in bulk
gps_list = to_gps(["2015-09-14 09:50:00", "2015-09-14 09:51:00"])
# → array([1126259417., 1126259477.])

# Convert numeric arrays back to Astropy Time objects
times = from_gps(np.arange(1126259400, 1126259410))
# → <Time object: scale='utc' format='gps' value=[1.1262594e+09 ...]>

3. Timezones & Leap Seconds#

目的: タイムゾーン未指定入力と timezone-aware datetime の違いを確認する
入力: 文字列または datetime
出力: 解釈の違いが分かる GPS 秒変換

# Use explicit timezone strings (recommended)
to_gps("2024-01-01 09:00:00 JST") 

# Be careful: inputs without timezones are treated as UTC
to_gps("2024-01-01 09:00:00") # UTC 09:00:00

# Naive datetime is treated as UTC
from datetime import datetime
to_gps(datetime(2024, 1, 1, 9, 0, 0))

# For local civil time, use a timezone-aware datetime
from zoneinfo import ZoneInfo
to_gps(datetime(2024, 1, 1, 9, 0, 0, tzinfo=ZoneInfo("Asia/Tokyo")))

4. Invalid Input Examples#

目的: どの入力が ValueError / TypeError になるかを先に把握する
入力: 不正文字列、非数値 GPS、未対応キーワード引数
出力: 代表的な例外条件

# String cannot be parsed as a datetime
to_gps("not-a-time")  # -> ValueError

# GPS input is not numeric
from_gps("abc")       # -> ValueError

# Unsupported keyword argument
to_gps("2024-01-01 09:00:00", timezone="Asia/Tokyo")  # -> TypeError

`to_gps` — 日時 → GPS 秒#

シグネチャ: to_gps(t, *args, dtype=None, **kwargs)

さまざまな時刻表現を GPS 秒に変換します。単一の値（スカラー）だけでなく、リスト・配列・Series に対しても効率的なベクトル演算を行います。

文字列・datetime オブジェクトの利用#

目的：スカラーの datetime 様の値を GPS 秒に変換する
入力：文字列または datetime
出力：LIGOTimeGPS または等価なスカラー GPS 表現

from gwexpy.time import to_gps

# ISO 8601 string (assumed UTC if no timezone is specified)
to_gps("2015-09-14 09:50:45.391 UTC")
# → LIGOTimeGPS(1126259462, 391000000)

# Python datetime (timezone-aware recommended)
from datetime import datetime, timezone
to_gps(datetime(2015, 9, 14, 9, 50, 45, 391000, tzinfo=timezone.utc))

出力型の選択#

デフォルトでは GWpy に合わせ、スカラー入力は LIGOTimeGPS を返します。特定の表現が必要な場合は dtype を指定します：

from gwexpy.time import to_gps

to_gps("2015-09-14 09:50:45.391 UTC", dtype=float)
# -> 1126259462.391

gps = to_gps("2015-09-14 09:50:45.391 UTC", dtype="quantity")
# -> <Quantity 1126259462.391 s>

dtype="quantity" は、GWpy/GWexpy の時刻軸と直接比較・差分計算したい場合に使えます：

threshold = to_gps("2015-09-14 09:50:45.391 UTC", dtype="quantity")
mask = ts.times > threshold
offset = ts.times - threshold

pandas での利用（ベクトル対応）#

目的: 複数時刻をまとめて変換する
入力：pandas の Series
出力：GPS 秒の NumPy 配列

import pandas as pd
from gwexpy.time import to_gps

dates = pd.Series(pd.to_datetime(["2015-09-14", "2015-09-15", "2015-09-16"]))
gps_array = to_gps(dates)
# → numpy array([1126224017., 1126310417., 1126396817.])

`from_gps` — GPS 秒 → 日時#

シグネチャ: from_gps(t, *args, **kwargs)

GPS 秒を人間が読みやすい時刻に変換します。スカラー入力は datetime、配列入力は astropy.time.Time 配列を返します。

単一の int / float / LIGOTimeGPS を渡した場合: datetime.datetime
リスト・NumPy 配列・pandas 系のベクトル入力を渡した場合: astropy.time.Time

from_gps(1126259462)
# → datetime.datetime(2015, 9, 14, 9, 50, 45, tzinfo=...)

`tconvert` — 自動判定変換#

シグネチャ: tconvert(t=None, *args, **kwargs)

tconvert は入力の型を自動判定し、to_gps または from_gps に振り分けます。 GWpy の tconvert と同様の動作に加え、配列入力に対応しています。

目的: 入力型が混在する場面で 1 つの関数から変換する
入力: 日時表現、GPS 秒、または "now"
出力: 入力に応じた GPS 秒または UTC 側の表現

from gwexpy.time import tconvert

tconvert("2015-09-14 09:50:45 UTC") # → 1126259462
tconvert("now")                     # Current time as GPS

`LIGOTimeGPS` — 高精度 GPS 時刻#

LIGOTimeGPS は GPS 時刻をナノ秒精度（整数秒 + 整数ナノ秒）で保持します。 LIGO データアクセスライブラリで標準的に使用される表現形式です。

目的: 秒とナノ秒を分けて高精度に保持する
入力: 整数秒と、必要に応じて整数ナノ秒
出力: LIGOTimeGPS オブジェクト

from gwexpy.time import LIGOTimeGPS

t = LIGOTimeGPS(1126259462, 391000000)

TimeSeries との連携#

GWexpy の多くのメソッドは、文字列・datetime・GPS 数値などの時刻指定を直接受け付けます。内部で gwexpy.time.to_gps が自動的に呼び出されます。

目的: 日常的な TimeSeries 操作の中で時刻ユーティリティがどう使われるかを見る
入力: to_gps() が受け付ける時刻文字列、datetime、GPS 数値
出力: 取得済みまたは切り出した TimeSeries

import gwexpy

ts = gwexpy.TimeSeries.fetch("H1:GDS-CALIB_STRAIN",
                             "2015-09-14 09:50:40",
                             "2015-09-14 09:51:00")

# .crop() accepts strings, datetimes, etc.
segment = ts.crop("2015-09-14 09:50:44", "2015-09-14 09:50:50")

次に読む#

API リファレンス — gwexpy.time の完全な API リファレンス
GWpy ユーザーのための GWexpy — GWexpy の全拡張機能の概要
前提条件と規約 — GPS 時刻・タイムゾーン・FFT の共通前提

GPS 時刻ユーティリティ (gwexpy.time)#