stl-rb 0.4.1 → 0.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c2dd80347b3360994ebdefd94b6649d1c43d1e8b9d0bfae1a81df87b3ef6b27
-  data.tar.gz: 9bd7ddf6a35529a2365fe55e19e025d0c94a122d5eede5db0a8fbc1fcc53ba91
+  metadata.gz: c47963b84db78ea882aa50f4a6a18c18ee84e9acc802d0db125772f80531b179
+  data.tar.gz: 9c9e732f43bc586dbac041be2a3c4cc59d552681a59f8185cb873f6800bf9787
 SHA512:
-  metadata.gz: 4517e2450a79e93177c55623a34e6d9bc1f9a2e366cd92060fc08ef43a7f768a8c09df5b47eb21b7aa5fd41084526e325eb0d3b6064331193d1e1e583f46068d
-  data.tar.gz: 1a482b74b0f6bd586f4c58974f125a0484eca0c7f36cfe91d26ab52a0c75a1634ade87b1ce14416d3ada5f04e3623c1b8d7e507267ecdd40388e11418c922485
+  metadata.gz: f434fe76d8498d8eaf6560fc464f84e10ea1aa1addf32a5fbf432e1f1435ae31d5936b2b49b64a3220bdf298b379074d97b4f9863e6e6a4a10a800ac6caa2746
+  data.tar.gz: 4aa67ef012521f9a810f6aa15586e0f9010c4a87b0f7aacbf0fb8eef6aeb47af06b0707d5268b0b9bb5c2f57cd0d295de47930907e24658db9e6d5091ab16b01

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 0.4.2 (2026-08-08)
+
+- Added support for MSTL
+
 ## 0.4.1 (2026-05-04)
 
 - Fixed error with certain options

data/README.md

@@ -18,9 +18,9 @@ Decompose a time series
 
 ```ruby
 series = {
-  Date.parse("2025-01-01") => 100,
-  Date.parse("2025-01-02") => 150,
-  Date.parse("2025-01-03") => 136,
+  Date.parse("2026-01-01") => 100,
+  Date.parse("2026-01-02") => 150,
+  Date.parse("2026-01-03") => 136,
   # ...
 }
 
@@ -47,6 +47,14 @@ Use robustness iterations
 Stl.decompose(series, period: 7, robust: true)
 ```
 
+## Multiple Seasonality
+
+Specify multiple periods
+
+```ruby
+Stl.decompose(series, period: [7, 365])
+```
+
 ## Options
 
 Pass options
@@ -66,7 +74,9 @@ Stl.decompose(
   low_pass_jump: 1,       # skipping value for low-pass smoothing
   inner_loops: 2,         # number of loops for updating the seasonal and trend components
   outer_loops: 0,         # number of iterations of robust fitting
-  robust: false           # if robustness iterations are to be used
+  robust: false,          # if robustness iterations are to be used
+  iterations: 2,          # number of iterations for MSTL
+  lambda: 0.5             # lambda for Box-Cox transformation for MSTL
 )
 ```
 
@@ -105,6 +115,7 @@ This library was ported from the [Fortran implementation](https://www.netlib.org
 ## References
 
 - [STL: A Seasonal-Trend Decomposition Procedure Based on Loess](https://www.scb.se/contentassets/ca21efb41fee47d293bbee5bf7be7fb3/stl-a-seasonal-trend-decomposition-procedure-based-on-loess.pdf)
+- [MSTL: A Seasonal-Trend Decomposition Algorithm for Time Series with Multiple Seasonal Patterns](https://arxiv.org/pdf/2107.13462.pdf)
 - [Measuring strength of trend and seasonality](https://otexts.com/fpp2/seasonal-strength.html)
 
 ## History

data/ext/stl/ext.cpp

@@ -33,6 +33,13 @@ void Init_ext() {
     .define_attr("outer_loops", &stl::StlParams::outer_loops)
     .define_attr("robust", &stl::StlParams::robust);
 
+  Rice::define_class_under<stl::MstlParams>(rb_mStl, "MstlParams")
+    .define_constructor(Rice::Constructor<stl::MstlParams>())
+    .define_attr("iterations", &stl::MstlParams::iterations)
+    .define_attr("lambda", &stl::MstlParams::lambda)
+    .define_attr("seasonal_lengths", &stl::MstlParams::seasonal_lengths)
+    .define_attr("stl_params", &stl::MstlParams::stl_params);
+
   rb_mStl
     .define_singleton_function(
       "_decompose",
@@ -48,5 +55,22 @@ void Init_ext() {
           ret[Rice::Symbol("weights")] = to_a(fit.weights());
         }
         return ret;
+      })
+    .define_singleton_function(
+      "_decompose_mstl",
+      [](Rice::Array rb_series, const std::vector<size_t>& periods, const stl::MstlParams& params) {
+        std::vector<float> series = rb_series.to_vector<float>();
+        stl::Mstl fit{series, periods, params};
+
+        Rice::Array seasonal;
+        for (const auto& s : fit.seasonal()) {
+          seasonal.push(to_a(s), false);
+        }
+
+        Rice::Hash ret;
+        ret[Rice::Symbol("seasonal")] = seasonal;
+        ret[Rice::Symbol("trend")] = to_a(fit.trend());
+        ret[Rice::Symbol("remainder")] = to_a(fit.remainder());
+        return ret;
       });
 }

data/lib/stl/version.rb

@@ -1,3 +1,3 @@
 module Stl
-  VERSION = "0.4.1"
+  VERSION = "0.4.2"
 end

data/lib/stl.rb

@@ -11,15 +11,18 @@ module Stl
       seasonal_length: nil, trend_length: nil, low_pass_length: nil,
       seasonal_degree: nil, trend_degree: nil, low_pass_degree: nil,
       seasonal_jump: nil, trend_jump: nil, low_pass_jump: nil,
-      inner_loops: nil, outer_loops: nil, robust: false
+      inner_loops: nil, outer_loops: nil, robust: false,
+      iterations: nil, lambda: nil
     )
-      if period < 2
+      mstl = period.is_a?(Array)
+
+      if !mstl && period < 2
         raise ArgumentError, "period must be greater than 1"
       end
 
       params = StlParams.new
 
-      params.seasonal_length = seasonal_length unless seasonal_length.nil?
+      params.seasonal_length = seasonal_length if !seasonal_length.nil? && !(mstl && seasonal_length.is_a?(Array))
       params.trend_length = trend_length unless trend_length.nil?
       params.low_pass_length = low_pass_length unless low_pass_length.nil?
 
@@ -42,12 +45,27 @@ module Stl
         y = series
       end
 
-      _decompose(y, period, params, outer_loops.nil? ? robust : outer_loops > 0)
+      if mstl
+        mstl_params = MstlParams.new
+        mstl_params.iterations = iterations unless iterations.nil?
+        mstl_params.lambda = lambda unless lambda.nil?
+        mstl_params.seasonal_lengths = seasonal_length if seasonal_length.is_a?(Array)
+        mstl_params.stl_params = params
+        _decompose_mstl(y, period, mstl_params)
+      else
+        raise ArgumentError, "iterations requires MSTL" unless iterations.nil?
+        raise ArgumentError, "lambda requires MSTL" unless lambda.nil?
+        _decompose(y, period, params, outer_loops.nil? ? robust : outer_loops > 0)
+      end
     end
 
     def plot(series, result)
       require "vega"
 
+      if mstl?(result)
+        raise "not implemented yet"
+      end
+
       data =
         if series.is_a?(Hash)
           series.sort_by { |k, _| k }.map.with_index do |s, i|
@@ -101,13 +119,17 @@ module Stl
     end
 
     def seasonal_strength(result)
-      sr = result[:seasonal].zip(result[:remainder]).map { |a, b| a + b }
-      [0, 1 - var(result[:remainder]) / var(sr)].max
+      if mstl?(result)
+        result[:seasonal].map do |s|
+          strength(s, result[:remainder])
+        end
+      else
+        strength(result[:seasonal], result[:remainder])
+      end
     end
 
     def trend_strength(result)
-      tr = result[:trend].zip(result[:remainder]).map { |a, b| a + b }
-      [0, 1 - var(result[:remainder]) / var(tr)].max
+      strength(result[:trend], result[:remainder])
     end
 
     private
@@ -120,9 +142,18 @@ module Stl
       end
     end
 
+    def strength(component, remainder)
+      sr = component.zip(remainder).map { |a, b| a + b }
+      [0, 1 - var(remainder) / var(sr)].max
+    end
+
     def var(series)
       mean = series.sum / series.size.to_f
       series.sum { |v| (v - mean) ** 2 } / (series.size.to_f - 1)
     end
+
+    def mstl?(result)
+      result[:seasonal][0].is_a?(Array)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stl-rb
 version: !ruby/object:Gem::Version
-  version: 0.4.1
+  version: 0.4.2
 platform: ruby
 authors:
 - Andrew Kane
@@ -55,7 +55,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.6
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Seasonal-trend decomposition for Ruby
 test_files: []