pandas 0.22.0 空值与全 NA 聚合语义变更详解sum()/prod()与新增的min_count参数【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas导读pandas 0.22.02017 年 12 月 29 日发布是 0.21.1 之后的一个大版本但它的核心改动只有一项——而且是唯一的API 破坏性变更空empty或全 NA 的Series在sum()时默认返回0、prod()时默认返回1同时为这两个方法引入了全新的min_count参数来控制结果有效的非空值最低个数。本文以官方发布说明 doc/source/whatsnew/v0.22.0.rst 为主线结合当前仓库源码pandas/core/generic.py、pandas/core/nanops.py 等与测试用例带你完整掌握这次语义变化的来龙去脉、受影响的所有场景GroupBy、Resample、Rolling/Expanding以及面向多版本兼容的实际应对方案。读完本文你将能够解释min_count的默认值与取值含义在Series、DataFrame、groupby、resample、rolling/expanding五种场景中精确控制聚合返回0/1还是NaN并知道如何在自己的库中规避 pandas 0.21 的不一致行为。一、变更背景一次部分回退的决策本次变更是对 pandas 0.21 行为的一次部分回退partially reverted其历史脉络如下在 pandas 0.21 之前全 NA 序列的求和结果依赖是否安装了 bottleneck 库而出现不一致详见 doc/source/whatsnew/v0.21.0.rst 中的相关说明。0.21 修复了这一长年遗留的不一致问题但顺带把空序列的sum()/prod()也一并改成了NaN。社区反馈认为空序列与全 NA 序列的求和返回NaN过于激进。于是 0.22.0 基于反馈部分回退了 0.21 的改动——默认行为恢复为空或全 NA 时sum返回0、prod返回1同时用新参数min_count提供精确控制。变更总结为三条核心规则空或全 NA 的Seriessum()结果为0空或全 NA 的Seriesprod()结果为1新增min_count参数当非 NA 值的个数少于min_count时结果为 NA默认值为0。要恢复 0.21 的NaN行为使用min_count1。从当前源码可以确认这一设计延续至今。在 pandas/core/generic.py#L11849-L11910 中sum与prod共用_min_count_stat_function辅助方法签名均为def sum(self, *, axis0, skipnaTrue, numeric_onlyFalse, min_count0, **kwargs): def prod(self, *, axis0, skipnaTrue, numeric_onlyFalse, min_count0, **kwargs):两者最终都进入self._reduce(...)把min_count一路透传给底层nanops.nansum/nanops.nanprod。也就是说min_count是Series与DataFrame在共享基类NDFrame层面统一实现的公共 API这也解释了为什么它同时作用于分组、重采样等所有派生场景。二、基础语义Series.sum()与Series.prod()的新默认值2.1 求和sum空序列与全 NA 序列的默认求和结果从NaN变为0.0 import numpy as np import pandas as pd # pandas 0.21.x pd.Series([]).sum() # nan pd.Series([np.nan]).sum() # nan # pandas 0.22.0 pd.Series([]).sum() 0.0 pd.Series([np.nan]).sum() 0.0官方文档特别指出这个默认行为与pandas 0.20.3 bottleneck的表现一致也等价于 NumPy 对空数组与全 NA 数组的np.nansum行为。也就是说0.22.0 实际上是把无缺失值参与运算时的恒等元语义求和的恒等元是 0求积的恒等元是 1恢复为默认。需要NaN即 0.20.3 无 bottleneck 或 0.21.x 的默认行为时使用min_count1 pd.Series([]).sum(min_count1) nan2.2 与skipna的关系由于sum()默认skipnaTrue跳过 NA一个全 NA 序列在概念上等价于一个先剔除所有 NA 后再求和的空序列。因此 pd.Series([np.nan]).sum(min_count1) # skipnaTrue 是默认值 nan这与pd.Series([]).sum(min_count1)的结果一致。理解这一点就能把握住整个新语义的数学本质先按skipna规则确定参与计算的有效值集合再比较有效值个数与min_count。2.3 求积prodprod()遵循与sum()完全相同的规则只是恒等元为1 pd.Series([]).prod() 1.0 pd.Series([np.nan]).prod() 1.0 pd.Series([]).prod(min_count1) nan2.4min_count的精确定义min_count指的是非空non-null值的最少个数只有非 NA 值个数达到该阈值求和/求积结果才有效否则返回 NA。默认值0意味着任何情况下包括空序列都返回数值结果。在源码层面这个判定逻辑集中在 pandas/core/nanops.py#L1914-L1994 的两个函数中_maybe_null_out()当min_count 0时如果某一维度axis上非空值个数不足就把该位置的结果替换为NaN数值类型、None非数值类型或iNaTdatetimelike 类型check_below_min_count()核心判定非空值个数 min_count即返回True其中non_nulls mask.size - mask.sum()有 mask 时或np.prod(shape)无缺失时。nansum内部pandas/core/nanops.py#L775-L846在求和之前先对缺失位置填充fill_value0因此空/全 NA 输入自然求和得0随后再经由_maybe_null_out按min_count决定是否抹掉结果。这一实现路径保证了0这个默认返回值的稳定性。仓库中的参数化测试对min_count与skipna的全部组合做了覆盖例如 pandas/tests/reductions/test_reductions.py#L615-L705 中依次断言min_count0与min_count1、skipnaTrue与skipnaFalse下sum/prod的结果以及在 pandas/tests/reductions/test_reductions.py#L1363-L1364 中验证显式更大的min_count依然被尊重skipnaFalse, min_count5时结果为 NA。2.5DataFrame同样受影响由于实现位于共享基类DataFrame.sum()与DataFrame.prod()也同步应用新默认值按轴逐列/逐行聚合时全 NA 的列/行返回0或1并使用同一个min_count参数。三、受影响场景一按 Categorical 分组求和分组键为Categorical且observedFalse默认时聚合结果会包含没有观测值的类别。在 0.21 中这些未观测类别返回NaN0.22.0 起求和返回0、求积返回1# pandas 0.21.x grouper pd.Categorical([a, a], categories[a, b]) pd.Series([1, 2]).groupby(grouper, observedFalse).sum() # a 3.0 # b NaN # dtype: float64 # pandas 0.22.0 grouper pd.Categorical([a, a], categories[a, b]) pd.Series([1, 2]).groupby(grouper).sum() a 3 b 0 dtype: int64注意输出还发生了 dtype 变化0.21 中因存在NaN而被迫升为float640.22.0 中未观测类别直接补0因此保持整数类型int64这实际上是额外的一个 dtype 红利。要恢复 0.21 的NaN行为给sum()传入min_count1 pd.Series([1, 2]).groupby(grouper).sum(min_count1) a 3.0 b NaN dtype: float64当前源码中GroupBy.sum()的签名pandas/core/groupby/groupby.py#L2766-L2773为sum(numeric_onlyFalse, min_count0, skipnaTrue, engineNone, engine_kwargsNone)其 docstring 明确写着若非 NA 值少于min_count结果将为 NA。默认值0正是未观测类别补 0这一行为得以成立的关键——它被透传到_cython_agg_general后的底层分组聚合中由 Cython 实现按与nansum相同的规则处理缺失组。四、受影响场景二Resample 重采样4.1 全 NA 桶bin的默认变化重采样后若某个时间桶内全为 NA其求和结果从NaN变为0求积从NaN变为1s pd.Series([1, 1, np.nan, np.nan], indexpd.date_range(2017, periods4)) # pandas 0.21.x s.resample(2d).sum() # 2017-01-01 2.0 # 2017-01-03 NaN # Freq: 2D, dtype: float64 # pandas 0.22.0 s.resample(2d).sum() 2017-01-01 2.0 2017-01-03 0.0 Freq: 2D, Length: 2, dtype: float64恢复 0.21 行为同样只需min_count1 s.resample(2d).sum(min_count1) 2017-01-01 2.0 2017-01-03 NaN Freq: 2D, Length: 2, dtype: float644.2 上采样upsampling尤其值得警惕重采样场景中最隐蔽的影响是上采样即使原始序列完全有效上采样也会在新增的时间点上人为引入缺失值从而把原本不受影响的序列也卷入新语义中idx pd.DatetimeIndex([2017-01-01, 2017-01-02]) # pandas 0.21.x pd.Series([1, 2], indexidx).resample(12H).sum() # 2017-01-01 00:00:00 1.0 # 2017-01-01 12:00:00 NaN # 2017-01-02 00:00:00 2.0 # Freq: 12H, dtype: float64 # pandas 0.22.0 pd.Series([1, 2], indexidx).resample(12H).sum() 2017-01-01 00:00:00 1 2017-01-01 12:00:00 0 2017-01-02 00:00:00 2 Freq: 12H, Length: 3, dtype: int64这里除了全 NA 中间桶从NaN变为0还可以再次观察到 dtype 从float64降为int64的连带效果。如需保持NaN语义例如后续要配合缺失值填充管道显式传入min_count1即可 pd.Series([1, 2], indexidx).resample(12H).sum(min_count1) 2017-01-01 00:00:00 1.0 2017-01-01 12:00:00 NaN 2017-01-02 00:00:00 2.0 Freq: 12H, Length: 3, dtype: float64在源码层面Resampler.sum()pandas/core/resample.py#L1108-L1164与prod()pandas/core/resample.py#L1168-L1222的签名同样携带min_count: int 0并在 docstring 中写明非 NA 值少于min_count时结果为 NA随后经由self._downsample(sum, ...)进入与GroupBy共享的底层聚合链路。五、受影响场景三Rolling 与 Expandingmin_periods0滚动与扩展窗口早已拥有与min_count语义相近的min_periods参数。本次变更中唯一改变的情形是当min_periods0且窗口内非 NA 值不足min_periods即窗口全 NA 时sum()从NaN变为0s pd.Series([np.nan, np.nan]) # pandas 0.21.1 s.rolling(2, min_periods0).sum() # 0 NaN # 1 NaN # dtype: float64 # pandas 0.22.0 s.rolling(2, min_periods0).sum() 0 0.0 1 0.0 dtype: float64需要特别强调min_periodsNone默认时的行为完全不变。此时min_periods等于窗口大小窗口内有效值不足窗口大小时依旧返回NaN与本变更无关。仓库测试对min_periods0的窗口语义有系统覆盖例如 pandas/tests/window/test_expanding.py#L64expanding(min_periods0).sum()与 pandas/tests/window/test_base_indexer.py#L178min_periods0等价于count的讨论可作为理解该行为的参考用例。六、跨版本兼容策略如何安全地依赖 pandas本次变更带来的最大工程风险在于同一段代码在 pandas 0.21 与 0.22 上运行会得到不同的结果而如果同时维护空序列分支行为会更加混乱。官方给出的兼容性建议非常干脆如果你的库需要跨多个 pandas 版本工作最简单的办法是在依赖中排除 pandas 0.21。否则你所有的sum()调用都必须在求和前先检查Series是否为空。6.1 setuptoolssetup.pyinstall_requires[pandas!0.21.*, ...]6.2 condaenvironment.yml/ meta.yamlrequirements: run: - pandas !0.21.0,!0.21.16.3 注意事项与边界排除 0.21 只解决空序列场景的差异全 NA 序列的返回不一致问题在pandas 0.20.3 及更早版本中依然存在这正是 0.21 最初试图修复的历史问题见本文第一节的背景梳理。因此如果你的用户群中还可能出现 0.20.3 及更早版本单纯排除 0.21 是不够的需要另行兜底例如显式传min_count并接受不同版本间的结果差异或在聚合前主动规范化输入。七、总结新语义速查表场景pandas 0.21.xpandas 0.22.0默认恢复 0.21 行为空/全 NASeries.sum()NaN0.0sum(min_count1)空/全 NASeries.prod()NaN1.0prod(min_count1)Categorical 未观测类别的groupby.sum()NaNfloat640int64sum(min_count1)全 NA 桶的resample(2d).sum()NaN0.0sum(min_count1)上采样引入空桶的resample(12H).sum()NaNfloat640int64sum(min_count1)rolling(2, min_periods0).sum()全 NA 窗口NaN0.0行为由min_periods控制min_count参数的引入是这次发布最核心的 API 财富它把求和/求积结果何时应该有效的控制权完整交给了用户其默认值0保证了代数恒等元语义空和 → 0空积 → 1的一致性且这一设计从 0.22.0 一直延续到当前主分支pandas/core/generic.py#L11849、pandas/core/nanops.py#L1914。实践建议在新代码中凡是可能面对空序列或全 NA 序列的聚合都显式写明min_count——需要数值恒等元用默认0需要缺失信号用min_count1或按业务阈值放大如min_count2要求至少两个有效值。这样既能获得 0.22.0 之后稳定一致的语义也能让你的代码在未来的 pandas 版本中保持可预期。【免费下载链接】pandasFlexible and powerful data analysis / manipulation library for Python, providing labeled data structures similar to R data.frame objects, statistical functions, and much more项目地址: https://gitcode.com/gh_mirrors/pa/pandas创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考