spacepy.time.Ticktock¶

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

Ticktock class holding various time coordinate systems (TAI, UTC, ISO, JD, MJD, GPS, 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)
GPS: Elapsed seconds since 1980-1-6 (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.

Parameters:

dataarray_like (int, datetime, float, string): time stamp
dtypestring {CDF, ISO, UTC, TAI, ‘GPS’, 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'.

See also

datetime.datetime.strptime, isoformat

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’.

See also

argsort, numpy.argsort

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

See also

getUTC, getUNX, getRDT, getJD, getMJD, getCDF, getISO, getDOY, geteDOY
getGPS

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.

See also

getUTC
getUNX
getRDT
getJD
getMJD
getISO
getTAI
getDOY
geteDOY
getAPT

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

See also

getUTC
getUNX
getRDT
getJD
getMJD
getISO
getTAI
getDOY
geteDOY
getAPT

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.

See also

getUTC, getUNX, getRDT, getJD, getMJD, getCDF, getISO, getDOY, geteDOY
getAPT

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

See also

getUTC, getUNX, getRDT, getJD, getMJD, getCDF, getTAI, getDOY, geteDOY
getAPT

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

See also

getUTC
getUNX
getRDT
getJD
getMJD
getISO
getTAI
getDOY
geteDOY
getAPT

Notes

This is based on the UTC day, defined as JD(UTC), 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)

See also

getUTC, getUNX, getRDT, getJD, getISO, getCDF, getTAI, getDOY, geteDOY
getAPT

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.

See also

getUTC, getUNX, getISO, getJD, getMJD, getCDF, getTAI, getDOY, geteDOY
getAPT

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

If data was provided in TAI, returns data.

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

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.

See also

getUTC, getUNX, getRDT, getJD, getMJD, getCDF, getISO, getDOY, geteDOY
getAPT

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)

See also

getUTC, getISO, getRDT, getJD, getMJD, getCDF, getTAI, getDOY, geteDOY
getAPT

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

If data was provided in UTC, returns data.

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

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

See also

getISO, getUNX, getRDT, getJD, getMJD, getCDF, getTAI, getDOY, geteDOY
getAPT

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

See also

getUTC
getUNX
getRDT
getJD
getMJD
getISO
getTAI
getDOY
geteDOY
getAPT

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()

See also

datetime.datetime.now, datetime.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’.

See also

argsort, numpy.argsort

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

See also

datetime.date.today

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

See also

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

Previous topic

Next topic

This Page

spacepy.time.Ticktock¶