# SARIMA/SARIMAX

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

Full page: https://docs.thefintechbuilder.com/statistical-time-series/forecast-models/sarima-sarimax/
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 { forecastSARIMAX } from "fintech-algorithms/statistical-time-series/forecast-models/sarima-sarimax";
```

## Signature

```ts
forecastSARIMAX(values, exog, futureExog, beta, ar, ma, seasonalAr, seasonalMa, intercept, differenceOrder, seasonalDifferenceOrder, period, horizon)
```

Seasonal ARIMA with optional exogenous regressors. Future exogenous values must be supplied for the whole horizon — if you do not know them, the forecast is conditional on a guess, and that dependency is worth being explicit about.

## Parameters

| Name | Type | Required | Notes |
| --- | --- | --- | --- |
| `values` | `number[]` | yes | Observation series in chronological order, oldest first. |
| `exog` | `number[][]` | yes | In-sample exogenous regressors, one row per observation. |
| `futureExog` | `number[][]` | yes | Exogenous values over the forecast horizon. These are assumptions, not data. |
| `beta` | `number[]` | yes | Coefficients on the exogenous regressors. |
| `ar` | `number[]` | yes | Non-seasonal AR coefficients. |
| `ma` | `number[]` | yes | Non-seasonal MA coefficients. |
| `seasonalAr` | `number[]` | yes | Seasonal AR coefficients. |
| `seasonalMa` | `number[]` | yes | Seasonal MA coefficients. |
| `intercept` | `number` | yes | Constant term. |
| `differenceOrder` | `number` | yes | Non-seasonal differencing order. · min: 0, integer: true |
| `seasonalDifferenceOrder` | `number` | yes | Seasonal differencing order. · min: 0, integer: true |
| `period` | `number` | yes | Seasonal period — 12 for monthly, 4 for quarterly, 5 for trading days in a week. · min: 1, integer: true |
| `horizon` | `number` | yes | Steps ahead. · min: 1, integer: true |

## Returns

`{ forecast, fitted, residuals, state, transformed_forecast, residualized_forecast }`

The final forecast plus the transformed and residualised intermediates.

## Errors

- When futureExog is shorter than the horizon — throws

## Complexity

Time `O(n × (p + q + P + Q))`, 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
[12, 15, 18, 21, 24, 27]
```

Showing 6 of 8 elements.

`exog`:

```json
[
  [1],
  [2],
  [3]
]
```

Showing 3 of 8 elements.

`futureExog`:

```json
[
  [9],
  [10]
]
```

`beta`:

```json
[2]
```

`ar`:

```json
[0.5]
```

`ma`:

```json
[]
```

`seasonalAr`:

```json
[0.25]
```

`seasonalMa`:

```json
[]
```

`intercept`:

```json
0
```

`differenceOrder`:

```json
1
```

`seasonalDifferenceOrder`:

```json
0
```

`period`:

```json
2
```

`horizon`:

```json
2
```

### Call

```ts
forecastSARIMAX(values, exog, futureExog, beta, ar, ma, seasonalAr, seasonalMa, intercept, differenceOrder, seasonalDifferenceOrder, period, horizon)
```

### Returns

object with 1 field: forecast

```json
{
  "forecast": [35.625, 38.0625]
}
```

## 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/sarima-sarimax/
- Implementation source: https://github.com/IslamBaraka90/Fintech-Algorithms-Library/blob/main/src/statistical-time-series/forecast-models/sarima-sarimax/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