TimeGPT 接受 长格式 的 pandas 和 polars 数据框，需要以下列：

  • ds (时间戳): 时间戳格式为 YYYY-MM-DD 或 YYYY-MM-DD HH:MM:SS。
  • y (数值): 要预测的目标变量。

（可选：您也可以传入一个没有 ds 列但具有 DatetimeIndex 的 DataFrame）

TimeGPT 也支持分布式数据框，例如 dask、spark 和 ray。

您也可以在 DataFrame 中包含外生特征作为附加列。更多信息请参阅此教程。

以下是 TimeGPT 有效输入数据框的示例。

import pandas as pd 

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv')
df.head()
timestampvalue
01949-01-01112
11949-02-01118
21949-03-01132
31949-04-01129
41949-05-01121

请注意，在此示例中，ds 列被命名为 timestamp，y 列被命名为 value。您有两种选择：

  1. 分别将列重命名为 ds 和 y，或者

  2. 保留当前列名并在使用 NixtlaClient 类中的任何方法时，通过 time_col 和 target_col 参数指定它们。

例如，当使用 NixtlaClient 类中的 forecast 方法时，您必须实例化该类，然后如下指定列名。

from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    api_key = 'my_api_key_provided_by_nixtla'
)

fcst = nixtla_client.forecast(df=df, h=12, time_col='timestamp', target_col='value')
fcst.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Inferred freq: MS
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Querying model metadata...
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
timestampTimeGPT
01961-01-01437.83792
11961-02-01426.06270
21961-03-01463.11655
31961-04-01478.24450
41961-05-01505.64648

在此示例中，NixtlaClient 会推断频率，但您可以使用 freq 参数明确指定它。

要了解如何实例化 NixtlaClient 类，请参阅TimeGPT 快速入门

​
多序列

如果您处理多个时间序列，请确保每个序列都有一个唯一标识符。您可以将此列命名为 unique_id，或者在使用 NixtlaClient 类中的任何方法时，使用 id_col 参数指定其名称。此列应为字符串、整数或类别类型。

在此示例中，我们有五个序列，表示五个不同市场的每小时电价。列名已是默认名称，因此无需指定 id_col、time_col 或 target_col 参数。如果您的列名不同，请根据需要指定这些参数。

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short.csv')
df.head()
unique_iddsy
0BE2016-10-22 00:00:0070.00
1BE2016-10-22 01:00:0037.10
2BE2016-10-22 02:00:0037.10
3BE2016-10-22 03:00:0044.75
4BE2016-10-22 04:00:0037.10
fcst = nixtla_client.forecast(df=df, h=24) # use id_col, time_col and target_col here if needed. 
fcst.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Inferred freq: h
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Querying model metadata...
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
unique_iddsTimeGPT
0BE2016-12-31 00:00:0045.190582
1BE2016-12-31 01:00:0043.244987
2BE2016-12-31 02:00:0041.958897
3BE2016-12-31 03:00:0039.796680
4BE2016-12-31 04:00:0039.204865

处理大量时间序列时，请考虑使用分布式计算框架以高效处理数据。TimeGPT 支持 Spark、Dask 和 Ray 等框架。

​
外生变量

TimeGPT 也接受外生变量。您可以通过在 y 列之后添加额外列来将外生变量添加到您的数据框中。

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-with-ex-vars.csv')
df.head()
unique_iddsyExogenous1Exogenous2day_0day_1day_2day_3day_4day_5day_6
0BE2016-10-22 00:00:0070.0057253.049593.00.00.00.00.00.01.00.0
1BE2016-10-22 01:00:0037.1051887.046073.00.00.00.00.00.01.00.0
2BE2016-10-22 02:00:0037.1051896.044927.00.00.00.00.00.01.00.0
3BE2016-10-22 03:00:0044.7548428.044483.00.00.00.00.00.01.00.0
4BE2016-10-22 04:00:0037.1046721.044338.00.00.00.00.00.01.00.0

使用外生变量时，您还需要提供其未来值。

future_ex_vars_df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/electricity-short-future-ex-vars.csv')
future_ex_vars_df.head()
unique_iddsExogenous1Exogenous2day_0day_1day_2day_3day_4day_5day_6
0BE2016-12-31 00:00:0070318.064108.00.00.00.00.00.01.00.0
1BE2016-12-31 01:00:0067898.062492.00.00.00.00.00.01.00.0
2BE2016-12-31 02:00:0068379.061571.00.00.00.00.00.01.00.0
3BE2016-12-31 03:00:0064972.060381.00.00.00.00.00.01.00.0
4BE2016-12-31 04:00:0062900.060298.00.00.00.00.00.01.00.0
fcst = nixtla_client.forecast(df=df, X_df=future_ex_vars_df, h=24)
fcst.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Inferred freq: h
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Using future exogenous features: ['Exogenous1', 'Exogenous2', 'day_0', 'day_1', 'day_2', 'day_3', 'day_4', 'day_5', 'day_6']
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...
unique_iddsTimeGPT
0BE2016-12-31 00:00:0051.632830
1BE2016-12-31 01:00:0045.750877
2BE2016-12-31 02:00:0039.650543
3BE2016-12-31 03:00:0034.000072
4BE2016-12-31 04:00:0033.785370

要了解如何将外生变量与 TimeGPT 结合使用，请参阅外生变量教程。

​
重要注意事项

使用 TimeGPT 时，数据不能包含缺失值。这意味着对于每个序列，时间戳不应有间隔，目标变量不应有缺失值。

更多信息，请参阅关于处理 TimeGPT 中缺失值的教程。

​
最低数据要求（适用于 AzureAI）

TimeGPT 目前支持任何数量的数据来生成点预测。也就是说，无论频率如何，每个序列调用 nixtla_client.forecast(df=df, h=h, freq=freq) 并期望获得结果所需的最小大小为一。

对于 Azure AI，在使用参数 level、finetune_steps、X_df（外生变量）或 add_history 时，API 根据频率要求最低数据点数量。以下是每种频率的最低大小：

频率最低大小
每小时和亚小时（例如，“H”、“min”、“15T”）1008
每日（“D”）300
每周（例如，“W-MON”,..., “W-SUN”）64
每月及其他频率（例如，“M”、“MS”、“Y”）48

对于交叉验证，您需要考虑这些数量以及预测范围 (h)、窗口数量 (n_windows) 和窗口之间的间隔 (step_size)。因此，在这种情况下每个序列的最小观测数量将由以下关系确定：

先前描述的最低数量 + h + step_size + (n_windows - 1)