PriorLabs/tabpfn-time-series

Zero-shot Time Series Forecasting with TabPFN (work accepted at NeurIPS 2024 TRL and TSALM workshops)

📦 TabPFN-TSとは？

TabPFN-TSは、合成テーブルデータで学習された大規模ニューラルネットワークであるTabPFN基礎モデルを再利用することで、ゼロショット時系列予測を可能にするPythonライブラリです。このライブラリは、単変量系列をテーブルに変換し、エンジニアリングされたカレンダー形式の特長量を追加した後、TabPFNを回帰モデルとして実行します。モデルはすでに事前学習済みであるため、学習なしで点予測と確率予測を取得できます。

🛠️ 主要コンポーネント

コンポーネント	役割
`TabPFNTSPipeline`	データ変換、特長量作成、TabPFNの呼び出し（ローカルまたはクラウドクライアント経由）、予測結果の返却といったワークフロー全体を処理する高レベルクラス。
特長量エンジニアリング	カレンダー、サイン/コサイン、その他の時間的特長量を自動的に作成するデフォルトセット (`TABPFN_TS_DEFAULT_FEATURES`)。
TabPFN モデル	基盤となるテーブル基礎モデル。デフォルトでは、パッケージはHugging Faceから TabPFN-3.5（または微調整された TabPFN-TS-3 チェックポイント）を取得します。
`tabpfn-client`	オプションのクラウド推論バックエンド。GPUなしで予測を実行できます。

🚀 使用方法（クイック例）

from tabpfn_time_series import TabPFNTSPipeline

# `context_df` には過去のターゲット列（および既知の未来の共変量）が含まれます
pipeline = TabPFNTSPipeline()          # デフォルトはクラウドクライアント、GPU不要
forecast = pipeline.predict_df(context_df, prediction_length=24)

predict_df は、時間インデックスとターゲット列を持つpandas DataFrameを期待します。既知の未来の共変量（例：休日）がある場合は、future_df 引数に渡してください。
返されるオブジェクトには点予測が含まれ、要求に応じて確率分位点も含まれます。

ステップバイステップのガイドについては、READMEにリンクされているノートブックを参照してください：

quickstart.ipynb – サンプルデータセットでの予測取得。
how-it-works.ipynb – テーブル変換と特長量パイプラインの詳細。

🎯 強みは何か？

強み	重要性
ゼロショット – 学習データや微調整が不要	ラピッドプロトタイピングや、短い履歴ウィンドウしかない場合に最適。
高速推論 – ローカル (CPU) またはクラウドクライアント	低スペックなハードウェアでも動作。クラウドクライアントによりGPUが不要。
確率的出力	リスクを考慮した意思決定に役立つ予測区間を提供。
既知の未来の共変量	カレンダー効果、休日フラグ、または予測時に利用可能な外部予測を入力可能。

⚠️ 制限事項

制限事項	詳細
単変量へのフォーカス	多変量ターゲットは独立した予測に分割され、系列間の相互作用は無視されます。
過去の動的共変量なし	過去の観測値を必要とする特長量（例：過去の天気）は除外されます。
静的共変量の無視	`store_id` のようなアイテムレベルの属性は使用されません。
TabPFNチェックポイントへの依存	予測品質は、テーブルモデルが変換された系列に対してどれだけ汎化できるかに依存します。

過去の動的または静的な情報に大きく依存する問題の場合は、専用の多変量時系列モデルの方が適している可能性があります。

📦 インストールと要件

pip install tabpfn-time-series

デフォルトのクラウドモードには tabpfn>=9.0.0 および tabpfn-client>=0.5.3 が必要です。
ローカルモードでは、初回実行時に ux.priorlabs.ai でライセンスに同意した後、TabPFN-3.5チェックポイントがダウンロードされます。

📚 さらなる学習と引用

論文 – Zero-Shot Time Series Forecasting with TabPFN (arXiv:2501.02945)。
TabPFN-3 レポート – GIFT-EVALベンチマークでSOTA結果を達成した微調整済みチェックポイントの詳細。
学術的な作業でこのライブラリを使用する場合は、両方を引用してください。

🔍 テレメトリとプライバシー

このライブラリは、匿名化された使用統計（パッケージバージョン、Pythonバージョン、呼び出し回数、入力次元）のみを送信します。データ、コード、モデル出力は送信されません。TABPFN_DISABLE_TELEMETRY=1 を設定することでオプトアウト可能です。

TL;DR – TabPFN-TSは、TabPFNテーブル基礎モデルを高速な点予測および確率的な単変量時系列予測に再利用する、軽量で学習不要なライブラリです。GPU不要のクラウド推論オプションも備えています。