当前位置: 首页>>编程示例 >>用法及示例精选 >>正文

Python Pandas DataFrame tz_localize方法用法及代码示例

Pandas DataFrame.tz_localize(~) 使 DataFrame 的索引能够感知时区。

注意

要本地化列而不是索引，请改用Series.dt.tz_localize()。

参数

1.tz | string 或 tzinfo

要使用的时区。

2. axis | int 或 string | optional

是否本地化行索引或列索引：

轴

说明

0 或 "index"

本地化行索引。

1 或 "columns"

本地化列索引。

默认情况下 axis=0 。

3. level | int 或 string | optional

目标水平。仅当您的 DataFrame 具有 MultiIndex 时，这才有意义。

4. copy | boolean | optional

  • 如果True，则返回新的DataFrame。修改此 DataFrame 不会改变源 DataFrame，反之亦然。

  • 如果 False ，则不会创建新的 DataFrame - 修改返回的 DataFrame 将改变源 DataFrame，反之亦然。

默认情况下，copy=True 。

5. ambiguous | string 或 Numpy 布尔数组 | optional

由于夏令时 (DST) 引起的时间调整，时间可能会出现歧义。例如，考虑以下情况：

Local time:
01:59:58
01:59:59   
01:00:00   # DST ends and so we set the wall clock back 1 hour
01:00:01
...
01:59:58   # This local time occured for the second time
...

如果您尝试本地化发生两次的时间(例如 01:59:58 )，那么 Pandas 会很困惑您指的是哪个时间 - 第一次(DST)还是第二次(非 DST)？

Pandas 可以通过以下方式之一处理这种歧义：

值

说明

"infer"

根据提供的时间顺序推断 DST 转换。

array 共 boolean

布尔数组(例如列表、Numpy 数组)，其中：

  • True表示夏令时

  • False表示非夏令时

"NaT"

不明确的时间将转换为NaT (not-a-time)。

"raise"

模棱两可的时候会引发错误。

默认情况下，ambiguous="raise" 。

6. nonexistent | string 或 timedelta | optional

同样，由于夏令时 (DST)，某些当地时间不存在。例如：

Local time:
00:59:58
00:59:59   # DST starts so the wall clock is turned forwards by 1 hour
02:00:00
02:00:01

请注意，由于 DST 导致挂钟向前移动一小时，因此 01:30:30 等本地时间并不存在。

Pandas 可以通过以下方式处理不存在的时间：

值

说明

"shift_forward"

将任何不存在的时间向前移动到最近的现有时间。

"shift_backward"

将任何不存在的时间向后移动到最近的现有时间。

"NaT"

对于不存在的时间返回NaT。

timedelta 对象

将不存在的时间移动提供的时间增量。

"raise"

对于不存在的时间抛出错误。

默认情况下，nonexistent="raise" 。

返回值

DataFrame，其索引转换为本地时间。

例子

基本用法

考虑以下时区天真 DatetimeIndex ：

idx = pd.DatetimeIndex(['2020-12-22 15:30:00',
 '2020-12-23 16:00:00'])
s = pd.Series(range(2), index=idx)
s



2020-12-22 15:30:00    0
2020-12-23 16:00:00    1
dtype: int64

在这里，天真仅仅意味着我们的 DatetimeIndex 没有时区的概念。

要使 DatetimeIndex 时区感知：

s.tz_localize(tz="Asia/Tokyo")



2020-12-22 15:30:00+09:00    0
2020-12-23 16:00:00+09:00    1
dtype: int64

这里，附加的+09:00表示东京的标准时间比UTC早9个小时。

处理暧昧时期

考虑以下具有不明确日期的时间序列：

idx = pd.DatetimeIndex(['2019-10-27 02:30:00',
 '2019-10-27 02:00:00',
 '2019-10-27 02:30:00',
 '2019-10-27 03:00:00',
 '2019-10-27 03:30:00'])
s = pd.Series(range(5), index=idx)
s



2019-10-27 02:30:00    0
2019-10-27 02:00:00    1
2019-10-27 02:30:00    2
2019-10-27 03:00:00    3
2019-10-27 03:30:00    4
dtype: int64

2019-10-27 3AM(中欧时间)，DST 结束，这意味着挂钟拨慢一小时。因此，我们这里有一个不明确的情况，像 2019-10-27 02:30:00 这样的时间在本地发生了两次。

增加

默认情况下， ambiguous="raise" ，这意味着只要时间不明确就会抛出错误：

s.tz_localize("CET")   # ambiguous="raise"



AmbiguousTimeError: Cannot infer dst time from 2019-10-27 02:30:00, try using the 'ambiguous' argument
推断

在本例中，从数据中可以推断出，前一个02:30:00指的是夏令时时间，后一个02:30:00指的是非夏令时时间：

s.tz_localize("CET", ambiguous="infer")



2019-10-27 02:30:00+02:00    0
2019-10-27 02:00:00+01:00    1
2019-10-27 02:30:00+01:00    2
2019-10-27 03:00:00+01:00    3
2019-10-27 03:30:00+01:00    4
dtype: int64

观察 Pandas 如何通过 UTC+02:00 抵消来计算 DST。

布尔数组

有时无法区分 DST 和非 DST 时间：

idx = pd.DatetimeIndex(['2019-10-27 02:30:00'])
s = pd.Series("a", index=idx)
s.tz_localize("CET", ambiguous="infer")



AmbiguousTimeError: Cannot infer dst time from 2019-10-27 02:30:00 as there are no repeated times

在这里，我们得到一个错误，因为没有日期时间序列(如我们上面的)，Pandas 无法知道 02:30:00 的模糊时间是 DST 还是非 DST。

在这种情况下，我们可以通过传入一个布尔数组来直接告诉 Pandas 某个日期时间是否是 DST：

idx = pd.DatetimeIndex(['2019-10-27 02:30:00', '2019-10-27 02:35:00'])
s = pd.Series("a", index=idx)
s.tz_localize("CET", ambiguous=[True,False])



2019-10-27 02:30:00+02:00    a
2019-10-27 02:35:00+01:00    a
dtype: object

这里True表示对应的时间是DST。

NaT

要将所有不明确的日期时间映射到 NaT ：

idx = pd.DatetimeIndex(['2019-10-27 02:30:00', '2019-10-27 03:30:00'])
s = pd.Series("a", index=idx)
s.tz_localize("CET", ambiguous="NaT")



NaT                          a
2019-10-27 03:30:00+01:00    a
dtype: object

处理不存在的时间

考虑以下系列：

idx = pd.DatetimeIndex(['2019-03-31 01:30:00', '2019-03-31 02:30:00', '2019-03-31 03:30:00'])
s = pd.Series("a", index=idx)
s



2019-03-31 01:30:00    a
2019-03-31 02:30:00    a
2019-03-31 03:30:00    a
dtype: object

2019-03-31 2AM(中欧时间)开始实行 DST，这意味着挂钟向前拨动一小时。因此，像 2:30AM 这样的本地时间是不存在的。

增加

默认情况下 nonexistent="raise" 这意味着不存在这样的时间会引发错误：

s.tz_localize("CET")   # nonexistent="raise"



NonExistentTimeError: 2019-03-31 02:30:00
shift_forward

要将不存在的时间向前移动到最近的现有时间：

s.tz_localize("CET", nonexistent="shift_forward")



2019-03-31 01:30:00+01:00    a
2019-03-31 03:00:00+02:00    a
2019-03-31 03:30:00+02:00    a
dtype: object
shift_backward

要将不存在的时间向后移动到最近的现有时间：

s.tz_localize("CET", nonexistent="shift_backward")



2019-03-31 01:30:00+01:00              a
2019-03-31 01:59:59.999999999+01:00    a
2019-03-31 03:30:00+02:00              a
dtype: object

这是同一系列s供您参考：

s



2019-03-31 01:30:00    a
2019-03-31 02:30:00    a
2019-03-31 03:30:00    a
dtype: object
时间增量对象

要将不存在的时间向前移动一小时：

s.tz_localize("CET", nonexistent=pd.Timedelta("1 hour"))



2019-03-31 01:30:00+01:00    a
2019-03-31 03:30:00+02:00    a
2019-03-31 03:30:00+02:00    a
dtype: object

要将不存在的时间向后移动一小时：

s.tz_localize("CET", nonexistent=-pd.Timedelta("1 hour"))   # notice the "-" there



2019-03-31 01:30:00+01:00    a
2019-03-31 01:30:00+01:00    a
2019-03-31 03:30:00+02:00    a
dtype: object

请注意，如果移动后的不存在时间仍然不存在，则会抛出错误：

s.tz_localize("CET", nonexistent=pd.Timedelta("5 minutes"))



ValueError: The nonexistent argument must be one of 'raise', 'NaT', 'shift_forward', 'shift_backward' or a timedelta object
NaT

要将不存在的时间转换为NaT (not-a-time)：

s.tz_localize("CET", nonexistent="NaT")



2019-03-31 01:30:00+01:00    a
NaT                          a
2019-03-31 03:30:00+02:00    a
dtype: object

相关用法


注：本文由纯净天空筛选整理自Isshin Inada大神的英文原创作品 Pandas DataFrame | tz_localize method。非经特殊声明，原始代码版权归原作者所有，本译文未经允许或授权，请勿转载或复制。