statistics.hpp

Go to the documentation of this file.

#pragma once
 
#include <algorithm>  
#include <cmath>  
#include <functional>  
#include <iterator>  
#include <map>  
#include <numeric>  
#include <stdexcept>  
#include <string>  
#include <type_traits>  
#include <utility>  
#include <vector>  
 
#include <cpp-toolbox/type_traits.hpp>
 
namespace toolbox::math
{
 
template<typename TContainer>
void check_empty(const TContainer& data, const char* func_name)
{
  if (data.empty()) {
    std::string err_msg = "Input container for '";
    err_msg += func_name;
    err_msg += "' cannot be empty.";
    throw std::invalid_argument(err_msg);
  }
}
 
template<typename TContainer>
double mean(const TContainer& data)
{
  using ValueType = typename TContainer::value_type;
  static_assert(std::is_arithmetic_v<ValueType>,
                "Mean requires arithmetic type elements.");
  check_empty(data, "mean");
 
  double sum = 0.0;
  for (const auto& val : data) {
    sum += static_cast<double>(val);  // 使用 double 进行累加保证精度/Use double
                                      // for accumulation to ensure precision
  }
  return sum / data.size();
}
 
template<typename TContainer>
double median(const TContainer& data)
{
  using ValueType = typename TContainer::value_type;
  static_assert(std::is_arithmetic_v<ValueType>,
                "Median requires arithmetic type elements for calculation.");
  static_assert(toolbox::traits::is_less_than_comparable_v<ValueType>,
                "Median requires comparable elements for sorting.");
  check_empty(data, "median");
 
  std::vector<ValueType> sorted_data(
      data.begin(),
      data.end());  // 复制数据以便排序/Copy data for sorting
  std::sort(sorted_data.begin(), sorted_data.end());
 
  size_t n = sorted_data.size();
  if (n % 2 != 0) {
    // 奇数个元素/Odd number of elements
    return static_cast<double>(sorted_data[n / 2]);
  } else {
    // 偶数个元素/Even number of elements
    return static_cast<double>(sorted_data[n / 2 - 1] + sorted_data[n / 2])
        / 2.0;
  }
}
 
template<typename TContainer>
std::vector<typename TContainer::value_type> mode(const TContainer& data)
{
  using ValueType = typename TContainer::value_type;
  static_assert(
      toolbox::traits::is_less_than_comparable_v<ValueType>,
      "Mode requires element type to be comparable (for std::map keys).");
  // 允许空容器的众数为空集合/Allow mode of empty container to be empty set
  if (data.empty()) {
    return {};
  }
 
  std::map<ValueType, size_t> counts;
  for (const auto& val : data) {
    counts[val]++;
  }
 
  size_t max_freq = 0;
  for (const auto& pair : counts) {
    if (pair.second > max_freq) {
      max_freq = pair.second;
    }
  }
 
  std::vector<ValueType> modes;
  if (max_freq > 0) {  // 确保至少有一个元素/Ensure at least one element
    for (const auto& pair : counts) {
      if (pair.second == max_freq) {
        modes.push_back(pair.first);
      }
    }
    // 为了结果的一致性，对众数进行排序 (如果它们本身是可比较的)/Sort modes for
    // consistency (if comparable) 如果 ValueType 不支持排序，但作为 map key
    // 必须支持，这里 sort 应该也没问题/If ValueType is not sortable, but as map
    // key it must be, so sort is fine here
    std::sort(modes.begin(), modes.end());
  }
  return modes;
}
 
template<typename TContainer>
double variance(const TContainer& data, bool sample_variance = true)
{
  using ValueType = typename TContainer::value_type;
  static_assert(std::is_arithmetic_v<ValueType>,
                "Variance requires arithmetic type elements.");
 
  size_t n = data.size();
  const char* func_name_str =
      sample_variance ? "sample variance" : "population variance";
 
  if (sample_variance) {
    if (n < 2) {
      std::string err_msg =
          "Sample variance requires at least 2 data points. Container for '";
      err_msg += func_name_str;
      err_msg += "' is too small.";
      throw std::invalid_argument(err_msg);
    }
  } else {  // population variance/总体方差
    check_empty(data, func_name_str);  // 总体方差至少需要1个元素/Population
                                       // variance requires at least 1 element
  }
  // mean() 内部会调用 check_empty/mean() will call check_empty internally
  double m = mean(data);
  double sum_sq_diff = 0.0;
  for (const auto& val : data) {
    sum_sq_diff += std::pow(static_cast<double>(val) - m, 2);
  }
 
  if (sample_variance) {
    return sum_sq_diff / (n - 1);
  } else {
    return sum_sq_diff / n;
  }
}
 
template<typename TContainer>
double stdev(const TContainer& data, bool sample_stdev = true)
{
  using ValueType = typename TContainer::value_type;
  static_assert(std::is_arithmetic_v<ValueType>,
                "Standard deviation requires arithmetic type elements.");
  // variance 函数会处理大小检查和空容器情况/variance will handle size and empty
  // checks
  return std::sqrt(variance(data, sample_stdev));
}
 
template<typename TContainer>
typename TContainer::value_type sum(const TContainer& data)
{
  using ValueType = typename TContainer::value_type;
  static_assert(std::is_arithmetic_v<ValueType>,
                "Sum requires arithmetic type elements.");
  if (data.empty()) {
    return static_cast<ValueType>(0);  // 空集合的和为0/Sum of empty set is 0
  }
  // 注意：对于较小整数类型和大量数据，这里可能溢出。考虑使用 sum_d。/Note: For
  // small integer types and large data, may overflow. Consider using sum_d.
  return std::accumulate(data.begin(), data.end(), static_cast<ValueType>(0));
}
 
template<typename TContainer>
double sum_d(const TContainer& data)
{
  using ValueType = typename TContainer::value_type;
  static_assert(std::is_arithmetic_v<ValueType>,
                "Sum (double) requires arithmetic type elements.");
  if (data.empty()) {
    return 0.0;
  }
  double current_sum = 0.0;
  for (const auto& val : data) {
    current_sum += static_cast<double>(val);
  }
  return current_sum;
}
 
template<typename TContainer>
typename TContainer::value_type min(const TContainer& data)
{
  using ValueType = typename TContainer::value_type;
  static_assert(toolbox::traits::is_less_than_comparable_v<ValueType>,
                "min requires comparable elements.");
  check_empty(data, "min");
  return *std::min_element(data.begin(), data.end());
}
 
template<typename TContainer>
typename TContainer::value_type max(const TContainer& data)
{
  using ValueType = typename TContainer::value_type;
  // std::max_element 默认使用 operator</std::max_element uses operator< by
  // default
  static_assert(toolbox::traits::is_less_than_comparable_v<ValueType>,
                "max requires comparable elements.");
  check_empty(data, "max");
  return *std::max_element(data.begin(), data.end());
}
 
template<typename TContainer>
typename TContainer::value_type range(const TContainer& data)
{
  using ValueType = typename TContainer::value_type;
  static_assert(std::is_arithmetic_v<ValueType>,
                "Range requires arithmetic type elements for subtraction.");
  static_assert(toolbox::traits::is_less_than_comparable_v<ValueType>,
                "Range requires comparable elements to find min/max.");
  check_empty(data, "range");  // min 和 max 内部也会检查/min and max will also
                               // check internally
 
  // C++17 中 std::minmax_element 已经可用/std::minmax_element is available in
  // C++17
  auto [min_it, max_it] = std::minmax_element(data.begin(), data.end());
  return static_cast<ValueType>(*max_it - *min_it);
}
 
template<typename TContainer>
double percentile(const TContainer& data, double p)
{
  using ValueType = typename TContainer::value_type;
  static_assert(
      std::is_arithmetic_v<ValueType>,
      "Percentile requires arithmetic type elements for calculation.");
  static_assert(toolbox::traits::is_less_than_comparable_v<ValueType>,
                "Percentile requires comparable elements for sorting.");
  check_empty(data, "percentile");
 
  if (p < 0.0 || p > 1.0) {
    throw std::out_of_range(
        "Percentile p must be between 0.0 and 1.0 inclusive.");
  }
 
  std::vector<ValueType> sorted_data(data.begin(), data.end());
  std::sort(sorted_data.begin(), sorted_data.end());
 
  // Avoid direct floating point equality comparison which triggers
  // -Wfloat-equal when building with strict warnings. Treat values very
  // close to the bounds as the bounds themselves.
  if (p <= 0.0)
    return static_cast<double>(sorted_data.front());
  if (p >= 1.0)
    return static_cast<double>(sorted_data.back());
 
  // 线性插值法 (R-7 in R, type 7 in NumPy, "Excel.Exclusive" in Excel)/Linear
  // interpolation (R-7 in R, type 7 in NumPy, "Excel.Exclusive" in Excel)
  // (N-1)p gives 0-based index./(N-1)p gives 0-based index.
  double index_double = p * (static_cast<double>(sorted_data.size()) - 1.0);
  size_t lower_index = static_cast<size_t>(std::floor(index_double));
  size_t upper_index = static_cast<size_t>(std::ceil(index_double));
 
  if (lower_index == upper_index) {  // 索引是整数/Index is integer
    return static_cast<double>(sorted_data[lower_index]);
  } else {  // 在两个值之间插值/Interpolate between two values
    double lower_val = static_cast<double>(sorted_data[lower_index]);
    double upper_val = static_cast<double>(sorted_data[upper_index]);
    return lower_val + (index_double - lower_index) * (upper_val - lower_val);
  }
}
 
template<typename TContainer>
std::vector<typename TContainer::value_type> min_k(const TContainer& data,
                                                   size_t k)
{
  using ValueType = typename TContainer::value_type;
  static_assert(
      toolbox::traits::is_less_than_comparable_v<ValueType>,
      "min_k requires elements comparable with operator< for sorting.");
 
  if (k == 0) {
    return {};
  }
  check_empty(
      data,
      "min_k");  // 如果 k > 0, data 不应为空/If k > 0, data should not be empty
 
  std::vector<ValueType> result;
  if (k >= data.size()) {  // 如果 k
                           // 大于或等于容器大小，返回所有元素排序后的结果/If k
                           // >= container size, return all sorted
    result.assign(data.begin(), data.end());
    std::sort(result.begin(), result.end());
  } else {
    result.resize(k);  // 必须先调整大小/Must resize first
    std::partial_sort_copy(data.begin(),
                           data.end(),  // 从 data 复制并部分排序到 result/Copy
                                        // from data and partial sort to result
                           result.begin(),
                           result.end());
  }
  return result;
}
 
template<typename TContainer>
std::vector<typename TContainer::value_type> max_k(const TContainer& data,
                                                   size_t k)
{
  using ValueType = typename TContainer::value_type;
  // std::partial_sort_copy with std::greater
  // 需要元素可比较/std::partial_sort_copy with std::greater requires comparable
  // elements std::greater<T> 使用
  // operator>，或者等价地，operator</std::greater<T> uses operator> or
  // equivalently operator<
  static_assert(toolbox::traits::is_greater_than_comparable_v<ValueType>
                    || toolbox::traits::is_less_than_comparable_v<ValueType>,
                "max_k requires comparable elements (operator> or operator< "
                "for std::greater).");
 
  if (k == 0) {
    return {};
  }
  check_empty(data, "max_k");
 
  std::vector<ValueType> result;
  if (k >= data.size()) {
    result.assign(data.begin(), data.end());
    std::sort(result.begin(),
              result.end(),
              std::greater<ValueType>());  // 使用 std::greater 进行降序排序/Use
                                           // std::greater for descending sort
  } else {
    result.resize(k);
    std::partial_sort_copy(
        data.begin(),
        data.end(),
        result.begin(),
        result.end(),
        std::greater<ValueType>());  // 使用 std::greater 获取最大的k个/Use
                                     // std::greater to get top k
  }
  return result;
}
 
}  // namespace toolbox::math