TimesFM Output Format: Understanding NumPy Arrays and DataFrame Forecasts

TimesFM returns forecasts as two NumPy arrays—point_forecast with shape (N, H) and quantile_forecast with shape (N, H, 1+Q)—where N is the number of series, H is the horizon, and Q is the number of quantiles, with an optional DataFrame interface available via forecast_on_df.

The TimesFM (Time Series Foundation Model) from Google Research provides probabilistic forecasts through a standardized output structure. Whether you use the base API for raw tensor operations or the high-level DataFrame interface, understanding the exact TimesFM output format is critical for integrating predictions into downstream pipelines. The model returns both point estimates and full predictive distributions, implemented in the TimesFmBase class within the repository's core module.

Core Output Structure

The forecast() Method Return Values

According to the source code in v1/src/timesfm/timesfm_base.py (lines 78-124), the TimesFmBase.forecast method always returns a tuple containing two NumPy arrays:

• point_forecast: A 2D array with shape (N, H) containing point predictions for N input series and H forecast steps ahead. The point value represents either the model's mean output (when point_forecast_mode="mean") or the median quantile (when point_forecast_mode="median").

• quantile_forecast: A 3D array with shape (N, H, 1+Q) representing the full predictive distribution. The first channel ([..., 0]) contains the mean prediction, while the remaining Q channels correspond to the quantiles configured in the model's hparams.quantiles (defaulting to 0.1, 0.2, … 0.9).

Array Shapes and Dimensions

The dimensional structure follows strict conventions based on the batch size and horizon length. For example, in the global temperature forecasting example (timesfm-forecasting/examples/global-temperature/run_forecast.py, lines 101-108), processing two time series with a 12-step horizon and the default nine quantiles produces:

point_forecast.shape      # (2, 12)

quantile_forecast.shape   # (2, 12, 10)  # 9 quantiles + mean channel

The backend-specific _forecast implementation in src/timesfm/timesfm_2p5/timesfm_2p5_base.py generates the raw (N, H, 1+Q) tensor before the base class handles post-processing and median extraction.

DataFrame Convenience Interface

Using forecast_on_df for Tabular Output

For users requiring pandas integration, the forecast_on_df method (implemented in v1/src/timesfm/timesfm_base.py, lines 271-332) wraps the NumPy output into a structured DataFrame. This interface constructs a future-dated dataframe where:

• The point forecast appears in a column named after the model (e.g., TimesFM). When the median quantile is present, this column is populated with median values rather than the mean.
• Each quantile receives its own column following the pattern model-q-<quantile> (e.g., TimesFM-q-0.1, TimesFM-q-0.5).
• The dataframe includes automatically generated future timestamps based on the input frequency.

This abstraction eliminates manual array manipulation while preserving access to the full predictive distribution.

Practical Code Examples

Direct NumPy Output

The most flexible approach accesses raw arrays directly through the forecast method:

import numpy as np
import timesfm

# Load pretrained TimesFM-2.5 checkpoint

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)

# Configure with median point forecast mode

model.compile(
    timesfm.ForecastConfig(
        max_context=1024,
        max_horizon=256,
        normalize_inputs=True,
        use_continuous_quantile_head=True,
        point_forecast_mode="median",
    )
)

# Prepare input series

series_a = np.linspace(0, 1, 100).astype(np.float32)
series_b = np.sin(np.linspace(0, 20, 67)).astype(np.float32)

# Generate forecasts

point_pred, quantile_pred = model.forecast(
    horizon=12, 
    inputs=[series_a, series_b]
)

print(f"Point shape: {point_pred.shape}")      # (2, 12)

print(f"Quantile shape: {quantile_pred.shape}")  # (2, 12, 10)

DataFrame Output with forecast_on_df

For tabular analysis and reporting, use the DataFrame interface:

import pandas as pd

# Create sample data

df = pd.DataFrame({
    "unique_id": ["ts1"] * 100,
    "ds": pd.date_range(start="2020-01-01", periods=100, freq="MS"),
    "value": np.random.randn(100).astype(np.float32)
})

# Generate forecast DataFrame

fcst_df = model.forecast_on_df(
    inputs=df,
    freq="MS",
    value_name="value",
    model_name="TimesFM",
    horizon=12
)

print(fcst_df.head())

The resulting dataframe contains columns: unique_id, ds, TimesFM, TimesFM-q-0.1, through TimesFM-q-0.9, with the point forecast column (TimesFM) reflecting the median values when configured appropriately.

Command-Line CSV Export

The repository includes a script (timesfm-forecasting/scripts/forecast_csv.py, lines 44-86) that automates CSV output:

python timesfm-forecasting/scripts/forecast_csv.py \
    my_data.csv --horizon 24 --date-col date --value-cols sales,revenue \
    --output forecasts.csv

This CLI tool calls model.forecast internally, then expands the NumPy results into the standard CSV format with the same column layout as the DataFrame interface.

Summary

• TimesFM output format consists of two NumPy arrays: point_forecast with shape (N, H) and quantile_forecast with shape (N, H, 1+Q).
• The quantile_forecast array stores the mean in the first channel and quantile values in subsequent channels, with defaults ranging from 0.1 to 0.9.
• Point forecasts can represent either the mean or median depending on the point_forecast_mode configuration in ForecastConfig.
• The forecast_on_df method in v1/src/timesfm/timesfm_base.py provides a convenient pandas interface with standardized column naming conventions.
• All output formatting logic resides in TimesFmBase.forecast and forecast_on_df, with backend-specific implementations producing the initial tensors.

Frequently Asked Questions

What is the exact shape of TimesFM quantile forecasts?

The quantile_forecast array returns with shape (N, H, 1+Q), where N is the number of input series, H is the forecast horizon, and Q is the number of configured quantiles. The first slice ([..., 0]) always contains the mean prediction, while indices 1 through Q contain the quantile values (typically 0.1 through 0.9 by default).

How do I get DataFrame output instead of NumPy arrays?

Use the forecast_on_df method available in TimesFmBase (defined in v1/src/timesfm/timesfm_base.py lines 271-332). This method accepts a pandas DataFrame with unique_id, ds, and value columns, then returns a forecast DataFrame with point predictions and quantile columns named according to the model_name parameter you specify.

What is the difference between mean and median point forecasts in TimesFM?

The point_forecast array contains the mean prediction when point_forecast_mode="mean" (default) or the median quantile when point_forecast_mode="median". The median is extracted from the quantile distribution during post-processing in the forecast method, specifically from the channel corresponding to quantile 0.5 if present in the model configuration.

Can I customize which quantiles TimesFM returns?

Quantiles are configured through the model's hparams.quantiles parameter during initialization or compilation. While the default configuration includes nine quantiles (0.1 through 0.9), the exact quantiles available depend on the checkpoint and configuration used when calling model.compile() with the appropriate ForecastConfig settings.

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