NEP 7 — 在NumPy中实现日期/时间类型的一项提案#

作者:

Travis Oliphant

联系方式:

oliphant@enthought.com

日期:

2009-06-09

状态:

最终

由以下人员在第三项提案基础上略作修订

作者:

Francesc Alted i Abad

联系方式:

faltet@pytables.com

作者:

Ivan Vilata i Balaguer

联系方式:

ivan@selidor.net

日期:

2008-07-30

执行摘要#

日期/时间标记在需要处理数据集的许多领域都非常有用。尽管Python有多个模块定义了日期/时间类型(例如集成的datetime [1]mx.DateTime [2]),但NumPy却缺乏这些类型。

我们提议添加日期/时间类型以填补这一空白。所提议类型的要求有两个方面:1) 它们必须操作快速;2) 它们必须尽可能与Python自带的现有datetime模块兼容。

提议的类型#

几乎不可能提出一个能够满足所有用例需求的单一日期/时间类型。因此,我们提出了两种通用的日期时间类型:1) timedelta64 – 相对时间,以及 2) datetime64 – 绝对时间。

这些时间中的每一个在内部都表示为64位有符号整数,它们指代一个特定的单位(小时、分钟、微秒等)。有几种预定义单位,并且能够创建这些单位的有理倍数。还支持一种表示形式,使得存储的日期时间整数既可以编码特定单位的数量,又可以编码每个单位跟踪的顺序事件数量。

datetime64表示一个绝对时间。在内部,它表示为目标时间与纪元(1970年1月1日午夜12:00 — POSIX时间,包括其不考虑闰秒的特点)之间的时间单位数量。

时间单位#

64位整数时间可以表示几种不同的基本单位以及派生单位。基本单位列在下表中

时间单位

时间跨度

时间跨度(年)

代码

含义

相对时间

绝对时间

Y

± 9.2e18 年

[公元前9.2e18年, 公元9.2e18年]

M

± 7.6e17 年

[公元前7.6e17年, 公元7.6e17年]

W

± 1.7e17 年

[公元前1.7e17年, 公元1.7e17年]

B

工作日

± 3.5e16 年

[公元前3.5e16年, 公元3.5e16年]

D

± 2.5e16 年

[公元前2.5e16年, 公元2.5e16年]

h

小时

± 1.0e15 年

[公元前1.0e15年, 公元1.0e15年]

m

分钟

± 1.7e13 年

[公元前1.7e13年, 公元1.7e13年]

s

± 2.9e12 年

[ 公元前2.9e9年, 公元2.9e9年]

ms

毫秒

± 2.9e9 年

[ 公元前2.9e6年, 公元2.9e6年]

us

微秒

± 2.9e6 年

[公元前290301年, 公元294241年]

ns

纳秒

± 292 年

[ 公元1678年, 公元2262年]

ps

皮秒

± 106 天

[ 公元1969年, 公元1970年]

fs

飞秒

± 2.6 小时

[ 公元1969年, 公元1970年]

as

阿秒

± 9.2 秒

[ 公元1969年, 公元1970年]

时间单位由一个字符串指定,该字符串由上表中给出的基本类型组成

除了这些基本代码单位,用户还可以创建由任何基本单位的倍数组成的派生单位:100ns、3M、15m等。

任何基本单位的有限次除法可用于创建更高分辨率单位的倍数,前提是除数可以被可用更高分辨率单位的数量整除。例如:Y/4只是->(12M)/4->3M的简写,并且Y/4在创建后将表示为3M。将选择第一个找到具有偶数除数的更低单位(最多3个更低单位)。在这种特定情况下,使用以下标准化定义来查找可接受的除数

代码

解释为

Y

12M, 52W, 365D

M

4W, 30D, 720h

W

5B, 7D, 168h, 10080m

B

24h, 1440m, 86400s

D

24h, 1440m, 86400s

h

60m, 3600s

m

60s, 60000ms

s, ms, us, ns, ps, fs(分别使用接下来的两个可用更低单位的1000和1000000)。

最后,可以创建一个支持在基本单位内跟踪顺序事件的日期时间数据类型:[D]//100, [Y]//4(注意所需的方括号)。这些取模事件单位为日期时间整数提供了以下解释

  • 除数是每个周期中的事件数量

  • (整数)商是表示基本单位的整数

  • 余数是该周期中的特定事件。

取模事件单位可以与任何派生单位结合,但需要方括号。例如 [100ns]//50,它允许每100ns记录50个事件,这样0表示第一个100ns刻度中的第一个事件,1表示第一个100ns刻度中的第二个事件,而50表示第二个100ns刻度中的第一个事件,51表示第二个100ns刻度中的第二个事件。

为了完整指定日期时间类型,时间单位字符串必须与datetime64(‘M8’)或timedelta64(‘m8’)的字符串结合使用方括号‘[]’。因此,表示日期时间dtype的完整指定字符串是‘M8[Y]’或(更复杂的例子)‘M8[7s/9]//5’。

如果未指定时间单位,则默认为[us]。因此,‘M8’等效于‘M8[us]’(除非需要取模事件单位——即您不能将‘M8[us]//5’指定为‘M8//5’或‘//5’)

datetime64#

此dtype表示一个绝对时间(即非相对时间)。它在内部实现为int64类型。该整数表示从内部POSIX纪元以来的单位(参见[3])。与POSIX一样,日期的表示不考虑闰秒。

在时间单位转换和时间表示中(但在其他时间计算中不适用),值-2**63 (0x8000000000000000) 被解释为无效或未知日期,即非时间NaT。有关更多信息,请参阅时间单位转换一节。

因此,一个绝对日期表示从纪元以来所选时间单位的整数个单位。如果整数是负数,则整数的绝对值表示在纪元之前的单位数量。在使用工作日时,周六和周日将从计数中简单忽略(即,工作日中的第3天不是1970年1月3日星期六,而是1970年1月5日星期一)。

构建datetime64 dtype#

在dtype构造函数中指定时间单位的建议方式是

使用长字符串表示法

dtype('datetime64[us]')

使用短字符串表示法

dtype('M8[us]')

如果未指定时间单位,则默认为[us]。因此,‘M8’等效于‘M8[us]’。

设置和获取值#

具有此dtype的对象可以通过多种方式设置

t = numpy.ones(3, dtype='M8[s]')
t[0] = 1199164176    # assign to July 30th, 2008 at 17:31:00
t[1] = datetime.datetime(2008, 7, 30, 17, 31, 01) # with datetime module
t[2] = '2008-07-30T17:31:02'    # with ISO 8601

也可以通过不同的方式获取

str(t[0])  -->  2008-07-30T17:31:00
repr(t[1]) -->  datetime64(1199164177, 's')
str(t[0].item()) --> 2008-07-30 17:31:00  # datetime module object
repr(t[0].item()) --> datetime.datetime(2008, 7, 30, 17, 31)  # idem
str(t)  -->  [2008-07-30T17:31:00  2008-07-30T17:31:01  2008-07-30T17:31:02]
repr(t)  -->  array([1199164176, 1199164177, 1199164178],
                    dtype='datetime64[s]')

比较#

比较也将被支持

numpy.array(['1980'], 'M8[Y]') == numpy.array(['1979'], 'M8[Y]')
--> [False]

包括应用广播

numpy.array(['1979', '1980'], 'M8[Y]') == numpy.datetime64('1980', 'Y')
--> [False, True]

以下也应该有效

numpy.array(['1979', '1980'], 'M8[Y]') == '1980-01-01'
--> [False, True]

因为右侧表达式可以广播成一个包含2个dtype为‘M8[Y]’元素的数组。

兼容性问题#

只有在使用微秒作为时间单位时,这将与Python datetime模块的datetime类完全兼容。对于其他时间单位,转换过程将根据需要损失精度或发生溢出。从/到datetime对象的转换不考虑闰秒。

timedelta64#

它表示一个相对时间(即非绝对时间)。它在内部实现为int64类型。

在时间单位转换和时间表示中(但在其他时间计算中不适用),值-2**63 (0x8000000000000000) 被解释为无效或未知时间,即非时间NaT。有关更多信息,请参阅时间单位转换一节。

时间差的值是所选时间单位的整数个单位

构建timedelta64 dtype#

在dtype构造函数中指定时间单位的建议方式是

使用长字符串表示法

dtype('timedelta64[us]')

使用短字符串表示法

dtype('m8[us]')

如果未指定时间单位,则假定默认为[us]。因此,‘m8’和‘m8[us]’是等效的。

设置和获取值#

具有此dtype的对象可以通过多种方式设置

t = numpy.ones(3, dtype='m8[ms]')
t[0] = 12    # assign to 12 ms
t[1] = datetime.timedelta(0, 0, 13000)   # 13 ms
t[2] = '0:00:00.014'    # 14 ms

也可以通过不同的方式获取

str(t[0])  -->  0:00:00.012
repr(t[1]) -->  timedelta64(13, 'ms')
str(t[0].item()) --> 0:00:00.012000   # datetime module object
repr(t[0].item()) --> datetime.timedelta(0, 0, 12000)  # idem
str(t)     -->  [0:00:00.012  0:00:00.014  0:00:00.014]
repr(t)    -->  array([12, 13, 14], dtype="timedelta64[ms]")

比较#

比较也将被支持

numpy.array([12, 13, 14], 'm8[ms]') == numpy.array([12, 13, 13], 'm8[ms]')
--> [True, True, False]

或通过应用广播

numpy.array([12, 13, 14], 'm8[ms]') == numpy.timedelta64(13, 'ms')
--> [False, True, False]

以下也应该有效

numpy.array([12, 13, 14], 'm8[ms]') == '0:00:00.012'
--> [True, False, False]

因为右侧表达式可以广播成一个包含3个dtype为‘m8[ms]’元素的数组。

兼容性问题#

只有在使用微秒作为时间单位时,这将与Python datetime模块的timedelta类完全兼容。对于其他单位,转换过程将根据需要损失精度或发生溢出。

使用示例#

以下是datetime64的使用示例

In [5]: numpy.datetime64(42, 'us')
Out[5]: datetime64(42, 'us')

In [6]: print numpy.datetime64(42, 'us')
1970-01-01T00:00:00.000042  # representation in ISO 8601 format

In [7]: print numpy.datetime64(367.7, 'D')  # decimal part is lost
1971-01-02  # still ISO 8601 format

In [8]: numpy.datetime('2008-07-18T12:23:18', 'm')  # from ISO 8601
Out[8]: datetime64(20273063, 'm')

In [9]: print numpy.datetime('2008-07-18T12:23:18', 'm')
Out[9]: 2008-07-18T12:23

In [10]: t = numpy.zeros(5, dtype="datetime64[ms]")

In [11]: t[0] = datetime.datetime.now()  # setter in action

In [12]: print t
[2008-07-16T13:39:25.315  1970-01-01T00:00:00.000
 1970-01-01T00:00:00.000  1970-01-01T00:00:00.000
 1970-01-01T00:00:00.000]

In [13]: repr(t)
Out[13]: array([267859210457, 0, 0, 0, 0], dtype="datetime64[ms]")

In [14]: t[0].item()     # getter in action
Out[14]: datetime.datetime(2008, 7, 16, 13, 39, 25, 315000)

In [15]: print t.dtype
dtype('datetime64[ms]')

以下是timedelta64的使用示例

In [5]: numpy.timedelta64(10, 'us')
Out[5]: timedelta64(10, 'us')

In [6]: print numpy.timedelta64(10, 'us')
0:00:00.000010

In [7]: print numpy.timedelta64(3600.2, 'm')  # decimal part is lost
2 days, 12:00

In [8]: t1 = numpy.zeros(5, dtype="datetime64[ms]")

In [9]: t2 = numpy.ones(5, dtype="datetime64[ms]")

In [10]: t = t2 - t1

In [11]: t[0] = datetime.timedelta(0, 24)  # setter in action

In [12]: print t
[0:00:24.000  0:00:01.000  0:00:01.000  0:00:01.000  0:00:01.000]

In [13]: print repr(t)
Out[13]: array([24000, 1, 1, 1, 1], dtype="timedelta64[ms]")

In [14]: t[0].item()     # getter in action
Out[14]: datetime.timedelta(0, 24)

In [15]: print t.dtype
dtype('timedelta64[s]')

使用日期/时间数组进行操作#

datetime64对比datetime64#

绝对日期之间唯一允许的算术运算是减法

In [10]: numpy.ones(3, "M8[s]") - numpy.zeros(3, "M8[s]")
Out[10]: array([1, 1, 1], dtype=timedelta64[s])

但不允许其他操作

In [11]: numpy.ones(3, "M8[s]") + numpy.zeros(3, "M8[s]")
TypeError: unsupported operand type(s) for +: 'numpy.ndarray' and 'numpy.ndarray'

允许绝对日期之间的比较。

转换规则#

当对具有不同时间单位的两个绝对时间进行操作时(基本上,只允许减法),结果将是引发异常。这是因为不同时间单位的范围和时间跨度可能差异很大,而且完全不清楚用户会偏好哪种时间单位。例如,以下操作应该允许

>>> numpy.ones(3, dtype="M8[Y]") - numpy.zeros(3, dtype="M8[Y]")
array([1, 1, 1], dtype="timedelta64[Y]")

但下一个不应该

>>> numpy.ones(3, dtype="M8[Y]") - numpy.zeros(3, dtype="M8[ns]")
raise numpy.IncompatibleUnitError  # what unit to choose?

datetime64对比timedelta64#

将可以从绝对日期中添加和减去相对时间

In [10]: numpy.zeros(5, "M8[Y]") + numpy.ones(5, "m8[Y]")
Out[10]: array([1971, 1971, 1971, 1971, 1971], dtype=datetime64[Y])

In [11]: numpy.ones(5, "M8[Y]") - 2 * numpy.ones(5, "m8[Y]")
Out[11]: array([1969, 1969, 1969, 1969, 1969], dtype=datetime64[Y])

但不允许其他操作

In [12]: numpy.ones(5, "M8[Y]") * numpy.ones(5, "m8[Y]")
TypeError: unsupported operand type(s) for *: 'numpy.ndarray' and 'numpy.ndarray'

转换规则#

在这种情况下,绝对时间应优先确定结果的时间单位。这代表了大多数时候人们想要做的事情。例如,这将允许执行以下操作

>>> series = numpy.array(['1970-01-01', '1970-02-01', '1970-09-01'],
dtype='datetime64[D]')
>>> series2 = series + numpy.timedelta(1, 'Y')  # Add 2 relative years
>>> series2
array(['1972-01-01', '1972-02-01', '1972-09-01'],
dtype='datetime64[D]')  # the 'D'ay time unit has been chosen

timedelta64对比timedelta64#

最后,将可能像操作常规int64 dtype一样操作相对时间,只要结果可以转换回timedelta64

In [10]: numpy.ones(3, 'm8[us]')
Out[10]: array([1, 1, 1], dtype="timedelta64[us]")

In [11]: (numpy.ones(3, 'm8[M]') + 2) ** 3
Out[11]: array([27, 27, 27], dtype="timedelta64[M]")

但是

In [12]: numpy.ones(5, 'm8') + 1j
TypeError: the result cannot be converted into a ``timedelta64``

转换规则#

当结合两个具有不同时间单位的timedelta64 dtype时,结果将是两者中较短的时间单位(“保持精度”规则)。例如

In [10]: numpy.ones(3, 'm8[s]') + numpy.ones(3, 'm8[m]')
Out[10]: array([61, 61, 61],  dtype="timedelta64[s]")

然而,由于无法知道相对年份或相对月份的确切持续时间,当这些时间单位出现在其中一个操作数中时,操作将不被允许

In [11]: numpy.ones(3, 'm8[Y]') + numpy.ones(3, 'm8[D]')
raise numpy.IncompatibleUnitError  # how to convert relative years to days?

为了能够执行上述操作,提出一个新的NumPy函数,名为change_timeunit。其签名将是

change_timeunit(time_object, new_unit, reference)

其中‘time_object’是要更改单位的时间对象,‘new_unit’是所需的新时间单位,‘reference’是一个绝对日期(NumPy datetime64标量),将用于在时间单位包含不确定数量的更小时间单位(例如相对年或月无法用天数表示)的情况下允许相对时间的转换。

有了它,上述操作可以如下进行

In [10]: t_years = numpy.ones(3, 'm8[Y]')

In [11]: t_days = numpy.change_timeunit(t_years, 'D', '2001-01-01')

In [12]: t_days + numpy.ones(3, 'm8[D]')
Out[12]: array([366, 366, 366],  dtype="timedelta64[D]")

dtype与时间单位转换#

为了改变现有数组的日期/时间dtype,我们建议使用.astype()方法。这主要用于改变时间单位。

例如,对于绝对日期

In[10]: t1 = numpy.zeros(5, dtype="datetime64[s]")

In[11]: print t1
[1970-01-01T00:00:00  1970-01-01T00:00:00  1970-01-01T00:00:00
 1970-01-01T00:00:00  1970-01-01T00:00:00]

In[12]: print t1.astype('datetime64[D]')
[1970-01-01  1970-01-01  1970-01-01  1970-01-01  1970-01-01]

对于相对时间

In[10]: t1 = numpy.ones(5, dtype="timedelta64[s]")

In[11]: print t1
[1 1 1 1 1]

In[12]: print t1.astype('timedelta64[ms]')
[1000 1000 1000 1000 1000]

不支持直接在相对和绝对dtype之间进行转换

In[13]: numpy.zeros(5, dtype="datetime64[s]").astype('timedelta64')
TypeError: data type cannot be converted to the desired type

工作日具有特殊性,它们不覆盖连续的时间线(周末有间隔)。因此,当从任何普通时间转换为工作日时,可能出现原始时间无法表示的情况。在这种情况下,转换结果为非时间NaT

In[10]: t1 = numpy.arange(5, dtype="datetime64[D]")

In[11]: print t1
[1970-01-01  1970-01-02  1970-01-03  1970-01-04  1970-01-05]

In[12]: t2 = t1.astype("datetime64[B]")

In[13]: print t2  # 1970 begins in a Thursday
[1970-01-01  1970-01-02  NaT  NaT  1970-01-05]

当转换回普通日期时,NaT值保持不变(所有时间单位转换中都会发生这种情况)

In[14]: t3 = t2.astype("datetime64[D]")

In[13]: print t3
[1970-01-01  1970-01-02  NaT  NaT  1970-01-05]

对NumPy的必要更改#

为了便于添加日期时间数据类型,对NumPy进行了一些更改

向dtype添加元数据#

所有数据类型现在都有一个元数据字典。它可以在对象构造期间使用metadata关键字进行设置。

日期时间数据类型将在元数据字典中放置“__frequency__”键,其中包含一个带有以下参数的4元组。

(基本单位字符串(str),

倍数(int),子分区数(int),事件数(int))。

因此,像表示天数的‘D’这样的简单时间单位将通过元数据中“__frequency__”键的(‘D’, 1, 1, 1)来指定。更复杂的时间单位(例如‘[2W/5]//50’)将通过(‘D’, 2, 5, 50)来表示。

“__frequency__”键保留用于元数据,不能通过dtype构造函数设置。

Ufunc接口扩展#

具有datetime和timedelta参数的ufunc可以在ufunc调用期间使用Python API(以引发错误)。

有一个新的ufunc C-API调用,用于将特定函数指针(针对特定数据类型集)的数据设置为传递给ufunc的数组列表。

数组接口扩展#

数组接口已扩展,可以处理datetime和timedelta typestr(包括扩展表示法)。

此外,只要版本字符串为4,__array_interface__的typestr元素就可以是元组。该元组是(‘typestr’,元数据字典)。

对typestr概念的此扩展延伸到__array_interface__的descr部分。因此,描述数据格式的元组列表中的第二个元组元素本身可以是(‘typestr’,元数据字典)的元组。

最终考量#

为什么会有分数时间与事件:[3Y/12]//50#

很难想出足够的单位来满足所有需求。例如,在Windows上的C#中,基本时间刻度是100ns。基本单位的倍数很容易处理。基本单位的除数更难任意处理,但通常会将一个月视为一年的1/12,或将一天视为一周的1/7。因此,实现了以“更大”单位的分数形式指定单位的能力。

添加事件概念(//50)是为了解决本NEP一位商业赞助商的用例。其思想是允许时间戳同时携带事件编号和时间戳信息。余数携带事件编号信息,而商携带时间戳信息。

为什么origin元数据消失了#

在NumPy邮件列表中讨论日期/时间dtype时,最初认为拥有一个补充绝对datetime64定义的origin元数据很有用。

然而,经过进一步思考,我们发现绝对datetime64与相对timedelta64的组合提供了相同的功能,同时消除了对额外origin元数据的需求。这就是我们将其从本提案中移除的原因。

混合时间单位的操作#

只要接受相同dtype和相同单位的两个时间值之间的操作,那么不同单位的时间值之间的相同操作也应可能(例如,添加一个以秒计的时间差和一个以微秒计的时间差),从而得到一个合适的时间单位。此类操作的确切语义在“使用日期/时间数组进行操作”部分的“转换规则”小节中定义。

由于工作日的特殊性,混合工作日与其他时间单位的操作很可能不被允许。