spacepy.time.Ticktock

class spacepy.time.Ticktock(data, dtype)[source]

Ticktock class holding various time coordinate systems (TAI, UTC, ISO, JD, MJD, UNX, RDT, CDF, DOY, eDOY, APT)

Possible input data types:

ISO

ISO standard format like ‘2002-02-25T12:20:30’

UTC

datetime object with UTC time

TAI

Elapsed seconds since 1958-1-1 (includes leap seconds)

UNX

Elapsed seconds since 1970-1-1 ignoring leapseconds (all days have 86400 secs).

JD

Julian days elapsed

MJD

Modified Julian days

RDT

Rata Die days elapsed since 0001-1-1

CDF

CDF Epoch type: float milliseconds since 0000-1-1 ignoring leapseconds

APT

AstroPy Time. Requires AstroPy 1.0. (New in version 0.2.2.)

Possible output data types: All those listed above, plus:

DOY

Integer day of year, starts with day 1

eDOY

Fractional day of year, starts at day 0

It is strongly recommended to access various time systems via the attributes listed above, as in the examples. They will be calculated automatically if necessary. Using the get methods will force a recalculation.

The original input data will always be available as the data attribute.

Changed in version 0.2.2: In earlier versions of SpacePy, most values were derived from the datetime-based UTC representation. This did not properly handle leap seconds in many cases. Now most are derived from TAI (exceptions being DOY and eDOY). In addition to differences around actual leap seconds, this may result in small differences between versions of SpacePy, with relative magnitude on the order of the resolution of a 64-bit float (2e-16). For times in the modern era, this is about 50 microseconds (us) for JD, 15 us for CDF, 1.5 us for RDT, 1 us for MJD, and 360 nanoseconds for TAI.

The relationships between parameters and how they are calculated are listed in the get methods and illustrated below.

../_images/ticktock_relationships.svg
Parameters
dataarray_like (int, datetime, float, string)

time stamp

dtypestring {CDF, ISO, UTC, TAI, UNX, JD, MJD, RDT, APT} or function

data type for data, if a function it must convert input time format to Python datetime

Returns
outTicktock

instance with self.data, self.dtype, self.UTC etc

Other Parameters
isoformatstr, optional

New in version 0.2.2.

Format string used for parsing and outputting ISO format. Input is not forced to be in this format; it is tried first, and other common formats tried if parsing fails. Because of this, if ISO input is in a consistent format, specifying this can speed up the input parsing. Can be changed on existing Ticktock with isoformat() method. Default '%Y-%m-%dT%H:%M:%S'.

Notes

UTC data type is implemented as Python datetime, which cannot represent leap seconds. The time within a leap second is regarded as not happening.

The CDF data type is the older CDF_EPOCH time type, not the newer CDF_TIME_TT2000. It similarly cannot represent leap seconds. Year 0 is considered a leap year.

Examples

>>> x = Ticktock([2452331.0142361112, 2452332.0142361112], 'JD')
>>> x.ISO
dmarray(['2002-02-25T12:20:30', '2002-02-26T12:20:30'], dtype='|S19')
>>> x.DOY # Day of year
dmarray([ 56.,  57.])
>>> y = Ticktock(['01-01-2013', '20-03-2013'], lambda x: datetime.datetime.strptime(x, '%d-%m-%Y'))
>>> y.UTC
dmarray([2013-01-01 00:00:00, 2013-03-20 00:00:00], dtype=object)
>>> y.DOY # Day of year
dmarray([  1.,  79.])

append(other)

Will be called when another Ticktock instance has to be appended to the current one

argsort()

This will return the indices that would sort the Ticktock values

convert(dtype)

convert a Ticktock instance into a new time coordinate system provided in dtype

getAPT()

a.APT or a.getAPT()

getCDF()

a.getCDF() or a.CDF

getDOY()

a.DOY or a.getDOY()

getGPS()

a.GPS or a.getGPS()

getISO()

a.ISO or a.getISO()

getJD()

a.JD or a.getJD()

getMJD()

a.MJD or a.getMJD()

getRDT()

a.RDT or a.RDT()

getTAI()

a.TAI or a.getTAI()

getUNX()

a.UNX or a.getUNX()

getUTC()

a.UTC or a.getUTC()

geteDOY()

a.eDOY or a.geteDOY()

getleapsecs()

a.leaps or a.getleapsecs()

isoformat(b, attrib)

This changes the self._isofmt attribute by and subsequently this function will update the ISO attribute.

now()

Create Ticktock with the current UTC time.

sort()

This will sort the Ticktock values in place based on the values in data.

today()

Create Ticktock with the current UTC date and time set to 00:00:00

update_items(attrib)

After changing the self.data attribute by either __setitem__ or __add__ etc this function will update all other attributes.

append(other)[source]

Will be called when another Ticktock instance has to be appended to the current one

Parameters
otherTicktock

other (Ticktock instance)

argsort()[source]

This will return the indices that would sort the Ticktock values

Returns
outlist

indices that would sort the Ticktock values

Other Parameters
kindstr, optional

Sort algorithm to use, default ‘quicksort’.

Changed in version 0.2.2: Default is now ‘quicksort’ to match numpy default; previously was ‘mergesort’.

convert(dtype)[source]

convert a Ticktock instance into a new time coordinate system provided in dtype

Parameters
dtypestring

data type for new system, possible values are {CDF, ISO, UTC, TAI, UNX, JD, MJD, RDT}

Returns
outTicktock

Ticktock instance with new time coordinates

See also

CDF
ISO
UTC

Examples

>>> a = Ticktock(['2002-02-02T12:00:00', '2002-02-02T12:00:00'], 'ISO')
>>> s = a.convert('TAI')
>>> type(s)
<class 'time.Ticktock'>
>>> s
Ticktock( [1391342432 1391342432] ), dtype=TAI
getAPT()[source]

a.APT or a.getAPT()

Return AstroPy time object.

Always recalculates from the current value of TAI, which will be created if necessary.

Updates the APT attribute.

Returns
outastropy.time.Time

AstroPy Time object

Notes

New in version 0.2.2.

Requires AstroPy 1.0. The returned value will be on the tai scale in gps format (unless the Ticktock was created from a Time object, in which case it will be the original input.) See the astropy.time docs for conversion to other scales and formats.

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.APT
<Time object: scale='tai' format='gps' value=696686413.0>
getCDF()[source]

a.getCDF() or a.CDF

Return CDF Epoch time which is milliseconds since 0000-1-1 at 00:00:00.000. “Year zero” is a convention chosen by NSSDC to measure epoch values. This date is more commonly referred to as 1 BC and is considered a leap year.

The CDF date/time calculations do not take into account the change to the Gregorian calendar or leap seconds, and cannot be directly converted into Julian date/times.

Returns data if it was provided in CDF; otherwise always recalculates from the current value of TAI, which will be created if necessary.

Updates the CDF attribute.

Returns
outnumpy array

milliseconds since 0000-01-01T00:00:00 assuming no discontinuities.

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.CDF
array([  6.31798704e+13])
getDOY()[source]

a.DOY or a.getDOY()

extract DOY (days since January 1st of given year)

Always recalculates from the current value of UTC, which will be created if necessary.

Updates the DOY attribute.

Returns
outnumpy array

day of the year

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.DOY
array([ 33])
getGPS()[source]

a.GPS or a.getGPS()

Return seconds since the GPS epoch (1980-1-6T00:00 UT)

Always recalculates from the current value of TAI, which will be created if necessary.

Updates the GPS attribute.

Returns
outnumpy array

elapsed secs since 1980-1-6. Leap seconds are counted; i.e. there are no discontinuities.

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.GPS
dmarray([6.96686413e+08])
getISO()[source]

a.ISO or a.getISO()

convert dtype data into ISO string

Always recalculates from the current value of UTC, which will be created if necessary. Applies leapsecond correction based on TAI, also created as necessary.

Updates the ISO attribute.

Returns
outlist of strings

date in ISO format

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.ISO
dmarray(['2002-02-02T12:00:00'])
getJD()[source]

a.JD or a.getJD()

convert dtype data into Julian Date (JD)

Returns data if it was provided in JD; otherwise always recalculates from the current value of TAI, which will be created if necessary.

Updates the JD attribute.

Returns
outnumpy array

elapsed days since 4713 BCE 01-01T12:00

Notes

This is based on the UTC day, defined as JD(UTC) - 2 400 000.5, per the recommendation of IAU General Assembly XXIII resolution B1. Julian days with leapseconds are 86401 seconds long and each second is a smaller fraction of the day. Note this “stretching” is across the Julian Day, noon to noon.

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.JD
array([ 2452308.])
getMJD()[source]

a.MJD or a.getMJD()

convert dtype data into MJD (modified Julian date)

Returns data if it was provided in MJD; otherwise always recalculates from the current value of TAI which will be created if necessary.

Updates the MJD attribute.

Returns
outnumpy array

elapsed days since 1858-11-17T00:00 (Julian date of 1858-11-17T12:00 was 2 400 000)

Notes

This is based on the UTC day, defined as JD(UTC) - 2 400 000.5, per the recommendation of IAU General Assembly XXIII resolution B1. Julian days with leapseconds are 86401 seconds long and each second is a smaller fraction of the day. Note this “stretching” is across the Julian Day not the MJD, so it will affect the last half of the MJD before the leap second and the first half of the following MJD, so that MJD is always JD - 2 400 000.5 This also means that the MJD following a leap second does not begin exactly at midnight.

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.MJD
array([ 52307.5])
>>> a = Ticktock('2009-01-01T00:00:00', 'ISO')
>>> a.MJD
array([ 54832.00000579])
getRDT()[source]

a.RDT or a.RDT()

convert dtype data into Rata Die (lat.) Time, or elapsed days counting 0001-01-01 as day 1. This is a naive conversion: it ignores the existence of leapseconds for fractional days and ignores the conversion from Julian to Gregorian calendar, i.e. it assumes Gregorian calendar infinitely into the past.

Returns data if it was provided in RDT; otherwise always recalculates from the current value of TAI, which will be created if necessary.

Updates the RDT attribute.

Returns
outnumpy array

elapsed days counting 1/1/1 as day 1.

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.RDT
array([ 730883.5])
getTAI()[source]

a.TAI or a.getTAI()

return TAI (International Atomic Time), elapsed secs since 1958-1-1 (leap seconds are counted.) Ticktock’s handling of TAI and UTC conversions treats the UTC second as always equal in length to the SI second (and thus TAI), ignoring frequency changes and fractional leap seconds from 1958 through 1972, i.e. the UTC to TAI offset is always treated as an integer, truncated (not rounded) from the value at the most recent leap second (or fraction thereof).

Return value comes from (in priority order):

  1. If data was provided in TAI, returns data.

  2. Else recalculates directly from data if it was provided in APT, CDF, GPS, ISO, JD, MJD, RDT, or UNX.

  3. Else calculates from current value of UTC, which will be created if necessary.

Updates the TAI attribute; will also create the UTC and ISO attributes from data if input is in ISO (but will not overwrite an existing ISO or UTC). This is for efficiency, as computation from ISO requires calculating UTC and makes creating a formatted ISO string easy.

Returns
outnumpy array

TAI as seconds since 1958-1-1.

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.TAI
array([1391342432])
getUNX()[source]

a.UNX or a.getUNX()

convert dtype data into Unix Time (Posix Time) seconds since 1970-1-1 (not counting leap seconds)

Returns data if it was provided in UNX; otherwise always recalculates from the current value of TAI, which will be created if necessary.

Updates the UNX attribute.

Returns
outnumpy array

elapsed secs since 1970-1-1 (not counting leap secs)

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.UNX
array([  1.01265120e+09])
getUTC()[source]

a.UTC or a.getUTC()

convert dtype data into UTC object a la datetime()

Return value comes from (in priority order):

  1. If data was provided in UTC, returns data.

  2. Else recalculates directly from data if it was provided in ISO.

  3. Else calculates from current value of TAI, which will be created if necessary. (data is TAI, GPS, JD, MJD, RDT, CDF, UNX)).

Updates the UTC attribute.

Returns
outlist of datetime objects

datetime object in UTC time

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.UTC
[datetime.datetime(2002, 2, 2, 12, 0)]
geteDOY()[source]

a.eDOY or a.geteDOY()

extract eDOY (elapsed days since midnight January 1st of given year)

Always recalculates from the current value of UTC, which will be created if necessary.

Updates the eDOY attribute.

Returns
outnumpy array

days elapsed since midnight bbedJan. 1st

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.eDOY
array([ 32.5])
getleapsecs()[source]

a.leaps or a.getleapsecs()

retrieve leapseconds from lookup table, used in getTAI

Always recalculates from current value of TAI if data is dtype TAI, otherwise from the current value of UTC, which will be created if necessary.

Updates the leaps attribute.

Returns
outnumpy array

leap seconds

See also

getTAI

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.leaps
array([32])
isoformat(b, attrib)[source]

This changes the self._isofmt attribute by and subsequently this function will update the ISO attribute.

Parameters
fmtstring, optional
classmethod now()[source]

Create Ticktock with the current UTC time.

Equivalent to datetime.utcnow()

Changed in version 0.2.2: This now returns a UTC time; previously it returned a Ticktock UTC object, but in the local timezone, which made all conversions incorrect.

Returns
outticktock

Ticktock object with the current time, equivalent to datetime.utcnow()

sort()[source]

This will sort the Ticktock values in place based on the values in data. If you need a stable sort use kind=’mergesort’

Other Parameters
kindstr

Sort algorithm to use, default ‘quicksort’.

classmethod today()[source]

Create Ticktock with the current UTC date and time set to 00:00:00

Similar to date.today() with time included but in UTC and with the time included (zero hours, minutes, seconds)

Changed in version 0.2.2: This now returns the UTC day; previously it returned a Ticktock UTC object, but in the local timezone, which made all conversions incorrect.

Returns
outticktock

Ticktock object with the current UTC day

update_items(attrib)[source]

After changing the self.data attribute by either __setitem__ or __add__ etc this function will update all other attributes. This function is called automatically in __add__, __init__, and __setitem__.

Parameters
attribstr

attribute that was updated; update others from this

Other Parameters
clstype

Deprecated since version 0.2.2: Class is now taken from the self of the bound instance.

Class to use for finding possible attributes; now ignored.

See also

spacepy.Ticktock.__setitem__
spacepy.Ticktock.__add__
spacepy.Ticktock.__sub__