Development documentation · 0.2.3 30c2f8ba · Intro examples tested with 0.2.3 · Version details · Known limitations

GPS Time Utility Functions (gwexpy.time)#

gwexpy extends GWpy’s time utilities to support vector operations on pandas Series, NumPy ndarrays, and Astropy Time objects, in addition to standard string/datetime scalars.

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

Quick Guide: Important Considerations (FAQ)#

It is important to understand these fundamental behaviors before performing conversions.

Handling Leap Seconds#

  • GPS Time: Continuous seconds starting from 1980-01-06 00:00:00 UTC. It does not include leap seconds.

  • Conversion: When converting to/from UTC, astropy.time’s IERS leap second tables are automatically applied.

  • Note: For future dates or very recent leap seconds, you may need to update astropy data or use the latest IERS table.

Strings Without Timezones#

  • Strings like "2015-09-14 09:50:45" without a timezone are treated as UTC by default in to_gps and tconvert.

  • For reliable local time conversion, always include the timezone name (e.g., "Asia/Tokyo") or provide a timezone-aware datetime object.

Common Failure Modes#

  • Strings that cannot be parsed as datetimes, such as to_gps("not-a-time") or tconvert("not-a-time"), fail with ValueError.

  • Inputs that cannot be converted to numeric GPS seconds, such as from_gps("abc"), fail with ValueError.

  • Unsupported keyword arguments such as to_gps(..., timezone="Asia/Tokyo") raise TypeError in the current implementation. Pass the timezone in the string itself or use a timezone-aware datetime.

  • Naive datetime inputs are treated as UTC. If you mean a local civil time, use a timezone-aware datetime.

  • For DST boundaries or other ambiguous local civil times, this page does not guarantee automatic resolution. Prefer explicit UTC offsets or timezone-aware datetime objects for boundary cases.

Function Selection Quick Reference#

Choose the most appropriate function for your goal.

Goal

Use

Input types

Output

Key args

DateTime → GPS

to_gps

str, datetime, Time, Series

LIGOTimeGPS / f8 ndarray

—

GPS → DateTime

from_gps

int, float, LIGOTimeGPS, ndarray

datetime / astropy.time.Time

—

Convenience (Auto)

tconvert

All above + "now"

Context-dependent (Scalar pref.)

—

High-Precision Object

LIGOTimeGPS

seconds, nanoseconds

LIGOTimeGPS (integer s+ns)

—

Basic Examples#

1. Simple Conversion#

  • Purpose: verify round-trip conversion between a datetime string and GPS seconds

  • Input: one UTC string and one GPS scalar

  • Output: LIGOTimeGPS, datetime, and tconvert return values

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#

Passing lists or NumPy arrays will invoke optimized batch conversions.

  • Purpose: convert multiple timestamps in one call

  • Input: a list of datetime strings or a NumPy array of GPS seconds

  • Output: numpy.ndarray or astropy.time.Time array

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#

  • Purpose: show the difference between timezone-free input and timezone-aware input

  • Input: strings or datetime objects

  • Output: GPS-second conversions with explicit interpretation

# 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#

  • Purpose: identify representative ValueError and TypeError cases before wiring this into a workflow

  • Input: unparsable strings, non-numeric GPS input, unsupported keyword arguments

  • Output: failure-mode examples

# 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 — DateTime → GPS Seconds#

Signature: to_gps(t, *args, dtype=None, **kwargs)

Converts various time representations into GPS seconds. It performs efficient vectorized operations on lists, arrays, and Series in addition to individual scalars.

Working with Strings and DateTime Objects#

  • Purpose: convert a scalar datetime-like value into GPS seconds

  • Input: a string or datetime

  • Output: LIGOTimeGPS or equivalent scalar GPS representation

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))

Choosing the Output Type#

By default, scalar calls mirror GWpy and return LIGOTimeGPS. Use dtype when you need a specific representation:

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" is useful for direct comparison or arithmetic with GWpy/GWexpy time axes:

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

Working with pandas (Vectorized)#

  • Purpose: convert multiple timestamps in one call

  • Input: a pandas Series

  • Output: a NumPy array of GPS seconds

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 Seconds → DateTime#

Signature: from_gps(t, *args, **kwargs)

Converts GPS seconds into human-readable formats. Scalar inputs return datetime objects, while array inputs return astropy.time.Time objects.

  • Scalar input such as int, float, or LIGOTimeGPS: returns datetime.datetime

  • Vector input such as a list, NumPy array, or pandas object: returns astropy.time.Time

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

tconvert — Automatic Conversion#

Signature: tconvert(t=None, *args, **kwargs)

Automatically detects the input type and dispatches to to_gps or from_gps.

  • Purpose: use one convenience function when the input type may vary

  • Input: a datetime-like value, a GPS value, or "now"

  • Output: GPS seconds or a formatted UTC-side representation depending on input type

from gwexpy.time import tconvert

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

LIGOTimeGPS — High-Precision GPS Time#

LIGOTimeGPS stores GPS time with nanosecond precision (integer seconds + integer nanoseconds).

  • Purpose: preserve integer-second and nanosecond precision explicitly

  • Input: integer seconds and optional nanoseconds

  • Output: a LIGOTimeGPS object

from gwexpy.time import LIGOTimeGPS

t = LIGOTimeGPS(1126259462, 391000000)

TimeSeries Integration#

Many methods in gwexpy accept time specifications in any format supported by to_gps().

  • Purpose: show where the time helpers surface in everyday TimeSeries workflows

  • Input: time strings, datetimes, or GPS-style values accepted by to_gps()

  • Output: fetched or cropped TimeSeries objects

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")

Next to Read#