irfpy.util.utc

Module related to the universal time.

Code author: Yoshifumi Futaana

The module has functionalities of:

• conversion among many formats in the universal time

• production of regularly gridded time interval

Conversion This contais functionality of connverting among UTC-epoch, datetime, Julday, matlab time, and mpl time.

You may also be interested in Matplotlib’s package matplotlib.dates where several similar functions are defined.

Conversions

From To	String expression	UTC epoch	datetime.datetime	julday.Julday	matplotlib float	matlab float
String expression			dateutil.parser.parse()
UTC epoch			dateutime.datetime.fromtimestamp()
datetime.datetime	obj.strftime()	obj.timestamp()
julday.Julday
matplotlib float
matlab float

Todo

Fill in the table specifying the conversion of times.

Todo

Refactor the functions to coordinate the consistency in the function names for time conversion.

Regular gridding

• irfpy.util.utc.dtrange(): Return a list of equally-gridded datetime objects

• irfpy.util.utc.trange(): Return a generator of equally-gridded datetime objects

irfpy.util.utc.datestr2mplnum(string_date)

Date expression of string to maplotlib.dates float

It may be similar to matplotlib.dates.datestr2num() but when used in np.genfromtxt converter, the datestr2num fails due to the toordinary conversion exception.

>>> s = '2014-10-30T15:27:13.332'
>>> n1 = datestr2mplnum(s)
>>> print(n1)
735536.6439043055
>>> n2 = mpldates.datestr2num(s)
>>> print(n2)
735536.6439043055

irfpy.util.utc.dt2tt(dt)

Convert datetime object to epoch time

irfpy.util.utc.tt2dt(tt)

Convert epoch time to datetime instance

irfpy.util.utc.dt2jd(dt)

Convert datetime object to irfpy.util.julday.Julday object.

irfpy.util.utc.jd2dt(jd)

Convert irfpy.util.julday.Julday object to datetime.datetime object

irfpy.util.utc.tt2jd(tt)

irfpy.util.utc.jd2tt(jd)

irfpy.util.utc.mat2dt(matlabtime, remove_tz=True)

Convert matlab floating time to datetime.datetime instance.

Parameters

• matlabtime (float) – Matlab time.

• remove_tz (boolean) – Time zone (UTC) is removed if set True. Keep as it was if set False. num2data function add tzinfo as UTC, while most of the irfpy library does not. So by default, the information will be removed.

Matlab time is a float and similar to Julian day, but offset is different. Also matplotlib has different offset. Thus, this method will convert Matlab time to datatime.datetime instance.

To convert matplotlib time to datetime.datetime, you can use matplotlib.dates.num2date method.

Parameters

matlabtime – Matlab time

Returns

datetime.datetime

>>> from matplotlib.dates import num2date, date2num
>>> mattime = 733408  # corresponding to 2008-01-01 00:00:00
>>> pytime = mat2dt(mattime)
>>> print(pytime.strftime('%F %T'))
2008-01-01 00:00:00

>>> print(pytime.strftime('%F %T %Z').strip())
2008-01-01 00:00:00

>>> pytime2 = mat2dt(mattime, remove_tz=False)
>>> print(pytime2.strftime('%F %T %Z'))
2008-01-01 00:00:00 UTC

>>> mpltime = date2num(pytime)  # If you use matplotlib time, take care!
>>> print('%.1f' % mpltime)  # This is different from mattime by 366 days.
733042.0

irfpy.util.utc.dt2mat(dt)

Convert the datetime.datetime instance to matlab floating time.

Note that the function will return matlab time, not matplotlib time. They have a difference by 366.

>>> t = datetime.datetime(2006, 12, 2, 15, 30, 0)
>>> tmat = dt2mat(t)
>>> print(tmat)    
733013.645833...
>>> trev = mat2dt(tmat)
>>> print(trev)
2006-12-02 15:30:00

If you use date2num in matplotlib.dates module, you will get 366 day difference. This is matplotlib time. >>> print(date2num(t)) # doctest: +ELLIPSIS 732647.645833…

irfpy.util.utc.convert(intime, outfmt=<class 'float'>)

Convert between irfpy.util.julday.Julday, datetime.datetime, and time_t.

Parameters

• intime – Time in supported format.

• outfmt – Specify the format. irfpy.util.julday.Julday, datetime, and time_t(float) is supported. Default is time_t.

Supporeted time format is irfpy.util.julday.Julday, datetime.datetime and time_t (=float). Matplotlib’s number (also float) is NOT supported.

irfpy.util.utc.ymd2doy(year, month, day)

Convert the calendar time to day of year.

irfpy.util.utc.doy2ymd(year, doi)

Convert the day of year to the calendar day as a tuple of (month, day).

If the speicified doy does not exist for the specified year, ValueError is raised.

irfpy.util.utc.dtrange(t0, t1, dt)

Return the equally stepped datetime object.

Return the equally separated datatime objects between t0 and t1 (exclusive) with a step of dt.

Indeed, this is an alias to irfpy.util.timeseries.dtrange().

>>> t0 = datetime.datetime(2014, 10, 1)
>>> t1 = datetime.datetime(2014, 10, 10)
>>> dt = datetime.timedelta(hours=12)
>>> tlist = dtrange(t0, t1, dt)
>>> print(len(tlist))
18
>>> print(tlist[5])
2014-10-03 12:00:00
>>> print(tlist[-1])
2014-10-09 12:00:00

irfpy.util.utc.dtlinspace(t0, t1, ndiv)

Return the equally separated datetime objects.

Parameters

• t0 – Start time

• t1 – Stop time

• ndiv – Number of elements

Returns

A list of datetime object

irfpy.util.utc.trange(t0, t1, dt)

Generator of equally separated datetime object.

>>> t0 = datetime.datetime(2014, 1, 1)
>>> t1 = datetime.datetime(2014, 1, 3)
>>> dt = datetime.timedelta(hours=12)
>>> for t in trange(t0, t1, dt):
...     print(t)
2014-01-01 00:00:00
2014-01-01 12:00:00
2014-01-02 00:00:00
2014-01-02 12:00:00

Of course you can by enclosure.

>>> tlist = [t.strftime('%FT%T') for t in trange(t0, t1, dt)]
>>> print(tlist)
['2014-01-01T00:00:00', '2014-01-01T12:00:00', '2014-01-02T00:00:00', '2014-01-02T12:00:00']

irfpy.util.utc.doctests()