timesfm-forecasting — Прогнозирование временных рядов без обучения

--- 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. allowed-tools: Read Write Edit Bash license: Apache-2.0 license metadata: skill-author: Clayton Young / Superior Byte Works, LLC (@borealBytes) skill-version: "1.0.0" --- # 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] # Or using pip 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) pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cu121 # CPU only pip install torch>=2.0.0 --index-url https://download.pytorch.org/whl/cpu # Apple Silicon (MPS) 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" ) ``` ## 📊 Understanding the Output ### Quantile Forecast Structure TimesFM returns `(point_forecast, quantile_forecast)`: - **`point_forecast`**: shape `(batch, horizon)` — the median (0.5 quantile) - **`quantile_forecast`**: shape `(batch, horizon, 10)` — ten slices: | Index | Quantile | Use | | ----- | -------- | --- | | 0 | Mean | Average prediction | | 1 | 0.1 | Lower bound of 80% PI | | 2 | 0.2 | Lower bound of 60% PI | | 3 | 0.3 | — | | 4 | 0.4 | — | | **5** | **0.5** | **Median (= `point_forecast`)** | | 6 | 0.6 | — | | 7 | 0.7 | — | | 8 | 0.8 | Upper bound of 60% PI | | 9 | 0.9 | Upper bound of 80% PI | ### Extracting Prediction Intervals ```python point, q = model.forecast(horizon=H, inputs=data) # 80% prediction interval (most common) lower_80 = q[:, :, 1] # 10th percentile upper_80 = q[:, :, 9] # 90th percentile # 60% prediction interval (tighter) lower_60 = q[:, :, 2] # 20th percentile upper_60 = q[:, :, 8] # 80th percentile # Median (same as point forecast) median = q[:, :, 5] ``` ```mermaid flowchart LR accTitle: Quantile Forecast Anatomy accDescr: Diagram showing how the 10-element quantile vector maps to prediction intervals. input["📈 Input Series<br/>1-D array"] --> model["🤖 TimesFM<br/>compile + forecast"] model --> point["📍 Point Forecast<br/>(batch, horizon)"] model --> quant["📊 Quantile Forecast<br/>(batch, horizon, 10)"] quant --> pi80["80% PI<br/>q[:,:,1] – q[:,:,9]"] quant --> pi60["60% PI<br/>q[:,:,2] – q[:,:,8]"] quant --> median["Median<br/>q[:,:,5]"] classDef data fill:#dbeafe,stroke:#2563eb,stroke-width:2px,color:#1e3a5f classDef model fill:#f3e8ff,stroke:#9333ea,stroke-width:2px,color:#581c87 classDef output fill:#dcfce7,stroke:#16a34a,stroke-width:2px,color:#14532d class input data class model model class point,quant,pi80,pi60,median output ``` ## 🔧 ForecastConfig Reference All forecasting behavior is controlled by `timesfm.ForecastConfig`: ```python timesfm.ForecastConfig( max_context=1024, # Max context window (truncates longer series) max_horizon=256, # Max forecast horizon normalize_inputs=True, # Normalize inputs (RECOMMENDED for stability) per_core_batch_size=32, # Batch size per device (tune for memory) use_continuous_quantile_head=True, # Better quantile accuracy for long horizons force_flip_invariance=True, # Ensures f(-x) = -f(x) (mathematical consistency) infer_is_positive=True, # Clamp forecasts ≥ 0 when all inputs > 0 fix_quantile_crossing=True, # Ensure q10 ≤ q20 ≤ ... ≤ q90 return_backcast=False, # Return backcast (for covariate workflows) ) ``` | Parameter | Default | When to Change | | --------- | ------- | -------------- | | `max_context` | 0 | Set to match your longest historical window (e.g., 512, 1024, 4096) | | `max_horizon` | 0 | Set to your maximum forecast length | | `normalize_inputs` | False | **Always set True** — prevents scale-dependent instability | | `per_core_batch_size` | 1 | Increase for throughput; decrease if OOM | | `use_continuous_quantile_head` | False | **Set True** for calibrated prediction intervals | | `force_flip_invariance` | True | Keep True unless profiling shows it hurts | | `infer_is_positive` | True | Set False for series that can be negative (temperature, returns) | | `fix_quantile_crossing` | False | **Set True** to guarantee monotonic quantiles | ## 📋 Common Workflows ### Workflow 1: Single Series Forecast ```mermaid flowchart TD accTitle: Single Series Forecast Workflow accDescr: Step-by-step workflow for forecasting a single time series with system checking. check["1. Run check_system.py"] --> load["2. Load model<br/>from_pretrained()"] load --> compile["3. Compile with ForecastConfig"] compile --> prep["4. Prepare data<br/>pd.read_csv → np.array"] prep --> forecast["5. model.forecast()<br/>horizon=N"] forecast --> extract["6. Extract point + PI"] extract --> plot["7. Plot or export results"] classDef step fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#1f2937 class check,load,compile,prep,forecast,extract,plot step ``` ```python import torch, numpy as np, pandas as pd, timesfm # 1. System check (run once) # python scripts/check_system.py # 2-3. Load and compile 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=512, max_horizon=52, normalize_inputs=True, use_continuous_quantile_head=True, fix_quantile_crossing=True, )) # 4. Prepare data df = pd.read_csv("weekly_demand.csv", parse_dates=["week"]) values = df["demand"].values.astype(np.float32) # 5. Forecast point, quantiles = model.forecast(horizon=52, inputs=[values]) # 6. Extract prediction intervals forecast_df = pd.DataFrame({ "forecast": point[0], "lower_80": quantiles[0, :, 1], "upper_80": quantiles[0, :, 9], }) # 7. Plot import matplotlib.pyplot as plt fig, ax = plt.subplots(figsize=(12, 5)) ax.plot(values[-104:], label="Historical") x_fc = range(len(values[-104:]), len(values[-104:]) + 52) ax.plot(x_fc, forecast_df["forecast"], label="Forecast", color="tab:orange") ax.fill_between(x_fc, forecast_df["lower_80"], forecast_df["upper_80"], alpha=0.2, color="tab:orange", label="80% PI") ax.legend() ax.set_title("52-Week Demand Forecast") plt.tight_layout() plt.savefig("forecast.png", dpi=150) print("Saved forecast.png") ``` ### Workflow 2: Batch Forecasting (Many Series) ```python import pandas as pd, numpy as np # Load wide-format CSV (one column per series) df = pd.read_csv("all_stores.csv", parse_dates=["date"], index_col="date") inputs = [df[col].dropna().values.astype(np.float32) for col in df.columns] # Forecast all series at once (batched internally) point, quantiles = model.forecast(horizon=30, inputs=inputs) # Collect results results = {} for i, col in enumerate(df.columns): results[col] = { "forecast": point[i].tolist(), "lower_80": quantiles[i, :, 1].tolist(), "upper_80": quantiles[i, :, 9].tolist(), } # Export import json with open("batch_forecasts.json", "w") as f: json.dump(results, f, indent=2) print(f"Forecasted {len(results)} series → batch_forecasts.json") ``` ### Workflow 3: Evaluate Forecast Accuracy ```python import numpy as np # Hold out the last H points for evaluation H = 24 train = values[:-H] actual = values[-H:] point, quantiles = model.forecast(horizon=H, inputs=[train]) pred = point[0] # Metrics mae = np.mean(np.abs(actual - pred)) rmse = np.sqrt(np.mean((actual - pred) ** 2)) mape = np.mean(np.abs((actual - pred) / actual)) * 100 # Prediction interval coverage lower = quantiles[0, :, 1] upper = quantiles[0, :, 9] coverage = np.mean((actual >= lower) & (actual <= upper)) * 100 print(f"MAE: {mae:.2f}") print(f"RMSE: {rmse:.2f}") print(f"MAPE: {mape:.1f}%") print(f"80% PI Coverage: {coverage:.1f}% (target: 80%)") ``` ## ⚙️ Performance Tuning ### GPU Acceleration ```python import torch # Check GPU availability if torch.cuda.is_available(): print(f"GPU: {torch.cuda.get_device_name(0)}") print(f"VRAM: {torch.cuda.get_device_properties(0).total_mem / 1e9:.1f} GB") elif hasattr(torch.backends, "mps") and torch.backends.mps.is_available(): print("Apple Silicon MPS available") else: print("CPU only — inference will be slower but still works") # Always set this for Ampere+ GPUs (A100, RTX 3090, etc.) torch.set_float32_matmul_precision("high") ``` ### Batch Size Tuning ```python # Start conservative, increase until OOM # GPU with 8 GB VRAM: per_core_batch_size=64 # GPU with 16 GB VRAM: per_core_batch_size=128 # GPU with 24 GB VRAM: per_core_batch_size=256 # CPU with 8 GB RAM: per_core_batch_size=8 # CPU with 16 GB RAM: per_core_batch_size=32 # CPU with 32 GB RAM: per_core_batch_size=64 model.compile(timesfm.ForecastConfig( max_context=1024, max_horizon=256, per_core_batch_size=32, # <-- tune this normalize_inputs=True, use_continuous_quantile_head=True, fix_quantile_crossing=True, )) ``` ### Memory-Constrained Environments ```python import gc, torch # Force garbage collection before loading gc.collect() if torch.cuda.is_available(): torch.cuda.empty_cache() # Load model model = timesfm.TimesFM_2p5_200M_torch.from_pretrained( "google/timesfm-2.5-200m-pytorch" ) # Use small batch size on low-memory machines model.compile(timesfm.ForecastConfig( max_context=512, # Reduce context if needed max_horizon=128, # Reduce horizon if needed per_core_batch_size=4, # Small batches normalize_inputs=True, use_continuous_quantile_head=True, fix_quantile_crossing=True, )) # Process series in chunks to avoid OOM CHUNK = 50 all_results = [] for i in range(0, len(inputs), CHUNK): chunk = inputs[i:i+CHUNK] p, q = model.forecast(horizon=H, inputs=chunk) all_results.append((p, q)) gc.collect() # Clean up between chunks ``` ## 🔗 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](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 ## Examples Three fully-working reference examples live in `examples/`. Use them as ground truth for correct API usage and expected output shape. | Example | Directory | What It Demonstrates | When To Use It | | ------- | --------- | -------------------- | -------------- | | **Global Temperature Forecast** | `examples/global-temperature/` | Basic `model.forecast()` call, CSV -> PNG -> GIF pipeline, 36-month NOAA context | Starting point; copy-paste baseline for any univariate series | | **Anomaly Detection** | `examples/anomaly-detection/` | Two-phase detection: linear detrend + Z-score on context, quantile PI on forecast; 2-panel viz | Any task requiring outlier detection on historical + forecasted data | | **Covariates (XReg)** | `examples/covariates-forecasting/` | `forecast_with_covariates()` API (TimesFM 2.5), covariate decomposition, 2x2 shared-axis viz | Retail, energy, or any series with known exogenous drivers | ### Running the Examples ```bash # Global temperature (no TimesFM 2.5 needed) cd examples/global-temperature && python run_forecast.py && python visualize_forecast.py # Anomaly detection (uses TimesFM 1.0) cd examples/anomaly-detection && python detect_anomalies.py # Covariates (API demo -- requires TimesFM 2.5 + timesfm[xreg] for real inference) cd examples/covariates-forecasting && python demo_covariates.py ``` ### Expected Outputs | Example | Key output files | Acceptance criteria | | ------- | ---------------- | ------------------- | | global-temperature | `output/forecast_output.json`, `output/forecast_visualization.png` | `point_forecast` has 12 values; PNG shows context + forecast + PI bands | | anomaly-detection | `output/anomaly_detection.json`, `output/anomaly_detection.png` | Sep 2023 flagged CRITICAL (z >= 3.0); >= 2 forecast CRITICAL from injected anomalies | | covariates-forecasting | `output/sales_with_covariates.csv`, `output/covariates_data.png` | CSV has 108 rows (3 stores x 36 weeks); stores have **distinct** price arrays | ## Quality Checklist Run this checklist after every TimesFM task before declaring success: - [ ] **Output shape correct** -- `point_fc` shape is `(n_series, horizon)`, `quant_fc` is `(n_series, horizon, 10)` - [ ] **Quantile indices** -- index 0 = mean, 1 = q10, 2 = q20 ... 9 = q90. **NOT** 0 = q0, 1 = q10. - [ ] **Frequency flag** -- TimesFM 1.0/2.0: pass `freq=[0]` for monthly data. TimesFM 2.5: no freq flag. - [ ] **Series length** -- context must be >= 32 data points (model minimum). Warn if shorter. - [ ] **No NaN** -- `np.isnan(point_fc).any()` should be False. Check input series for gaps first. - [ ] **Visualization axes** -- if multiple panels share data, use `sharex=True`. All time axes must cover the same span. - [ ] **Binary outputs in Git LFS** -- PNG and GIF files must be tracked via `.gitattributes` (repo root already configured). - [ ] **No large datasets committed** -- any real dataset > 1 MB should be downloaded to `tempfile.mkdtemp()` and annotated in code. - [ ] **`matplotlib.use('Agg')`** -- must appear before any pyplot import when running headless. - [ ] **`infer_is_positive`** -- set `False` for temperature anomalies, financial returns, or any series that can be negative. ## Common Mistakes These bugs have appeared in this skill's examples. Learn from them: 1. **Quantile index off-by-one** -- The most common mistake. `quant_fc[..., 0]` is the **mean**, not q0. q10 = index 1, q90 = index 9. Always define named constants: `IDX_Q10, IDX_Q20, IDX_Q80, IDX_Q90 = 1, 2, 8, 9`. 2. **Variable shadowing in comprehensions** -- If you build per-series covariate dicts inside a loop, do NOT use the loop variable as the comprehension variable. Accumulate into separate `dict[str, ndarray]` outside the loop, then assign. ```python # WRONG -- outer `store_id` gets shadowed: covariates = {store_id: arr[store_id] for store_id in stores} # inside outer loop over store_id # CORRECT -- use a different name or accumulate beforehand: prices_by_store: dict[str, np.ndarray] = {} for store_id, config in stores.items(): prices_by_store[store_id] = compute_price(config) ``` 3. **Wrong CSV column name** -- The global-temperature CSV uses `anomaly_c`, not `anomaly`. Always `print(df.columns)` before accessing. 4. **`tight_layout()` warning with `sharex=True`** -- Harmless; suppress with `plt.tight_layout(rect=[0, 0, 1, 0.97])` or ignore. 5. **TimesFM 2.5 required for `forecast_with_covariates()`** -- TimesFM 1.0 does NOT have this method. Install `pip install timesfm[xreg]` and use checkpoint `google/timesfm-2.5-200m-pytorch`. 6. **Future covariates must span the full horizon** -- Dynamic covariates (price, promotions, holidays) must have values for BOTH the context AND the forecast horizon. You cannot pass context-only arrays. 7. **Anomaly thresholds must be defined once** -- Define `CRITICAL_Z = 3.0`, `WARNING_Z = 2.0` as module-level constants. Never hardcode `3` or `2` inline. 8. **Context anomaly detection uses residuals, not raw values** -- Always detrend first (`np.polyfit` linear, or seasonal decomposition), then Z-score the residuals. Raw-value Z-scores are misleading on trending data. ## Validation & Verification Use the example outputs as regression baselines. If you change forecasting logic, verify: ```bash # Anomaly detection regression check: python -c " import json d = json.load(open('examples/anomaly-detection/output/anomaly_detection.json')) ctx = d['context_summary'] assert ctx['critical'] >= 1, 'Sep 2023 must be CRITICAL' assert any(r['date'] == '2023-09' and r['severity'] == 'CRITICAL' for r in d['context_detections']), 'Sep 2023 not found' print('Anomaly detection regression: PASS')" # Covariates regression check: python -c " import pandas as pd df = pd.read_csv('examples/covariates-forecasting/output/sales_with_covariates.csv') assert len(df) == 108, f'Expected 108 rows, got {len(df)}' prices = df.groupby('store_id')['price'].mean() assert prices['store_A'] > prices['store_B'] > prices['store_C'], 'Store price ordering wrong' print('Covariates regression: PASS')" ```