在使用时间序列数据时，正确指定其频率非常重要，因为这会显著影响预测结果。TimeGPT 旨在自动推断时间戳的频率。对于常用频率，例如每小时、每天或每月，TimeGPT 会可靠地自动推断频率，因此无需额外输入。

但是，对于不规则频率，即观测值不是以一致或规则的间隔记录的，例如美国股市的交易日，则需要直接指定频率。

TimeGPT 要求您的数据不包含缺失值，因为目前不支持此功能。换句话说，数据的不规则性应源于记录现象的性质，而不是缺失的观测值。如果您的数据包含缺失值，请参阅我们的缺失日期教程。

在本教程中，我们将向您展示如何在 TimeGPT 中处理不规则和自定义频率。

​
1. 导入包

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

import pandas as pd
import pandas_market_calendars as mcal
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="you azure ai endpoint", api_key="your api_key")

​
2. 处理规则频率

如引言中所述，对于具有规则频率的时间序列数据，即观测值以一致间隔记录，如果输入数据是 pandas DataFrame，则 TimeGPT 可以自动推断时间戳的频率。如果您不想依赖 TimeGPT 的自动推断，可以将 freq 参数设置为有效的 pandas 频率字符串，例如用于月度开始频率的 MS 或用于分钟频率的 min。

在使用 Polars DataFrames 时，您必须通过使用有效的 polars offset 明确指定频率，例如用于每日频率的 1d 或用于每小时频率的 1h。

下面是如何为 Polars DataFrame 指定频率的示例。

import polars as pl 

url = 'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/air_passengers.csv'

polars_df = pl.read_csv(url, try_parse_dates=True)

fcst_df = nixtla_client.forecast(
    df=polars_df,
    h=12, 
    freq='1mo', 
    time_col='timestamp', 
    target_col='value', 
    level=[80, 95]
)

INFO:nixtla.nixtla_client:Validating inputs...
INFO:nixtla.nixtla_client:Preprocessing dataframes...
INFO:nixtla.nixtla_client:Restricting input...
INFO:nixtla.nixtla_client:Calling Forecast Endpoint...

nixtla_client.plot(polars_df, fcst_df, time_col='timestamp', target_col='value', level=[80,95])

​
3. 处理不规则频率

在本节中，我们将讨论观测值不是以一致间隔记录的情况。

​
3.1 加载数据

我们将使用 Palantir Technologies (PLTR) 从 2020 年到 2023 年的每日股票价格数据。该数据集包含截至 2023 年 9 月 22 日的数据，但出于本教程的目的，我们将排除 2023 年 8 月 28 日之前的任何数据。这使得我们可以展示自定义频率如何处理股市休市的日子，例如美国的劳动节。

url = 'https://raw.githubusercontent.com/Nixtla/transfer-learning-time-series/main/datasets/openbb/pltr.csv'
pltr_df = pd.read_csv(url, parse_dates=['date'])
pltr_df = pltr_df.query('date < "2023-08-28"')
pltr_df.head()
dateOpenHighLowCloseAdj CloseVolumeDividendsStock Splits
02020-09-3010.0011.419.119.509.503385844000.00.0
12020-10-019.6910.109.239.469.461242976000.00.0
22020-10-029.069.288.949.209.20550183000.00.0
32020-10-059.439.498.929.039.03363169000.00.0
42020-10-069.0410.188.909.909.90908640000.00.0

我们将预测调整后的收盘价，它代表了根据公司行动（如股票拆分、股息和配股）调整后的股票收盘价。因此，我们将从数据集中排除其他列。

pltr_df = pltr_df[['date', 'Adj Close']]

nixtla_client.plot(pltr_df, time_col = "date", target_col = "Adj Close")

​
3.2 定义频率

为了定义自定义频率，我们将首先从输入数据中提取并排序日期，确保它们是正确的 datetime 格式。接下来，我们将使用 pandas_market_calendars package，特别是 get_calendar 方法，获取纽约证券交易所 (NYSE) 日历。使用此日历，我们可以创建一个仅包含股票市场开放日的自定义频率。

dates = pd.DatetimeIndex(sorted(pltr_df['date'].unique())) # sort all dates in the dataset

nyse = mcal.get_calendar('NYSE') # New Yor Stock Exchange calendar

请注意，股票市场开放日需要包括输入数据中的所有日期以及预测范围。在此示例中，我们将预测未来 7 天，因此我们需要确保我们的交易日包括输入数据中的最后一天以及接下来的 7 个有效交易日。

为了避免在预测范围内处理节假日或周末，我们将指定一个远超预测范围的结束日期。在此示例中，我们将使用 2024 年 1 月 1 日作为安全的截止日期。

trading_days = nyse.valid_days(start_date=dates.min(), end_date="2024-01-01").tz_localize(None)

现在，有了交易日列表，我们可以识别股票市场休市的日子。这些是范围内的所有非交易日的工作日（周一至周五）。利用此信息，我们可以定义一个跳过股市休市日的自定义频率。

all_weekdays = pd.date_range(start=dates.min(), end="2024-01-01", freq='B')

closed_days = all_weekdays.difference(trading_days)

custom_bday = pd.offsets.CustomBusinessDay(holidays=closed_days)

​
3.3 使用 TimeGPT 进行预测

定义自定义频率后，我们现在可以使用 forecast 方法，在 freq 参数中指定 custom_bday 频率。这将使预测遵守股票市场的交易时间表。

fcst_pltr_df = nixtla_client.forecast(
    df=pltr_df, 
    h=7, 
    freq=custom_bday,
    time_col='date', 
    target_col='Adj Close',
    level=[80, 95]
)

INFO:nixtla.nixtla_client:Validating inputs...
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...

📘 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(pltr_df, fcst_pltr_df, time_col = "date", target_col = "Adj Close", level=[80, 95], max_insample_length = 180)


fcst_pltr_df[['date']].head(7)
date
02023-08-28
12023-08-29
22023-08-30
32023-08-31
42023-09-01
52023-09-05
62023-09-06

请注意，预测排除了 2023 年 9 月 4 日，这是一个周一，美国股市因劳动节休市。

​
4. 总结

以下是本教程的关键要点

  • TimeGPT 可以可靠地推断规则频率，但您可以通过将 freq 参数设置为相应的 pandas 别名来覆盖此设置。

  • 在使用 polars 数据帧时，您必须始终使用正确的 polars offset 指定频率。

  • TimeGPT 支持不规则频率，并允许您定义自定义频率，仅针对指定日期生成预测。