anomaly_detection 0.3.0 → 0.4.0

data/ext/anomaly_detection/stl.hpp

@@ -1,5 +1,5 @@
-/*!
- * STL C++ v0.1.3
+/*
+ * STL C++ v0.3.0
  * https://github.com/ankane/stl-cpp
  * Unlicense OR MIT License
  *
@@ -8,120 +8,177 @@
  * 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
 
 #include <algorithm>
 #include <cmath>
+#include <cstddef>
 #include <numeric>
 #include <optional>
+#include <span>
 #include <stdexcept>
+#include <tuple>
+#include <utility>
 #include <vector>
 
 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 detail {
+
+// TODO use span.at() for C++26
+template<typename T>
+T& span_at(std::span<T> sp, size_t pos) {
+    if (pos >= sp.size()) [[unlikely]] {
+        throw std::out_of_range("pos >= size()");
+    }
+    return sp[pos];
+}
+
+template<typename T>
+bool est(
+    const std::vector<T>& y,
+    size_t n,
+    size_t len,
+    int ideg,
+    T xs,
+    T& ys,
+    size_t nleft,
+    size_t nright,
+    std::vector<T>& w,
+    bool userw,
+    const std::vector<T>& rw
+) {
+    T range = static_cast<T>(n) - static_cast<T>(1.0);
+    T h = std::max(xs - static_cast<T>(nleft), static_cast<T>(nright) - xs);
 
     if (len > n) {
-        h += (float) ((len - n) / 2);
+        h += static_cast<T>((len - n) / 2);
     }
 
-    auto h9 = 0.999 * h;
-    auto h1 = 0.001 * h;
+    T h9 = static_cast<T>(0.999) * h;
+    T h1 = static_cast<T>(0.001) * h;
 
     // compute weights
-    auto a = 0.0;
-    for (auto j = nleft; j <= nright; j++) {
-        w[j - 1] = 0.0;
-        auto r = fabs(((float) j) - xs);
+    T a = 0.0;
+    for (size_t j = nleft; j <= nright; j++) {
+        w.at(j - 1) = 0.0;
+        T r = std::abs(static_cast<T>(j) - xs);
         if (r <= h9) {
             if (r <= h1) {
-                w[j - 1] = 1.0;
+                w.at(j - 1) = 1.0;
             } else {
-                w[j - 1] = pow(1.0 - pow(r / h, 3), 3);
+                w.at(j - 1) = static_cast<T>(std::pow(1.0 - std::pow(r / h, 3.0), 3.0));
             }
             if (userw) {
-                w[j - 1] *= rw[j - 1];
+                w.at(j - 1) *= rw.at(j - 1);
             }
-            a += w[j - 1];
+            a += w.at(j - 1);
         }
     }
 
     if (a <= 0.0) {
         return false;
-    } else { // weighted least squares
-        for (auto j = nleft; j <= nright; j++) { // make sum of w(j) == 1
-            w[j - 1] /= a;
+    } else {
+        // weighted least squares
+        for (size_t j = nleft; j <= nright; j++) {
+            // make sum of w(j) == 1
+            w.at(j - 1) /= 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);
+        if (h > 0.0 && ideg > 0) {
+            // use linear fit
+            T a = 0.0;
+            for (size_t j = nleft; j <= nright; j++) {
+                // weighted center of x values
+                a += w.at(j - 1) * static_cast<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);
+            T b = xs - a;
+            T c = 0.0;
+            for (size_t j = nleft; j <= nright; j++) {
+                c += w.at(j - 1) * std::pow(static_cast<T>(j) - a, static_cast<T>(2.0));
             }
-            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;
+                for (size_t j = nleft; j <= nright; j++) {
+                    w.at(j - 1) *= b * (static_cast<T>(j) - a) + static_cast<T>(1.0);
                 }
             }
         }
 
-        *ys = 0.0;
-        for (auto j = nleft; j <= nright; j++) {
-            *ys += w[j - 1] * y[j - 1];
+        ys = 0.0;
+        for (size_t j = nleft; j <= nright; j++) {
+            ys += w.at(j - 1) * y.at(j - 1);
         }
 
         return true;
     }
 }
 
-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 std::vector<T>& y,
+    size_t n,
+    size_t len,
+    int ideg,
+    size_t njump,
+    bool userw,
+    const std::vector<T>& rw,
+    std::span<T> ys,
+    std::vector<T>& res
+) {
     if (n < 2) {
-        ys[0] = y[0];
+        span_at(ys, 0) = y.at(0);
         return;
     }
 
     size_t nleft = 0;
     size_t nright = 0;
 
-    auto newnj = std::min(njump, n - 1);
+    size_t newnj = std::min(njump, n - 1);
     if (len >= n) {
         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);
+            bool ok = est(
+                y, n, len, ideg, static_cast<T>(i), span_at(ys, i - 1), nleft, nright, res, userw,
+                rw
+            );
             if (!ok) {
-                ys[i - 1] = y[i - 1];
+                span_at(ys, i - 1) = y.at(i - 1);
             }
         }
-    } else if (newnj == 1) { // newnj equal to one, len less than n
-        auto nsh = (len + 1) / 2;
+    } else if (newnj == 1) {
+        // newnj equal to one, len less than n
+        size_t nsh = (len + 1) / 2;
         nleft = 1;
         nright = len;
-        for (size_t i = 1; i <= n; i++) { // fitted value at i
+        for (size_t i = 1; i <= n; i++) {
+            // fitted value at i
             if (i > nsh && nright != n) {
                 nleft += 1;
                 nright += 1;
             }
-            auto ok = est(y, n, len, ideg, (float) i, &ys[i - 1], nleft, nright, res, userw, rw);
+            bool ok = est(
+                y, n, len, ideg, static_cast<T>(i), span_at(ys, i - 1), nleft, nright, res, userw,
+                rw
+            );
             if (!ok) {
-                ys[i - 1] = y[i - 1];
+                span_at(ys, i - 1) = y.at(i - 1);
             }
         }
-    } else { // newnj greater than one, len less than n
-        auto nsh = (len + 1) / 2;
-        for (size_t i = 1; i <= n; i += newnj) { // fitted value at i
+    } else {
+        // newnj greater than one, len less than n
+        size_t nsh = (len + 1) / 2;
+        for (size_t i = 1; i <= n; i += newnj) {
+            // fitted value at i
             if (i < nsh) {
                 nleft = 1;
                 nright = len;
@@ -132,380 +189,714 @@ 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);
+            bool ok = est(
+                y, n, len, ideg, static_cast<T>(i), span_at(ys, i - 1), nleft, nright, res, userw,
+                rw
+            );
             if (!ok) {
-                ys[i - 1] = y[i - 1];
+                span_at(ys, i - 1) = y.at(i - 1);
             }
         }
     }
 
     if (newnj != 1) {
         for (size_t i = 1; i <= n - newnj; i += newnj) {
-            auto delta = (ys[i + newnj - 1] - ys[i - 1]) / ((float) newnj);
-            for (auto j = i + 1; j <= i + newnj - 1; j++) {
-                ys[j - 1] = ys[i - 1] + delta * ((float) (j - i));
+            T delta = (span_at(ys, i + newnj - 1) - span_at(ys, i - 1)) / static_cast<T>(newnj);
+            for (size_t j = i + 1; j <= i + newnj - 1; j++) {
+                span_at(ys, j - 1) = span_at(ys, i - 1) + delta * static_cast<T>(j - i);
             }
         }
-        auto k = ((n - 1) / newnj) * newnj + 1;
+        size_t 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);
+            bool ok = est(
+                y, n, len, ideg, static_cast<T>(n), span_at(ys, n - 1), nleft, nright, res, userw,
+                rw
+            );
             if (!ok) {
-                ys[n - 1] = y[n - 1];
+                span_at(ys, n - 1) = y.at(n - 1);
             }
             if (k != n - 1) {
-                auto delta = (ys[n - 1] - ys[k - 1]) / ((float) (n - k));
-                for (auto j = k + 1; j <= n - 1; j++) {
-                    ys[j - 1] = ys[k - 1] + delta * ((float) (j - k));
+                T delta = (span_at(ys, n - 1) - span_at(ys, k - 1)) / static_cast<T>(n - k);
+                for (size_t j = k + 1; j <= n - 1; j++) {
+                    span_at(ys, j - 1) = span_at(ys, k - 1) + delta * static_cast<T>(j - k);
                 }
             }
         }
     }
 }
 
-void ma(const float* x, size_t n, size_t len, float* ave) {
-    auto newn = n - len + 1;
-    auto flen = (float) len;
-    auto v = 0.0;
+template<typename T>
+void ma(const std::vector<T>& x, size_t n, size_t len, std::vector<T>& ave) {
+    size_t newn = n - len + 1;
+    auto flen = static_cast<double>(len);
+    double v = 0.0;
 
     // get the first average
     for (size_t i = 0; i < len; i++) {
-        v += x[i];
+        v += x.at(i);
     }
 
-    ave[0] = v / flen;
+    ave.at(0) = static_cast<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;
+            v = v - x.at(m) + x.at(k);
+            ave.at(j) = static_cast<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 std::vector<T>& x,
+    size_t n,
+    size_t np,
+    std::vector<T>& trend,
+    std::vector<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) {
-    for (size_t i = 0; i < n; i++) {
-        rw[i] = fabs(y[i] - fit[i]);
+template<typename T>
+void rwts(std::span<const T> y, const std::vector<T>& fit, std::vector<T>& rw) {
+    // TODO use std::views::zip for C++23
+    for (size_t i = 0; i < y.size(); i++) {
+        rw.at(i) = std::abs(span_at(y, i) - fit.at(i));
     }
 
-    auto mid1 = (n - 1) / 2;
-    auto mid2 = n / 2;
+    size_t n = y.size();
+    size_t mid1 = (n - 1) / 2;
+    size_t mid2 = n / 2;
 
     // sort
-    std::sort(rw, rw + n);
+    std::ranges::sort(rw);
 
-    auto cmad = 3.0 * (rw[mid1] + rw[mid2]); // 6 * median abs resid
-    auto c9 = 0.999 * cmad;
-    auto c1 = 0.001 * cmad;
+    T cmad = static_cast<T>(3.0) * (rw.at(mid1) + rw.at(mid2)); // 6 * median abs resid
+    T c9 = static_cast<T>(0.999) * cmad;
+    T c1 = static_cast<T>(0.001) * cmad;
 
-    for (size_t i = 0; i < n; i++) {
-        auto r = fabs(y[i] - fit[i]);
+    // TODO use std::views::zip for C++23
+    for (size_t i = 0; i < y.size(); i++) {
+        T r = std::abs(span_at(y, i) - fit.at(i));
         if (r <= c1) {
-            rw[i] = 1.0;
+            rw.at(i) = 1.0;
         } else if (r <= c9) {
-            rw[i] = pow(1.0 - pow(r / cmad, 2), 2);
+            rw.at(i) = static_cast<T>(std::pow(1.0 - std::pow(r / cmad, 2.0), 2.0));
         } else {
-            rw[i] = 0.0;
+            rw.at(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 std::vector<T>& y,
+    size_t n,
+    size_t np,
+    size_t ns,
+    int isdeg,
+    size_t nsjump,
+    bool userw,
+    std::vector<T>& rw,
+    std::vector<T>& season,
+    std::vector<T>& work1,
+    std::vector<T>& work2,
+    std::vector<T>& work3,
+    std::vector<T>& work4
+) {
     for (size_t j = 1; j <= np; j++) {
         size_t k = (n - j) / np + 1;
 
         for (size_t i = 1; i <= k; i++) {
-            work1[i - 1] = y[(i - 1) * np + j - 1];
+            work1.at(i - 1) = y.at((i - 1) * np + j - 1);
         }
         if (userw) {
             for (size_t i = 1; i <= k; i++) {
-                work3[i - 1] = rw[(i - 1) * np + j - 1];
+                work3.at(i - 1) = rw.at((i - 1) * np + j - 1);
             }
         }
-        ess(work1, k, ns, isdeg, nsjump, userw, work3, work2 + 1, work4);
-        auto xs = 0.0;
-        auto nright = std::min(ns, k);
-        auto ok = est(work1, k, ns, isdeg, xs, &work2[0], 1, nright, work4, userw, work3);
+        ess(work1, k, ns, isdeg, nsjump, userw, work3, std::span{work2}.subspan(1), work4);
+        T xs = 0.0;
+        size_t nright = std::min(ns, k);
+        bool ok = est(work1, k, ns, isdeg, xs, work2.at(0), 1, nright, work4, userw, work3);
         if (!ok) {
-            work2[0] = work2[1];
+            work2.at(0) = work2.at(1);
         }
-        xs = k + 1;
-        size_t nleft = std::max(1, (int) k - (int) ns + 1);
-        ok = est(work1, k, ns, isdeg, xs, &work2[k + 1], nleft, k, work4, userw, work3);
+        xs = static_cast<T>(k + 1);
+        size_t nleft = static_cast<size_t>(
+            std::max(1, static_cast<int>(k) - static_cast<int>(ns) + 1)
+        );
+        ok = est(work1, k, ns, isdeg, xs, work2.at(k + 1), nleft, k, work4, userw, work3);
         if (!ok) {
-            work2[k + 1] = work2[k];
+            work2.at(k + 1) = work2.at(k);
         }
         for (size_t m = 1; m <= k + 2; m++) {
-            season[(m - 1) * np + j - 1] = work2[m - 1];
+            season.at((m - 1) * np + j - 1) = work2.at(m - 1);
         }
     }
 }
 
-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(
+    std::span<const T> y,
+    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,
+    std::vector<T>& rw,
+    std::vector<T>& season,
+    std::vector<T>& trend,
+    std::vector<T>& work1,
+    std::vector<T>& work2,
+    std::vector<T>& work3,
+    std::vector<T>& work4,
+    std::vector<T>& work5
+) {
+    size_t n = y.size();
+
     for (size_t j = 0; j < ni; j++) {
-        for (size_t i = 0; i < n; i++) {
-            work1[i] = y[i] - trend[i];
+        // TODO use std::views::zip for C++23
+        for (size_t i = 0; i < y.size(); i++) {
+            work1.at(i) = span_at(y, i) - trend.at(i);
         }
 
         ss(work1, n, np, ns, isdeg, nsjump, userw, rw, work2, work3, work4, work5, season);
         fts(work2, n + 2 * np, np, work3, work1);
-        ess(work3, n, nl, ildeg, nljump, false, work4, work1, work5);
+        ess(work3, n, nl, ildeg, nljump, false, work4, std::span{work1}, work5);
+        // TODO use std::views::zip for C++23
         for (size_t i = 0; i < n; i++) {
-            season[i] = work2[np + i] - work1[i];
+            season.at(i) = work2.at(np + i) - work1.at(i);
         }
-        for (size_t i = 0; i < n; i++) {
-            work1[i] = y[i] - season[i];
+        // TODO use std::views::zip for C++23
+        for (size_t i = 0; i < y.size(); i++) {
+            work1.at(i) = span_at(y, i) - season.at(i);
         }
-        ess(work1, n, nt, itdeg, ntjump, userw, rw, trend, work3);
+        ess(work1, n, nt, itdeg, ntjump, userw, rw, std::span{trend}, work3);
     }
 }
 
-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(
+    std::span<const T> y,
+    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,
+    std::vector<T>& rw,
+    std::vector<T>& season,
+    std::vector<T>& trend
+) {
+    size_t n = y.size();
+
     if (ns < 3) {
-        throw std::invalid_argument("seasonal_length must be at least 3");
+        throw std::invalid_argument{"seasonal_length must be at least 3"};
     }
     if (nt < 3) {
-        throw std::invalid_argument("trend_length must be at least 3");
+        throw std::invalid_argument{"trend_length must be at least 3"};
     }
     if (nl < 3) {
-        throw std::invalid_argument("low_pass_length must be at least 3");
+        throw std::invalid_argument{"low_pass_length must be at least 3"};
     }
     if (np < 2) {
-        throw std::invalid_argument("period must be at least 2");
+        throw std::invalid_argument{"period must be at least 2"};
     }
 
     if (isdeg != 0 && isdeg != 1) {
-        throw std::invalid_argument("seasonal_degree must be 0 or 1");
+        throw std::invalid_argument{"seasonal_degree must be 0 or 1"};
     }
     if (itdeg != 0 && itdeg != 1) {
-        throw std::invalid_argument("trend_degree must be 0 or 1");
+        throw std::invalid_argument{"trend_degree must be 0 or 1"};
     }
     if (ildeg != 0 && ildeg != 1) {
-        throw std::invalid_argument("low_pass_degree must be 0 or 1");
+        throw std::invalid_argument{"low_pass_degree must be 0 or 1"};
     }
 
     if (ns % 2 != 1) {
-        throw std::invalid_argument("seasonal_length must be odd");
+        throw std::invalid_argument{"seasonal_length must be odd"};
     }
     if (nt % 2 != 1) {
-        throw std::invalid_argument("trend_length must be odd");
+        throw std::invalid_argument{"trend_length must be odd"};
     }
     if (nl % 2 != 1) {
-        throw std::invalid_argument("low_pass_length must be odd");
+        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);
+    std::vector<T> work1(n + 2 * np);
+    std::vector<T> work2(n + 2 * np);
+    std::vector<T> work3(n + 2 * np);
+    std::vector<T> work4(n + 2 * np);
+    std::vector<T> work5(n + 2 * np);
 
-    auto userw = false;
+    bool userw = false;
     size_t k = 0;
 
     while (true) {
-        onestp(y, n, np, ns, nt, nl, isdeg, itdeg, ildeg, nsjump, ntjump, nljump, ni, userw, rw, season, trend, work1.data(), work2.data(), work3.data(), work4.data(), work5.data());
+        onestp(
+            y,
+            np,
+            ns,
+            nt,
+            nl,
+            isdeg,
+            itdeg,
+            ildeg,
+            nsjump,
+            ntjump,
+            nljump,
+            ni,
+            userw,
+            rw,
+            season,
+            trend,
+            work1,
+            work2,
+            work3,
+            work4,
+            work5
+        );
         k += 1;
         if (k > no) {
             break;
         }
         for (size_t i = 0; i < n; i++) {
-            work1[i] = trend[i] + season[i];
+            work1.at(i) = trend.at(i) + season.at(i);
         }
-        rwts(y, n, work1.data(), rw);
+        rwts(y, work1, rw);
         userw = true;
     }
 
     if (no <= 0) {
         for (size_t i = 0; i < n; i++) {
-            rw[i] = 1.0;
+            rw.at(i) = 1.0;
         }
     }
 }
 
-float var(const std::vector<float>& series) {
-    auto mean = std::accumulate(series.begin(), series.end(), 0.0) / series.size();
-    std::vector<float> tmp;
-    tmp.reserve(series.size());
+template<typename T>
+double var(const std::vector<T>& series) {
+    double mean = std::accumulate(series.begin(), series.end(), 0.0)
+        / static_cast<double>(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 / static_cast<double>(series.size() - 1);
 }
 
-class StlResult {
-public:
-    std::vector<float> seasonal;
-    std::vector<float> trend;
-    std::vector<float> remainder;
-    std::vector<float> weights;
-
-    inline float seasonal_strength() {
-        std::vector<float> sr;
-        sr.reserve(remainder.size());
-        for (size_t i = 0; i < remainder.size(); i++) {
-            sr.push_back(seasonal[i] + remainder[i]);
-        }
-        return std::max(0.0, 1.0 - var(remainder) / var(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.at(i) + remainder.at(i));
     }
+    return std::max(0.0, 1.0 - var(remainder) / var(sr));
+}
 
-    inline float trend_strength() {
-        std::vector<float> tr;
-        tr.reserve(remainder.size());
-        for (size_t i = 0; i < remainder.size(); i++) {
-            tr.push_back(trend[i] + remainder[i]);
-        }
-        return std::max(0.0, 1.0 - var(remainder) / var(tr));
-    }
+} // namespace detail
+
+/// A set of STL parameters.
+struct StlParams {
+    /// Sets the length of the seasonal smoother.
+    std::optional<size_t> seasonal_length = std::nullopt;
+    /// Sets the length of the trend smoother.
+    std::optional<size_t> trend_length = std::nullopt;
+    /// Sets the length of the low-pass filter.
+    std::optional<size_t> low_pass_length = std::nullopt;
+    /// Sets the degree of locally-fitted polynomial in seasonal smoothing.
+    int seasonal_degree = 0;
+    /// Sets the degree of locally-fitted polynomial in trend smoothing.
+    int trend_degree = 1;
+    /// Sets the degree of locally-fitted polynomial in low-pass smoothing.
+    std::optional<int> low_pass_degree = std::nullopt;
+    /// Sets the skipping value for seasonal smoothing.
+    std::optional<size_t> seasonal_jump = std::nullopt;
+    /// Sets the skipping value for trend smoothing.
+    std::optional<size_t> trend_jump = std::nullopt;
+    /// Sets the skipping value for low-pass smoothing.
+    std::optional<size_t> low_pass_jump = std::nullopt;
+    /// Sets the number of loops for updating the seasonal and trend components.
+    std::optional<size_t> inner_loops = std::nullopt;
+    /// Sets the number of iterations of robust fitting.
+    std::optional<size_t> outer_loops = std::nullopt;
+    /// Sets whether robustness iterations are to be used.
+    bool robust = false;
 };
 
-class StlParams {
-    std::optional<size_t> ns_ = std::nullopt;
-    std::optional<size_t> nt_ = std::nullopt;
-    std::optional<size_t> nl_ = std::nullopt;
-    int isdeg_ = 0;
-    int itdeg_ = 1;
-    std::optional<int> ildeg_ = std::nullopt;
-    std::optional<size_t> nsjump_ = std::nullopt;
-    std::optional<size_t> ntjump_ = std::nullopt;
-    std::optional<size_t> nljump_ = std::nullopt;
-    std::optional<size_t> ni_ = std::nullopt;
-    std::optional<size_t> no_ = std::nullopt;
-    bool robust_ = false;
+/// Seasonal-trend decomposition using Loess (STL).
+template<typename T = float>
+class Stl {
+  public:
+    /// Decomposes a time series from a vector.
+    Stl(const std::vector<T>& series, size_t period, const StlParams& params = StlParams());
 
-public:
-    inline StlParams seasonal_length(size_t ns) {
-        this->ns_ = ns;
-        return *this;
+    /// Decomposes a time series from a span.
+    Stl(std::span<const T> series, size_t period, const StlParams& params = StlParams());
+
+    /// Returns the seasonal component.
+    const std::vector<T>& seasonal() const {
+        return seasonal_;
     }
 
-    inline StlParams trend_length(size_t nt) {
-        this->nt_ = nt;
-        return *this;
+    /// Returns the trend component.
+    const std::vector<T>& trend() const {
+        return trend_;
     }
 
-    inline StlParams low_pass_length(size_t nl) {
-        this->nl_ = nl;
-        return *this;
+    /// Returns the remainder.
+    const std::vector<T>& remainder() const {
+        return remainder_;
     }
 
-    inline StlParams seasonal_degree(int isdeg) {
-        this->isdeg_ = isdeg;
-        return *this;
+    /// Returns the weights.
+    const std::vector<T>& weights() const {
+        return weights_;
     }
 
-    inline StlParams trend_degree(int itdeg) {
-        this->itdeg_ = itdeg;
-        return *this;
+    /// Returns the seasonal strength.
+    double seasonal_strength() const {
+        return detail::strength(seasonal_, remainder_);
     }
 
-    inline StlParams low_pass_degree(int ildeg) {
-        this->ildeg_ = ildeg;
-        return *this;
+    /// Returns the trend strength.
+    double trend_strength() const {
+        return detail::strength(trend_, remainder_);
     }
 
-    inline StlParams seasonal_jump(size_t nsjump) {
-        this->nsjump_ = nsjump;
-        return *this;
+  private:
+    std::vector<T> seasonal_;
+    std::vector<T> trend_;
+    std::vector<T> remainder_;
+    std::vector<T> weights_;
+};
+
+template<typename T>
+Stl<T>::Stl(std::span<const T> series, size_t period, const StlParams& params) {
+    std::span<const T> y = series;
+    size_t np = period;
+    size_t n = series.size();
+
+    if (n / 2 < np) {
+        throw std::invalid_argument{"series has less than two periods"};
     }
 
-    inline StlParams trend_jump(size_t ntjump) {
-        this->ntjump_ = ntjump;
-        return *this;
+    size_t ns = params.seasonal_length.value_or(np);
+
+    int isdeg = params.seasonal_degree;
+    int itdeg = params.trend_degree;
+
+    std::vector<T> seasonal(n);
+    std::vector<T> trend(n);
+    std::vector<T> remainder;
+    std::vector<T> weights(n);
+
+    int ildeg = params.low_pass_degree.value_or(itdeg);
+    size_t newns = std::max(ns, static_cast<size_t>(3));
+    if (newns % 2 == 0) {
+        newns += 1;
     }
 
-    inline StlParams low_pass_jump(size_t nljump) {
-        this->nljump_ = nljump;
-        return *this;
+    size_t newnp = std::max(np, static_cast<size_t>(2));
+    auto nt = static_cast<size_t>(
+        std::ceil((1.5 * static_cast<float>(newnp)) / (1.0 - 1.5 / static_cast<float>(newns)))
+    );
+    nt = params.trend_length.value_or(nt);
+    nt = std::max(nt, static_cast<size_t>(3));
+    if (nt % 2 == 0) {
+        nt += 1;
     }
 
-    inline StlParams inner_loops(bool ni) {
-        this->ni_ = ni;
-        return *this;
+    size_t nl = params.low_pass_length.value_or(newnp);
+    if (nl % 2 == 0 && !params.low_pass_length.has_value()) {
+        nl += 1;
     }
 
-    inline StlParams outer_loops(bool no) {
-        this->no_ = no;
-        return *this;
+    size_t ni = params.inner_loops.value_or(params.robust ? 1 : 2);
+    size_t no = params.outer_loops.value_or(params.robust ? 15 : 0);
+
+    size_t nsjump = params.seasonal_jump.value_or(
+        static_cast<size_t>(std::ceil(static_cast<float>(newns) / 10.0))
+    );
+    size_t ntjump = params.trend_jump.value_or(
+        static_cast<size_t>(std::ceil(static_cast<float>(nt) / 10.0))
+    );
+    size_t nljump = params.low_pass_jump.value_or(
+        static_cast<size_t>(std::ceil(static_cast<float>(nl) / 10.0))
+    );
+
+    detail::stl(
+        y,
+        newnp,
+        newns,
+        nt,
+        nl,
+        isdeg,
+        itdeg,
+        ildeg,
+        nsjump,
+        ntjump,
+        nljump,
+        ni,
+        no,
+        weights,
+        seasonal,
+        trend
+    );
+
+    remainder.reserve(n);
+    // TODO use std::views::zip for C++23
+    for (size_t i = 0; i < y.size(); i++) {
+        remainder.push_back(detail::span_at(y, i) - seasonal.at(i) - trend.at(i));
+    }
+
+    seasonal_ = std::move(seasonal);
+    trend_ = std::move(trend);
+    remainder_ = std::move(remainder);
+    weights_ = std::move(weights);
+}
+
+template<typename T>
+Stl<T>::Stl(const std::vector<T>& series, size_t period, const StlParams& params) :
+    Stl(std::span{series}, period, params) {}
+
+/// A set of MSTL parameters.
+struct MstlParams {
+    /// Sets the number of iterations.
+    size_t iterations = 2;
+    /// Sets lambda for Box-Cox transformation.
+    std::optional<float> lambda = std::nullopt;
+    /// Sets the lengths of the seasonal smoothers.
+    std::optional<std::vector<size_t>> seasonal_lengths = std::nullopt;
+    /// Sets the STL parameters.
+    StlParams stl_params = StlParams();
+};
+
+/// Multiple seasonal-trend decomposition using Loess (MSTL).
+template<typename T = float>
+class Mstl {
+  public:
+    /// Decomposes a time series from a vector.
+    Mstl(
+        const std::vector<T>& series,
+        const std::vector<size_t>& periods,
+        const MstlParams& params = MstlParams()
+    );
+
+    /// Decomposes a time series from a span.
+    Mstl(
+        std::span<const T> series,
+        std::span<const size_t> periods,
+        const MstlParams& params = MstlParams()
+    );
+
+    /// Returns the seasonal component.
+    const std::vector<std::vector<T>>& seasonal() const {
+        return seasonal_;
+    }
+
+    /// Returns the trend component.
+    const std::vector<T>& trend() const {
+        return trend_;
+    }
+
+    /// Returns the remainder.
+    const std::vector<T>& remainder() const {
+        return remainder_;
+    }
+
+    /// Returns the seasonal strength.
+    std::vector<double> seasonal_strength() const {
+        std::vector<double> res;
+        res.reserve(seasonal_.size());
+        for (const auto& s : seasonal_) {
+            res.push_back(detail::strength(s, remainder_));
+        }
+        return res;
     }
 
-    inline StlParams robust(bool robust) {
-        this->robust_ = robust;
-        return *this;
+    /// Returns the trend strength.
+    double trend_strength() const {
+        return detail::strength(trend_, remainder_);
     }
 
-    StlResult fit(const float* y, size_t n, size_t np);
-    StlResult fit(const std::vector<float>& y, size_t np);
+  private:
+    std::vector<std::vector<T>> seasonal_;
+    std::vector<T> trend_;
+    std::vector<T> remainder_;
 };
 
-StlParams params() {
-    return StlParams();
-}
+namespace detail {
 
-StlResult StlParams::fit(const float* y, size_t n, size_t np) {
-    if (n < 2 * np) {
-        throw std::invalid_argument("series has less than two periods");
+template<typename T>
+std::vector<T> box_cox(std::span<const T> y, float lambda) {
+    std::vector<T> res;
+    res.reserve(y.size());
+    if (lambda != 0.0) {
+        for (auto yi : y) {
+            res.push_back(static_cast<T>(std::pow(yi, lambda) - 1.0) / lambda);
+        }
+    } else {
+        for (auto yi : y) {
+            res.push_back(std::log(yi));
+        }
     }
+    return res;
+}
 
-    auto ns = this->ns_.value_or(np);
+template<typename T>
+std::tuple<std::vector<T>, std::vector<T>, std::vector<std::vector<T>>> mstl(
+    std::span<const T> x,
+    std::span<const size_t> seas_ids,
+    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(seas_ids.size());
+    std::iota(indices.begin(), indices.end(), 0);
+    std::ranges::sort(indices, [&seas_ids](size_t a, size_t b) {
+        return span_at(seas_ids, a) < span_at(seas_ids, b);
+    });
+
+    if (seas_ids.size() == 1) {
+        iterate = 1;
+    }
+
+    std::vector<std::vector<T>> seasonality;
+    seasonality.reserve(seas_ids.size());
+    std::vector<T> trend;
+
+    std::vector<T> deseas = lambda.has_value()
+        ? box_cox(x, lambda.value())
+        : std::vector<T>(x.begin(), x.end());
+
+    if (!seas_ids.empty()) {
+        for (size_t i = 0; i < seas_ids.size(); i++) {
+            seasonality.push_back(std::vector<T>());
+        }
 
-    auto isdeg = this->isdeg_;
-    auto itdeg = this->itdeg_;
+        for (size_t j = 0; j < iterate; j++) {
+            for (size_t i = 0; i < indices.size(); i++) {
+                size_t idx = indices.at(i);
 
-    auto res = StlResult {
-        std::vector<float>(n),
-        std::vector<float>(n),
-        std::vector<float>(),
-        std::vector<float>(n)
-    };
+                if (j > 0) {
+                    for (size_t ii = 0; ii < deseas.size(); ii++) {
+                        deseas.at(ii) += seasonality.at(idx).at(ii);
+                    }
+                }
 
-    auto ildeg = this->ildeg_.value_or(itdeg);
-    auto newns = std::max(ns, (size_t) 3);
-    if (newns % 2 == 0) {
-        newns += 1;
-    }
+                StlParams params = stl_params;
+                if (swin) {
+                    params.seasonal_length = swin.value().at(idx);
+                } else if (!stl_params.seasonal_length.has_value()) {
+                    params.seasonal_length = 7 + 4 * (i + 1);
+                }
+                Stl<T> fit{deseas, span_at(seas_ids, idx), params};
 
-    auto newnp = std::max(np, (size_t) 2);
-    auto nt = (size_t) ceil((1.5 * newnp) / (1.0 - 1.5 / (float) newns));
-    nt = this->nt_.value_or(nt);
-    nt = std::max(nt, (size_t) 3);
-    if (nt % 2 == 0) {
-        nt += 1;
+                seasonality.at(idx) = fit.seasonal();
+                trend = fit.trend();
+
+                for (size_t ii = 0; ii < deseas.size(); ii++) {
+                    deseas.at(ii) -= seasonality.at(idx).at(ii);
+                }
+            }
+        }
+    } else {
+        // TODO use Friedman's Super Smoother for trend
+        throw std::invalid_argument{"periods must not be empty"};
     }
 
-    auto nl = this->nl_.value_or(newnp);
-    if (nl % 2 == 0 && !this->nl_.has_value()) {
-        nl += 1;
+    std::vector<T> remainder;
+    remainder.reserve(x.size());
+    for (size_t i = 0; i < x.size(); i++) {
+        remainder.push_back(deseas.at(i) - trend.at(i));
     }
 
-    auto ni = this->ni_.value_or(this->robust_ ? 1 : 2);
-    auto no = this->no_.value_or(this->robust_ ? 15 : 0);
+    return std::make_tuple(trend, remainder, seasonality);
+}
 
-    auto nsjump = this->nsjump_.value_or((size_t) ceil(((float) newns) / 10.0));
-    auto ntjump = this->ntjump_.value_or((size_t) ceil(((float) nt) / 10.0));
-    auto nljump = this->nljump_.value_or((size_t) ceil(((float) nl) / 10.0));
+} // namespace detail
+
+template<typename T>
+Mstl<T>::Mstl(
+    std::span<const T> series,
+    std::span<const size_t> periods,
+    const MstlParams& params
+) {
+    // return error to be consistent with stl
+    // and ensure seasonal is always same length as periods
+    for (auto v : periods) {
+        if (v < 2) {
+            throw std::invalid_argument{"periods must be at least 2"};
+        }
+    }
 
-    stl(y, n, newnp, newns, nt, nl, isdeg, itdeg, ildeg, nsjump, ntjump, nljump, ni, no, res.weights.data(), res.seasonal.data(), res.trend.data());
+    // return error to be consistent with stl
+    // and ensure seasonal is always same length as periods
+    for (auto v : periods) {
+        if (series.size() < v * 2) {
+            throw std::invalid_argument{"series has less than two periods"};
+        }
+    }
 
-    res.remainder.reserve(n);
-    for (size_t i = 0; i < n; i++) {
-        res.remainder.push_back(y[i] - res.seasonal[i] - res.trend[i]);
+    if (params.lambda.has_value()) {
+        float lambda = params.lambda.value();
+        if (lambda < 0 || lambda > 1) {
+            throw std::invalid_argument{"lambda must be between 0 and 1"};
+        }
     }
 
-    return res;
-}
+    if (params.seasonal_lengths.has_value()) {
+        if (params.seasonal_lengths.value().size() != periods.size()) {
+            throw std::invalid_argument{"seasonal_lengths must have the same length as periods"};
+        }
+    }
 
-StlResult StlParams::fit(const std::vector<float>& y, size_t np) {
-    return StlParams::fit(y.data(), y.size(), np);
-}
+    auto [trend, remainder, seasonal] = detail::mstl(
+        series,
+        periods,
+        params.iterations,
+        params.lambda,
+        params.seasonal_lengths,
+        params.stl_params
+    );
 
+    seasonal_ = std::move(seasonal);
+    trend_ = std::move(trend);
+    remainder_ = std::move(remainder);
 }
+
+template<typename T>
+Mstl<T>::Mstl(
+    const std::vector<T>& series,
+    const std::vector<size_t>& periods,
+    const MstlParams& params
+) :
+    Mstl(std::span{series}, std::span{periods}, params) {}
+
+} // namespace stl