Times and timestamps¶

GPS time¶

All gravitational-wave data are recorded with timestamps in the GPS time system (recording the absolute number of seconds since the start of the GPS epoch at midnight on January 6th 1980).

The LIGO Scientific Collaboration stores such GPS times with nanosecond precision using the ligotimegps object.

Time conversions¶

Astropy provides the excellent Time object to allow easy conversion between this format and a number of other formats. For convenience, this object is available in GWpy as gwpy.time.Time.

On top of that, GWpy provides three simple methods to simplify converting between GPS times and Python-standard datetime objects, namely:

`tconvert`	Convert GPS times to ISO-format date-times and vice-versa.
`to_gps`	Convert any input date/time into a `LIGOTimeGPS`.
`from_gps`	Convert a GPS time into a `datetime.datetime`.

Reference¶

gwpy.time.tconvert(gpsordate: SupportsFloat | date | str = 'now') → date | LIGOTimeGPS[source]¶

Convert GPS times to ISO-format date-times and vice-versa.

Parameters:

gpsordatefloat, astropy.time.Time, datetime.datetime, …: Input gps or date to convert, many input types are supported.

Returns:

datedatetime.datetime or LIGOTimeGPS: Converted gps or date.

Notes

If the input object is a float or LIGOTimeGPS, it will get converted from GPS format into a datetime.datetime, otherwise the input will be converted into LIGOTimeGPS.

Warning

This method cannot convert exact leap seconds to datetime.datetime, that object doesn’t support it, so you should consider using astropy.time.Time directly.

Examples

Integers and floats are automatically converted from GPS to datetime.datetime:

>>> from gwpy.time import tconvert
>>> tconvert(0)
datetime.datetime(1980, 1, 6, 0, 0)
>>> tconvert(1126259462.3910)
datetime.datetime(2015, 9, 14, 9, 50, 45, 391000)

while strings are automatically converted to LIGOTimeGPS:

>>> to_gps("Sep 14 2015 09:50:45.391")
LIGOTimeGPS(1126259462, 391000000)

Additionally, a few special-case words as supported, which all return LIGOTimeGPS:

>>> tconvert("now")
>>> tconvert("today")
>>> tconvert("tomorrow")
>>> tconvert("yesterday")

gwpy.time.to_gps(t: SupportsFloat | date | str, *args, **kwargs) → LIGOTimeGPS[source]¶

Convert any input date/time into a LIGOTimeGPS.

Any input object that can be cast as a Time (with str going through the datetime.datetime) are acceptable.

Parameters:

tfloat, datetime, Time, str: The input time, any object that can be converted into a LIGOTimeGPS, Time, or datetime, is acceptable.
args, kwargs: Other arguments to pass to pass to Time if given.

Returns:

gpsLIGOTimeGPS: The number of GPS seconds (non-integer) since the start of the epoch (January 6 1980).

Raises:

TypeError: If a str input cannot be parsed as a datetime.datetime.
ValueError: If the input cannot be cast as a Time or LIGOTimeGPS.

Examples

>>> to_gps("Jan 1 2017")
LIGOTimeGPS(1167264018, 0)
>>> to_gps("Sep 14 2015 09:50:45.391")
LIGOTimeGPS(1126259462, 391000000)

>>> import datetime
>>> to_gps(datetime.datetime(2017, 1, 1))
LIGOTimeGPS(1167264018, 0)

>>> from astropy.time import Time
>>> to_gps(Time(57754, format="mjd"))
LIGOTimeGPS(1167264018, 0)

gwpy.time.from_gps(gps: LIGOTimeGPS | float) → datetime[source]¶

Convert a GPS time into a datetime.datetime.

Parameters:

gpsLIGOTimeGPS, int, float: GPS time to convert

Returns:

datetimedatetime.datetime: ISO-format datetime equivalent of input GPS time

Notes

Warning

This method cannot convert exact leap seconds to datetime.datetime, that object doesn’t support it, so you should consider using astropy.time.Time directly.

Examples

>>> from_gps(1167264018)
datetime.datetime(2017, 1, 1, 0, 0)
>>> from_gps(1126259462.3910)
datetime.datetime(2015, 9, 14, 9, 50, 45, 391000)