time-series-forecasting

name	time-series-forecasting
description	Forecast/predict future values of a time series, choose reasonable baselines, and compare forecasting methods on arbitrary series loaded from ts-agents data.
compatibility	Best with the ts-agents repo + CLI (`ts-agents`).
metadata	{"domain":"time-series","tasks":["forecasting","prediction","model-selection"],"ts_agents":{"tool_category":"forecasting","prefers_with_data_tools":true,"preferred_workflow":"forecast-series","preferred_tools":["detect_periodicity_with_data","forecast_seasonal_naive_with_data"],"artifact_checklist":["forecast_comparison.json","forecast.json","forecast.csv","report.md"]},"claude_code":{"allowed-tools":["Bash","Read","Write","Edit"],"disable-model-invocation":false}}

Time series forecasting

What this skill does

Given a univariate time series, produce future predictions with a workflow that is:

• baseline-first
• explicit about seasonality
• cost-aware
• easy to extend when more forecasting tools are added

If the user wants a reproducible benchmark/report workflow on the vendored M4 Monthly mini-panel, switch to SKILL-pro.md. This base skill is for arbitrary run_id + variable series, not the fixed workflow contract.

Minimal info to proceed

• A specific series (run_id + variable, or raw array in Python)
• Forecast horizon

Useful extras:

• season length / period if known
• whether the user wants quick projection vs holdout comparison
• whether the user needs prediction intervals

If the season length is unknown and seasonality matters, estimate it first.

Model selection cheat sheet

• Seasonal Naive: minimum serious baseline for seasonal data. Cheap and easy to interpret.
• Theta: strong simple baseline; often competitive. Requires the optional forecasting extra.
• ETS: good default for level/trend/seasonality. Requires the optional forecasting extra.
• ARIMA: stronger but more fragile and higher cost. Requires the optional forecasting extra.
• Ensemble: use after you have compared individual methods; advanced combinations require the optional forecasting extra.

Workflow

0) Estimate seasonality when needed

uv run ts-agents tool run detect_periodicity_with_data --run <RUN_ID> --var <VARIABLE> --param n_top=3

1) Check which methods are available in the current environment

uv run ts-agents workflow show forecast-series --json

Interpret available_methods / unavailable_methods before you choose models. In a default/base install, expect seasonal_naive to be available and theta, ets, arima to remain unavailable until the optional forecasting extra is installed.

2) Run a base-safe baseline and artifact workflow

uv run ts-agents workflow run forecast-series \
  --run-id <RUN_ID> --variable <VARIABLE> \
  --horizon 50 \
  --methods seasonal_naive \
  --season-length <PERIOD>

If you only need a quick point forecast instead of the workflow artifact set:

uv run ts-agents tool run forecast_seasonal_naive_with_data \
  --run <RUN_ID> --var <VARIABLE> \
  --param horizon=50 --param season_length=<PERIOD>

3) Expand the comparison only after confirming advanced backends are available

Notes:

• The comparison tool uses a simple historical split, not the professional rolling-origin + official holdout protocol.
• Use this when the user asks "which model looks best on this series?"
• If workflow show forecast-series --json lists theta, ets, or arima in available_methods, rerun the same workflow with those method names added to --methods.
• If those methods are listed under unavailable_methods, stay with seasonal_naive or install ts-agents[forecasting].

4) Use an ensemble only after individual comparisons

Treat ensembles as an advanced path, not a base-profile default. Only use them after individual methods are available and have been compared explicitly.

Prediction intervals

The core forecasting functions support level=[80, 95], while the *_with_data wrappers are mainly geared toward point forecasts and plots.

If you need interval-capable statistical models such as ETS, Theta, or ARIMA, install ts-agents[forecasting] and use Python directly:

from ts_agents.data_access import get_series
from ts_agents.core.forecasting import forecast_ets

y = get_series("Re200Rm200", "bx001_real")
res = forecast_ets(y, horizon=50, level=[80, 95], season_length=12)
print(res.lower_bound[:5])
print(res.upper_bound[:5])

Output expectations

Return:

• the chosen horizon
• which model(s) you ran and why
• the season length you assumed or estimated
• a short interpretation of the forecast
• if multiple models were compared: a recommendation tied to the reported metrics

Reporting standard

For stakeholder-facing outputs, produce a short Markdown or Quarto report with:

• model comparison table
• forecast figure with labeled axes
• selected method rationale
• limitations and follow-up recommendation