TimesFM Forecasting

Overview

TimesFM (Time Series Foundation Model) is a pretrained decoder-only foundation model developed by Google Research for time-series forecasting. It works zero-shot — feed it any univariate time series and it returns point forecasts with calibrated quantile prediction intervals, no training required.

This skill wraps TimesFM for safe, agent-friendly local inference. It includes a mandatory preflight system checker that verifies RAM, GPU memory, and disk space before the model is ever loaded so the agent never crashes a user's machine.

> Key numbers: TimesFM 2.5 uses 200M parameters (~800 MB on disk, ~1.5 GB in RAM on > CPU, ~1 GB VRAM on GPU). The archived v1/v2 500M-parameter model needs ~32 GB RAM. > Always run the system checker first.

When to Use This Skill

Use this skill when:

• Forecasting any univariate time series (sales, demand, sensor, vitals, price, weather)
• You need zero-shot forecasting without training a custom model
• You want probabilistic forecasts with calibrated prediction intervals (quantiles)
• You have time series of any length (the model handles 1–16,384 context points)
• You need to batch-forecast hundreds or thousands of series efficiently
• You want a foundation model approach instead of hand-tuning ARIMA/ETS parameters

Do not use this skill when:

• You need classical statistical models with coefficient interpretation → use statsmodels
• You need time series classification or clustering → use aeon
• You need multivariate vector autoregression or Granger causality → use statsmodels
• Your data is tabular (not temporal) → use scikit-learn

> Note on Anomaly Detection: TimesFM does not have built-in anomaly detection, but you can > use the quantile forecasts as prediction intervals — values outside the 90% CI (q10–q90) > are statistically unusual. See the examples/anomaly-detection/ directory for a full example.

⚠️ Mandatory Preflight: System Requirements Check

CRITICAL — ALWAYS run the system checker before loading the model for the first time.

bash
python scripts/check_system.py

This script checks:

1. Available RAM — warns if below 4 GB, blocks if below 2 GB
2. GPU availability — detects CUDA/MPS devices and VRAM
3. Disk space — verifies room for the ~800 MB model download
4. Python version — requires 3.10+
5. Existing installation — checks if timesfm and torch are installed

> Note: Model weights are NOT stored in this repository. TimesFM weights (~800 MB) > download on-demand from HuggingFace on first use and cache in ~/.cache/huggingface/. > The preflight checker ensures sufficient resources before any download begins.

mermaid
flowchart TD
    accTitle: Preflight System Check
    accDescr: Decision flowchart showing the system requirement checks that must pass before loading TimesFM.

    start["🚀 Run check_system.py"] --> ram{"RAM ≥ 4 GB?"}
    ram -->|"Yes"| gpu{"GPU available?"}
    ram -->|"No (2-4 GB)"| warn_ram["⚠️ Warning: tight RAM<br/>CPU-only, small batches"]
    ram -->|"No (< 2 GB)"| block["🛑 BLOCKED<br/>Insufficient memory"]
    warn_ram --> disk
    gpu -->|"CUDA / MPS"| vram{"VRAM ≥ 2 GB?"}
    gpu -->|"CPU only"| cpu_ok["✅ CPU mode<br/>Slower but works"]
    vram -->|"Yes"| gpu_ok["✅ GPU mode<br/>Fast inference"]
    vram -->|"No"| cpu_ok
    gpu_ok --> disk{"Disk ≥ 2 GB free?"}
    cpu_ok --> disk
    disk -->|"Yes"| ready["✅ READY<br/>Safe to load model"]
    disk -->|"No"| block_disk["🛑 BLOCKED<br/>Need space for weights"]

    classDef ok fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d
    classDef warn fill:#fef9c3,stroke:#ca8a04,stroke-width:2px,color:#713f12
    classDef block fill:#fee2e2,stroke:#dc2626,stroke-width:2px,color:#7f1d1d
    classDef neutral fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937

    class ready,gpu_ok,cpu_ok ok
    class warn_ram warn
    class block,block_disk block
    class start,ram,gpu,vram,disk neutral

Hardware Requirements by Model Version

| Model | Parameters | RAM (CPU) | VRAM (GPU) | Disk | Context | | ----- | ---------- | --------- | ---------- | ---- | ------- | | TimesFM 2.5 (recommended) | 200M | ≥ 4 GB | ≥ 2 GB | ~800 MB | up to 16,384 | | TimesFM 2.0 (archived) | 500M | ≥ 16 GB | ≥ 8 GB | ~2 GB | up to 2,048 | | TimesFM 1.0 (archived) | 200M | ≥ 8 GB | ≥ 4 GB | ~800 MB | up to 2,048 |

> Recommendation: Always use TimesFM 2.5 unless you have a specific reason to use an > older checkpoint. It is smaller, faster, and supports 8× longer context.

🔧 Installation

Step 1: Verify System (always first)

bash
python scripts/check_system.py

Step 2: Install TimesFM

bash
# Using uv (recommended by this repo)
uv pip install timesfm[torch]

# For JAX/Flax backend (faster on TPU/GPU)
uv pip install timesfm[flax]

Step 3: Install PyTorch for Your Hardware

bash
# CUDA 12.1 (NVIDIA GPU)
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121

# CPU only
uv pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cpu

# Apple Silicon (MPS)
uv pip install torch>=2.0.0  # MPS support is built-in

Step 4: Verify Installation

python
import timesfm
import numpy as np
print(f"TimesFM version: {timesfm.__version__}")
print("Installation OK")

🎯 Quick Start

Minimal Example (5 Lines)

python
import torch, numpy as np, timesfm

torch.set_float32_matmul_precision("high")

model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)
model.compile(timesfm.ForecastConfig(
    max_context=1024, max_horizon=256, normalize_inputs=True,
    use_continuous_quantile_head=True, force_flip_invariance=True,
    infer_is_positive=True, fix_quantile_crossing=True,
))

point, quantiles = model.forecast(horizon=24, inputs=[
    np.sin(np.linspace(0, 20, 200)),  # any 1-D array
])
# point.shape == (1, 24)        — median forecast
# quantiles.shape == (1, 24, 10) — 10th–90th percentile bands

Forecast from CSV

python
import pandas as pd, numpy as np

df = pd.read_csv("monthly_sales.csv", parse_dates=["date"], index_col="date")

# Convert each column to a list of arrays
inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns]

point, quantiles = model.forecast(horizon=12, inputs=inputs)

# Build a results DataFrame
for i, col in enumerate(df.columns):
    last_date = df[col].dropna().index[-1]
    future_dates = pd.date_range(last_date, periods=13, freq="MS")[1:]
    forecast_df = pd.DataFrame({
        "date": future_dates,
        "forecast": point[i],
        "lower_80": quantiles[i, :, 2],  # 20th percentile
        "upper_80": quantiles[i, :, 8],  # 80th percentile
    })
    print(f"\n--- {col} ---")
    print(forecast_df.to_string(index=False))

Forecast with Covariates (XReg)

TimesFM 2.5+ supports exogenous variables through forecast_with_covariates(). Requires timesfm[xreg].

python
# Requires: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"price": price_arrays},
    dynamic_categorical_covariates={"holiday": holiday_arrays},
    static_categorical_covariates={"region": region_labels},
    xreg_mode="xreg + timesfm",  # or "timesfm + xreg"
)

| Covariate Type | Description | Example | | -------------- | ----------- | ------- | | dynamic_numerical | Time-varying numeric | price, temperature, promotion spend | | dynamic_categorical | Time-varying categorical | holiday flag, day of week | | static_numerical | Per-series numeric | store size, account age | | static_categorical | Per-series categorical | store type, region, product category |

XReg Modes:

• "xreg + timesfm" (default): TimesFM forecasts first, then XReg adjusts residuals
• "timesfm + xreg": XReg fits first, then TimesFM forecasts residuals

> See examples/covariates-forecasting/ for a complete example with synthetic retail data.

Anomaly Detection (via Quantile Intervals)

TimesFM does not have built-in anomaly detection, but the quantile forecasts naturally provide prediction intervals that can detect anomalies:

python
point, q = model.forecast(horizon=H, inputs=[values])

# 90% prediction interval
lower_90 = q[0, :, 1]  # 10th percentile
upper_90 = q[0, :, 9]  # 90th percentile

# Detect anomalies: values outside the 90% CI
actual = test_values  # your holdout data
anomalies = (actual < lower_90) | (actual > upper_90)

# Severity levels
is_warning = (actual < q[0, :, 2]) | (actual > q[0, :, 8])  # outside 80% CI
is_critical = anomalies  # outside 90% CI

| Severity | Condition | Interpretation | | -------- | --------- | -------------- | | Normal | Inside 80% CI | Expected behavior | | Warning | Outside 80% CI | Unusual but possible | | Critical | Outside 90% CI | Statistically rare (< 10% probability) |

> See examples/anomaly-detection/ for a complete example with visualization.

python
# Requires: uv pip install timesfm[xreg]
point, quantiles = model.forecast_with_covariates(
    inputs=inputs,
    dynamic_numerical_covariates={"temperature": temp_arrays},
    dynamic_categorical_covariates={"day_of_week": dow_arrays},
    static_categorical_covariates={"region": region_labels},
    xreg_mode="xreg + timesfm",  # or "timesfm + xreg"
)

Output, Configuration, Workflows, and Tuning

• references/output_and_config.md: reading the point

forecast and the 10 quantile bands, deriving prediction intervals, and every ForecastConfig field.

• references/workflows.md: the standard forecast sequence,

many-series forecasting from a wide CSV, and backtesting with interval coverage.

• references/performance_tuning.md: GPU and TF32

setup, per_core_batch_size by available memory, and memory management.

• references/examples_and_validation.md:

runnable examples, the quality checklist, common mistakes, and regression checks.

🔗 Integration with Other Skills

With statsmodels

Use statsmodels for classical models (ARIMA, SARIMAX) as a comparison baseline:

python
# TimesFM forecast
tfm_point, tfm_q = model.forecast(horizon=H, inputs=[values])

# statsmodels ARIMA forecast
from statsmodels.tsa.arima.model import ARIMA
arima = ARIMA(values, order=(1,1,1)).fit()
arima_forecast = arima.forecast(steps=H)

# Compare
print(f"TimesFM MAE: {np.mean(np.abs(actual - tfm_point[0])):.2f}")
print(f"ARIMA MAE:   {np.mean(np.abs(actual - arima_forecast)):.2f}")

With matplotlib / scientific-visualization

Plot forecasts with prediction intervals as publication-quality figures.

With exploratory-data-analysis

Run EDA on the time series before forecasting to understand trends, seasonality, and stationarity.

📚 Available Scripts

scripts/check_system.py

Mandatory preflight checker. Run before first model load.

bash
python scripts/check_system.py

Output example:

=== TimesFM System Requirements Check ===

[RAM]       Total: 32.0 GB | Available: 24.3 GB  ✅ PASS
[GPU]       NVIDIA RTX 4090 | VRAM: 24.0 GB      ✅ PASS
[Disk]      Free: 142.5 GB                        ✅ PASS
[Python]    3.12.1                                 ✅ PASS
[timesfm]   Installed (2.5.0)                      ✅ PASS
[torch]     Installed (2.4.1+cu121)                ✅ PASS

VERDICT: ✅ System is ready for TimesFM 2.5 (GPU mode)
Recommended: per_core_batch_size=128

scripts/forecast_csv.py

End-to-end CSV forecasting with automatic system check.

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

📖 Reference Documentation

Detailed guides in references/:

| File | Contents | | ---- | -------- | | references/system_requirements.md | Hardware tiers, GPU/CPU selection, memory estimation formulas | | references/api_reference.md | Full ForecastConfig docs, from_pretrained options, output shapes | | references/data_preparation.md | Input formats, NaN handling, CSV loading, covariate setup |

Common Pitfalls

1. Not running system check → model load crashes on low-RAM machines. Always run check_system.py first.
2. Forgetting model.compile() → RuntimeError: Model is not compiled. Must call compile() before forecast().
3. Not setting normalize_inputs=True → unstable forecasts for series with large values.
4. Using v1/v2 on machines with < 32 GB RAM → use TimesFM 2.5 (200M params) instead.
5. Not setting fix_quantile_crossing=True → quantiles may not be monotonic (q10 > q50).
6. Huge per_core_batch_size on small GPU → CUDA OOM. Start small, increase.
7. Passing 2-D arrays → TimesFM expects a list of 1-D arrays, not a 2-D matrix.
8. Forgetting torch.set_float32_matmul_precision("high") → slower inference on Ampere+ GPUs.
9. Not handling NaN in output → edge cases with very short series. Always check np.isnan(point).any().
10. Using infer_is_positive=True for series that can be negative → clamps forecasts at zero. Set False for temperature, returns, etc.

Model Versions

mermaid
timeline
    accTitle: TimesFM Version History
    accDescr: Timeline of TimesFM model releases showing parameter counts and key improvements.

    section 2024
        TimesFM 1.0 : 200M params, 2K context, JAX only
        TimesFM 2.0 : 500M params, 2K context, PyTorch + JAX
    section 2025
        TimesFM 2.5 : 200M params, 16K context, quantile head, no frequency indicator

| Version | Params | Context | Quantile Head | Frequency Flag | Status | | ------- | ------ | ------- | ------------- | -------------- | ------ | | 2.5 | 200M | 16,384 | ✅ Continuous (30M) | ❌ Removed | Latest | | 2.0 | 500M | 2,048 | ✅ Fixed buckets | ✅ Required | Archived | | 1.0 | 200M | 2,048 | ✅ Fixed buckets | ✅ Required | Archived |

Hugging Face checkpoints:

• google/timesfm-2.5-200m-pytorch (recommended)
• google/timesfm-2.5-200m-flax
• google/timesfm-2.0-500m-pytorch (archived)
• google/timesfm-1.0-200m-pytorch (archived)

Resources

• Paper: A Decoder-Only Foundation Model for Time-Series Forecasting (ICML 2024)
• Repository: https://github.com/google-research/timesfm
• Hugging Face: https://huggingface.co/collections/google/timesfm-release-66e4be5fdb56e960c1e482a6
• Google Blog: https://research.google/blog/a-decoder-only-foundation-model-for-time-series-forecasting/
• BigQuery Integration: https://cloud.google.com/bigquery/docs/timesfm-model