pandas pd.period_range() 生成时间区间序列

看过来

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

pandas.period_range 是 pandas 中用于生成时间区间序列（PeriodIndex）的函数。它根据指定的起止时间、时间频率等参数，返回一个包含时间区间的 PeriodIndex，广泛用于时间序列分析、频率转换和周期性数据处理。

1. 适用数据类型

适用于生成基于时间区间的序列，常用作索引或数据的时间维度。
返回值是 pandas 的 PeriodIndex，其中每个元素是一个 Period 对象，表示特定的时间区间。

2. 语法

pandas.period_range(
    start=None, 
    end=None, 
    periods=None, 
    freq=None, 
    name=None
)

3. 参数详解

start（可选）
- 起始时间，支持字符串（如 '2024-01'）或 Period 对象。
- 示例：'2024-01-01' 或 pd.Period('2024-01', freq='M')。
end（可选）
- 结束时间，支持字符串或 Period 对象。
periods（可选）
- 时间区间的数量。
- 如果提供了 start 和 end，此参数不能指定。
freq（可选）
- 时间区间的频率，默认为 None。常用频率包括：
  - 'D'：日
  - 'M'：月
  - 'Q'：季度
  - 'Y'：年
  - 'H'：小时
  - 'T'：分钟
  - 'S'：秒
name（可选）
- 返回的 PeriodIndex 的名称。

4. 返回值

返回一个 pandas 的 PeriodIndex 对象。
包含符合条件的时间区间序列。

5. 使用场景

生成时间区间序列：
- 用于时间序列分析，如季度报表分析。
- 构造日期范围以生成时间维度数据。
时间索引：
- 创建时间区间为索引的 DataFrame 或 Series。
周期性数据处理：
- 如统计月度、季度或年度数据。

6. 示例代码

示例 1：生成月份区间

按月生成从 2024 年 1 月到 2024 年 12 月的时间区间：

import pandas as pd

# 生成从 2024 年 1 月到 12 月的月份区间
periods = pd.period_range(start='2024-01', end='2024-12', freq='M')
print(periods)

输出：

PeriodIndex(['2024-01', '2024-02', '2024-03', '2024-04', '2024-05', '2024-06',
             '2024-07', '2024-08', '2024-09', '2024-10', '2024-11', '2024-12'],
            dtype='period[M]')

示例 2：指定周期数量

生成从 2024 年 1 月开始的连续 6 个月：

periods = pd.period_range(start='2024-01', periods=6, freq='M')
print(periods)

输出：

PeriodIndex(['2024-01', '2024-02', '2024-03', '2024-04', '2024-05', '2024-06'],
            dtype='period[M]')

示例 3：生成季度区间

按季度生成从 2023 年 Q1 到 2024 年 Q4 的时间区间：

periods = pd.period_range(start='2023Q1', end='2024Q4', freq='Q')
print(periods)

输出：

PeriodIndex(['2023Q1', '2023Q2', '2023Q3', '2023Q4', '2024Q1', '2024Q2',
             '2024Q3', '2024Q4'],
            dtype='period[Q-DEC]')

示例 4：生成年度区间

生成从 2020 年到 2025 年的年度区间：

periods = pd.period_range(start='2020', end='2025', freq='Y')
print(periods)

输出：

PeriodIndex(['2020', '2021', '2022', '2023', '2024', '2025'], dtype='period[A-DEC]')

示例 5：生成更高频率的区间

生成从 2024-01-01 12:00 开始的 10 个小时区间：

periods = pd.period_range(start='2024-01-01 12:00', periods=10, freq='H')
print(periods)

输出：

PeriodIndex(['2024-01-01 12:00', '2024-01-01 13:00', '2024-01-01 14:00',
             '2024-01-01 15:00', '2024-01-01 16:00', '2024-01-01 17:00',
             '2024-01-01 18:00', '2024-01-01 19:00', '2024-01-01 20:00',
             '2024-01-01 21:00'],
            dtype='period[H]')

示例 6：为时间区间命名

为生成的时间区间命名为 "Quarters":

periods = pd.period_range(start='2023Q1', end='2024Q4', freq='Q', name='Quarters')
print(periods)

输出：

PeriodIndex(['2023Q1', '2023Q2', '2023Q3', '2023Q4', '2024Q1', '2024Q2',
             '2024Q3', '2024Q4'],
            dtype='period[Q-DEC]', name='Quarters')

7. 注意事项

频率必须一致：
- 如果指定了 start 或 end，时间格式需与 freq 一致（如月频率对应 '2024-01'）。
- 不一致会引发 ValueError。
start、end 和 periods 的组合：
- 必须至少指定两个参数（如 start 和 end，或 start 和 periods）。
频率的多样性：
- 支持多种时间频率（如小时、分钟、季度），可以根据分析需求选择合适的频率。

8. 总结

参数情况：

参数	描述
`start`	起始时间，字符串或 `Period` 对象。
`end`	结束时间，字符串或 `Period` 对象。
`periods`	时间区间的数量，与 `start` 或 `end` 配合使用。
`freq`	时间区间的频率（如 `D`、`M`、`Q`、`Y` 等）。
`name`	给返回的 `PeriodIndex` 命名。

常见使用场景：

构建时间维度索引，适合时间序列数据。
生成定期的报表或业务周期数据（如季度、年度统计）。
创建以时间区间为基础的特征列。

参考

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