pandas pd.timedelta_range() 生成时间差范围序列

看过来

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

pandas.timedelta_range 是 pandas 中用于生成时间差范围序列（TimedeltaIndex）的函数，可以根据指定的起止时间、步长或时间间隔等参数生成一组连续的时间差值。常用于时间序列分析和操作时间差数据。

1. 适用数据类型

适用于生成基于时间差的序列。
返回一个 TimedeltaIndex 对象，每个元素是一个 Timedelta，表示一个时间间隔。

2. 语法

pandas.timedelta_range(
    start=None, 
    end=None, 
    periods=None, 
    freq=None, 
    name=None, 
    closed=None, 
    *,
    unit=None
)

3. 参数详解

主要参数：

start（可选）
- 起始时间差，支持字符串（如 '1D'）、Timedelta 对象或数字（需配合 unit 使用）。
- 示例：'1 days' 或 pd.Timedelta(days=1)。
end（可选）
- 结束时间差，与 start 配合指定范围。
periods（可选）
- 时间差的数量。
- 如果指定了 start 和 end，此参数不能使用。
freq（可选，默认为 'D'）
- 时间差的步长或频率，支持 Pandas 的频率字符串（如 'H' 表示每小时）。
- 常见值：
  - 'D'：天
  - 'H'：小时
  - 'T'：分钟
  - 'S'：秒
  - 'ms'：毫秒
  - 'us'：微秒
  - 'ns'：纳秒
name（可选）
- 为返回的 TimedeltaIndex 命名。
closed（可选，默认为 None）
- 指定是否包含边界：
  - 'left'：仅包含左边界。
  - 'right'：仅包含右边界。
  - None：包含两端。
unit（仅在未指定 freq 时使用，可选）
- 指定单位，用于解析 start 和 end 中的数字值：
  - 'D'：天
  - 'h'：小时
  - 'm'：分钟
  - 's'：秒
  - 'ms'：毫秒
  - 'us'：微秒
  - 'ns'：纳秒

4. 返回值

返回一个 Pandas 的 TimedeltaIndex 对象。
包含符合条件的时间差序列。

5. 使用场景

生成时间间隔序列：
- 用于分析定时任务、连续时间间隔数据等。
时间差计算与操作：
- 构建时间差维度，用于时间序列数据的处理。
时间索引：
- 为时间间隔数据构造索引。

6. 示例代码

示例 1：生成默认时间间隔

生成从 1 天到 10 天的时间间隔，步长为 1 天（默认频率）：

import pandas as pd

# 从 1 天到 10 天，每天一个时间间隔
timedeltas = pd.timedelta_range(start='1D', end='10D')
print(timedeltas)

输出：

TimedeltaIndex(['1 days', '2 days', '3 days', '4 days', '5 days', '6 days',
                '7 days', '8 days', '9 days', '10 days'],
               dtype='timedelta64[ns]', freq='D')

示例 2：指定时间间隔的数量

从 1 小时开始，生成 5 个时间间隔：

timedeltas = pd.timedelta_range(start='1H', periods=5, freq='H')
print(timedeltas)

输出：

TimedeltaIndex(['0 days 01:00:00', '0 days 02:00:00', '0 days 03:00:00',
                '0 days 04:00:00', '0 days 05:00:00'],
               dtype='timedelta64[ns]', freq='H')

示例 3：指定频率

按分钟生成从 5 分钟到 30 分钟的时间间隔：

timedeltas = pd.timedelta_range(start='5T', end='30T', freq='5T')
print(timedeltas)

输出：

TimedeltaIndex(['0 days 00:05:00', '0 days 00:10:00', '0 days 00:15:00',
                '0 days 00:20:00', '0 days 00:25:00', '0 days 00:30:00'],
               dtype='timedelta64[ns]', freq='5T')

示例 4：使用单位解析数字值

如果 start 和 end 是数字值，可以通过 unit 参数指定时间单位：

timedeltas = pd.timedelta_range(start=1, end=10, freq='D', unit='D')
print(timedeltas)

输出：

TimedeltaIndex(['1 days', '2 days', '3 days', '4 days', '5 days', '6 days',
                '7 days', '8 days', '9 days', '10 days'],
               dtype='timedelta64[ns]', freq='D')

示例 5：闭区间控制

生成从 1 天到 5 天的时间间隔，仅包含右边界：

timedeltas = pd.timedelta_range(start='1D', end='5D', closed='right')
print(timedeltas)

输出：

TimedeltaIndex(['2 days', '3 days', '4 days', '5 days'],
               dtype='timedelta64[ns]', freq='D')

示例 6：为时间间隔命名

为生成的时间间隔序列命名为 "Intervals"：

timedeltas = pd.timedelta_range(start='1H', periods=5, freq='H', name='Intervals')
print(timedeltas)

输出：

TimedeltaIndex(['0 days 01:00:00', '0 days 02:00:00', '0 days 03:00:00',
                '0 days 04:00:00', '0 days 05:00:00'],
               dtype='timedelta64[ns]', freq='H', name='Intervals')

7. 注意事项

参数互斥性：
- 如果指定了 start 和 end，则 periods 不能同时指定。
频率和单位的区别：
- freq 定义时间间隔的步长（如 'D'、'H'）。
- unit 用于解析 start 和 end 的数值含义（如 'D' 表示天）。
时间差的范围：
- timedelta_range 支持从毫秒到数年的时间差范围。

8. 总结

参数	描述
`start`	起始时间差，支持字符串或数字。
`end`	结束时间差，支持字符串或数字。
`periods`	时间间隔的数量，与 `start` 或 `end` 配合使用。
`freq`	时间间隔的频率（如 `'H'`、`'T'`、`'D'`）。
`name`	为返回的 `TimedeltaIndex` 命名。
`closed`	指定是否包含边界（`'left'`、`'right'` 或 `None`）。
`unit`	指定单位，用于解析数字形式的 `start` 和 `end`。

常见使用场景：

构造时间间隔序列，用于定时任务或实验周期管理。
为时间差数据生成索引，进行基于时间间隔的计算。
数据分析中，生成特定步长的时间维度。

参考

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

< pandas pd.period_range() 生成时间区间序列 pandas 时间序列数据类型

更新时间：2024-12-07 09:44:10 标签：pandas python 时长