gwexpy.time.Time

class gwexpy.time.Time(val, val2=None, format=None, scale=None, precision=None, in_subfmt=None, out_subfmt=None, location=None, copy=False)[source]

Bases: TimeBase

Represent and manipulate times and dates for astronomy.

A Time object is initialized with one or more times in the val argument. The input times in val must conform to the specified format and must correspond to the specified time scale. The optional val2 time input should be supplied only for numeric input formats (e.g. JD) where very high precision (better than 64-bit precision) is required.

The allowed values for format can be listed with:

>>> list(Time.FORMATS)
['jd', 'mjd', 'decimalyear', 'unix', 'unix_tai', 'cxcsec', 'galexsec', 'gps',
 'plot_date', 'stardate', 'datetime', 'ymdhms', 'iso', 'isot', 'yday', 'datetime64',
 'fits', 'byear', 'jyear', 'byear_str', 'jyear_str']

See also: http://docs.astropy.org/en/stable/time/

Parameters:

  • val (sequence, ndarray, number, str, bytes, or ~astropy.time.Time object) – Value(s) to initialize the time or times. Bytes are decoded as ascii.

  • val2 (sequence, ndarray, or number; optional) – Value(s) to initialize the time or times. Only used for numerical input, to help preserve precision.

  • format (str, optional) – Format of input value(s), specifying how to interpret them (e.g., ISO, JD, or Unix time). By default, the same format will be used for output representation.

  • scale (str, optional) – Time scale of input value(s), must be one of the following: (‘tai’, ‘tcb’, ‘tcg’, ‘tdb’, ‘tt’, ‘ut1’, ‘utc’)

  • precision (int, optional) – Digits of precision in string representation of time

  • in_subfmt (str, optional) – Unix glob to select subformats for parsing input times

  • out_subfmt (str, optional) – Unix glob to select subformat for outputting times

  • location (~astropy.coordinates.EarthLocation or tuple, optional) – If given as an tuple, it should be able to initialize an an EarthLocation instance, i.e., either contain 3 items with units of length for geocentric coordinates, or contain a longitude, latitude, and an optional height for geodetic coordinates. Can be a single location, or one for each input time. If not given, assumed to be the center of the Earth for time scale transformations to and from the solar-system barycenter.

  • copy (bool, optional) – Make a copy of the input values

__init__(val, val2=None, format=None, scale=None, precision=None, in_subfmt=None, out_subfmt=None, location=None, copy=False)[source]

Methods

__init__(val[, val2, format, scale, ...])

argmax([axis, out])

Return indices of the maximum values along the given axis.

argmin([axis, out])

Return indices of the minimum values along the given axis.

argsort([axis, kind])

Returns the indices that would sort the time array.

copy([format])

Return a fully independent copy the Time object, optionally changing the format.

diagonal(*args, **kwargs)

Return an instance with the specified diagonals.

earth_rotation_angle([longitude])

Calculate local Earth rotation angle.

filled(fill_value)

Get a copy of the underlying data, with masked values filled in.

flatten(*args, **kwargs)

Return a copy with the array collapsed into one dimension.

get_delta_ut1_utc([iers_table, return_status])

Find UT1 - UTC differences by interpolating in IERS Table.

insert(obj, values[, axis])

Insert values before the given indices in the column and return a new ~astropy.time.Time or ~astropy.time.TimeDelta object.

isclose(other[, atol])

Returns a boolean or boolean array where two Time objects are element-wise equal within a time tolerance.

light_travel_time(skycoord[, kind, ...])

Light travel time correction to the barycentre or heliocentre.

max([axis, out, keepdims])

Maximum along a given axis.

mean([axis, dtype, out, keepdims, where])

min([axis, out, keepdims])

Minimum along a given axis.

now()

Creates a new object corresponding to the instant in time this method is called.

ptp([axis, out, keepdims])

ravel(*args, **kwargs)

Return an instance with the array collapsed into one dimension.

replicate([format, copy, cls])

Return a replica of the Time object, optionally changing the format.

reshape(*args, **kwargs)

Returns an instance containing the same data with a new shape.

sidereal_time(kind[, longitude, model])

Calculate sidereal time.

sort([axis])

Return a copy sorted along the specified axis.

squeeze(*args, **kwargs)

Return an instance with single-dimensional shape entries removed.

strftime(format_spec)

Convert Time to a string or a numpy.array of strings according to a format specification.

strptime(time_string, format_string, **kwargs)

Parse a string to a Time according to a format specification.

swapaxes(*args, **kwargs)

Return an instance with the given axes interchanged.

take(indices[, axis, out, mode])

Return a new instance formed from the elements at the given indices.

to_datetime([timezone, leap_second_strict])

Convert to (potentially timezone-aware) ~datetime.datetime object.

to_string()

Output a string representation of the Time or TimeDelta object.

to_value(format[, subfmt])

Get time values expressed in specified output format.

transpose(*args, **kwargs)

Return an instance with the data transposed.

Attributes

FORMATS

Dict of time formats

SCALES

List of time scales

T

Return an instance with the data transposed.

cache

Return the cache associated with this instance.

delta_tdb_tt

TDB - TT time scale offset

delta_ut1_utc

UT1 - UTC time scale offset

format

Get or set time format.

in_subfmt

Unix wildcard pattern to select subformats for parsing string input times.

info

Container for meta information like name, description, format.

isscalar

jd1

First of the two doubles that internally store time value(s) in JD.

jd2

Second of the two doubles that internally store time value(s) in JD.

location

mask

masked

ndim

The number of dimensions of the instance and underlying arrays.

out_subfmt

Unix wildcard pattern to select subformats for outputting times.

precision

Decimal precision when outputting seconds as floating point (int value between 0 and 9 inclusive).

scale

Time scale.

shape

The shape of the time instances.

size

The size of the object, as calculated from its shape.

unmasked

Get an instance without the mask.

value

Time value(s) in current format.

writeable

FORMATS = {'byear': <class 'astropy.time.formats.TimeBesselianEpoch'>, 'byear_str': <class 'astropy.time.formats.TimeBesselianEpochString'>, 'cxcsec': <class 'astropy.time.formats.TimeCxcSec'>, 'datetime': <class 'astropy.time.formats.TimeDatetime'>, 'datetime64': <class 'astropy.time.formats.TimeDatetime64'>, 'decimalyear': <class 'astropy.time.formats.TimeDecimalYear'>, 'fits': <class 'astropy.time.formats.TimeFITS'>, 'galexsec': <class 'astropy.time.formats.TimeGalexSec'>, 'gps': <class 'astropy.time.formats.TimeGPS'>, 'iso': <class 'astropy.time.formats.TimeISO'>, 'isot': <class 'astropy.time.formats.TimeISOT'>, 'jd': <class 'astropy.time.formats.TimeJD'>, 'jyear': <class 'astropy.time.formats.TimeJulianEpoch'>, 'jyear_str': <class 'astropy.time.formats.TimeJulianEpochString'>, 'mjd': <class 'astropy.time.formats.TimeMJD'>, 'plot_date': <class 'astropy.time.formats.TimePlotDate'>, 'stardate': <class 'astropy.time.formats.TimeStardate'>, 'unix': <class 'astropy.time.formats.TimeUnix'>, 'unix_tai': <class 'astropy.time.formats.TimeUnixTai'>, 'yday': <class 'astropy.time.formats.TimeYearDayTime'>, 'ymdhms': <class 'astropy.time.formats.TimeYMDHMS'>}

Dict of time formats

SCALES = ('tai', 'tcb', 'tcg', 'tdb', 'tt', 'ut1', 'utc', 'local')

List of time scales

classmethod now()[source]

Creates a new object corresponding to the instant in time this method is called.

Note

“Now” is determined using the ~datetime.datetime.now function, so its accuracy and precision is determined by that function. Generally that means it is set by the accuracy of your system clock. The timezone is set to UTC.

Returns:

nowtime – A new Time object (or a subclass of Time if this is called from such a subclass) at the current time.

Return type:

Time

info

Container for meta information like name, description, format. This is required when the object is used as a mixin column within a table, but can be used as a general way to store meta information.

classmethod strptime(time_string, format_string, **kwargs)[source]

Parse a string to a Time according to a format specification. See time.strptime documentation for format specification.

>>> Time.strptime('2012-Jun-30 23:59:60', '%Y-%b-%d %H:%M:%S')
<Time object: scale='utc' format='isot' value=2012-06-30T23:59:60.000>
Parameters:

  • time_string (str, sequence, or ndarray) – Objects containing time data of type string

  • format_string (str) – String specifying format of time_string.

  • kwargs (dict) – Any keyword arguments for Time. If the format keyword argument is present, this will be used as the Time format.

Returns:

time_obj – A new ~astropy.time.Time object corresponding to the input time_string.

Return type:

~astropy.time.Time

strftime(format_spec)[source]

Convert Time to a string or a numpy.array of strings according to a format specification. See time.strftime documentation for format specification.

Parameters:

format_spec (str) – Format definition of return string.

Returns:

formatted – String or numpy.array of strings formatted according to the given format string.

Return type:

str or numpy.array

light_travel_time(skycoord, kind='barycentric', location=None, ephemeris=None)[source]

Light travel time correction to the barycentre or heliocentre.

The frame transformations used to calculate the location of the solar system barycentre and the heliocentre rely on the erfa routine epv00, which is consistent with the JPL DE405 ephemeris to an accuracy of 11.2 km, corresponding to a light travel time of 4 microseconds.

The routine assumes the source(s) are at large distance, i.e., neglects finite-distance effects.

Parameters:

  • skycoord (~astropy.coordinates.SkyCoord) – The sky location to calculate the correction for.

  • kind (str, optional) – 'barycentric' (default) or 'heliocentric'

  • location (~astropy.coordinates.EarthLocation, optional) – The location of the observatory to calculate the correction for. If no location is given, the location attribute of the Time object is used

  • ephemeris (str, optional) – Solar system ephemeris to use (e.g., ‘builtin’, ‘jpl’). By default, use the one set with astropy.coordinates.solar_system_ephemeris.set. For more information, see ~astropy.coordinates.solar_system_ephemeris.

Returns:

time_offset – The time offset between the barycentre or Heliocentre and Earth, in TDB seconds. Should be added to the original time to get the time in the Solar system barycentre or the Heliocentre. Also, the time conversion to BJD will then include the relativistic correction as well.

Return type:

~astropy.time.TimeDelta

earth_rotation_angle(longitude=None)[source]

Calculate local Earth rotation angle.

Parameters:

longitude (~astropy.units.Quantity, ~astropy.coordinates.EarthLocation, str, or None; optional) – The longitude on the Earth at which to compute the Earth rotation angle (taken from a location as needed). If None (default), taken from the location attribute of the Time instance. If the special string ‘tio’, the result will be relative to the Terrestrial Intermediate Origin (TIO) (i.e., the output of ~erfa.era00).

Returns:

Local Earth rotation angle with units of hourangle.

Return type:

~astropy.coordinates.Longitude

See also

astropy.time.Time.sidereal_time

References

IAU 2006 NFA Glossary (currently located at: https://syrte.obspm.fr/iauWGnfa/NFA_Glossary.html)

Notes

The difference between apparent sidereal time and Earth rotation angle is the equation of the origins, which is the angle between the Celestial Intermediate Origin (CIO) and the equinox. Applying apparent sidereal time to the hour angle yields the true apparent Right Ascension with respect to the equinox, while applying the Earth rotation angle yields the intermediate (CIRS) Right Ascension with respect to the CIO.

The result includes the TIO locator (s’), which positions the Terrestrial Intermediate Origin on the equator of the Celestial Intermediate Pole (CIP) and is rigorously corrected for polar motion. (except when longitude='tio').

sidereal_time(kind, longitude=None, model=None)[source]

Calculate sidereal time.

Parameters:

  • kind (str) – 'mean' or 'apparent', i.e., accounting for precession only, or also for nutation.

  • longitude (~astropy.units.Quantity, ~astropy.coordinates.EarthLocation, str, or None; optional) – The longitude on the Earth at which to compute the Earth rotation angle (taken from a location as needed). If None (default), taken from the location attribute of the Time instance. If the special string ‘greenwich’ or ‘tio’, the result will be relative to longitude 0 for models before 2000, and relative to the Terrestrial Intermediate Origin (TIO) for later ones (i.e., the output of the relevant ERFA function that calculates greenwich sidereal time).

  • model (str or None; optional) – Precession (and nutation) model to use. The available ones are: - apparent: [‘IAU1994’, ‘IAU2000A’, ‘IAU2000B’, ‘IAU2006A’] - mean: [‘IAU1982’, ‘IAU2000’, ‘IAU2006’] If None (default), the last (most recent) one from the appropriate list above is used.

Returns:

Local sidereal time, with units of hourangle.

Return type:

~astropy.coordinates.Longitude

See also

astropy.time.Time.earth_rotation_angle

References

IAU 2006 NFA Glossary (currently located at: https://syrte.obspm.fr/iauWGnfa/NFA_Glossary.html)

Notes

The difference between apparent sidereal time and Earth rotation angle is the equation of the origins, which is the angle between the Celestial Intermediate Origin (CIO) and the equinox. Applying apparent sidereal time to the hour angle yields the true apparent Right Ascension with respect to the equinox, while applying the Earth rotation angle yields the intermediate (CIRS) Right Ascension with respect to the CIO.

For the IAU precession models from 2000 onwards, the result includes the TIO locator (s’), which positions the Terrestrial Intermediate Origin on the equator of the Celestial Intermediate Pole (CIP) and is rigorously corrected for polar motion (except when longitude='tio' or 'greenwich').

get_delta_ut1_utc(iers_table=None, return_status=False)[source]

Find UT1 - UTC differences by interpolating in IERS Table.

Parameters:

  • iers_table (~astropy.utils.iers.IERS, optional) – Table containing UT1-UTC differences from IERS Bulletins A and/or B. Default: ~astropy.utils.iers.earth_orientation_table (which in turn defaults to the combined version provided by ~astropy.utils.iers.IERS_Auto).

  • return_status (bool) – Whether to return status values. If False (default), iers raises IndexError if any time is out of the range covered by the IERS table.

Returns:

  • ut1_utc (float or float array) – UT1-UTC, interpolated in IERS Table

  • status (int or int array) –

    Status values (if return_status=`True`)::

    astropy.utils.iers.FROM_IERS_B astropy.utils.iers.FROM_IERS_A astropy.utils.iers.FROM_IERS_A_PREDICTION astropy.utils.iers.TIME_BEFORE_IERS_RANGE astropy.utils.iers.TIME_BEYOND_IERS_RANGE

Notes

In normal usage, UT1-UTC differences are calculated automatically on the first instance ut1 is needed.

Examples

To check in code whether any times are before the IERS table range:

>>> from astropy.utils.iers import TIME_BEFORE_IERS_RANGE
>>> t = Time(['1961-01-01', '2000-01-01'], scale='utc')
>>> delta, status = t.get_delta_ut1_utc(return_status=True)
>>> status == TIME_BEFORE_IERS_RANGE
array([ True, False]...)
property delta_ut1_utc

UT1 - UTC time scale offset

property delta_tdb_tt

TDB - TT time scale offset

mean(axis=None, dtype=None, out=None, keepdims=False, *, where=True)[source]
to_datetime(timezone=None, leap_second_strict='raise')[source]

Convert to (potentially timezone-aware) ~datetime.datetime object.

If timezone is not None, return a timezone-aware datetime object.

Since the ~datetime.datetime class does not natively handle leap seconds, the behavior when converting a time within a leap second is controlled by the leap_second_strict argument. For example:

>>> from astropy.time import Time
>>> t = Time("2015-06-30 23:59:60.500")
>>> print(t.to_datetime(leap_second_strict='silent'))
2015-07-01 00:00:00.500000
Parameters:

  • timezone ({~datetime.tzinfo, None}, optional) – If not None, return timezone-aware datetime.

  • leap_second_strict (str, optional) – If raise (default), raise an exception if the time is within a leap second. If warn then issue a warning. If silent then silently handle the leap second.

Returns:

If timezone is not None, output will be timezone-aware.

Return type:

~datetime.datetime