数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载导读pylibcudf.aggregation是 NVIDIA cuDF GPU DataFrame 库中负责描述一次聚合计算的核心模块。它提供统一的Aggregation类型与三十余个工厂函数将sum、mean、groupby、rolling等各类聚合操作封装成可参数化的对象供GroupBy.aggregate、滚动窗口、归约reduce与扫描scan等上层 API 复用。读完本文你将掌握Aggregation类的设计理念、全部工厂函数的签名与参数语义、底层 libcudf C 实现脉络以及如何通过is_valid_aggregation校验聚合与数据类型的兼容性从而在 pylibcudf 上写出类型安全、可组合的 GPU 聚合代码。pylibcudf.aggregation 模块定位与文档来源本文对应仓库中的 Sphinx 文档页面 docs/cudf/source/pylibcudf/api_docs/aggregation.rst该页面通过automodule指令自动生成 API 文档 aggregation .. automodule:: pylibcudf.aggregation :members:即页面正文完全由 python/pylibcudf/pylibcudf/aggregation.pyx 中每个公开类、函数与枚举的 docstring 渲染而来。因此理解该模块的权威途径是直接阅读这个 Cython 实现文件以及它的类型存根 python/pylibcudf/pylibcudf/aggregation.pyi供 IDE 补全与静态检查使用。模块导出__all__包含Aggregation类、Kind、BitwiseOp、CorrelationType、EWMHistory、RankMethod、RankPercentage六个枚举/类型以及sum、product、min、max、count、any、all、mean、median、quantile、variance、std、argmax、argmin、nunique、nth_element、collect_list、collect_set、correlation、covariance、rank、ewma、lag、lead、row_number、histogram、m2、merge_m2、merge_histogram、merge_lists、merge_sets、merge_tdigest、tdigest、bitwise、is_valid_aggregation等 35 个公开符号。Aggregation 类统一聚合描述的核心抽象设计意图Aggregation类定义于 aggregation.pyx的 docstring 明确指出A type of aggregation to perform. Aggregations are passed to APIs likepylibcudf.groupby.GroupBy.aggregateto indicate what operations to perform. Using a class for aggregations provides a unified API for handling parametrizable aggregations. This class should never be instantiated directly, only via one of the factory functions.也就是说聚合对象承担着两大职责统一携带参数不同聚合需要不同的参数如quantile需要分位数列表、rank需要排名方法、nth_element需要索引 n。全部经由一个类承载上层 API 无需针对每种聚合分别设计入口。按场景转换类型同一聚合对象可以用于 groupby、rolling、reduce、scan 等不同场景底层通过 C 的多态类型动态转换实现。禁止直接构造Aggregation.__init__会直接抛出ValueError提醒用户必须通过工厂函数创建cdef class Aggregation: def __init__(self): raise ValueError( Aggregations should not be constructed directly. Use one of the factories. )正确的用法是调用模块级的工厂函数例如plc.aggregation.sum()、plc.aggregation.mean()它们内部通过Aggregation.from_libcudf(...)将 C 工厂返回的std::unique_ptrcudf::aggregation包装为 Python 对象。核心方法与行为Aggregation提供以下公开/内部方法方法说明kind()返回Kind枚举标识聚合类型对应 Ccudf::aggregation::Kind__eq__/__hash__基于底层 C 对象is_equal()与do_hash()实现因此相同类型、相同参数的聚合可以比较相等并用于集合/字典__repr__输出形如Aggregation(Kind.SUM: 0)的调试信息clone_underlying_as_groupby()深拷贝并动态转型为groupby_aggregation失败抛NotImplementedErrorclone_underlying_as_groupby_scan()深拷贝并转型为groupby_scan_aggregationclone_underlying_as_rolling()深拷贝并转型为rolling_aggregationview_underlying_as_reduce()/view_underlying_as_scan()/view_underlying_as_rolling()以视图方式转型为对应派生类型这些转型方法正是场景适配机制的实现例如 groupby 请求构造时aggregation_request._to_libcudf_agg_request()会对每个聚合调用agg.clone_underlying_as_groupby()见 python/pylibcudf/pylibcudf/groupby.pyx滚动窗口请求构造时rolling_request.view()调用self.aggregation.clone_underlying_as_rolling()见 python/pylibcudf/pylibcudf/rolling.pyx。如果某个聚合不支持特定场景例如某些聚合不是reduce_aggregation的派生类型动态转换会返回空指针此时_unsupported_agg_error抛出NotImplementedError(f{self} aggregations are not supported by {alg})——这也解释了为什么Aggregation的 docstring 特别提醒该类型是功能多态的。Kind 枚举全部聚合类型的目录Kind枚举映射 C 的cudf::aggregation::Kind见 cpp/include/cudf/aggregation.hpp在 pylibcudf 中的声明位于 python/pylibcudf/pylibcudf/libcudf/aggregation.pxdSUM, PRODUCT, MIN, MAX, COUNT_VALID, COUNT_ALL, ANY, ALL, SUM_OF_SQUARES, MEAN, M2, VARIANCE, STD, MEDIAN, QUANTILE, ARGMAX, ARGMIN, NUNIQUE, NTH_ELEMENT, ROW_NUMBER, EWMA, RANK, COLLECT_LIST, COLLECT_SET, LEAD, LAG, HOST_UDF, MERGE_LISTS, MERGE_SETS, MERGE_M2, COVARIANCE, CORRELATION, TDIGEST, MERGE_TDIGEST, HISTOGRAM, MERGE_HISTOGRAM, BITWISE_AGG对照 C 头文件中的注释各类型的语义为基本归约SUM求和、PRODUCT乘积、MIN/MAX极值、ANY/ALL逻辑或/与、SUM_OF_SQUARES平方和统计量MEAN均值、M2与均值之差的平方和、VARIANCE方差、STD标准差、MEDIAN中位数、QUANTILE分位数计数与去重COUNT_VALID有效元素计数、COUNT_ALL全部元素计数、NUNIQUE唯一值计数位置相关ARGMAX/ARGMIN最大/最小元素索引、NTH_ELEMENT第 n 个元素、ROW_NUMBER相对窗口的行号、RANK排名收集COLLECT_LIST收集为列表、COLLECT_SET收集为去重列表窗口函数LEAD/LAG偏移访问后续/前驱行、EWMA指数加权移动平均成对统计COVARIANCE、CORRELATION合并/增量聚合MERGE_LISTS、MERGE_SETS、MERGE_M2、MERGE_TDIGEST、MERGE_HISTOGRAM其他TDIGEST、HISTOGRAM、BITWISE_AGG位运算、HOST_UDF宿主端 UDF未导出工厂函数。注意Kind底层直接来自 C 枚举Kind.__str__ Kind.__repr__便于打印调试。另外C 端还有TOP_K与INVALID等成员但 pylibcudf 的Kind枚举只导出有对应工厂函数的类型。辅助枚举类型工厂函数参数中还会用到以下几组枚举同样定义于 libcudf/aggregation.pxd枚举取值用途CorrelationTypePEARSON、KENDALL、SPEARMAN相关系数类型EWMHistoryINFINITE、FINITE指数加权移动平均是否把历史视为无限RankMethodFIRST、AVERAGE、MIN、MAX、DENSE排名方法RankPercentageNONE、ZERO_NORMALIZED、ONE_NORMALIZED排名是否归一化为百分比BitwiseOpAND、OR、XOR位运算类型此外工厂函数参数还会复用pylibcudf.types中的通用枚举NullPolicyINCLUDE/EXCLUDEnull 是否参与计算、NullEqualityEQUAL/UNEQUAL、NanEqualityALL_EQUAL/UNEQUAL、NullOrderBEFORE/AFTER、OrderASCENDING/DESCENDING、Interpolation分位数插值法。工厂函数全览签名、参数与默认值下表汇总全部工厂函数源码见 aggregation.pyx函数必选参数可选参数默认值说明sum()——求和product()——乘积min()——最小值max()——最大值count()—null_handlingNullPolicy.EXCLUDE计数EXCLUDE表示排除 nullany()——逻辑或all()——逻辑与sum_of_squares()——平方和mean()——均值variance()—ddof1方差ddof为自由度增量std()—ddof1标准差默认ddof1样本标准差median()——中位数quantile()quantiles: list[float]interpInterpolation.LINEAR分位数取值应在 0~1 之间argmax()——最大值所在索引argmin()——最小值所在索引nunique()—null_handlingNullPolicy.EXCLUDE唯一值计数nth_element()n: intnull_handlingNullPolicy.INCLUDE第 n 个元素注意默认包含 nullcollect_list()—null_handlingNullPolicy.INCLUDE收集为列表collect_set()—null_handlingNullPolicy.INCLUDE,nulls_equalNullEquality.EQUAL,nans_equalNanEquality.ALL_EQUAL收集为去重列表correlation()type: CorrelationType,min_periods: int—相关系数min_periods为最少观测数covariance()min_periods: int,ddof: int—协方差rank()method: RankMethodcolumn_orderOrder.ASCENDING,null_handlingNullPolicy.EXCLUDE,null_precedenceNullOrder.AFTER,percentageRankPercentage.NONE排名ewma()center_of_mass: float,history: EWMHistory—指数加权移动平均lag()offset: int—取前 offset 行窗口函数lead()offset: int—取后 offset 行窗口函数row_number()——当前行号histogram()——元素频数统计m2()——与均值之差的平方和M2merge_m2()——合并部分 M2 结果merge_histogram()——合并部分直方图结果merge_lists()——合并多个列表为一个列表merge_sets()—nulls_equalNullEquality.EQUAL,nans_equalNanEquality.ALL_EQUAL合并列表并去重tdigest()max_centroids: int—构建 t-digestmax_centroids控制压缩度与精度merge_tdigest()max_centroids: int—合并多个 t-digestbitwise()op: BitwiseOp—数值列位运算AND/OR/XOR参数语义详解null 策略NullPolicycount与nunique默认EXCLUDEnull 不计入nth_element、collect_list、collect_set默认INCLUDE。使用前应明确业务口径例如唯一值计数是否把 null 算一个值直接决定结果。ddofDelta Degrees of Freedomvariance/std默认1对应样本方差/标准差分母 n-1传0则得到总体方差/标准差。quantile的quantiles列表值须在 [0, 1] 区间interp决定分位数落在两个数据点之间时的插值方式默认线性插值Interpolation.LINEAR。rank的五参数method决定并列值如何取秩FIRST按出现顺序、AVERAGE取平均、MIN/MAX取最小/最大秩、DENSE密集排名column_order控制排序方向null_handling/null_precedence控制 null 是否参与及排在前后percentage可将排名归一化到 [0,1] 或 [1,n]。ewma的center_of_mass以质心形式给出的衰减参数historyEWMHistory.INFINITE表示历史无限。tdigest/merge_tdigest的max_centroids直接控制压缩级别与后续查询精度越大越精确、占用内存越多。lag/lead的offset窗口内相对偏移行数二者是典型的窗口window聚合常与rolling场景配合。类型校验is_valid_aggregationis_valid_aggregation(source: DataType, agg: Aggregation) - boolaggregation.pyx用于判断某个数据类型是否支持某种聚合内部直接委托给 C 的cudf::is_valid_aggregation(source.c_obj, agg.kind())cpdef bool is_valid_aggregation(DataType source, Aggregation agg): Return if an aggregation is supported for a given datatype. return cpp_is_valid_aggregation(source.c_obj, agg.kind())典型应用对字符串列求sum()是非法的先用校验函数确认再决定是否执行聚合可避免运行时异常。例如 python/pylibcudf/tests/test_reduce.py 中展示了合法/非法组合的判定测试。场景适配聚合对象如何流入上层 API聚合对象设计为描述性对象本身不执行计算真正的计算由调用它的上层 API 根据场景分发。其调用链如下用户构造工厂函数 - AggregationCython 包装 cudf::aggregation | --- GroupBy.aggregate(values, aggregations) # clone_underlying_as_groupby --- groupby scan_request # clone_underlying_as_groupby_scan --- rolling_window(rolling_request) # clone_underlying_as_rolling --- reduce / scan # view_underlying_as_reduce / as_scan以 groupby 为例GroupBy.aggregate的请求对象构造过程python/pylibcudf/pylibcudf/groupby.pyx会对每个Aggregation执行clone_underlying_as_groupby()将cudf::aggregation动态转型为cudf::groupby::aggregation_request所需的groupby_aggregation派生类型并推入请求向量。滚动窗口场景则通过rolling_request.view()python/pylibcudf/pylibcudf/rolling.pyx调用clone_underlying_as_rolling()。这正是 C 侧设计的关键cudf::aggregation是一个带clone()/is_equal()/do_hash()虚函数的基类cpp/include/cudf/aggregation.hpp并派生rolling_aggregation、groupby_aggregation、groupby_scan_aggregation、reduce_aggregation、scan_aggregation等多个视图类型。同一聚合对象能否用于某场景取决于其真实类型是否是该场景对应派生类的子类——若动态转型失败pylibcudf 会抛出NotImplementedError例如Aggregation(Kind.HISTOGRAM: 30) aggregations are not supported by groupby。实战示例在 pylibcudf 中组合使用聚合下面是一个可直接运行的组合示例演示工厂函数、kind()、相等性判断与 groupby 的配合import pylibcudf as plc from pylibcudf import aggregation # 1. 通过工厂函数构造聚合对象禁止直接实例化 Aggregation agg_sum aggregation.sum() agg_mean aggregation.mean() agg_quantile aggregation.quantile([0.25, 0.5, 0.75]) agg_rank aggregation.rank(aggregation.RankMethod.DENSE) # 2. 查看类型与调试信息 print(agg_sum.kind()) # Kind.SUM print(repr(agg_sum)) # Aggregation(Kind.SUM: 0) # 3. 相同参数的聚合对象可比较相等、可哈希 assert aggregation.variance(1) aggregation.variance(1) assert aggregation.variance(1) ! aggregation.variance(0) assert hash(aggregation.mean()) hash(aggregation.mean()) # 4. 校验数据类型与聚合的兼容性 dtype plc.DataType(plc.TypeId.INT32) assert aggregation.is_valid_aggregation(dtype, agg_sum) assert not aggregation.is_valid_aggregation(dtype, aggregation.nth_element(2)) # 示例按需验证 # 5. 用于 groupby 聚合请求 # values plc.Column(...) # 待聚合列 # keys plc.Column(...) # 分组键 # result plc.groupby.GroupBy(keys).aggregate( # plc.groupby.aggregation_request(values, [agg_sum, agg_mean, agg_quantile]) # )更完整的用法可参考仓库测试python/pylibcudf/tests/test_reduce.pyreduce场景sum/max/mean/quantile/count/nunique/rank等python/pylibcudf/tests/test_rolling.pyrolling场景如collect_listpython/pylibcudf/tests/test_stream_protocol.py自定义流协议下构造sum聚合使用建议与注意事项不要直接Aggregation()类构造会抛ValueError必须走工厂函数以保证底层 C 对象构造正确。注意不同聚合的 null 默认值count/nunique默认EXCLUDE而nth_element/collect_list/collect_set默认INCLUDE统计口径务必显式确认。ddof默认 1variance/std默认按样本统计n-1需要总体统计时显式传ddof0。场景兼容性由动态类型决定同一聚合对象在不同 API 下可能受支持情况不同若收到NotImplementedError: ... not supported by ...说明该聚合不属于对应场景的派生类型可用is_valid_aggregation预检。聚合对象可哈希、可比较__eq__/__hash__委托 C 实现便于在字典、集合中缓存聚合配置。版本与适用范围以上 API 以当前仓库pylibcudf 模块对应 libcudf cpp/include/cudf/aggregation.hpp为准Kind中如SUM_OVERFLOW、TOP_K、HOST_UDF等成员未在 pylibcudf 导出工厂函数如需使用需关注后续版本支持情况。赞分享数据分析数据工程机器学习【免费下载链接】cudfcuDF - GPU DataFrame Library项目地址https://gitcode.com/gh_mirrors/cu/cudf点击查看免费下载相关推荐免费新手指南把真实地图变成 Minecraft 世界3 个参数配方复刻家园免费新手指南把真实地图变成 Minecraft 世界3 个参数配方复刻家园 Arnis 是一款免费开源的世界生成工具读取 OpenStreetMap 地理数据分析数据工程机器学习cuDF 聚合归约Aggregation ReductionAPI 全解reduce、segmented_reduce、scan 与 minmax 的底层实现与使用指南cuDF 聚合归约Aggregation ReductionAPI 全解reduce、segmented_reduce、scan 与 minmax 的底层数据分析数据工程机器学习StarRocks group_concat 聚合函数完全指南语法、排序去重与底层实现解析StarRocks group_concat 聚合函数完全指南语法、排序去重与底层实现解析 GROUP_CONCAT 是 StarRocks 中把分组内多行非数据库OLAP数据仓库大数据湖仓一体数据分析上一篇BinDiff入门教程10分钟学会使用反汇编代码差异分析工具下一篇NetworkX MultiDiGraph 完全指南有向多重图的数据结构、增删改查与子类化实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
