Navigation

The astropy.time package provides functionality for manipulating times and
dates. Specific emphasis is placed on supporting time scales (e.g. UTC, TAI,
UT1, TDB) and time representations (e.g. JD, MJD, ISO 8601) that are used in
astronomy and required to calculate, e.g., sidereal times and barycentric
corrections.
It uses Cython to wrap the C language ERFA time and calendar
routines, using a fast and memory efficient vectorization scheme.

All time manipulations and arithmetic operations are done internally using two
64-bit floats to represent time. Floating point algorithms from [1] are used so
that the Time object maintains sub-nanosecond precision over times spanning
the age of the universe.

The basic way to use astropy.time is to create a Time
object by supplying one or more input time values as well as the time format and
time scale of those values. The input time(s) can either be a single scalar like
"2010-01-0100:00:00" or a list or a numpy array of values as shown below.
In general any output values have the same shape (scalar or array) as the input.

The format argument specifies how to interpret the input values,
e.g. ISO or JD or Unix time. The scale argument specifies the time scale for the
values, e.g. UTC or TT or UT1. The scale argument is optional and
defaults to UTC except for Time from epoch formats.
We could have written the above as:

>>> t=Time(times,format='isot')

When the format of the input can be unambiguously determined then the
format argument is not required, so we can simplify even further:

>>> t=Time(times)

Now let’s get the representation of these times in the JD and MJD
formats by requesting the corresponding Time attributes:

Note that both the ISO (ISOT) and JD representations of t2 are different
than for t because they are expressed relative to the TT time scale. Of
course, from the numbers or strings one could not tell; one format in which
this information is kept is the fits format:

In astropy.time a “time” is a single instant of time which is
independent of the way the time is represented (the “format”) and the time
“scale” which specifies the offset and scaling relation of the unit of time.
There is no distinction made between a “date” and a “time” since both concepts
(as loosely defined in common usage) are just different representations of a
moment in time.

Once a Time object is created it cannot be altered internally. In code lingo
it is “immutable.” In particular the common operation of “converting” to a
different time scale is always performed by returning a copy of the original
Time object which has been converted to the new time scale.

The time format specifies how an instant of time is represented. The currently
available formats are can be found in the Time.FORMATS dict and
are listed in the table below. Each of these formats is implemented as a class
that derives from the base TimeFormat class.
This class structure can be easily adapted and extended by users for
specialized time formats not supplied in astropy.time.

The TimeFITS format allows for most
but not all of the the FITS standard [2]. Not implemented (yet) is
support for a LOCAL timescale. Furthermore, FITS supports some deprecated
names for timescales; these are translated to the formal names upon
initialization. Furthermore, any specific realization information,
such as UT(NIST) is stored only as long as the time scale is not changed.

The time format classes TimeISO,
TimeISOT, TimeFITS, and
TimeYearDayTime support the concept of
subformats. This allows for variations on the basic theme of a format in both
the input string parsing and the output.

The supported subformats are date_hms, date_hm, and date
for all but the TimeFITS format; the latter
does not support date_hm but does support longdate_hms and
longdate for years before the year 0 and after the year 10000. The
table below illustrates these subformats for iso, fits, yday
formats:

The formats cxcsec, gps, and unix are a little special in
that they provide a floating point representation of the elapsed
time in seconds since a particular reference date. These formats have
a intrinsic time scale which is used to compute the elapsed seconds
since the reference date.

Format

Scale

Reference date

cxcsec

TT

1998-01-0100:00:00

unix

UTC

1970-01-0100:00:00

gps

TAI

1980-01-0600:00:19

Unlike the other formats which default to UTC, if no scale is provided when
initializing a Time object then the above intrinsic scale is used.
This is done for computational efficiency.

A Time object can hold either a single time value or an array of time values.
The distinction is made entirely by the form of the input time(s). If a Time
object holds a single value then any format outputs will be a single scalar
value, and likewise for arrays. Like other arrays and lists, Time objects
holding arrays are subscriptable, returning scalar or array objects as
appropriate:

Note that similarly to the ndarray methods, all but
flatten() try to use new views of the data,
with the data copied only if that it is impossible (as discussed, e.g., in
the documentation for numpy reshape()).

The Time class initializer will not accept ambiguous inputs,
but it will make automatic inferences in cases where the inputs are
unambiguous. This can apply when the times are supplied as datetime
objects or strings. In the latter case
it is not required to specify the format because the available
string formats have no overlap. However, if the format is known in advance
the string parsing will be faster if the format is provided.

The Time object maintains an internal representation of time as a pair of
double precision numbers expressing Julian days. The sum of the two numbers is
the Julian Date for that time relative to the given time scale. Users
requiring no better than microsecond precision over human time scales (~100
years) can safely ignore the internal representation details and skip this section.

This representation is driven by the underlying ERFA C-library implementation.
The ERFA routines take care throughout to maintain overall precision of the
double pair. The user is free to choose the way in which total JD is
provided, though internally one part contains integer days and the
other the fraction of the day, as this ensures optimal accuracy for
all conversions. The internal JD pair is available via the jd1
and jd2 attributes:

The val argument specifies the input time or times and
can be a single string or number, or it can be a Python list or numpy array
of strings or numbers. To initialize a Time object based on a specified time,
it must be present. If val is absent (or None), the Time object will
be created for the time corresponding to the instant the object is created.

In most situations one also needs to specify the time scale via the
scale argument. The Time class will never guess the time scale,
so a simple example would be:

The val2 argument is available for specialized situations where extremely
high precision is required. Recall that the internal representation of time
within astropy.time is two double-precision numbers that when summed give
the Julian date. If provided the val2 argument is used in combination with
val to set the second the internal time values. The exact interpretation of
val2 is determined by the input format class. As of this release all
string-valued formats ignore val2 and all numeric inputs effectively add
the two values in a way that maintains the highest precision. Example:

The scale argument sets the time scale and is required except for time
formats such as plot_date (TimePlotDate) and unix
(TimeUnix). These formats represent the duration
in SI seconds since a fixed instant in time which is independent of time scale.

The precision setting affects string formats when outputting a value that
includes seconds. It must be an integer between 0 and 9. There is no effect
when inputting time values from strings. The default precision is 3. Note
that the limit of 9 digits is driven by the way that ERFA handles fractional
seconds. In practice this should should not be an issue.

The in_subfmt argument provides a mechanism to select one or more
subformat values from the available subformats for string input. Multiple
allowed subformats can be selected using Unix-style wildcard characters, in
particular * and ?, as documented in the Python fnmatch module.

The default value for in_subfmt is * which matches any available
subformat. This allows for convenient input of values with unknown or
heterogeneous subformat:

This optional parameter specifies the observer location, using an
EarthLocation object or a tuple containing any form that can initialize one:
either a tuple with geocentric coordinates (X, Y, Z), or a tuple with geodetic
coordinates (longitude, latitude, height; with height defaulting to zero).
They are used for time scales that are sensitive to observer location
(currently, only TDB, which relies on the ERFA routine eraDtdb to
determine the time offset between TDB and TT), as well as for sidereal time if
no explicit longitude is given.

Instants of time can be represented in different ways, for instance as an
ISO-format date string ('1999-07-2304:31:00') or seconds since 1998.0
(49091460.0) or Modified Julian Date (51382.187451574).

The representation of a Time object in a particular format is available
by getting the object attribute corresponding to the format name. The list of
available format names is in the time format section.

A new Time object for the same time value(s) but referenced to a new time
scale can be created getting the object attribute corresponding to the time
scale name. The list of available time scale names is in the time scale
section and in the figure below illustrating the network of time scale
transformations.

In this process the format and other object attributes like lon,
lat, and precision are also propagated to the new object.

As noted in the Timeobjectbasics section, a Time object is immutable and
the internal time values cannot be altered once the object is created. The
process of changing the time scale therefore begins by making a copy of the
original object and then converting the internal time values in the copy to the
new time scale. The new Time object is returned by the attribute access.

The computations for transforming to different time scales or formats can be
time-consuming for large arrays. In order to avoid repeated computations, each
Time or TimeDelta instance caches such transformations internally:

Time scale transformations that cross one of the orange circles in the image
above require an additional offset time value that is model or
observation-dependent. See SOFA Time Scale and Calendar Tools for further details.

The two attributes delta_ut1_utc and
delta_tdb_tt provide a way to set
these offset times explicitly. These represent the time scale offsets
UT1 - UTC and TDB - TT, respectively. As an example:

>>> t=Time('2010-01-01 00:00:00',format='iso',scale='utc')>>> t.delta_ut1_utc=0.334# Explicitly set one part of the transformation>>> t.ut1.iso# ISO representation of time in UT1 scale'2010-01-01 00:00:00.334'

For the UT1 to UTC offset, one has to interpolate the observed values provided
by the International Earth Rotation and Reference Systems (IERS) Service. Astropy will automatically download and use values
from the IERS which cover times spanning from 1973-Jan-01 through one year into
the future. In addition the astropy package is bundled with a data table of
values provided in Bulletin B, which cover the period from 1962 to shortly
before an astropy release.

When the delta_ut1_utc attribute is not set
explicitly then IERS values will be used (initiating a download of a few Mb
file the first time). For details about how IERS values are used in astropy
time and coordinates, and to understand how to control automatic downloads see
IERS data access (astropy.utils.iers). The example below illustrates converting to the UT1
scale along with the auto-download feature:

The IERS_Auto class contains machinery
to ensure that the IERS table is kept up to date by auto-downloading the
latest version as needed. This means that the IERS table is assured of
having the state-of-the-art definitive and predictive values for Earth
rotation. As a user it is your responsibility to understand the
accuracy of IERS predictions if your science depends on that. If you
request UT1-UTC for times beyond the range of IERS table data then the
nearest available values will be provided.

In the case of the TDB to TT offset, most users need only provide the lon
and lat values when creating the Time object. If the
delta_tdb_tt attribute is not explicitly set then
the ERFA C-library routine eraDtdb will be used to compute the TDB to TT
offset. Note that if lon and lat are not explicitly initialized,
values of 0.0 degrees for both will be used.

The following code replicates an example in the SOFA Time Scale and Calendar
Tools document. It
does the transform from UTC to all supported time scales (TAI, TCB, TCG, TDB,
TT, UT1, UTC). This requires an observer location (here, latitude and
longitude).:

Apparent or mean sidereal time can be calculated using
sidereal_time(). The method returns a Longitude
with units of hourangle, which by default is for the longitude corresponding to
the location with which the Time object is initialized. Like the scale
transformations, ERFA C-library routines are used under the hood, which support
calculations following different IAU resolutions. Sample usage:

Simple time arithmetic is supported using the TimeDelta class. The
following operations are available:

Create a TimeDelta explicitly by instantiating a class object

Create a TimeDelta by subtracting two Times

Add a TimeDelta to a Time object to get a new Time

Subtract a TimeDelta from a Time object to get a new Time

Add two TimeDelta objects to get a new TimeDelta

Negate a TimeDelta or take its absolute value

Multiply or divide a TimeDelta by a constant or array

Convert TimeDelta objects to and from time-like Quantities

The TimeDelta class is derived from the Time class and shares many of its
properties. One difference is that the time scale has to be one for which one
day is exactly 86400 seconds. Hence, the scale cannot be UTC.

Above, one sees that the difference between two UTC times is a TimeDelta
with a scale of TAI. This is because a UTC time difference cannot be uniquely
defined unless one knows the two times that were differenced (because of leap
seconds, a day does not always have 86400 seconds). For all other time
scales, the TimeDelta inherits the scale of the first Time object:

The arrival times of photons at an observatory are not particularly useful for
accurate timing work, such as eclipse/transit timing of binaries or exoplanets.
This is because the changing location of the observatory causes photons to
arrive early or late. The solution is to calculate the time the photon would
have arrived at a standard location; either the Solar system barycentre or the
heliocentre.

Suppose you observed IP Peg from Greenwich and have a list of times in MJD form, in
the UTC timescale. You then create appropriate Time and SkyCoord objects and
calculate light travel times to the barycentre as follows:

The method returns an TimeDelta object, which can be added to
your times to give the arrival time of the photons at the barycentre or
heliocentre. Here, one should be careful with the timescales used; for more
detailed information about timescales, see Time Scale.

The heliocentre is not a fixed point, and therefore the gravity
continually changes at the heliocentre. Thus, the use of a relativistic
timescale like TDB is not particularly appropriate, and, historically,
times corrected to the heliocentre are given in the UTC timescale:

>>> times_heliocentre=times.utc+ltt_helio

Corrections to the barycentre are more precise than the heliocentre,
because the barycenter is a fixed point where gravity is constant. For
maximum accuracy you want to have your barycentric corrected times in a
timescale that has always ticked at a uniform rate, and ideally one
whose tick rate is related to the rate that a clock would tick at the
barycentre. For this reason, barycentric corrected times normally use
the TDB timescale:

>>> time_barycentre=times.tdb+ltt_bary

By default, the light travel time is calculated using the position and velocity
of Earth and the Sun from built-in ERFA routines,
but one can also use more precise calculations using the JPL ephemerides (which are derived from
dynamical models). An example using the JPL ephemerides is:

The difference between the builtin ephemerides and the JPL ephemerides is normally
of the order of 1/100th of a millisecond, so the builtin ephemerides should be suitable
for most purposes. For more details about what ephemerides are available,
including the requirements for using JPL ephemerides, see Solar System Ephemerides.

Where possible, Quantity objects with units of time are treated as TimeDelta
objects with undefined scale (though necessarily with lower precision). They
can also be used as input in constructing Time and TimeDelta objects, and
TimeDelta objects can be converted to Quantity objects of arbitrary units
of time. Usage is most easily illustrated by examples:

Some applications may need a custom Time format, and this capability is
available by making a new subclass of the TimeFormat class.
When such a subclass is defined in your code then the format class and
corresponding name is automatically registered in the set of available time
formats.

The key elements of a new format class are illustrated by examining the
code for the jd format (which is one of the simplest):

classTimeJD(TimeFormat):""" Julian Date time format. """name='jd'# Unique format namedefset_jds(self,val1,val2):""" Set the internal jd1 and jd2 values from the input val1, val2. The input values are expected to conform to this format, as validated by self._check_val_type(val1, val2) during __init__. """self._check_scale(self._scale)# Validate scale.self.jd1,self.jd2=day_frac(val1,val2)@propertydefvalue(self):""" Return format ``value`` property from internal jd1, jd2 """returnself.jd1+self.jd2

As mentioned above, the _check_val_type(self,val1,val2)
method may need to be overridden to validate the inputs as conforming to the
format specification. By default this checks for valid float, float array, or
Quantity inputs. In contrast the iso format class ensures the inputs
meet the ISO format spec for strings.

One special case that is relatively common and easier to implement is a format
that makes a small change to the date format. For instance one could insert T
in the yday format with the following TimeYearDayTimeCustom class. Notice how
the subfmts definition is modified slightly from the standard
TimeISO class from which it inherits:

Another special case that is relatively common is a
format that represents the time since a particular epoch. The classic example
is Unix time which is the number of seconds since 1970-01-01 00:00:00 UTC,
not counting leap seconds. What if we wanted that value but do want
to count leap seconds. This would be done by using the TAI scale instead
of the UTC scale. In this case we inherit from the
TimeFromEpoch class and define a few class attributes:

Going beyond this will probably require looking at the astropy code for more
guidance, but if you get stuck the astropy developers are more than happy to
help. If you write a format class that is widely useful then we might want to
include it in the core!

This package makes use of the ERFA Software ANSI C library. The copyright of the ERFA
software belongs to the NumFOCUS Foundation. The library is made available
under the terms of the “BSD-three clauses” license.

The ERFA library is derived, with permission, from the International
Astronomical Union’s “Standards of Fundamental Astronomy” library,
available from http://www.iausofa.org.