pandas.DataFrame.tz_localize#

DataFrame.tz_localize(tz, axis=0, level=None, copy=<no_default>, ambiguous='raise', nonexistent='raise')[源代码]#

将 Series 或 DataFrame 的时区未指定索引本地化为目标时区。

此操作本地化索引。要在时区无知的系列中本地化值，请使用 Series.dt.tz_localize()。

参数:

tzstr 或 tzinfo 或 None

时区本地化。传递 None 将移除时区信息并保留本地时间。

轴{0 或 ‘index’, 1 或 ‘columns’}, 默认 0

要本地化的轴

级别int, str, 默认 None

如果 axis 是一个 MultiIndex，本地化一个特定的级别。否则必须为 None。

复制布尔值, 默认为 False

还要制作基础数据的副本。

备注

copy 关键字将在 pandas 3.0 中改变行为。写时复制将被默认启用，这意味着所有带有 copy 关键字的方法将使用一种延迟复制机制来推迟复制并忽略 copy 关键字。copy 关键字将在未来版本的 pandas 中被移除。

通过启用写时复制 pd.options.mode.copy_on_write = True，您已经可以获得未来的行为和改进。

自 3.0.0 版本弃用.

模糊‘infer’, bool, bool-ndarray, ‘NaT’, 默认 ‘raise’

由于夏令时导致的时钟回拨，可能会出现不明确的时间。例如在中欧时间（UTC+01），当从夏令时03:00变为非夏令时02:00时，本地时间02:30:00在UTC时间00:30:00和01:30:00都会出现。在这种情况下，`ambiguous`参数决定了如何处理不明确的时间。

‘infer’ 将尝试根据顺序推断出 dst-transition 小时
bool (或 bool-ndarray) 其中 True 表示夏令时时间，False 表示非夏令时时间（请注意，此标志仅适用于不明确的时间）
‘NaT’ 将在有歧义的时间返回 NaT
‘raise’ 如果存在歧义时间，将引发 ValueError。

nonexistentstr, 默认 ‘raise’

在一个特定的时区中，不存在一个不存在的时间，因为时钟因夏令时而向前移动。有效值是：

‘shift_forward’ 会将不存在的时间向前移动到最近的现有时间
‘shift_backward’ 会将不存在的时间向后移动到最近的现有时间
‘NaT’ 将在不存在时间的地方返回 NaT
timedelta 对象会将不存在的时间按 timedelta 进行调整
‘raise’ 如果存在不存在的时间，将引发 ValueError。

返回:

系列/数据框: 与输入类型相同，根据 tz 具有时区无感知或感知的索引。

引发:

TypeError: 如果 TimeSeries 是 tz-aware 并且 tz 不是 None。

参见

Series.dt.tz_localize: 在时区未知的系列中本地化值。
Timestamp.tz_localize: 将时间戳本地化为一个时区。

例子

本地化本地时间：

>>> s = pd.Series(
...     [1],
...     index=pd.DatetimeIndex(["2018-09-15 01:30:00"]),
... )
>>> s.tz_localize("CET")
2018-09-15 01:30:00+02:00    1
dtype: int64

传递 None 以转换为 tz-naive 索引并保留本地时间：

>>> s = pd.Series([1], index=pd.DatetimeIndex(["2018-09-15 01:30:00+02:00"]))
>>> s.tz_localize(None)
2018-09-15 01:30:00    1
dtype: int64

注意DST的变化。当有顺序数据时，pandas可以推断DST时间：

>>> s = pd.Series(
...     range(7),
...     index=pd.DatetimeIndex(
...         [
...             "2018-10-28 01:30:00",
...             "2018-10-28 02:00:00",
...             "2018-10-28 02:30:00",
...             "2018-10-28 02:00:00",
...             "2018-10-28 02:30:00",
...             "2018-10-28 03:00:00",
...             "2018-10-28 03:30:00",
...         ]
...     ),
... )
>>> s.tz_localize("CET", ambiguous="infer")
2018-10-28 01:30:00+02:00    0
2018-10-28 02:00:00+02:00    1
2018-10-28 02:30:00+02:00    2
2018-10-28 02:00:00+01:00    3
2018-10-28 02:30:00+01:00    4
2018-10-28 03:00:00+01:00    5
2018-10-28 03:30:00+01:00    6
dtype: int64

在某些情况下，推断DST是不可能的。在这种情况下，你可以传递一个ndarray到ambiguous参数来显式设置DST。

>>> s = pd.Series(
...     range(3),
...     index=pd.DatetimeIndex(
...         [
...             "2018-10-28 01:20:00",
...             "2018-10-28 02:36:00",
...             "2018-10-28 03:46:00",
...         ]
...     ),
... )
>>> s.tz_localize("CET", ambiguous=np.array([True, True, False]))
2018-10-28 01:20:00+02:00    0
2018-10-28 02:36:00+02:00    1
2018-10-28 03:46:00+01:00    2
dtype: int64

如果夏令时转换导致不存在的时间，您可以使用 timedelta 对象或 ‘shift_forward’ 或 ‘shift_backward’ 将这些日期向前或向后移动。

>>> dti = pd.DatetimeIndex(
...     ["2015-03-29 02:30:00", "2015-03-29 03:30:00"], dtype="M8[ns]"
... )
>>> s = pd.Series(range(2), index=dti)
>>> s.tz_localize("Europe/Warsaw", nonexistent="shift_forward")
2015-03-29 03:00:00+02:00    0
2015-03-29 03:30:00+02:00    1
dtype: int64
>>> s.tz_localize("Europe/Warsaw", nonexistent="shift_backward")
2015-03-29 01:59:59.999999999+01:00    0
2015-03-29 03:30:00+02:00              1
dtype: int64
>>> s.tz_localize("Europe/Warsaw", nonexistent=pd.Timedelta("1h"))
2015-03-29 03:30:00+02:00    0
2015-03-29 03:30:00+02:00    1
dtype: int64