Trend, Seasonality, Cycles, and Remainder

Install and import#

npm install fintech-algorithms

import { trendSeasonalityCyclesAndRemainder } from "fintech-algorithms/foundations/financial-time-series-foundations/trend-seasonality-cycles-and-remainder";

Signature#

trendSeasonalityCyclesAndRemainder(input)

Separates a series into a rolling-mean trend, a seasonal difference taken period steps back, and the remainder left once the trend is removed.

Parameters#

Returns#

D00Output

trend is the rolling mean, null at positions with fewer than window observations behind them. seasonalDifference subtracts the value period positions earlier and is null for the first period entries. remainder is the value minus the trend, null wherever the trend is. period is echoed back.

Errors#

• When values is absent, empty, or holds a non-finite number — throws RangeError
• When timestamps and values have different lengths — throws RangeError
• When the series holds fewer than two observations — throws RangeError
• When window is not an integer between one and the observation count — throws RangeError
• When period is not an integer between one and the observation count minus one — throws RangeError

Complexity: time O(n^2), space O(n).

Worked example#

verified This is the worked example published in the article, replayed by the test suite on every run. The output cannot drift.

Input#

{
  "timestamps": [
    "2025-01-01T00:00:00Z",
    "2025-01-02T00:00:00Z",
    "2025-01-03T00:00:00Z",
    "2025-01-04T00:00:00Z",
    "2025-01-05T00:00:00Z",
    "2025-01-06T00:00:00Z"
  ],
  "values": [100, 102, 101, 104, 106, 105],
  "lag": 1,
  "window": 3,
  "resampleSize": 2,
  "period": 3,
  "stationarityTolerance": 3,
  "alpha": 0.4,
  "splitIndex": 4
}

Call#

trendSeasonalityCyclesAndRemainder(input)

Returns#

object with 2 fields: trend, seasonalDifference

{
  "trend": [null, null, 101, 102.33333333333333, 103.66666666666667, 105],
  "seasonalDifference": [null, null, null, 4, 4, 4]
}

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#

• Time Series Plot — NIST/SEMATECH e-Handbook
• Common Pitfalls and Recommended Practices — scikit-learn
• Historical-example decision

The rest of the Financial Time-Series Foundations family#

• Time Order, Frequency, Regularity, and Financial CalendarsChecks whether a timestamped series runs in chronological order and whether its observations are evenly spaced, reporting the c…
• Levels, Changes, Differences, and ReturnsConverts a level series into its period-over-period differences and its simple returns, keeping the original levels alongside t…
• Lags, Leads, and Temporal DependencePairs every observation with the value lag positions behind it, and exposes the same series shifted forward as the lead.
• Rolling and Expanding WindowsComputes a fixed-length rolling mean of the series next to its expanding mean, so a window that forgets can be compared with on…
• Resampling, Aggregation, and Time AlignmentCuts the series into consecutive fixed-size buckets and averages each one, coarsening the sampling frequency.
• Autocovariance and AutocorrelationMeasures how far a series moves with its own past at a given lag, using the population convention that divides by the full obse…
• Stationarity and Differencing IntuitionCompares the average level of the second half of a series with the first half, and reports the first differences, as a rough re…
• Smoothing, Baselines, and Naive ForecastsRuns simple exponential smoothing over the series and reports both the naive last-value forecast and the smoothed one.
• Look-Ahead Leakage and Time-Aware Data SplitsSplits a timestamped series at a given position and reports whether the training block reaches into the testing block's time ra…