spacepy_logo

Table Of Contents

Previous topic

spacepy.seapy.sea_signif

This Page

time - Time conversion, manipulation and implementation of Ticktock class

Time conversion, manipulation and implementation of Ticktock class

Examples:

>>> import spacepy.time as spt
>>> import datetime as dt

Day of year calculations

>>> dts = spt.doy2date([2002]*4, range(186,190), dtobj=True)
>>> dts
[datetime.datetime(2002, 7, 5, 0, 0),
datetime.datetime(2002, 7, 6, 0, 0),
datetime.datetime(2002, 7, 7, 0, 0),
datetime.datetime(2002, 7, 8, 0, 0)]
>>> dts = spt.Ticktock(dts,'UTC')
>>> dts.DOY
array([ 186.,  187.,  188.,  189.])

Ticktock object creation

>>> isodates = ['2009-12-01T12:00:00', '2009-12-04T00:00:00', '2009-12-06T12:00:00']
>>> dts = spt.Ticktock(isodates, 'ISO')

OR

>>> dtdates = [dt.datetime(2009,12,1,12), dt.datetime(2009,12,4), dt.datetime(2009,12,6,12)]
>>> dts = spt.Ticktock(dtdates, 'UTC')

ISO time formatting

>>> dts = spt.tickrange('2009-12-01T12:00:00','2009-12-06T12:00:00',2.5)

OR

>>> dts = spt.tickrange(dt.datetime(2009,12,1,12),dt.datetime(2009,12,6,12),     dt.timedelta(days=2, hours=12))
>>> dts
Ticktock( ['2009-12-01T12:00:00', '2009-12-04T00:00:00', '2009-12-06T12:00:00'] ), dtype=ISO
>>> dts.isoformat()
Current ISO output format is %Y-%m-%dT%H:%M:%S
Options are: [('seconds', '%Y-%m-%dT%H:%M:%S'), ('microseconds', '%Y-%m-%dT%H:%M:%S.%f')]
>>> dts.isoformat('microseconds')
>>> dts.ISO
['2009-12-01T12:00:00.000000',
 '2009-12-04T00:00:00.000000',
 '2009-12-06T12:00:00.000000']

Time manipulation

>>> new_dts = dts + tdelt
>>> new_dts.UTC
[datetime.datetime(2009, 12, 2, 18, 0),
 datetime.datetime(2009, 12, 5, 6, 0),
 datetime.datetime(2009, 12, 7, 18, 0)]

Other time formats

>>> dts.RDT  # Gregorian ordinal time
array([ 733742.5,  733745. ,  733747.5])
>>> dts.GPS # GPS time
array([  9.43704015e+08,   9.43920015e+08,   9.44136015e+08])
>>> dts.JD # Julian day
array([ 2455167. ,  2455169.5,  2455172. ])

And so on.

Authors: Josef Koller, Brian Larsen, Steve Morley, Jon Niehof Institution: Los Alamos National Laboratory Contact: jkoller@lanl.gov,

Copyright 2010 Los Alamos National Security, LLC.

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

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

Possible 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 (all days have 86400 secs sometimes unequal lenghts) JD: Julian days elapsed MJD: Modified Julian days RDT: Rata Die days elapsed since 1/1/1 CDF: CDF epoch: milliseconds since 1/1/0000

Parameters :

data : array_like (int, datetime, float, string)

time stamp

dtype : string {CDF, ISO, UTC, TAI, UNX, JD, MJD, RDT}

data type for data

Returns :

out : Ticktock

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

Examples

>>> x=Ticktock([2452331.0142361112, 2452332.0142361112], 'JD')
>>> x.ISO
['2002-02-25T12:20:30', '2002-02-26T12:20:30']
>>> x.DOY # Day of year
array([ 56.,  57.])
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
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
now() Creates a Ticktock object with the current time, equivalent to datetime.now()
sort() This will sort the Ticktock values in place
update_items(b, 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 :

other : Ticktock

other (Ticktock instance)

argsort()[source]

This will return the indices that would sort the Ticktock values

Returns :

out : list

indices that would sort the Ticktock values

convert(dtype)[source]

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

Parameters :

dtype : string

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

Returns :

out : Ticktock

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
getCDF()[source]

a.getCDF() or a.CDF

Return CDF time which is milliseconds since 01-Jan-0000 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. Remember that 1 BC was a leap year. The CDF date/time calculations do not take into account the changes to the Gregorian calendar, and cannot be directly converted into Julian date/times.

Returns :

out : numpy array

days elapsed since Jan. 1st

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)

Returns :

out : numpy 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 GPS epoch (0000 UT (midnight) on January 6, 1980)

Returns :

out : numpy array

elapsed secs since 6Jan1980 (excludes leap secs)

Examples

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

a.ISO or a.getISO()

convert dtype data into ISO string

Returns :

out : list 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 :

out : numpy array

elapsed days since 12:00 January 1, 4713 BC

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 :

out : numpy array

elapsed days since November 17, 1858 (Julian date was 2,400 000)

Examples

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

a.RDT or a.RDT()

convert dtype data into Rata Die (lat.) Time (days since 1/1/0001)

Returns :

out : numpy array

elapsed days since 1/1/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)

Returns :

out : numpy array

elapsed secs since 1958/1/1 (includes leap secs, i.e. all secs have equal lengths)

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-Jan-1 (not counting leap seconds)

Returns :

out : numpy 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()

Returns :

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

Returns :

out : numpy 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

Returns :

out : numpy 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 :fmt : string, optional
classmethod now()[source]

Creates a Ticktock object with the current time, equivalent to datetime.now()

Returns :

out : ticktock

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

sort()[source]

This will sort the Ticktock values in place

update_items(b, 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__ and __setitem__

Parameters :

cls : Ticktock

attrib : string

attribute to update

See also

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

append(other)[source]

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

Parameters :

other : Ticktock

other (Ticktock instance)

argsort()[source]

This will return the indices that would sort the Ticktock values

Returns :

out : list

indices that would sort the Ticktock values

convert(dtype)[source]

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

Parameters :

dtype : string

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

Returns :

out : Ticktock

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
getCDF()[source]

a.getCDF() or a.CDF

Return CDF time which is milliseconds since 01-Jan-0000 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. Remember that 1 BC was a leap year. The CDF date/time calculations do not take into account the changes to the Gregorian calendar, and cannot be directly converted into Julian date/times.

Returns :

out : numpy array

days elapsed since Jan. 1st

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)

Returns :

out : numpy 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 GPS epoch (0000 UT (midnight) on January 6, 1980)

Returns :

out : numpy array

elapsed secs since 6Jan1980 (excludes leap secs)

Examples

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

a.ISO or a.getISO()

convert dtype data into ISO string

Returns :

out : list 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 :

out : numpy array

elapsed days since 12:00 January 1, 4713 BC

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 :

out : numpy array

elapsed days since November 17, 1858 (Julian date was 2,400 000)

Examples

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

a.RDT or a.RDT()

convert dtype data into Rata Die (lat.) Time (days since 1/1/0001)

Returns :

out : numpy array

elapsed days since 1/1/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)

Returns :

out : numpy array

elapsed secs since 1958/1/1 (includes leap secs, i.e. all secs have equal lengths)

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-Jan-1 (not counting leap seconds)

Returns :

out : numpy 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()

Returns :

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

Returns :

out : numpy 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

Returns :

out : numpy array

leap seconds

See also

getTAI

Examples

>>> a = Ticktock('2002-02-02T12:00:00', 'ISO')
>>> a.leaps
array([32])
insert(idx, val, dtype=None)[source]

insert values into the TickTock object

Note

If more than one value to insert a slice must be specified

as the index. See numpy.insert

Parameters :

idx : int, slice or sequence of ints

Object that defines the index or indices before which val is inserted.

val : array_like

values to insert

dtype : str (optional)

must be specified if not CDF, ISO, or UTC

isoformat(b, attrib)[source]

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

Parameters :fmt : string, optional
classmethod now()[source]

Creates a Ticktock object with the current time, equivalent to datetime.now()

Returns :

out : ticktock

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

remove(idx)[source]

This will remove the Ticktock value at index idx

sort()[source]

This will sort the Ticktock values in place

update_items(b, 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__ and __setitem__

Parameters :

cls : Ticktock

attrib : string

attribute to update

See also

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

spacepy.time.doy2date(year, doy, dtobj=False, flAns=False)[source]

convert integer day-of-year doy into a month and day after http://pleac.sourceforge.net/pleac_python/datesandtimes.html

Parameters :

year : int or array of int

year

doy : int or array of int

day of year

Returns :

month : int or array of int

month as integer number

day : int or array of int

as integer number

See also

Ticktock.getDOY

Examples

>>> month, day = doy2date(2002, 186)
>>> dts = doy2date([2002]*4, range(186,190), dtobj=True)
spacepy.time.extract_YYYYMMDD(filename)[source]

go through a string and extract the first valid YYYYMMDD as a datetime

Parameters :

filename : str

string to parse for a YYYYMMDD format

Returns :

out : (None, datetime.datetime)

the datetime found in the string or None

spacepy.time.leapyear(year, numdays=False)[source]

return an array of boolean leap year, a lot faster than the mod method that is normally seen

Parameters :

year : array_like

array of years

numdays : boolean (optional)

optionally return the number of days in the year

Returns :

out : numpy array

an array of boolean leap year, or array of number of days

Examples

>>> import numpy
>>> import spacepy.time
>>> spacepy.time.leapyear(numpy.arange(15)+1998)
[False, False,  True, False, False, False,  True, False, False,
      False,  True, False, False, False,  True]
spacepy.time.no_tzinfo(dt)[source]

take in an arraylike of datetime objects and return them without any tzinfo

Parameters :

dt : iterable

iterable of datetime.datetime objects

Returns :

out : list

list of datetime.datetime without tzinfo

spacepy.time.randomDate(dt1, dt2, N=1, tzinfo=False, sorted=False)[source]

Return a (or many) random datetimes between two given dates, this is done under the convention dt <=1 rand < dt2

Parameters :

dt1 : datetime.datetime

start date for the the random date

dt2 : datetime.datetime

stop date for the the random date

Returns :

out : datetime.datetime or numpy.ndarray of datetime.datetime

the new time for the next call to EventTimer

Other Parameters:
 

N : int (optional)

the number of random dates to generate (defualt=1)

tzinfo : bool (optional)

maintain the tzinfo of the input datetimes (default=False)

sorted : bool (optional)

return the times sorted (default=False)

spacepy.time.sec2hms(sec, rounding=True, days=False, dtobj=False)[source]

Convert seconds of day to hours, minutes, seconds

Parameters :

sec : float

Seconds of day

Returns :

out : [hours, minutes, seconds] or datetime.timedelta

Other Parameters:
 

rounding : boolean

set for integer seconds

days : boolean

set to wrap around day (i.e. modulo 86400)

dtobj : boolean

set to return a timedelta object

spacepy.time.tickrange(start, end, deltadays, dtype='UTC')[source]

return a Ticktock range given the start, end, and delta

Parameters :

start : string or number

start time

end : string or number

end time (inclusive)

deltadays : float or timedelta

step in units of days (float); or datetime timedelta object

dtype : string (optional)

data type for start, end; e.g. ISO, UTC, RTD, etc. see Ticktock for all options

Returns :

out : Ticktock instance

ticks

See also

Ticktock

Examples

>>> ticks = st.tickrange('2002-02-01T00:00:00', '2002-02-10T00:00:00', deltadays = 1)
>>> ticks
Ticktock( ['2002-02-01T00:00:00', '2002-02-02T00:00:00', '2002-02-03T00:00:00',
'2002-02-04T00:00:00'] , dtype=ISO)
spacepy.time.valid_YYYYMMDD(inval)[source]

if inval is valid YYYYMMDD return True, False otherwise

Classes

Tickdelta
Ticktock(data, dtype) Ticktock class holding various time coordinate systems

Functions

date2num
doy2date(year, doy[, dtobj, flAns]) convert integer day-of-year doy into a month and day
leapyear(year[, numdays]) return an array of boolean leap year,
num2date
randomDate(dt1, dt2[, N, tzinfo, sorted]) Return a (or many) random datetimes between two given dates, this is done under the convention dt <=1 rand < dt2
sec2hms(sec[, rounding, days, dtobj]) Convert seconds of day to hours, minutes, seconds
tickrange(start, end, deltadays[, dtype]) return a Ticktock range given the start, end, and delta