聚合 Groupby#

group GroupBy
struct aggregation_request#
#include <groupby.hpp>

对列执行 groupby 聚合的请求。

每个 value[i] 的组成员身份由用于构建 groupby 的 keys 的原始顺序中的对应行 i 确定。即，对于每个 aggregation，values[i] 与 values[j] 中的所有其他值聚合，其中 keys 中的行 i 和 j 是等价的。

values.size() 列必须等于 keys.num_rows()。

公共成员

column_view values#

要聚合的元素。

std::vector<std::unique_ptr<groupby_aggregation>> aggregations#

所需的聚合。

struct scan_request#
#include <groupby.hpp>

对列进行扫描聚合的请求。

每个 value[i] 的组成员身份由用于构建 groupby 的 keys 的原始顺序中的对应行 i 确定。即，对于每个 aggregation，values[i] 与 values[j] 中的所有其他值聚合，其中 keys 中的行 i 和 j 是等价的。

values.size() 列必须等于 keys.num_rows()。

公共成员

column_view values#

要聚合的元素。

std::vector<std::unique_ptr<groupby_scan_aggregation>> aggregations#

所需的聚合。

struct aggregation_result#
#include <groupby.hpp>

一个 aggregation_request 的结果。

对于提供给 groupby::aggregate 的每个 aggregation_request，将返回一个 aggregation_result。 aggregation_result 包含对 request 值执行的每个请求聚合的结果列。

公共成员

std::vector<std::unique_ptr<column>> results = {}#

来自 aggregation_request 的结果列。

class groupby#
#include <groupby.hpp>

按键对值进行分组并计算这些组上的聚合。

公共函数

explicit groupby(table_view const &keys, null_policy null_handling = null_policy::EXCLUDE, sorted keys_are_sorted = sorted::NO, std::vector<order> const &column_order = {}, std::vector<null_order> const &null_precedence = {})#

使用指定的 keys 构造一个 groupby 对象

如果 keys 已排序，可以通过传递 keys_are_sorted == true 并在 column_order 和 null_precedence 中分别指示每列的升序/降序和 null 顺序来获得更好的性能。

注意

此对象不维护 keys 的生命周期。用户有责任确保 groupby 对象的生命周期不超过 keys table_view 所查看的数据的生命周期。

参数:

  • keys – 其行充当 groupby 键的表

  • null_handling – 指示是否应包含 keys 中包含 NULL 值的行

  • keys_are_sorted – 指示 keys 中的行是否已排序

  • column_order – 如果 keys_are_sorted == YES，指示每列是升序还是降序。如果为空，则假定所有列都是升序的。如果 keys_are_sorted == false，则忽略此参数。

  • null_precedence – 如果 keys_are_sorted == YES，指示每列中 null 值的排序顺序。否则，忽略。如果为空，则假定所有列都使用 null_order::AFTER。如果 keys_are_sorted == false，则忽略此参数。

std::pair<std::unique_ptr<table, std::vector<aggregation_result>> aggregate(host_span<aggregation_request const> requests, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

对指定的值执行分组聚合。

要聚合的值和要执行的聚合在 aggregation_request 中指定。每个请求包含一个用于聚合值的 column_view 和一组要对这些元素执行的 aggregation。

对于请求中的每个 aggregation，values[i] 与所有其他 values[j] 聚合，其中 keys 中的行 i 和 j 是等价的。

请求列的 size() 必须等于 keys.num_rows()。

对于提供给 groupby::aggregate 的每个 aggregation_request，将返回一个 aggregation_result。 aggregation_result 包含对 request 值执行的每个请求聚合的结果列。每个结果中列的顺序与请求中指定的顺序相同。

返回的 table 包含每个组的组标签，即来自 keys 的唯一行。所有聚合结果中的元素 i 属于组标签表中第 i 行的组。

组标签中行的顺序是任意的。此外，连续调用 groupby::aggregate 可能会返回不同顺序的结果。

示例

Input:
keys:     {1 2 1 3 1}
          {1 2 1 4 1}
request:
  values: {3 1 4 9 2}
  aggregations: {{SUM}, {MIN}}

result:

keys:  {3 1 2}
       {4 1 2}
values:
  SUM: {9 9 1}
  MIN: {9 2 1}

抛出:

cudf::logic_error – 如果 requests[i].values.size() != keys.num_rows()。

参数:

  • requests – 要聚合的列集合和要执行的聚合

  • stream – 用于设备内存操作和内核启动的 CUDA 流。

  • mr – 用于分配返回表和列的设备内存的设备内存资源

返回:

包含每个组的唯一键的表，以及每个请求的 aggregation_results 向量，其顺序与 requests 中指定的顺序相同。

std::pair<std::unique_ptr<table, std::vector<aggregation_result>> scan(host_span<scan_request const> requests, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

对指定的值执行分组扫描。

要聚合的值和要执行的聚合在 aggregation_request 中指定。每个请求包含一个用于聚合值的 column_view 和一组要对这些元素执行的 aggregation。

对于请求中的每个 aggregation，values[i] 与 values[j] 中所有先前的、且 keys 中的行 i 和 j 等价的值进行扫描聚合。

请求列的 size() 必须等于 keys.num_rows()。

对于提供给 groupby::aggregate 的每个 aggregation_request，将返回一个 aggregation_result。 aggregation_result 包含对 request 值执行的每个请求聚合的结果列。每个结果中列的顺序与请求中指定的顺序相同。

返回的 table 包含每行的组标签，即提供给 groupby 对象的 keys。所有聚合结果中的元素 i 属于组标签表中第 i 行的组。

组标签中行的顺序是任意的。此外，连续调用 groupby::scan 可能会返回不同顺序的结果。

示例

Input:
keys:     {1 2 1 3 1}
          {1 2 1 4 1}
request:
  values: {3 1 4 9 2}
  aggregations: {{SUM}, {MIN}}

result:

keys:  {3 1 1 1 2}
       {4 1 1 1 2}
values:
  SUM: {9 3 7 9 1}
  MIN: {9 3 3 2 1}

抛出:

cudf::logic_error – 如果 requests[i].values.size() != keys.num_rows()。

参数:

  • requests – 要扫描的列集合和要执行的扫描

  • stream – 用于设备内存操作和内核启动的 CUDA 流。

  • mr – 用于分配返回表和列的设备内存的设备内存资源

返回:

包含每个组的键的表，以及每个请求的 aggregation_results 向量，其顺序与 requests 中指定的顺序相同。

std::pair<std::unique_ptr<table, std::unique_ptr<table>> shift(table_view const &values, host_span<size_type const> offsets, std::vector<std::reference_wrapper<scalar const>> const &fill_values, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

对指定的值执行分组移位。

在第 j 列中，对于每个组，第 i 个元素由该组的第 i - offsets[j] 个元素决定。如果 i - offsets[j] < 0 or >= group_size，则该值由 fill_values[j] 决定。

示例

keys:    {1 4 1 3 4 4 1}
         {1 2 1 3 2 2 1}
values:  {3 9 1 4 2 5 7}
         {"a" "c" "bb" "ee" "z" "x" "d"}
offset:  {2, -1}
fill_value: {@, @}
result (group order maybe different):
   keys:   {3 1 1 1 4 4 4}
           {3 1 1 1 2 2 2}
   values: {@ @ @ 3 @ @ 9}
           {@ "bb" "d" @ "z" "x" @}

-------------------------------------------------
keys:    {1 4 1 3 4 4 1}
         {1 2 1 3 2 2 1}
values:  {3 9 1 4 2 5 7}
         {"a" "c" "bb" "ee" "z" "x" "d"}
offset:  {-2, 1}
fill_value: {-1, "42"}
result (group order maybe different):
   keys:   {3 1 1 1 4 4 4}
           {3 1 1 1 2 2 2}
   values: {-1 7 -1 -1 5 -1 -1}
           {"42" "42" "a" "bb" "42" "c" "z"}

注意

返回的第一个表存储传递给 groupby 对象的键。键表中的行 i 对应于移位列中行 i 的组标签。每个组中的键顺序与输入顺序匹配。每个组的顺序是任意的。连续调用 groupby::shifts 的组顺序可能不同。

参数:

  • values – 其列将进行移位的表

  • offsets – 移位的偏移量

  • fill_values – 用于不确定输出的填充值

  • stream – 用于设备内存操作和内核启动的 CUDA 流。

  • mr – 用于分配返回表和列的设备内存的设备内存资源

抛出:

cudf::logic_error – 如果 fill_value[i] 的 dtype 与第 i 列的 values[i] 的 dtype 不匹配

返回:

包含每个组的键表和移位后的列的对

groups get_groups(cudf::table_view values = {}, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

获取与对一组值执行的 groupby 操作相对应的分组键和值。

返回一个表示分组键和值的 groups 对象。如果未提供 values，则仅对键进行分组，并且 groups 对象的 values 将为 nullptr。

参数:

  • values – 表示要对其执行 groupby 操作的值的表

  • stream – 用于设备内存操作和内核启动的 CUDA 流。

  • mr – 用于在返回的 groups 中分配返回的表的设备内存的设备内存资源

返回:

一个表示分组键和值的 groups 对象

std::pair<std::unique_ptr<table, std::unique_ptr<table>> replace_nulls(table_view const &values, host_span<cudf::replace_policy const> replace_policies, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

对 value 执行分组 null 替换。

对于组 j 中每个 value[i] == NULL，value[i] 将被替换为组 j 中位于 value[i] 之前或之后的第一个非 null 值。如果在指定方向上未找到非 null 值，则 value[i] 保持 NULL。

返回的对包含排序键的列和结果列。在结果列中，同一组的值位于连续内存中。在每个组中，值的顺序保持其原始顺序。不保证组的顺序。

示例

//Inputs:
keys:    {3 3 1 3 1 3 4}
         {2 2 1 2 1 2 5}
values:  {3 4 7 @ @ @ @}
         {@ @ @ "x" "tt" @ @}
replace_policies:    {FORWARD, BACKWARD}

//Outputs (group orders may be different):
keys:    {3 3 3 3 1 1 4}
         {2 2 2 2 1 1 5}
result:  {3 4 4 4 7 7 @}
         {"x" "x" "x" @ "tt" "tt" @}

参数:

  • values – [in] 其列 null 值将被替换的表

  • replace_policies – [in] 指定替换值相对于 null 值的位置，每列一个

  • stream – [in] 用于设备内存操作和内核启动的 CUDA 流。

  • mr – [in] 用于分配返回列的设备内存的设备内存资源

返回:

包含排序键表和结果列的对

struct groups#
#include <groupby.hpp>

与对一组值执行的 groupby 操作相对应的分组数据。

一个 groups 对象包含两个行数相同的表：一个分组键表和一个分组值表。此外，它还包含一个指向这些表行的整数偏移量向量，使得 offsets[i+1] - offsets[i] 给出组 i 的大小。

公共成员

std::unique_ptr<table> keys#

分组键表。

std::vector<size_type> offsets#

组偏移量。

std::unique_ptr<table> values#

分组值表。