TimeDelta¶

class
astropy.time.
TimeDelta
(val, val2=None, format=None, scale=None, precision=None, in_subfmt=None, out_subfmt=None, location=None, copy=False)[source]¶ Bases:
astropy.time.TimeBase
Represent the time difference between two times.
A TimeDelta object is initialized with one or more times in the
val
argument. The input times inval
must conform to the specifiedformat
. The optionalval2
time input should be supplied only for numeric input formats (e.g. JD) where very high precision (better than 64bit precision) is required.The allowed values for
format
can be listed with:>>> list(TimeDelta.FORMATS) ['sec', 'jd', 'datetime']
Note that for time differences, the scale can be among three groups: geocentric (‘tai’, ‘tt’, ‘tcg’), barycentric (‘tcb’, ‘tdb’), and rotational (‘ut1’). Within each of these, the scales for time differences are the same. Conversion between geocentric and barycentric is possible, as there is only a scale factor change, but one cannot convert to or from ‘ut1’, as this requires knowledge of the actual times, not just their difference. For a similar reason, ‘utc’ is not a valid scale for a time difference: a UTC day is not always 86400 seconds.
See also:
 Parameters
 valsequence, ndarray, number,
Quantity
orTimeDelta
object Value(s) to initialize the time difference(s). Any quantities will be converted appropriately (with care taken to avoid rounding errors for regular time units).
 val2sequence, ndarray, number, or
Quantity
; optional Additional values, as needed to preserve precision.
 formatstr, optional
Format of input value(s)
 scalestr, optional
Time scale of input value(s), must be one of the following values: (‘tdb’, ‘tt’, ‘ut1’, ‘tcg’, ‘tcb’, ‘tai’). If not given (or
None
), the scale is arbitrary; when added or subtracted from aTime
instance, it will be used without conversion. copybool, optional
Make a copy of the input values
 valsequence, ndarray, number,
Attributes Summary
Dict of time delta formats.
List of time delta scales.
Return an instance with the data transposed.
Return the cache associated with this instance.
Get or set time format.
Unix wildcard pattern to select subformats for parsing string input times.
First of the two doubles that internally store time value(s) in JD.
Second of the two doubles that internally store time value(s) in JD.
The number of dimensions of the instance and underlying arrays.
Unix wildcard pattern to select subformats for outputting times.
Decimal precision when outputting seconds as floating point (int value between 0 and 9 inclusive).
Time scale
The shape of the time instances.
The size of the object, as calculated from its shape.
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.
insert
(obj, values[, axis])Insert values before the given indices in the column and return a new
Time
orTimeDelta
object.isclose
(other[, atol, rtol])Returns a boolean or boolean array where two TimeDelta objects are elementwise equal within a time tolerance.
max
([axis, out, keepdims])Maximum along a given axis.
min
([axis, out, keepdims])Minimum along a given axis.
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
(*args, **kwargs)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.
sort
([axis])Return a copy sorted along the specified axis.
squeeze
(*args, **kwargs)Return an instance with singledimensional 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
(unit[, equivalencies])Convert to a quantity in the specified unit.
Convert to
datetime.timedelta
object.to_value
(*args, **kwargs)Get time delta values expressed in specified output format or unit.
transpose
(*args, **kwargs)Return an instance with the data transposed.
Attributes Documentation

FORMATS
= {'datetime': <class 'astropy.time.formats.TimeDeltaDatetime'>, 'jd': <class 'astropy.time.formats.TimeDeltaJD'>, 'sec': <class 'astropy.time.formats.TimeDeltaSec'>}¶ Dict of time delta formats.

SCALES
= ('tai', 'tt', 'tcg', 'tcb', 'tdb', 'ut1', 'local')¶ List of time delta 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.

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 theTime
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', 'unix_tai', 'cxcsec', 'gps', 'plot_date', 'stardate', 'datetime', 'ymdhms', 'iso', 'isot', 'yday', 'datetime64', 'fits', 'byear', 'jyear', 'byear_str', 'jyear_str']

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

info
¶

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.

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.
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 thereshape
method. Raises
 ValueError
If the new shape has the wrong total number of elements.
 AttributeError
If the shape of the
jd1
,jd2
,location
,delta_ut1_utc
, ordelta_tdb_tt
attributes cannot be changed without the arrays being copied. For these cases, use theTime.reshape
method (which copies any arrays that cannot be reshaped inplace).

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

value
¶ Time value(s) in current format

writeable
¶
Methods Documentation

argmax
(axis=None, out=None)¶ 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 doublesjd1
andjd2
is used. Seeargmax()
for detailed documentation.

argmin
(axis=None, out=None)¶ 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 doublesjd1
andjd2
is used. Seeargmin()
for detailed documentation.

argsort
(axis= 1)¶ 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 doublesjd1
andjd2
is used, and that corresponding attributes are copied. Internally, it useslexsort()
, and hence no sort method can be chosen.

copy
(format=None)¶ 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
 formatstr, optional
Time format of the copy.
 Returns
 tmTime object
Copy of this object

diagonal
(*args, **kwargs)¶ 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)¶ Return a copy with the array collapsed into one dimension.
Parameters are as for
flatten()
.

insert
(obj, values, axis=0)¶ Insert values before the given indices in the column and return a new
Time
orTimeDelta
object.The values to be inserted must conform to the rules for inplace setting of
Time
objects (seeGet and set values
in theTime
documentation).The API signature matches the
np.insert
API, but is more limited. The specification of insert indexobj
must be a single integer, and theaxis
must be0
for simple row insertion before the index. Parameters
 objint
Integer index before which
values
is inserted. valuesarray_like
Value(s) to insert. If the type of
values
is different from that of quantity,values
is converted to the matching type. axisint, optional
Axis along which to insert
values
. Default is 0, which is the only allowed value and will insert a row.
 Returns
 out
Time
subclass New time object with inserted value(s)
 out

isclose
(other, atol=None, rtol=0.0)[source]¶ Returns a boolean or boolean array where two TimeDelta objects are elementwise equal within a time tolerance.
This effectively evaluates the expression below:
abs(self  other) <= atol + rtol * abs(other)
 Parameters

max
(axis=None, out=None, keepdims=False)¶ Maximum along a given axis.
This is similar to
max()
, but adapted to ensure that the full precision given by the two doublesjd1
andjd2
is used, and that corresponding attributes are copied.Note that the
out
argument is present only for compatibility withnp.max
; sinceTime
instances are immutable, it is not possible to have an actualout
to store the result in.

min
(axis=None, out=None, keepdims=False)¶ Minimum along a given axis.
This is similar to
min()
, but adapted to ensure that the full precision given by the two doublesjd1
andjd2
is used, and that corresponding attributes are copied.Note that the
out
argument is present only for compatibility withnp.min
; sinceTime
instances are immutable, it is not possible to have an actualout
to store the result in.

ptp
(axis=None, out=None, keepdims=False)¶ 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 doublesjd1
andjd2
is used.Note that the
out
argument is present only for compatibility withptp
; sinceTime
instances are immutable, it is not possible to have an actualout
to store the result in.

ravel
(*args, **kwargs)¶ 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
(*args, **kwargs)[source]¶ 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 toTrue
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 setcopy
toTrue
.The convenience method copy() is available in which
copy
isTrue
by default. Parameters
 formatstr, optional
Time format of the replica.
 copybool, optional
Return a true copy instead of using references where possible.
 Returns
 tmTime object
Replica of this object

reshape
(*args, **kwargs)¶ 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 (seereshape()
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 usingShapedLikeNDArray
).

sort
(axis= 1)¶ Return a copy sorted along the specified axis.
This is similar to
sort()
, but internally uses indexing withlexsort()
to ensure that the full precision given by the two doublesjd1
andjd2
is kept, and that corresponding attributes are properly sorted and copied as well. Parameters
 axisint or None
Axis to be sorted. If
None
, the flattened array is sorted. By default, sort over the last axis.

squeeze
(*args, **kwargs)¶ Return an instance with singledimensional shape entries removed
Parameters are as for
squeeze()
. All internal data are views of the data of the original.

swapaxes
(*args, **kwargs)¶ 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')¶ 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
(unit, equivalencies=[])[source]¶ Convert to a quantity in the specified unit.
 Parameters
 unit
UnitBase
instance, str The unit to convert to.
 equivalencieslist of equivalence pairs, optional
A list of equivalence pairs to try if the units are not directly convertible (see Equivalencies). If
None
, no equivalencies will be applied at all, not even any set globallyq or within a context.
 unit
 Returns
 quantity
Quantity
The quantity in the units specified.
 quantity
See also
to_value
get the numerical value in a given unit.

to_value
(*args, **kwargs)[source]¶ Get time delta values expressed in specified output format or unit.
This method is flexible and handles both conversion to a specified
TimeDelta
format / subformat AND conversion to a specified unit. If positional argument(s) are provided then the first one is checked to see if it is a validTimeDelta
format, and next it is checked to see if it is a valid unit or unit string.To convert to a
TimeDelta
format and optional subformat the options are:tm = TimeDelta(1.0 * u.s) tm.to_value('jd') # equivalent of tm.jd tm.to_value('jd', 'decimal') # convert to 'jd' as a Decimal object tm.to_value('jd', subfmt='decimal') tm.to_value(format='jd', subfmt='decimal')
To convert to a unit with optional equivalencies, the options are:
tm.to_value('hr') # convert to u.hr (hours) tm.to_value('hr', []) # specify equivalencies as a positional arg tm.to_value('hr', equivalencies=[]) tm.to_value(unit='hr', equivalencies=[])
The builtin
TimeDelta
options forformat
are: {‘jd’, ‘sec’, ‘datetime’}.For the two numerical formats ‘jd’ and ‘sec’, the available
subfmt
options are: {‘float’, ‘long’, ‘decimal’, ‘str’, ‘bytes’}. Here, ‘long’ usesnumpy.longdouble
for somewhat enhanced precision (with the enhancement depending on platform), and ‘decimal’ instances ofdecimal.Decimal
for full precision. For the ‘str’ and ‘bytes’ subformats, the number of digits is also chosen such that time values are represented accurately. Default: as set byout_subfmt
(which by default picks the first available for a given format, i.e., ‘float’). Parameters
 formatstr, optional
The format in which one wants the
TimeDelta
values. Default: the current format. subfmtstr, optional
Possible subformat in which the values should be given. Default: as set by
out_subfmt
(which by default picks the first available for a given format, i.e., ‘float’ or ‘date_hms’). unit
UnitBase
instance or str, optional The unit in which the value should be given.
 equivalencieslist of equivalence pairs, optional
A list of equivalence pairs to try if the units are not directly convertible (see Equivalencies). If
None
, no equivalencies will be applied at all, not even any set globally or within a context.
 Returns
 value
ndarray
or scalar The value in the format or units specified.
 value

transpose
(*args, **kwargs)¶ Return an instance with the data transposed.
Parameters are as for
transpose()
. All internal data are views of the data of the original.