Using Exogenous Features (Covariates)

This guide shows you how to incorporate exogenous features (covariates, often denoted $X$) into your time series model to improve forecast accuracy. Use this when you have external data that influences the target series and is known for both the historical period and the forecast horizon.

Prerequisites

Chronax installed and imported.
y (target series) is a 1-D jnp.ndarray of shape (N,), float32.
X (exogenous features) is a 2-D jnp.ndarray of shape (N + h, D), where $N$ is the history length, $h$ is the forecast horizon, and $D$ is the number of features. X must span both the historical period and the future forecast horizon.

import jax.numpy as jnp
from chronax.models import AutoARIMA

Steps

1. Prepare the target series and the full covariate matrix

Define your historical target series (y) and the full covariate matrix (X_full). The length of X_full must equal the length of y plus the desired forecast horizon (h).

# Define history length (N), forecast horizon (h), and number of features (D)
N = 100
h = 10
D = 2

# Target series (history only)
y = jnp.linspace(10, 20, N, dtype=jnp.float32)

# Full covariate matrix (history + future)
# X_full must have N + h rows
X_full = jnp.arange(N + h * D, dtype=jnp.float32).reshape(N + h, D)

2. Initialize the model

Initialize the model you wish to use. Most Chronax models that support exogenous features accept them via the X argument in the fit or forecast methods.

model = AutoARIMA()

3. Generate the forecast using the full covariate matrix

Use the model.forecast() method, passing the historical target series (y), the forecast horizon (h), and the full covariate matrix (X_full) via the X argument. Chronax automatically splits X_full into past_covariates (aligned with y) and future_covariates (aligned with h).

out = model.forecast(y, h, X=X_full)

# The forecast mean is stored in the 'mean' key
forecast_mean = out["mean"]

print(f"Forecast shape: {forecast_mean.shape}")
# Expected output: Forecast shape: (10,)

Full example

This example demonstrates preparing the data, initializing the model, and generating a forecast using exogenous features.

import jax.numpy as jnp
from chronax.models import AutoARIMA

# 1. Prepare the target series and the full covariate matrix
N = 100  # History length
h = 10   # Forecast horizon
D = 2    # Number of features

# Target series (history only)
y = jnp.linspace(10, 20, N, dtype=jnp.float32)

# Full covariate matrix (history + future: N + h rows)
X_full = jnp.arange(N + h * D, dtype=jnp.float32).reshape(N + h, D)

# 2. Initialize the model
model = AutoARIMA()

# 3. Generate the forecast using the full covariate matrix
out = model.forecast(y, h, X=X_full)

forecast_mean = out["mean"]

print(f"Input history length (N): {N}")
print(f"Forecast horizon (h): {h}")
print(f"Full X shape: {X_full.shape}")
print(f"Forecast mean shape: {forecast_mean.shape}")

Next steps

See the guide on "Forecasting a univariate series" if you do not require X.
Learn how to "Add prediction intervals" using the level argument in forecast.
Explore the chronax.models.AutoARIMA documentation for specific model parameters.
Understand the model.fit and model.predict workflow for sequential forecasting.