【入門編】TimesFM-3の入力設計｜target・共変量・多変量予測の違いを解説

TimesFM-3で予測を始めるとき、最初につまずきやすいのはモデルの呼び出し方よりも、「手元の各列をどの入力として渡すか」です。

本記事では、テトゥアン市の電力消費データを例に、TimesFM-3の入力設計に必要な用語と判断基準を整理します。

この記事を読むと、次の点を判断できるようになります。

• 何をtargetとし、何を共変量とするか
• past-only covariateとpast-future covariateをどう区別するか
• 単変量予測と多変量予測では何が異なるか
• 静的共変量を現行APIでどう扱うか

TimesFM-3の入力設計に必要な用語と判断基準を知りたい読者を想定しています。

まず押さえる時系列予測の5つの用語

2017年2月1日0時を予測開始時刻とし、直前30日間のデータから次の24時間を予測する場面を考えます。
この設定に必要な用語は5つです。

contextとhorizonの境界は、「予測を作成する時点」です。

境界より左側では観測済みの値を使えますが、右側ではその時点で本当に入手できる情報しか使えません。

ここまでが、モデルに依存しない時系列予測の基礎用語です。

TimesFM-3では多変量と共変量を区別する

TimesFM-3は、Google Researchが公開した330Mパラメータの学習済み時系列モデルです。

新しいデータで追加学習をしなくても予測できるゼロショット予測に加え、複数のtargetを同時に扱う多変量予測と、共変量を使った予測に対応しています。

ライセンス上の注意
2026年10月時点で、TimesFM-3の公式モデルウェイトは、非商用・非本番用途を対象とする「TimesFM Non-Commercial License v1.0」で公開されています。
業務利用、商用サービス、本番環境での利用を検討する場合は、事前に公式ライセンスの最新条件を確認してください。

ここで重要なのは、「多変量」と「共変量」は同じ意味ではないことです。

• 多変量(multivariate)：予測したい系列targetが複数あること
• 共変量(covariate)：targetの予測を補助する入力のこと

具体例での違い

• 多変量（複数target）の例：
  Zone 1、Zone 2、Zone 3の電力消費をすべて同時に予測したい場合、これら3地域は3本のtargetとして扱います。
• 共変量（補助入力）の例：
  気温は予測せず、あくまで電力消費の予測を助ける情報として使うなら、気温は共変量です。

この区別が曖昧なままでは、配列を作れても、意図した予測問題にはなりません。

TimesFM-3の3種類の入力を区別する

TimesFM-3へ渡す時系列は、役割と利用できる時間範囲によって次の3種類に分かれます。

ダミー配列とDataFrame変換でshapeを確認する

最初に、ダミー配列でshapeだけを確認します。
値をすべて0にしているのは、ここでは配列の向きと長さだけを見るためです。

import numpy as np

target = np.zeros((3, 720), dtype=np.float32)
past_only = np.zeros((5, 720), dtype=np.float32)
past_future = np.zeros((5, 720 + 24), dtype=np.float32)

print(target.shape)       # (3, 720)
print(past_only.shape)    # (5, 720)
print(past_future.shape)  # (5, 744)

1つ目の軸は「系列数」、2つ目の軸は「時間」です。

本記事では、past-future covariateとして、時刻を表すhour_sin・hour_cos 、曜日を表すweekday_sin・weekday_cos、週末かどうかを表すis_weekendの5系列を使用します。時刻と曜日は周期的に繰り返す情報であるため、それぞれsinとcosの2系列で表現します。

これらは未来の日時から事前に計算できるため、past-futureだけはcontext 720時間とhorizon 24時間を合わせた744時点を入力します。（5行目のコードに注目！）

実務では、720行を持つDataFrameから対象列を選び、NumPy配列へ変換して転置します。
テトゥアン市データのtargetなら、次のコードです。

#（前提）元の表からcontext区間である直近720行を切り出したデータとする
#（前提）元の10分間隔データを1時間間隔へ集計済みであり、720行が30日間に相当する
# df_context = df.tail(720) 

zone_columns = [
    "Zone 1 Power Consumption",
    "Zone 2  Power Consumption",
    "Zone 3  Power Consumption",
]

# 変換前: 720行 × 3列
# 変換後: 3系列 × 720時点
target = df_context[zone_columns].to_numpy(dtype=np.float32).T

assert target.shape == (3, 720)

to_numpy(...)でDataFrameをNumPy配列へ変換し、.Tで行と列を入れ替えています。（※入力型を明確にし、API内部での余計な型変換を避けるため、ここではfloat32へ変換します。）

つまり、(720行, 3列)の表を、TimesFM-3が受け取る(3系列, 720時点)へ変換しています。

past-only covariateも同じように対象列を選んで転置します。

past-future covariateでは、contextとhorizonを合わせた744行のDataFrameを転置します。（※実務では、現在までの720行に、未来の時刻や予報値が入った24行のデータを結合（concat）して744行のDataFrameを作成してから転置します。）

完全な前処理や日時の切り出しは実装編で扱いますが、DataFrameから配列へ変える中心操作はこの1行です。

静的共変量はAPIに直接の引数がないため、まず省いてベースラインを作る

店舗面積、地域区分、設備容量のように、時間によって変化しない情報は静的共変量（static covariate）と呼ばれます。

現行のTimesFM3Forecaster.predict／predict_batchには、静的共変量を直接渡すstatic_covariates引数がありません。公開APIが直接受け取るのは、target、past-only covariate、past-future covariateの3種類です。

静的な値を時間方向へ繰り返し、past-future covariateの1行として渡すことはshape上は可能です。
ただし、これは静的特徴を専用の仕組みで扱う方法とは異なります。
特に、地域IDのようなカテゴリ値を整数のまま渡すと、本来は存在しない大小関係までモデルへ与えてしまうため避けます。

実務では、次の順番で検証するのがおすすめです。

1. 静的共変量を使わない：targetと動的共変量だけで、再現可能なベースラインを作る
2. 追加条件として比較する：設備容量などの数値を時間方向へ繰り返し、同じ予測期間・評価条件で精度差を確認する
3. 静的属性が重要なら別方式も比較する：属性ごとのモデル分割、モデルの追加学習、静的特徴を明示的に扱えるモデルを検討する

迷った場合は、まず静的共変量を省いてベースラインを作ります。
その後、一つの条件だけを追加して結果を比較すると、静的共変量が本当に役立ったかを判断できます。

したがって、「静的な値をpast-future covariateとして繰り返せば、静的共変量を正しく扱える」とは断定できません。
まずは静的共変量なしで予測を成立させ、必要に応じて追加条件として比較します。

Tetouan Cityデータの各列を分類する

具体例として、UCI Machine Learning RepositoryのPower Consumption of Tetouan Cityを使います。

このデータセットは、複数の予測対象と補助情報が同じ時刻で並んでいるため、多変量targetと共変量の違いを確認する題材に向いています。

モロッコ北部のテトゥアン市について、次の値が10分間隔で記録されています。

• Zone 1〜3 Power Consumption：3つの配電ネットワークの電力消費
• Temperature、Humidity、Wind Speed：気温、湿度、風速の気象観測値
• general diffuse flows、diffuse flows：日射や散乱光に関係する列名として収録された連続値
• DateTime：各観測の日時

UCIの変数表では、general diffuse flowsとdiffuse flowsの詳しい測定定義や単位までは示されていません。そのため、本記事では物理量を細かく解釈せず、「過去に観測された気象側のセンサー値」として扱います。

TimesFM-3への入力を考える前に、「何を予測したいか」と「予測時点で何が分かるか」を列ごとに整理します。

Zone 2とZone 3は、Zone 1の予測を補助する列としても働くかもしれません。それでも、3地域すべてを予測したいという問題設定なら、3本ともtargetです。

ある列がtargetか共変量かは、データの性質だけではなく、予測の目的によって決まります。

なお、実務の電力需要予測では、未来の気温が重要な説明要因になることがあります。
予測時点で提供されていた気象予報を保存しているなら、その予報値を未来側へ与える設計を検討できます。
一方、後から得た未来の実測気温で代用すると、予測時には使えない情報を混ぜることになり、公平な評価ではありません。

単変量targetと多変量targetの違い

単変量予測では、1回の予測で1本のtargetを扱います。
3地域を予測する場合は、Zone 1、Zone 2、Zone 3を別々にモデルへ渡します。

contextが720時間、horizonが24時間なら、各地域の入出力は次の形です。

Zone 1: (720,) -> (24,)
Zone 2: (720,) -> (24,)
Zone 3: (720,) -> (24,)

多変量予測では、3地域を同じ入力にまとめます。

3地域: (3, 720) -> (3, 24)

1つ目の軸は「系列数」、2つ目の軸は「時間」です。
つまり(3, 720)は、「3本のtargetについて、それぞれ過去720時点がある」ことを表します。

TimesFM-3は、時系列を「系列×時間」の2次元グリッドとして扱います。

【詳細】TimesFM-3内部のAttentionメカニズム（クリックで展開）

TimesFM-3は、連続する32時点をパッチと呼ばれる単位にまとめ、次の2種類のAttention（データ内の重要な部分に「注目」する仕組み）を交互に適用します。

• 時間方向のAttention（Causal temporal attention）：各系列が、自分自身の過去を参照する
• 系列方向のAttention（Full variate attention）：同じ時点にある複数の系列を相互に参照する

このため、入力方法によって系列間の情報交換の有無が変わります。

• predict_batchへ3本の(720,)配列を渡す：3件の独立した単変量予測として処理する
• predictへ1本の(3, 720)配列を渡す：3系列を1つの多変量予測として処理し、系列間でも情報を参照する

また、past-future covariateでは、過去側と未来側の既知値をつなぐlookahead構造が使われます。

未来区間のtargetとpast-only covariateはモデルから見えないマスク状態になり、予測時点で値が分かっているpast-future covariateだけを参照できます。

ただし、系列間を参照できることが、必ずしも精度向上につながるとは限りません。
関連性の低い系列がノイズになる可能性もあるため、単変量予測と多変量予測を同じ条件で比較する必要があります。

TimesFM-3の入力設計のまとめ

TimesFM-3へデータを渡す前に、各系列の役割と利用できる時間範囲を整理することが重要です。

• targetは、未来の値を予測したい系列
• past-only covariateは、context区間だけで利用できる補助系列
• past-future covariateは、予測時点で未来の値まで分かる補助系列
• 複数のtargetを2次元配列へまとめる多変量予測は、独立した単変量バッチとは異なる
• 静的共変量はまず省いてベースラインを作り、反復入力は追加条件として比較する

次の実装編では、Tetouan Cityデータを1時間間隔へ集計し、次の配列を実際に作成します。

target:                 (3, 720)
past-only covariate:    (5, 720)
past-future covariate:  (5, 744)

将来の検証編では、単変量・多変量・共変量の条件を変え、予測精度の差を比較します。

参考資料

• TimesFM-3: A zero-shot foundation model for multivariate forecasting（Google Research）
• TimesFM GitHubリポジトリ（インストール、版別仕様、ライセンス）
• TimesFM-3 PyTorch Forecasterの実装（API shape、内部配列化）
• google/timesfm-3.0-pytorch（Hugging Face）

データセット

• Salam, A. & El Hibaoui, A. (2018). Power Consumption of Tetouan City. UCI Machine Learning Repository. （CC BY 4.0）