指数平滑

class darts.models.forecasting.exponential_smoothing.ExponentialSmoothing(trend=ModelMode.ADDITIVE, damped=False, seasonal=SeasonalityMode.ADDITIVE, seasonal_periods=None, random_state=0, kwargs=None, **fit_kwargs)

基类: LocalForecastingModel

指数平滑

这是对 statsmodels 的 Holt-Winters 指数平滑 的封装；参数的原始和更完整的文档请参考此链接。

trend 必须是 ModelMode 枚举成员。您可以通过以下方式访问该枚举：

from darts.utils.utils import ModelMode.

seasonal 必须是 SeasonalityMode 枚举成员。您可以通过 from darts.utils.utils import SeasonalityMode 访问该枚举。

ExponentialSmoothing(trend=ModelMode.NONE, seasonal=SeasonalityMode.NONE) 对应于简单的指数平滑。ExponentialSmoothing(trend=ModelMode.ADDITIVE, seasonal=SeasonalityMode.NONE) 对应于 Holt 指数平滑。

请注意，自动选择 seasonal_period（将 seasonal_periods 参数设置为 None）有时可能导致错误，如果输入时间序列太短。在这种情况下，我们建议手动将 seasonal_periods 参数设置为正整数。

参数

• trend (联合[ModelMode, None]) – 趋势分量的类型。可以是 ModelMode.ADDITIVE, ModelMode.MULTIPLICATIVE, ModelMode.NONE, 或 None。默认为 ModelMode.ADDITIVE。

• damped (联合[bool, None]) – 趋势分量是否应该被阻尼。默认为 False。

• seasonal (联合[SeasonalityMode, None]) – 季节分量的类型。可以是 SeasonalityMode.ADDITIVE, SeasonalityMode.MULTIPLICATIVE, SeasonalityMode.NONE, 或 None。默认为 SeasonalityMode.ADDITIVE。

• seasonal_periods (联合[int, None]) – 完整季节周期中的周期数，例如，季度数据为 4，或带有周周期效应的日数据为 7。如果未设置，则从时间序列的频率推断。

• kwargs (联合[dict[str, 任意], None]) – 将用于调用 statsmodels.tsa.holtwinters.ExponentialSmoothing() 的一些可选关键字参数。详见文档。

• fit_kwargs –

  将用于调用 statsmodels.tsa.holtwinters.ExponentialSmoothing.fit() 的一些可选关键字参数。详见文档。

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import ExponentialSmoothing
>>> from darts.utils.utils import ModelMode, SeasonalityMode
>>> series = AirPassengersDataset().load()
>>> # using Holt's exponential smoothing
>>> model = ExponentialSmoothing(trend=ModelMode.ADDITIVE, seasonal=SeasonalityMode.MULTIPLICATIVE)
>>> model.fit(series)
>>> pred = model.predict(6)
>>> pred.values()
array([[445.24283838],
       [418.22618932],
       [465.31305075],
       [494.95129261],
       [505.4770514 ],
       [573.31519186]])

属性

considers_static_covariates	模型是否考虑静态协变量（如果存在）。
extreme_lags	一个 8 元组，按顺序包含：(最小目标滞后，最大目标滞后，最小历史协变量滞后，最大历史协变量滞后，最小未来协变量滞后，最大未来协变量滞后，输出偏移，训练时的最大目标滞后 (仅限 RNNModel))。
likelihood	返回模型用于概率预测的似然（如果存在）。
min_train_samples	训练模型所需的最小样本数。
output_chunk_length	模型一次预测的时间步数，对于统计模型未定义。
output_chunk_shift	输出/预测开始于输入结束之后的时间步数。
supports_future_covariates	模型是否支持未来协变量
supports_likelihood_parameter_prediction	模型实例是否支持直接预测似然参数
supports_multivariate	模型是否考虑时间序列中的多个变量。
supports_optimized_historical_forecasts	模型是否支持优化的历史预测
supports_past_covariates	模型是否支持历史协变量
supports_probabilistic_prediction	检查此配置的预测模型是否支持概率预测。
supports_sample_weight	模型是否支持训练时的样本权重。
supports_static_covariates	模型是否支持静态协变量
supports_transferable_series_prediction	模型是否支持对任何输入 series 进行预测。
uses_future_covariates	模型拟合后是否使用未来协变量。
uses_past_covariates	模型拟合后是否使用历史协变量。
uses_static_covariates	模型拟合后是否使用静态协变量。

model_params

方法

backtest(series[, past_covariates, ...])	计算模型对（可能多个）series 的历史预测所产生的误差值。
fit(series)	在提供的系列上拟合/训练模型。
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[, num_samples, verbose, show_warnings])	预测训练系列结束后 n 个时间步的值。
residuals(series[, past_covariates, ...])	计算模型对（可能多个）series 的历史预测所产生的残差。
save([path, clean])	将模型保存到给定路径或文件句柄下。
untrained_model()	返回使用相同参数创建的新的（未训练的）模型实例。

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 (联合[TimeSeries, 序列[TimeSeries]]) – 用于依次训练（如果 retrain 不是 False）和计算历史预测的（序列化的）目标时间序列。

• past_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，用于 series 中每个输入时间序列的（序列化的）历史观测协变量时间序列。这仅适用于模型支持历史协变量的情况。

• future_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，用于 series 中每个输入时间序列的（序列化的）未来已知协变量时间序列。这仅适用于模型支持未来协变量的情况。

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

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

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

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

• start (联合[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 不在可训练/可预测点范围内，则使用最接近的有效起始点，该点

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

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

  向未来移位 output_chunk_shift 个点。

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

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

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

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

• retrain (联合[bool, int, 可调用对象[…, 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 (联合[可调用对象[…, 联合[float, 列表[float], ndarray, 列表[ndarray]]], 列表[可调用对象[…, 联合[float, 列表[float], ndarray, 列表[ndarray]]]]]) – 一个度量函数或度量函数列表。每个度量必须是 Darts 度量（参见此处），或者是一个具有与 Darts 度量相同签名的自定义度量，使用装饰器 multi_ts_support() 和 multi_ts_support()，并返回度量得分。

• reduction (联合[可调用对象[…, 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 (联合[dict[str, 联合[BaseDataTransformer, Pipeline]], None]) – 可选的，一个字典，包含要应用于相应系列的 BaseDataTransformer 或 Pipeline（可能的键包括：“series”、“past_covariates”、“future_covariates”）。如果提供，所有输入系列必须位于未转换的空间中。对于可拟合的转换器/管道：

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

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

  拟合后的转换器在训练和预测过程中都用于转换输入。如果转换是可逆的，则预测结果将被逆向转换。仅当 historical_forecasts=None 时有效。

  • metric_kwargs (联合[dict[str, 任意], 列表[dict[str, 任意]], None]) – 传递给 metric() 的额外参数，例如用于并行化的 ‘n_jobs’、用于减少分量维度度量的 ‘component_reduction’、缩放度量的季节性参数 ‘m’ 等。将参数单独传递给每个度量，且仅当它们出现在相应的度量签名中时。缩放度量（例如 mase、rmsse 等）的参数 ‘insample’ 会被忽略，因为它在内部处理。

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

  predict_kwargs (联合[dict[str, 任意], None]) – 可选的，传递给模型 predict() 方法的一些额外参数。

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

• 返回类型

• 联合[float, ndarray, 列表[float], 列表[ndarray]]

• 返回

float – 对于单个单变量/多变量系列、单个 metric 函数以及

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

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

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

  • 单个 metric 函数，使用 last_points_only=False 且回测 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 用于“每时间步度量”的情况

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

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

  • property considers_static_covariates: bool

• bool

• property extreme_lags: tuple[可选[int], 可选[int], 可选[int], 可选[int], 可选[int], 可选[int], int, 可选[int]]

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

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

如果模型未用以下数据拟合：

目标（仅与 RegressionModels 相关）：则第一个元素应为 None。

历史协变量：则第三和第四个元素应为 None。

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

• 应由使用历史或未来协变量的模型，以及/或者具有可能不同于 -1 和 0 的最小目标滞后和最大目标滞后的模型重写此属性。

• 注意

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

元组[可选[int, None], 可选[int, None], 可选[int, None], 可选[int, None], 可选[int, None], 可选[int, None], int, 可选[int, None]]

fit(series)

series (TimeSeries) – 目标时间序列。模型将训练用于预测此时间序列。

示例

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

已拟合的模型。

self

在提供的系列上拟合/训练模型。

参数

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

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

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

past_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，拟合模型时使用的包含历史观测协变量的系列或系列列表。

future_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，拟合模型时使用的包含未来已知协变量的系列或系列列表。

参数

• 一个包含（历史协变量，未来协变量）的元组。每个协变量包含原始协变量和编码后的协变量。

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

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

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

n (int) – 打算用于预测的、在 series 结束后的预测时间步数。

series (联合[TimeSeries, 序列[TimeSeries]]) – 打算用于训练和预测的包含目标值的系列或系列列表。

past_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，打算用于训练和预测的包含历史观测协变量的系列。维度必须与用于训练的协变量维度匹配。

参数

• future_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，打算用于预测的包含未来已知协变量的系列。维度必须与用于训练的协变量维度匹配。

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

• 生成用于推理/预测集的协变量编码，并返回一个包含原始协变量和编码协变量堆叠在一起的历史协变量和未来协变量系列元组。编码由模型创建时使用参数 add_encoders 定义的编码器生成。传递您打算用于预测的相同的 series、past_covariates 和 future_covariates。

• series (联合[TimeSeries, 序列[TimeSeries]]) – 打算用于预测的包含目标值的系列或系列列表。

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

n (int) – 打算用于预测的、在 series 结束后的预测时间步数。

past_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，打算用于预测的包含历史观测协变量的系列。维度必须与用于训练的协变量维度匹配。

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)

参数

• future_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，打算用于预测的包含未来已知协变量的系列。维度必须与用于训练的协变量维度匹配。

• 此函数有 3 种操作模式：扩展窗口模式、分割模式和拟合值模式。这三种操作模式通过实例化 ForecastingModel 的 model_class 子类，并使用 parameters 字典中提供的每种超参数值组合，然后返回在 metric 函数方面表现最佳的模型。期望 metric 函数返回一个误差值，因此将选择产生最小 metric 输出的模型。

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

• series (联合[TimeSeries, 序列[TimeSeries]]) – 打算用于预测的包含目标值的系列或系列列表。

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

n (int) – 打算用于预测的、在 series 结束后的预测时间步数。

扩展窗口模式（当传递 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 (联合[TimeSeries, None]) – 可选的，历史观测协变量系列。这仅适用于模型支持历史协变量的情况。

• future_covariates (联合[TimeSeries, None]) – 可选的，未来已知协变量系列。这仅适用于模型支持未来协变量的情况。

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

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

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

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

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

• start (联合[Timestamp, float, int, None]) – 可选的，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果为 float，它是时间序列中位于第一个预测点之前的比例。如果为 int，它对于带有 pd.DatetimeIndex 的 series 是第一个预测点的索引位置，或者对于带有 pd.RangeIndex 的 series 是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，它是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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

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

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

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

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

  向未来移位 output_chunk_shift 个点。

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

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

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

• val_series (联合[TimeSeries, None]) – 在分割模式中用于验证的 TimeSeries 实例。如果提供，此系列必须紧接在 series 结束后开始，以便进行正确的预测比较。

• 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，此时将忽略随机选择。

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

  拟合后的转换器在训练和预测过程中都用于转换输入。如果转换是可逆的，则预测结果将被逆向转换。仅当 historical_forecasts=None 时有效。

  • metric_kwargs (联合[dict[str, 任意], 列表[dict[str, 任意]], None]) – 传递给 metric() 的额外参数，例如用于并行化的 ‘n_jobs’、用于减少分量维度度量的 ‘component_reduction’、缩放度量的季节性参数 ‘m’ 等。将参数单独传递给每个度量，且仅当它们出现在相应的度量签名中时。缩放度量（例如 mase、rmsse 等）的参数 ‘insample’ 会被忽略，因为它在内部处理。

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

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

• 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”（指数）衰减——过去越远，权重越低。

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

一个元组，包含一个从未训练过的 model_class 实例（使用性能最佳的超参数创建）、一个包含这些最佳超参数的字典，以及最佳超参数的度量分数。

float – 对于单个单变量/多变量系列、单个 metric 函数以及

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 (联合[TimeSeries, 序列[TimeSeries]]) – 用于依次训练（如果 retrain 不是 False）和计算历史预测的（序列化的）目标时间序列。

• past_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，用于 series 中每个输入时间序列的（序列化的）历史观测协变量时间序列。这仅适用于模型支持历史协变量的情况。

• future_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，用于 series 中每个输入时间序列的（序列化的）未来已知协变量时间序列。这仅适用于模型支持未来协变量的情况。

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

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

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

• start (联合[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 不在可训练/可预测点范围内，则使用最接近的有效起始点，该点

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

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

  向未来移位 output_chunk_shift 个点。

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

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

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

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

• retrain (联合[bool, int, 可调用对象[…, 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 (联合[可调用对象[…, 联合[float, 列表[float], ndarray, 列表[ndarray]]], 列表[可调用对象[…, 联合[float, 列表[float], ndarray, 列表[ndarray]]]]]) – 一个度量函数或度量函数列表。每个度量必须是 Darts 度量（参见此处），或者是一个具有与 Darts 度量相同签名的自定义度量，使用装饰器 multi_ts_support() 和 multi_ts_support()，并返回度量得分。

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

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

• enable_optimization (bool) – 当支持且可用时，是否使用优化的 historical_forecasts 版本。默认值：True。

• data_transformers (联合[dict[str, 联合[BaseDataTransformer, Pipeline]], None]) – 可选的，一个字典，包含要应用于相应系列的 BaseDataTransformer 或 Pipeline（可能的键包括：“series”、“past_covariates”、“future_covariates”）。如果提供，所有输入系列必须位于未转换的空间中。对于可拟合的转换器/管道：

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

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

  拟合后的转换器在训练和预测过程中都用于转换输入。如果转换是可逆的，则预测结果将被逆向转换。仅当 historical_forecasts=None 时有效。

  • metric_kwargs (联合[dict[str, 任意], 列表[dict[str, 任意]], None]) – 传递给 metric() 的额外参数，例如用于并行化的 ‘n_jobs’、用于减少分量维度度量的 ‘component_reduction’、缩放度量的季节性参数 ‘m’ 等。将参数单独传递给每个度量，且仅当它们出现在相应的度量签名中时。缩放度量（例如 mase、rmsse 等）的参数 ‘insample’ 会被忽略，因为它在内部处理。

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

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

• 返回类型

• 联合[float, ndarray, 列表[float], 列表[ndarray]]

• 返回

float – 对于单个单变量/多变量系列、单个 metric 函数以及

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

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

• 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: Optional[Likelihood]

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

Optional[Likelihood, None]

static load(path)

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

参数

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

ForecastingModel

property min_train_samples: int

训练模型所需的最小样本数。

float – 对于单个单变量/多变量系列、单个 metric 函数以及

int

property model_params: dict

float – 对于单个单变量/多变量系列、单个 metric 函数以及

dict

property output_chunk_length: Optional[int]

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

Optional[int, None]

property output_chunk_shift: int

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

int

predict(n, num_samples=1, verbose=False, show_warnings=True)

预测训练系列结束后 n 个时间步的值。

参数

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

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

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

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

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

一个时间序列，包含训练系列结束后的 n 个后续点。

float – 对于单个单变量/多变量系列、单个 metric 函数以及

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（或仅在 values_only=True 时返回 np.ndarray），其时间索引来自历史预测，值来自按分量和时间步长计算的度量。

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

参数

• series (联合[TimeSeries, 序列[TimeSeries]]) – 用于依次训练（如果 retrain 不是 False）和计算历史预测的（序列化的）目标时间序列。

• past_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，用于 series 中每个输入时间序列的（序列化的）历史观测协变量时间序列。这仅适用于模型支持历史协变量的情况。

• future_covariates (联合[TimeSeries, 序列[TimeSeries], None]) – 可选的，用于 series 中每个输入时间序列的（序列化的）未来已知协变量时间序列。这仅适用于模型支持未来协变量的情况。

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

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

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

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

• start (联合[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 不在可训练/可预测点范围内，则使用最接近的有效起始点，该点

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

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

  向未来移位 output_chunk_shift 个点。

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

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

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

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

• retrain (联合[bool, int, 可调用对象[…, 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 (联合[可调用对象[…, 联合[float, 列表[float], ndarray, 列表[ndarray]]], 列表[可调用对象[…, 联合[float, 列表[float], ndarray, 列表[ndarray]]]]]) – 一个度量函数或度量函数列表。每个度量必须是 Darts 度量（参见此处），或者是一个具有与 Darts 度量相同签名的自定义度量，使用装饰器 multi_ts_support() 和 multi_ts_support()，并返回度量得分。

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

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

  可以是 Darts 的“每时间步”度量之一（参见此处），也可以是自定义度量，其签名与 Darts 的“每时间步”度量相同，使用装饰器 multi_ts_support() 和 multi_ts_support()，并为每个时间步长返回一个值。

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

• enable_optimization (bool) – 当支持且可用时，是否使用优化的 historical_forecasts 版本。默认值：True。

• data_transformers (联合[dict[str, 联合[BaseDataTransformer, Pipeline]], None]) – 可选的，一个字典，包含要应用于相应系列的 BaseDataTransformer 或 Pipeline（可能的键包括：“series”、“past_covariates”、“future_covariates”）。如果提供，所有输入系列必须位于未转换的空间中。对于可拟合的转换器/管道：

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

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

  拟合后的转换器在训练和预测过程中都用于转换输入。如果转换是可逆的，则预测结果将被逆向转换。仅当 historical_forecasts=None 时有效。

  • metric_kwargs (联合[dict[str, 任意], 列表[dict[str, 任意]], None]) – 传递给 metric() 的额外参数，例如用于并行化的 ‘n_jobs’、用于减少分量维度度量的 ‘component_reduction’、缩放度量的季节性参数 ‘m’ 等。将参数单独传递给每个度量，且仅当它们出现在相应的度量签名中时。缩放度量（例如 mase、rmsse 等）的参数 ‘insample’ 会被忽略，因为它在内部处理。

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

  predict_kwargs (联合[dict[str, 任意], None]) – 可选的，传递给模型 predict() 方法的一些额外参数。

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

• 返回类型

• 联合[float, ndarray, 列表[float], 列表[ndarray]]

• 返回

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

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

使用 last_points_only=False 并使用回测 reduction 生成的 historical_forecasts

• 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() 的关键字参数

float – 对于单个单变量/多变量系列、单个 metric 函数以及

None

property supports_future_covariates: bool

模型是否支持未来协变量

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property supports_likelihood_parameter_prediction: bool

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property supports_multivariate: bool

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property supports_optimized_historical_forecasts: bool

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property supports_past_covariates: bool

模型是否支持历史协变量

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property supports_probabilistic_prediction: bool

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

默认返回 False。需要支持概率预测的模型重写此方法。

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property supports_sample_weight: bool

模型是否支持训练时的样本权重。

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property supports_static_covariates: bool

模型是否支持静态协变量

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property supports_transferable_series_prediction: bool

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

untrained_model()

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

property uses_future_covariates: bool

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property uses_past_covariates: bool

模型拟合后是否使用历史协变量。

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

property uses_static_covariates: bool

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

float – 对于单个单变量/多变量系列、单个 metric 函数以及

参见下方示例。

上一页

<无标题>

下一页

快速傅里叶变换