列复制#

group column_copy

枚举

enum class out_of_bounds_policy : bool#

策略以考虑可能的越界索引。

NULLIFY 表示将与越界的 gather_map 值对应的输出值置为空。DONT_CHECK 表示不检查索引是否越界，以提高性能。

值：

enumerator NULLIFY#: 超出边界索引对应的输出值为null。

enumerator DONT_CHECK#: 不执行边界检查，性能更好。

enum class mask_allocation_policy : int32_t#

指示何时基于现有掩码分配掩码。

值：

enumerator NEVER#: 无论输入如何，都不要分配空掩码。

enumerator RETAIN#: 如果输入包含一个空掩码，则分配一个空掩码。

enumerator ALWAYS#: 分配一个空掩码，无论输入如何。

enum class sample_with_replacement : bool#

指示一行是否可以被多次采样。

值：

enumerator FALSE#: 一行只能被采样一次。

enumerator TRUE#: 一行可以被多次采样。

函数

std::unique_ptr<table> reverse(table_view const &source_table, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

反转表中的行。

创建一个新表，它是source_table的反向。示例：

source = [[4,5,6], [7,8,9], [10,11,12]]
return = [[6,5,4], [9,8,7], [12,11,10]]

Parameters:

source_table – 将被反转的表
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回表的设备内存的设备内存资源

Returns:

反转的表格

std::unique_ptr<column> reverse(column_view const &source_column, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

反转列中的元素。

创建一个新列，该列是source_column的反向。示例：

source = [4,5,6]
return = [6,5,4]

Parameters:

source_column – 将被反转的列
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回表的设备内存的设备内存资源

Returns:

反转列

std::unique_ptr<column> empty_like(column_view const &input)#

初始化并返回一个与input类型相同的空列。

Parameters:: input – [in] 输入列的不可变视图，用于模拟
Returns:: 与 input 类型相同的空列

std::unique_ptr<column> empty_like(scalar const &input)#

初始化并返回一个与input类型相同的空列。

Parameters:: input – [in] 要模拟的标量
Returns:: 与 input 类型相同的空列

std::unique_ptr<column> allocate_like(column_view const &input, mask_allocation_policy mask_alloc = mask_allocation_policy::RETAIN, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

创建一个与input大小和类型相同的未初始化新列。

仅支持固定宽度类型。

如果 mask_alloc 分配了一个有效性掩码，该掩码也是未初始化的，调用者应设置有效性位和空值计数。

Throws:

cudf::data_type_error – 如果输入类型不是固定宽度。

Parameters:

input – 输入列的不可变视图，用于模拟
mask_alloc – 可选，用于分配空掩码的策略。默认为 RETAIN
mr – 用于分配返回列的设备内存的设备内存资源
stream – 用于设备内存操作和内核启动的CUDA流

Returns:

一个具有足够未初始化容量的列，能够容纳与input相同数量的元素，且类型与input.type()相同

std::unique_ptr<column> allocate_like(column_view const &input, size_type size, mask_allocation_policy mask_alloc = mask_allocation_policy::RETAIN, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

创建一个指定大小且与input类型相同的未初始化新列。

仅支持固定宽度类型。

如果 mask_alloc 分配了一个有效性掩码，该掩码也是未初始化的，调用者应设置有效性位和空值计数。

Parameters:

input – 输入列的不可变视图，用于模拟
size – 新列应具有的元素数量的期望容量
mask_alloc – 可选，用于分配空掩码的策略。默认为 RETAIN
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回列的设备内存的设备内存资源

Returns:

一个具有足够未初始化容量的列，以容纳指定数量的元素，这些元素的类型与input相同，类型为input.type()

std::unique_ptr<table> empty_like(table_view const &input_table)#

创建一个与input_table类型相同的空列表格

创建cudf::column对象，但不会为列的数据或位掩码分配任何底层设备内存。

Parameters:: input_table – [in] 输入表的不可变视图，用于模拟
Returns:: 一个空列的表，其列类型与input_table中的列类型相同

void copy_range_in_place(column_view const &source, mutable_column_view &target, size_type source_begin, size_type source_end, size_type target_begin, rmm::cuda_stream_view stream = cudf::get_default_stream())#

将一列中的一系列元素原地复制到另一列。

覆盖target中由索引[target_begin, target_begin + N)指示的元素范围，使用source中由索引[source_begin, source_end)指示的元素（其中N = (source_end - source_begin)）。对于需要内存重新分配的使用情况，使用返回std::unique_ptr的非原地复制函数。例如，对于字符串列和其他可变宽度类型。

如果 source 和 target 引用相同的元素并且范围重叠，则行为是未定义的。

Throws:

cudf::data_type_error – 如果需要重新分配内存（例如，对于可变宽度类型）。
std::out_of_range – 用于无效范围（如果 source_begin > source_end, source_begin < 0, source_begin >= source.size(), source_end > source.size(), target_begin < 0, target_begin >= target.size(), 或 target_begin + (source_end - source_begin) > target.size()）。
cudf::data_type_error – 如果 target 和 source 的类型不同。
std::invalid_argument – 如果 source 有空值且 target 不可为空。

Parameters:

source – 要从中复制的列
target – 预分配的列，用于复制数据
source_begin – 源范围的起始索引（包含）
source_end – 源范围中最后一个元素的索引（不包括）
target_begin – 目标范围的起始索引（包含）
stream – 用于设备内存操作和内核启动的CUDA流

std::unique_ptr<column> copy_range(column_view const &source, column_view const &target, size_type source_begin, size_type source_end, size_type target_begin, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

将一系列元素从一个列复制到另一个列，不改变原位置。

创建一个新列，就像在target中执行了原地复制一样。首先创建target的副本，然后将由索引[target_begin, target_begin + N)指示的元素从source的索引[source_begin, source_end)指示的元素复制过来（其中N = (source_end - source_begin)）。范围之外的元素从target复制到返回的新列目标中。

如果 source 和 target 引用相同的元素并且范围重叠，则行为是未定义的。

如果满足以下条件，范围被视为无效：

开始或结束索引超出了相应列的范围
源或目标的开始大于结束
源范围的大小将溢出从 target_begin 开始的目标列

Throws:

std::out_of_range – 用于任何无效范围。
cudf::data_type_error – 如果 target 和 source 的类型不同。
cudf::data_type_error – 如果数据类型不是固定宽度、字符串或字典

Parameters:

source – 要从中复制的列，位于范围内
target – 从范围外复制的列
source_begin – 源范围的起始索引（包含）
source_end – 源范围中最后一个元素的索引（不包括）
target_begin – 目标范围的起始索引（包含）
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回列的设备内存的设备内存资源

Returns:

结果目标列

std::unique_ptr<column> copy_if_else(column_view const &lhs, column_view const &rhs, column_view const &boolean_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

返回一个新列，其中每个元素根据boolean_mask中相应元素的值从lhs或rhs中选择。

从rhs或lhs中选择输出列中的每个元素i，使用以下规则：output[i] = (boolean_mask.valid(i) and boolean_mask[i]) ? lhs[i] : rhs[i]

Throws:

cudf::data_type_error – 如果 lhs 和 rhs 不是同一类型
std::invalid_argument – 如果 lhs 和 rhs 的长度不相同
cudf::data_type_error – 如果布尔掩码的类型不是布尔型
std::invalid_argument – 如果布尔掩码的长度与 lhs 和 rhs 不相同

Parameters:

lhs – 左侧的 column_view
rhs – 右侧的 column_view
boolean_mask – 表示每个元素的“左（真）/右（假）”布尔值的type_id::BOOL8列。空元素表示假。
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回列的设备内存的设备内存资源

Returns:

新列包含所选元素

std::unique_ptr<column> copy_if_else(scalar const &lhs, column_view const &rhs, column_view const &boolean_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

返回一个新列，其中每个元素根据boolean_mask中相应元素的值从lhs或rhs中选择。

从rhs或lhs中选择输出列中的每个元素i，使用以下规则：output[i] = (boolean_mask.valid(i) and boolean_mask[i]) ? lhs : rhs[i]

Throws:

cudf::data_type_error – 如果 lhs 和 rhs 不是同一类型
cudf::data_type_error – 如果布尔掩码的类型不是布尔型
std::invalid_argument – 如果布尔掩码的长度与 lhs 和 rhs 不相同

Parameters:

lhs – 左侧标量
rhs – 右侧的 column_view
boolean_mask – 表示每个元素的“左（真）/右（假）”布尔值的type_id::BOOL8列。空元素表示假。
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回列的设备内存的设备内存资源

Returns:

新列包含所选元素

std::unique_ptr<column> copy_if_else(column_view const &lhs, scalar const &rhs, column_view const &boolean_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

返回一个新列，其中每个元素根据boolean_mask中相应元素的值从lhs或rhs中选择。

从rhs或lhs中选择输出列中的每个元素i，使用以下规则：output[i] = (boolean_mask.valid(i) and boolean_mask[i]) ? lhs[i] : rhs

Throws:

cudf::data_type_error – 如果 lhs 和 rhs 不是同一类型
cudf::data_type_error – 如果布尔掩码的类型不是布尔型
std::invalid_argument – 如果布尔掩码的长度与 lhs 和 rhs 不相同

Parameters:

lhs – 左侧的 column_view
rhs – 右侧标量
boolean_mask – 表示每个元素的“左（真）/右（假）”布尔值的type_id::BOOL8列。空元素表示假。
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回列的设备内存的设备内存资源

Returns:

新列包含所选元素

std::unique_ptr<column> copy_if_else(scalar const &lhs, scalar const &rhs, column_view const &boolean_mask, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

返回一个新列，其中每个元素根据boolean_mask中相应元素的值从lhs或rhs中选择。

从rhs或lhs中选择输出列中的每个元素i，使用以下规则：output[i] = (boolean_mask.valid(i) and boolean_mask[i]) ? lhs : rhs

Throws:

cudf::logic_error – 如果布尔掩码不是布尔类型

Parameters:

lhs – 左侧标量
rhs – 右侧标量
boolean_mask – 表示每个元素的“左（真）/右（假）”布尔值的type_id::BOOL8列。空元素表示假。
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回列的设备内存的设备内存资源

Returns:

新列包含所选元素

std::unique_ptr<scalar> get_element(column_view const &input, size_type index, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从列中获取指定索引处的元素。

警告

此函数开销较大（会触发内核启动）。因此，不建议在性能敏感的代码或循环中使用。

Throws:

std::out_of_range – 如果 index 不在范围 [0, input.size()) 内

Parameters:

input – 从中获取元素的列视图
index – 索引到 input 以获取元素
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回标量的设备内存的设备内存资源

Returns:

包含单个值的标量

std::unique_ptr<table> sample(table_view const &input, size_type const n, sample_with_replacement replacement = sample_with_replacement::FALSE, int64_t const seed = 0, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

从给定的input中随机收集n个样本。

Example:
input: {col1: {1, 2, 3, 4, 5}, col2: {6, 7, 8, 9, 10}}
n: 3
replacement: false

output:       {col1: {3, 1, 4}, col2: {8, 6, 9}}

replacement: true

output:       {col1: {3, 1, 1}, col2: {8, 6, 6}}

Throws:

cudf::logic_error – 如果 n > input.num_rows() 并且 replacement == FALSE。
cudf::logic_error – 如果 n < 0。

Parameters:

input – 要采样的表的视图
n – 期望从 input 中获取的非负样本数量
replacement – 允许或禁止对同一行进行多次采样
seed – 用于初始化随机数生成器的种子值
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回表的设备内存的设备内存资源

Returns:

包含来自 input 样本的表格

bool has_nonempty_nulls(column_view const &input, rmm::cuda_stream_view stream = cudf::get_default_stream())#

检查列或其子列是否包含非空的行。

一个LIST或STRING列可能包含被标记为null的非空行。一个STRUCT或LIST列可能包含具有非空null行的子列。其他类型的列被认为不能具有非空null行。例如，固定宽度列没有“空”行的概念。

注意

此函数是精确的。如果它返回 true，则存在一个或多个非空 null 元素。

Parameters:

input – 要检查非空null行的列（及其后代）。
stream – 用于设备内存操作和内核启动的CUDA流

Returns:

true 如果列或其子列有空行

Returns:

false 如果列或其子列没有非空的行

bool may_have_nonempty_nulls(column_view const &input)#

近似判断一个列或其子列可能包含非空的空元素。

可能会出现误报，但不会出现漏报。

与精确的has_nonempty_nulls()函数相比，此函数通常更高效。

复杂度：

最佳情况：O(count_descendants(input))
最坏情况：O(count_descendants(input)) * m，其中 m 是最大后代中的行数

注意

这个函数是近似的。

true: 可能存在非空的空元素
false: 非空的 null 元素肯定不存在

Parameters:: input – 要检查非空空行的列（及其后代列）
Returns:: true 如果列或其子列有空行
Returns:: false 如果该列及其后代列都没有空行

std::unique_ptr<column> purge_nonempty_nulls(column_view const &input, rmm::cuda_stream_view stream = cudf::get_default_stream(), rmm::device_async_resource_ref mr = cudf::get_current_device_resource_ref())#

将input复制到输出中，同时清除列或其子项中的任何非空null行。

如果输入列不是复合类型（LIST/STRING/STRUCT/DICTIONARY），输出将与输入相同。

清除操作仅直接适用于LIST和STRING列，但也间接适用于STRUCT/DICTIONARY列，因为这些列可能包含LIST或STRING类型的子列。

示例：

auto const lists   = lists_column_wrapper<int32_t>{ {0,1}, {2,3}, {4,5} }.release();
cudf::set_null_mask(lists->null_mask(), 1, 2, false);

lists[1] is now null, but the lists child column still stores `{2,3}`.
The lists column contents will be:
  Validity: 101
  Offsets:  [0, 2, 4, 6]
  Child:    [0, 1, 2, 3, 4, 5]

After purging the contents of the list's null rows, the column's contents will be:
  Validity: 101
  Offsets:  [0, 2, 2, 4]
  Child:    [0, 1, 4, 5]

auto const strings = strings_column_wrapper{ "AB", "CD", "EF" }.release();
cudf::set_null_mask(strings->null_mask(), 1, 2, false);

strings[1] is now null, but the strings column still stores `"CD"`.
The lists column contents will be:
  Validity: 101
  Offsets:  [0, 2, 4, 6]
  Child:    [A, B, C, D, E, F]

After purging the contents of the list's null rows, the column's contents
will be:
  Validity: 101
  Offsets:  [0, 2, 2, 4]
  Child:    [A, B, E, F]

auto const lists   = lists_column_wrapper<int32_t>{ {0,1}, {2,3}, {4,5} };
auto const structs = structs_column_wrapper{ {lists}, null_at(1) };

structs[1].child is now null, but the lists column still stores `{2,3}`.
The lists column contents will be:
  Validity: 101
  Offsets:  [0, 2, 4, 6]
  Child:    [0, 1, 2, 3, 4, 5]

After purging the contents of the list's null rows, the column's contents
will be:
  Validity: 101
  Offsets:  [0, 2, 2, 4]
  Child:    [0, 1, 4, 5]

Parameters:

input – 要检查并清除空行的列
stream – 用于设备内存操作和内核启动的CUDA流
mr – 用于分配返回列的设备内存的设备内存资源

Returns:

一个新列，其内容与input相同，但已清除空行