Pandas pd.Timedelta() 函数

pd.Timedelta() 是 Pandas 库中用于创建时间差的函数。它表示两个时间点之间的持续时间，可以用于日期时间的加减运算。

Timedelta 是处理时间Duration的有力工具，常用于计算两个日期之间的差值、添加或减去特定的时间长度等场景。

单词释义： 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 对象，表示时间间隔。
效果：可以用于时间戳的加减运算，或计算两个时间点之间的差值。

实例

让我们通过一系列从简单到复杂的例子，彻底掌握 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. 两个时间戳相减得到时间差
print("n=== 两个时间戳相减 ===")
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

代码解析:

时间戳加上时间差得到新的时间戳。
两个时间戳相减得到时间差。
时间差之间可以相加、相减。
时间差可以与数值相乘、相除。

示例 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 中使用时间差

实例

注意事项