日期时间和时间增量#

从 NumPy 1.7 开始，核心数组数据类型原生支持日期时间功能。该数据类型称为 datetime64，之所以这样命名是因为 Python 标准库已经使用了 datetime。

Datetime64 约定和假设#

类似于 Python 的 date 类，日期以当前格里高利历表示，未来和过去无限延伸。[1] 与仅支持公元 1 年至 9999 年的 Python date 相反，datetime64 也允许公元前日期；公元前年份遵循 天文纪年法，即公元前 2 年编号为 -1，公元前 1 年编号为 0，公元 1 年编号为 1。

时间点，例如 16:23:32.234，表示从午夜开始计算的小时、分钟、秒和分数：即 00:00:00.000 为午夜，12:00:00.000 为中午，等等。每个日历日正好有 86400 秒。这是一个“幼稚的”时间，没有明确的时区或特定时间尺度（UT1、UTC、TAI 等）的概念。[2]

基本日期时间#

创建日期时间最基本的方法是从 ISO 8601 日期或日期时间格式的字符串创建。也可以通过相对于 Unix 纪元（1970 年 1 月 1 日 00:00:00 UTC）的偏移量从整数创建日期时间。内部存储的单位会根据字符串的格式自动选择，可以是 日期单位 或 时间单位。日期单位是年（‘Y’）、月（‘M’）、周（‘W’）和日（‘D’），而时间单位是小时（‘h’）、分钟（‘m’）、秒（‘s’）、毫秒（‘ms’）和一些额外的基于 SI 前缀的秒单位。datetime64 数据类型还接受字符串“NAT”（任何大小写组合）表示“非时间”值。

示例

一个简单的 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')

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

>>> 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”代替数字表示“非时间”值。

示例

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

日期时间单位#

日期时间和时间增量数据类型支持大量时间单位，以及可以根据输入数据强制转换为任何其他单位的通用单位。

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

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

以下是日期单位

代码

含义

时间跨度（相对）

时间跨度（绝对）

Y

年

+/- 9.2e18 年

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

M

月

+/- 7.6e17 年

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

W

周

+/- 1.7e17 年

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

D

日

+/- 2.5e16 年

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

以下是时间单位

代码

含义

时间跨度（相对）

时间跨度（绝对）

h

小时

+/- 1.0e15 年

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

m

分钟

+/- 1.7e13 年

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

s

秒

+/- 2.9e11 年

[公元前 2.9e11 年，公元 2.9e11 年]

ms

毫秒

+/- 2.9e8 年

[公元前 2.9e8 年，公元 2.9e8 年]

us / μs

微秒

+/- 2.9e5 年

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

ns

纳秒

+/- 292 年

[公元 1678 年，公元 2262 年]

ps

皮秒

+/- 106 天

[公元 1969 年，公元 1970 年]

fs

飞秒

+/- 2.6 小时

[公元 1969 年，公元 1970 年]

as

阿秒

+/- 9.2 秒

[公元 1969 年，公元 1970 年]

工作日功能#

为了允许在只有某些工作日有效的上下文中使用日期时间，NumPy 包含一组“busday”（工作日）函数。

工作日函数的默认设置是仅将周一至周五视为有效工作日。其实现基于一个“weekmask”（星期掩码），包含7个布尔型标志来指示有效日期；也可以使用自定义的weekmask来指定其他有效日期集合。

“busday”（工作日）函数还可以检查一个“holiday”（节假日）日期列表，这些日期为无效日期。

busday_offset 函数允许您将以工作日为单位（单位为‘D’（天））的偏移量应用于日期时间。

示例

>>> 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” 是一个有效的时间戳，但无法被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是世界时

    >>> 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秒的精确值只能估算，例如，可以使用Stephenson等人2016年发表在皇家学会会刊A 472, Measurement of the Earth’s rotation: 720 BC to AD 2015上的数据估算。一个合理的估计是50491112870 ± 90 秒，差异为10330秒。