STL Ruby

Seasonal-trend decomposition for Ruby

Installation

Add this line to your application’s Gemfile:

gem 'stl-rb'

Getting Started

Decompose a time series

series = {
  Date.parse("2020-01-01") => 100,
  Date.parse("2020-01-02") => 150,
  Date.parse("2020-01-03") => 136,
  # ...
}

Stl.decompose(series, period: 7)

Works great with Groupdate

series = User.group_by_day(:created_at).count
Stl.decompose(series, period: 7)

Series can also be an array without times

series = [100, 150, 136, ...]
Stl.decompose(series, period: 7)

Use robustness iterations

Stl.decompose(series, period: 7, robust: true)

Options

Pass options

Stl.decompose(
  series,
  period: 7,              # period of the seasonal component
  seasonal_length: 7,     # length of the seasonal smoother
  trend_length: 15,       # length of the trend smoother
  low_pass_length: 7,     # length of the low-pass filter
  seasonal_degree: 0,     # degree of locally-fitted polynomial in seasonal smoothing
  trend_degree: 1,        # degree of locally-fitted polynomial in trend smoothing
  low_pass_degree: 1,     # degree of locally-fitted polynomial in low-pass smoothing
  seasonal_jump: 1,       # skipping value for seasonal smoothing
  trend_jump: 2,          # skipping value for trend smoothing
  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
)

Plotting

Add Vega to your application’s Gemfile:

gem 'vega'

And use:

Stl.plot(series, decompose_result)

Strength

Get the seasonal strength

Stl.seasonal_strength(decompose_result)

Get the trend strength

Stl.trend_strength(decompose_result)

Credits

This library was ported from the Fortran implementation.

References

• STL: A Seasonal-Trend Decomposition Procedure Based on Loess
• Measuring strength of trend and seasonality

History

View the changelog

Contributing

Everyone is encouraged to help improve this project. Here are a few ways you can help:

• Report bugs
• Fix bugs and submit pull requests
• Write, clarify, or fix documentation
• Suggest or add new features

To get started with development:

git clone https://github.com/ankane/stl-ruby.git
cd stl-ruby
bundle install
bundle exec rake compile
bundle exec rake test