数据需求

本节解释了 TimeGPT 的数据需求。

from nixtla.utils import colab_badge

colab_badge('docs/getting-started/5_data_requirements')

TimeGPT 接受带有以下必要列的长格式的 pandas 和 polars 数据框：

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

（可选地，您还可以传递一个没有 ds 列的 DataFrame，只要它有 DatetimeIndex）

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()

	timestamp	value
0	1949-01-01	112
1	1949-02-01	118
2	1949-03-01	132
3	1949-04-01	129
4	1949-05-01	121

请注意，在这个例子中，ds 列被命名为 timestamp，而 y 列被命名为 value。你可以选择：

将列重命名为 ds 和 y，分别，或者
保持当前列名，并在使用 NixtlaClient 类的任何方法时通过 time_col 和 target_col 参数来指定它们。

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

from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    api_key = 'my_api_key_provided_by_nixtla'
)

nixtla_client = NixtlaClient()

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:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: MS
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...

	timestamp	TimeGPT
0	1961-01-01	437.837921
1	1961-02-01	426.062714
2	1961-03-01	463.116547
3	1961-04-01	478.244507
4	1961-05-01	505.646484

在这个示例中，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_id	ds	y
0	BE	2016-10-22 00:00:00	70.00
1	BE	2016-10-22 01:00:00	37.10
2	BE	2016-10-22 02:00:00	37.10
3	BE	2016-10-22 03:00:00	44.75
4	BE	2016-10-22 04:00:00	37.10

fcst = nixtla_client.forecast(df=df, h=24) # 如有需要，在此处使用id_col、time_col和target_col。 
fcst.head()

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: H
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...

	unique_id	ds	TimeGPT
0	BE	2016-12-31 00:00:00	45.190453
1	BE	2016-12-31 01:00:00	43.244446
2	BE	2016-12-31 02:00:00	41.958389
3	BE	2016-12-31 03:00:00	39.796486
4	BE	2016-12-31 04:00:00	39.204536

在处理大量时间序列时，考虑使用分布式计算框架以有效管理数据。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_id	ds	y	Exogenous1	Exogenous2	day_5
0	BE	2016-10-22 00:00:00	70.00	49593.0	57253.0	1.0
1	BE	2016-10-22 01:00:00	37.10	46073.0	51887.0	1.0
2	BE	2016-10-22 02:00:00	37.10	44927.0	51896.0	1.0
3	BE	2016-10-22 03:00:00	44.75	44483.0	48428.0	1.0
4	BE	2016-10-22 04:00:00	37.10	44338.0	46721.0	1.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_id	ds	Exogenous1	Exogenous2	day_5
0	BE	2016-12-31 00:00:00	64108.0	70318.0	1.0
1	BE	2016-12-31 01:00:00	62492.0	67898.0	1.0
2	BE	2016-12-31 02:00:00	61571.0	68379.0	1.0
3	BE	2016-12-31 03:00:00	60381.0	64972.0	1.0
4	BE	2016-12-31 04:00:00	60298.0	62900.0	1.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:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: H
INFO:nixtla.nixtla_client:Using the following exogenous variables: Exogenous1, Exogenous2, day_0, day_1, day_2, day_3, day_4, day_5, day_6
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...

	unique_id	ds	TimeGPT
0	BE	2016-12-31 00:00:00	74.540773
1	BE	2016-12-31 01:00:00	43.344289
2	BE	2016-12-31 02:00:00	44.429220
3	BE	2016-12-31 03:00:00	38.094395
4	BE	2016-12-31 04:00:00	37.389141

要了解如何在 TimeGPT 中使用外生变量，请咨询外生变量教程。

重要注意事项

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

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

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

TimeGPT 当前支持任何数量的数据来生成点预测。也就是说，从以下调用 nixtla_client.forecast(df=df, h=h, freq=freq) 期望结果的每个系列的最小大小为 1，无论频率如何。

对于 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)

Give us a ⭐ on Github