spacepy.time

Time conversion, manipulation and implementation of Ticktock class

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

For additional documentation time - Time conversion, manipulation and implementation of Ticktock class

Copyright 2010 Los Alamos National Security, LLC.

Functions

doy2date(year, doy[, dtobj, flAns])	convert integer day-of-year doy into a month and day after http://pleac.sourceforge.net/pleac_python/datesandtimes.html
dtstr2iso(dtstr[, fmt])	Convert a datetime string to a standard format
extract_YYYYMMDD(filename)	go through a string and extract the first valid YYYYMMDD as a datetime
leapyear(year[, numdays])	return an array of boolean leap year, a lot faster than the mod method that is normally seen
no_tzinfo(dt)	take in an arraylike of datetime objects and return them without any tzinfo
randomDate(dt1, dt2[, N, tzinfo, sorted])	Return a (or many) random datetimes between two given dates
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
valid_YYYYMMDD(inval)	if inval is valid YYYYMMDD return True, False otherwise

Classes

Ticktock(data, dtype)

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

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

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

Parameters:

yearint or array of int

year

doyint or array of int

day of year

Returns:

monthint or array of int

month as integer number

dayint 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.dtstr2iso(dtstr, fmt='%Y-%m-%dT%H:%M:%S')

Convert a datetime string to a standard format

Attempts to maintain leap second representation while converting time strings to the specified format (by default, ISO8601-like.) Only handles a single positive leap second; negative leap seconds require no special handling and policy is for UTC-UT1 not to exceed 0.9.

Parameters:

dtstrsequence of str

Date + time representation, format is fairly open.

Returns:

isostrarray of str

Representation of dtstr formatted according to fmt. Always a new sequence even if contents are identical to dtstr.

UTCarray of datetime.datetime

The closest-possible rendering of UTC time before or equal to dtstr.

offsetarray of int

Amount (in microseconds) to add to UTC to get the real time.

Other Parameters:

fmtstr, optional

Format appropriate for strftime() for rendering the output time.

spacepy.time.extract_YYYYMMDD(filename)

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

Parameters:

filenamestr

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)

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

Parameters:

yeararray_like

array of years

numdaysboolean (optional)

optionally return the number of days in the year

Returns:

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

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

Parameters:

dtiterable

iterable of datetime.datetime objects

Returns:

outlist

list of datetime.datetime without tzinfo

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

Return a (or many) random datetimes between two given dates

Convention used is dt1 <= rand < dt2. Leap second times will not be returned.

Parameters:

dt1datetime.datetime

start date for the the random date

dt2datetime.datetime

stop date for the the random date

Returns:

outdatetime.datetime or numpy.ndarray of datetime.datetime

the new time for the next call to EventTimer

Other Parameters:

Nint (optional)

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

tzinfobool (optional)

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

sortedbool (optional)

return the times sorted (default=False)

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

Convert seconds of day to hours, minutes, seconds

Parameters:

secfloat

Seconds of day

Returns:

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

Other Parameters:

roundingboolean

set for integer seconds

daysboolean

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

dtobjboolean

set to return a timedelta object

spacepy.time.tickrange(start, end, deltadays, dtype=None)

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

Parameters:

startstring or number

start time (ISO standard string and UTC/datetime do not require a dtype)

endstring or number

last possible time in series (excluded unless end=start+n*step for integer n)

deltadaysfloat or timedelta

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

dtypestring (optional)

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

Returns:

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

if inval is valid YYYYMMDD return True, False otherwise