stl-rb 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9618c6ec1b85dd66819a5d2ad583a7eea4f3477d00ec2294bfb11ead531c8a2
-  data.tar.gz: 85bfe604d2baa36e592f5c10639301258152a0805bf6790e2926af6fbac0bbe5
+  metadata.gz: f27ba59a612d7502f6251944cf1f7f622ed9466b94351f888fd18ec04bb77faa
+  data.tar.gz: c7c6127cdbb8832a3d5fe89a1577c0ae20e1f8eda505b046b5f7c1520e2ae830
 SHA512:
-  metadata.gz: 32e4f5fee0ec21fa9676a25fea82609b7c1814c27ae26d6e45117d3e7c815827fc4ab6628feb4736b5c93bc93925483a1a6a510a3930a49e8e27e83f4690919b
-  data.tar.gz: 86e8cd5354cca7c121c9e26a8b9a7dde4b3585095843fdc80b1eedcce25a0c8fb0aa8b8b0a6fa2e15a0a6a10f682e8ef71e5e4da186e3e7b17fe8de6b1506332
+  metadata.gz: e793bab429ba275161ef9d1d5566517a602d7a320a01edbe0e065e8ac21d90f6d7f70ea8e2708c583cff2e4cd848ff0955341f011cba102d2540730ecd09de10
+  data.tar.gz: 67b59c7a814295f852b3f2e26537826ef4879d33439f8603ce0d20877f6ae1254fc4f0f7b6e85fc595ff3ef1be63eb08aa5e72121572743d31ee0a93b4aa54ae

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 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/README.md

@@ -18,9 +18,9 @@ Decompose a time series
 
 ```ruby
 series = {
-  Date.parse("2023-01-01") => 100,
-  Date.parse("2023-01-02") => 150,
-  Date.parse("2023-01-03") => 136,
+  Date.parse("2025-01-01") => 100,
+  Date.parse("2025-01-02") => 150,
+  Date.parse("2025-01-03") => 136,
   # ...
 }
 

data/ext/stl/ext.cpp

@@ -1,3 +1,5 @@
+#include <vector>
+
 #include <rice/rice.hpp>
 #include <rice/stl.hpp>
 
@@ -6,7 +8,7 @@
 Rice::Array to_a(std::vector<float>& x) {
   auto a = Rice::Array();
   for (auto v : x) {
-    a.push(v);
+    a.push(v, false);
   }
   return a;
 }

data/ext/stl/stl.hpp

@@ -1,5 +1,5 @@
 /*!
- * STL C++ v0.1.4
+ * STL C++ v0.2.0
  * https://github.com/ankane/stl-cpp
  * Unlicense OR MIT License
  *
@@ -8,6 +8,10 @@
  * Cleveland, R. B., Cleveland, W. S., McRae, J. E., & Terpenning, I. (1990).
  * STL: A Seasonal-Trend Decomposition Procedure Based on Loess.
  * Journal of Official Statistics, 6(1), 3-33.
+ *
+ * Bandara, K., Hyndman, R. J., & Bergmeir, C. (2021).
+ * MSTL: A Seasonal-Trend Decomposition Algorithm for Time Series with Multiple Seasonal Patterns.
+ * arXiv:2107.13462 [stat.AP]. https://doi.org/10.48550/arXiv.2107.13462
  */
 
 #pragma once
@@ -17,16 +21,24 @@
 #include <numeric>
 #include <optional>
 #include <stdexcept>
+#include <tuple>
 #include <vector>
 
+#if __cplusplus >= 202002L
+#include <span>
+#endif
+
 namespace stl {
 
-bool est(const float* y, size_t n, size_t len, int ideg, float xs, float* ys, size_t nleft, size_t nright, float* w, bool userw, const float* rw) {
-    auto range = ((float) n) - 1.0;
-    auto h = std::max(xs - ((float) nleft), ((float) nright) - xs);
+namespace {
+
+template<typename T>
+bool est(const T* y, size_t n, size_t len, int ideg, T xs, T* ys, size_t nleft, size_t nright, T* w, bool userw, const T* rw) {
+    auto range = ((T) n) - 1.0;
+    auto h = std::max(xs - ((T) nleft), ((T) nright) - xs);
 
     if (len > n) {
-        h += (float) ((len - n) / 2);
+        h += (T) ((len - n) / 2);
     }
 
     auto h9 = 0.999 * h;
@@ -36,12 +48,12 @@ bool est(const float* y, size_t n, size_t len, int ideg, float xs, float* ys, si
     auto a = 0.0;
     for (auto j = nleft; j <= nright; j++) {
         w[j - 1] = 0.0;
-        auto r = fabs(((float) j) - xs);
+        auto r = std::abs(((T) j) - xs);
         if (r <= h9) {
             if (r <= h1) {
                 w[j - 1] = 1.0;
             } else {
-                w[j - 1] = pow(1.0 - pow(r / h, 3), 3);
+                w[j - 1] = (T) std::pow(1.0 - std::pow(r / h, 3), 3);
             }
             if (userw) {
                 w[j - 1] *= rw[j - 1];
@@ -54,25 +66,25 @@ bool est(const float* y, size_t n, size_t len, int ideg, float xs, float* ys, si
         return false;
     } else { // weighted least squares
         for (auto j = nleft; j <= nright; j++) { // make sum of w(j) == 1
-            w[j - 1] /= a;
+            w[j - 1] /= (T) a;
         }
 
         if (h > 0.0 && ideg > 0) { // use linear fit
             auto a = 0.0;
             for (auto j = nleft; j <= nright; j++) { // weighted center of x values
-                a += w[j - 1] * ((float) j);
+                a += w[j - 1] * ((T) j);
             }
             auto b = xs - a;
             auto c = 0.0;
             for (auto j = nleft; j <= nright; j++) {
-                c += w[j - 1] * pow(((float) j) - a, 2);
+                c += w[j - 1] * std::pow(((T) j) - a, 2);
             }
-            if (sqrt(c) > 0.001 * range) {
+            if (std::sqrt(c) > 0.001 * range) {
                 b /= c;
 
                 // points are spread out enough to compute slope
                 for (auto j = nleft; j <= nright; j++) {
-                    w[j - 1] *= b * (((float) j) - a) + 1.0;
+                    w[j - 1] *= (T) (b * (((T) j) - a) + 1.0);
                 }
             }
         }
@@ -86,7 +98,8 @@ bool est(const float* y, size_t n, size_t len, int ideg, float xs, float* ys, si
     }
 }
 
-void ess(const float* y, size_t n, size_t len, int ideg, size_t njump, bool userw, const float* rw, float* ys, float* res) {
+template<typename T>
+void ess(const T* y, size_t n, size_t len, int ideg, size_t njump, bool userw, const T* rw, T* ys, T* res) {
     if (n < 2) {
         ys[0] = y[0];
         return;
@@ -100,7 +113,7 @@ void ess(const float* y, size_t n, size_t len, int ideg, size_t njump, bool user
         nleft = 1;
         nright = n;
         for (size_t i = 1; i <= n; i += newnj) {
-            auto ok = est(y, n, len, ideg, (float) i, &ys[i - 1], nleft, nright, res, userw, rw);
+            auto ok = est(y, n, len, ideg, (T) i, &ys[i - 1], nleft, nright, res, userw, rw);
             if (!ok) {
                 ys[i - 1] = y[i - 1];
             }
@@ -114,7 +127,7 @@ void ess(const float* y, size_t n, size_t len, int ideg, size_t njump, bool user
                 nleft += 1;
                 nright += 1;
             }
-            auto ok = est(y, n, len, ideg, (float) i, &ys[i - 1], nleft, nright, res, userw, rw);
+            auto ok = est(y, n, len, ideg, (T) i, &ys[i - 1], nleft, nright, res, userw, rw);
             if (!ok) {
                 ys[i - 1] = y[i - 1];
             }
@@ -132,7 +145,7 @@ void ess(const float* y, size_t n, size_t len, int ideg, size_t njump, bool user
                 nleft = i - nsh + 1;
                 nright = len + i - nsh;
             }
-            auto ok = est(y, n, len, ideg, (float) i, &ys[i - 1], nleft, nright, res, userw, rw);
+            auto ok = est(y, n, len, ideg, (T) i, &ys[i - 1], nleft, nright, res, userw, rw);
             if (!ok) {
                 ys[i - 1] = y[i - 1];
             }
@@ -141,60 +154,63 @@ void ess(const float* y, size_t n, size_t len, int ideg, size_t njump, bool user
 
     if (newnj != 1) {
         for (size_t i = 1; i <= n - newnj; i += newnj) {
-            auto delta = (ys[i + newnj - 1] - ys[i - 1]) / ((float) newnj);
+            auto delta = (ys[i + newnj - 1] - ys[i - 1]) / ((T) newnj);
             for (auto j = i + 1; j <= i + newnj - 1; j++) {
-                ys[j - 1] = ys[i - 1] + delta * ((float) (j - i));
+                ys[j - 1] = ys[i - 1] + delta * ((T) (j - i));
             }
         }
         auto k = ((n - 1) / newnj) * newnj + 1;
         if (k != n) {
-            auto ok = est(y, n, len, ideg, (float) n, &ys[n - 1], nleft, nright, res, userw, rw);
+            auto ok = est(y, n, len, ideg, (T) n, &ys[n - 1], nleft, nright, res, userw, rw);
             if (!ok) {
                 ys[n - 1] = y[n - 1];
             }
             if (k != n - 1) {
-                auto delta = (ys[n - 1] - ys[k - 1]) / ((float) (n - k));
+                auto delta = (ys[n - 1] - ys[k - 1]) / ((T) (n - k));
                 for (auto j = k + 1; j <= n - 1; j++) {
-                    ys[j - 1] = ys[k - 1] + delta * ((float) (j - k));
+                    ys[j - 1] = ys[k - 1] + delta * ((T) (j - k));
                 }
             }
         }
     }
 }
 
-void ma(const float* x, size_t n, size_t len, float* ave) {
+template<typename T>
+void ma(const T* x, size_t n, size_t len, T* ave) {
     auto newn = n - len + 1;
-    auto flen = (float) len;
-    auto v = 0.0;
+    double flen = (T) len;
+    double v = 0.0;
 
     // get the first average
     for (size_t i = 0; i < len; i++) {
         v += x[i];
     }
 
-    ave[0] = v / flen;
+    ave[0] = (T) (v / flen);
     if (newn > 1) {
-        auto k = len;
-        auto m = 0;
+        size_t k = len;
+        size_t m = 0;
         for (size_t j = 1; j < newn; j++) {
             // window down the array
             v = v - x[m] + x[k];
-            ave[j] = v / flen;
+            ave[j] = (T) (v / flen);
             k += 1;
             m += 1;
         }
     }
 }
 
-void fts(const float* x, size_t n, size_t np, float* trend, float* work) {
+template<typename T>
+void fts(const T* x, size_t n, size_t np, T* trend, T* work) {
     ma(x, n, np, trend);
     ma(trend, n - np + 1, np, work);
     ma(work, n - 2 * np + 2, 3, trend);
 }
 
-void rwts(const float* y, size_t n, const float* fit, float* rw) {
+template<typename T>
+void rwts(const T* y, size_t n, const T* fit, T* rw) {
     for (size_t i = 0; i < n; i++) {
-        rw[i] = fabs(y[i] - fit[i]);
+        rw[i] = std::abs(y[i] - fit[i]);
     }
 
     auto mid1 = (n - 1) / 2;
@@ -208,18 +224,19 @@ void rwts(const float* y, size_t n, const float* fit, float* rw) {
     auto c1 = 0.001 * cmad;
 
     for (size_t i = 0; i < n; i++) {
-        auto r = fabs(y[i] - fit[i]);
+        auto r = std::abs(y[i] - fit[i]);
         if (r <= c1) {
             rw[i] = 1.0;
         } else if (r <= c9) {
-            rw[i] = pow(1.0 - pow(r / cmad, 2), 2);
+            rw[i] = (T) std::pow(1.0 - std::pow(r / cmad, 2), 2);
         } else {
             rw[i] = 0.0;
         }
     }
 }
 
-void ss(const float* y, size_t n, size_t np, size_t ns, int isdeg, size_t nsjump, bool userw, float* rw, float* season, float* work1, float* work2, float* work3, float* work4) {
+template<typename T>
+void ss(const T* y, size_t n, size_t np, size_t ns, int isdeg, size_t nsjump, bool userw, T* rw, T* season, T* work1, T* work2, T* work3, T* work4) {
     for (size_t j = 1; j <= np; j++) {
         size_t k = (n - j) / np + 1;
 
@@ -232,14 +249,14 @@ void ss(const float* y, size_t n, size_t np, size_t ns, int isdeg, size_t nsjump
             }
         }
         ess(work1, k, ns, isdeg, nsjump, userw, work3, work2 + 1, work4);
-        auto xs = 0.0;
+        T xs = 0.0;
         auto nright = std::min(ns, k);
         auto ok = est(work1, k, ns, isdeg, xs, &work2[0], 1, nright, work4, userw, work3);
         if (!ok) {
             work2[0] = work2[1];
         }
         xs = k + 1;
-        size_t nleft = std::max(1, (int) k - (int) ns + 1);
+        size_t nleft = (size_t) std::max(1, (int) k - (int) ns + 1);
         ok = est(work1, k, ns, isdeg, xs, &work2[k + 1], nleft, k, work4, userw, work3);
         if (!ok) {
             work2[k + 1] = work2[k];
@@ -250,7 +267,8 @@ void ss(const float* y, size_t n, size_t np, size_t ns, int isdeg, size_t nsjump
     }
 }
 
-void onestp(const float* y, size_t n, size_t np, size_t ns, size_t nt, size_t nl, int isdeg, int itdeg, int ildeg, size_t nsjump, size_t ntjump, size_t nljump, size_t ni, bool userw, float* rw, float* season, float* trend, float* work1, float* work2, float* work3, float* work4, float* work5) {
+template<typename T>
+void onestp(const T* y, size_t n, size_t np, size_t ns, size_t nt, size_t nl, int isdeg, int itdeg, int ildeg, size_t nsjump, size_t ntjump, size_t nljump, size_t ni, bool userw, T* rw, T* season, T* trend, T* work1, T* work2, T* work3, T* work4, T* work5) {
     for (size_t j = 0; j < ni; j++) {
         for (size_t i = 0; i < n; i++) {
             work1[i] = y[i] - trend[i];
@@ -269,7 +287,8 @@ void onestp(const float* y, size_t n, size_t np, size_t ns, size_t nt, size_t nl
     }
 }
 
-void stl(const float* y, size_t n, size_t np, size_t ns, size_t nt, size_t nl, int isdeg, int itdeg, int ildeg, size_t nsjump, size_t ntjump, size_t nljump, size_t ni, size_t no, float* rw, float* season, float* trend) {
+template<typename T>
+void stl(const T* y, size_t n, size_t np, size_t ns, size_t nt, size_t nl, int isdeg, int itdeg, int ildeg, size_t nsjump, size_t ntjump, size_t nljump, size_t ni, size_t no, T* rw, T* season, T* trend) {
     if (ns < 3) {
         throw std::invalid_argument("seasonal_length must be at least 3");
     }
@@ -303,11 +322,11 @@ void stl(const float* y, size_t n, size_t np, size_t ns, size_t nt, size_t nl, i
         throw std::invalid_argument("low_pass_length must be odd");
     }
 
-    auto work1 = std::vector<float>(n + 2 * np);
-    auto work2 = std::vector<float>(n + 2 * np);
-    auto work3 = std::vector<float>(n + 2 * np);
-    auto work4 = std::vector<float>(n + 2 * np);
-    auto work5 = std::vector<float>(n + 2 * np);
+    auto work1 = std::vector<T>(n + 2 * np);
+    auto work2 = std::vector<T>(n + 2 * np);
+    auto work3 = std::vector<T>(n + 2 * np);
+    auto work4 = std::vector<T>(n + 2 * np);
+    auto work5 = std::vector<T>(n + 2 * np);
 
     auto userw = false;
     size_t k = 0;
@@ -332,18 +351,20 @@ void stl(const float* y, size_t n, size_t np, size_t ns, size_t nt, size_t nl, i
     }
 }
 
-float var(const std::vector<float>& series) {
+template<typename T>
+double var(const std::vector<T>& series) {
     auto mean = std::accumulate(series.begin(), series.end(), 0.0) / series.size();
-    std::vector<float> tmp;
-    tmp.reserve(series.size());
+    double sum = 0.0;
     for (auto v : series) {
-        tmp.push_back(pow(v - mean, 2));
+        double diff = v - mean;
+        sum += diff * diff;
     }
-    return std::accumulate(tmp.begin(), tmp.end(), 0.0) / (series.size() - 1);
+    return sum / (series.size() - 1);
 }
 
-float strength(const std::vector<float>& component, const std::vector<float>& remainder) {
-    std::vector<float> sr;
+template<typename T>
+double strength(const std::vector<T>& component, const std::vector<T>& remainder) {
+    std::vector<T> sr;
     sr.reserve(remainder.size());
     for (size_t i = 0; i < remainder.size(); i++) {
         sr.push_back(component[i] + remainder[i]);
@@ -351,24 +372,41 @@ float strength(const std::vector<float>& component, const std::vector<float>& re
     return std::max(0.0, 1.0 - var(remainder) / var(sr));
 }
 
+}
+
+/// A STL result.
+template<typename T = float>
 class StlResult {
 public:
-    std::vector<float> seasonal;
-    std::vector<float> trend;
-    std::vector<float> remainder;
-    std::vector<float> weights;
+    /// Returns the seasonal component.
+    std::vector<T> seasonal;
+
+    /// Returns the trend component.
+    std::vector<T> trend;
 
-    inline float seasonal_strength() {
+    /// Returns the remainder.
+    std::vector<T> remainder;
+
+    /// Returns the weights.
+    std::vector<T> weights;
+
+    /// Returns the seasonal strength.
+    inline double seasonal_strength() const {
         return strength(seasonal, remainder);
     }
 
-    inline float trend_strength() {
+    /// Returns the trend strength.
+    inline double trend_strength() const {
         return strength(trend, remainder);
     }
 };
 
+/// A set of STL parameters.
 class StlParams {
+public:
+    /// @private
     std::optional<size_t> ns_ = std::nullopt;
+private:
     std::optional<size_t> nt_ = std::nullopt;
     std::optional<size_t> nl_ = std::nullopt;
     int isdeg_ = 0;
@@ -382,75 +420,104 @@ class StlParams {
     bool robust_ = false;
 
 public:
-    inline StlParams seasonal_length(size_t ns) {
-        this->ns_ = ns;
+    /// Sets the length of the seasonal smoother.
+    inline StlParams seasonal_length(size_t length) {
+        this->ns_ = length;
         return *this;
     }
 
-    inline StlParams trend_length(size_t nt) {
-        this->nt_ = nt;
+    /// Sets the length of the trend smoother.
+    inline StlParams trend_length(size_t length) {
+        this->nt_ = length;
         return *this;
     }
 
-    inline StlParams low_pass_length(size_t nl) {
-        this->nl_ = nl;
+    /// Sets the length of the low-pass filter.
+    inline StlParams low_pass_length(size_t length) {
+        this->nl_ = length;
         return *this;
     }
 
-    inline StlParams seasonal_degree(int isdeg) {
-        this->isdeg_ = isdeg;
+    /// Sets the degree of locally-fitted polynomial in seasonal smoothing.
+    inline StlParams seasonal_degree(int degree) {
+        this->isdeg_ = degree;
         return *this;
     }
 
-    inline StlParams trend_degree(int itdeg) {
-        this->itdeg_ = itdeg;
+    /// Sets the degree of locally-fitted polynomial in trend smoothing.
+    inline StlParams trend_degree(int degree) {
+        this->itdeg_ = degree;
         return *this;
     }
 
-    inline StlParams low_pass_degree(int ildeg) {
-        this->ildeg_ = ildeg;
+    /// Sets the degree of locally-fitted polynomial in low-pass smoothing.
+    inline StlParams low_pass_degree(int degree) {
+        this->ildeg_ = degree;
         return *this;
     }
 
-    inline StlParams seasonal_jump(size_t nsjump) {
-        this->nsjump_ = nsjump;
+    /// Sets the skipping value for seasonal smoothing.
+    inline StlParams seasonal_jump(size_t jump) {
+        this->nsjump_ = jump;
         return *this;
     }
 
-    inline StlParams trend_jump(size_t ntjump) {
-        this->ntjump_ = ntjump;
+    /// Sets the skipping value for trend smoothing.
+    inline StlParams trend_jump(size_t jump) {
+        this->ntjump_ = jump;
         return *this;
     }
 
-    inline StlParams low_pass_jump(size_t nljump) {
-        this->nljump_ = nljump;
+    /// Sets the skipping value for low-pass smoothing.
+    inline StlParams low_pass_jump(size_t jump) {
+        this->nljump_ = jump;
         return *this;
     }
 
-    inline StlParams inner_loops(size_t ni) {
-        this->ni_ = ni;
+    /// Sets the number of loops for updating the seasonal and trend components.
+    inline StlParams inner_loops(size_t loops) {
+        this->ni_ = loops;
         return *this;
     }
 
-    inline StlParams outer_loops(size_t no) {
-        this->no_ = no;
+    /// Sets the number of iterations of robust fitting.
+    inline StlParams outer_loops(size_t loops) {
+        this->no_ = loops;
         return *this;
     }
 
+    /// Sets whether robustness iterations are to be used.
     inline StlParams robust(bool robust) {
         this->robust_ = robust;
         return *this;
     }
 
-    StlResult fit(const float* y, size_t n, size_t np);
-    StlResult fit(const std::vector<float>& y, size_t np);
+    /// Decomposes a time series from an array.
+    template<typename T>
+    StlResult<T> fit(const T* series, size_t series_size, size_t period) const;
+
+    /// Decomposes a time series from a vector.
+    template<typename T>
+    StlResult<T> fit(const std::vector<T>& series, size_t period) const;
+
+#if __cplusplus >= 202002L
+    /// Decomposes a time series from a span.
+    template<typename T>
+    StlResult<T> fit(std::span<const T> series, size_t period) const;
+#endif
 };
 
-StlParams params() {
+/// Creates a new set of STL parameters.
+inline StlParams params() {
     return StlParams();
 }
 
-StlResult StlParams::fit(const float* y, size_t n, size_t np) {
+template<typename T>
+StlResult<T> StlParams::fit(const T* series, size_t series_size, size_t period) const {
+    auto y = series;
+    auto np = period;
+    auto n = series_size;
+
     if (n < 2 * np) {
         throw std::invalid_argument("series has less than two periods");
     }
@@ -460,11 +527,11 @@ StlResult StlParams::fit(const float* y, size_t n, size_t np) {
     auto isdeg = this->isdeg_;
     auto itdeg = this->itdeg_;
 
-    auto res = StlResult {
-        std::vector<float>(n),
-        std::vector<float>(n),
-        std::vector<float>(),
-        std::vector<float>(n)
+    auto res = StlResult<T> {
+        std::vector<T>(n),
+        std::vector<T>(n),
+        std::vector<T>(),
+        std::vector<T>(n)
     };
 
     auto ildeg = this->ildeg_.value_or(itdeg);
@@ -503,8 +570,257 @@ StlResult StlParams::fit(const float* y, size_t n, size_t np) {
     return res;
 }
 
-StlResult StlParams::fit(const std::vector<float>& y, size_t np) {
-    return StlParams::fit(y.data(), y.size(), np);
+template<typename T>
+StlResult<T> StlParams::fit(const std::vector<T>& series, size_t period) const {
+    return StlParams::fit(series.data(), series.size(), period);
+}
+
+#if __cplusplus >= 202002L
+template<typename T>
+StlResult<T> StlParams::fit(std::span<const T> series, size_t period) const {
+    return StlParams::fit(series.data(), series.size(), period);
+}
+#endif
+
+/// A MSTL result.
+template<typename T = float>
+class MstlResult {
+public:
+    /// Returns the seasonal component.
+    std::vector<std::vector<T>> seasonal;
+
+    /// Returns the trend component.
+    std::vector<T> trend;
+
+    /// Returns the remainder.
+    std::vector<T> remainder;
+
+    /// Returns the seasonal strength.
+    inline std::vector<double> seasonal_strength() const {
+        std::vector<double> res;
+        for (auto& s : seasonal) {
+            res.push_back(strength(s, remainder));
+        }
+        return res;
+    }
+
+    /// Returns the trend strength.
+    inline double trend_strength() const {
+        return strength(trend, remainder);
+    }
+};
+
+/// A set of MSTL parameters.
+class MstlParams {
+    size_t iterate_ = 2;
+    std::optional<float> lambda_ = std::nullopt;
+    std::optional<std::vector<size_t>> swin_ = std::nullopt;
+    StlParams stl_params_;
+
+public:
+    /// Sets the number of iterations.
+    inline MstlParams iterations(size_t iterations) {
+        this->iterate_ = iterations;
+        return *this;
+    }
+
+    /// Sets lambda for Box-Cox transformation.
+    inline MstlParams lambda(float lambda) {
+        this->lambda_ = lambda;
+        return *this;
+    }
+
+    /// Sets the lengths of the seasonal smoothers.
+    inline MstlParams seasonal_lengths(const std::vector<size_t>& lengths) {
+        this->swin_ = lengths;
+        return *this;
+    }
+
+    /// Sets the STL parameters.
+    inline MstlParams stl_params(const StlParams& stl_params) {
+        this->stl_params_ = stl_params;
+        return *this;
+    }
+
+    /// Decomposes a time series from an array.
+    template<typename T>
+    MstlResult<T> fit(const T* series, size_t series_size, const size_t* periods, size_t periods_size) const;
+
+    /// Decomposes a time series from a vector.
+    template<typename T>
+    MstlResult<T> fit(const std::vector<T>& series, const std::vector<size_t>& periods) const;
+
+#if __cplusplus >= 202002L
+    /// Decomposes a time series from a span.
+    template<typename T>
+    MstlResult<T> fit(std::span<const T> series, std::span<const size_t> periods) const;
+#endif
+};
+
+/// Creates a new set of MSTL parameters.
+inline MstlParams mstl_params() {
+    return MstlParams();
+}
+
+namespace {
+
+template<typename T>
+std::vector<T> box_cox(const T* y, size_t y_size, float lambda) {
+    std::vector<T> res;
+    res.reserve(y_size);
+    if (lambda != 0.0) {
+        for (size_t i = 0; i < y_size; i++) {
+            res.push_back((T) (std::pow(y[i], lambda) - 1.0) / lambda);
+        }
+    } else {
+        for (size_t i = 0; i < y_size; i++) {
+            res.push_back(std::log(y[i]));
+        }
+    }
+    return res;
+}
+
+template<typename T>
+std::tuple<std::vector<T>, std::vector<T>, std::vector<std::vector<T>>> mstl(
+    const T* x,
+    size_t k,
+    const size_t* seas_ids,
+    size_t seas_size,
+    size_t iterate,
+    std::optional<float> lambda,
+    const std::optional<std::vector<size_t>>& swin,
+    const StlParams& stl_params
+) {
+    // keep track of indices instead of sorting seas_ids
+    // so order is preserved with seasonality
+    std::vector<size_t> indices;
+    for (size_t i = 0; i < seas_size; i++) {
+        indices.push_back(i);
+    }
+    std::sort(indices.begin(), indices.end(), [&seas_ids](size_t a, size_t b) {
+        return seas_ids[a] < seas_ids[b];
+    });
+
+    if (seas_size == 1) {
+        iterate = 1;
+    }
+
+    std::vector<std::vector<T>> seasonality;
+    seasonality.reserve(seas_size);
+    std::vector<T> trend;
+
+    auto deseas = lambda.has_value() ? box_cox(x, k, lambda.value()) : std::vector<T>(x, x + k);
+
+    if (seas_size != 0) {
+        for (size_t i = 0; i < seas_size; i++) {
+            seasonality.push_back(std::vector<T>());
+        }
+
+        for (size_t j = 0; j < iterate; j++) {
+            for (size_t i = 0; i < indices.size(); i++) {
+                auto idx = indices[i];
+
+                if (j > 0) {
+                    for (size_t ii = 0; ii < deseas.size(); ii++) {
+                        deseas[ii] += seasonality[idx][ii];
+                    }
+                }
+
+                StlResult<T> fit;
+                if (swin) {
+                    StlParams clone = stl_params;
+                    fit = clone.seasonal_length((*swin)[idx]).fit(deseas, seas_ids[idx]);
+                } else if (stl_params.ns_.has_value()) {
+                    fit = stl_params.fit(deseas, seas_ids[idx]);
+                } else {
+                    StlParams clone = stl_params;
+                    fit = clone.seasonal_length(7 + 4 * (i + 1)).fit(deseas, seas_ids[idx]);
+                }
+
+                seasonality[idx] = fit.seasonal;
+                trend = fit.trend;
+
+                for (size_t ii = 0; ii < deseas.size(); ii++) {
+                    deseas[ii] -= seasonality[idx][ii];
+                }
+            }
+        }
+    } else {
+        // TODO use Friedman's Super Smoother for trend
+        throw std::invalid_argument("periods must not be empty");
+    }
+
+    std::vector<T> remainder;
+    remainder.reserve(k);
+    for (size_t i = 0; i < k; i++) {
+        remainder.push_back(deseas[i] - trend[i]);
+    }
+
+    return std::make_tuple(trend, remainder, seasonality);
+}
+
+}
+
+template<typename T>
+MstlResult<T> MstlParams::fit(const T* series, size_t series_size, const size_t* periods, size_t periods_size) const {
+    // return error to be consistent with stl
+    // and ensure seasonal is always same length as periods
+    for (size_t i = 0; i < periods_size; i++) {
+        if (periods[i] < 2) {
+            throw std::invalid_argument("periods must be at least 2");
+        }
+    }
+
+    // return error to be consistent with stl
+    // and ensure seasonal is always same length as periods
+    for (size_t i = 0; i < periods_size; i++) {
+        if (series_size < periods[i] * 2) {
+            throw std::invalid_argument("series has less than two periods");
+        }
+    }
+
+    if (lambda_.has_value()) {
+        auto lambda = lambda_.value();
+        if (lambda < 0 || lambda > 1) {
+            throw std::invalid_argument("lambda must be between 0 and 1");
+        }
+    }
+
+    if (swin_.has_value()) {
+        auto swin = swin_.value();
+        if (swin.size() != periods_size) {
+            throw std::invalid_argument("seasonal_lengths must have the same length as periods");
+        }
+    }
+
+    auto [trend, remainder, seasonal] = mstl(
+        series,
+        series_size,
+        periods,
+        periods_size,
+        iterate_,
+        lambda_,
+        swin_,
+        stl_params_
+    );
+
+    return MstlResult<T> {
+        seasonal,
+        trend,
+        remainder
+    };
+}
+
+template<typename T>
+MstlResult<T> MstlParams::fit(const std::vector<T>& series, const std::vector<size_t>& periods) const {
+    return MstlParams::fit(series.data(), series.size(), periods.data(), periods.size());
+}
+
+#if __cplusplus >= 202002L
+template<typename T>
+MstlResult<T> MstlParams::fit(std::span<const T> series, std::span<const size_t> periods) const {
+    return MstlParams::fit(series.data(), series.size(), periods.data(), periods.size());
 }
+#endif
 
 }

data/lib/stl/version.rb

@@ -1,3 +1,3 @@
 module Stl
-  VERSION = "0.3.0"
+  VERSION = "0.3.1"
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: stl-rb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Andrew Kane
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rice
@@ -16,15 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.3.3
+        version: '4.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.3.3
-description:
+        version: '4.7'
 email: andrew@ankane.org
 executables: []
 extensions:
@@ -43,7 +41,6 @@ homepage: https://github.com/ankane/stl-ruby
 licenses:
 - Unlicense OR MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -58,8 +55,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Seasonal-trend decomposition for Ruby
 test_files: []