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

> Explore TimesFM XReg modes Combine covariates with foundation model forecasts Learn how xreg timesfm and timesfm xreg modes optimize forecasting accuracy

- Repository: [Google Research/timesfm](https://github.com/google-research/timesfm)
- Tags: deep-dive
- Published: 2026-04-02

---

**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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/v1/src/timesfm/xreg_lib.py) at lines 27-30, which restricts input to `"xreg + timesfm"` or `"timesfm + xreg"`.

```python
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:**

```python
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:**

```python
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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/v1/src/timesfm/timesfm_base.py)**, with user-facing documentation and usage guidance provided in **[`timesfm-forecasting/examples/covariates-forecasting/demo_covariates.py`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/timesfm_base.py).