Time

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

Bases: astropy.utils.misc.ShapedLikeNDArray

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', 'cxcsec', 'gps', 'plot_date',
 'datetime', 'iso', 'isot', 'yday', 'fits', 'byear', 'jyear', 'byear_str',
 'jyear_str']
Parameters:

val : sequence, str, number, or Time object

Value(s) to initialize the time or times.

val2 : sequence, str, or number; optional

Value(s) to initialize the time or times.

format : str, optional

Format of input value(s)

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

Subformat for inputting string times

out_subfmt : str, optional

Subformat for outputting string times

location : 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.

copy : bool, optional

Make a copy of the input values

Attributes Summary

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.
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.
value Time value(s) in current format

Methods Summary

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]) 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.
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.
light_travel_time(skycoord[, kind, …]) Light travel time correction to the barycentre or heliocentre.
max([axis, out, keepdims]) Maximum along a given axis.
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]) Peak to peak (maximum - minimum) along a given axis.
ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension.
replicate([format, copy]) 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
swapaxes(*args, **kwargs) Return an instance with the given axes interchanged.
take(indices[, axis, mode]) Return a new instance formed from the elements at the given indices.
to_datetime([timezone]) Convert to (potentially timezone-aware) datetime object.
transpose(*args, **kwargs) Return an instance with the data transposed.

Attributes Documentation

FORMATS = OrderedDict([('jd', <class 'astropy.time.formats.TimeJD'>), ('mjd', <class 'astropy.time.formats.TimeMJD'>), ('decimalyear', <class 'astropy.time.formats.TimeDecimalYear'>), ('unix', <class 'astropy.time.formats.TimeUnix'>), ('cxcsec', <class 'astropy.time.formats.TimeCxcSec'>), ('gps', <class 'astropy.time.formats.TimeGPS'>), ('plot_date', <class 'astropy.time.formats.TimePlotDate'>), ('datetime', <class 'astropy.time.formats.TimeDatetime'>), ('iso', <class 'astropy.time.formats.TimeISO'>), ('isot', <class 'astropy.time.formats.TimeISOT'>), ('yday', <class 'astropy.time.formats.TimeYearDayTime'>), ('fits', <class 'astropy.time.formats.TimeFITS'>), ('byear', <class 'astropy.time.formats.TimeBesselianEpoch'>), ('jyear', <class 'astropy.time.formats.TimeJulianEpoch'>), ('byear_str', <class 'astropy.time.formats.TimeBesselianEpochString'>), ('jyear_str', <class 'astropy.time.formats.TimeJulianEpochString'>)])

Dict of time formats

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

List of time scales

T

Return an instance with the data transposed.

Parameters are as for T. All internal data are views of the data of the original.

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.

The format defines the way times are represented when accessed via the .value attribute. By default it is the same as the format used for initializing the Time instance, but it can be set to any other value that could be used for initialization. These can be listed with:

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

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

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.

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.

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.

Like shape, can be set to a new shape by assigning a tuple. Note that if different instances share some but not all underlying data, setting the shape of one instance can make the other instance unusable. Hence, it is strongly recommended to get new, reshaped instances with the reshape method.

Raises:

AttributeError

If the shape of the jd1, jd2, location, delta_ut1_utc, or delta_tdb_tt attributes cannot be changed without the arrays being copied. For these cases, use the Time.reshape method (which copies any arrays that cannot be reshaped in-place).

size

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

value

Time value(s) in current format

Methods Documentation

argmax(axis=None, out=None)[source] [edit on github]

Return indices of the maximum values along the given axis.

This is similar to argmax(), but adapted to ensure that the full precision given by the two doubles jd1 and jd2 is used. See argmax() for detailed documentation.

argmin(axis=None, out=None)[source] [edit on github]

Return indices of the minimum values along the given axis.

This is similar to argmin(), but adapted to ensure that the full precision given by the two doubles jd1 and jd2 is used. See argmin() for detailed documentation.

argsort(axis=-1)[source] [edit on github]

Returns the indices that would sort the time array.

This is similar to argsort(), but adapted to ensure that the full precision given by the two doubles jd1 and jd2 is used, and that corresponding attributes are copied. Internally, it uses lexsort(), and hence no sort method can be chosen.

copy(format=None)[source] [edit on github]

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

If format is supplied then the time format of the returned Time object will be set accordingly, otherwise it will be unchanged from the original.

In this method a full copy of the internal time arrays will be made. The internal time arrays are normally not changeable by the user so in most cases the replicate() method should be used.

Parameters:

format : str, optional

Time format of the copy.

Returns:

tm : Time object

Copy of this object

diagonal(*args, **kwargs) [edit on github]

Return an instance with the specified diagonals.

Parameters are as for diagonal(). All internal data are views of the data of the original.

flatten(*args, **kwargs) [edit on github]

Return a copy with the array collapsed into one dimension.

Parameters are as for flatten().

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

Find UT1 - UTC differences by interpolating in IERS Table.

Parameters:

iers_table : astropy.utils.iers.IERS table, optional

Table containing UT1-UTC differences from IERS Bulletins A and/or B. If None, use default version (see astropy.utils.iers)

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]...)
light_travel_time(skycoord, kind='barycentric', location=None, ephemeris=None)[source] [edit on github]

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 : SkyCoord

The sky location to calculate the correction for.

kind : str, optional

'barycentric' (default) or 'heliocentric'

location : 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 solar_system_ephemeris.

Returns:

time_offset : TimeDelta

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.

max(axis=None, out=None, keepdims=False)[source] [edit on github]

Maximum along a given axis.

This is similar to max(), but adapted to ensure that the full precision given by the two doubles jd1 and jd2 is used, and that corresponding attributes are copied.

Note that the out argument is present only for compatibility with np.max; since Time instances are immutable, it is not possible to have an actual out to store the result in.

min(axis=None, out=None, keepdims=False)[source] [edit on github]

Minimum along a given axis.

This is similar to min(), but adapted to ensure that the full precision given by the two doubles jd1 and jd2 is used, and that corresponding attributes are copied.

Note that the out argument is present only for compatibility with np.min; since Time instances are immutable, it is not possible to have an actual out to store the result in.

classmethod now()[source] [edit on github]

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

Note

“Now” is determined using the utcnow function, so its accuracy and precision is determined by that function. Generally that means it is set by the accuracy of your system clock.

Returns:

nowtime

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

ptp(axis=None, out=None, keepdims=False)[source] [edit on github]

Peak to peak (maximum - minimum) along a given axis.

This is similar to ptp(), but adapted to ensure that the full precision given by the two doubles jd1 and jd2 is used.

Note that the out argument is present only for compatibility with ptp; since Time instances are immutable, it is not possible to have an actual out to store the result in.

ravel(*args, **kwargs) [edit on github]

Return an instance with the array collapsed into one dimension.

Parameters are as for ravel(). Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape (-1,) to the shape attribute.

replicate(format=None, copy=False)[source] [edit on github]

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

If format is supplied then the time format of the returned Time object will be set accordingly, otherwise it will be unchanged from the original.

If copy is set to True then a full copy of the internal time arrays will be made. By default the replica will use a reference to the original arrays when possible to save memory. The internal time arrays are normally not changeable by the user so in most cases it should not be necessary to set copy to True.

The convenience method copy() is available in which copy is True by default.

Parameters:

format : str, optional

Time format of the replica.

copy : bool, optional

Return a true copy instead of using references where possible.

Returns:

tm : Time object

Replica of this object

reshape(*args, **kwargs) [edit on github]

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

Parameters are as for reshape(). Note that it is not always possible to change the shape of an array without copying the data (see reshape() documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ShapedLikeNDArray).

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

Calculate sidereal time.

Parameters:

kind : str

'mean' or 'apparent', i.e., accounting for precession only, or also for nutation.

longitude : Quantity, str, or None; optional

The longitude on the Earth at which to compute the sidereal time. Can be given as a Quantity with angular units (or an Angle or Longitude), or as a name of an observatory (currently, only 'greenwich' is supported, equivalent to 0 deg). If None (default), the lon attribute of the Time object is used.

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:

sidereal time : Longitude

Sidereal time as a quantity with units of hourangle

sort(axis=-1)[source] [edit on github]

Return a copy sorted along the specified axis.

This is similar to sort(), but internally uses indexing with lexsort() to ensure that the full precision given by the two doubles jd1 and jd2 is kept, and that corresponding attributes are properly sorted and copied as well.

Parameters:

axis : int or None

Axis to be sorted. If None, the flattened array is sorted. By default, sort over the last axis.

squeeze(*args, **kwargs) [edit on github]

Return an instance with single-dimensional shape entries removed

Parameters are as for squeeze(). All internal data are views of the data of the original.

swapaxes(*args, **kwargs) [edit on github]

Return an instance with the given axes interchanged.

Parameters are as for swapaxes(): axis1, axis2. All internal data are views of the data of the original.

take(indices, axis=None, mode='raise') [edit on github]

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

Parameters are as for take(), except that, obviously, no output array can be given.

to_datetime(timezone=None)[source] [edit on github]

Convert to (potentially timezone-aware) datetime object.

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

Parameters:

timezone : {tzinfo, None} (optional)

If not None, return timezone-aware datetime.

Returns:

datetime

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

transpose(*args, **kwargs) [edit on github]

Return an instance with the data transposed.

Parameters are as for transpose(). All internal data are views of the data of the original.