Pandas pd.Timedelta() 関数

pd.Timedelta()はPandasライブラリにおいて、時間差を作成するための関数です。これは2つの時点間の継続時間を表し、日時の加減算に使用できます。

Timedeltaは時間のDuration（期間）を扱う強力なツールで、2つの日付間の差分の計算や、特定の時間長の加算・減算などのシーンでよく使用されます。

単語の意味： Timedelta"time"（時間）と"delta"（変化量）の組み合わせであり、「時間増分」、すなわち一定期間の継続時間を意味します。

基本構文とパラメータ

pd.Timedelta()はPandasライブラリのトップレベル関数で、時間差オブジェクトを作成するために使用されます。

構文形式

pd.Timedelta(value, unit='ns', **kwargs)

パラメータの説明

パラメータ	型	必須かどうか	説明	デフォルト値
value	文字列、int、float、datetime.timedelta	任意	変換する時間差の値。	None
unit	文字列	任意	valueが数値の場合の単位：'D'(日)、'h'(時)、'm'(分)、's'(秒)、'ms'(ミリ秒)、'us'(マイクロ秒)、'ns'(ナノ秒)。	'ns'
days	整数	任意	日数。	0
hours	整数	任意	時間数。	0
minutes	整数	任意	分数。	0
seconds	整数	任意	秒数。	0
milliseconds	整数	任意	ミリ秒数。	0
microseconds	整数	任意	マイクロ秒数。	0
nanoseconds	整数	任意	ナノ秒数。	0

戻り値の説明

戻り値： Timedeltaオブジェクトを返し、時間間隔を表します。
効果：タイムスタンプの加減算、または2つの時点間の差の計算に使用できます。

例

簡単なものから複雑なものまでの一連の例を通して、徹底的にpd.Timedelta()使い方を習得しましょう。

例1: 基本用法 - 時間差の作成

例

import pandas as pd

# 1. 文字列を使用してTimedeltaを作成
print("=== 文字列による時間差の作成 ===")
td1 = pd.Timedelta('1 days')
print(f"pd.Timedelta('1 days'): {td1}")

td2 = pd.Timedelta('2 hours 30 minutes')
print(f"pd.Timedelta('2 hours 30 minutes'): {td2}")

td3 = pd.Timedelta('1 days 02:30:45')
print(f"pd.Timedelta('1 days 02:30:45'): {td3}")

td4 = pd.Timedelta('2 weeks')
print(f"pd.Timedelta('2 weeks'): {td4}")

# 2. キーワード引数を使用して作成
print("n=== キーワード引数による作成 ===")
td5 = pd.Timedelta(days=5, hours=10, minutes=30)
print(f"pd.Timedelta(days=5, hours=10, minutes=30): {td5}")

td6 = pd.Timedelta(hours=1.5)
print(f"pd.Timedelta(hours=1.5): {td6}")

# 3. 数値と単位を使用して作成
print("n=== 数値と単位による作成 ===")
td7 = pd.Timedelta(10, unit='D')
print(f"pd.Timedelta(10, unit='D'): {td7}")

td8 = pd.Timedelta(30, unit='m')
print(f"pd.Timedelta(30, unit='m'): {td8}")

# 4. datetime.timedeltaから変換
print("n=== datetime.timedeltaからの変換 ===")
import datetime
dt_td = datetime.timedelta(days=3, hours=6)
td9 = pd.Timedelta(dt_td)
print(f"datetime.timedeltaから: {td9}")

# 5. Timedeltaの属性を確認
print("n=== Timedelta 属性 ===")
td = pd.Timedelta('3 days 12 hours 30 minutes 45 seconds')
print(f"時間差: {td}")
print(f"総日数: {td.days}")
print(f"総秒数: {td.seconds}")
print(f"総マイクロ秒数: {td.microseconds}")
print(f"総秒数 (小数を含む): {td.total_seconds()}")
print(f"時間に変換: {td.total_seconds() / 3600}")

実行結果:

=== 字符串创建时间差 ===
pd.Timedelta('1 days'): 1 days, 0:00:00
pd.Timedelta('2 hours 30 minutes'): 0 days, 2:30:00
pd.Timedelta('1 days 02:30:45'): 1 days 02:30:45
pd.Timedelta('2 weeks'): 14 days, 0:00:00

=== 关键字参数创建 ===
pd.Timedelta(days=5, hours=10, minutes=30): 5 days 10:30:00
pd.Timedelta(hours=1.5): 0 days, 01:30:00

=== 数值和单位创建 ===
pd.Timedelta(10, unit='D'): 10 days, 0:00:00
pd.Timedelta(30, unit='m'): 0 days, 0:30:00

=== 从 datetime.timedelta 转换 ===
从 datetime.timedelta: 3 days 06:00:00

=== Timedelta 属性 ===
时间差: 3 days 12:30:45
总天数: 3
总秒数: 45045
总微秒数: 45000
总秒数 (含小数): 303045.0
84.17916666666667

コード解説:

pd.Timedelta()複数の作成方法をサポートしています：文字列、キーワード引数、数値+単位、datetime.timedelta。
文字列形式は非常に柔軟で、'1 days'、'2 weeks'、'1 days 02:30:45' などをサポートします。
total_seconds()メソッドは合計秒数（小数部分を含む）を返します。

例2: 時間差の演算

例

import pandas as pd
import numpy as np

# 1. タイムスタンプと時間差の加減算
print("=== タイムスタンプと時間差の演算 ===")
ts = pd.Timestamp('2023-01-01 12:00:00')

td = pd.Timedelta(days=5, hours=3)
print(f"タイムスタンプ: {ts}")
print(f"時間差: {td}")
print(f"ts + td: {ts + td}")
print(f"ts - td: {ts - td}")

# 2. 2つのタイムスタンプを減算して時間差を取得
print("n=== 2つのタイムスタンプの減算 ===")
ts1 = pd.Timestamp('2023-01-15 18:00:00')
ts2 = pd.Timestamp('2023-01-10 09:00:00')

tdiff = ts1 - ts2
print(f"ts1: {ts1}")
print(f"ts2: {ts2}")
print(f"ts1 - ts2: {tdiff}")
print(f"日数差: {tdiff.days}")
print(f"時間差: {tdiff.total_seconds() / 3600}")

# 3. 時間差同士の演算
print("n=== 時間差同士の演算 ===")
td1 = pd.Timedelta(days=2)
td2 = pd.Timedelta(hours=12)

print(f"td1: {td1}")
print(f"td2: {td2}")
print(f"td1 + td2: {td1 + td2}")
print(f"td1 - td2: {td1 - td2}")
print(f"td1 * 2: {td1 * 2}")
print(f"td1 / 2: {td1 / 2}")

# 4. 時間差と数値の演算
print("n=== 時間差と数値の演算 ===")
td = pd.Timedelta(hours=10)
print(f"10時間 * 3 = {td * 3}")
print(f"10時間 / 2 = {td / 2}")
print(f"10時間 // 3 = {td // 3}")

実行結果:

=== 时间戳与时间差运算 ===
时间戳: 2023-01-01 12:00:00
时间差: 5 days 03:00:00
ts + td: 2023-01-06 15:00:00
ts - td: 2022-12-27 09:00:00

=== 两个时间戳相减 ===
ts1: 2023-01-15 18:00:00
ts2: 2023-01-10 09:00:00
ts1 - ts2: 5 days 09:00:00
天数差: 5
小时差: 129.0

=== 时间差之间的运算 ===
td1: 2 days, 0:00:00
td2: 12:00:00
td1 + td2: 2 days 12:00:00
td1 - td2: 1 day, 12:00:00
td1 * 2: 4 days, 0:00:00
td1 / 2: 1 day, 0:00:00

=== 时间差与数值运算 ===
10小时 * 3 = 1 day, 3:00:00
10小时 / 2 = 5:00:00
10小时 // 3 = 3:20:00

コード解説:

タイムスタンプに時間差を加算すると新しいタイムスタンプが得られます。
2つのタイムスタンプを減算すると時間差が得られます。
時間差同士は加算・減算できます。
時間差は数値との乗算・除算ができます。

例3: DataFrameで時間差を使用する

例

import pandas as pd
import numpy as np

# 1. 時間差を持つDataFrameを作成
print("=== 注文処理時間の分析 ===")

# 注文データをシミュレート
df = pd.DataFrame({
'order_id': ['A001', 'A002', 'A003', 'A004', 'A005'],
'order_time': pd.date_range('2023-01-01 09:00', periods=5, freq='2H'),
'process_time_min': [30, 45, 60, 20, 90]
})

# 処理時間をTimedeltaに変換
df['process_timedelta'] = pd.to_timedelta(df['process_time_min'], unit='m')

# 完了時間を計算
df['complete_time'] = df['order_time'] + df['process_timedelta']

print(df)

# 2. 注文処理時間の統計を計算
print("n=== 処理時間の統計 ===")
total_time = df['process_timedelta'].sum()
avg_time = df['process_timedelta'].mean()
print(f"総処理時間: {total_time}")
print(f"平均処理時間: {avg_time}")

# 3. 期限時刻の計算
print("n=== 期限時刻の計算（注文は24時間以内に完了する必要があると仮定）===")
deadline = pd.Timedelta(hours=24)
df['deadline'] = df['order_time'] + deadline
df['is_ontime'] = df['complete_time'] <= df['deadline']
print(df[['order_id', 'order_time', 'complete_time', 'deadline', 'is_ontime']])

# 4. 期限超過の注文を抽出
print("n===期限超過の注文===")
late_orders = df[~df['is_ontime']]
print(f"期限超過の注文数:{len(late_orders)}")
print(late_orders[['order_id', 'complete_time', 'deadline']])

実行結果:

=== 订单处理时间分析 ===
      order_id           order_time  process_time_min          complete_time
0      A001 2023-01-01 09:00:00                 30 2023-01-01 09:30:00
1      A002 2023-01-01 11:00:00                 45 2023-01-01 11:45:00
2      A003 2023-01-01 13:00:00                 60 2023-01-01 14:00:00
3      A004 2023-01-01 15:00:00                 20 2023-01-01 15:20:00
4      A005 2023-01-01 17:00:00                 90 2023-01-01 18:30:00

=== 处理时长统计 ===
总处理时间: 0 days 04:05:00
平均处理时间: 0 days 00:49:00

=== 计算到期时间（假设订单需要在24小时内完成）===
           order_id           order_time         complete_time         deadline  is_ontime
0  A001  2023-01-01 09:00:00  2023-01-01 09:30:00  2023-01-02 09:00:00      True
1  A002  2023-01-01 11:00:00  2023-01-01 11:45:00  2023-01-02 11:00:00      True
2  A003  2023-01-01 13:00:00  2023-01-01 14:00:00  2023-02-01 13:00:00      True
3  A004  2023-01-01 15:00:00  2023-01-01 15:20:00  2023-02-01 15:00:00      True
4  A005 2023-01-01 17:00:00  2023-01-01 18:30:00  2023-02-01 17:00:00      True

=== 超时订单 ===
超时订单数: 0

コード解説:

pd.to_timedelta()数値をTimedeltaに変換できます。
時間差はタイムスタンプとの加減算を簡単に行えます。
総処理時間や平均処理時間などの統計情報を簡単に計算できます。

注意事項

重要なヒント：

pd.Timedelta保存されるのは時間間隔であり、具体的な時点ではありません。

時間差は正の数（未来）または負の数（過去）になります。

とpd.NaT同様に、pd.NaT欠損した時間差を表します。

使用する際は、unitパラメータの数値型が正しいことを確認してください。

Pandas 通用函数 Pandas よく使われる関数

その他の拡張

データの読み書き

データ処理の核心

リファレンスマニュアル

統計とケーススタディ

Pandas pd.Timedelta() 関数

基本構文とパラメータ

構文形式

パラメータの説明

戻り値の説明

例

例1: 基本用法 - 時間差の作成

例

例2: 時間差の演算

例

例3: DataFrameで時間差を使用する

例

注意事項