pandas pd.to_timedelta() 转换为时长

看过来

《pandas 教程》持续更新中，提供建议、纠错、催更等加作者微信: gairuo123（备注：pandas教程）和关注公众号「盖若」ID: gairuo。跟作者学习，请进入 Python学习课程。欢迎关注作者出版的书籍：《深入浅出Pandas》和《Python之光》。

pandas.to_timedelta 函数用于将各种数据类型转换为 pandas.Timedelta 对象，这是一个表示时间差或持续时间的数据类型。该函数在处理时间序列数据时非常有用，尤其是当需要进行时间差异计算时。

语法

将参数转换为时间增量。时间增量是时间的绝对差异，以差异单位表示（例如天、小时、分钟、秒）。此方法将参数从可识别的timedelta格式/值转换为timedelta类型。

pandas.to_timedelta(
    arg,
    unit=None,
    errors='raise'
)

如果精度高于纳秒，则字符串输入的持续时间精度将截断为纳秒。

参数意义

arg：要转换为 Timedelta 的数据。可以是单个字符串、列表、Series、数字或 timedelta 对象。
unit：指定时间单位，用于解释数字输入数据。常见单位包括：
- 'Y'：年
- 'M'：月
- 'D'：天
- 'h'：小时
- 'm'：分钟
- 's'：秒
- 'ms'：毫秒
- 'us'：微秒
- 'ns'：纳秒
- 如果 arg 是字符串，则忽略 unit 参数。
errors：指定如何处理无法解析的输入数据。
- 'raise'（默认）：遇到错误时抛出异常。
- 'coerce'：无法解析的数据会被转换为 NaT。
- 'ignore'：返回输入数据，不进行任何转换。

unit 的别名有：

‘W’
‘D’ / ‘days’ / ‘day’
‘hours’ / ‘hour’ / ‘hr’ / ‘h’ / ‘H’
‘m’ / ‘minute’ / ‘min’ / ‘minutes’ / ‘T’
‘s’ / ‘seconds’ / ‘sec’ / ‘second’ / ‘S’
‘ms’ / ‘milliseconds’ / ‘millisecond’ / ‘milli’ / ‘millis’ / ‘L’
‘us’ / ‘microseconds’ / ‘microsecond’ / ‘micro’ / ‘micros’ / ‘U’
‘ns’ / ‘nanoseconds’ / ‘nano’ / ‘nanos’ / ‘nanosecond’ / ‘N’

返回值

返回值是一个 pandas.Timedelta 或 pandas.Series，具体取决于输入的类型。如果输入是单个时间字符串或数字，则返回 Timedelta。

示例讲解

将单个字符串解析为Timedelta：

pd.to_timedelta('1 days 06:05:01.00003')
# Timedelta('1 days 06:05:01.000030')
pd.to_timedelta('15.5us')
# Timedelta('0 days 00:00:00.000015500')

解析字符串列表或数组：

pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
'''
TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015500', NaT],
               dtype='timedelta64[ns]', freq=None)
'''

解析字符串列表或数组：

pd.to_timedelta(np.arange(5), unit='s')
'''
TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
                '0 days 00:00:03', '0 days 00:00:04'],
               dtype='timedelta64[ns]', freq=None)
'''

pd.to_timedelta(np.arange(5), unit='d')
'''
TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],
               dtype='timedelta64[ns]', freq=None
'''

使用场景与例子

场景 1：将字符串转换为 Timedelta

import pandas as pd

# 示例数据
time_str = "2 days 3 hours 4 minutes"

# 转换为 Timedelta
result = pd.to_timedelta(time_str)

print(result)

输出：

'''
2 days 03:04:00
'''

场景 2：将整数转换为 Timedelta

import pandas as pd

# 示例数据
time_int = 5

# 转换为 Timedelta（单位为天）
result = pd.to_timedelta(time_int, unit='D')

print(result)

输出：

'''
5 days 00:00:00
'''

场景 3：处理包含时间字符串的 Series

import pandas as pd

# 示例数据
time_series = pd.Series(["1 days 2 hours", "3 days", "4 hours 30 minutes"])

# 转换为 Timedelta Series
result = pd.to_timedelta(time_series)

print(result)

输出：

'''
0   1 days 02:00:00
1   3 days 00:00:00
2   0 days 04:30:00
dtype: timedelta64[ns]
'''

场景 4：处理无法解析的时间字符串

import pandas as pd

# 示例数据
time_series = pd.Series(["1 days 2 hours", "invalid", "4 hours 30 minutes"])

# 使用 errors='coerce' 参数处理错误
result = pd.to_timedelta(time_series, errors='coerce')

print(result)

输出：

'''
0   1 days 02:00:00
1                 NaT
2   0 days 04:30:00
dtype: timedelta64[ns]
'''

场景 5：将秒数转换为 Timedelta

import pandas as pd

# 示例数据
time_seconds = 3600  # 3600 秒

# 转换为 Timedelta（单位为秒）
result = pd.to_timedelta(time_seconds, unit='s')

print(result)

输出：

'''
0 days 01:00:00
'''

通过以上例子可以看出，pandas.to_timedelta 是一个非常灵活的函数，可以处理各种时间数据格式，并且支持处理错误情况。它可以帮助我们在时间序列数据分析中，轻松地处理时间差异和持续时间。

参考

https://pandas.pydata.org/docs/reference/api/pandas.to_timedelta.html