STL Decomposition

Install and import

bash

npm install fintech-algorithms

import { stlDecompose } from "fintech-algorithms/statistical-time-series/decomposition-and-cycles/stl-decomposition";

Signature

stlDecompose(values, period, seasonalWindow, trendWindow, robustIterations)

Seasonal-trend decomposition by loess: splits a series into seasonal, trend and remainder. Unlike a fixed seasonal index it lets the seasonal shape evolve, which is why it survives series where the pattern drifts.

Parameters

Name	Type	Notes
`values`	`number[]`	Observation series, chronological.
`period`	`number`	Seasonal period — 12 for monthly, 5 for a trading week. min: 1 · integer: true
`seasonalWindow`	`number`	Loess span for the seasonal component. Larger holds the seasonal shape more constant across cycles. min: 1 · integer: true
`trendWindow`	`number`	Loess span for the trend. min: 1 · integer: true
`robustIterations`	`number`	Robustness passes that downweight outliers. Zero gives the non-robust fit. min: 0 · integer: true

Returns

{ seasonal, trend, remainder, … }

The three components, which sum back to the original series.

Errors

When the series is shorter than two full periods — throws

Complexity: time O(n × window × iterations), space O(n).

Worked example

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input

values

[
  100.0901805654,
  101.3367333472,
  102.4083163971,
  102.9128416721,
  103.198587938,
  102.4311805579
]

Showing 6 of 192 elements.

period

seasonalWindow

trendWindow

robustIterations

Call

stlDecompose(values, period, seasonalWindow, trendWindow, robustIterations)

Returns

object with 10 fields: observed, trend, seasonal, residual, robust_weights, period, seasonal_window, trend_window, …

{
  "observed": [
    100.0901805654,
    101.3367333472,
    102.4083163971,
    102.9128416721,
    103.198587938,
    102.4311805579
  ],
  "trend": [
    101.80653184631831,
    101.74335719017421,
    101.68290299767973,
    101.62622211934938,
    101.5743610938178,
    101.52818917545937
  ],
  "seasonal": [
    -1.675059270552302,
    -0.37793707310334934,
    0.5876119710645483,
    1.128755113942449,
    1.414763613255315,
    0.6984276428857473
  ],
  "residual": [
    -0.041292010366001275,
    -0.028686769870863493,
    0.13780142835571352,
    0.15786443880817314,
    0.20946323092688846,
    0.20456373955488483
  ],
  "robust_weights": [
    0.9997399824592482,
    0.9998384208965301,
    0.9966750447871305,
    0.9957359792237003,
    0.9926684141414982,
    0.9930448769484919
  ],
  "period": 12,
  "seasonal_window": 7,
  "trend_window": 19,
  "robust_iterations": 2,
  "reconstruction_max_error": 0
}

Other exports

This module also exports hpFilter, bkFilter, cfFilter, fftPeriodogram, haarWavelet, runTopic. Every module additionally exports run as an alias of its primary function, and a meta object carrying its catalog id, domain, family, shape and article URL.

Diagrams

How it works

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References

Evidence table
Source records
Evidence policy
Version notes