irfpy.util.utc

Universal time related module.

Code author: Yoshifumi Futaana

Warning

Version 3.3.0 of matplotlib changed the num2date functionality in a backward incompatible way.

https://matplotlib.org/3.3.1/api/dates_api.html

This influence the time handling in this module.

Upgrade irfpy.util to v4.6 or higher.

pip install --find-links=https://irfpy.irf.se/sdist irfpy.util -U

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, and matlab 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.num2date(number)

Convert the days from the epoch to the datetime object.

The epoch is always 0001-01-01 (January 1st, year 1 AD), and the number is in days, but with 1 added.

Note that the epoch in matplotlib’s num2date is configurable after v3.3.0. This method can be used regardless of the setting.

Parameters:

number – Days after the epoch (0001-01-01). It should be 1 or more.

Returns:

The datetime.datetime object corresponding to the number

>>> print(num2date(1))
0001-01-01 00:00:00+00:00

irfpy.util.utc.date2num(dt)

Convert the days from the epoch to the datetime object.

The epoch is always 0001-01-01 (January 1st, year 1 AD), and the number is in days, but with 1 added.

Note that the epoch in matplotlib’s num2date is configurable after v3.3.0. This method can be used regardless of the setting.

Parameters:

• dt – The datetime.datetime object

• number – Days after the epoch (0001-01-01) plus 1. It should be 1 or more.

>>> print(date2num(datetime.datetime(1, 1, 1)))
1.0
>>> t = datetime.datetime(2006, 12, 2, 15, 30, 0)
>>> print(date2num(t))  
732647.6458...
>>> print(num2date(date2num(t)))
2006-12-02 15:30:00+00:00

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.

Warning

After v3.3.0 of Matplotlib, the matplotlib epoch was changed and configurable.

The example below is for pre-3.3.0 Matplotlib behavior.

>>> 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 the UNIX epoch time

>>> dt2tt(datetime.datetime(1970, 1, 1))
0.0

irfpy.util.utc.tt2dt(tt)

Convert the UNIX epoch time to datetime instance

>>> print(tt2dt(0.0))
1970-01-01 00:00:00

irfpy.util.utc.dt2jd(dt)

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

>>> jd = dt2jd(datetime.datetime(1970, 1, 1))
>>> print(jd)
 2440587.50000(1970-01-01T00:00:00.000)

irfpy.util.utc.jd2dt(jd)

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

>>> from irfpy.util import julday
>>> jd = julday.Julday(1970, 1, 1, 0, 0, 0.0)
>>> print(jd)
 2440587.50000(1970-01-01T00:00:00.000)
>>> print(jd2dt(jd))
1970-01-01 00:00:00

irfpy.util.utc.tt2jd(tt)

Convert the UNIX epoch time to Julius day

>>> print(tt2jd(0))
 2440587.50000(1970-01-01T00:00:00.000)

irfpy.util.utc.jd2tt(jd)

Convert the julian day to UNIX epoch time

>>> from irfpy.util import julday
>>> jd = julday.Julday(1970, 1, 1, 0, 0, 0.0)
>>> print(jd)
 2440587.50000(1970-01-01T00:00:00.000)
>>> print(jd2tt(jd))
0.0

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 irfpy.util.utc 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.round_sec(t)

Return the rounded time to the resolution of second.

>>> t = datetime.datetime(2010, 3, 10, 5, 10, 25, 499999)
>>> print(round_sec(t))
2010-03-10 05:10:25
>>> t = datetime.datetime(2010, 3, 10, 5, 10, 25, 500000)
>>> print(round_sec(t))
2010-03-10 05:10:26