pandas pd.bdate_range() 生成工作日时间序列

看过来

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

pandas 的 bdate_range 方法用于生成一个以工作日为基础的时间序列。与 date_range 不同，bdate_range 默认会跳过周末，并支持灵活定义工作日掩码和节假日。这对于金融数据分析、业务时间表管理等场景非常有用。

适用数据类型

适用于需要生成工作日序列的场景。
返回一个 DatetimeIndex 对象，用于创建时间索引或构造时间序列数据。

函数语法

pandas.bdate_range(
    start=None, 
    end=None, 
    periods=None, 
    freq='B', 
    tz=None, 
    normalize=True, 
    name=None, 
    weekmask=None, 
    holidays=None, 
    inclusive='both', 
    **kwargs
)

参数详解

主要参数

start（可选）
- 起始日期，支持字符串或 datetime 对象。
- 示例：'2024-01-01' 或 pd.Timestamp('2024-01-01')。
end（可选）
- 结束日期，支持字符串或 datetime 对象。
periods（可选）
- 要生成的日期数量，不能和 end 同时指定。
freq（可选，默认为 'B'）
- 时间间隔的频率，'B' 表示标准工作日。
- 其他可选值如 'C' 表示自定义工作日频率（需结合 weekmask 和 holidays）。
tz（可选）
- 设置时区，支持字符串（如 'UTC'）或 pytz 对象。
normalize（可选，默认为 True）
- 是否将生成的日期时间规范化为日期（时分秒归零）。
name（可选）
- 给返回的 DatetimeIndex 命名。
weekmask（可选）
- 自定义工作日掩码，字符串形式定义哪些天是工作日。
- 示例："Mon Tue Wed Thu Fri" 表示周一到周五是工作日。
holidays（可选）
- 指定额外的节假日日期，格式为日期列表或数组。
inclusive（可选，默认为 'both'）
- 指定是否包括起始日期和结束日期：
  - 'both'：包含起始和结束日期。
  - 'left'：只包含起始日期。
  - 'right'：只包含结束日期。
  - 'neither'：两者都不包含。

返回值

返回一个 Pandas 的 DatetimeIndex 对象。
包含符合条件的工作日序列。

使用场景

生成以工作日为基础的时间序列：
- 用于金融数据分析（股票交易日等）。
- 构造业务时间表（如周一至周五的任务安排）。
自定义工作日规则：
- 跳过特定节假日。
- 定义特定的工作日（如仅包含周一到周四）。

示例代码

示例 1：生成默认工作日序列

import pandas as pd

# 生成从 2024-01-01 到 2024-01-10 的工作日序列
bdates = pd.bdate_range(start='2024-01-01', end='2024-01-10')
print(bdates)

输出：

DatetimeIndex(['2024-01-01', '2024-01-02', '2024-01-03', '2024-01-04',
               '2024-01-05', '2024-01-08', '2024-01-09', '2024-01-10'],
              dtype='datetime64[ns]', freq='B')

说明：

默认频率为 'B'，仅包含工作日。
跳过了周末（2024-01-06 和 2024-01-07）。

示例 2：生成指定数量的工作日

# 从起始日期开始，生成 7 个工作日
bdates = pd.bdate_range(start='2024-01-01', periods=7)
print(bdates)

输出：

DatetimeIndex(['2024-01-01', '2024-01-02', '2024-01-03', '2024-01-04',
               '2024-01-05', '2024-01-08', '2024-01-09'],
              dtype='datetime64[ns]', freq='B')

示例 3：设置自定义时区

# 生成带有时区的工作日序列
bdates = pd.bdate_range(start='2024-01-01', end='2024-01-10', tz='UTC')
print(bdates)

输出：

DatetimeIndex(['2024-01-01 00:00:00+00:00', '2024-01-02 00:00:00+00:00',
               '2024-01-03 00:00:00+00:00', '2024-01-04 00:00:00+00:00',
               '2024-01-05 00:00:00+00:00', '2024-01-08 00:00:00+00:00',
               '2024-01-09 00:00:00+00:00', '2024-01-10 00:00:00+00:00'],
              dtype='datetime64[ns, UTC]', freq='B')

示例 4：自定义工作日规则

# 定义周一到周四为工作日，跳过周五和周末
bdates = pd.bdate_range(
    start='2024-01-01',
    end='2024-01-10',
    weekmask='Mon Tue Wed Thu'
)
print(bdates)

输出：

DatetimeIndex(['2024-01-01', '2024-01-02', '2024-01-03', '2024-01-04',
               '2024-01-08', '2024-01-09'],
              dtype='datetime64[ns]', freq='C')

示例 5：加入节假日规则

# 自定义节假日
holidays = ['2024-01-02', '2024-01-08']
bdates = pd.bdate_range(
    start='2024-01-01',
    end='2024-01-10',
    holidays=holidays
)
print(bdates)

输出：

DatetimeIndex(['2024-01-01', '2024-01-03', '2024-01-04', '2024-01-05',
               '2024-01-09', '2024-01-10'],
              dtype='datetime64[ns]', freq='C')

总结

bdate_range 是一个非常强大的工具，适合生成符合业务规则的时间序列。它的灵活性表现在：

支持跳过周末、节假日。
自定义工作日规则（如指定工作日范围）。
结合时区、节假日和名称标签。

适用于金融数据分析、项目计划管理等需要精准控制工作日的场景。

参考

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