timesfm-forecasting

name	timesfm-forecasting
description	Zero-shot time series forecasting with Google's TimesFM foundation model. Use this skill when forecasting ANY univariate time series — sales, sensor readings, stock prices, energy demand, patient vitals, weather, or scientific measurements — without training a custom model. Supports both basic forecasting and advanced covariate forecasting (XReg) with dynamic and static exogenous variables. Automatically checks system RAM/GPU before loading the model, validates dataset fit before processing, supports CSV/DataFrame/array inputs, and returns point forecasts with calibrated prediction intervals. Includes a preflight system checker script that MUST be run before first use to verify the machine can load the model and handle your specific dataset.
license	Apache-2.0
metadata	{"author":"Clayton Young (@borealBytes)","version":"1.0.0"}

TimesFM Forecasting

TimesFM is a zero-shot time-series foundation model for univariate forecasting. Use it for sales, demand, sensors, vitals, prices, weather, and other temporal numeric series when you need point forecasts plus calibrated quantile intervals without training a custom model.

When to Use This Skill

Use when you need:

• zero-shot forecasting for one or many univariate series
• probabilistic forecasts with prediction intervals
• batch forecasting across many related series
• covariate forecasting with exogenous variables via TimesFM 2.5 + timesfm[xreg]
• anomaly screening by comparing actuals against forecast quantile bands

Do not use when the task needs coefficient interpretation, time-series classification/clustering, multivariate VAR/Granger causality, generic tabular ML, or unavailable optional XReg dependencies.

Mandatory Safety Preflight

Always run the system checker before first model load:

python scripts/check_system.py

For dataset sizing, run the checker with --num-series, --context-length, --horizon, and --batch-size. Model weights are not stored here; they download on demand from Hugging Face.

Read references/operational-guide.md for the full RAM/GPU/disk decision tree, dataset memory formula, hardware table, install commands, examples, and validation checks.

Minimum Operating Pattern

1. Run scripts/check_system.py and confirm RAM, disk, Python, and model dependency readiness.
2. Prepare numeric, ordered, one-dimensional arrays; handle missing values intentionally.
3. Use TimesFM 2.5 unless the task explicitly requires an older checkpoint.
4. Compile with ForecastConfig before calling forecast().
5. Set normalize_inputs=True, use_continuous_quantile_head=True, and fix_quantile_crossing=True unless you have a reason not to.
6. Set infer_is_positive=False for temperatures, returns, PnL, or any negative-capable series.
7. Validate output shape, NaNs, quantile indices, and forecast reasonableness before reporting.

Minimal Example

import numpy as np
import torch
import 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,
    fix_quantile_crossing=True,
))

point, quantiles = model.forecast(
    horizon=24,
    inputs=[np.sin(np.linspace(0, 20, 200))],
)

Output Rules

TimesFM returns (point_forecast, quantile_forecast):

• point_forecast: (batch, horizon) median forecast.
• quantile_forecast: (batch, horizon, 10) with mean at index 0, q10 at index 1, median at index 5, and q90 at index 9.
• Values outside q10-q90 are unusual; use this carefully for anomaly screening.

References

• references/operational-guide.md — full preflight, install, examples, workflows, tuning, scripts, quality checks, mistakes, and validation snippets.
• references/system_requirements.md — hardware tiers, GPU/CPU selection, and memory estimation.
• references/api_reference.md — full model classes, ForecastConfig, output shapes, and model checkpoints.
• references/data_preparation.md — input formats, NaN handling, CSV loading, and covariate setup.

Quality Checklist

Before declaring success:

• output shapes match (n_series, horizon) and (n_series, horizon, 10)
• quantile indices are interpreted correctly
• context has at least 32 points
• forecasts contain no NaN values
• TimesFM 1.0/2.0 frequency flags are only used for those older versions
• headless plots set matplotlib.use("Agg") before pyplot import
• validation command output or saved artifacts are inspected