# Holt-Winters

`D09-F02-A05` · Statistical Time Series → Forecast Models · archetype `record-transform` · difficulty 3/5 · verification **verified**

Full page: https://docs.thefintechbuilder.com/statistical-time-series/forecast-models/holt-winters/
Agent skill: `npx skills add IslamBaraka90/Fintech-Algorithms-Library` — https://docs.thefintechbuilder.com/guides/agent-skill/

## Install and import

```bash
npm install fintech-algorithms
```

```ts
import { forecastHoltWintersAdditive } from "fintech-algorithms/statistical-time-series/forecast-models/holt-winters";
```

## Signature

```ts
forecastHoltWintersAdditive(values, alpha, beta, gamma, period, horizon, initialLevel, initialTrend, initialSeasonals)
```

Additive Holt-Winters: exponential smoothing of level, trend and seasonality. Unfashionable and frequently competitive with far more complex methods on short seasonal series.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `values` | `number[]` | yes | Observation series in chronological order, oldest first. |
| `alpha` | `number` | yes | Level smoothing factor, 0…1. · min: 0 |
| `beta` | `number` | yes | Trend smoothing factor, 0…1. · min: 0 |
| `gamma` | `number` | yes | Seasonal smoothing factor, 0…1. · min: 0 |
| `period` | `number` | yes | Seasonal period. · min: 2, integer: true |
| `horizon` | `number` | yes | Steps ahead. · min: 1, integer: true |
| `initialLevel` | `number` | yes | Starting level. |
| `initialTrend` | `number` | yes | Starting trend. |
| `initialSeasonals` | `number[]` | yes | Starting seasonal factors, one per period step. Additive factors should sum to approximately zero. |

## Returns

`{ forecast, fitted, residuals, trace, state }`

Forecasts with a `trace` of level, trend and seasonal components at each step.

## Errors

- When any smoothing factor falls outside 0…1, or initialSeasonals is not of length period — throws

## Complexity

Time `O(n)`, space `O(n)`.

## Worked example

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

### Input

`values`:

```json
[10, 12, 11, 13]
```

`alpha`:

```json
0.5
```

`beta`:

```json
0.5
```

`gamma`:

```json
0.5
```

`period`:

```json
2
```

`horizon`:

```json
2
```

`initialLevel`:

```json
9
```

`initialTrend`:

```json
1
```

`initialSeasonals`:

```json
[-1, 1]
```

### Call

```ts
forecastHoltWintersAdditive(values, alpha, beta, gamma, period, horizon, initialLevel, initialTrend, initialSeasonals)
```

### Returns

object with 1 field: forecast

```json
{
  "forecast": [12.35546875, 14.58203125]
}
```

## Verification and provenance

Tier: **verified** (via input-expected).

The worked example below is the figure published in this algorithm's article, replayed and asserted by the test suite on every build. The arithmetic cannot drift without the build failing.

Both tiers guarantee the signature. Full explanation: https://docs.thefintechbuilder.com/guides/verification/

Generated from the docs.json payload shipped inside fintech-algorithms@0.13.1.
The signature and parameter list are checked against the compiled implementation at build time,
so a description that contradicts the code fails the build rather than reaching this file.

## Links

- Article (how it works, step by step): https://thefintechbuilder.com/statistical-time-series/forecast-models/holt-winters/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/statistical-time-series/forecast-models/holt-winters/impl.ts
- Package on npm: https://www.npmjs.com/package/fintech-algorithms
- Domain index for agents: https://docs.thefintechbuilder.com/statistical-time-series/llms.txt