# TimesFM Output Format: Understanding NumPy Arrays and DataFrame Forecasts

> Explore the TimesFM output format. Learn how forecasts are returned as NumPy arrays and DataFrame objects, detailing point and quantile forecasts for your time series analysis.

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

---

**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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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:

```python
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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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:

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

```python
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`](https://github.com/google-research/timesfm/blob/main/timesfm-forecasting/scripts/forecast_csv.py), lines 44-86) that automates CSV output:

```bash
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`](https://github.com/google-research/timesfm/blob/main/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`](https://github.com/google-research/timesfm/blob/main/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.