XGBoost 模型

基于 XGBoost 的回归模型。

此实现具有生成概率预测的能力。

class darts.models.forecasting.xgboost.XGBModel(lags=None, lags_past_covariates=None, lags_future_covariates=None, output_chunk_length=1, output_chunk_shift=0, add_encoders=None, likelihood=None, quantiles=None, random_state=None, multi_models=True, use_static_covariates=True, **kwargs)

基类: RegressionModel

XGBoost 模型

参数

• lags (Union[int, list[int], dict[str, Union[int, list[int]]], None]) – 用于预测下一个时间步的时间序列 series 的滞后目标值。如果为整数，则必须 > 0。使用最后 n=lags 个历史滞后；例如 (-1, -2, …, -lags)，其中 0 对应于每个样本的第一个预测时间步。如果 output_chunk_shift > 0，则滞后 -1 对应于第一个预测步之前的 -1 - output_chunk_shift 步。如果为整数列表，每个值必须 < 0。仅使用指定的滞后值。如果为字典，键对应于 series 的分量名称（在使用多个序列时取第一个序列），值对应于分量滞后（整数或整数列表）。键 'default_lags' 可用于为未指定的分量提供默认滞后。如果缺少某些分量且未提供 'default_lags' 键，则会引发错误。

• lags_past_covariates (Union[int, list[int], dict[str, Union[int, list[int]]], None]) – 用于预测下一个时间步的时间序列 past_covariates 的滞后值。如果为整数，则必须 > 0。使用最后 n=lags_past_covariates 个历史滞后；例如 (-1, -2, …, -lags)，其中 0 对应于每个样本的第一个预测时间步。如果 output_chunk_shift > 0，则滞后 -1 对应于第一个预测步之前的 -1 - output_chunk_shift 步。如果为整数列表，每个值必须 < 0。仅使用指定的滞后值。如果为字典，键对应于 past_covariates 的分量名称（在使用多个序列时取第一个序列），值对应于分量滞后（整数或整数列表）。键 'default_lags' 可用于为未指定的分量提供默认滞后。如果缺少某些分量且未提供 'default_lags' 键，则会引发错误。

• lags_future_covariates (Union[tuple[int, int], list[int], dict[str, Union[tuple[int, int], list[int]]], None]) – 用于预测下一个时间步的时间序列 future_covariates 的滞后值。滞后始终相对于输出块中的第一个步，即使 output_chunk_shift > 0 也是如此。如果为 (past, future) 元组，两个值都必须 > 0。使用最后 n=past 个历史滞后和 n=future 个未来滞后；例如 (-past, -(past - 1), …, -1, 0, 1, …. future - 1)，其中 0 对应于每个样本的第一个预测时间步。如果 output_chunk_shift > 0，负滞后的位置与 lags 和 lags_past_covariates 不同。在这种情况下，未来滞后 -5 将指向与目标滞后 -5 + output_chunk_shift 相同的步。如果为整数列表，仅使用指定的滞后值。如果为字典，键对应于 future_covariates 的分量名称（在使用多个序列时取第一个序列），值对应于分量滞后（元组或整数列表）。键 'default_lags' 可用于为未指定的分量提供默认滞后。如果缺少某些分量且未提供 'default_lags' 键，则会引发错误。

• output_chunk_length (int) – 内部模型一次预测的时间步数（每个块）。这与 predict() 中使用的预测范围 n 不同，预测范围是使用一次性预测或自回归预测生成的所需预测点数。设置 n <= output_chunk_length 可以防止自回归。当协变量在未来的范围不够远时，或者为了禁止模型使用过去和/或未来协变量的未来值进行预测时（取决于模型的协变量支持），这非常有用。

• output_chunk_shift (int) – 可选地，将输出块的起始位置向未来（相对于输入块的结束）移动的步数。这将在输入（目标和过去协变量的历史）和输出之间创建一个间隔。如果模型支持 future_covariates，则 lags_future_covariates 相对于偏移输出块中的第一个步。预测将从目标 series 结束后的 output_chunk_shift 步开始。如果设置了 output_chunk_shift，模型将无法生成自回归预测 (n > output_chunk_length)。

• add_encoders (Optional[dict, None]) –

  可以使用 add_encoders 自动生成大量过去和未来协变量。这可以通过添加多个预定义的索引编码器和/或用作索引编码器的自定义用户定义函数来实现。此外，还可以添加 Darts 的 Scaler 等转换器来转换生成的协变量。这一切都在一个机制下发生，只需在创建模型时指定。阅读 SequentialEncoder 以了解更多关于 add_encoders 的信息。默认值: None。显示 add_encoders 部分功能的示例

  def encode_year(idx):
      return (idx.year - 1950) / 50
  
  add_encoders={
      'cyclic': {'future': ['month']},
      'datetime_attribute': {'future': ['hour', 'dayofweek']},
      'position': {'past': ['relative'], 'future': ['relative']},
      'custom': {'past': [encode_year]},
      'transformer': Scaler(),
      'tz': 'CET'
  }
  

• likelihood (Optional[str, None]) – 可以设置为 poisson 或 quantile。如果设置，模型将具有概率性，允许在预测时进行采样。这将覆盖任何 objective 参数。

• quantiles (Optional[list[float], None]) – 如果 likelihood 设置为 quantile，则使用这些分位数拟合模型。

• random_state (Optional[int, None]) – 控制拟合过程和采样的随机性。默认值: None。

• multi_models (Optional[bool, None]) – 如果为 True，将为预测的每个未来滞后训练一个单独的模型。如果为 False，则训练一个模型来预测 'output_chunk_length' 中的所有步（每个步 n 的特征滞后会向后偏移 output_chunk_length - n）。默认值: True。

• use_static_covariates (bool) – 输入到 fit() 的 series 包含静态协变量时，模型是否应该使用静态协变量信息。如果为 True，并且在拟合时静态协变量可用，将强制所有目标 series 在 fit() 和 predict() 中具有相同的静态协变量维度。

• **kwargs – 传递给 xgb.XGBRegressor 的额外关键字参数。

示例

确定性预测，使用过去/未来协变量（可选）

>>> from darts.datasets import WeatherDataset
>>> from darts.models import XGBModel
>>> series = WeatherDataset().load()
>>> # predicting atmospheric pressure
>>> target = series['p (mbar)'][:100]
>>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100)
>>> past_cov = series['rain (mm)'][:100]
>>> # optionally, use future temperatures (pretending this component is a forecast)
>>> future_cov = series['T (degC)'][:106]
>>> # predict 6 pressure values using the 12 past values of pressure and rainfall, as well as the 6 temperature
>>> # values corresponding to the forecasted period
>>> model = XGBModel(
>>>     lags=12,
>>>     lags_past_covariates=12,
>>>     lags_future_covariates=[0,1,2,3,4,5],
>>>     output_chunk_length=6,
>>> )
>>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
>>> pred = model.predict(6)
>>> pred.values()
array([[1005.9185 ],
       [1005.8315 ],
       [1005.7878 ],
       [1005.72626],
       [1005.7475 ],
       [1005.76074]])

属性

考虑静态协变量	模型是否考虑静态协变量（如果存在）。
极端滞后	一个 8 元组，按顺序包含：(最小目标滞后，最大目标滞后，最小过去协变量滞后，最大过去协变量滞后，最小未来协变量滞后，最大未来协变量滞后，输出偏移，最大目标训练滞后（仅适用于 RNNModel）)。
滞后特征名称	模型训练时使用的滞后特征名称。
滞后标签名称	模型估计器的滞后标签名称。
似然	返回模型用于概率预测的似然（如果存在）。
最小训练样本数	训练模型的最小样本数。
输出块长度	模型一次预测的时间步数，统计模型未定义。
输出块偏移	输出/预测开始于输入结束之后的时间步数。
支持未来协变量	模型是否支持未来协变量
支持似然参数预测	模型实例是否支持直接预测似然参数
支持多元	如果可用，使用 model 原生的多元支持。
支持优化的历史预测	模型是否支持优化的历史预测
支持过去协变量	模型是否支持过去协变量
支持概率预测	检查具有此配置的预测模型是否支持概率预测。
支持样本权重	模型在训练期间是否支持验证集。
支持静态协变量	模型是否支持静态协变量
支持可迁移序列预测	模型是否支持对任何输入 series 进行预测。
支持验证集	模型在训练期间是否支持验证集。
使用未来协变量	模型拟合后是否使用未来协变量。
使用过去协变量	模型拟合后是否使用过去协变量。
使用静态协变量	模型拟合后是否使用静态协变量。
验证集参数	返回验证集的参数名称，如果支持验证集，还返回验证样本权重。

模型参数

方法

backtest(series[, past_covariates, ...])	计算模型在（可能多个）series 上进行历史预测时产生的误差值。
fit(series[, past_covariates, ...])	使用提供的特征时间序列列表和目标时间序列拟合/训练模型。
generate_fit_encodings(series[, ...])	生成用于拟合模型的协变量编码，并返回一个包含原始和编码协变量堆叠在一起的过去和未来协变量序列的元组。
generate_fit_predict_encodings(n, series[, ...])	为训练和推理/预测生成协变量编码，并返回一个包含原始和编码协变量堆叠在一起的过去和未来协变量序列的元组。
generate_predict_encodings(n, series[, ...])	为推理/预测集生成协变量编码，并返回一个包含原始和编码协变量堆叠在一起的过去和未来协变量序列的元组。
get_estimator(horizon, target_dim[, quantile])	返回预测 `horizon` 步和 `target_dim` 目标分量的估计器。
gridsearch(parameters, series[, ...])	使用网格搜索在一组给定参数中找到最佳超参数。
historical_forecasts(series[, ...])	通过在提供的（可能多个）series 的整个历史中模拟不同时间点的预测来生成历史预测。
load(path)	从给定路径或文件句柄加载模型。
predict(n[, series, past_covariates, ...])	预测序列结束后的 n 个时间步的值。
residuals(series[, past_covariates, ...])	计算模型在（可能多个）series 上进行历史预测时产生的残差。
save([path, clean])	将模型保存到给定路径或文件句柄。
未训练的模型()	返回使用相同参数创建的新的（未训练）模型实例。

backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

计算模型在（可能多个）series 上进行历史预测时产生的误差值。

如果提供了 historical_forecasts，则直接在所有预测和实际值上评估指标（由 metric 函数给出）。必须传入用于生成历史预测的相同 series 和 last_points_only 值。最后，该方法返回所有这些指标分数的可选 reduction（默认为均值）。

如果 historical_forecasts 为 None，它首先根据下面给出的参数生成历史预测（有关详细信息，请参阅 ForecastingModel.historical_forecasts()），然后按照上述描述进行评估。

指标可以通过 metric_kwargs 进一步定制（例如，控制分量、时间步、多个序列的聚合，以及分位数指标所需的其他参数 q 等）。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续训练（如果 retrain 不为 False）并计算历史预测的（序列）目标时间序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。

• historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – 可选地，要评估的（或序列/序列的序列）历史预测时间序列。对应于 historical_forecasts() 的输出。必须传入用于生成历史预测的相同 series 和 last_points_only 值。如果提供，将跳过历史预测，并忽略除 series、last_points_only、metric 和 reduction 之外的所有参数。

• forecast_horizon (int) – 预测的预测范围。

• num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用值 >1。

• train_length (Optional[int, None]) – 可选地，为每个构建的训练集使用固定长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时它使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。

• start (Union[Timestamp, float, int, None]) –

  可选地，计算预测的第一个时间点。此参数支持: float, int, pandas.Timestamp, 和 None。如果为 float，则表示第一个预测点之前的时间序列比例。如果为 int，对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

  • 如果 retrain 为 False>，或 retrain 是一个可调用对象且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。

  • 如果 retrain 为 True 或 int（给定 train_length），或 retrain 是一个 Callable 且第一个可训练点早于第一个可预测点，则设置为第一个可训练点。

  • 否则为第一个可训练点（给定 train_length）

  注意：如果 start 不在可训练/可预测点范围内，则使用最接近 start 且是 stride 倍数的有效起始点。

  是 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。

  注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会

  向未来偏移 output_chunk_shift 个点。

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数

  （使用 None 时的默认行为）并从第一个可训练/可预测点开始。

• start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果值不在 series 的索引中，将引发错误。默认值: 'value'。

• stride (int) – 两个连续预测之间的时间步数。

• retrain (Union[bool, int, Callable[…, bool]]) –

  是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool，（正）int，以及 Callable（返回 bool）。 对于 bool 类型：在每个步骤重新训练模型（True），或从不重新训练模型（False）。 对于 int 类型：模型每 retrain 次迭代重新训练一次。 对于 Callable 类型：当可调用对象返回 True 时，模型会重新训练。 可调用对象必须具有以下位置参数

  • counter (int): 当前 retrain 迭代次数

  • pred_time (pd.Timestamp 或 int): 预测时间戳（训练序列的结束时间）

  • train_series (TimeSeries): 直至 pred_time 的训练序列

  • past_covariates (TimeSeries): 直至 pred_time 的过去协变量序列

  • future_covariates (TimeSeries): 直至 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

  注意：如果没有将任何可选的 *_covariates 传递给 historical_forecast，则将 None 传递给相应的 retrain 函数参数。注意：有些模型需要每次都重新训练，不支持除 retrain=True 之外的任何值。注意：这也控制了 data_transformers 的重新训练。

• overlap_end (bool) – 返回的预测是否可以超出序列的末尾。

• last_points_only (bool) – 是否只返回每个历史预测的最后一个点。如果设置为 True，该方法返回一个包含连续点预测的单个 TimeSeries（对于 series 中的每个时间序列）。否则，返回历史 TimeSeries 预测的列表。

• metric (Union[Callable[…, Union[float, list[float], ndarray, list[ndarray]]], list[Callable[…, Union[float, list[float], ndarray, list[ndarray]]]]]) – 一个指标函数或一个指标函数列表。每个指标必须是 Darts 指标（参见此处），或者是一个具有与 Darts 指标相同签名的自定义指标，使用装饰器 multi_ts_support() 并返回指标分数。

• reduction (Optional[Callable[…, float], None]) – 当 last_points_only 设置为 False 时，用于组合获得的单个误差分数的函数。当提供多个指标函数时，该函数将接收参数 axis = 1，以便为每个指标函数获得单个值。如果明确设置为 None，该方法将返回单个误差分数的列表。默认为 np.mean。

• verbose (bool) – 是否打印进度。

• show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。

• predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然的概率模型，且 num_samples = 1 和 n<=output_chunk_length。默认值: False。

• enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值: True。

• data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –

  可选地，一个字典，包含要应用于相应序列的 BaseDataTransformer 或 Pipeline（可能的键：“series”、“past_covariates”、“future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合转换器/管道

  • 如果 retrain=True，数据转换器在每个历史预测步骤重新拟合训练数据。

  • 如果 retrain=False，数据转换器在所有预测之前转换一次序列。

  拟合的转换器用于在训练和预测期间转换输入。如果转换是可逆的，预测将被反向转换。仅当 historical_forecasts=None 时有效。

• metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – 传递给 metric() 的额外参数，例如用于并行化的 ‘n_jobs’，用于减少分量维度指标的 ‘component_reduction’，用于缩放指标的季节性 ‘m’ 等。将参数分别传递给每个指标，并且仅当参数存在于相应的指标签名中时才会传递。缩放指标（例如 mase`, rmsse 等）的参数 ‘insample’ 会被忽略，因为它在内部处理。

• fit_kwargs (Optional[dict[str, Any], None]) – 可选地，传递给模型 fit() 方法的一些额外参数。

• predict_kwargs (Optional[dict[str, Any], None]) – 可选地，传递给模型 predict() 方法的一些额外参数。

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选地，应用于训练时目标 series 标签的一些样本权重。仅当 retrain 不为 False 时有效。它们按观测、按标签（output_chunk_length 中的每个步）和按分量应用。如果是一个或一系列序列，则使用这些权重。如果权重序列只有一个分量/列，则权重全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的数量匹配。如果为字符串，则使用内置加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减——越远的过去，权重越低。权重根据 series 中最长序列的长度全局计算。然后对于每个序列，从全局权重的末尾提取权重。这在所有序列上提供了一个共同的时间权重。

返回类型

Union[float, ndarray, list[float], list[ndarray]]

返回

• float – 单个单/多元序列、单个 metric 函数以及

  • 使用 last_points_only=True 生成的 historical_forecasts 的单个回测分数

  • 使用 last_points_only=False 生成的 historical_forecasts 并使用回测 reduction 的单个回测分数

• np.ndarray – 回测分数的 numpy 数组。对于单个序列和以下之一：

  • 单个 metric 函数，使用 last_points_only=False 生成的 historical_forecasts 和回测 reduction=None。输出形状为 (n forecasts, *)。

  • 多个 metric 函数以及使用 last_points_only=False 生成的 historical_forecasts。使用回测 reduction 时，输出形状为 (*, n metrics)，当 reduction=None 时，输出形状为 (n forecasts, *, n metrics)

  • 多个单/多元序列，包括 series_reduction，并且至少有一个 component_reduction=None 或 time_reduction=None 用于“每时间步指标”

• List[float] – 与 float 类型相同，但适用于序列的序列。返回的指标列表长度为 len(series)，包含每个输入 series 的 float 指标。

• List[np.ndarray] – 与 np.ndarray 类型相同，但适用于序列的序列。返回的指标列表长度为 len(series)，包含每个输入 series 的 np.ndarray 指标。

property considers_static_covariates: bool

模型是否考虑静态协变量（如果存在）。

返回类型

bool

property extreme_lags: tuple[Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], Optional[int], int, Optional[int]]

一个 8 元组，按顺序包含：(最小目标滞后，最大目标滞后，最小过去协变量滞后，最大过去协变量滞后，最小未来协变量滞后，最大未来协变量滞后，输出偏移，最大目标训练滞后（仅适用于 RNNModel）)。 如果 0 是第一个预测的索引，则所有滞后都相对于此索引。

请参阅下面的示例。

如果模型未拟合

• 目标（仅涉及 RegressionModels）：则第一个元素应为 None。

• 过去协变量：则第三和第四个元素应为 None。

• 未来协变量：则第五和第六个元素应为 None。

使用过去或未来协变量的模型，以及/或最小目标滞后和最大目标滞后可能与 -1 和 0 不同的模型应覆盖此属性。

注意

最大目标滞后（第二个值）不能为 None，且始终大于或等于 0。

示例

>>> model = LinearRegressionModel(lags=3, output_chunk_length=2)
>>> model.fit(train_series)
>>> model.extreme_lags
(-3, 1, None, None, None, None, 0, None)
>>> model = LinearRegressionModel(lags=3, output_chunk_length=2, output_chunk_shift=2)
>>> model.fit(train_series)
>>> model.extreme_lags
(-3, 1, None, None, None, None, 2, None)
>>> model = LinearRegressionModel(lags=[-3, -5], lags_past_covariates = 4, output_chunk_length=7)
>>> model.fit(train_series, past_covariates=past_covariates)
>>> model.extreme_lags
(-5, 6, -4, -1,  None, None, 0, None)
>>> model = LinearRegressionModel(lags=[3, 5], lags_future_covariates = [4, 6], output_chunk_length=7)
>>> model.fit(train_series, future_covariates=future_covariates)
>>> model.extreme_lags
(-5, 6, None, None, 4, 6, 0, None)
>>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7)
>>> model.fit(train_series)
>>> model.extreme_lags
(-10, 6, None, None, None, None, 0, None)
>>> model = NBEATSModel(input_chunk_length=10, output_chunk_length=7, lags_future_covariates=[4, 6])
>>> model.fit(train_series, future_covariates)
>>> model.extreme_lags
(-10, 6, None, None, 4, 6, 0, None)

返回类型

tuple[Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], int, Optional[int, None]]

fit(series, past_covariates=None, future_covariates=None, val_series=None, val_past_covariates=None, val_future_covariates=None, max_samples_per_ts=None, n_jobs_multioutput_wrapper=None, sample_weight=None, val_sample_weight=None, **kwargs)

使用提供的特征时间序列列表和目标时间序列拟合/训练模型。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – TimeSeries 或 Sequence[TimeSeries] 对象，包含目标值。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个或一系列序列，指定过去观测的协变量

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个或一系列序列，指定未来已知的协变量

• val_series (Union[TimeSeries, Sequence[TimeSeries], None]) – TimeSeries 或 Sequence[TimeSeries] 对象，包含评估数据集的目标值。

• val_past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个或一系列序列，指定评估数据集的过去观测协变量

• val_future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个或一系列序列，指定评估数据集的未来已知协变量

• max_samples_per_ts (Optional[int, None]) – 这是每个时间序列可生成的元组数量的整数上限。可用于限制数据集的总大小并确保正确采样。如果为 None，它将在创建数据集时提前读取所有单个时间序列以了解其大小，这在大数据集上可能开销较大。如果某些序列的长度允许生成超过 max_samples_per_ts 的样本，则只会考虑最新的 max_samples_per_ts 个样本。

• n_jobs_multioutput_wrapper (Optional[int, None]) – MultiOutputRegressor 包装器并行运行的作业数。仅当模型原生不支持多输出回归时使用。

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选地，应用于训练时目标 series 标签的一些样本权重。它们按观测、按标签（output_chunk_length 中的每个步）和按分量应用。如果是一个或一系列序列，则使用这些权重。如果权重序列只有一个分量/列，则权重全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的数量匹配。如果为字符串，则使用内置加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减——越远的过去，权重越低。权重根据 series 中最长序列的长度全局计算。然后对于每个序列，从全局权重的末尾提取权重。这在所有序列上提供了一个共同的时间权重。

• val_sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 与 sample_weight 相同，但用于评估数据集。

• **kwargs – 传递给 xgb.XGBRegressor.fit() 的额外 kwargs

generate_fit_encodings(series, past_covariates=None, future_covariates=None)

生成用于拟合模型的协变量编码，并返回一个包含原始和编码协变量堆叠在一起的过去和未来协变量序列的元组。编码由模型创建时参数 add_encoders 定义的编码器生成。传入与训练/拟合模型时使用的相同的 series、past_covariates 和 future_covariates。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 拟合模型时使用的包含目标值的序列或序列的序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）用于拟合模型时，包含过去观测协变量的时间序列或时间序列序列。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）用于拟合模型时，包含未来已知协变量的时间序列或时间序列序列。

返回

一个包含（过去协变量，未来协变量）的元组。每个协变量都包含原始协变量和编码后的协变量。

返回类型

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)

生成用于训练和推断/预测的协变量编码，并返回一个包含过去协变量和未来协变量序列的元组，其中原始协变量和编码协变量被堆叠在一起。编码是由模型创建时通过参数 add_encoders 定义的编码器生成的。请传递您打算用于训练和预测的相同的 series、past_covariates 和 future_covariates。

参数

• n (int) – 意图用于预测时，series 结束之后的预测时间步数。

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 意图用于训练和预测时，包含目标值的时间序列或时间序列序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）意图用于训练和预测时，包含过去观测协变量的时间序列。其维度必须与训练时使用的协变量维度一致。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）意图用于预测时，包含未来已知协变量的时间序列。其维度必须与训练时使用的协变量维度一致。

返回

一个包含（过去协变量，未来协变量）的元组。每个协变量都包含原始协变量和编码后的协变量。

返回类型

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)

生成用于推断/预测集的协变量编码，并返回一个包含过去协变量和未来协变量序列的元组，其中原始协变量和编码协变量被堆叠在一起。编码是由模型创建时通过参数 add_encoders 定义的编码器生成的。请传递您打算用于预测的相同的 series、past_covariates 和 future_covariates。

参数

• n (int) – 意图用于预测时，series 结束之后的预测时间步数。

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 意图用于预测时，包含目标值的时间序列或时间序列序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）意图用于预测时，包含过去观测协变量的时间序列。其维度必须与训练时使用的协变量维度一致。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）意图用于预测时，包含未来已知协变量的时间序列。其维度必须与训练时使用的协变量维度一致。

返回

一个包含（过去协变量，未来协变量）的元组。每个协变量都包含原始协变量和编码后的协变量。

返回类型

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

get_estimator(horizon, target_dim, quantile=None)

返回预测第 target_dim 个目标分量的第 horizon 步的估计器。

对于拟合分位数的概率模型，也可以指定分位数。

如果模型原生支持多输出，则直接返回模型。

注意：在内部，估计器按 output_chunk_length 位置分组，然后按分量分组。对于拟合分位数的概率模型，还有一个额外的抽象层，按 quantile 对估计器进行分组。

参数

• horizon (int) – output_chunk_length 内的预测点索引。

• target_dim (int) – 目标分量的索引。

• quantile (Optional[float, None]) – （可选）对于使用 likelihood=”quantile” 的概率模型，指定一个分位数。

classmethod gridsearch(parameters, series, past_covariates=None, future_covariates=None, forecast_horizon=None, stride=1, start=None, start_format='value', last_points_only=False, show_warnings=True, val_series=None, use_fitted_values=False, metric=<function mape>, reduction=<function mean>, verbose=False, n_jobs=1, n_random_samples=None, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

使用网格搜索在一组给定参数中找到最佳超参数。

此函数有 3 种操作模式：扩展窗口模式（Expanding window mode）、分割模式（split mode）和拟合值模式（fitted value mode）。这三种操作模式通过实例化 ForecastingModel 的 model_class 子类，并使用 parameters 字典中提供的超参数值的每种可能组合来评估，然后返回根据 metric 函数表现最佳的模型。metric 函数应返回一个误差值，因此将选择 metric 输出最小的模型。

训练数据和测试数据的关系取决于操作模式。

扩展窗口模式（传递 forecast_horizon 时激活）：对于每种超参数组合，模型会在 series 的不同分割上重复进行训练和评估。这个过程通过使用 backtest() 函数作为子程序来完成，从 start 开始生成历史预测，并与 series 的真实值进行比较。请注意，模型会为每个单独的预测重新训练，因此此模式较慢。

分割窗口模式（传递 val_series 时激活）：当传递 val_series 参数时将使用此模式。对于每种超参数组合，模型会在 series 上训练，并在 val_series 上评估。

拟合值模式（将 use_fitted_values 设置为 True 时激活）：对于每种超参数组合，模型会在 series 上训练，并根据生成的拟合值进行评估。并非所有模型都有拟合值，如果模型没有 fitted_values 成员，此方法将引发错误。拟合值是模型在 series 上拟合的结果。与拟合值进行比较是评估模型的一种快速方法，但无法判断模型是否对序列过拟合。

派生类必须确保模型的单个实例不会与其他实例共享参数，例如，将模型保存在同一路径下。否则，在并行运行多个模型时（当 n_jobs != 1 时）可能会出现意外行为。如果无法避免这种情况，则应重新定义 gridsearch，强制设置 n_jobs = 1。

目前此方法仅支持确定性预测（即当模型的预测只有 1 个样本时）。

参数

• model_class – 要针对 ‘series’ 进行调优的 ForecastingModel 子类。

• parameters (dict) – 一个字典，其键是超参数名称，其值是相应超参数的值列表。

• series (TimeSeries) – 用作训练输入和目标的序列。

• past_covariates (Optional[TimeSeries, None]) – （可选）一个过去观测的协变量序列。这仅在模型支持过去协变量时适用。

• future_covariates (Optional[TimeSeries, None]) – （可选）一个未来已知的协变量序列。这仅在模型支持未来协变量时适用。

• forecast_horizon (Optional[int, None]) – 预测范围的整数值。激活扩展窗口模式。

• stride (int) – 仅在扩展窗口模式下使用。两次连续预测之间的时间步数。

• start (Union[Timestamp, float, int, None]) –

  仅在扩展窗口模式下使用。（可选）计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果是 float，则表示时间序列中应位于第一个预测点之前的比例。如果是 int，则对于带有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于带有 pd.RangeIndex 的 series，它是索引值。后者可以使用 start_format=”position” 更改为索引位置。如果是 pandas.Timestamp，它是第一个预测点的时间戳。如果是 None，第一个预测点将自动设置为

  • 如果 retrain 为 False>，或 retrain 是一个可调用对象且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。

  • 如果 retrain 为 True 或 int（给定 train_length），或者 retrain 是一个 Callable 且第一个可训练点早于第一个可预测点，则设置为第一个可训练点。

  • 否则为第一个可训练点（给定 train_length）

  注意：如果 start 不在可训练/可预测点范围内，则使用最接近 start 且是 stride 倍数的有效起始点。

  是 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。

  注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会

  向未来偏移 output_chunk_shift 个点。

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数

  （使用 None 时的默认行为）并从第一个可训练/可预测点开始。

• start_format (Literal[‘position’, ‘value’]) – 仅在扩展窗口模式下使用。定义 start 的格式。仅当 start 是整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 ‘value’，start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'

• last_points_only (bool) – 仅在扩展窗口模式下使用。是使用整个预测序列，还是仅使用每个预测序列的最后一个点来计算误差。

• show_warnings (bool) – 仅在扩展窗口模式下使用。是否显示与 start 参数相关的警告。

• val_series (Optional[TimeSeries, None]) – 在分割模式下用于验证的 TimeSeries 实例。如果提供，此序列必须紧接在 series 结束之后开始；以便进行适当的预测比较。

• use_fitted_values (bool) – 如果为 True，则使用与拟合值的比较。如果 fitted_values 不是 model_class 的属性，则引发错误。

• metric (Callable[[TimeSeries, TimeSeries], float]) –

  一个将两个 TimeSeries 之间的误差作为浮点值返回的指标函数。必须是 Darts 的“按时间聚合”指标之一（参见此处），或一个自定义指标，该自定义指标接收两个 TimeSeries 作为输入并返回误差

• reduction (Callable[[ndarray], float]) – 一个归约函数（将数组映射为浮点数），描述如何在回测时聚合在不同验证序列上获得的误差。默认情况下，它将计算误差的平均值。

• verbose – 是否打印进度。

• n_jobs (int) – 并行运行的作业数。仅当有两个或更多参数组合需要评估时才会创建并行作业。每个作业将实例化、训练和评估模型的不同实例。默认为 1 (顺序执行)。将参数设置为 -1 意味着使用所有可用的核心。

• n_random_samples (Union[int, float, None]) – 从完整参数网格中选择的超参数组合的数量/比例。这将执行随机搜索而不是使用完整网格。如果为整数，n_random_samples 是从完整网格中选择的参数组合数，必须在 0 和参数组合总数之间。如果为浮点数，n_random_samples 是从完整网格中选择的参数组合比例，必须在 0 和 1 之间。默认为 None，此时将忽略随机选择。

• data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –

  可选地，一个字典，包含要应用于相应序列的 BaseDataTransformer 或 Pipeline（可能的键：“series”、“past_covariates”、“future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合转换器/管道

  • 如果 retrain=True，数据转换器在每个历史预测步骤重新拟合训练数据。

  • 如果 retrain=False，数据转换器在所有预测之前转换一次序列。

  拟合的转换器用于在训练和预测期间转换输入。如果转换是可逆的，预测结果将被逆向转换。

• fit_kwargs (Optional[dict[str, Any], None]) – 传递给模型 fit() 方法的额外参数。

• predict_kwargs (Optional[dict[str, Any], None]) – 传递给模型 predict() 方法的额外参数。

• sample_weight (Union[TimeSeries, str, None]) – （可选）应用于目标 series 标签进行训练的样本权重。仅当 retrain 不是 False 时有效。权重应用于每个观测、每个标签（output_chunk_length 中的每一步）和每个分量。如果是一个序列，则使用这些权重。如果权重序列只有一个分量/列，则权重将全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的数量匹配。如果是一个字符串，则使用内置加权函数生成权重。可用选项是“线性”或“指数”衰减——时间越远，权重越低。

返回

一个元组，包含使用表现最佳的超参数创建的未训练的 model_class 实例，以及一个包含这些最佳超参数的字典，以及最佳超参数的指标得分。

返回类型

ForecastingModel, Dict, float

historical_forecasts(series, past_covariates=None, future_covariates=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

通过模拟在提供的（可能多个）series 历史记录中不同时间点的预测来生成历史预测。这个过程涉及将模型追溯性地应用于不同的时间步长，就像预测是在这些特定时刻实时进行的一样。这允许评估模型在整个序列持续时间内的性能，从而提供关于其在不同历史时期内的预测准确性和鲁棒性的见解。

此方法有两种主要模式

• 再训练模式（默认，retrain=True）：模型在模拟的每个步骤中都会重新训练，并使用更新后的模型生成预测。如果存在多个序列，模型会针对每个序列独立地重新训练（尚不支持全局训练）。

• 预训练模式（retrain=False）：预测在模拟的每个步骤中生成，无需重新训练。仅支持预训练的全局预测模型。此模式跳过了重新训练步骤，因此速度明显更快。

通过选择适当的模式，您可以在计算效率和最新模型训练的需求之间取得平衡。

再训练模式： 此模式通过从 series 的开头扩展或使用固定长度的 train_length （起始点也可以使用 start 和 start_format 进行配置）重复构建训练集。然后在此训练集上训练模型，并生成长度为 forecast_horizon 的预测。随后，训练集的结束点向前移动 stride 个时间步，并重复该过程。

预训练模式： 此模式仅支持预训练的全局预测模型。它使用与 再训练模式 中相同的模拟步骤（忽略 train_length），但直接生成预测而无需重新训练。

默认情况下，如果设置 last_points_only=True，此方法返回一个时间序列（或时间序列序列），由每个历史预测的最后一个点组成。因此，此时间序列的频率将是 series.freq * stride。如果设置 last_points_only=False，它将返回一个列表（或列表序列），其中包含完整的历史预测序列，每个序列的频率为 series.freq。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续训练（如果 retrain 不为 False）并计算历史预测的（序列）目标时间序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。

• forecast_horizon (int) – 预测的预测范围。

• num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用值 >1。

• train_length (Optional[int, None]) – 可选地，为每个构建的训练集使用固定长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时它使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。

• start (Union[Timestamp, float, int, None]) –

  可选地，计算预测的第一个时间点。此参数支持: float, int, pandas.Timestamp, 和 None。如果为 float，则表示第一个预测点之前的时间序列比例。如果为 int，对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

  • 如果 retrain 为 False>，或 retrain 是一个可调用对象且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。

  • 如果 retrain 为 True 或 int（给定 train_length），或 retrain 是一个 Callable 且第一个可训练点早于第一个可预测点，则设置为第一个可训练点。

  • 否则为第一个可训练点（给定 train_length）

  注意：如果 start 不在可训练/可预测点范围内，则使用最接近 start 且是 stride 倍数的有效起始点。

  是 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。

  注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会

  向未来偏移 output_chunk_shift 个点。

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数

  （使用 None 时的默认行为）并从第一个可训练/可预测点开始。

• start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果值不在 series 的索引中，将引发错误。默认值: 'value'。

• stride (int) – 两个连续预测之间的时间步数。

• retrain (Union[bool, int, Callable[…, bool]]) –

  是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool，（正）int，以及 Callable（返回 bool）。 对于 bool 类型：在每个步骤重新训练模型（True），或从不重新训练模型（False）。 对于 int 类型：模型每 retrain 次迭代重新训练一次。 对于 Callable 类型：当可调用对象返回 True 时，模型会重新训练。 可调用对象必须具有以下位置参数

  • counter (int): 当前 retrain 迭代次数

  • pred_time (pd.Timestamp 或 int): 预测时间戳（训练序列的结束时间）

  • train_series (TimeSeries): 直至 pred_time 的训练序列

  • past_covariates (TimeSeries): 直至 pred_time 的过去协变量序列

  • future_covariates (TimeSeries): 直至 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

  注意：如果没有将任何可选的 *_covariates 传递给 historical_forecast，则将 None 传递给相应的 retrain 函数参数。注意：有些模型需要每次都重新训练，不支持除 retrain=True 之外的任何值。注意：这也控制了 data_transformers 的重新训练。

• overlap_end (bool) – 返回的预测是否可以超出序列的末尾。

• last_points_only (bool) – 是否只返回每个历史预测的最后一个点。如果设置为 True，该方法返回一个包含连续点预测的单个 TimeSeries（对于 series 中的每个时间序列）。否则，返回历史 TimeSeries 预测的列表。

• verbose (bool) – 是否打印进度。

• show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。

• predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然的概率模型，且 num_samples = 1 和 n<=output_chunk_length。默认值: False。

• enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值: True。

• data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –

  可选地，一个字典，包含要应用于相应序列的 BaseDataTransformer 或 Pipeline（可能的键：“series”、“past_covariates”、“future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合转换器/管道

  • 如果 retrain=True，数据转换器在每个历史预测步骤重新拟合训练数据。

  • 如果 retrain=False，数据转换器在所有预测之前转换一次序列。

  拟合的转换器用于在训练和预测期间转换输入。如果转换是可逆的，预测结果将被逆向转换。

• fit_kwargs (Optional[dict[str, Any], None]) – 可选地，传递给模型 fit() 方法的一些额外参数。

• predict_kwargs (Optional[dict[str, Any], None]) – 可选地，传递给模型 predict() 方法的一些额外参数。

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选地，应用于训练时目标 series 标签的一些样本权重。仅当 retrain 不为 False 时有效。它们按观测、按标签（output_chunk_length 中的每个步）和按分量应用。如果是一个或一系列序列，则使用这些权重。如果权重序列只有一个分量/列，则权重全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的数量匹配。如果为字符串，则使用内置加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减——越远的过去，权重越低。权重根据 series 中最长序列的长度全局计算。然后对于每个序列，从全局权重的末尾提取权重。这在所有序列上提供了一个共同的时间权重。

返回类型

Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

返回

• TimeSeries – 对于单个 series 且 last_points_only=True 的单个历史预测：它仅包含所有历史预测中 forecast_horizon 步的预测。

• List[TimeSeries] – 历史预测列表，用于

  • 一系列（列表）series 且 last_points_only=True：对于每个序列，它仅包含所有历史预测中 forecast_horizon 步的预测。

  • 单个 series 且 last_points_only=False：对于每个历史预测，它包含整个预测范围 forecast_horizon。

• List[List[TimeSeries]] – 对于一系列 series 且 last_points_only=False，这是一个残差 TimeSeries 的列表的列表。外层残差列表的长度为 len(series)。内层列表包含所有可能的序列特定历史预测的残差。

property lagged_feature_names: Optional[list[str]]

模型训练时使用的滞后特征名称。

目标、过去和未来协变量的命名约定是："{name}_{type}_lag{i}"，其中

• {name} (第一个)序列的分量名称

• {type} 是特征类型，可以是“target”、“pastcov”和“futcov”之一

• {i} 是滞后值

静态协变量的命名约定是："{name}_statcov_target_{comp}"，其中

• {name} (第一个)序列的静态协变量名称

• {comp} (第一个)静态协变量作用的目标分量名称。如果静态

  协变量全局作用于多元目标序列，则显示“global”。

返回类型

Optional[list[str], None]

property lagged_label_names: Optional[list[str]]

模型估计器的滞后标签名称。

命名约定是："{name}_target_hrz{i}"，其中

• {name} (第一个)序列的分量名称

• {i} 是 output_chunk_length 中的位置（标签滞后）

返回类型

Optional[list[str], None]

property likelihood: Optional[SKLearnLikelihood]

返回模型用于概率预测的似然（如果存在）。

返回类型

Optional[SKLearnLikelihood, None]

static load(path)

从给定路径或文件句柄加载模型。

参数

path (Union[str, PathLike, BinaryIO]) – 加载模型的路径或文件句柄。

返回类型

ForecastingModel

property min_train_samples: int

训练模型的最小样本数。

返回类型

int

property model_params: dict

返回类型

dict

property output_chunk_length: int

模型一次预测的时间步数，统计模型未定义。

返回类型

int

property output_chunk_shift: int

输出/预测开始于输入结束之后的时间步数。

返回类型

int

predict(n, series=None, past_covariates=None, future_covariates=None, num_samples=1, verbose=False, predict_likelihood_parameters=False, show_warnings=True, **kwargs)

预测序列结束后的 n 个时间步的值。

参数

• n (int) – 预测范围 - 在序列结束之后需要生成预测的时间步数。

• series (TimeSeries or list of TimeSeries, optional) – （可选）一个或多个输入 TimeSeries，表示其未来将被预测的目标序列的历史记录。如果指定，该方法返回这些序列的预测结果。否则，该方法返回（单个）训练序列的预测结果。

• past_covariates (TimeSeries or list of TimeSeries, optional) – （可选）作为模型输入所需的过去观测协变量序列。它们在维度和类型上必须与训练时使用的协变量匹配。

• future_covariates (TimeSeries or list of TimeSeries, optional) – （可选）作为模型输入所需的未来已知协变量序列。它们在维度和类型上必须与训练时使用的协变量匹配。

• num_samples (int, default: 1) – 从概率模型中采样预测的次数。对于确定性模型应设置为 1。

• verbose (bool) – 是否打印进度。

• predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标值。仅支持具有 likelihood 的概率模型，并且 num_samples = 1 且 n<=output_chunk_length。默认值：False

• **kwargs (dict, optional) – 传递给模型 predict 方法的额外关键字参数。仅适用于单变量目标序列。

• show_warnings (bool) – （可选）控制是否显示警告。并非对所有模型都有效。

返回类型

Union[TimeSeries, Sequence[TimeSeries]]

residuals(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, metric=<function err>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None, values_only=False)

计算模型在（可能多个）series 上进行历史预测时产生的残差。

此函数计算 series 中的实际观测值与在 series 上训练模型（或使用 retrain=False 的预训练模型）获得的拟合值之间的差值（或 Darts 的“每个时间步”指标之一）。并非所有模型都支持拟合值，因此我们使用历史预测作为它们的近似值。

此方法按顺序执行

• 使用预计算的 historical_forecasts 或为每个序列计算历史预测（详见 historical_forecasts()）。历史预测的生成方式可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 进行配置。

• 计算一个回测，使用“每个时间步”的 metric，在历史预测和 series 之间，按分量/列和时间步进行（详见 backtest()）。默认情况下，使用残差 err() (error) 作为 metric。

• 使用历史预测的时间索引，以及按分量和时间步计算的指标值，创建并返回 TimeSeries （或仅当 values_only=True 时返回一个 np.ndarray）。

此方法适用于单个或多个单变量或多元序列。它使用中位数预测（处理随机预测时）。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续训练（如果 retrain 不为 False）并计算历史预测的（序列）目标时间序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。

• historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – 可选地，要评估的（或序列/序列的序列）历史预测时间序列。对应于 historical_forecasts() 的输出。必须传入用于生成历史预测的相同 series 和 last_points_only 值。如果提供，将跳过历史预测，并忽略除 series、last_points_only、metric 和 reduction 之外的所有参数。

• forecast_horizon (int) – 预测的预测范围。

• num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用值 >1。

• train_length (Optional[int, None]) – 可选地，为每个构建的训练集使用固定长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时它使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。

• start (Union[Timestamp, float, int, None]) –

  可选地，计算预测的第一个时间点。此参数支持: float, int, pandas.Timestamp, 和 None。如果为 float，则表示第一个预测点之前的时间序列比例。如果为 int，对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

  • 如果 retrain 为 False>，或 retrain 是一个可调用对象且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。

  • 如果 retrain 为 True 或 int（给定 train_length），或 retrain 是一个 Callable 且第一个可训练点早于第一个可预测点，则设置为第一个可训练点。

  • 否则为第一个可训练点（给定 train_length）

  注意：如果 start 不在可训练/可预测点范围内，则使用最接近 start 且是 stride 倍数的有效起始点。

  是 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。

  注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会

  向未来偏移 output_chunk_shift 个点。

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数

  （使用 None 时的默认行为）并从第一个可训练/可预测点开始。

• start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果值不在 series 的索引中，将引发错误。默认值: 'value'。

• stride (int) – 两个连续预测之间的时间步数。

• retrain (Union[bool, int, Callable[…, bool]]) –

  是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool，（正）int，以及 Callable（返回 bool）。 对于 bool 类型：在每个步骤重新训练模型（True），或从不重新训练模型（False）。 对于 int 类型：模型每 retrain 次迭代重新训练一次。 对于 Callable 类型：当可调用对象返回 True 时，模型会重新训练。 可调用对象必须具有以下位置参数

  • counter (int): 当前 retrain 迭代次数

  • pred_time (pd.Timestamp 或 int): 预测时间戳（训练序列的结束时间）

  • train_series (TimeSeries): 直至 pred_time 的训练序列

  • past_covariates (TimeSeries): 直至 pred_time 的过去协变量序列

  • future_covariates (TimeSeries): 直至 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

  注意：如果没有将任何可选的 *_covariates 传递给 historical_forecast，则将 None 传递给相应的 retrain 函数参数。注意：有些模型需要每次都重新训练，不支持除 retrain=True 之外的任何值。注意：这也控制了 data_transformers 的重新训练。

• overlap_end (bool) – 返回的预测是否可以超出序列的末尾。

• last_points_only (bool) – 是否只返回每个历史预测的最后一个点。如果设置为 True，该方法返回一个包含连续点预测的单个 TimeSeries（对于 series 中的每个时间序列）。否则，返回历史 TimeSeries 预测的列表。

• metric (Callable[…, Union[float, list[float], ndarray, list[ndarray]]]) –

  Darts 的“每个时间步”指标之一（参见此处），或一个与 Darts 的“每个时间步”指标具有相同签名的自定义指标，该自定义指标使用装饰器 multi_ts_support() 和 multi_ts_support()，并为每个时间步返回一个值。

• verbose (bool) – 是否打印进度。

• show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。

• predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然的概率模型，且 num_samples = 1 和 n<=output_chunk_length。默认值: False。

• enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值: True。

• data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –

  可选地，一个字典，包含要应用于相应序列的 BaseDataTransformer 或 Pipeline（可能的键：“series”、“past_covariates”、“future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合转换器/管道

  • 如果 retrain=True，数据转换器在每个历史预测步骤重新拟合训练数据。

  • 如果 retrain=False，数据转换器在所有预测之前转换一次序列。

  拟合的转换器用于在训练和预测期间转换输入。如果转换是可逆的，预测将被反向转换。仅当 historical_forecasts=None 时有效。

• metric_kwargs (Optional[dict[str, Any], None]) – 传递给 metric() 的额外参数，例如用于并行化的 ‘n_jobs’，用于缩放指标的 ‘m’ 等。仅当参数存在于相应指标签名中时才会传递。忽略归约参数 “series_reduction”、“component_reduction”、“time_reduction” 以及缩放指标（例如 mase、rmsse 等）的参数 ‘insample’，因为它们在内部处理。

• fit_kwargs (Optional[dict[str, Any], None]) – 可选地，传递给模型 fit() 方法的一些额外参数。

• predict_kwargs (Optional[dict[str, Any], None]) – 可选地，传递给模型 predict() 方法的一些额外参数。

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选地，应用于训练时目标 series 标签的一些样本权重。仅当 retrain 不为 False 时有效。它们按观测、按标签（output_chunk_length 中的每个步）和按分量应用。如果是一个或一系列序列，则使用这些权重。如果权重序列只有一个分量/列，则权重全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的数量匹配。如果为字符串，则使用内置加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减——越远的过去，权重越低。权重根据 series 中最长序列的长度全局计算。然后对于每个序列，从全局权重的末尾提取权重。这在所有序列上提供了一个共同的时间权重。

• values_only (bool) – 是否将残差作为 np.ndarray 返回。如果为 False，则将残差作为 TimeSeries 返回。

返回类型

Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

返回

• TimeSeries – 对于单个 series 且使用 last_points_only=True 生成的 historical_forecasts 的残差 TimeSeries。

• List[TimeSeries] – 对于一系列（列表）series 且 last_points_only=True 的残差 TimeSeries 列表。残差列表的长度为 len(series)。

• List[List[TimeSeries]] – 对于一系列 series 且 last_points_only=False，这是一个残差 TimeSeries 的列表的列表。外层残差列表的长度为 len(series)。内层列表包含所有可能的序列特定历史预测的残差。

save(path=None, clean=False, **pkl_kwargs)

将模型保存到给定路径或文件句柄。

保存和加载 RegressionModel 的示例

from darts.models import RegressionModel

model = RegressionModel(lags=4)

model.save("my_model.pkl")
model_loaded = RegressionModel.load("my_model.pkl")

参数

• path (Union[str, PathLike, BinaryIO, None]) – 保存模型当前状态的路径或文件句柄。如果未指定路径，模型将自动保存为 "{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.pkl"。例如，"RegressionModel_2020-01-01_12_00_00.pkl"。

• clean (bool) –

  是否存储模型的清理版本。仅对全局预测模型有效。如果为 True，则移除训练序列和协变量。

  注意：加载使用 clean=True 存储的全局预测模型后，必须将 series 传递给 ‘predict()’、historical_forecasts() 和其他预测方法。

• pkl_kwargs – 传递给 pickle.dump() 的关键字参数

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

bool

property supports_likelihood_parameter_prediction: bool

模型实例是否支持直接预测似然参数

返回类型

bool

property supports_multivariate: bool

如果可用，使用 model 的原生多元支持。如果不可用，则通过将单变量模型包装在 sklearn.multioutput.MultiOutputRegressor 中来获得多元支持。

返回类型

bool

property supports_optimized_historical_forecasts: bool

模型是否支持优化的历史预测

返回类型

bool

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

bool

property supports_probabilistic_prediction: bool

检查具有此配置的预测模型是否支持概率预测。

默认返回 False。需要由支持概率预测的模型覆盖。

返回类型

bool

property supports_sample_weight: bool

模型在训练期间是否支持验证集。

返回类型

bool

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

bool

property supports_transferable_series_prediction: bool

模型是否支持对任何输入 series 进行预测。

返回类型

bool

property supports_val_set: bool

模型在训练期间是否支持验证集。

返回类型

bool

untrained_model()

返回使用相同参数创建的新的（未训练）模型实例。

property uses_future_covariates: bool

模型拟合后是否使用未来协变量。

返回类型

bool

property uses_past_covariates: bool

模型拟合后是否使用过去协变量。

返回类型

bool

property uses_static_covariates: bool

模型拟合后是否使用静态协变量。

返回类型

bool

property val_set_params: tuple[Optional[str], Optional[str]]

返回验证集的参数名称，如果支持验证集，还返回验证样本权重。

返回类型

tuple[Optional[str, None], Optional[str, None]]

darts.models.forecasting.xgboost.xgb_quantile_loss(labels, preds, quantile)

用于 XGBoost 计算分位数损失梯度的自定义损失函数。

灵感来源：https://gist.github.com/Nikolay-Lysenko/06769d701c1d9c9acb9a66f2f9d7a6c7

这计算了预测值与目标标签之间的 pinball 损失的梯度。

上一页

VARIMA

下一页

Utils