CatBoost 模型

基于 CatBoost 的回归模型。

此实现能够生成概率预测。

class darts.models.forecasting.catboost_model.CatBoostModel(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, categorical_past_covariates=None, categorical_future_covariates=None, categorical_static_covariates=None, **kwargs)

基类: RegressionModelWithCategoricalCovariates

CatBoost 模型

参数

• lags (Union[int, list, 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], 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], 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]) – 可以设置为 ‘quantile’、‘poisson’ 或 ‘gaussian’。如果设置，模型将是概率性的，允许在预测时进行采样。当设置为 ‘gaussian’ 时，模型将使用 CatBoost 的 ‘RMSEWithUncertainty’ 损失函数。使用此损失函数时，CatBoost 返回均值和方差对，用于捕获数据（偶然）不确定性。这将覆盖任何 objective 参数。

• quantiles (Optional[list, 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()

• categorical_past_covariates (Union[str, list[str], None]) – 可选参数，分量名称或分量名称列表，指定应由底层 CatBoostRegressor 视为分类的过去协变量。指定为分类的分量必须是整数编码的。有关 CatBoost 如何处理分类特征的更多信息，请访问：分类特征支持文档。

• categorical_future_covariates (Union[str, list[str], None]) – 可选参数，分量名称或分量名称列表，指定应由底层 CatBoostRegressor 视为分类的未来协变量。指定为分类的分量必须是整数编码的。

• categorical_static_covariates (Union[str, list[str], None]) – 可选参数，字符串或字符串列表，指定应由底层 CatBoostRegressor 视为分类的静态协变量。指定为分类的分量必须是整数编码的。

• **kwargs – 传递给 catboost.CatBoostRegressor 的额外关键字参数。通过使用适当的 loss_function（‘MultiRMSE’、‘MultiRMSEWithMissingValues’）可以实现原生的多输出支持。否则，Darts 会使用其 MultiOutputRegressor 包装器添加多输出支持。

示例

>>> from darts.datasets import WeatherDataset
>>> from darts.models import CatBoostModel
>>> 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 = CatBoostModel(
>>>     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([[1006.4153701 ],
       [1006.41907237],
       [1006.30872957],
       [1006.28614154],
       [1006.22355514],
       [1006.21607546]])

属性

考虑静态协变量	如果存在静态协变量，模型是否考虑它们。
极限滞后	包含以下顺序的 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])	返回预测 target_dim 目标分量第 horizon 步的估计器。
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 是一个 Callable 并且第一个可预测点早于第一个可训练点，则为第一个可预测点。

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

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

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

  是在 start 之前 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：每当 callable 返回 True 时，模型重新训练。callable 必须包含以下位置参数

  • 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() 和 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”）。如果提供，所有输入序列必须位于未转换的空间中。对于可拟合的 transformer / pipeline

  • 如果 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 标签的样本权重。它们按观测、按标签（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 并使用 backtest reduction 生成的 historical_forecasts

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

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

  • 多个 metric 函数，以及使用 last_points_only=False 生成的 historical_forecasts。使用 backtest 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, verbose=0, **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]]) – 可选参数，指定评估数据集未来已知协变量的序列或序列的序列。

• 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 相同，但用于评估数据集。

• verbose (Union[bool, int, None]) – 可设置为 1 以显示 catboost 默认详细输出的整数或布尔值

• **kwargs – 传递给 catboost.CatboostRegressor.fit() 的额外关键字参数。

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[时间序列, Sequence[时间序列]], Union[时间序列, Sequence[时间序列]]]

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[时间序列, Sequence[时间序列]], Union[时间序列, Sequence[时间序列]]]

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[时间序列, Sequence[时间序列]], Union[时间序列, Sequence[时间序列]]]

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 种操作模式：扩展窗口模式、拆分模式和拟合值模式。这 3 种操作模式通过实例化 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。

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

参数

• 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 是一个 Callable 并且第一个可预测点早于第一个可训练点，则为第一个可预测点。

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

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

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

  是在 start 之前 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”）。如果提供，所有输入序列必须位于未转换的空间中。对于可拟合的 transformer / pipeline

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

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

  拟合好的 transformer 用于在训练和预测期间转换输入。如果转换是可逆的，预测结果将进行逆转换。

• 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 的组件数量匹配。如果是一个字符串，则使用内置的权重函数生成权重。可用的选项是 “linear” 或 “exponential” 衰减 - 越往过去，权重越低。

返回值

一个元组，包含一个由表现最佳的超参数创建的未训练的 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 是一个 Callable 并且第一个可预测点早于第一个可训练点，则为第一个可预测点。

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

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

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

  是在 start 之前 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：每当 callable 返回 True 时，模型重新训练。callable 必须包含以下位置参数

  • 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”）。如果提供，所有输入序列必须位于未转换的空间中。对于可拟合的 transformer / pipeline

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

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

  拟合好的 transformer 用于在训练和预测期间转换输入。如果转换是可逆的，预测结果将进行逆转换。

• 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 标签的样本权重。它们按观测、按标签（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] – 历史预测列表，对应

  • 一系列 (list) series 且 last_points_only=True：对于每个系列，它仅包含所有历史预测中步骤 forecast_horizon 的预测。

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

• List[List[TimeSeries]] – 历史预测列表的列表，对应一系列 series 且 last_points_only=False。对于每个系列和历史预测，它包含整个范围 forecast_horizon。外部列表是输入序列中提供的系列，内部列表包含每个系列的历史预测。

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 或 TimeSeries 列表, 可选) – 可选，一个或多个输入 TimeSeries，表示要预测未来的目标系列的历史。如果指定，方法返回这些系列的预测。否则，方法返回（单个）训练系列的预测。

• past_covariates (TimeSeries 或 TimeSeries 列表, 可选) – 可选，模型作为输入所需的过去观测的协变量系列。它们的维度和类型必须与训练中使用的协变量匹配。

• future_covariates (TimeSeries 或 TimeSeries 列表, 可选) – 可选，模型作为输入所需的未来已知的协变量系列。它们的维度和类型必须与训练中使用的协变量匹配。

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

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

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

• **kwargs (dict, 可选) – 传递给模型的 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()（误差）作为 metric。

• 创建并返回具有历史预测时间索引和按组件和时间步计算的指标值的 TimeSeries（或仅返回一个 np.ndarray 当 values_only=True 时）。

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

参数

• 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 是一个 Callable 并且第一个可预测点早于第一个可训练点，则为第一个可预测点。

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

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

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

  是在 start 之前 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：每当 callable 返回 True 时，模型重新训练。callable 必须包含以下位置参数

  • 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”）。如果提供，所有输入序列必须位于未转换的空间中。对于可拟合的 transformer / pipeline

  • 如果 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 标签的样本权重。它们按观测、按标签（output_chunk_length 中的每个步骤）和按分量应用。如果是系列或系列序列，则使用这些权重。如果权重系列只有一个分量/列，则权重将全局应用于 series 中的所有分量。否则，对于特定分量的权重，分量数量必须与 series 的分量数量匹配。如果是字符串，则使用内置权重函数生成权重。可用选项是 “linear”（线性）或 “exponential”（指数）衰减 - 过去越远，权重越低。权重根据 series 中最长序列的长度进行全局计算。然后对于每个序列，从全局权重的末尾提取权重。这为所有序列提供了共同的时间加权。

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

返回类型

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

返回值

• TimeSeries – 单个 series 的残差 TimeSeries，以及使用 last_points_only=True 生成的 historical_forecasts：它仅包含来自所有历史预测中步骤 forecast_horizon 的残差。

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

• List[List[TimeSeries]] – 一系列 series 的残差 TimeSeries 列表的列表，且 last_points_only=False。外部残差列表的长度为 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 存储的全局预测模型后，必须在 predict()、historical_forecasts() 和其他预测方法中传递 series。

• 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]]

上一个

块循环神经网络

下一个

保形模型