anomaly_detection 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd8b32a5d482c312deb58949c67489b21ce336ddfd90d6215a0f5cf7650f8067
-  data.tar.gz: 3ebd3c26210e64df4f07a13dccf7e0f0276e4cc2e825d0684a9947cbc5d94bc8
+  metadata.gz: b7e239fb8a7cef345a877f6f9ad0d980f820f35a89b66248d48c6350a92ce750
+  data.tar.gz: 617ce11f0df37dc0033b120ec77a99d719bb9ba3254097cbfb38e420b6a8398f
 SHA512:
-  metadata.gz: fd3972f75c65c104057b0b3b4102462e66cf490a901b3d18b2aebd623916d058d0c7eeaa0528d5013838605e36ae29efacaaf2bcbb76c74f90740bb36c191fca
-  data.tar.gz: 0dccba6f00ee2b41683aaa3833108b61095ac02f1be9cf4c6d581a822765022fa8fbd99f7e6afee499768eda69bd2355775af90592a46672ff829b9c38b0735d
+  metadata.gz: bde266b02df66b998313177272f2d24d749442a96f7610ea57c70e057e3aaa723248fcee8e487839f15ba078bd3ece933ecf00b803f5790b4799a9dbd909045b
+  data.tar.gz: 56873cb20e990426e03871320b4217a50d6f2ff446ac0e848f627c9aa2a8ab2e8b0f8ee6c7084f08c5795930250232e4ff0282b60a9c200fb4c5a099fc6a6033

data/CHANGELOG.md

@@ -1,3 +1,12 @@
+## 0.4.0 (2026-04-07)
+
+- Updated AnomalyDetection.cpp to 0.3.0
+- Dropped support for Ruby < 3.3
+
+## 0.3.1 (2025-10-26)
+
+- Fixed error with Rice 4.7
+
 ## 0.3.0 (2024-10-22)
 
 - Dropped support for Ruby < 3.1

data/NOTICE.txt

@@ -1,5 +1,5 @@
 Copyright (C) 2015 Twitter, Inc and other contributors
-Copyright (C) 2021-2024 Andrew Kane
+Copyright (C) 2021-2026 Andrew Kane
 
 This program is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by

data/README.md

@@ -20,9 +20,9 @@ Detect anomalies in a time series
 
 ```ruby
 series = {
-  Date.parse("2020-01-01") => 100,
-  Date.parse("2020-01-02") => 150,
-  Date.parse("2020-01-03") => 136,
+  Date.parse("2025-01-01") => 100,
+  Date.parse("2025-01-02") => 150,
+  Date.parse("2025-01-03") => 136,
   # ...
 }
 
@@ -74,7 +74,7 @@ AnomalyDetection.plot(series, anomalies)
 
 ## Credits
 
-This library was ported from the [AnomalyDetection](https://github.com/twitter/AnomalyDetection) R package and is available under the same license. It uses [stl-cpp](https://github.com/ankane/stl-cpp) for seasonal-trend decomposition and [dist.h](https://github.com/ankane/dist.h) for the quantile function.
+This library was ported from the [AnomalyDetection](https://github.com/twitter/AnomalyDetection) R package and is available under the same license. It uses [stl-cpp](https://github.com/ankane/stl-cpp) for seasonal-trend decomposition and [dist-c](https://github.com/ankane/dist-c) for the quantile function.
 
 ## References
 

data/ext/anomaly_detection/anomaly_detection.hpp

@@ -1,15 +1,21 @@
-/*!
- * AnomalyDetection.cpp v0.1.3
+/*
+ * AnomalyDetection.cpp v0.3.0
  * https://github.com/ankane/AnomalyDetection.cpp
  * GPL-3.0-or-later License
  */
 
 #pragma once
 
+#include <algorithm>
+#include <cmath>
+#include <cstddef>
 #include <functional>
 #include <iostream>
 #include <iterator>
 #include <numeric>
+#include <span>
+#include <stdexcept>
+#include <utility>
 #include <vector>
 
 #include "dist.h"
@@ -17,62 +23,107 @@
 
 namespace anomaly_detection {
 
-enum Direction { Positive, Negative, Both };
+/// The direction to detect anomalies.
+enum class Direction {
+    /// Positive direction.
+    Positive,
+    /// Negative direction.
+    Negative,
+    /// Both directions.
+    Both
+};
+
+namespace detail {
 
-float median_sorted(const std::vector<float>& sorted) {
-    return (sorted[(sorted.size() - 1) / 2] + sorted[sorted.size() / 2]) / 2.0;
+template<typename T>
+T median_sorted(const std::vector<T>& sorted) {
+    return (sorted.at((sorted.size() - 1) / 2) + sorted.at(sorted.size() / 2))
+        / static_cast<T>(2.0);
 }
 
-float median(const std::vector<float>& data) {
-    std::vector<float> sorted(data);
-    std::sort(sorted.begin(), sorted.end());
+template<typename T>
+T median(std::span<const T> data) {
+    std::vector<T> sorted(data.begin(), data.end());
+    std::ranges::sort(sorted);
     return median_sorted(sorted);
 }
 
-float mad(const std::vector<float>& data, float med) {
-    std::vector<float> res;
+template<typename T>
+T mad(const std::vector<T>& data, T med) {
+    std::vector<T> res;
     res.reserve(data.size());
     for (auto v : data) {
-        res.push_back(fabs(v - med));
+        res.push_back(std::abs(v - med));
     }
-    std::sort(res.begin(), res.end());
-    return 1.4826 * median_sorted(res);
+    std::ranges::sort(res);
+    return static_cast<T>(1.4826) * median_sorted(res);
 }
 
-std::vector<size_t> detect_anoms(const std::vector<float>& data, size_t num_obs_per_period, float k, float alpha, bool one_tail, bool upper_tail, bool verbose, std::function<void()> callback) {
-    auto n = data.size();
+template<typename T>
+std::vector<size_t> detect_anoms(
+    std::span<const T> data,
+    size_t num_obs_per_period,
+    float k,
+    float alpha,
+    bool one_tail,
+    bool upper_tail,
+    bool verbose,
+    const std::function<void()>& callback
+) {
+    size_t n = data.size();
 
     // Check to make sure we have at least two periods worth of data for anomaly context
-    if (n < num_obs_per_period * 2) {
-        throw std::invalid_argument("series must contain at least 2 periods");
+    if (n / 2 < num_obs_per_period) {
+        throw std::invalid_argument{"series must contain at least 2 periods"};
     }
 
     // Handle NANs
-    auto nan = std::count_if(data.begin(), data.end(), [](const auto& value) { return std::isnan(value); });
-    if (nan > 0) {
-        throw std::invalid_argument("series contains NANs");
+    bool nans = std::ranges::any_of(data, [](const auto& value) { return std::isnan(value); });
+    if (nans) {
+        throw std::invalid_argument{"series contains NANs"};
+    }
+
+    if (k < 0) {
+        throw std::invalid_argument{"max_anoms must be non-negative"};
+    }
+
+    if (k >= 0.5) {
+        throw std::invalid_argument{"max_anoms must be less than 50% of the data points"};
     }
 
-    std::vector<float> data2;
+    if (alpha < 0) {
+        throw std::invalid_argument{"alpha must be non-negative"};
+    }
+
+    if (alpha > 0.5) {
+        throw std::invalid_argument{"alpha must not be greater than 0.5"};
+    }
+
+    std::vector<T> data2;
     data2.reserve(n);
-    auto med = median(data);
+    T med = median(data);
 
     if (num_obs_per_period > 1) {
         // Decompose data. This returns a univarite remainder which will be used for anomaly detection. Optionally, we might NOT decompose.
-        auto data_decomp = stl::params().robust(true).seasonal_length(data.size() * 10 + 1).fit(data, num_obs_per_period);
-        auto seasonal = data_decomp.seasonal;
-
-        for (size_t i = 0; i < n; i++) {
-            data2.push_back(data[i] - seasonal[i] - med);
+        stl::Stl data_decomp{
+            data, num_obs_per_period, {.seasonal_length = data.size() * 10 + 1, .robust = true}
+        };
+        const std::vector<T>& seasonal = data_decomp.seasonal();
+
+        // TODO use std::views::zip for C++23
+        size_t i = 0;
+        for (auto v : data) {
+            data2.push_back(v - seasonal.at(i) - med);
+            i++;
         }
     } else {
-        for (size_t i = 0; i < n; i++) {
-            data2.push_back(data[i] - med);
+        for (auto v : data) {
+            data2.push_back(v - med);
         }
     }
 
-    auto num_anoms = 0;
-    auto max_outliers = (size_t) n * k;
+    size_t num_anoms = 0;
+    auto max_outliers = static_cast<size_t>(static_cast<float>(n) * k);
     std::vector<size_t> anomalies;
     anomalies.reserve(max_outliers);
 
@@ -80,18 +131,20 @@ std::vector<size_t> detect_anoms(const std::vector<float>& data, size_t num_obs_
     // Use stable sort for indexes for deterministic results
     std::vector<size_t> indexes(n);
     std::iota(indexes.begin(), indexes.end(), 0);
-    std::stable_sort(indexes.begin(), indexes.end(), [&data2](size_t a, size_t b) { return data2[a] < data2[b]; });
-    std::sort(data2.begin(), data2.end());
+    std::ranges::stable_sort(indexes, [&data2](size_t a, size_t b) {
+        return data2.at(a) < data2.at(b);
+    });
+    std::ranges::sort(data2);
 
     // Compute test statistic until r=max_outliers values have been removed from the sample
-    for (auto i = 1; i <= max_outliers; i++) {
+    for (size_t i = 1; i <= max_outliers; i++) {
         if (verbose) {
             std::cout << i << " / " << max_outliers << " completed" << std::endl;
         }
 
         // TODO Improve performance between loop iterations
-        auto ma = median_sorted(data2);
-        std::vector<float> ares;
+        T ma = median_sorted(data2);
+        std::vector<T> ares;
         ares.reserve(data2.size());
         if (one_tail) {
             if (upper_tail) {
@@ -105,36 +158,34 @@ std::vector<size_t> detect_anoms(const std::vector<float>& data, size_t num_obs_
             }
         } else {
             for (auto v : data2) {
-                ares.push_back(fabs(v - ma));
+                ares.push_back(std::abs(v - ma));
             }
         }
 
         // Protect against constant time series
-        auto data_sigma = mad(data2, ma);
+        T data_sigma = mad(data2, ma);
         if (data_sigma == 0.0) {
             break;
         }
 
-        auto iter = std::max_element(ares.begin(), ares.end());
-        auto r_idx_i = std::distance(ares.begin(), iter);
+        auto iter = std::ranges::max_element(ares);
+        ptrdiff_t r_idx_i = std::distance(ares.begin(), iter);
 
         // Only need to take sigma of r for performance
-        auto r = ares[r_idx_i] / data_sigma;
+        T r = ares.at(static_cast<size_t>(r_idx_i)) / data_sigma;
 
-        anomalies.push_back(indexes[r_idx_i]);
+        anomalies.push_back(indexes.at(static_cast<size_t>(r_idx_i)));
         data2.erase(data2.begin() + r_idx_i);
         indexes.erase(indexes.begin() + r_idx_i);
 
         // Compute critical value
-        float p;
-        if (one_tail) {
-            p = 1.0 - alpha / (n - i + 1);
-        } else {
-            p = 1.0 - alpha / (2.0 * (n - i + 1));
-        }
+        double p = one_tail
+            ? (1.0 - alpha / static_cast<double>(n - i + 1))
+            : (1.0 - alpha / (2.0 * static_cast<double>(n - i + 1)));
 
-        auto t = students_t_ppf(p, n - i - 1);
-        auto lam = t * (n - i) / sqrt(((n - i - 1) + t * t) * (n - i + 1));
+        double t = students_t_ppf(p, static_cast<double>(n - i - 1));
+        double lam = t * static_cast<double>(n - i)
+            / std::sqrt((static_cast<double>(n - i - 1) + t * t) * static_cast<double>(n - i + 1));
 
         if (r > lam) {
             num_anoms = i;
@@ -148,63 +199,69 @@ std::vector<size_t> detect_anoms(const std::vector<float>& data, size_t num_obs_
     anomalies.resize(num_anoms);
 
     // Sort like R version
-    std::sort(anomalies.begin(), anomalies.end());
+    std::ranges::sort(anomalies);
 
     return anomalies;
 }
 
-class AnomalyDetectionResult {
-public:
-    std::vector<size_t> anomalies;
-};
-
-class AnomalyDetectionParams {
-    float alpha_ = 0.05;
-    float max_anoms_ = 0.1;
-    Direction direction_ = Direction::Both;
-    bool verbose_ = false;
-    std::function<void()> callback_ = nullptr;
-
-public:
-    inline AnomalyDetectionParams alpha(float alpha) {
-        this->alpha_ = alpha;
-        return *this;
-    };
-
-    inline AnomalyDetectionParams max_anoms(float max_anoms) {
-        this->max_anoms_ = max_anoms;
-        return *this;
-    };
-
-    inline AnomalyDetectionParams direction(Direction direction) {
-        this->direction_ = direction;
-        return *this;
-    };
-
-    inline AnomalyDetectionParams verbose(bool verbose) {
-        this->verbose_ = verbose;
-        return *this;
-    };
-
-    inline AnomalyDetectionParams callback(std::function<void()> callback) {
-        this->callback_ = callback;
-        return *this;
-    };
-
-    AnomalyDetectionResult fit(const std::vector<float>& series, size_t period);
+} // namespace detail
+
+/// A set of anomaly detection parameters.
+struct AnomalyDetectionParams {
+    /// Sets the level of statistical significance.
+    float alpha = 0.05f;
+    /// Sets the maximum number of anomalies as percent of data.
+    float max_anoms = 0.1f;
+    /// Sets the direction.
+    Direction direction = Direction::Both;
+    /// Sets whether to show progress.
+    bool verbose = false;
+    /// Sets a callback for each iteration.
+    std::function<void()> callback = nullptr;
 };
 
-AnomalyDetectionParams params() {
-    return AnomalyDetectionParams();
-}
+/// An anomaly detection result.
+class AnomalyDetection {
+  public:
+    /// Detects anomalies in a time series from a span.
+    template<typename T>
+    AnomalyDetection(
+        std::span<const T> series,
+        size_t period,
+        const AnomalyDetectionParams& params = AnomalyDetectionParams()
+    ) {
+        bool one_tail = params.direction != Direction::Both;
+        bool upper_tail = params.direction == Direction::Positive;
+
+        std::vector<size_t> anomalies = detail::detect_anoms(
+            series,
+            period,
+            params.max_anoms,
+            params.alpha,
+            one_tail,
+            upper_tail,
+            params.verbose,
+            params.callback
+        );
+        anomalies_ = std::move(anomalies);
+    }
 
-AnomalyDetectionResult AnomalyDetectionParams::fit(const std::vector<float>& series, size_t period) {
-    bool one_tail = this->direction_ != Direction::Both;
-    bool upper_tail = this->direction_ == Direction::Positive;
+    /// Detects anomalies in a time series from a vector.
+    template<typename T>
+    AnomalyDetection(
+        const std::vector<T>& series,
+        size_t period,
+        const AnomalyDetectionParams& params = AnomalyDetectionParams()
+    ) :
+        AnomalyDetection(std::span<const T>{series}, period, params) {}
+
+    /// Returns the anomalies.
+    const std::vector<size_t>& anomalies() const {
+        return anomalies_;
+    }
 
-    auto res = AnomalyDetectionResult();
-    res.anomalies = detect_anoms(series, period, this->max_anoms_, this->alpha_, one_tail, upper_tail, this->verbose_, this->callback_);
-    return res;
-}
+  private:
+    std::vector<size_t> anomalies_;
+};
 
-}
+} // namespace anomaly_detection

data/ext/anomaly_detection/dist.h

@@ -1,5 +1,5 @@
-/*!
- * dist.h v0.3.0
+/*
+ * Dist C v0.3.1
  * https://github.com/ankane/dist.h
  * Unlicense OR MIT License
  */
@@ -8,6 +8,8 @@
 
 #include <math.h>
 
+/// @cond
+
 #ifdef M_E
 #define DIST_E M_E
 #else
@@ -26,7 +28,14 @@
 #define DIST_SQRT2 1.41421356237309504880
 #endif
 
-double normal_pdf(double x, double mean, double std_dev) {
+/// @endcond
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// Returns the probability density function (PDF) of the normal distribution.
+static inline double normal_pdf(double x, double mean, double std_dev) {
     if (std_dev <= 0) {
         return NAN;
     }
@@ -35,7 +44,8 @@ double normal_pdf(double x, double mean, double std_dev) {
     return (1.0 / (std_dev * sqrt(2.0 * DIST_PI))) * pow(DIST_E, -0.5 * n * n);
 }
 
-double normal_cdf(double x, double mean, double std_dev) {
+/// Returns the cumulative distribution function (CDF) of the normal distribution.
+static inline double normal_cdf(double x, double mean, double std_dev) {
     if (std_dev <= 0) {
         return NAN;
     }
@@ -43,10 +53,11 @@ double normal_cdf(double x, double mean, double std_dev) {
     return 0.5 * (1.0 + erf((x - mean) / (std_dev * DIST_SQRT2)));
 }
 
+/// Returns the percent-point/quantile function (PPF) of the normal distribution.
 // Wichura, M. J. (1988).
 // Algorithm AS 241: The Percentage Points of the Normal Distribution.
 // Journal of the Royal Statistical Society. Series C (Applied Statistics), 37(3), 477-484.
-double normal_ppf(double p, double mean, double std_dev) {
+static inline double normal_ppf(double p, double mean, double std_dev) {
     if (p < 0 || p > 1 || std_dev <= 0 || isnan(mean) || isnan(std_dev)) {
         return NAN;
     }
@@ -83,7 +94,8 @@ double normal_ppf(double p, double mean, double std_dev) {
     }
 }
 
-double students_t_pdf(double x, double n) {
+/// Returns the probability density function (PDF) of the Student's t distribution.
+static inline double students_t_pdf(double x, double n) {
     if (n <= 0) {
         return NAN;
     }
@@ -95,10 +107,11 @@ double students_t_pdf(double x, double n) {
     return tgamma((n + 1.0) / 2.0) / (sqrt(n * DIST_PI) * tgamma(n / 2.0)) * pow(1.0 + x * x / n, -(n + 1.0) / 2.0);
 }
 
+/// Returns the cumulative distribution function (CDF) of the Student's t distribution.
 // Hill, G. W. (1970).
 // Algorithm 395: Student's t-distribution.
 // Communications of the ACM, 13(10), 617-619.
-double students_t_cdf(double x, double n) {
+static inline double students_t_cdf(double x, double n) {
     if (n < 1) {
         return NAN;
     }
@@ -159,7 +172,7 @@ double students_t_cdf(double x, double n) {
         return start + sign * (z - a) / 2;
     }
 
-    // tail series expanation for large t-values
+    // tail series expansion for large t-values
     double a = sqrt(b);
     y = a * n;
     int j = 0;
@@ -182,10 +195,11 @@ double students_t_cdf(double x, double n) {
     return start + sign * (z - a) / 2;
 }
 
+/// Returns the percent-point/quantile function (PPF) of the Student's t distribution.
 // Hill, G. W. (1970).
 // Algorithm 396: Student's t-quantiles.
 // Communications of the ACM, 13(10), 619-620.
-double students_t_ppf(double p, double n) {
+static inline double students_t_ppf(double p, double n) {
     if (p < 0 || p > 1 || n < 1) {
         return NAN;
     }
@@ -234,3 +248,11 @@ double students_t_ppf(double p, double n) {
     }
     return sign * sqrt(n * y);
 }
+
+#ifdef __cplusplus
+}
+#endif
+
+#undef DIST_E
+#undef DIST_PI
+#undef DIST_SQRT2

data/ext/anomaly_detection/ext.cpp

@@ -1,18 +1,27 @@
+#include <cstddef>
+#include <stdexcept>
+#include <string>
+#include <vector>
+
 #include <rice/rice.hpp>
-#include <rice/stl.hpp>
 
 #include "anomaly_detection.hpp"
 
+using anomaly_detection::AnomalyDetection;
+using anomaly_detection::AnomalyDetectionParams;
 using anomaly_detection::Direction;
 
 extern "C"
 void Init_ext() {
-  auto rb_mAnomalyDetection = Rice::define_module("AnomalyDetection");
+  Rice::Module rb_mAnomalyDetection = Rice::define_module("AnomalyDetection");
 
   rb_mAnomalyDetection
     .define_singleton_function(
       "_detect",
-      [](std::vector<float> series, int period, float k, float alpha, const std::string& direction, bool verbose) {
+      [](Rice::Array rb_series, size_t period, float k, float alpha, Rice::String rb_direction, bool verbose) {
+        std::vector<float> series = rb_series.to_vector<float>();
+        std::string direction = rb_direction.str();
+
         Direction dir;
         if (direction == "pos") {
           dir = Direction::Positive;
@@ -24,17 +33,18 @@ void Init_ext() {
           throw std::invalid_argument("direction must be pos, neg, or both");
         }
 
-        auto res = anomaly_detection::params()
-          .max_anoms(k)
-          .alpha(alpha)
-          .direction(dir)
-          .verbose(verbose)
-          .callback(rb_thread_check_ints)
-          .fit(series, period);
-
-        auto a = Rice::Array();
-        for (auto v : res.anomalies) {
-          a.push(v);
+        AnomalyDetectionParams params{
+          .alpha = alpha,
+          .max_anoms = k,
+          .direction = dir,
+          .verbose = verbose,
+          .callback = rb_thread_check_ints
+        };
+        AnomalyDetection res{series, period, params};
+
+        Rice::Array a;
+        for (const auto v : res.anomalies()) {
+          a.push(v, false);
         }
         return a;
       });

data/ext/anomaly_detection/extconf.rb

@@ -1,5 +1,5 @@
 require "mkmf-rice"
 
-$CXXFLAGS += " -std=c++17 $(optflags)"
+$CXXFLAGS += " -std=c++20 $(optflags)"
 
 create_makefile("anomaly_detection/ext")