Reduction

Files
file	reduction.hpp

Enumerations
enum class	cudf::scan_type : bool { INCLUSIVE , EXCLUSIVE }
	Enum to describe scan operation type.

Functions
std::unique_ptr< scalar >	cudf::reduce (column_view const &col, reduce_aggregation const &agg, data_type output_dtype, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Computes the reduction of the values in all rows of a column. More...
std::unique_ptr< scalar >	cudf::reduce (column_view const &col, reduce_aggregation const &agg, data_type output_dtype, std::optional< std::reference_wrapper< scalar const >> init, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Computes the reduction of the values in all rows of a column with an initial value. More...
std::unique_ptr< column >	cudf::segmented_reduce (column_view const &segmented_values, device_span< size_type const > offsets, segmented_reduce_aggregation const &agg, data_type output_dtype, null_policy null_handling, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Compute reduction of each segment in the input column. More...
std::unique_ptr< column >	cudf::segmented_reduce (column_view const &segmented_values, device_span< size_type const > offsets, segmented_reduce_aggregation const &agg, data_type output_dtype, null_policy null_handling, std::optional< std::reference_wrapper< scalar const >> init, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Compute reduction of each segment in the input column with an initial value. Only SUM, PRODUCT, MIN, MAX, ANY, and ALL aggregations are supported. More...
std::unique_ptr< column >	cudf::scan (column_view const &input, scan_aggregation const &agg, scan_type inclusive, null_policy null_handling=null_policy::EXCLUDE, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Computes the scan of a column. More...
std::pair< std::unique_ptr< scalar >, std::unique_ptr< scalar > >	cudf::minmax (column_view const &col, rmm::cuda_stream_view stream=cudf::get_default_stream(), rmm::device_async_resource_ref mr=cudf::get_current_device_resource_ref())
	Determines the minimum and maximum values of a column. More...

Detailed Description

Function Documentation

minmax()

std::pair<std::unique_ptr<scalar>, std::unique_ptr<scalar> > cudf::minmax	(	column_view const &	col,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

Determines the minimum and maximum values of a column.

Parameters

col	column to compute minmax
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned column's device memory

Returns

A std::pair of scalars with the first scalar being the minimum value and the second scalar being the maximum value of the input column.

reduce() [1/2]

std::unique_ptr<scalar> cudf::reduce	(	column_view const &	col,
		reduce_aggregation const &	agg,
		data_type	output_dtype,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

Computes the reduction of the values in all rows of a column.

This function does not detect overflows in reductions. When output_dtype does not match the col.type(), their values may be promoted to int64_t or double for computing aggregations and then cast to output_dtype before returning.

Only min and max ops are supported for reduction of non-arithmetic types (e.g. timestamp or string).

Any null values are skipped for the operation. If the reduction fails, the output scalar returns with is_valid()==false.

For empty or all-null input, the result is generally a null scalar except for specific aggregations where the aggregation has a well-defined output.

If the input column is an arithmetic type, the output_dtype can be any arithmetic type. If the input column is a non-arithmetic type (e.g. timestamp or string) the output_dtype must match the col.type(). If the reduction type is any or all, the output_dtype must be type BOOL8.

Aggregation	Output Type	Init Value	Empty Input	Comments
SUM/PRODUCT	output_dtype	yes	NA	Input accumulated into output_dtype variable
SUM_OF_SQUARES	output_dtype	no	NA	Input accumulated into output_dtype variable
MIN/MAX	col.type	yes	NA	Supports arithmetic, timestamp, duration, string
ANY/ALL	BOOL8	yes	True for ALL only	Checks for non-zero elements
MEAN/VARIANCE/STD	FLOAT32/FLOAT64	no	NA	output_dtype must be a float type
MEDIAN/QUANTILE	FLOAT64	no	NA
NUNIQUE	output_dtype	no	1 if all-nulls	May process null rows
NTH_ELEMENT	col.type	no	NA
BITWISE_AGG	col.type	no	NA	Supports only integral types
HISTOGRAM/MERGE_HISTOGRAM	LIST of col.type	no	empty list
COLLECT_LIST/COLLECT_SET	LIST of col.type	no	empty list
TDIGEST/MERGE_TDIGEST	STRUCT	no	empty struct	tdigest scalar is returned
HOST_UDF	output_dtype	yes	NA	Custom UDF could ignore output_dtype

The NA in the table indicates an output scalar with is_valid()==false

Exceptions

cudf::logic_error	if reduction is called for non-arithmetic output type and operator other than min and max.
cudf::logic_error	if input column data type is not convertible to output_dtype.
cudf::logic_error	if min or max reduction is called and the output type does not match the input column data type.
cudf::logic_error	if any or all reduction is called and the output type is not BOOL8.
cudf::logic_error	if mean, var, or std reduction is called and the output_dtype is not floating point.

Parameters

col	Input column view
agg	Aggregation operator applied by the reduction
output_dtype	The output scalar type
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned scalar's device memory

Returns

Output scalar with reduce result

reduce() [2/2]

std::unique_ptr<scalar> cudf::reduce	(	column_view const &	col,
		reduce_aggregation const &	agg,
		data_type	output_dtype,
		std::optional< std::reference_wrapper< scalar const >>	init,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

Computes the reduction of the values in all rows of a column with an initial value.

Only sum, product, min, max, any, and all reductions are supported.

See also

cudf::reduce(column_view const&,reduce_aggregation const&,data_type,rmm::cuda_stream_view,rmm::device_async_resource_ref) for more details

Exceptions

cudf::logic_error

if reduction is not sum, product, min, max, any, or all and init is specified.

Parameters

col	Input column view
agg	Aggregation operator applied by the reduction
output_dtype	The output scalar type
init	The initial value of the reduction
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned scalar's device memory

Returns

Output scalar with reduce result

scan()

std::unique_ptr<column> cudf::scan	(	column_view const &	input,
		scan_aggregation const &	agg,
		scan_type	inclusive,
		null_policy	null_handling = null_policy::EXCLUDE,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

Computes the scan of a column.

The null values are skipped for the operation, and if an input element at i is null, then the output element at i will also be null.

Exceptions

cudf::logic_error

if column datatype is not numeric type.

Parameters

[in]	input	The input column view for the scan
[in]	agg	unique_ptr to aggregation operator applied by the scan
[in]	inclusive	The flag for applying an inclusive scan if scan_type::INCLUSIVE, an exclusive scan if scan_type::EXCLUSIVE.
[in]	null_handling	Exclude null values when computing the result if null_policy::EXCLUDE. Include nulls if null_policy::INCLUDE. Any operation with a null results in a null.
[in]	stream	CUDA stream used for device memory operations and kernel launches
[in]	mr	Device memory resource used to allocate the returned scalar's device memory

Returns

Scanned output column

segmented_reduce() [1/2]

std::unique_ptr<column> cudf::segmented_reduce	(	column_view const &	segmented_values,
		device_span< size_type const >	offsets,
		segmented_reduce_aggregation const &	agg,
		data_type	output_dtype,
		null_policy	null_handling,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

Compute reduction of each segment in the input column.

This function does not detect overflows in reductions. When output_dtype does not match the segmented_values.type(), their values may be promoted to int64_t or double for computing aggregations and then cast to output_dtype before returning.

Null values are treated as identities during reduction.

If the segment is empty, the row corresponding to the result of the segment is null.

If any index in offsets is out of bound of segmented_values, the behavior is undefined.

If the input column has arithmetic type, output_dtype can be any arithmetic type. If the input column has non-arithmetic type, e.g. timestamp, the same output type must be specified.

If input is not empty, the result is always nullable.

Exceptions

cudf::logic_error	if reduction is called for non-arithmetic output type and operator other than min and max.
cudf::logic_error	if input column data type is not convertible to output_dtype type.
cudf::logic_error	if min or max reduction is called and the output_dtype does not match the input column data type.
cudf::logic_error	if any or all reduction is called and the output_dtype is not BOOL8.

Parameters

segmented_values	Column view of segmented inputs
offsets	Each segment's offset of segmented_values. A list of offsets with size num_segments + 1. The size of ith segment is offsets[i+1] - offsets[i].
agg	Aggregation operator applied by the reduction
output_dtype	The output column type
null_handling	If INCLUDE, the reduction is valid if all elements in a segment are valid, otherwise null. If EXCLUDE, the reduction is valid if any element in the segment is valid, otherwise null.
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned scalar's device memory

Returns

Output column with results of segmented reduction

segmented_reduce() [2/2]

std::unique_ptr<column> cudf::segmented_reduce	(	column_view const &	segmented_values,
		device_span< size_type const >	offsets,
		segmented_reduce_aggregation const &	agg,
		data_type	output_dtype,
		null_policy	null_handling,
		std::optional< std::reference_wrapper< scalar const >>	init,
		rmm::cuda_stream_view	stream = cudf::get_default_stream(),
		rmm::device_async_resource_ref	mr = cudf::get_current_device_resource_ref()
	)

Compute reduction of each segment in the input column with an initial value. Only SUM, PRODUCT, MIN, MAX, ANY, and ALL aggregations are supported.

Parameters

segmented_values	Column view of segmented inputs
offsets	Each segment's offset of segmented_values. A list of offsets with size num_segments + 1. The size of ith segment is offsets[i+1] - offsets[i].
agg	Aggregation operator applied by the reduction
output_dtype	The output column type
null_handling	If INCLUDE, the reduction is valid if all elements in a segment are valid, otherwise null. If EXCLUDE, the reduction is valid if any element in the segment is valid, otherwise null.
init	The initial value of the reduction
stream	CUDA stream used for device memory operations and kernel launches
mr	Device memory resource used to allocate the returned scalar's device memory

Returns

Output column with results of segmented reduction.