AutoETS

class darts.models.forecasting.sf_auto_ets.AutoETS(*args, add_encoders=None, quantiles=None, random_state=None, **kwargs)

基类: StatsForecastModel

基于 Statsforecasts 包 的 Auto-ETS 模型。

使用信息准则自动选择最佳指数平滑模型 (ETS)。有关参数的详细文档，请参考 StatsForecast 文档。

除了单变量确定性预测，它还支持

• 未来协变量：使用外部特征来潜在地提高预测精度。Darts 添加了支持，方法是先使用 LinearRegressionModel 模型将时间序列对未来协变量进行回归，然后在原始回归的样本内残差上运行 StatsForecast 模型。这种方法受到了 Stephan Kolassa 这篇帖子的启发。

• 概率预测：要生成概率预测，您可以在调用 predict() 时设置以下参数

  • 通过设置 predict_likelihood_parameters=True 直接预测分位数。

  • 通过设置 num_samples >> 1 从这些分位数生成采样预测。

• 一致性预测：除了原生概率支持外，您还可以在模型创建时设置 prediction_intervals 来执行一致性预测。然后按照上述方法进行预测。

• 可转移时间序列预测：在预测时将拟合模型应用于新的输入 series。

注意

输入时间序列包含缺失值时，不支持未来协变量。

注意

由于模型依赖 Numba 和 jit 编译，第一次模型调用可能会比后续调用花费更多时间。

参数

• args – statsforecasts.models.AutoETS 的位置参数。

• 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': {'future': ['relative']},
      'custom': {'future': [encode_year]},
      'transformer': Scaler(),
      'tz': 'CET'
  }
  

• quantiles (Optional[list[float], None]) – （可选）在使用 num_samples > 1 或 predict_likelihood_parameters=True 执行概率预测时，在 quantiles 水平生成分位数预测。

• random_state (Optional[int, None]) – 控制不同运行中概率一致性预测（样本生成）的随机性。

• kwargs – statsforecasts.models.AutoETS 的关键字参数。

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import AutoETS
>>> from darts.utils.timeseries_generation import datetime_attribute_timeseries
>>> series = AirPassengersDataset().load()
>>> # optionally, use some future covariates; e.g. the value of the month encoded as a sine and cosine series
>>> future_cov = datetime_attribute_timeseries(series, "month", cyclic=True, add_length=6)
>>> # define AutoETS parameters
>>> model = AutoETS(season_length=12, model="AZZ")
>>> model.fit(series, future_covariates=future_cov)
>>> pred = model.predict(6, future_covariates=future_cov)
>>> pred.values()
array([[441.40323676],
       [415.09871431],
       [448.90785391],
       [491.38584654],
       [493.11817462],
       [549.88974472]])

属性

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

模型参数

方法

backtest(series[, past_covariates, ...])	计算模型对（可能多个）series 的历史预测所产生的误差值。
fit(series[, future_covariates])	在提供的（单个）时间序列上拟合/训练模型。
generate_fit_encodings(series[, ...])	生成用于拟合模型的协变量编码，并返回一个包含原始和编码协变量堆叠在一起的过去协变量和未来协变量时间序列元组。
generate_fit_predict_encodings(n, series[, ...])	生成用于训练和推理/预测的协变量编码，并返回一个包含原始和编码协变量堆叠在一起的过去协变量和未来协变量时间序列元组。
generate_predict_encodings(n, series[, ...])	生成用于推理/预测集的协变量编码，并返回一个包含原始和编码协变量堆叠在一起的过去协变量和未来协变量时间序列元组。
gridsearch(parameters, series[, ...])	使用网格搜索在给定集合中找到最佳超参数。
historical_forecasts(series[, ...])	通过模拟在提供的（可能多个）series 的历史中的不同时间点进行预测来生成历史预测。
load(path)	从给定路径或文件句柄加载模型。
predict(n[, series, future_covariates, ...])	如果未设置 series 参数，则预测训练时间序列结束后的 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 值。最后，该方法返回所有这些评估指标分数的（可选）缩减结果（默认为平均值）。

如果 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 的时间序列，它是第一个预测点所在的索引位置；对于带有 pd.RangeIndex 的时间序列，它是第一个预测点所在的索引值。后者可以使用 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则为第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

  • 如果 retrain 为 False，或者 retrain 是一个 Callable 且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。

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

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

  注意：如果 start 不在可训练/可预测点内，则使用距离 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”）。如果提供，所有输入序列必须位于未转换的空间。对于可拟合的转换器/管道

  • 如果 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”（指数）衰减 - 过去越远，权重越低。权重是按时间序列计算的。

返回类型

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

返回值

• float – 对于单个单/多变量时间序列、单个 metric 函数以及

  • 使用 last_points_only=True 生成的 historical_forecasts

  • 使用 last_points_only=False 并使用回测 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。使用回测 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, future_covariates=None)

在提供的（单个）时间序列上拟合/训练模型。

（可选）也可以提供一个未来协变量时间序列。

参数

• series (TimeSeries) – 模型将在此时间序列上进行训练以进行预测。如果模型支持，可以是多变量时间序列。

• future_covariates (Optional[TimeSeries, None]) – 未来已知协变量的时间序列。此时间序列不会被预测，但可以被某些模型用作输入。它必须包含至少与目标 series 相同的时间步长/索引。如果比必需的更长，它将自动被截断。

返回值

拟合后的模型。

返回类型

self

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

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 种操作模式：扩展窗口模式、分割模式和拟合值模式。这三种操作模式通过使用 parameters 字典中提供的每种超参数组合实例化 ForecastingModel 的 model_class 子类，并返回在 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 的时间序列，它是第一个预测点所在的索引位置；对于带有 pd.RangeIndex 的时间序列，它是第一个预测点所在的索引值。后者可以使用 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则为第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

  • 如果 retrain 为 False，或者 retrain 是一个 Callable 且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。

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

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

  注意：如果 start 不在可训练/可预测点内，则使用距离 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 的属性，则引发错误。拟合值是模型在 series 上拟合的结果。与拟合值进行比较是评估模型的快速方法，但无法判断模型是否过拟合了时间序列。

• 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 的组件数量匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “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 的时间序列，它是第一个预测点所在的索引位置；对于带有 pd.RangeIndex 的时间序列，它是第一个预测点所在的索引值。后者可以使用 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则为第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

  • 如果 retrain 为 False，或者 retrain 是一个 Callable 且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。

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

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

  注意：如果 start 不在可训练/可预测点内，则使用距离 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”）。如果提供，所有输入序列必须位于未转换的空间。对于可拟合的转换器/管道

  • 如果 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”（指数）衰减 - 过去越远，权重越低。权重是按时间序列计算的。

返回类型

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 的历史预测列表的列表。对于每个序列和历史预测，它包含整个预测范围 forecast_horizon。外层列表对应于输入序列中提供的序列，内层列表包含每个序列的历史预测。

property likelihood: QuantilePrediction

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

返回类型

QuantilePrediction

static load(path)

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

参数

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

返回类型

ForecastingModel

property min_train_samples: int

训练模型的最小样本数。

返回类型

int

property model_params: dict

返回类型

dict

property output_chunk_length: Optional[int]

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

返回类型

Optional[int, None]

property output_chunk_shift: int

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

返回类型

int

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

如果未设置 series 参数，则预测训练序列结束后的 n 个时间步的值。如果在训练期间指定了某些未来协变量，则在此处也必须指定它们。

如果设置了 series 参数，则预测新目标序列结束后的 n 个时间步的值。如果在训练期间指定了某些未来协变量，则在此处也必须指定它们。

参数

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

• series (Optional[TimeSeries, None]) – 可选参数，一个新的目标序列，将预测其未来值。默认为 None，表示模型将预测训练序列的未来值。

• future_covariates (Optional[TimeSeries, None]) –

  可作为模型输入的未来已知协变量时间序列。它必须与用于训练的 fit() 方法中使用的协变量时间序列相对应。

  如果未设置 series，它必须至少包含训练目标序列结束后的接下来 n 个时间步/索引。如果设置了 series，它必须至少包含与新目标序列相对应的时间步/索引（历史未来协变量），以及序列结束后的接下来 n 个时间步/索引。

• num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型必须为 1。

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

• verbose (bool) – 可选参数，设置预测的详细程度。并非对所有模型都有效。

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

返回类型

TimeSeries，一个包含训练序列结束后的接下来 n 个点的单时间序列。

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 进行配置。

• 计算历史预测与 series 之间按组件/列和时间步计算的“每时间步”metric 的回测（更多详细信息请参见 backtest()）。默认情况下，使用残差 err() (误差) 作为 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 的时间序列，它是第一个预测点所在的索引位置；对于带有 pd.RangeIndex 的时间序列，它是第一个预测点所在的索引值。后者可以使用 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则为第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

  • 如果 retrain 为 False，或者 retrain 是一个 Callable 且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。

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

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

  注意：如果 start 不在可训练/可预测点内，则使用距离 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”）。如果提供，所有输入序列必须位于未转换的空间。对于可拟合的转换器/管道

  • 如果 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”（指数）衰减 - 过去越远，权重越低。权重是按时间序列计算的。

• 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 存储的全局预测模型后，必须向 ‘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

模型是否考虑时间序列中的多个变量。

返回类型

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

untrained_model()

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

property uses_future_covariates: bool

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

返回类型

bool

property uses_past_covariates: bool

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

返回类型

bool

property uses_static_covariates: bool

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

返回类型

bool

上一页

AutoCES

下一页

AutoMFLES