日期时间和时间增量#

从 NumPy 1.7 开始,有一些核心数组数据类型本身支持日期时间功能.数据类型称为 datetime64 ,之所以这样命名,是因为 datetime 已经被 Python 标准库占用.

Datetime64 约定和假设#

与 Python date 类相似,日期以当前的格里高利历表示,在未来和过去无限期地扩展. [1] 与仅支持 1 AD - 9999 AD 范围内的年份的 Python date 不同, datetime64 也允许公元前的日期;公元前的年份遵循 Astronomical year numbering 惯例,即公元前 2 年编号为 -1,公元前 1 年编号为 0,公元 1 年编号为 1.

时间瞬间,比如 16:23:32.234,通过计算午夜以来的小时,分钟,秒和分数来表示:即 00:00:00.000 是午夜,12:00:00.000 是中午,等等.每个日历日正好有 86400 秒.这是一个“naive”时间,没有时区或特定时间尺度(UT1,UTC,TAI 等)的明确概念. [2]

基本日期时间#

创建日期时间最基本的方式是使用 ISO 8601 日期或日期时间格式的字符串.也可以通过相对于 Unix 纪元(1970 年 1 月 1 日 00:00:00 UTC)的偏移量,使用整数来创建日期时间.内部存储的单位会根据字符串的形式自动选择,可以是 date unit 或 time unit .日期单位有年(‘Y’),月(‘M’),周(‘W’)和日(‘D’),而时间单位有时(‘h’),分(‘m’),秒(‘s’),毫秒(‘ms’)以及一些额外的基于秒的 SI 前缀单位. datetime64 数据类型也接受字符串 “NAT”,可以使用大小写字母的任意组合,表示 “Not A Time” 值.

示例

一个简单的 ISO 日期:

>>> import numpy as np

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

从一个整数和一个日期单位,表示自 UNIX 纪元以来的 1 年:

>>> np.datetime64(1, 'Y')
np.datetime64('1971')

使用月份作为单位:

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

仅指定月份,但强制使用 ‘days’ 单位:

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

从日期和时间:

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

NAT (不是时间):

>>> np.datetime64('nat')
np.datetime64('NaT')

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

示例

>>> import numpy as np

>>> 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', '2002-02-03T13:56:03.172'],
      dtype='datetime64[ms]')

可以从表示具有给定单位的 POSIX 时间戳的整数构造日期时间数组.

示例

>>> import numpy as np

>>> np.array([0, 1577836800], dtype='datetime64[s]')
array(['1970-01-01T00:00:00', '2020-01-01T00:00:00'],
      dtype='datetime64[s]')

>>> np.array([0, 1577836800000]).astype('datetime64[ms]')
array(['1970-01-01T00:00:00.000', '2020-01-01T00:00:00.000'],
      dtype='datetime64[ms]')

日期时间类型适用于许多常见的 NumPy 函数,例如,可以使用 arange 生成日期范围.

示例

一个月的所有日期:

>>> import numpy as np

>>> 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]')

日期时间对象表示时间中的一个时刻.如果两个日期时间具有不同的单位,它们可能仍然表示同一时刻,并且从较大的单位(如月)转换为较小的单位(如日)被认为是“安全”的转换,因为时间点仍然被精确地表示.

示例

>>> import numpy as np

>>> np.datetime64('2005') == np.datetime64('2005-01-01')
True

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

自 1.11.0 版本弃用: NumPy 不存储时区信息.为了向后兼容,datetime64 仍然解析时区偏移量,它通过转换为 UTC±00:00(祖鲁时间)来处理这些偏移量.此行为已弃用,将来会引发错误.

日期时间和时间差算术#

NumPy 允许减去两个日期时间值,此操作会生成一个具有时间单位的数字.因为 NumPy 的核心没有物理量系统,所以创建了 timedelta64 数据类型来补充 datetime64 . timedelta64 的参数是一个数字,用于表示单位的数量,以及一个日期/时间单位,例如(D)天,(M)月,(Y)年,(h)小时,(m)分钟或(s)秒. timedelta64 数据类型也接受字符串 “NAT” 来代替数字,表示 “Not A Time” 值.

示例

>>> import numpy as np

>>> np.timedelta64(1, 'D')
np.timedelta64(1,'D')

>>> np.timedelta64(4, 'h')
np.timedelta64(4,'h')

>>> np.timedelta64('nAt')
np.timedelta64('NaT')

日期时间和时间差协同工作,为简单的日期时间计算提供方法.

示例

>>> import numpy as np

>>> np.datetime64('2009-01-01') - np.datetime64('2008-01-01')
np.timedelta64(366,'D')

>>> np.datetime64('2009') + np.timedelta64(20, 'D')
np.datetime64('2009-01-21')

>>> np.datetime64('2011-06-15T00:00') + np.timedelta64(12, 'h')
np.datetime64('2011-06-15T12:00')

>>> np.timedelta64(1,'W') / np.timedelta64(1,'D')
7.0

>>> np.timedelta64(1,'W') % np.timedelta64(10,'D')
np.timedelta64(7,'D')

>>> np.datetime64('nat') - np.datetime64('2009-01-01')
np.timedelta64('NaT','D')

>>> np.datetime64('2009-01-01') + np.timedelta64('nat')
np.datetime64('NaT')

有两个时间差单位(‘Y’,年和 ‘M’,月)被特殊对待,因为它们代表的时间量根据使用时间而变化.虽然时间差天单位相当于 24 小时,但如果不使用“不安全”的转换,月份和年份单位不能直接转换为天.

numpy.ndarray.astype 方法可用于将月份/年份不安全地转换为天.转换遵循从 400 年闰年周期计算平均值的过程.

示例

>>> import numpy as np

>>> 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 和 Timedelta 数据类型支持大量时间单位,以及可以根据输入数据强制转换为任何其他单位的通用单位.

日期时间始终使用 1970-01-01T00:00 的纪元存储. 这意味着支持的日期始终是纪元周围的对称间隔,在下表中称为“时间跨度”.

跨度的长度是 64 位整数范围乘以日期或单位的长度.例如,’W’(周)的时间跨度正好是 ‘D’(天)的时间跨度的 7 倍,而 ‘D’(天)的时间跨度正好是 ‘h’(小时)的时间跨度的 24 倍.

以下是日期单位:

代码	含义	时间跨度(相对)	时间跨度(绝对)
Y	年	+/- 9.2e18 年	[9.2e18 BC, 9.2e18 AD]
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 BC, 2.9e11 AD]
ms	毫秒	+/- 2.9e8 年	[ 2.9e8 BC, 2.9e8 AD]
us / μs	微秒	+/- 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]
as	阿秒	+/- 9.2 秒	[ 1969 AD, 1970 AD]

工作日功能#

为了允许 datetime 在仅某些星期几有效的情况下使用,NumPy 包含一组“busday”(工作日)函数.

busday 函数的默认设置是只有周一到周五(通常的工作日)才有效.该实现基于一个包含 7 个布尔标志的“weekmask”来指示有效日期;可以自定义 weekmask 来指定其他有效日期集.

“busday”函数还可以检查“holiday”日期列表,即特定无效日期.

busday_offset 函数允许将以工作日指定的偏移量应用于单位为 ‘D’(天)的 datetimes.

示例

>>> import numpy as np

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

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

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

示例

>>> import numpy as np

>>> 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')
np.datetime64('2011-06-27')

>>> np.busday_offset('2011-06-25', 2, roll='forward')
np.datetime64('2011-06-29')

>>> np.busday_offset('2011-06-25', 0, roll='backward')
np.datetime64('2011-06-24')

>>> np.busday_offset('2011-06-25', 2, roll='backward')
np.datetime64('2011-06-28')

在某些情况下,需要适当地使用滚动和偏移才能获得所需的答案.

示例

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

>>> import numpy as np

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

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

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

该函数对于计算某些类型的日子(如假期)也很有用.在加拿大和美国,母亲节是五月的第二个星期日,可以使用自定义的 weekmask 进行计算.

示例

>>> import numpy as np

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

当需要使用特定的 weekmask 和节假日来操作大量业务日期时,可以使用 busdaycalendar 对象,它以优化的形式存储必要的数据.

np.is_busday():#

要测试 datetime64 值以查看它是否为有效日期,请使用 is_busday .

示例

>>> import numpy as np

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

np.busday_count():#

要查找指定范围的 datetime64 日期中有多少个有效日期,请使用 busday_count :

示例

>>> import numpy as np

>>> 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 日期值数组,并且想要统计其中有多少个是有效日期,您可以这样做:

示例

>>> import numpy as np

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

自定义 weekmask#

以下是自定义 weekmask 值的几个示例.这些示例指定了“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"

Datetime64 的缺点#

假设所有天数都精确地是 86400 秒长,这使得 datetime64 在很大程度上与 Python datetime 和“POSIX 时间”语义兼容;因此,它们都与 UTC 时间尺度和历史时间确定方面存在相同的众所周知的缺点.下面给出一个简短的非详尽的总结.

不可能解析在正闰秒期间发生的有效 UTC 时间戳.
示例

“2016-12-31 23:59:60 UTC”是一个闰秒,因此“2016-12-31 23:59:60.450 UTC”是一个有效的 timestamp, datetime64 无法解析:
>>> import numpy as np
>>> np.datetime64("2016-12-31 23:59:60.450") Traceback (most recent call last): File "<stdin>", line 1, in <module> ValueError: Seconds out of range in datetime string "2016-12-31 23:59:60.450"
两个 UTC 日期之间的 Timedelta64 计算结果可能与 SI 秒的整数值相差.
示例

计算“2021-01-01 12:56:23.423 UTC”和“2001-01-01 00:00:00.000 UTC”之间的 SI 秒数:
>>> import numpy as np
>>> ( ... np.datetime64("2021-01-01 12:56:23.423") ... - np.datetime64("2001-01-01") ... ) / np.timedelta64(1, "s") 631198583.423
但是,正确的答案是 631198588.423 SI 秒,因为 2001 年到 2021 年之间有 5 个闰秒.
过去日期的 Timedelta64 计算不会像人们期望的那样返回 SI 秒.
示例

计算“000-01-01 UT”和“1600-01-01 UT”之间的秒数,其中 UT 是 universal time :
>>> import numpy as np
>>> a = np.datetime64("0000-01-01", "us") >>> b = np.datetime64("1600-01-01", "us") >>> b - a numpy.timedelta64(50491123200000000,'us')
计算结果 50491123200 秒是通过经过的天数 ( 584388 ) 乘以 86400 秒得到的;这是与地球自转同步的时钟的秒数.SI 秒的精确值只能估计,例如,使用 Measurement of the Earth’s rotation: 720 BC to AD 2015, 2016, Royal Society’s Proceedings A 472, by Stephenson et.al. 中发布的数据.一个合理的估计是 50491112870 ± 90 秒,相差 10330 秒.

如何运行和测试 NumPy 的代码？

在探索 NumPy 库的核心概念、常见问题和实用代码示例时，所有代码都可在 PythonRun 上直接运行测试。

请给出一个简单的 NumPy 代码示例

下面是一个简单的 NumPy 用法示例：

import numpy as np
a = np.array([1, 2, 3])
a = a * 2
print(a)

你可以在 PythonRun 上执行它，看看结果。