Timesfm 1.0 200m

🚀 TimesFM

TimesFM (Time Series Foundation Model) は、Google Researchによって開発された、時系列予測用の事前学習済み時系列基礎モデルです。このモデルは、時系列データの予測タスクにおいて高い性能を発揮します。

リソースと技術ドキュメント：

• 論文: A decoder-only foundation model for time-series forecasting、ICML 2024に掲載予定
• Google Researchブログ
• GitHubリポジトリ

著者: Google Research

これは公式にサポートされているGoogleの製品ではありません。

🚀 クイックスタート

TimesFMを使って時系列予測を行うには、まずモデルを初期化しチェックポイントをロードする必要があります。その後、入力データを用いて予測を実行できます。

✨ 主な機能

• 最大512時点までのコンテキスト長と任意の予測期間での単変量時系列予測が可能。
• ポイント予測に特化しており、確率的予測はサポートしていません。ただし、実験的に分位数ヘッドを提供していますが、事前学習後にキャリブレーションされていません。
• コンテキストが連続していることを要求し、コンテキストと予測期間の頻度が同じである必要があります。

📦 インストール

このHuggingFaceリポジトリにはTimesFmのチェックポイントがホストされています。モデル推論用のtimesfmライブラリをインストールするには、GitHubリポジトリを訪問し、そこに記載されている手順に従ってください。

特に、依存関係のlingvoはARMアーキテクチャをサポートしておらず、Appleシリコンのマシンでは推論コードが動作しません。この問題を認識しており、解決策を検討中です。引き続きお楽しみに。

💻 使用例

基本的な使用法

モデルを初期化し、チェックポイントをロードする方法は以下の通りです。

import timesfm

tfm = timesfm.TimesFm(
    context_len=<context>,
    horizon_len=<horizon>,
    input_patch_len=32,
    output_patch_len=128,
    num_layers=20,
    model_dims=1280,
    backend=<backend>,
)
tfm.load_from_checkpoint(repo_id="google/timesfm-1.0-200m")

200mモデルをロードするためには、以下の4つのパラメータが固定されています。

input_patch_len=32,
output_patch_len=128,
num_layers=20,
model_dims=1280,

1. ここでのcontext_lenは、モデルの最大コンテキスト長として設定できます。tfm.forecast()関数により短い系列を提供することもでき、モデルはそれを処理します。現在、モデルは最大512のコンテキスト長を処理でき、将来的なリリースで増やす予定です。入力時系列は任意のコンテキスト長を持つことができます。必要に応じて、推論コードによってパディング/切り捨てが処理されます。
2. 予測期間は任意の値に設定できます。アプリケーションの予測タスクで必要となる最大の予測期間に設定することをおすすめします。一般的には、予測期間 <= コンテキスト長をおすすめしますが、関数呼び出しでは必須ではありません。

高度な使用法

推論を実行する方法は、配列入力またはpandasデータフレームのどちらからでも可能です。両方の予測メソッドは、(1) 入力時系列コンテキストと、(2) それらの頻度を期待します。tfm.forecast()およびtfm.forecast_on_df()関数のドキュメントを参照して、詳細な指示を確認してください。

特に、頻度に関して、TimesFMは{0, 1, 2}のカテゴリカル指標を期待します。

• 0 (デフォルト): 高頻度、長期間の時系列。日次粒度までの時系列にこれを使用することをおすすめします。
• 1: 中頻度の時系列。週次および月次データにこれを使用することをおすすめします。
• 2: 低頻度、短期間の時系列。月次を超えるもの、例えば四半期または年次データにこれを使用することをおすすめします。

このカテゴリカル値は、配列入力とともに直接提供する必要があります。データフレーム入力の場合、従来の頻度の文字コードを期待するカテゴリに変換します。

• 0: T, MIN, H, D, B, U
• 1: W, M
• 2: Q, Y

ここで、推奨事項に厳密に従う必要はありません。これはモデル学習時の設定であり、最良の予測結果を提供することを期待していますが、頻度入力を自由パラメータと見なし、特定のユースケースに合わせて変更することもできます。

配列入力の例

頻度をそれぞれ低、中、高に設定した配列入力の例です。

import numpy as np
forecast_input = [
    np.sin(np.linspace(0, 20, 100))
    np.sin(np.linspace(0, 20, 200)),
    np.sin(np.linspace(0, 20, 400)),
]
frequency_input = [0, 1, 2]

point_forecast, experimental_quantile_forecast = tfm.forecast(
    forecast_input,
    freq=frequency_input,
)

pandasデータフレームの例

頻度を月次（"M"）に設定したpandasデータフレームの例です。

import pandas as pd

# e.g. input_df is
#       unique_id  ds          y
# 0     T1         1975-12-31  697458.0
# 1     T1         1976-01-31  1187650.0
# 2     T1         1976-02-29  1069690.0
# 3     T1         1976-03-31  1078430.0
# 4     T1         1976-04-30  1059910.0
# ...   ...        ...         ...
# 8175  T99        1986-01-31  602.0
# 8176  T99        1986-02-28  684.0
# 8177  T99        1986-03-31  818.0
# 8178  T99        1986-04-30  836.0
# 8179  T99        1986-05-31  878.0

forecast_df = tfm.forecast_on_df(
    inputs=input_df,
    freq="M",  # monthly
    value_name="y",
    num_jobs=-1,
)

📚 ドキュメント

チェックポイントtimesfm-1.0-200mについての詳細な情報は以下の通りです。

timesfm-1.0-200mは最初のオープンモデルチェックポイントです。

• 最大512時点までのコンテキスト長と任意の予測期間での単変量時系列予測が可能で、オプションの頻度指標を使用できます。
• ポイント予測に特化しており、確率的予測はサポートしていません。実験的に分位数ヘッドを提供していますが、事前学習後にキャリブレーションされていません。
• コンテキストが連続していることを要求し、コンテキストと予測期間の頻度が同じである必要があります。

🔧 技術詳細

ベンチマークに関する結果は、拡張ベンチマークおよび長期間ベンチマークの結果表を参照してください。

それぞれのベンチマークでTimesFMを実行するための指示は、experiments/内のそれぞれのベンチマークディレクトリのREADMEファイルを参照してください。

📄 ライセンス

このプロジェクトはApache-2.0ライセンスの下でライセンスされています。