Pandas resample()完全指南：时间序列粒度变换与业务应用

先说个场景。我手头有一份某电商平台五分钟粒度的交易流水，整整三个月，大概几十万行。业务方要的是三个视图：每日销售额趋势、每周各品类销量占比、每月客单价变化。用循环去按天切片再聚合，跑一次要几分钟，而且代码丑得没法维护。后来换了DataFrame.resample()，整个分析脚本从几十行缩到几行，运行时间降到秒级。

这篇文章就围绕resample()展开，目标是把"时间序列粒度变换"这件事讲透：它和groupby()是什么关系、rule参数怎么写才不会错、closed和label到底怎么影响结果、聚合时怎么对不同字段分别处理、以及那些我在实际业务里踩过并已经修好的坑。适合两类读者：一是刚接触 pandas 时间序列、被各种文档绕晕的新手；二是已经在用resample()但偶尔对边界情况心里没底、想查漏补缺的进阶用户。

1. DataFrame.resample() 到底在解决什么问题

1.1 它本质上是"带时间感知的 groupby"

先下一个结论：resample()不是什么全新的黑科技，它本质上就是groupby()的一个特殊变体。普通groupby()是按某一列的值（比如用户ID、商品类目）把行分成组；resample()则是按时间间隔把行分成组。唯一的区别是，分组键不是现成的列，而是根据时间索引动态"切"出来的。

拿五日线图的价格变化来说，groupby()面对的是"把每个交易日当成一组"，而resample()面对的是"把每个小时当成一组"。理解这一点后，resample()的所有行为就都说得通了：它返回的对象支持agg()、transform()、apply()，这些和groupby()返回的GroupBy对象几乎一样的接口。

我这里强调是 DataFrame 的resample()而不是 Series 的版本，关键在于：DataFrame 版本可以同时对多个列做不同粒度的降采样，而且每列可以指定不同的聚合方式。Series.resample()只能处理一列数据，做单值聚合。实际业务里你几乎总是需要同时看销售额、订单数、用户数几个指标，所以 DataFrame 版本才是真正的主力。

1.2 完整链路：从原始数据到聚合结果

一个标准的resample()调用链是这样的：

import pandas as pd # 假设 df 是五分钟粒度的交易数据，索引为 DatetimeIndex df_resampled = ( df .set_index('trade_time') # 1. 确保时间列成为索引 .resample('D') # 2. 定义时间分组规则，D 表示按自然日 .agg({ 'order_id': 'count', # 订单数 'amount': 'sum', # 销售额 'user_id': 'nunique' # 活跃用户数 }) )

三步拆解：

1. 确保时间列在索引中。resample()默认以索引作为时间来源，如果时间在普通列里，需要先set_index()。还可以用on='trade_time'参数直接指定普通列，但会稍微影响后续操作，我一般还是习惯把时间放到索引上。
2. 定义分组周期。'D'表示按天，这是最常用的频率字符串，后面会展开讲。
3. 聚合计算。.agg()接收字典，每个字段独立指定聚合方式。更复杂的例子，还能传一个字典的嵌套结构，实现对同一字段的多次聚合。

使用过程中最值得注意的是第 2 步：rule的写法直接决定分组边界。下面我会专门拆开讲。

2. rule参数深挖：时间分组到底是怎么切出来的

2.1 频率字符串写法与常见误区

resample('D')里的'D'是 pandas 的频率别名。常见的如下表所示：

频率前可以加数字，表示倍率：'2H'是每两小时，'10T'是每十分钟，'3D'是每三天。也能组合多个偏移量：'2H30T'表示每 2 小时 30 分钟，这在轮班数据分析时非常实用。

最容易踩坑的是'W'和'M'的边界认定。'W'默认以周日为每周的最后一天，也就是分组边界是周日。如果你做的是财务管理，周一为一周起点，那要用'W-MON'。写法里的MON表示"以周一作为一周结束日"，分组区间就是上一个周一到这个周一。开个脑洞：resample('W-FRI')按"周五到下周五"分组，在美国零售数据里很常见，因为他们的销售周通常到周六或周日结束，但有些报表从周五开始。

'M'的坑也不小：'M'生成的时间标签是每个月最后一天，比如 2025-01-31，但分组实际覆盖的区间是该月全部数据。如果某个自然月最后一天恰好是周末，你会看到标签日期是 2025-02-28 这种，但区间还是 2 月 1 日到 2 月 28 日。还有'MS'，表示月初，标签是 2025-02-01。这两个在写报表时非常容易混淆。

2.2 closed 和 label 参数：左开右闭的实际影响

resample()默认的时间区间是左边开右边闭，换句话说，一个组的起点不属于该组，终点属于该组。但对大多数人来说，默认逻辑恰好是反着的。来看例子：

df.resample('D', closed='right', label='right').sum()

上面的写法中closed='right'表示左开右闭，label='right'表示用区间右端点作为结果索引。这是默认配置吗？不是。默认配置对'D'来说是closed='right', label='right'，但对某些偏移量，pandas 会自行调整。这导致同样一份数据，替换了 rule 之后，结果可能突然多一条或少一条。

碰到这种情况，我的排查方法是：先打印重采样之后索引的边界日期，看和自己预期是否一致。如果多了 00:00:00 那一条空数据，往往是 closed 参数设置不对。以五分钟聚合成小时为例，如果用默认参数，23:55 那条数据会被归到 00:00:00 那组？不会，默认左开右闭，23:55 在 23:00 那小时区间 (23:00, 00:00] 内。但如果你改了 closed='left'，部分数据会被切到下一组。

实际建议：做日、周、月等低频聚合时，保持默认即可。做小时、分钟这种高频聚合时，确认一下你想要的边界到底是整点还是整点后一秒。我自己在聚合轮班生产数据时，喜欢显式写出closed='left'和label='left'，因为轮班的换班时间点通常是一个小时的第一秒，不把这一秒丢给下一个班次。

2.3 origin 参数：处理跨日、跨周分组的边界修正

再进阶一点，resample()还有一个origin参数，用来控制分组的起始参照点。默认的 origin 是'start_day'，即每天零点作为分组起点。但有些业务的时间零点不是 00:00:00。比如我们公司有个排班系统，白班从早上 8 点开始，夜班从晚上 20 点开始。要按班次聚合，直接用'12H'重采样会在 00:00 和 12:00 切分，但业务上一白一夜的分界点在 08:00 和 20:00。

此时用origin参数：

df.resample('12H', origin='08:00').sum()

这样分组就会变成 08:00-20:00 一组，20:00-次日 08:00 一组（前提是关闭 label 的默认偏差，必要时配合offset调整标签显示）。这个参数对于跨时区业务同样重要，后面时区部分我再展开。

resample()还有offset参数，通常用来偏移生成的标签。origin是切分组边界的参照，offset只是把标签挪个位置。这两个概念经常被混为一谈，实际分主次：先按origin切分组，再按offset改标签显示。如果您要的是"标签显示 8 点，但分组从 0 点切到 24 点"，用offset就够了。

3. 聚合方式：从单个聚合到字段级的多维控制

3.1 agg() 与字典式写法：一次重采样，多种聚合

DataFrame.resample()最强大的一点在于.agg()可以接受一个字典，每个字段独立定义聚合方式：

daily = df_day.resample('D').agg({ 'order_id': 'count', 'amount': ['sum', 'mean'], 'duration_sec': ['sum', 'max'], 'user_id': 'nunique' })

这种写法的结果是一个多级列索引的 DataFrame，顶层是字段名，第二层是聚合函数名，比如('amount', 'sum')。输出表格的可读性比groupby()后的多级列好不少，直接把.columns拉平即可：

daily.columns = ['_'.join(col).strip('_') for col in daily.columns]

得到order_id_count、amount_sum、amount_mean这样的列名，非常适合直接接 Excel 或 BI 工具。这里想提一句：如果只用.sum()或.mean()单一函数，会得到普通 DataFrame，列名保持原样。混合使用字典和列表时，列名才会变成多级。我用.agg()几乎总是上面这种写法，因为数据分析时很少只关心单一指标。

3.2 命名聚合的简化技巧：NamedAgg

如果不想处理多级列，pandas 还提供了命名聚合：pd.NamedAgg(column=..., aggfunc=...)。这个功能语法上稍微啰嗦一点，但结果列名干净：

daily_named = df_day.resample('D').agg( order_cnt=pd.NamedAgg(column='order_id', aggfunc='count'), amount_sum=pd.NamedAgg(column='amount', aggfunc='sum'), amount_avg=pd.NamedAgg(column='amount', aggfunc='mean'), active_users=pd.NamedAgg(column='user_id', aggfunc='nunique') )

结果列名是order_cnt、amount_sum、amount_avg、active_users。这种方式的可读性非常好，但如果字段特别多，写起来会有点长。我的习惯是：3 到 4 个指标之内用 NamedAgg，字段超过 5 个就用字典加拉平操作，后者批量修改列名更灵活。

3.3 自定义聚合函数与性能注意

aggfunc可以传自定义函数，比如：

def peak_hour_orders(series): # 返回订单量最高的小时数 return series.index.hour[series.values.argmax()] result = df_order.resample('D').agg( peak_hour=pd.NamedAgg(column='order_id', aggfunc=peak_hour_orders) )

这个函数接收的是每个时间分组内的 Series，返回一个标量。业务上你还能做更多复杂逻辑，比如"计算每个时段的最大连续在线时长"、"识别每个交易日的首单时间"等，只要入参是 Series、出参是标量即可。需要注意：自定义函数的性能远低于内置聚合，数据量大时建议先用向量化操作粗筛，再在聚合里做精细计算。比如自定义函数内部尽量别用 Python 循环，能改成Series内置方法就改。

还有一点小坑：aggfunc传字符串'sum'和传函数np.sum或pd.sum的行为不是完全等价的。字符串'sum'会走 pandas 的优化路径，遇到缺失值时默认跳过；np.sum会把 NaN 传播出去。也就是np.sum遇到一个 NaN，整个和就是 NaN。我在处理含缺失时间点的数据时习惯用字符串形式或者min_count参数，避免因为一个空洞让整条聚合结果变成 NaN。

4. 实战：五分钟交易数据在日、周、月三个粒度上的聚合

4.1 数据准备与检查

模拟的不是真实数据，但结构接近我处理过的业务数据：五分钟粒度，三个字段：order_id（订单号）、amount（金额）、user_id（用户标识）。

import pandas as pd import numpy as np np.random.seed(42) time_index = pd.date_range('2025-01-01 00:00', '2025-03-31 23:55', freq='5T') n = len(time_index) df = pd.DataFrame({ 'order_id': ['ORD' + str(i).zfill(8) for i in range(n)], 'amount': np.round(np.random.uniform(50, 500, n), 2), 'user_id': np.random.choice([f'U{i:04d}' for i in range(2000)], n) }, index=time_index)

这只是示例，真实数据里通常有白天订单多、凌晨几乎没有的强烈波动，这里简化处理，因为核心是演示重采样逻辑。实际动手前我一般先检查三件事：

1. 索引是不是DatetimeIndex：df.index的类型必须是DatetimeIndex，否则resample()报错。
2. 索引是否单调递增：非单调索引会导致按时间分组时顺序混乱，结果没法看。
3. 是否有重复的时间戳：重复会直接放大某组的数量，如果存在需要先df = df[~df.index.duplicated()]消除。

4.2 日粒度聚合与缺失时间点处理

直接聚合成日：

daily = df.resample('D').agg({ 'order_id': 'count', 'amount': 'sum', 'user_id': 'nunique' })

结果的索引是每天的自然日。这里有个常见情况：因为我们的原始数据每分钟都有记录，所以每天都有值，但如果原始数据存在某天无记录，重采样后这一天的结果是 NaN（有的函数是空值），这时用.fillna(0)补上。但注意，nunique的 NaN 填充为 0 没问题，sum的 NaN 填充为 0 也没问题。用min_count可以控制：df.resample('D').sum(min_count=1)意味着只要组内没有非 NaN 记录，结果就是 NaN，而不是 0。这样你做"缺失天数标记"分析时能有差别。

另一个细节是，聚合后的索引是时间戳，比如 2025-01-01 00:00:00。如果想变成日期字符串，可以：daily.index = daily.index.strftime('%Y-%m-%d')或daily.index = daily.index.normalize()。我推荐保留时间戳格式，因为后续画图、连接其他日期表时时间戳是标准类型，字符串反而碍事。

4.3 周粒度与月粒度聚合的边界效应

按周聚合：

weekly = df.resample('W-MON').agg({ 'order_id': 'count', 'amount': 'sum', 'user_id': 'nunique' })

'W-MON'的含义是每个周一作为分组终点，也就是一共包含上一个周一到这个周一的记录。这个在"以周为销售周期"的业务中很常用。但由于默认label='right'，结果索引显示的是周一。如果要索引显示为周日的日期，改成label='left'，不过它会显示上一个周日的日期——对阅读来说不一定好看。更清晰的做法是生成"周起始日 + 周序号"的列：

weekly['week_start'] = weekly.index - pd.Timedelta(days=6) weekly['week_num'] = weekly.index.isocalendar().week

这里isocalendar().week返回 ISO 周序号，非常简单。

按月聚合：

monthly = df.resample('M').agg({ 'order_id': 'count', 'amount': 'sum', 'user_id': 'nunique' })

注意，'M'的索引会是月末日期。如果业务上习惯月初展示，可以用'MS'：

monthly_ms = df.resample('MS').agg({ 'order_id': 'count', 'amount': 'sum', 'user_id': 'nunique' })

这两个差别只有一点：标签是月初还是月末。但很多人在这上面栽过。我可以提供一个小技巧：不要改代码里的 rule 去硬拗，直接在结果上转一下：

monthly_display = monthly.copy() monthly_display.index = monthly_display.index.to_period('M').to_timestamp('M')

这里用了to_period('M')把时间戳变为月度周期，再用to_timestamp('M')转回月末时间戳。本质上还是月末，但代码意图更明确。

4.4 用 asfreq() 做纯降采样，不做聚合

resample()对应agg()是用函数压缩数据。但有时你不想聚合，只想把高频数据变成低频数据的采样格式——比如从五分钟取每个小时最后一行的数值，这种叫asfreq()：

hourly_last = df.resample('H').asfreq()

这相当于每个小时组内取最后一条记录，其他行丢弃。注意，这会保留原始值，不加任何统计。对于传感器数据，想在每个小时记录一次瞬时值，asfreq()很方便。但务必确认原始数据的时间点是否正好排在组内末尾，否则取到的可能不是你想留的那个点。

5. 时间序列重采样的常见坑与修复方案

5.1 非单调时间索引与重复时间戳

最常报错的是：

ValueError: Index must be monotonic

原因为索引没排序或有重复。修复：

df = df.sort_index() df = df[~df.index.duplicated(keep='last')]

关于重复时间戳我多说一句：keep='last'会在同日同时刻出现多条记录时保留最后一条，适合"取最终状态"的场景。如果业务上重复时间戳代表同一时刻的不同用户行为，那应该先按用户粒度聚合，再做时间重采样，而不是简单去重。比如一个订单在同一时刻有两条支付流水，聚合前先按order_id去重，避免金额被翻倍。

5.2 时区与夏令时：看不见的"隐形重采样"

DataFrame 的索引带有时区信息时，resample()的行为会变得更加微妙：

df_tz = df.copy() df_tz.index = df_tz.index.tz_localize('Asia/Shanghai') # 按天重采样 daily_tz = df_tz.resample('D').sum()

这很正常，但换成一个有夏令时的时区，比如美国的America/New_York，春季有一天只有 23 小时，秋季有一天有 25 小时。resample('D')对这种日子的处理结果可能出乎意料：23 小时那天会少一个小时的数据，25 小时那天会多出数据，聚合结果看起来在某一天偏低或偏高，但实际上只是时区切换导致的自然现象。

处理方案：如果业务粒度不需要那么精细，可以先把时区统一成 UTC：

df_utc = df_tz.tz_convert('UTC')

再用 UTC 重采样，按需转换回本地时区展示。国际业务、跨时区报表尤其推荐这么干。另一个常见选择是tz_localize(None)去掉时区信息，但这样会丢失真实的时间语义，不推荐。

5.3 重采样后索引不是"干净"的时间序列

有时你会发现，重采样后的索引出现了一些奇怪的时间点，比如2025-01-01 00:00:00和2025-01-01 00:05:00混在一起——这说明rule没有正确对齐。常见原因是在rule里使用了带偏移量的频率，你以为是按天，实际按"24小时偏移"在切。比如：

df.resample('24H').sum()

这个和'D'不同。'D'按自然日对齐边界（零点），而'24H'从索引第一个时间戳开始，向后推 24 小时作为边界。如果你的第一个时间戳是 2025-01-01 08:23，那 24H 分组的边界就是 08:23。看起来"每 24 小时一条"，但边界不是零点。要按自然日聚合，必须用'D'或显式传origin='start_day'。

如果要用'24H'但希望边界对齐零点，可以：

df.resample('24H', origin='start_day').sum()

这里origin='start_day'就是"以当天零点作为分组原点"的意思。这是我前面讲origin时强调过的点，很多教程没讲透。

5.4 聚合对象是空组时怎么办

当原始数据本身有较大缺口而你又按小时/分钟聚合时，会得到一堆空组。此时：

resampled = df.resample('H').sum() resampled[resampled['amount'] == 0]

你会看到大量"全零"的行，这可能不是业务上想要的。正确做法是先筛非空组：

resampled = df.resample('H').sum(numeric_only=True) resampled = resampled[resampled.sum(axis=1) > 0]

或者用group_keys相关操作保留原始信息。这个在"打卡记录按小时统计"场景中非常重要——没有人打卡的小时就不该在结果里出现零值行，否则下游做可视化时会画出长段无意义的横线。

6. 一个更复杂的案例：分组内聚合后再重采样

有些分析任务不是简单对原始时间戳重采样，而是需要"先在某列上做 groupby，再对每个子组重采样"。比如：按product_category分组，分别看每个类目的日销量。

result = ( df.groupby('product_category') .resample('D') .agg({'order_id': 'count', 'amount': 'sum'}) )

这里groupby()之后接resample()，得到的是多级索引：第一级是product_category，第二级是时间。有时候你还会想把时间拉出来作为普通列：

result = result.reset_index()

如果业务上想按"每个类目 + 每天"作为主键，这样最合适。我个人经验是：比用groupby('product_category')先对每个类别单独取子集再循环聚合要快得多，因为 pandas 内部对切分和聚合做了不少优化。

另外一个 trick：groupby(...).resample(...)返回的结果可以直接.transform()，用来把聚合结果广播回原始粒度。比如：

df['daily_amount'] = ( df.groupby('product_category') .resample('D')['amount'] .transform('sum') )

这一行会在原始行里新增一列，表示该商品所在类目当天总金额。这在做"单笔金额占当天类目金额比例"这类特征计算时很好用，不需要复杂的 merge。

7. 除了 resample() 之外，还有哪些替代方案

7.1 用 Grouper 分组：更灵活的指定方式

resample()其实可以完全被下面这种方式替代：

df.groupby(pd.Grouper(freq='D')).sum()

Grouper也能指定key参数，比如用普通列作为时间来源而不 set_index：

df.groupby(pd.Grouper(key='trade_time', freq='D')).agg(...)

这个对于时间列不想挪到索引的场景挺方便。而且Grouper支持多列分组加上时间分组的混合操作：

df.groupby(['product_category', pd.Grouper(key='trade_time', freq='W')]).agg(...)

7.2 用 to_period() 做固定周期的标签转换

to_period()不是重采样，但它经常和resample()搭配。当你已经得到重采样结果，但想用2025-W03或2025-01这种周期标签而不是时间戳时：

daily.index = daily.index.to_period('D')

随后daily.index的类型变成PeriodIndex。这在生成财务月报时特别有用：月末标签直接显示为2025-01，而不是2025-01-31 00:00:00。我的建议是：同一天内多次重采样，并且最后要落库 Excel 的场景，用PeriodIndex更直观；做后续时间运算时，还是保留DatetimeIndex更保险。

7.3 性能对比：groupby + resample 的取舍

如果数据量在千万级以上，resample()的向量化操作已经很高效；但如果你在自定义聚合里写 Python 循环，数据量一大照样很慢。此时考虑用numba优化或转成polars实现，后者自带时间窗口函数，体验也不错。不过多数场景下，优化 pandas 写法已经够用。

我在实际处理中有一条经验：把原始时间索引预先截断到秒级精度，避免不带时区但带毫秒的时间戳。毫秒会让分组起点提前或推后一个微小时段，导致某些分组数量偏了 1。用df.index = df.index.floor('s')可以把毫秒去掉，很多莫名的边界问题就不见了。

最后的实战小提醒

把resample()用好的核心，我总结下来就三个判断：

1. 分组的边界是否符合业务时间口径，比如自然日、财务周、班次日。拿不准就打印几条边界日期人工核对。
2. 有没有提前处理好时区、非单调索引、重复时间戳。这三样是大多数报错和结果异常的根源。
3. 用agg()做多指标聚合时，确认哪些字段用sum、哪些用count、哪些用nunique。count不等于nunique，计算去重用户数时用错会出大笑话。

我个人最近的一次实际项目里，用resample('W-MON')做周粒度销售统计，顺手加了to_period('W')标签，配合数据透视表直接产出一张周报看板。整个链路从读取 CSV 到输出 Excel 只用了三十行代码。这个函数不复杂，但细节非常多，希望这篇文章能帮你在真正遇到问题时少走几步弯路。