autogluon.timeseries.TimeSeriesPredictor

class autogluon.timeseries.TimeSeriesPredictor(target: str | None = None, known_covariates_names: List[str] | None = None, prediction_length: int = 1, freq: str | None = None, eval_metric: str | TimeSeriesScorer | None = None, eval_metric_seasonal_period: int | None = None, horizon_weight: List[float] | None = None, path: str | Path | None = None, verbosity: int = 2, log_to_file: bool = True, log_file_path: str | Path = 'auto', quantile_levels: List[float] | None = None, cache_predictions: bool = True, label: str | None = None, **kwargs)

AutoGluon TimeSeriesPredictor 预测多个相关时间序列的未来值。

TimeSeriesPredictor 为单变量时间序列提供概率（分位数）多步提前预测。预测包含平均值（即给定过去未来值的条件期望），以及预测分布的分位数，指示未来可能结果的范围。

TimeSeriesPredictor 同时拟合跨所有时间序列共享的“全局”深度学习模型（例如 DeepAR、Transformer），以及针对每个单独时间序列拟合的“局部”统计模型（例如 ARIMA、ETS）。

TimeSeriesPredictor 期望输入数据并以 TimeSeriesDataFrame 格式进行预测。

参数:

• target (str, 默认为 "target") – 包含要预测的目标值（即时间序列的数值观测值）的列名。

• prediction_length (int, 默认为 1) – 预测范围，即模型应该训练预测未来多少个时间步长。例如，如果时间序列包含每日观测值，将 prediction_length = 3 将训练预测未来 3 天的模型，从最近的观测值算起。

• freq (str, 可选) –

  时间序列数据的频率（可用的频率请参阅 pandas 文档）。例如，"D" 表示每日数据，"h" 表示每小时数据。

  默认情况下，预测器会尝试自动从数据中推断频率。此参数应仅在两种情况下设置：

  1. 时间序列数据具有不规则时间戳，因此无法自动推断频率。

  2. 您希望以不同的频率重新采样原始数据（例如，将每小时测量值转换为每日测量值）。

  如果在创建预测器时提供了 freq，则传递给预测器的所有数据都将自动以该频率重新采样。

• eval_metric (Union[str, TimeSeriesScorer], 默认为 "WQL") –

  最终将在未来测试数据上评估预测的指标。AutoGluon 调整超参数以提高验证数据上的此指标，并根据此指标对模型（在验证数据上）进行排名。

  概率预测指标（根据指定 quantile_levels 的分位数预测进行评估）

  • "SQL"：缩放分位数损失

  • "WQL"：加权分位数损失

  点预测指标（这些指标始终在预测的 "mean" 列上评估）

  • "MAE"：平均绝对误差

  • "MAPE"：平均绝对百分比误差

  • "MASE"：平均绝对缩放误差

  • "MSE"：均方误差

  • "RMSE"：均方根误差

  • "RMSLE"：均方根对数误差

  • "RMSSE"：均方根缩放误差

  • "SMAPE"：“对称”平均绝对百分比误差

  • "WAPE"：加权绝对百分比误差

  有关这些指标的更多信息，请参阅 时间序列预测 - 评估指标。

• eval_metric_seasonal_period (int, 可选) – 用于计算某些评估指标（如平均绝对缩放误差 (MASE)）的季节周期。默认为 None，在这种情况下，季节周期根据数据频率计算。

• horizon_weight (List[float], 可选) –

  计算 eval_metric 时分配给预测范围中每个时间步长的权重。如果提供，这必须是一个包含 prediction_length 个非负值的列表，其中至少有一些值大于零。AutoGluon 会自动标准化权重，使其总和等于 prediction_length。默认情况下，预测范围中的所有时间步长具有相同的权重，这等同于设置 horizon_weight = [1] * prediction_length。

  此参数仅影响模型选择和集成构建；它对单个预测模型的损失函数没有影响。

• known_covariates_names (List[str], 可选) –

  在预测范围内的所有时间步长中已知的前瞻协变量的名称。这些协变量也称为动态特征、外生变量、附加回归变量或相关时间序列。此类协变量的示例包括假期、促销或天气预报。

  如果提供了 known_covariates_names，那么

  • fit()、evaluate() 和 leaderboard() 将期望一个数据框，其中包含 known_covariates_names 中列出的列（除了 target 列）。

  • predict() 将期望一个额外的关键字参数 known_covariates，其中包含以 TimeSeriesDataFrame 格式存储的已知协变量的未来值。

• quantile_levels (List[float], 可选) – 递增小数列表，指定进行分布预测时应估计哪些分位数。默认为 [0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9]。

• path (str 或 pathlib.Path, 可选) – 保存模型和中间输出的本地目录路径。默认为工作目录中创建的带时间戳文件夹 AutogluonModels/ag-[TIMESTAMP]。

• verbosity (int, 默认为 2) – 详细程度级别范围从 0 到 4，控制打印到标准输出的信息量。级别越高，打印语句越详细，verbosity=0 抑制输出，包括警告。verbosity 0 对应于 Python 的 ERROR 日志级别，仅记录错误输出。verbosity 1 和 2 分别另外记录警告和信息输出。verbosity 4 启用所有日志输出，包括 AutoGluon 的调试消息和所有依赖项（GluonTS、PyTorch Lightning、AutoGluon-Tabular 等）中的日志记录。

• log_to_file (bool, 默认为 True) – 是否将日志保存到文件中以供后续参考

• log_file_path (Union[str, Path], 默认为 "auto") – 保存日志的文件路径。如果设置为 auto，日志将保存到 predictor_path/logs/predictor_log.txt 下。如果 log_to_file 设置为 False，此参数将被忽略。

• cache_predictions (bool, 默认为 True) – 如果为 True，预测器将在调用 predict()、leaderboard() 或 evaluate() 方法时缓存并重用单个模型生成的预测。这可以显著加快这些方法的速度。如果为 False，则禁用缓存。您可以将此参数设置为 False 以减少磁盘使用，但代价是预测时间更长。

• label (str, 可选) – target 的别名。

__init__(target: str | None = None, known_covariates_names: List[str] | None = None, prediction_length: int = 1, freq: str | None = None, eval_metric: str | TimeSeriesScorer | None = None, eval_metric_seasonal_period: int | None = None, horizon_weight: List[float] | None = None, path: str | Path | None = None, verbosity: int = 2, log_to_file: bool = True, log_file_path: str | Path = 'auto', quantile_levels: List[float] | None = None, cache_predictions: bool = True, label: str | None = None, **kwargs)

方法

evaluate	评估给定数据集的预测准确性。
feature_importance	通过将每个特征替换为相同特征的打乱版本（也称为排列特征重要性）或通过分配表示该特征的中位数或众数的常数值，并计算模型预测性能的相对下降来计算给定模型的特征重要性得分。
fit	将概率预测模型拟合到给定的时间序列数据集。
fit_summary	输出 fit() 期间生成的模型信息摘要。
info	返回一个字典，其中每个对象描述了训练过程和训练模型的属性。
leaderboard	返回显示每个训练模型性能的排行榜，输出是一个包含以下列的 pandas 数据框
load	从给定 path 加载现有的 TimeSeriesPredictor。
make_future_data_frame	生成一个数据框，其中包含对应于预测范围的 item_id 和 timestamp 值。
model_names	返回此预测器对象训练的模型名称列表。
persist	在内存中持久化模型以减少推理延迟。
plot	绘制历史时间序列值和预测。
predict	返回给定数据集的分位数和平均预测，从每个时间序列的末尾开始。
refit_full	在所有数据（训练 + 验证）上重新训练模型。
save	将此预测器保存到此预测器的 path 指定目录中的文件。
unpersist	取消在内存中持久化的模型以减少内存使用。

属性

model_best	返回训练器中的最佳模型名称。
predictor_file_name