TimesFM XReg Modes: How to Combine Covariates with Foundation Model Forecasts

TimesFM supports two XReg (exogenous regression) modes—xreg + timesfm (default) and timesfm + xreg—that determine whether covariates explain the residual variation after the base forecast or capture the primary signal with the foundation model filling in the gaps.

The google-research/timesfm repository provides a foundation model for time-series forecasting that integrates exogenous covariates through two distinct computational strategies. These TimesFM XReg modes control the order of operations between the transformer-based forecast and a linear regression component, directly impacting accuracy when external variables influence the series.

What Are the TimesFM XReg Modes?

TimesFM implements exogenous regression by combining its core forecast with a linear model processing covariates. The library exposes two modes via the xreg_mode parameter in the forecast method, each suited to different relationships between covariates and target values.

xreg + timesfm (Default Mode)

In the default xreg + timesfm mode, as implemented in v1/src/timesfm/timesfm_base.py, the system executes a three-step pipeline:

1. TimesFM generates a baseline forecast from historical time-series inputs.
2. A linear regression fits on the residuals (actual values minus the baseline forecast) using the provided covariates.
3. The final output combines the baseline forecast with the XReg adjustment.

This mode excels when covariates explain remaining variation that the foundation model misses, such as promotional spikes or holiday effects that deviate from the learned trend.

timesfm + xreg (Alternative Mode)

The alternative timesfm + xreg mode reverses the computational order:

1. A linear regression fits directly on the target values using the covariates to capture the primary signal.
2. TimesFM forecasts the residuals of this regression—the variation unexplained by the covariates.
3. The final forecast sums the XReg prediction and the TimesFM residual forecast.

According to the example script in timesfm-forecasting/examples/covariates-forecasting/demo_covariates.py, this mode performs best when covariates capture the main signal of the series, such as temperature driving energy demand, allowing the foundation model to refine only the unexplained noise.

How to Configure XReg Modes in the Forecast API

You select the mode by passing the xreg_mode string to the high-level forecast method. The literal type defining the allowed values lives in v1/src/timesfm/xreg_lib.py at lines 27-30, which restricts input to "xreg + timesfm" or "timesfm + xreg".

outputs, xregs = model.forecast(
    inputs,
    freq,
    window_size,
    forecast_context_len,
    xreg_mode="xreg + timesfm",  # or "timesfm + xreg"

    ...
)

Practical Implementation Examples

The following examples demonstrate both configurations using the TimesFM Python API. Note the use of normalize_xreg_target_per_input and ridge parameters for regularization control.

Default mode with residual adjustment:

model = TimesFM()
outputs, xregs = model.forecast(
    inputs=time_series_list,
    freq=[0, 1, 2],
    window_size=None,
    forecast_context_len=None,
    xreg_mode="xreg + timesfm",
    normalize_xreg_target_per_input=True,
    ridge=0.1,
)

Alternative mode with covariate-first signal extraction:

outputs, xregs = model.forecast(
    inputs=time_series_list,
    freq=[0, 1, 2],
    xreg_mode="timesfm + xreg",
    normalize_xreg_target_per_input=False,
)

Summary

• TimesFM provides two XReg modes that control how exogenous covariates interact with the foundation model's predictions.
• xreg + timesfm (default) fits covariates on residuals after the base forecast, ideal for promotional or holiday adjustments.
• timesfm + xreg fits covariates first on the raw targets, then forecasts residuals, optimal when covariates drive the primary trend.
• The mode is configured via the xreg_mode parameter in the forecast method, validated by the XRegMode literal type in v1/src/timesfm/xreg_lib.py.

Frequently Asked Questions

What is the default XReg mode in TimesFM?

The default mode is xreg + timesfm. In this configuration, TimesFM generates a baseline forecast first, and the XReg component adjusts this forecast by fitting a linear regression on the residuals using the provided covariates.

When should I use timesfm + xreg instead of xreg + timesfm?

Use timesfm + xreg when your covariates capture the dominant signal of the time series, such as temperature data predicting energy consumption. This mode fits the covariates directly on the targets first, allowing TimesFM to model only the remaining residual variation rather than the full trend.

Where is the XReg mode logic defined in the source code?

The allowed string literals are defined as a XRegMode type in v1/src/timesfm/xreg_lib.py (lines 27-30). The forecast method that interprets this parameter and executes the corresponding pipeline is located in v1/src/timesfm/timesfm_base.py, with user-facing documentation and usage guidance provided in timesfm-forecasting/examples/covariates-forecasting/demo_covariates.py.

Can I adjust regularization when using XReg modes?

Yes. Both modes support the ridge parameter for L2 regularization on the linear regression component and normalize_xreg_target_per_input for per-series normalization control, as documented in the forecast method signature in timesfm_base.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}