pandas.DataFrame.tz_localize#

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

将 Series 或 DataFrame 的时区感知索引本地化到目标时区。

此操作会本地化 Index。要本地化时区感知 Series 中的值，请使用 Series.dt.tz_localize()。

参数:

tzstr 或 tzinfo 或 None

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

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

要本地化的轴

levelint, str, 默认为 None

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

copybool，默认值 False

此关键字已被忽略；更改其值将不会影响方法。

已弃用，版本 3.0.0: 此关键字已被忽略，并将在 pandas 4.0 中删除。自 pandas 3.0 起，此方法始终返回一个新对象，并使用延迟复制机制，该机制会推迟复制直到必要时（写时复制）。有关更多详细信息，请参阅关于写时复制的用户指南。

ambiguous‘infer’、bool、bool-ndarray、‘NaT’，默认为 ‘raise’

当 DST 导致时钟倒转时，可能会出现歧义时间。例如，在中欧时间 (UTC+01) 中，从 DST 的 03:00 变为非 DST 的 02:00 时，本地时间 02:30:00 会同时出现在 UTC 的 00:30:00 和 UTC 的 01:30:00。在这种情况下，ambiguous 参数决定了如何处理歧义时间。

‘infer’ 将尝试根据顺序推断 DST 转换小时
布尔值 (或布尔数组)，其中 True 表示 DST 时间，False 表示非 DST 时间 (请注意，此标志仅适用于歧义时间)
‘NaT’ 将在模糊时间处返回 NaT
‘raise’ 将在存在模糊时间时引发 ValueError。

nonexistentstr，默认为 ‘raise’

不存在的时间在 DST 导致时钟向前移动的特定时区中不存在。有效值为

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

返回:

Series/DataFrame: 与输入相同的类型，具有时区感知或时区不敏感的索引，具体取决于 tz。

引发:

TypeError: 如果 TimeSeries 是时区感知的且 tz 不为 None。

另请参阅

Series.dt.tz_localize: 本地化时区不敏感 Series 中的值。
Timestamp.tz_localize: 将 Timestamp 本地化到某个时区。

示例

本地化本地时间

>>> 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 以转换为时区不敏感索引并保留本地时间

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

如果 DST 转换导致不存在的时间，您可以使用 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