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

The astropy package 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.datetime objects, namely:

tconvert([gpsordate]) Convert GPS times to ISO-format date-times and vice-versa.
to_gps(t, *args, **kwargs) Convert any input date/time into a LIGOTimeGPS.
from_gps(gps) Convert a GPS time into a datetime.datetime.

Reference

This reference contains the following class entries:

LIGOTimeGPS An object for storing times with nanosecond resolution.

and the following function entries:

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.
class gwpy.time.LIGOTimeGPS(seconds, nanoseconds=0)

Bases: object

An object for storing times with nanosecond resolution. LAL defines an equivalent object which is used through-out the search algorithms to represent times. Many LALApps routines input and output times in a manner that meshes well with this object.

Internally the time is represented as a signed integer “seconds” part and an unsigned integer “nanoseconds” part. The actual time is always constructed by adding the nanoseconds to the seconds. So -0.5 s is represented by setting seconds = -1, and nanoseconds to 500000000. That’s the way LAL does it.

Attributes Summary

gpsNanoSeconds
gpsSeconds
nanoseconds
seconds

Methods Summary

ns() Convert a LIGOTimeGPS to a count of nanoseconds as a long.

Attributes Documentation

gpsNanoSeconds
gpsSeconds
nanoseconds
seconds

Methods Documentation

ns()

Convert a LIGOTimeGPS to a count of nanoseconds as a long.

Example:

>>> LIGOTimeGPS(100.5).ns()
100500000000
time.tconvert(gpsordate='now')[source]

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

Parameters:

gpsordate : float, LIGOTimeGPS, Time, datetime.datetime, ...

input gps or date to convert

Returns:

date : datetime.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.

time.to_gps(t, *args, **kwargs)[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:

t : float, datetime.datetime, Time, str

the input time, any object that can be converted into a LIGOTimeGPS, Time, or datetime.datetime, is acceptable.

*args, **kwargs :

other arguments to pass to pass to Time if given

Returns:

gps : LIGOTimeGPS

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.

time.from_gps(gps)[source]

Convert a GPS time into a datetime.datetime.

Parameters:

gps : LIGOTimeGPS

GPS time to convert

Returns:

datetime : datetime.datetime

ISO-format datetime equivalent of input GPS time