【超便利】Pandas Timestampのタイムゾーン操作：tz_localizeを使いこなそう

pandas.Timestamp.tz_localize 関数は、Pandasライブラリで扱う Timestamp 型オブジェクトに対して、タイムゾーン情報を追加または削除するためのものです。

この関数は、以下の2つの操作を実行できます。

1. タイムゾーン情報を持たない（tz-naive）Timestampオブジェクトに、指定されたタイムゾーン情報を追加する
2. タイムゾーン情報を持つ（tz-aware）Timestampオブジェクトから、タイムゾーン情報を削除する

使い方

この関数の基本的な使い方は以下の通りです。

import pandas as pd

# タイムゾーン情報を持たないTimestampオブジェクトを作成
naive_timestamp = pd.Timestamp('2024-06-08 00:00:00')

# タイムゾーン情報 'Asia/Tokyo' を追加
asia_timestamp = naive_timestamp.tz_localize('Asia/Tokyo')

# タイムゾーン情報を持つTimestampオブジェクトを作成
aware_timestamp = pd.Timestamp('2024-06-08 09:00:00', tz='Asia/Tokyo')

# タイムゾーン情報を削除
local_timestamp = aware_timestamp.tz_localize(None)

オプション引数

tz_localize 関数は、オプション引数として以下のものを受け取ることができます。

• level: マルチレベルインデックスを持つデータフレームの場合、どのレベルに適用するかを指定します。
• error: タイムゾーン変換に失敗した場合の処理方法を指定します。デフォルトは 'raise' で、例外を発生させます。他のオプションとして 'coerce' (無効な値を NaT に変換) と 'ignore' (エラーを無視) があります。

例

以下に、tz_localize 関数の具体的な使用例をいくつか示します。

例1：タイムゾーン情報のないTimestampオブジェクトにタイムゾーン情報を追加する

import pandas as pd

# タイムゾーン情報を持たないTimestampオブジェクトを作成
naive_timestamp = pd.Timestamp('2024-06-08 00:00:00')

# タイムゾーン情報 'America/New_York' を追加
ny_timestamp = naive_timestamp.tz_localize('America/New_York')

print(ny_timestamp)

この例では、2024-06-08 00:00:00 というタイムスタンプに America/New_York というタイムゾーン情報が追加され、以下の出力が得られます。

2024-06-07 23:00:00-04:00

例2：タイムゾーン情報を持つTimestampオブジェクトからタイムゾーン情報を削除する

import pandas as pd

# タイムゾーン情報を持つTimestampオブジェクトを作成
aware_timestamp = pd.Timestamp('2024-06-08 09:00:00', tz='Asia/Tokyo')

# タイムゾーン情報を削除
local_timestamp = aware_timestamp.tz_localize(None)

print(local_timestamp)

この例では、Asia/Tokyo というタイムゾーン情報を持つ 2024-06-08 09:00:00 というタイムスタンプからタイムゾーン情報が削除され、以下の出力が得られます。

2024-06-08 09:00:00

例3：エラー処理を指定する

import pandas as pd

# タイムゾーン情報を持たないTimestampオブジェクトを作成
naive_timestamp = pd.Timestamp('2024-06-08 00:00:00')

# 無効なタイムゾーン名を指定して、エラーを発生させる
try:
  invalid_timestamp = naive_timestamp.tz_localize('Invalid/Timezone')
except Exception as e:
  print(f'エラーが発生しました: {e}')

この例では、Invalid/Timezone という無効なタイムゾーン名が指定されたため、以下のエラーが出力されます。

エラーが発生しました: Unknown timezone: Invalid/Timezone

import pandas as pd

# タイムゾーン情報を持つTimestampオブジェクトを含むマルチレベルインデックスを持つデータフレームを作成
df = pd.DataFrame({'timestamp': ['2024-06-08 09:00:00', '2024-06-08 10:

---

タイムゾーン情報のないTimestampオブジェクトにタイムゾーン情報を追加

import pandas as pd

# タイムゾーン情報のないTimestampオブジェクトを作成
naive_timestamp = pd.Timestamp('2024-06-08 00:00:00')

# 異なるタイムゾーン情報にtz_localize
# 例：America/New_York、Asia/Tokyo、Europe/Berlin
timezones = ['America/New_York', 'Asia/Tokyo', 'Europe/Berlin']

# 各タイムゾーン情報でTimestampオブジェクトを作成し、表示
for timezone in timezones:
  localized_timestamp = naive_timestamp.tz_localize(timezone)
  print(f'{timezone}: {localized_timestamp}')

America/New_York: 2024-06-07 23:00:00-04:00
Asia/Tokyo: 2024-06-08 08:00:00+09:00
Europe/Berlin: 2024-06-08 06:00:00+02:00

タイムゾーン情報を持つTimestampオブジェクトからタイムゾーン情報を削除

import pandas as pd

# タイムゾーン情報を持つTimestampオブジェクトを作成
aware_timestamps = [
    pd.Timestamp('2024-06-08 09:00:00', tz='Asia/Tokyo'),
    pd.Timestamp('2024-06-08 14:00:00', tz='Europe/Berlin'),
    pd.Timestamp('2024-06-08 20:00:00', tz='America/New_York')
]

# 各Timestampオブジェクトからタイムゾーン情報を削除し、表示
for timestamp in aware_timestamps:
  local_timestamp = timestamp.tz_localize(None)
  print(f'Before: {timestamp}, After: {local_timestamp}')

このコードを実行すると、以下の出力が得られます。

Before: 2024-06-08 09:00:00+09:00, After: 2024-06-08 09:00:00
Before: 2024-06-08 14:00:00+02:00, After: 2024-06-08 14:00:00
Before: 2024-06-08 20:00:00-04:00, After: 2024-06-08 20:00:00

エラー処理

import pandas as pd

# タイムゾーン情報のないTimestampオブジェクトを作成
naive_timestamp = pd.Timestamp('2024-06-08 00:00:00')

# 無効なタイムゾーン名を指定してエラーを発生させる
try:
  invalid_timestamp = naive_timestamp.tz_localize('Invalid/Timezone')
except Exception as e:
  print(f'エラーが発生しました: {e}')

# 存在するタイムゾーン名を指定して、正常に処理
valid_timestamp = naive_timestamp.tz_localize('America/New_York')
print(f'正常処理: {valid_timestamp}')

エラーが発生しました: Unknown timezone: Invalid/Timezone
正常処理: 2024-06-07 23:00:00-04:00

import pandas as pd

# タイムゾーン情報を持つTimestampオブジェクトを含むマルチレベルインデックスを持つデータフレームを作成
index = pd.MultiIndex.from_tuples([('US', 'NY', '2024-06-08 09:00:00'),
                                 ('Japan', 'Tokyo', '2024-06-08 14:00:00'),
                                 ('Germany', 'Berlin', '2024-06-08 20:00:00')],
                                names=('Country', 'City', 'Date'))
data = pd.Series([98.5,

---

pandas.to_datetime() 関数

pandas.to_datetime() 関数は、文字列や数値を Timestamp オブジェクトに変換するために使用できます。オプションで、タイムゾーン情報も指定できます。

import pandas as pd

# 文字列をTimestampオブジェクトに変換し、タイムゾーン情報 'Asia/Tokyo' を追加
asia_timestamp = pd.to_datetime('2024-06-08 09:00:00', tz='Asia/Tokyo')

# 数値をTimestampオブジェクトに変換し、タイムゾーン情報 'America/New_York' を追加
ny_timestamp = pd.to_datetime(1654646000, unit='s', tz='America/New_York')

print(asia_timestamp)
print(ny_timestamp)

2024-06-08 09:00:00+09:00
2024-06-07 23:00:00-04:00

pytz ライブラリ

pytz ライブラリを使用して、Timestampオブジェクトにタイムゾーン情報を追加または削除することもできます。

import pandas as pd
import pytz

# タイムゾーン情報のないTimestampオブジェクトを作成
naive_timestamp = pd.Timestamp('2024-06-08 00:00:00')

# タイムゾーン情報 'Asia/Tokyo' を追加
asia_timestamp = naive_timestamp.astimezone(pytz.timezone('Asia/Tokyo'))

# タイムゾーン情報 'America/New_York' を削除
ny_timestamp = asia_timestamp.astimezone(pytz.timezone('America/New_York')).tzinfo(None)

print(asia_timestamp)
print(ny_timestamp)

2024-06-08 09:00:00+09:00
2024-06-08 00:00:00

tzinfo 属性

Timestampオブジェクトには tzinfo 属性があり、そのオブジェクトのタイムゾーン情報が格納されています。この属性を使用して、タイムゾーン情報を取得したり設定したりすることができます。

import pandas as pd

# タイムゾーン情報を持つTimestampオブジェクトを作成
aware_timestamp = pd.Timestamp('2024-06-08 09:00:00', tz='Asia/Tokyo')

# タイムゾーン情報を確認
print(aware_timestamp.tzinfo)

# タイムゾーン情報 'America/New_York' を設定
aware_timestamp = aware_timestamp.tz_localize(None).tz_localize('America/New_York')

# 新しいタイムゾーン情報を確認
print(aware_timestamp.tzinfo)

Asia/Tokyo
America/New_York

上記以外にも、dateutil ライブラリや datetime モジュールなど、Timestampオブジェクトにタイムゾーン情報を追加または削除するための方法はいくつかあります。

最適な方法の選択

使用する方法は、状況によって異なります。

• すでに dateutil ライブラリや datetime モジュールを使用している場合は、それらのライブラリ/モジュールで提供されている機能を活用することができます。
• 複雑な操作が必要な場合は、pytz ライブラリや tzinfo 属性を使用する方が柔軟性があります。
• 単純に文字列や数値を Timestamp オブジェクトに変換し、タイムゾーン情報を追加したい場合は、pandas.to_datetime() 関数を使用するのが最も簡単です。

• dateutil ライブラリと datetime モジュールは、標準ライブラリに含まれています。
• pytz ライブラリは、別途インストールする必要があります。
• pandas.Timestamp.tz_localize 関数は、Pandas 0.22.0 で導入されました。

• pytz ドキュメント: