Datetimes and Timedeltas

版本1.7.0中的新功能。

从NumPy 1.7开始,有核心数组数据类型本身支持日期时间功能。数据类型称为“datetime64”,因此命名是因为“datetime”已经由Python中包含的datetime库采用。

注意

datetime API在1.7.0中是实验,并且可能在未来版本的NumPy中进行更改。

Basic Datetimes

创建数据时间的最基本的方法是使用ISO 8601日期或日期时间格式的字符串。内部存储单元是从字符串的形式自动选择的,可以是date unittime unit日期单位是年('Y'),月('M'),星期('W')和日('D'),而时间单位是小时),秒('s'),毫秒('ms')和一些附加的基于秒前缀的单位。

简单的ISO日期:

>>> np.datetime64('2005-02-25')
numpy.datetime64('2005-02-25')

使用月份为单位:

>>> np.datetime64('2005-02')
numpy.datetime64('2005-02')

仅指定月份,但强制使用“天”单位:

>>> np.datetime64('2005-02', 'D')
numpy.datetime64('2005-02-01')

从日期和时间:

>>> np.datetime64('2005-02-25T03:30')
numpy.datetime64('2005-02-25T03:30')

从字符串创建数据集的数组时,仍然可以使用带有通用单位的日期时间类型从输入中自动选择单位。

>>> np.array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='datetime64')
array(['2007-07-13', '2006-01-13', '2010-08-13'], dtype='datetime64[D]')
>>> np.array(['2001-01-01T12:00', '2002-02-03T13:56:03.172'], dtype='datetime64')
array(['2001-01-01T12:00:00.000-0600', '2002-02-03T13:56:03.172-0600'], dtype='datetime64[ms]')

datetime类型适用于许多常见的NumPy函数,例如arange可用于生成日期范围。

所有日期一个月:

>>> np.arange('2005-02', '2005-03', dtype='datetime64[D]')
array(['2005-02-01', '2005-02-02', '2005-02-03', '2005-02-04',
       '2005-02-05', '2005-02-06', '2005-02-07', '2005-02-08',
       '2005-02-09', '2005-02-10', '2005-02-11', '2005-02-12',
       '2005-02-13', '2005-02-14', '2005-02-15', '2005-02-16',
       '2005-02-17', '2005-02-18', '2005-02-19', '2005-02-20',
       '2005-02-21', '2005-02-22', '2005-02-23', '2005-02-24',
       '2005-02-25', '2005-02-26', '2005-02-27', '2005-02-28'],
       dtype='datetime64[D]')

datetime对象表示一个时间点。如果两个数据时间具有不同的单位,它们可能仍然表示相同的时刻,并且从诸如月份的较大单位转换为类似天的较小单位被认为是“安全的”投射,因为时间时刻仍然被精确地表示。

>>> np.datetime64('2005') == np.datetime64('2005-01-01')
True
>>> np.datetime64('2010-03-14T15Z') == np.datetime64('2010-03-14T15:00:00.00Z')
True

Datetime and Timedelta Arithmetic

NumPy允许减去两个日期时间值,一个产生具有时间单位的数字的操作。由于NumPy在其核心中没有物理量系统,因此创建了timedelta64数据类型以补充datetime64。

Datetimes和Timedeltas一起工作,为简单的日期时间计算提供方法。

>>> np.datetime64('2009-01-01') - np.datetime64('2008-01-01')
numpy.timedelta64(366,'D')
>>> np.datetime64('2009') + np.timedelta64(20, 'D')
numpy.datetime64('2009-01-21')
>>> np.datetime64('2011-06-15T00:00') + np.timedelta64(12, 'h')
numpy.datetime64('2011-06-15T12:00-0500')
>>> np.timedelta64(1,'W') / np.timedelta64(1,'D')
7.0

有两个Timedelta单位('Y',年和'M',月),它们被特别处理,因为它们代表的变化取决于它们被使用的时间。虽然timedelta天单位相当于24小时,但没有办法将月单位转换为天,因为不同的月份有不同的天数。

>>> a = np.timedelta64(1, 'Y')
>>> np.timedelta64(a, 'M')
numpy.timedelta64(12,'M')
>>> np.timedelta64(a, 'D')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: Cannot cast NumPy timedelta64 scalar from metadata [Y] to [D] according to the rule 'same_kind'

Datetime Units

Datetime和Timedelta数据类型支持大量的时间单位,以及可以基于输入数据强制转换为任何其他单位的通用单位。

数据时间总是基于POSIX时间存储(虽然具有允许计算闰秒的TAI模式),具有1970-01-01T00:00Z的时期。这意味着支持的日期总是围绕时期的对称间隔,在下表中称为“时间跨度”。

跨度的长度是64位整数乘以日期或单位长度的范围。例如,“W”(周)的时间跨度正好是“D”(天)的时间跨度的7倍,“D”(天)的时间跨度恰好是时间跨度的24倍为'h'(小时)。

以下是日期单位:

含义 时间跨度(相对) 时间跨度(绝对)
Y +/- 9.2e18年 [公元前9.2e18,公元9.2e18]
M +/- 7.6e17年 [7.6e17 BC,7.6e17 AD]
W +/- 1.7e17年 [1.7e17 BC,1.7e17 AD]
D +/- 2.5e16年 [2.5e16 BC,2.5e16 AD]

这里是时间单位:

含义 时间跨度(相对) 时间跨度(绝对)
H 小时 +/- 1.0e15年 [1.0e15 BC,1.0e15 AD]
m 分钟 +/- 1.7e13年 [1.7e13 BC,1.7e13 AD]
s 第二 +/- 2.9e11年 [公元前2.9e11,公元2.9e11]
女士 毫秒 +/- 2.9e8年 [公元前2.9e8年,公元2.9e8]
我们 微秒 +/- 2.9e5年 [290301 BC,294241 AD]
ns 纳秒 +/- 292年 [1678 AD,2262 AD]
ps 皮秒 +/- 106天 [1969 AD,1970 AD]
fs 飞秒 +/- 2.6小时 [1969 AD,1970 AD]
阿特秒 +/- 9.2秒 [1969 AD,1970 AD]

Business Day Functionality

为了允许在仅一周中的某些天有效的上下文中使用datetime,NumPy包括一组“busday”(工作日)函数。

busday函数的默认值是,唯一有效的天数是周一到周五(通常的工作日)。该实现基于包含7个布尔标志以指示有效天的“周掩模”;可以指定其他组的有效天数的自定义周边掩码。

“busday”功能还可以检查“假日”日期的列表,不是有效日期的特定日期。

函数busday_offset允许您将以工作日指定的偏移量应用于以“D”(天)为单位的数据时间。

>>> np.busday_offset('2011-06-23', 1)
numpy.datetime64('2011-06-24')
>>> np.busday_offset('2011-06-23', 2)
numpy.datetime64('2011-06-27')

当输入日期落在周末或节假日时,busday_offset首先应用规则将日期滚动到有效工作日,然后应用偏移量。默认规则是'raise',它只是引发一个异常。最常用的规则是“向前”和“向后”。

>>> np.busday_offset('2011-06-25', 2)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Non-business day date in busday_offset
>>> np.busday_offset('2011-06-25', 0, roll='forward')
numpy.datetime64('2011-06-27')
>>> np.busday_offset('2011-06-25', 2, roll='forward')
numpy.datetime64('2011-06-29')
>>> np.busday_offset('2011-06-25', 0, roll='backward')
numpy.datetime64('2011-06-24')
>>> np.busday_offset('2011-06-25', 2, roll='backward')
numpy.datetime64('2011-06-28')

在一些情况下,合适地使用卷和偏移量是获得期望的答案所必需的。

日期当天或之后的第一个工作日:

>>> np.busday_offset('2011-03-20', 0, roll='forward')
numpy.datetime64('2011-03-21','D')
>>> np.busday_offset('2011-03-22', 0, roll='forward')
numpy.datetime64('2011-03-22','D')

第一个工作日严格日期后:

>>> np.busday_offset('2011-03-20', 1, roll='backward')
numpy.datetime64('2011-03-21','D')
>>> np.busday_offset('2011-03-22', 1, roll='backward')
numpy.datetime64('2011-03-23','D')

该函数还可用于计算某些类型的假日。在加拿大和美国,母亲节在5月的第二个星期日,可以用定制的周密计算。

>>> np.busday_offset('2012-05', 1, roll='forward', weekmask='Sun')
numpy.datetime64('2012-05-13','D')

当性能对于操作许多商业日期很重要,通过一个特定的周末掩码和节假日选择,有一个对象busdaycalendar以优化的形式存储必要的数据。

np.is_busday():

要测试datetime64值以查看它是否是有效的一天,请使用is_busday

>>> np.is_busday(np.datetime64('2011-07-15'))  # a Friday
True
>>> np.is_busday(np.datetime64('2011-07-16')) # a Saturday
False
>>> np.is_busday(np.datetime64('2011-07-16'), weekmask="Sat Sun")
True
>>> a = np.arange(np.datetime64('2011-07-11'), np.datetime64('2011-07-18'))
>>> np.is_busday(a)
array([ True,  True,  True,  True,  True, False, False], dtype='bool')

np.busday_count():

要查找datetime64日期的指定范围内有多少有效天数,请使用busday_count

>>> np.busday_count(np.datetime64('2011-07-11'), np.datetime64('2011-07-18'))
5
>>> np.busday_count(np.datetime64('2011-07-18'), np.datetime64('2011-07-11'))
-5

如果你有一个datetime64 day值的数组,并且你想要一个有多少是有效日期的计数,你可以这样做:

>>> a = np.arange(np.datetime64('2011-07-11'), np.datetime64('2011-07-18'))
>>> np.count_nonzero(np.is_busday(a))
5

Custom Weekmasks

以下是自定义周掩码值的几个示例。这些示例指定“busday”默认值为星期一到星期五是有效日期。

一些例子:

# Positional sequences; positions are Monday through Sunday.
# Length of the sequence must be exactly 7.
weekmask = [1, 1, 1, 1, 1, 0, 0]
# list or other sequence; 0 == invalid day, 1 == valid day
weekmask = "1111100"
# string '0' == invalid day, '1' == valid day

# string abbreviations from this list: Mon Tue Wed Thu Fri Sat Sun
weekmask = "Mon Tue Wed Thu Fri"
# any amount of whitespace is allowed; abbreviations are case-sensitive.
weekmask = "MonTue Wed  Thu\tFri"

Changes with NumPy 1.11

在以前的NumPy版本中,datetime64类型总是存储UTC时间。默认情况下,从字符串创建datetime64对象或打印datetime64对象将从或转换为本地时间:

# old behavior
>>>> np.datetime64('2000-01-01T00:00:00')
numpy.datetime64('2000-01-01T00:00:00-0800')  # note the timezone offset -08:00

datetime64用户的一致性同意这种行为是不可取的,并且与datetime64通常使用(例如,通过pandas_)不一致。对于大多数使用情况,首选的时区naive datetime类型,类似于Python标准库中的datetime.datetime类型。因此,datetime64不再假设输入在本地时间,也不打印本地时间:

>>>> np.datetime64('2000-01-01T00:00:00')
numpy.datetime64('2000-01-01T00:00:00')

为了向后兼容,datetime64仍然解析时区偏移,它通过转换为UTC来处理。但是,生成的datetime是时区naive:

>>> np.datetime64('2000-01-01T00:00:00-08')
DeprecationWarning: parsing timezone aware datetimes is deprecated; this will raise an error in the future
numpy.datetime64('2000-01-01T08:00:00')

作为此更改的推论,我们不再禁止在数据时间之间使用日期单位和数据时间与时间单位进行转换。使用时区天真数据时,从日期到时间的转换规则不再含糊不清。

pandas_http://pandas.pydata.org

Differences Between 1.6 and 1.7 Datetimes

NumPy 1.6版本包括比1.7更原始的datetime数据类型。本节记录了已发生的许多变化。

String Parsing

NumPy 1.6中的datetime字符串解析器在它接受的内容非常自由,并且默默地允许无效输入,而不会引起错误。在NumPy 1.7中的解析器是非常严格的只接受ISO 8601日期,有一些方便的扩展。1.6总是默认创建微秒(us)单位,而1.7检测基于字符串格式的单位。这里是一个比较。

# NumPy 1.6.1
>>> np.datetime64('1979-03-22')
1979-03-22 00:00:00
# NumPy 1.7.0
>>> np.datetime64('1979-03-22')
numpy.datetime64('1979-03-22')

# NumPy 1.6.1, unit default microseconds
>>> np.datetime64('1979-03-22').dtype
dtype('datetime64[us]')
# NumPy 1.7.0, unit of days detected from string
>>> np.datetime64('1979-03-22').dtype
dtype('<M8[D]')

# NumPy 1.6.1, ignores invalid part of string
>>> np.datetime64('1979-03-2corruptedstring')
1979-03-02 00:00:00
# NumPy 1.7.0, raises error for invalid input
>>> np.datetime64('1979-03-2corruptedstring')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Error parsing datetime string "1979-03-2corruptedstring" at position 8

# NumPy 1.6.1, 'nat' produces today's date
>>> np.datetime64('nat')
2012-04-30 00:00:00
# NumPy 1.7.0, 'nat' produces not-a-time
>>> np.datetime64('nat')
numpy.datetime64('NaT')

# NumPy 1.6.1, 'garbage' produces today's date
>>> np.datetime64('garbage')
2012-04-30 00:00:00
# NumPy 1.7.0, 'garbage' raises an exception
>>> np.datetime64('garbage')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
ValueError: Error parsing datetime string "garbage" at position 0

# NumPy 1.6.1, can't specify unit in scalar constructor
>>> np.datetime64('1979-03-22T19:00', 'h')
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: function takes at most 1 argument (2 given)
# NumPy 1.7.0, unit in scalar constructor
>>> np.datetime64('1979-03-22T19:00', 'h')
numpy.datetime64('1979-03-22T19:00-0500','h')

# NumPy 1.6.1, reads ISO 8601 strings w/o TZ as UTC
>>> np.array(['1979-03-22T19:00'], dtype='M8[h]')
array([1979-03-22 19:00:00], dtype=datetime64[h])
# NumPy 1.7.0, reads ISO 8601 strings w/o TZ as local (ISO specifies this)
>>> np.array(['1979-03-22T19:00'], dtype='M8[h]')
array(['1979-03-22T19-0500'], dtype='datetime64[h]')

# NumPy 1.6.1, doesn't parse all ISO 8601 strings correctly
>>> np.array(['1979-03-22T12'], dtype='M8[h]')
array([1979-03-22 00:00:00], dtype=datetime64[h])
>>> np.array(['1979-03-22T12:00'], dtype='M8[h]')
array([1979-03-22 12:00:00], dtype=datetime64[h])
# NumPy 1.7.0, handles this case correctly
>>> np.array(['1979-03-22T12'], dtype='M8[h]')
array(['1979-03-22T12-0500'], dtype='datetime64[h]')
>>> np.array(['1979-03-22T12:00'], dtype='M8[h]')
array(['1979-03-22T12-0500'], dtype='datetime64[h]')

Unit Conversion

日期时间的1.6实现不能正确地在单位之间转换。

# NumPy 1.6.1, the representation value is untouched
>>> np.array(['1979-03-22'], dtype='M8[D]')
array([1979-03-22 00:00:00], dtype=datetime64[D])
>>> np.array(['1979-03-22'], dtype='M8[D]').astype('M8[M]')
array([2250-08-01 00:00:00], dtype=datetime64[M])
# NumPy 1.7.0, the representation is scaled accordingly
>>> np.array(['1979-03-22'], dtype='M8[D]')
array(['1979-03-22'], dtype='datetime64[D]')
>>> np.array(['1979-03-22'], dtype='M8[D]').astype('M8[M]')
array(['1979-03'], dtype='datetime64[M]')

Datetime Arithmetic

日期时间的1.6实现仅对算术运算的小子集正确工作。这里我们展示一些简单的案例。

# NumPy 1.6.1, produces invalid results if units are incompatible
>>> a = np.array(['1979-03-22T12'], dtype='M8[h]')
>>> b = np.array([3*60], dtype='m8[m]')
>>> a + b
array([1970-01-01 00:00:00.080988], dtype=datetime64[us])
# NumPy 1.7.0, promotes to higher-resolution unit
>>> a = np.array(['1979-03-22T12'], dtype='M8[h]')
>>> b = np.array([3*60], dtype='m8[m]')
>>> a + b
array(['1979-03-22T15:00-0500'], dtype='datetime64[m]')

# NumPy 1.6.1, arithmetic works if everything is microseconds
>>> a = np.array(['1979-03-22T12:00'], dtype='M8[us]')
>>> b = np.array([3*60*60*1000000], dtype='m8[us]')
>>> a + b
array([1979-03-22 15:00:00], dtype=datetime64[us])
# NumPy 1.7.0
>>> a = np.array(['1979-03-22T12:00'], dtype='M8[us]')
>>> b = np.array([3*60*60*1000000], dtype='m8[us]')
>>> a + b
array(['1979-03-22T15:00:00.000000-0500'], dtype='datetime64[us]')