Google Researchの時系列予測基盤モデルTimesFMでゼロショット予測と共変量付き予測を試してみる

Python 3.13.9
timesfm 2.0.0（GitHubリポジトリからインストール、モデルはv2.5を使用）
torch 2.11.0
numpy 2.4.4
pandas 3.0.2

$ git clone https://github.com/google-research/timesfm.git
$ cd timesfm

$ uv venv
$ source .venv/bin/activate

$ uv pip install -e ".[torch]"

$ uv pip install -e ".[flax]"

uv pip install matplotlib

import torch
import numpy as np
import matplotlib.pyplot as plt
import timesfm

# 浮動小数点演算の精度設定
torch.set_float32_matmul_precision("high")

# モデルの読み込み（Hugging Faceから自動ダウンロード）
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,         # 分位点交差の修正
    )
)

# 入力データ
linear_input = np.linspace(0, 1, 100)     # 線形トレンド
sine_input = np.sin(np.linspace(0, 20, 67))  # サイン波

# 予測の実行
point_forecast, quantile_forecast = model.forecast(
    horizon=12,  # 12ステップ先まで予測
    inputs=[linear_input, sine_input],
)

# グラフの作成（2段構成）
fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(12, 8))

for ax, data, pf, qf, title in [
    (ax1, linear_input, point_forecast[0], quantile_forecast[0], "Linear Trend"),
    (ax2, sine_input, point_forecast[1], quantile_forecast[1], "Sine Wave"),
]:
    input_x = np.arange(len(data))
    forecast_x = np.arange(len(data), len(data) + 12)

    ax.plot(input_x, data, color="#2563eb", linewidth=1.5, label="Actual")
    ax.plot(forecast_x, pf, color="#dc2626", linewidth=1.5, label="Point forecast")

    # 分位点予測の信頼区間
    ax.fill_between(forecast_x, qf[:, 0], qf[:, 8],
                    alpha=0.15, color="#dc2626", label="10-90 percentile")
    ax.fill_between(forecast_x, qf[:, 2], qf[:, 6],
                    alpha=0.25, color="#dc2626", label="30-70 percentile")

    ax.axvline(x=len(data) - 1, color="gray", linestyle="--", alpha=0.5)
    ax.set_title(title)
    ax.set_xlabel("Step")
    ax.set_ylabel("Value")
    ax.legend(loc="upper left")
    ax.grid(True, alpha=0.3)

fig.suptitle("Zero-shot Forecasting with TimesFM 2.5", fontsize=14, y=1.01)
fig.tight_layout()
fig.savefig("basic_forecast.png", dpi=150, bbox_inches="tight")

$ python basic_forecast.py
ポイント予測の形状: (12,)
分位点予測の形状: (12, 10)
ポイント予測（線形トレンド）: [1.0127583 1.0188394 1.0272744 1.0430083 1.0479412 1.059132  1.0746955
 1.0754819 1.0890975 1.1027    1.1116321 1.1225947]
ポイント予測（サイン波）: [ 0.9855352   0.97798777  0.8909132   0.72856337  0.47109857  0.1975782
 -0.1051054  -0.39542517 -0.6310076  -0.83595407 -0.9664636  -1.0037618 ]

import torch
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
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,
        force_flip_invariance=True,
        infer_is_positive=True,
        fix_quantile_crossing=True,
    )
)

# サンプルデータの作成（ランダムウォーク）
dates = pd.date_range(start="2024-01-01", periods=100, freq="D")
np.random.seed(42)
values = np.cumsum(np.random.randn(100)) + 50

df = pd.DataFrame({
    "ds": dates,
    "y": values,
})

# DataFrameからNumPy配列を取り出して予測
point_forecast, quantile_forecast = model.forecast(
    horizon=12,
    inputs=[df["y"].values],
)

# 予測結果をDataFrameにまとめる
last_date = df["ds"].max()
forecast_dates = pd.date_range(
    start=last_date + pd.Timedelta(days=1), periods=12, freq="D"
)

# グラフの作成
fig, ax = plt.subplots(figsize=(12, 5))

# 入力データ（実績） - 直近30日分を表示
display_start = 70
ax.plot(dates[display_start:], values[display_start:],
        color="#2563eb", linewidth=1.5, label="Actual")

# ポイント予測
ax.plot(forecast_dates, point_forecast[0],
        color="#dc2626", linewidth=1.5, label="Point forecast")

# 分位点予測の信頼区間
q10 = quantile_forecast[0][:, 0]
q90 = quantile_forecast[0][:, 8]
q30 = quantile_forecast[0][:, 2]
q70 = quantile_forecast[0][:, 6]

ax.fill_between(forecast_dates, q10, q90,
                alpha=0.15, color="#dc2626", label="10-90 percentile")
ax.fill_between(forecast_dates, q30, q70,
                alpha=0.25, color="#dc2626", label="30-70 percentile")

ax.axvline(x=dates[-1], color="gray", linestyle="--", alpha=0.5)
ax.set_xlabel("Date")
ax.set_ylabel("Value")
ax.set_title("Zero-shot Time Series Forecasting with TimesFM 2.5")
ax.legend(loc="upper left")
ax.grid(True, alpha=0.3)
fig.tight_layout()
fig.savefig("pandas_forecast.png", dpi=150)

$ uv pip install -e ".[xreg]"

$ uv pip install "jax>=0.9" "jaxlib>=0.9" scikit-learn

import torch
import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import timesfm

torch.set_float32_matmul_precision("high")

# UCI Bike Sharing Dataset の取得
url = "https://raw.githubusercontent.com/danwild/bike-share-prediction/master/Bike-Sharing-Dataset/day.csv"
df = pd.read_csv(url)
df["dteday"] = pd.to_datetime(df["dteday"])

# 最後30日をテスト期間として分割
horizon = 30
train_df = df.iloc[:-horizon]
test_df = df.iloc[-horizon:]
ts_data = train_df["cnt"].values.astype(float)
actual = test_df["cnt"].values

# モデルの準備
model = timesfm.TimesFM_2p5_200M_torch.from_pretrained(
    "google/timesfm-2.5-200m-pytorch"
)
model.compile(
    timesfm.ForecastConfig(
        max_context=1024,
        max_horizon=128,
        normalize_inputs=True,
        use_continuous_quantile_head=True,
        force_flip_invariance=True,
        infer_is_positive=True,
        fix_quantile_crossing=True,
        return_backcast=True,  # XReg使用時に必要
    )
)

# 通常の予測（共変量なし）
pf_normal, _ = model.forecast(horizon=horizon, inputs=[ts_data])
# return_backcast=Trueの場合、バックキャスト+予測が返るため末尾30が予測部分
pf_normal_h = pf_normal[0][-horizon:]

# 共変量付き予測（曜日 + 気温）
# 動的共変量は過去データ+予測期間分の全データを渡す
pf_xreg, _ = model.forecast_with_covariates(
    inputs=[ts_data],
    dynamic_numerical_covariates={
        "temp": [df["temp"].values.tolist()],
    },
    dynamic_categorical_covariates={
        "weekday": [df["weekday"].astype(str).tolist()],
    },
    xreg_mode="xreg + timesfm",
)

# MAE（平均絶対誤差）の計算
mae_normal = np.mean(np.abs(actual - pf_normal_h))
mae_xreg = np.mean(np.abs(actual - np.array(pf_xreg[0])))

# グラフの作成（通常予測との比較）
dates = df["dteday"].values
test_dates = test_df["dteday"].values
display_start = len(train_df) - 60

fig, ax = plt.subplots(figsize=(14, 5))
ax.plot(dates[display_start:len(train_df)],
        df["cnt"].values[display_start:len(train_df)],
        color="#2563eb", linewidth=1.5, label="Actual (train)")
ax.plot(test_dates, actual, color="#2563eb", linewidth=1.5,
        linestyle=":", label="Actual (test)")
ax.plot(test_dates, pf_normal_h, color="#10b981", linewidth=1.5,
        linestyle="--", label=f"TimesFM only (MAE={mae_normal:.0f})")
ax.plot(test_dates, pf_xreg[0], color="#dc2626", linewidth=1.5,
        label=f"TimesFM + covariates (MAE={mae_xreg:.0f})")

# 休日をハイライト
for _, row in test_df.iterrows():
    if row["workingday"] == 0:
        ax.axvspan(row["dteday"] - pd.Timedelta(hours=12),
                   row["dteday"] + pd.Timedelta(hours=12),
                   alpha=0.08, color="orange")

ax.axvline(x=dates[len(train_df) - 1], color="gray", linestyle="--", alpha=0.5)
ax.set_xlabel("Date")
ax.set_ylabel("Bike Rentals")
ax.set_title("Bike Sharing Daily Demand: TimesFM vs TimesFM + Covariates")
ax.legend(loc="upper left")
ax.grid(True, alpha=0.3)
fig.tight_layout()
fig.savefig("xreg_forecast.png", dpi=150)