K-Dense-AI/scientific-agent-skills / skills/timesfm-forecasting
timesfm-forecasting
VerifiedPerforms 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.
references/api_reference.md
View on GitHub# TimesFM 2.5 API in package 3.0.2
Reviewed 2026-10-01 against the released wheel and identical official source at
[commit e51928e](https://github.com/google-research/timesfm/tree/e51928e27119cb17bebc005be2696b75e0a9e688/src/timesfm).
This profile is separate from the `timesfm3` namespace.
## Loader
```python
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
"google/timesfm-2.5-200m-pytorch", # or a local safetensors directory
revision="1d952420fba87f3c6dee4f240de0f1a0fbc790e3",
cache_dir=None,
force_download=False,
local_files_only=False,
torch_compile=False,
)
```
The public method is inherited from `PyTorchModelHubMixin`; `revision`, `cache_dir`,
`force_download`, `local_files_only` and `token` are Hub arguments. Never print tokens.
The checkpoint uses `model.safetensors`; the old claim that it requires
`torch_model.ckpt` came from using the incompatible v1 loader. Loader default
`torch_compile=True` is distinct from the mandatory `model.compile(ForecastConfig)`.
The wrapper has no documented device parameter: the inner module chooses CUDA:0
if available, otherwise CPU. Public weights need no account token for normal
public downloads. Hub failures, permissions and local cache misses still propagate.
## Compile and forecast
`compile(forecast_config, **kwargs)` constructs a decode callable. Context is
rounded up to a multiple of 32; horizon to a multiple of 128. Use positive explicit
values, ideally already rounded: zero is not a sentinel for the model maximum.
Rounded context + horizon cannot exceed 16,384. The continuous quantile head
rejects rounded horizons over 1,024. Invalid configurations can raise `ValueError`.
`forecast(horizon: int, inputs: list[np.ndarray])` needs compilation first. With
`return_backcast=False`, output is `(point, q)`, shapes `(B,H)` and `(B,H,10)`.
Point equals `q[...,5]`; `q[...,0]` is the separately trained mean output, not a
decile. With `return_backcast=True`, outputs prepend a backcast of length
`max_context - 32` (including padded context positions). Slice the last H for
future-only results; a backcast is not a held-out accuracy measurement.
The implementation copies each array, strips leading NaNs and uses `np.interp`
for other NaNs (including last-value extension at the trailing edge). All-NaN
and empty inputs are not a reliable scientific input contract: validate and
reject them yourself. Internal gaps must retain positions, and interpolation
must never span a train/test cutoff. The batching implementation appends padding
series to the supplied list; pass `list(histories)` if retaining it for reuse.
## XReg
Native CPU regression requires JAX and scikit-learn, even with the torch backend.
On CPU/macOS use `uv pip install jax scikit-learn`; upstream `timesfm[xreg]`
requests CUDA JAX. Current JAX 0.11.2 requires Python >=3.12.
Illustrative checkpoint example (shape/return behavior tested without weights):
```python
import numpy as np
import timesfm
# model is the loaded 2.5 wrapper, histories is an ordered list of target arrays.
H = 12
model.compile(timesfm.ForecastConfig(
max_context=512, max_horizon=128, per_core_batch_size=1,
normalize_inputs=True, use_continuous_quantile_head=True,
infer_is_positive=False, fix_quantile_crossing=True, return_backcast=True,
))
# Prices and holiday schedules must be known at this forecast origin.
# Each dynamic array i has len(histories[i]) + H entries.
point_list, quantile_list = model.forecast_with_covariates(
inputs=list(histories),
dynamic_numerical_covariates={"price": price_arrays},
dynamic_categorical_covariates={"holiday": holiday_arrays},
static_numerical_covariates={"floor_area": store_areas},
static_categorical_covariates={"region": region_labels},
xreg_mode="xreg + timesfm",
normalize_xreg_target_per_input=True,
ridge=1.0, max_rows_per_col=0, force_on_cpu=True,
)
assert len(point_list) == len(histories)
assert quantile_list[0].shape == (H, 10)
```
| Argument | Contract |
| --- | --- |
| `inputs` | One finite target context per series; keep its exact origin/length |
| `dynamic_numerical_covariates` | Name -> list of numeric context+future arrays |
| `dynamic_categorical_covariates` | Name -> list of context+future categories; int or string |
| `static_numerical_covariates` | Name -> one numeric value per series |
| `static_categorical_covariates` | Name -> one category per series |
| `xreg_mode` | `"xreg + timesfm"` (default) or `"timesfm + xreg"` |
| `normalize_xreg_target_per_input` | Default True; target scaling per series |
| `ridge` | Default 0.0; positive values regularize the pooled regression |
| `max_rows_per_col` | Default 0; positive value may subsample regression rows |
| `force_on_cpu` | Default False; controls regression device, not TimesFM device |
Both modes require `return_backcast=True`. `xreg + timesfm` fits regression
on target contexts then TimesFM on residuals. `timesfm + xreg` obtains backcasts
then fits their residuals; require context >32 and avoid contexts longer than
the compiled context in that mode so residual lengths remain aligned.
Horizon is inferred from the first dynamic covariate's length minus context;
all features must agree. With only static covariates it uses the **compiled,
patch-rounded** max_horizon, so do not assume the unrounded requested value.
The 3.0.2 implementation returns `(list[point array], list[quantile array])`,
**not** `(combined forecast, regression forecast)` despite its stale docstring.
Validate shapes, finiteness and ordered deciles after the regression shift.
Future realized weather/prices are leakage unless those values were known at
origin. Covariate scenarios condition the prediction; their own uncertainty and
regression estimation uncertainty are not automatically covered by model bands.
## Other checkpoints
The supported Flax class is `timesfm.TimesFM_2p5_200M_flax` with
`google/timesfm-2.5-200m-flax`. This refresh did not execute Flax/TPU/CUDA.
Legacy 1.0/2.0 use package 1.3.0 and a different `TimesFmHparams` API; they are
not drop-in checkpoint IDs for these helpers. Transformers and MLX adapters
also have separate configurations and outputs; do not transplant indices blindly.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| deprecation-and-migrationaddyosmani/agent-skillsManages deprecation and migration. Use when removing old systems, APIs, or features. Use when migrating users from one implementation to another. Use when migrating a database schema in production, such as renaming or dropping a column without downtime (expand/contract). Use when deciding whether to maintain or sunset existing code. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| performance-optimizationaddyosmani/agent-skillsOptimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| agent-cost-reportthedotmack/claude-memBelievable agent cost report for any period, default the last 7 full days PT, not counting today. Measured tokens from Claude Code transcripts priced at OpenRouter list prices (ESTIMATED), measured provider spend when a sanctioned source exists, note-taker cost separate, Timing-style HTML/PDF plus report.json, line-items.csv, evidence.json. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |