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。非經特殊聲明，原始代碼版權歸原作者所有，本譯文未經允許或授權，請勿轉載或複製。