pd.Grouper专用于时间频率分组，需配合groupby使用，要求时间列为datetime64[ns]类型，支持freq如'1T''1H'等，可混合其他列分组，时区、类型、对齐方式须准确设置。
pd.Grouper 的核心用途是时间频率分组，不是通用分组器
它专为
或含时间列的 DataFrame 设计，不能替代普通字符串列分组。如果你的列是
类型（比如字符串格式的 '2023-01-01 10:30:45'），必须先用
转成
，否则
会静默失败或报
。
常见错误现象：分组后结果为空、行数没变、或抛出
—— 基本都是类型没转对，或传了错误的列名。
确认时间列类型：
应为
若列名是
，别写成
（大小写敏感）
必须配合
使用，不能单独调用
按分钟聚合：freq='1T' 或 freq='60S' 都可以，但推荐 '1T'
参数支持 pandas 时间频率别名，
（1 minute）比
更常用且语义清晰。注意：它默认按时间戳“左边界”对齐（即每分钟从 :00 开始），例如
到
内的所有记录归入同一组。
示例（按分钟聚合均值）：
如果想右对齐（以 :59 结束），加
和
若原始数据有缺失分钟，结果中对应行默认为 NaN；加
不会补全，需用
+
聚合列若含非数值类型（如字符串），
会跳过，改用
按小时聚合：freq='1H' 是标准写法，注意时区影响
表示自然小时（如 00:00–00:59、01:00–01:59），但如果时间列带时区（如
或
），分组边界会按该时区计算。本地无时区的时间会被当作
处理，可能导致意外偏移。
示例（带时区的安全做法）：
不指定时区时，
不会自动推断，容易和系统本地时间混淆
和
等价，但可读性差，不建议
跨天聚合（如每天 9:00–17:00）不能靠
实现，得先用
构造辅助列再分组
和 resample 的区别：groupby + Grouper 更灵活，但 resample 更简洁
如果你的数据索引已经是
，直接用
更短。但
的优势在于：支持多级 groupby（如同时按设备 ID 和每小时）、支持非索引时间列、可与其他列混合分组。
典型混合场景：
要求索引是时间，
不要求
混合分组时，
的
参数必须明确指向时间列名，不能省略
性能上，两者底层都走相同路径，差异可忽略；但
对单时间维度更直观，不易错
时区、数据类型、对齐方式这三点，漏掉任一个都可能让聚合结果偏移一小时或完全错乱。实际跑之前，先用
手动看几行对齐逻辑，比盲调
参数可靠得多。
DateTimeIndexobjectpd.to_datetime()datetime64[ns]pd.GrouperTypeError: No frequencyValueError: freq not specifieddf['ts'].dtypedatetime64[ns]'time'key='Time'pd.Groupergroupby()freq'1T''60S'2023-01-01 10:30:002023-01-01 10:30:59.999df.groupby(pd.Grouper(key='ts', freq='1T')).mean()closed='right'label='right'dropna=False.resample().asfreq().mean().agg({'val': 'mean', 'event': 'first'})freq='1H'UTC'Asia/Shanghai'UTCdf['ts'] = pd.to_datetime(df['ts']).dt.tz_localize('Asia/Shanghai')
df.groupby(pd.Grouper(key='ts', freq='1H')).sum()pd.Grouperfreq='60T''1H'freqdt.hour.between(9,16)DatetimeIndexdf.resample('1T').mean()pd.Grouperdf.groupby(['device_id', pd.Grouper(key='ts', freq='1H')]).agg({'temp': 'max', 'humidity': 'mean'})resamplepd.Grouperpd.Grouperkeyresampledf['ts'].head().dt.floor('1H')freq