aggregation.hpp

Go to the documentation of this file.

/*
 * Copyright (c) 2019-2025, NVIDIA CORPORATION.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
 
#pragma once
 
#include <cudf/types.hpp>
#include <cudf/utilities/export.hpp>
 
#include <functional>
#include <memory>
#include <vector>
 
namespace CUDF_EXPORT cudf {
// forward declaration
namespace detail {
class simple_aggregations_collector;
class aggregation_finalizer;
}  // namespace detail
 
enum class rank_method : int32_t {
  FIRST,    
  AVERAGE,  
  MIN,      
  MAX,      
  DENSE     
};
 
enum class rank_percentage : int32_t {
  NONE,             
  ZERO_NORMALIZED,  
  ONE_NORMALIZED    
};
 
enum class bitwise_op : int32_t {
  AND,  
  OR,   
  XOR   
};
 
class aggregation {
 public:
  enum Kind {
    SUM,                
    SUM_WITH_OVERFLOW,  
    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,                
    PTX,                
    CUDA,               
    HOST_UDF,           
    MERGE_LISTS,        
    MERGE_SETS,         
    MERGE_M2,           
    COVARIANCE,         
    CORRELATION,        
    TDIGEST,            
    MERGE_TDIGEST,      
    HISTOGRAM,          
    MERGE_HISTOGRAM,    
    BITWISE_AGG         
  };
 
  aggregation() = delete;
 
  aggregation(aggregation::Kind a) : kind{a} {}
  Kind kind;  
  virtual ~aggregation() = default;
 
  [[nodiscard]] virtual bool is_equal(aggregation const& other) const { return kind == other.kind; }
 
  [[nodiscard]] virtual size_t do_hash() const { return std::hash<int>{}(kind); }
 
  [[nodiscard]] virtual std::unique_ptr<aggregation> clone() const = 0;
 
  // override functions for compound aggregations
  virtual std::vector<std::unique_ptr<aggregation>> get_simple_aggregations(
    data_type col_type, cudf::detail::simple_aggregations_collector& collector) const = 0;
 
  virtual void finalize(cudf::detail::aggregation_finalizer& finalizer) const = 0;
};
 
class rolling_aggregation : public virtual aggregation {
 public:
  ~rolling_aggregation() override = default;
 
 protected:
  rolling_aggregation() {}
  using aggregation::aggregation;
};
 
class groupby_aggregation : public virtual aggregation {
 public:
  ~groupby_aggregation() override = default;
 
 protected:
  groupby_aggregation() {}
};
 
class groupby_scan_aggregation : public virtual aggregation {
 public:
  ~groupby_scan_aggregation() override = default;
 
 protected:
  groupby_scan_aggregation() {}
};
 
class reduce_aggregation : public virtual aggregation {
 public:
  ~reduce_aggregation() override = default;
 
 protected:
  reduce_aggregation() {}
};
 
class scan_aggregation : public virtual aggregation {
 public:
  ~scan_aggregation() override = default;
 
 protected:
  scan_aggregation() {}
};
 
class segmented_reduce_aggregation : public virtual aggregation {
 public:
  ~segmented_reduce_aggregation() override = default;
 
 protected:
  segmented_reduce_aggregation() {}
};
 
enum class udf_type : bool { CUDA, PTX };
enum class correlation_type : int32_t { PEARSON, KENDALL, SPEARMAN };
enum class ewm_history : int32_t { INFINITE, FINITE };
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_sum_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_sum_with_overflow_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_product_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_min_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_max_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_count_aggregation(null_policy null_handling = null_policy::EXCLUDE);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_any_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_all_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_histogram_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_sum_of_squares_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_mean_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_m2_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_variance_aggregation(size_type ddof = 1);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_std_aggregation(size_type ddof = 1);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_median_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_quantile_aggregation(std::vector<double> const& quantiles,
                                                interpolation interp = interpolation::LINEAR);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_argmax_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_argmin_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_nunique_aggregation(null_policy null_handling = null_policy::EXCLUDE);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_nth_element_aggregation(
  size_type n, null_policy null_handling = null_policy::INCLUDE);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_row_number_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_ewma_aggregation(double const center_of_mass, ewm_history history);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_rank_aggregation(rank_method method,
                                            order column_order         = order::ASCENDING,
                                            null_policy null_handling  = null_policy::EXCLUDE,
                                            null_order null_precedence = null_order::AFTER,
                                            rank_percentage percentage = rank_percentage::NONE);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_collect_list_aggregation(
  null_policy null_handling = null_policy::INCLUDE);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_collect_set_aggregation(
  null_policy null_handling = null_policy::INCLUDE,
  null_equality nulls_equal = null_equality::EQUAL,
  nan_equality nans_equal   = nan_equality::ALL_EQUAL);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_lag_aggregation(size_type offset);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_lead_aggregation(size_type offset);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_udf_aggregation(udf_type type,
                                           std::string const& user_defined_aggregator,
                                           data_type output_type);
 
// Forward declaration of `host_udf_base` for the factory function of `HOST_UDF` aggregation.
class host_udf_base;
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_host_udf_aggregation(std::unique_ptr<host_udf_base> host_udf);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_merge_lists_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_merge_sets_aggregation(
  null_equality nulls_equal = null_equality::EQUAL,
  nan_equality nans_equal   = nan_equality::ALL_EQUAL);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_merge_m2_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_merge_histogram_aggregation();
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_covariance_aggregation(size_type min_periods = 1, size_type ddof = 1);
 
template <typename Base = aggregation>
std::unique_ptr<Base> make_correlation_aggregation(correlation_type type,
                                                   size_type min_periods = 1);
 
template <typename Base>
std::unique_ptr<Base> make_tdigest_aggregation(int max_centroids = 1000);
 
template <typename Base>
std::unique_ptr<Base> make_merge_tdigest_aggregation(int max_centroids = 1000);
 
template <typename Base>
std::unique_ptr<Base> make_bitwise_aggregation(bitwise_op op);
 
bool is_valid_aggregation(data_type source, aggregation::Kind kind);
  // end of group
}  // namespace CUDF_EXPORT cudf