Python: to_timedeltaの理解を深める

業務中、既存コードでto_timedeltaが使われているのを目にしたものの、いまいち使い方がピンと来なかったので、調べながら動かしてみました。

そもそもタイムデルタ (timedelta) とは？

日付や時刻の「差」を表すデータ型になります。例えば、「2日間」や「1時間30分」といった、2つの日時の間隔や特定の期間を示すために使われます。このデータ型は、日付や時刻を操作したり、指定期間分だけ日時を加減する際に便利です。

to_timedeltaの使い方

まずはタイムデルタを作るところからみていきます。

1. 単体の期間をタイムデルタに変換する

pd.to_timedeltaに、ある一定の期間を文字列で直接渡すことでタイムデルタを生成できます。（一応、変換後の型も確認。）

import pandas as pd

# 1時間30分10秒のタイムデルタを作成
td = pd.to_timedelta('1 hour 30 minutes 10 seconds')

print(td)
print(type(td))

出力結果

2. 複数の期間をタイムデルタに変換する

リストデータやDataFrameの特定カラムに対してto_timedeltaを使うことで、文字列の時間データを一括で変換できます。

# タイムデルタに変換するリストデータ
durations = ['1 day', '2 days', '5 hours', '10 minutes']

# リストの文字列をTimedeltaに変換
td_list = pd.to_timedelta(durations)

print(td_list)

出力結果

# タイムデルタに変換するデータフレーム
data = {'task_duration': ['2 hours 30 min', '1 day', '10 hours']}
df = pd.DataFrame(data)

# データフレームの文字列をTimedeltaに変換
df['task_duration'] = pd.to_timedelta(df['task_duration'])

print(df)

出力結果

次に、変換したタイムデルタの用途についてみていきます。

3. Datetime型との加算・減算

to_timedeltaで作成した時間差をDatetime型データに加算・減算して、新しい日時を計算できます。

# 現在の日時から5時間後の日時を計算
now = pd.Timestamp.now(tz='Asia/Tokyo')
time_new = now + pd.to_timedelta('5 hours')

print(time_new)

出力結果

4. 数値データをタイムデルタに変換

数値データが「秒」「分」「時間」などを表している場合、unitに時間単位を指定すれば、to_timedeltaでタイムデルタに変換することができます。たとえば、システムのログで経過秒数が記録されている場合や、集計データで時間や日数が数値で記録されている場合に使えますね。

# 数値データから時間に変換
df_seconds = pd.DataFrame({'seconds': [3600, 7200, 10800]})
df_seconds['duration'] = pd.to_timedelta(df_seconds['seconds'], unit='s')

print(df_seconds)

出力結果

活用事例

業務で分析用データを加工する際、以下のような処理にここでの学びを活かすことができました。イベント開始日と、イベント開催期間（日数）を示す数値が入ったデータをサンプルとします。

import pandas as pd

# サンプルデータの作成
date = pd.date_range(start='2024/11/15', end='2024/11/20', freq='d')

# データフレームの作成
df_event = pd.DataFrame({'start_date': date, 'period':[2,3,4,5,6,7]})

print(df_event)

出力結果

# イベント終了日とイベント開始日の差を求める
df_event['gap'] = df_event['period'] - 1

# イベント開始日と終了日までの日数差から、イベント終了日を計算する
df_event['end_date'] = df_event['start_date'] + pd.to_timedelta(df_event['gap'], unit='d')

print(df_event)

出力結果

このように、期間を表す数値をタイムデルタに変換し、日付データを加工する際などに重宝しそうだなと思いました。これからも積極的に活用して、分析の幅を広げていきたいです。

※ この記事の一部は、ChatGPTを活用して調査した情報をもとに作成しています。ただし、掲載したコードはGoogle Colab上で実行し、出力結果を確認した上で掲載しています。読者の皆さまが再現できるよう、正確な情報提供に努めています。内容についてご指摘やお気づきの点がございましたら、ぜひコメントいただけると幸いです。