tsb — Exponential Smoothing (ETS / Holt-Winters)

1 — Simple Exponential Smoothing (SES)

SimpleExpSmoothing fits ETS(A,N,N): level-only smoothing with parameter α. All h-step forecasts equal the final level. α is estimated by minimising SSE via Nelder-Mead.

JavaScript

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

2 — Holt's Linear Trend (Double Exponential Smoothing)

Holt extends SES with a trend component β (ETS(A,A,N)). Optionally damps the trend with φ (ETS(A,Ad,N)) to prevent over-shooting.

JavaScript

import { Holt, holt } from "tsb";

// Upward trend data (roughly linear)
const y = [10, 12, 13, 15, 17, 18, 20, 22, 24, 25, 27, 29,
           31, 32, 34, 36, 38, 39, 41, 43];

// Standard Holt (ETS(A,A,N))
const modelA = new Holt();
const fitA = modelA.fit(y);
console.log("=== Holt (no damping) ===");
console.log("α:", fitA.alpha.toFixed(4), "  β:", fitA.beta.toFixed(4));
console.log("φ:", fitA.phi, " (= 1, no damping)");
console.log("AIC:", fitA.aic.toFixed(2));
console.log("5-step forecast:", modelA.forecast(5).map(v => v.toFixed(1)));

// Damped Holt (ETS(A,Ad,N))
const modelD = new Holt({ damped: true });
const fitD = modelD.fit(y);
console.log("\n=== Damped Holt ===");
console.log("α:", fitD.alpha.toFixed(4), "  β:", fitD.beta.toFixed(4));
console.log("φ:", fitD.phi.toFixed(4), " (< 1, damped)");
console.log("AIC:", fitD.aic.toFixed(2));
console.log("5-step forecast:", modelD.forecast(5).map(v => v.toFixed(1)));

// Damped forecasts converge, non-damped grow linearly
const fc5 = modelA.forecast(10);
const fcd5 = modelD.forecast(10);
console.log("\nStep 10 undamped:", fc5[9].toFixed(1), "vs damped:", fcd5[9].toFixed(1));

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

3 — Holt-Winters Additive Seasonal

ExponentialSmoothing with trend: "add" and seasonal: "add" models data with a linear trend plus additive seasonal fluctuations. Classic Holt-Winters ETS(A,A,A).

JavaScript

import { ExponentialSmoothing } from "tsb";

// Monthly passenger data — clear trend and seasonality (period = 12)
const airline = [
  112, 118, 132, 129, 121, 135, 148, 148, 136, 119, 104, 118,
  115, 126, 141, 135, 125, 149, 170, 170, 158, 133, 114, 140,
  145, 150, 178, 163, 172, 178, 199, 199, 184, 162, 146, 166,
];

const model = new ExponentialSmoothing({
  trend: "add",
  seasonal: "add",
  seasonalPeriods: 12,
});
const fit = model.fit(airline);

console.log("=== Holt-Winters Additive ===");
console.log("α (level):    ", fit.alpha.toFixed(4));
console.log("β (trend):    ", fit.beta.toFixed(4));
console.log("γ (seasonal): ", fit.gamma.toFixed(4));
console.log("φ (damping):  ", fit.phi.toFixed(4));
console.log("AIC:", fit.aic.toFixed(2), " BIC:", fit.bic.toFixed(2));
console.log("AICc:", fit.aicc.toFixed(2));
console.log("logL:", fit.logLikelihood.toFixed(2));

// In-sample MAE
const mae = fit.residuals.reduce((s, e) => s + Math.abs(e), 0) / fit.residuals.length;
console.log("In-sample MAE:", mae.toFixed(2));

// 12-month forecast
const fc = model.forecast(12);
console.log("\n12-month forecast:");
console.log(fc.map(v => v.toFixed(1)).join(", "));

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

4 — Holt-Winters Multiplicative Seasonal

Use seasonal: "mul" when the amplitude of seasonal swings grows with the level (common in economic time series). ETS(A,A,M).

JavaScript

import { ExponentialSmoothing, fitEts } from "tsb";

// Quarterly data with multiplicative seasonality (amplitude grows with level)
const y = [
  90, 120, 160, 80,    // year 1
  100, 135, 180, 90,   // year 2
  115, 155, 200, 100,  // year 3
  130, 170, 220, 115,  // year 4
];

// Additive model
const fitAdd = fitEts(y, { trend: "add", seasonal: "add", seasonalPeriods: 4 });

// Multiplicative model
const fitMul = fitEts(y, { trend: "add", seasonal: "mul", seasonalPeriods: 4 });

console.log("Additive AIC:       ", fitAdd.aic.toFixed(2));
console.log("Multiplicative AIC: ", fitMul.aic.toFixed(2));
console.log("\nMultiplicative seasonal indices:", fitMul.initialSeasons?.map(v => v.toFixed(3)));
console.log("(values near 1.0 = neutral, >1 = above average, <1 = below)");

// 4-quarter forecasts
const modelMul = new ExponentialSmoothing({
  trend: "add", seasonal: "mul", seasonalPeriods: 4,
});
modelMul.fit(y);
const fc = modelMul.forecast(4);
console.log("\nNext 4 quarters forecast:", fc.map(v => v.toFixed(1)));

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

5 — Forecast with prediction intervals

forecastWithCI(steps, alpha) returns point forecasts plus (1 − α) % prediction intervals. Intervals widen with forecast horizon.

JavaScript

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

6 — Model selection via AIC/BIC

Compare SES, Holt, and Holt-Winters using information criteria. Lower AIC/BIC indicates a better balance of fit and parsimony.

JavaScript

import { simpleExpSmoothing, holt, fitEts } from "tsb";

// Clearly seasonal data
const y = [
  17, 21, 23, 18, 22, 26, 19, 24, 27, 20, 25, 28,
  18, 23, 25, 20, 24, 28, 21, 26, 29, 22, 27, 30,
];

const models = [
  { name: "SES (ETS(A,N,N))",         r: ses },
  { name: "Holt (ETS(A,A,N))",        r: holtFit },
  { name: "H-W add (ETS(A,A,A))",     r: hwAdd },
  { name: "H-W mul (ETS(A,A,M))",     r: hwMul },
  { name: "H-W add damped (ETS(A,Ad,A))", r: hwDamped },
];

console.log("Model                        | AIC     | BIC     | SSE");
console.log("-----------------------------|---------|---------|--------");
for (const { name, r } of models) {
  console.log(
    name.padEnd(28) + " | " +
    r.aic.toFixed(2).padStart(7) + " | " +
    r.bic.toFixed(2).padStart(7) + " | " +
    r.sse.toFixed(2)
  );
}
console.log("\n↑ Lower AIC/BIC = better model fit vs complexity trade-off");

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent

7 — Known initialisation and fixed parameters

You can supply fixed smoothing parameters or initial state values. Use initializationMethod: "known" to set the initial state directly without estimating it.

JavaScript

Click ▶ Run to execute

Ctrl+Enter to run · Tab to indent