timesfm-forecasting · diff
v2.1 to v3.0
122 added, 364 removed. Audit A to A.
---
name: timesfm-forecasting
- description: Zero-shot time series forecasting with Google's TimesFM foundation model. Use for any univariate time series (sales, sensors, energy, vitals, weather) without training a custom model. Supports CSV/DataFrame/array inputs with point forecasts and prediction intervals. Includes a preflight system checker script to verify RAM/GPU before first use.
+ description: Performs zero-shot time-series forecasting with Google's TimesFM, including regular-grid CSV preparation, quantile forecasts, XReg covariates, and held-out evaluation. Uses the Apache-licensed TimesFM 2.5 checkpoint by default and documents the distinct TimesFM 3.0 multivariate API and weight-license requirements.
allowed-tools: Read Write Edit Bash
license: Apache-2.0 license
+ compatibility: Requires Python 3.10+ and timesfm 3.0.2 with PyTorch; CSV tooling also needs NumPy and pandas. Network access and cache space are needed for initial Hugging Face checkpoint download. Optional XReg needs JAX and scikit-learn; current JAX requires Python 3.12+.
metadata:
- version: "2.1"
+ version: "3.0"
skill-author: Clayton Young / Superior Byte Works, LLC (@borealBytes)
- skill-version: 1.0.0
+ last-reviewed: "2026-10-01"
+ tested-package: "timesfm 3.0.2"
---
# TimesFM Forecasting
- ## Output-schema migration (skill 2.0)
-
- `forecast_csv.py` now exports `lower_80`/`upper_80` for q10/q90 and `lower_60`/`upper_60` for q20/q80. Earlier releases mislabeled these as 90% and 80%; migrate old outer `*_90` fields to `*_80` and old inner `*_80` fields to `*_60` simultaneously. No 90% interval is supplied by these deciles (that would require q05/q95).
-
- The archived `examples/global-temperature/` scripts and generated figures/tables have incorrect quantile indexing and coverage labels. Treat them as historical, unvalidated artifacts; do not reuse their numerical bands or visuals until regenerated and checked against the model output mapping.
-
- ## 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
- a univariate time series and it returns point forecasts and quantile estimates, with no task-specific training required. Nominal interval coverage must be checked on representative held-out data; a quantile head does not guarantee calibration.
-
- 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 quantile-based prediction intervals
- - 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** — q10–q90 is a nominal **80% prediction interval**, not a 90% confidence interval. Validate empirical coverage before interpreting exceedances as anomalies. 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 |
+ ## Choose the model/API first
- > **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.
+ The **Python package version is 3.0.2**; checkpoint versions are separate.
- ## 🔧 Installation
+ | Checkpoint | Interface | Quantile output | Usage terms |
+ | --- | --- | --- | --- |
+ | 2.5, 200M | `timesfm.TimesFM_2p5_200M_torch`, `compile`, `forecast` | mean + 9 deciles, median index 5 | Apache-2.0 weights; bundled CLI default |
+ | 3.0, about 330M | `timesfm3.TimesFM3Forecaster`, `predict` / `predict_batch` | 9 deciles, median index 4 | Downloaded weights restricted to non-commercial, non-production use |
- ### Step 1: Verify System (always first)
+ Upstream identifies 3.0 as the latest model. This skill retains 2.5 as its default
+ local workflow because its Apache-licensed weights have different usage terms.
+ For 3.0 multivariate targets, past-only covariates or Apple MLX, read
+ [references/timesfm3.md](references/timesfm3.md) before adapting code. Authorized
+ Google Cloud services have separate terms; a Cloud entitlement does not change
+ the license of downloaded weights. See the [upstream license notice](https://github.com/google-research/timesfm#license-notice-for-pretrained-weights).
- ```bash
- python scripts/check_system.py
- ```
+ Use TimesFM for forecasting an ordered temporal target without task-specific
+ model training. It is not a causal effect estimator, clinical detector, or
+ physics-based climate model. Zero-shot describes fitting; it does not establish
+ absence of benchmark overlap in pretraining or good accuracy in a new domain.
- ### Step 2: Install TimesFM
+ ## Workflow
- ```bash
- # Using uv (recommended by this repo)
- uv pip install timesfm[torch]
+ 1. Establish cadence, units, forecast origin, horizon, known-at-origin covariates,
+ evaluation cutoffs and a naive/seasonal-naive baseline.
+ 2. Validate a sorted, unique, regular time grid. Do not `dropna()` internal gaps:
+ that changes temporal spacing. Reject nonfinite inputs, or explicitly impute
+ inside each training history. Never fill using held-out future targets.
+ 3. Run `python scripts/check_system.py` before downloading/loading weights.
+ Its available-RAM and cache-volume thresholds are heuristics, not a guarantee
+ against OOM. Start with batch size 1; measure actual peak usage.
+ 4. Load the chosen checkpoint with a recorded immutable revision. For 2.5,
+ compile explicit positive context/horizon settings; zero does **not** mean
+ “use the maximum.” Keep patch-rounded context + horizon <=16,384 and horizon
+ <=1,024 when using the continuous quantile head.
+ 5. Forecast, validate shapes/finite values/quantile ordering and export the
+ forecast origin, frequency, configuration and checkpoint revision.
+ 6. Evaluate across rolling origins with preprocessing fitted independently per
+ origin. Report accuracy, interval coverage and interval width by horizon;
+ label quantile intervals **nominal** until calibrated on relevant data.
- # For JAX/Flax backend (faster on TPU/GPU)
- uv pip install timesfm[flax]
- ```
+ ## Installation
- ### Step 3: Install PyTorch for Your Hardware
+ Run in a separate environment. The commands below target the reviewed release.
+ Shell extras and version constraints must be quoted, particularly in zsh.
```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
+ uv venv .venv-timesfm
+ uv pip install --python .venv-timesfm/bin/python "timesfm[torch]==3.0.2" numpy pandas
+ .venv-timesfm/bin/python scripts/check_system.py
```
- ### Step 4: Verify Installation
+ Use the current [PyTorch installation selector](https://pytorch.org/get-started/locally/)
+ for a CUDA wheel matching the host. The 2.5 loader in this release chooses
+ `cuda:0` if CUDA exists, otherwise CPU; detecting MPS does **not** enable MPS
+ inference. Do not use `model.to(...)` on the wrapper as if it were an `nn.Module`.
+ For CPU-only XReg, install `jax` and `scikit-learn` alongside the PyTorch profile;
+ the upstream `[xreg]` extra requests `jax[cuda]`, which is not appropriate for macOS.
+ Flax is a separate optional backend; it is not required by the bundled scripts.
```python
+ from importlib.metadata import version
import timesfm
- import numpy as np
- print(f"TimesFM version: {timesfm.__version__}")
- print("Installation OK")
+ print(version("timesfm")) # package has no guaranteed timesfm.__version__
+ assert hasattr(timesfm, "TimesFM_2p5_200M_torch")
```
- ## 🎯 Quick Start
-
- The model-call examples below are illustrative; no checkpoint inference was rerun for this documentation correction.
+ ## TimesFM 2.5 quick start
- ### Minimal Example (5 Lines)
+ The checkpoint-load examples are illustrative: validation of this refresh used
+ native package code with tiny random models and controlled decode fixtures,
+ without downloading pretrained weights. That verifies mechanics, not accuracy.
```python
- import torch, numpy as np, timesfm
-
- torch.set_float32_matmul_precision("high")
+ import numpy as np
+ import timesfm
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
- "google/timesfm-2.5-200m-pytorch"
+ "google/timesfm-2.5-200m-pytorch",
+ revision="1d952420fba87f3c6dee4f240de0f1a0fbc790e3",
+ torch_compile=False, # avoid compilation startup during an initial smoke run
)
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,
+ max_context=512, max_horizon=128, per_core_batch_size=1,
+ normalize_inputs=True, use_continuous_quantile_head=True,
+ force_flip_invariance=True, infer_is_positive=False,
+ 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) — mean, then q10 through q90
- ```
-
- ### 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, :, 1], # 10th percentile
- "upper_80": quantiles[i, :, 9], # 90th 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])
-
- # Nominal 80% prediction interval
- lower_80 = q[0, :, 1] # 10th percentile
- upper_80 = q[0, :, 9] # 90th percentile
-
- actual = test_values # your holdout data
- anomalies = (actual < lower_80) | (actual > upper_80)
-
- # Mutually exclusive screening levels; thresholds require application validation
- is_critical = anomalies # outside nominal 80% PI
- is_warning = ((actual < q[0, :, 2]) | (actual > q[0, :, 8])) & ~is_critical
- ```
-
- | Severity | Condition | Interpretation |
- | -------- | --------- | -------------- |
- | **Normal** | Inside nominal 60% PI (q20–q80) | Within the inner screening band |
- | **Warning** | Outside 60% PI but inside 80% PI | Between screening bands |
- | **Critical** | Outside nominal 80% PI (q10–q90) | Exceedance; not a calibrated anomaly 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](references/output_and_config.md): reading the point
- forecast and the 10 quantile bands, deriving prediction intervals, and every
- `ForecastConfig` field.
- - [references/workflows.md](references/workflows.md): the standard forecast sequence,
- many-series forecasting from a wide CSV, and backtesting with interval coverage.
- - [references/performance_tuning.md](references/performance_tuning.md): GPU and TF32
- setup, `per_core_batch_size` by available memory, and memory management.
- - [references/examples_and_validation.md](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
+ histories = [np.sin(np.linspace(0, 20, 200)).astype(np.float32)]
+ # 2.5 may append dummy series to its input list during batching; pass a fresh list.
+ point, q = model.forecast(horizon=24, inputs=list(histories))
+ assert point.shape == (1, 24) and q.shape == (1, 24, 10)
+ assert np.isfinite(q).all() and np.all(np.diff(q[..., 1:], axis=-1) >= 0)
+ assert np.allclose(point, q[..., 5])
+ lower_80, upper_80 = q[..., 1], q[..., 9] # q10-q90: nominal 80% PI
+ lower_60, upper_60 = q[..., 2], q[..., 8] # q20-q80: nominal 60% PI
```
- ### `scripts/forecast_csv.py`
+ Set `infer_is_positive=True` only for a target domain that is truly nonnegative.
+ A positive observed window does not establish that temperature anomalies,
+ returns or residuals cannot become negative. Monotonic quantiles and a
+ continuous quantile head do not establish interval calibration.
- End-to-end CSV forecasting with automatic system check.
+ ## CSV helper
```bash
- python scripts/forecast_csv.py input.csv \
- --horizon 24 \
- --date-col date \
- --value-cols sales,revenue \
- --output forecasts.csv
+ python scripts/forecast_csv.py monthly_sales.csv \
+ --date-col date --freq MS --value-cols sales,revenue \
+ --horizon 12 --batch-size 1 --nonnegative --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
+ `forecast_csv.py` validates before loading, sorts dates, rejects duplicate
+ headers/dates, checks the complete regular grid and preserves missing positions.
+ Missing values fail by default; `--missing interpolate` fills only internal gaps,
+ never leading/trailing values. Without `--date-col`, row order is assumed to be
+ the regular grid and output uses steps. Numeric IDs must be excluded using
+ `--value-cols`. `--max-context` controls history truncation; `--horizon` is limited
+ to 1..1,024 for this quantile-head workflow.
- ```mermaid
- timeline
- accTitle: TimesFM Version History
- accDescr: Timeline of TimesFM model releases showing parameter counts and key improvements.
+ Outputs retain `forecast`, `median`, `lower_80`, `upper_80`, `lower_60`, `upper_60`.
+ A `.metadata.json` sidecar records origin, cadence, model revision and config.
+ Old skill releases mislabeled q10-q90/q20-q80 as 90%/80%; migrate old outer
+ `*_90` to `*_80` and old inner `*_80` to `*_60` simultaneously. Old generated
+ example forecasts were removed because their mapping/provenance was invalid.
- 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
- ```
+ ## Covariates and anomaly screening
- | 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 |
+ For 2.5 XReg, compile `return_backcast=True`, retain targets and covariates on
+ identical grids and provide dynamic covariates over context **and** horizon.
+ `"xreg + timesfm"` fits regression on targets, then forecasts regression residuals.
+ `"timesfm + xreg"` forecasts first, then fits regression on backcast residuals.
+ The latter needs more than one input patch (32 observations). In package 3.0.2,
+ the implementation returns **lists of combined point and quantile forecasts**;
+ an inherited docstring incorrectly describes the second return as XReg-only.
+ See [references/api_reference.md](references/api_reference.md) for the complete call.
- **Hugging Face checkpoints:**
+ Quantile exceedances may screen for unusual observations, but even calibrated
+ 80% intervals exclude about 20% of ordinary observations marginally. They do
+ not supply anomaly probabilities, familywise control or validated alarm severity.
+ Retrospective detrended Z scores also differ from prospective anomaly detection.
- - `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)
+ ## References and examples
- ## Resources
+ - [API reference](references/api_reference.md): 2.5 loader, compile, forecast and XReg contracts.
+ - [Output/config](references/output_and_config.md): all real ForecastConfig fields and interval indexing.
+ - [Data preparation](references/data_preparation.md): grid, missingness, covariate timing and format recipes.
+ - [Workflows](references/workflows.md): held-out and rolling-origin validation, baseline comparisons.
+ - [System requirements](references/system_requirements.md): resource checks and backend requirements.
+ - [Performance tuning](references/performance_tuning.md): measured batch/context tuning.
+ - [Examples and validation](references/examples_and_validation.md): example commands and testing scope.
+ - [TimesFM 3.0](references/timesfm3.md): multivariate API, 9-decile layout and usage boundary.
- - **Paper**: [A Decoder-Only Foundation Model for Time-Series Forecasting](https://arxiv.org/abs/2310.10688) (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
+ Primary review sources: [official source](https://github.com/google-research/timesfm),
+ [3.0.2 distribution](https://pypi.org/project/timesfm/3.0.2/),
+ [2.5 model card](https://huggingface.co/google/timesfm-2.5-200m-pytorch),
+ [3.0 model card](https://huggingface.co/google/timesfm-3.0-pytorch).