日历变量和特殊日期是预测应用中最常见的额外变量类型之一。它们为时间序列的当前状态提供额外上下文，特别是对于 TimeGPT-1 等基于窗口的模型。这些变量通常包括添加每个观测值的月份、周、日或小时信息。例如，在高频率的小时数据中，提供当前的年份月份比输入窗口中有限的历史信息能提供更多上下文，从而改善预测。

在本教程中，我们将展示如何使用 date_features 函数自动向数据集添加日历变量。

​
1. 导入包

首先，我们导入所需的包并初始化 Nixtla 客户端。

import pandas as pd
from nixtla import NixtlaClient

nixtla_client = NixtlaClient(
    # defaults to os.environ.get("NIXTLA_API_KEY")
    api_key = 'my_api_key_provided_by_nixtla'
)

👍 使用 Azure AI 端点

要使用 Azure AI 端点，请记住同时设置 base_url 参数

nixtla_client = NixtlaClient(base_url="您的 Azure AI 端点", api_key="您的 API 密钥")

​
2. 加载数据

我们将使用关于巧克力的 Google Trends 数据集，数据为月度数据。

df = pd.read_csv('https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/google_trend_chocolate.csv')
df['month'] = pd.to_datetime(df['month']).dt.to_period('M').dt.to_timestamp('M')

df.head()
monthchocolate
02004-01-3135
12004-02-2945
22004-03-3128
32004-04-3030
42004-05-3129

​
3. 使用节假日和特殊日期进行预测

鉴于日历变量的广泛使用，我们在预测方法中作为预处理步骤包含了常见日历变量的自动创建。让我们创建一个包含美国即将到来的节假日的未来数据框。

# Create future dataframe with exogenous features

start_date = '2024-05'
dates = pd.date_range(start=start_date, periods=14, freq='M')

dates = dates.to_period('M').to_timestamp('M')

future_df = pd.DataFrame(dates, columns=['month'])

from nixtla.date_features import CountryHolidays

us_holidays = CountryHolidays(countries=['US'])
dates = pd.date_range(start=future_df.iloc[0]['month'], end=future_df.iloc[-1]['month'], freq='D')
holidays_df = us_holidays(dates)
monthly_holidays = holidays_df.resample('M').max()

monthly_holidays = monthly_holidays.reset_index(names='month')

future_df = future_df.merge(monthly_holidays)

future_df.head()
monthUS_新年US_阵亡将士纪念日US_六月节全国独立日US_独立日US_劳动节US_退伍军人节US_感恩节US_圣诞节US_马丁·路德·金纪念日US_华盛顿诞辰US_哥伦布日
02024-05-3100000000000
12024-06-3000100000000
22024-07-3100010000000
32024-08-3100000000000
42024-09-3000001000000

我们对输入数据框执行相同的步骤。

# Add exogenous features to input dataframe

dates = pd.date_range(start=df.iloc[0]['month'], end=df.iloc[-1]['month'], freq='D')
holidays_df = us_holidays(dates)
monthly_holidays = holidays_df.resample('M').max()

monthly_holidays = monthly_holidays.reset_index(names='month')

df = df.merge(monthly_holidays)

df.tail()
monthchocolateUS_新年US_新年 (观察日期)US_阵亡将士纪念日US_独立日US_独立日 (观察日期)US_劳动节US_退伍军人节US_感恩节US_圣诞节US_圣诞节 (观察日期)US_马丁·路德·金纪念日US_华盛顿诞辰US_哥伦布日US_退伍军人节 (观察日期)US_六月节全国独立日US_六月节全国独立日 (观察日期)
2392023-12-31900000000010000000
2402024-01-31641000000000100000
2412024-02-29660000000000010000
2422024-03-31590000000000000000
2432024-04-30510000000000000000

太好了！现在，TimeGPT 将把这些节假日视为外生变量，而即将到来的节假日将帮助它进行预测。

fcst_df = nixtla_client.forecast(
    df=df,
    h=14,
    freq='M',
    time_col='month',
    target_col='chocolate',
    X_df=future_df
)

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Inferred freq: M
WARNING:nixtla.nixtla_client:The specified horizon "h" exceeds the model horizon. This may lead to less accurate forecasts. Please consider using a smaller horizon.
INFO:nixtla.nixtla_client:Using the following exogenous variables: US_New Year's Day, US_Memorial Day, US_Juneteenth National Independence Day, US_Independence Day, US_Labor Day, US_Veterans Day, US_Thanksgiving, US_Christmas Day, US_Martin Luther King Jr. Day, US_Washington's Birthday, US_Columbus Day
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...

📘 Azure AI 中的可用模型

如果您正在使用 Azure AI 端点，请务必设置 model="azureai"

nixtla_client.forecast(..., model="azureai")

对于公共 API，我们支持两种模型：timegpt-1 和 timegpt-1-long-horizon。

默认使用 timegpt-1。有关如何以及何时使用 timegpt-1-long-horizon，请参阅此教程。

nixtla_client.plot(
    df, 
    fcst_df, 
    time_col='month',
    target_col='chocolate',
)

然后我们可以绘制每个节假日的权重，以查看哪些在预测对巧克力的兴趣方面更重要。

nixtla_client.weights_x.plot.barh(x='features', y='weights', figsize=(10, 10))

以下是 date_features 参数工作原理的详细说明

  • date_features (布尔值、字符串列表或可调用对象): 此参数指定要考虑哪些日期属性。
    • 如果设置为 True，模型将自动添加与给定数据框 (df) 频率相关的最常见日期特征。对于每日频率，这可能包括星期几、月份和年份等特征。
    • 如果提供字符串列表，它将考虑那些特定的日期属性。例如，date_features=['weekday', 'month'] 将仅添加星期几和月份作为特征。
    • 如果提供可调用对象，它应该是一个以日期为输入并返回所需特征的函数。这使得计算自定义日期特征具有灵活性。
  • date_features_to_one_hot (布尔值或字符串列表): 在确定日期特征后，您可能希望对其进行独热编码，特别是如果它们本质上是分类的（如星期几）。独热编码将这些分类特征转换为二进制矩阵，使其更适合许多机器学习算法。
    • 如果 date_features=True，则默认情况下，所有计算出的日期特征都将被独热编码。
    • 如果提供字符串列表，则仅对那些特定的日期特征进行独热编码。

通过利用 date_features 和 date_features_to_one_hot 参数，可以有效地将日期属性的时间效应纳入预测模型，从而潜在地提高其准确性和可解释性。