基线模型

用于单个单变量和多变量序列的简单基准模型集合。

class darts.models.forecasting.baselines.NaiveDrift(*args, **kwargs)

基类: LocalForecastingModel

朴素漂移模型

此模型在训练序列的第一个点和最后一个点之间拟合一条直线，并将其延伸到未来。对于长度为 \(T\) 的训练序列，我们有

\[\hat{y}_{T+h} = y_T + h\left( \frac{y_T - y_1}{T - 1} \right)\]

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import NaiveDrift
>>> series = AirPassengersDataset().load()
>>> model = NaiveDrift()
>>> model.fit(series)
>>> pred = model.predict(6)
>>> pred.values()
array([[434.23776224],
       [436.47552448],
       [438.71328671],
       [440.95104895],
       [443.18881119],
       [445.42657343]])

属性

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

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，对于 series 中的每个输入时间序列，提供一个（或多个）过去观察到的协变量时间序列。这仅适用于支持过去协变量的模型。

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

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

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

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

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

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

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/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 标签的一些样本权重。仅当 retrain 不为 False 时有效。它们应用于每个观测、每个标签（output_chunk_length 中的每个步骤）和每个组件。如果是一个序列或序列的序列，则使用这些权重。如果权重序列只有单个组件/列，则权重全局应用于 series 中的所有组件。否则，对于特定组件的权重，组件数必须与 series 的组件数匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear” 或 “exponential” 衰减——时间越远，权重越低。权重是按时间 series 计算的。

返回类型

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

返回

• float – 以下情况的单个回测得分：单个单变量/多变量序列、单个 metric 函数，以及使用 last_points_only=True 生成的 historical_forecasts

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

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

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

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

  • 多个 metric 函数，以及使用 last_points_only=False 生成的 historical_forecasts。使用回测 reduction 时输出形状为 (..., 指标数)，当 reduction=None 时输出形状为 (预测次数, ..., 指标数)。

  • 包括 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

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

返回类型

布尔值

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)

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

参数

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

返回

拟合后的模型。

返回类型

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 种操作模式：扩展窗口模式、分割模式和拟合值模式。这 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 的 series，它是第一个预测点的索引位置；对于带有 pd.RangeIndex 的 series，它是索引值。后者可以使用 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则它是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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]) – 在分割模式下用于验证的时间序列实例。如果提供，此序列必须紧接在 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

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

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

返回类型

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

返回

• TimeSeries – 当 last_points_only=True 时，针对单个 series 的单个历史预测：它仅包含所有历史预测中时间步长 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]

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

返回类型

Optional[Likelihood, None]

static load(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, num_samples=1, verbose=False, show_warnings=True)

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

参数

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

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

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

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

返回

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

返回类型

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 配置历史预测的生成方式。

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

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

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

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

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

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

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

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

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

• (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")

参数

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

• (bool) –

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

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

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

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

布尔值

property supports_likelihood_parameter_prediction: bool

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

返回类型

布尔值

property supports_multivariate: bool

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

返回类型

布尔值

property supports_optimized_historical_forecasts: bool

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

返回类型

布尔值

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

布尔值

property supports_probabilistic_prediction: bool

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

默认情况下返回 False。支持概率预测的模型需要重写此项。

返回类型

布尔值

property supports_sample_weight: bool

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

返回类型

布尔值

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

布尔值

property supports_transferable_series_prediction: bool

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

返回类型

布尔值

untrained_model()

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

property uses_future_covariates: bool

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

返回类型

布尔值

property uses_past_covariates: bool

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

返回类型

布尔值

property uses_static_covariates: bool

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

返回类型

布尔值

class darts.models.forecasting.baselines.NaiveEnsembleModel(forecasting_models, train_forecasting_models=True, show_warnings=True)

Bases: EnsembleModel

朴素组合模型

EnsembleModel 的朴素实现 返回所有构成模型的预测平均值

如果在训练或推理时提供了 future_covariates 或 past_covariates，它们将仅传递给支持它们的模型。

参数

• (list[ForecastingModel]) – 要进行组合的预测模型列表

• (bool) – 是否从头开始训练 forecasting_models。如果为 False，则在调用 fit() 时不会训练模型，并且可以直接调用 predict()（仅当所有 forecasting_models 都是预训练的 GlobalForecastingModels 时才支持）。默认值：True。

• (bool) – 是否显示与模型协变量支持相关的警告。

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import NaiveEnsembleModel, NaiveSeasonal, LinearRegressionModel
>>> series = AirPassengersDataset().load()
>>> # defining the ensemble
>>> model = NaiveEnsembleModel([NaiveSeasonal(K=12), LinearRegressionModel(lags=4)])
>>> model.fit(series)
>>> pred = model.predict(6)
>>> pred.values()
array([[439.23152974],
       [431.41161602],
       [439.72888401],
       [453.70180806],
       [454.96757177],
       [485.16604194]])

属性

considers_static_covariates	模型是否考虑静态协变量（如果存在）。
extreme_lags	一个包含以下顺序的 8 元组：（最小目标滞后，最大目标滞后，最小过去协变量滞后，最大过去协变量滞后，最小未来协变量滞后，最大未来协变量滞后，输出偏移，最大目标训练滞后（仅适用于 RNNModel））。
likelihood	返回模型用于概率预测的似然（如果存在）。
min_train_samples	训练模型所需的最少样本数。
output_chunk_length	如果所有预测模型都没有 output_chunk_length，则返回 None，否则返回最小的 output_chunk_length。
output_chunk_shift	输出/预测开始于输入结束之后的时间步数。
supports_future_covariates	模型是否支持未来协变量
supports_likelihood_parameter_prediction	如果 EnsembleModel 的所有预测模型都使用相同的似然函数进行拟合，则 EnsembleModel 可以预测似然参数。
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 上进行历史预测时产生的误差值。
ensemble(predictions, series[, num_samples, ...])	对 forecasting_models 的预测进行分量平均
fit(series[, past_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[, pl_trainer_kwargs])	从给定路径或文件句柄加载模型。
predict(n[, series, past_covariates, ...])	预测序列结束后的 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 (Union[TimeSeries, Sequence[TimeSeries]]) – 用于逐次训练（如果 retrain 不为 False）和计算历史预测的目标时间序列（或序列）。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，对于 series 中的每个输入时间序列，提供一个（或多个）过去观察到的协变量时间序列。这仅适用于支持过去协变量的模型。

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

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

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

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

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

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

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

• (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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/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 标签的一些样本权重。仅当 retrain 不为 False 时有效。它们应用于每个观测、每个标签（output_chunk_length 中的每个步骤）和每个组件。如果是一个序列或序列的序列，则使用这些权重。如果权重序列只有单个组件/列，则权重全局应用于 series 中的所有组件。否则，对于特定组件的权重，组件数必须与 series 的组件数匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear” 或 “exponential” 衰减——时间越远，权重越低。权重是按时间 series 计算的。

返回类型

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

返回

• float – 以下情况的单个回测得分：单个单变量/多变量序列、单个 metric 函数，以及使用 last_points_only=True 生成的 historical_forecasts

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

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

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

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

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

  • 包括 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

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

返回类型

布尔值

ensemble(predictions, series, num_samples=1, predict_likelihood_parameters=False)

对 forecasting_models 的预测进行分量平均

返回类型

Union[TimeSeries, Sequence[TimeSeries]]

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, sample_weight=None)

在提供的序列上拟合模型。请注意，EnsembleModel.fit() 并不会在其每个构成预测模型上调用 fit()。这留给继承自 EnsembleModel 的类在重写 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[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 种操作模式：扩展窗口模式、分割模式和拟合值模式。这 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 的 series，它是第一个预测点的索引位置；对于带有 pd.RangeIndex 的 series，它是索引值。后者可以使用 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则它是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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]) – 在分割模式下用于验证的时间序列实例。如果提供，此序列必须紧接在 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

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

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

返回类型

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

返回

• TimeSeries – 当 last_points_only=True 时，针对单个 series 的单个历史预测：它仅包含所有历史预测中时间步长 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]

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

返回类型

Optional[Likelihood, None]

static load(path, pl_trainer_kwargs=None, **kwargs)

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

参数

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

• (Optional[dict, None]) – 仅当底层预测模型包含 TorchForecastingModel 时有效。可选地，一组用于创建新的 Lightning Trainer 的关键字参数，用于配置模型以执行下游任务（例如预测）。一些示例包括指定批大小或将模型移动到 CPU/GPU。请查阅 Lightning Trainer 文档，了解更多关于支持的关键字参数的信息。

• **kwargs – 仅当底层预测模型包含 TorchForecastingModel 时有效。PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法的附加关键字参数。欲了解更多信息，请阅读官方文档。

返回类型

EnsembleModel

property min_train_samples: int

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

返回类型

int

property model_params: dict

返回类型

dict

property output_chunk_length: Optional[int]

如果所有预测模型都没有 output_chunk_length，则返回 None，否则返回最小的 output_chunk_length。

返回类型

Optional[int, None]

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)

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

如果调用 fit() 时仅使用一个 TimeSeries 作为参数，则此函数的 series 参数是可选的，它将简单地生成接下来 horizon 个时间步长的预测。在这种情况下，past_covariates 和 future_covariates 参数也不必再次提供。

如果调用 fit() 时，series 被指定为 Sequence[TimeSeries]（即模型已在多个时间序列上训练），则必须指定 series 参数。

当指定了 series 参数时，此函数将为由 series 给定的简单序列（或序列中的每个序列）计算接下来 n 个时间步长的预测。

如果在训练期间指定了多个过去或未来的协变量，则在此处也必须指定一些相应的协变量。对于 series 中的每个输入，都必须提供一个匹配的（过去和/或未来）协变量时间序列。

参数

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

• (Union[TimeSeries, Sequence[TimeSeries], None]) – 将要预测未来值的序列。

• (Union[TimeSeries, Sequence[TimeSeries], None]) – series 中每个输入时间序列对应一个过去观测的协变量时间序列。它们在维度上必须与训练时 fit() 函数使用的过去协变量相匹配。

• (Union[TimeSeries, Sequence[TimeSeries], None]) – series 中每个输入时间序列对应一个未来已知的协变量时间序列。它们在维度上必须与训练时 fit() 函数使用的过去协变量相匹配。

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

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

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

• (bool) – 是否显示与自回归和过去协变量使用相关的警告。

返回

如果未指定 series，则此函数返回一个时间序列，其中包含训练序列结束后的接下来 n 个点。如果指定了 series 并且是一个简单的 TimeSeries，则此函数返回 series 结束后的接下来 n 个点。如果指定了 series 并且是多个时间序列的序列，则此函数返回一个序列，其中每个元素包含相应的 n 个点预测。

返回类型

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 配置历史预测的生成方式。

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

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

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

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

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

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

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

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

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

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

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

此外，对于预测模型下的每个 TorchForecastingModel，会存储两个文件。

保存和加载 RegressionEnsembleModel 的示例

from darts.models import RegressionEnsembleModel, LinearRegressionModel, TiDEModel

model = RegressionEnsembleModel(
    forecasting_models = [
        LinearRegressionModel(lags=4),
        TiDEModel(input_chunk_length=4, output_chunk_length=4),
        ],
        regression_train_n_points=10,
)

model.save("my_ensemble_model.pkl")
model_loaded = RegressionEnsembleModel.load("my_ensemble_model.pkl")

参数

• (Union[str, PathLike, BinaryIO, None]) – 保存组合模型当前状态的路径或文件句柄。如果未指定路径，组合模型将自动保存为 "{RegressionEnsembleModel}_{YYYY-mm-dd_HH_MM_SS}.pkl"。如果 forecasting_models 中的第 i 个模型是 TorchForecastingModel，则会在 "{path}.{ithModelClass}_{i}.pt" 和 "{path}.{ithModelClass}_{i}.ckpt" 下保存两个文件（模型对象和检查点）。

• (bool) –

  是否存储模型的清理版本。如果为 True，则移除训练序列和协变量。如果底层 forecasting_models 包含任何 TorchForecastingModel，还将额外移除其所有与 Lightning Trainer 相关的参数。

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

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

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

布尔值

property supports_likelihood_parameter_prediction: bool

如果 EnsembleModel 的所有预测模型都使用相同的似然函数进行拟合，则 EnsembleModel 可以预测似然参数。

返回类型

布尔值

property supports_multivariate: bool

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

返回类型

布尔值

property supports_optimized_historical_forecasts: bool

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

返回类型

布尔值

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

布尔值

property supports_probabilistic_prediction: bool

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

默认情况下返回 False。支持概率预测的模型需要重写此项。

返回类型

布尔值

property supports_sample_weight: bool

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

返回类型

布尔值

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

布尔值

property supports_transferable_series_prediction: bool

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

返回类型

布尔值

untrained_model()

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

property uses_future_covariates: bool

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

返回类型

布尔值

property uses_past_covariates: bool

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

返回类型

布尔值

property uses_static_covariates: bool

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

返回类型

布尔值

class darts.models.forecasting.baselines.NaiveMean(*args, **kwargs)

基类: LocalForecastingModel

Naive 平均模型

此模型没有参数，总是预测训练时间序列的平均值。

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import NaiveMean
>>> series = AirPassengersDataset().load()
>>> model = NaiveMean()
>>> model.fit(series)
>>> pred = model.predict(6)
>>> pred.values()
array([[280.29861111],
      [280.29861111],
      [280.29861111],
      [280.29861111],
      [280.29861111],
      [280.29861111]])

属性

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

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，对于 series 中的每个输入时间序列，提供一个（或多个）过去观察到的协变量时间序列。这仅适用于支持过去协变量的模型。

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

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

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

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

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

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

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

• (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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/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 标签的一些样本权重。仅当 retrain 不为 False 时有效。它们应用于每个观测、每个标签（output_chunk_length 中的每个步骤）和每个组件。如果是一个序列或序列的序列，则使用这些权重。如果权重序列只有单个组件/列，则权重全局应用于 series 中的所有组件。否则，对于特定组件的权重，组件数必须与 series 的组件数匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear” 或 “exponential” 衰减——时间越远，权重越低。权重是按时间 series 计算的。

返回类型

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

返回

• float – 以下情况的单个回测得分：单个单变量/多变量序列、单个 metric 函数，以及使用 last_points_only=True 生成的 historical_forecasts

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

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

• 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

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

返回类型

布尔值

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)

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

参数

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

返回

拟合后的模型。

返回类型

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 种操作模式：扩展窗口模式、分割模式和拟合值模式。这 3 种模式通过使用字典 parameters 中提供的每种超参数值组合实例化 ForecastingModel 的 model_class 子类，并返回在 metric 函数方面表现最佳的模型来评估每种可能的组合。预期 metric 函数返回一个误差值，因此将选择产生最小 metric 输出的模型。

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

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

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

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

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

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

参数

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

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

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

• past_covariates (Optional[TimeSeries, None]) – 可选参数，过去观察到的协变量序列。这仅适用于支持过去协变量的模型。

• future_covariates (Optional[TimeSeries, None]) – 可选参数，未来已知的协变量序列。这仅适用于支持未来协变量的模型。

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

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

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

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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]) – 在分割模式下用于验证的时间序列实例。如果提供，此序列必须紧接在 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

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

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

返回类型

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

返回

• TimeSeries – 当 last_points_only=True 时，针对单个 series 的单个历史预测：它仅包含所有历史预测中时间步长 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]

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

返回类型

Optional[Likelihood, None]

static load(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, num_samples=1, verbose=False, show_warnings=True)

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

参数

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

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

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

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

返回

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

返回类型

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 配置历史预测的生成方式。

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

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

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

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

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

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

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

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

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

• (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")

参数

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

• (bool) –

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

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

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

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

布尔值

property supports_likelihood_parameter_prediction: bool

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

返回类型

布尔值

property supports_multivariate: bool

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

返回类型

布尔值

property supports_optimized_historical_forecasts: bool

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

返回类型

布尔值

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

布尔值

property supports_probabilistic_prediction: bool

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

默认情况下返回 False。支持概率预测的模型需要重写此项。

返回类型

布尔值

property supports_sample_weight: bool

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

返回类型

布尔值

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

布尔值

property supports_transferable_series_prediction: bool

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

返回类型

布尔值

untrained_model()

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

property uses_future_covariates: bool

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

返回类型

布尔值

property uses_past_covariates: bool

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

返回类型

布尔值

property uses_static_covariates: bool

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

返回类型

布尔值

class darts.models.forecasting.baselines.NaiveMovingAverage(input_chunk_length=1)

基类: LocalForecastingModel

Naive 移动平均模型

此模型使用移动平均进行预测。

参数

input_chunk_length (int) – 用于计算移动平均的滑动窗口大小

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import NaiveMovingAverage
>>> series = AirPassengersDataset().load()
# using the average of the last 6 months
>>> model = NaiveMovingAverage(input_chunk_length=6)
>>> pred = model.predict(6)
>>> pred.values()
array([[503.16666667],
       [483.36111111],
       [462.9212963 ],
       [455.40817901],
       [454.47620885],
       [465.22224366]])

属性

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

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，对于 series 中的每个输入时间序列，提供一个（或多个）过去观察到的协变量时间序列。这仅适用于支持过去协变量的模型。

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

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

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

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

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

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

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

• (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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/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 标签的一些样本权重。仅当 retrain 不为 False 时有效。它们应用于每个观测、每个标签（output_chunk_length 中的每个步骤）和每个组件。如果是一个序列或序列的序列，则使用这些权重。如果权重序列只有单个组件/列，则权重全局应用于 series 中的所有组件。否则，对于特定组件的权重，组件数必须与 series 的组件数匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear” 或 “exponential” 衰减——时间越远，权重越低。权重是按时间 series 计算的。

返回类型

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

返回

• float – 以下情况的单个回测得分：单个单变量/多变量序列、单个 metric 函数，以及使用 last_points_only=True 生成的 historical_forecasts

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

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

• 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

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

返回类型

布尔值

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)

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

参数

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

返回

拟合后的模型。

返回类型

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 种操作模式：扩展窗口模式、分割模式和拟合值模式。这 3 种模式通过使用字典 parameters 中提供的每种超参数值组合实例化 ForecastingModel 的 model_class 子类，并返回在 metric 函数方面表现最佳的模型来评估每种可能的组合。预期 metric 函数返回一个误差值，因此将选择产生最小 metric 输出的模型。

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

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

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

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

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

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

参数

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

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

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

• past_covariates (Optional[TimeSeries, None]) – 可选参数，过去观察到的协变量序列。这仅适用于支持过去协变量的模型。

• future_covariates (Optional[TimeSeries, None]) – 可选参数，未来已知的协变量序列。这仅适用于支持未来协变量的模型。

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

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

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

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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]) – 在分割模式下用于验证的时间序列实例。如果提供，此序列必须紧接在 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

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

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

返回类型

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

返回

• TimeSeries – 当 last_points_only=True 时，针对单个 series 的单个历史预测：它仅包含所有历史预测中时间步长 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]

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

返回类型

Optional[Likelihood, None]

static load(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, num_samples=1, verbose=False, show_warnings=True)

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

参数

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

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

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

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

返回

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

返回类型

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 配置历史预测的生成方式。

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

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

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

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

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

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

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

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

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

• (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")

参数

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

• (bool) –

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

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

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

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

布尔值

property supports_likelihood_parameter_prediction: bool

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

返回类型

布尔值

property supports_multivariate: bool

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

返回类型

布尔值

property supports_optimized_historical_forecasts: bool

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

返回类型

布尔值

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

布尔值

property supports_probabilistic_prediction: bool

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

默认情况下返回 False。支持概率预测的模型需要重写此项。

返回类型

布尔值

property supports_sample_weight: bool

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

返回类型

布尔值

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

布尔值

property supports_transferable_series_prediction: bool

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

返回类型

布尔值

untrained_model()

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

property uses_future_covariates: bool

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

返回类型

布尔值

property uses_past_covariates: bool

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

返回类型

布尔值

property uses_static_covariates: bool

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

返回类型

布尔值

class darts.models.forecasting.baselines.NaiveSeasonal(K=1)

基类: LocalForecastingModel

Naive 季节性模型

此模型总是预测 K 个时间步长之前的值。当 K=1 时，此模型预测训练集的最后一个值。当 K>1 时，它重复训练集的最后 K 个值。

参数

K (int) – 要重复的训练集最后 K 个时间步长的数量

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import NaiveSeasonal
>>> series = AirPassengersDataset().load()
# prior analysis suggested seasonality of 12
>>> model = NaiveSeasonal(K=12)
>>> model.fit(series)
>>> pred = model.predict(6)
>>> pred.values()
array([[417.],
       [391.],
       [419.],
       [461.],
       [472.],
       [535.]])

属性

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

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，对于 series 中的每个输入时间序列，提供一个（或多个）过去观察到的协变量时间序列。这仅适用于支持过去协变量的模型。

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

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

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

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

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

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

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

• (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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/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 标签的一些样本权重。仅当 retrain 不为 False 时有效。它们应用于每个观测、每个标签（output_chunk_length 中的每个步骤）和每个组件。如果是一个序列或序列的序列，则使用这些权重。如果权重序列只有单个组件/列，则权重全局应用于 series 中的所有组件。否则，对于特定组件的权重，组件数必须与 series 的组件数匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear” 或 “exponential” 衰减——时间越远，权重越低。权重是按时间 series 计算的。

返回类型

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

返回

• float – 以下情况的单个回测得分：单个单变量/多变量序列、单个 metric 函数，以及使用 last_points_only=True 生成的 historical_forecasts

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

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

• 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

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

返回类型

布尔值

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)

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

参数

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

返回

拟合后的模型。

返回类型

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 种操作模式：扩展窗口模式、分割模式和拟合值模式。这 3 种模式通过使用字典 parameters 中提供的每种超参数值组合实例化 ForecastingModel 的 model_class 子类，并返回在 metric 函数方面表现最佳的模型来评估每种可能的组合。预期 metric 函数返回一个误差值，因此将选择产生最小 metric 输出的模型。

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

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

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

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

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

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

参数

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

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

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

• past_covariates (Optional[TimeSeries, None]) – 可选参数，过去观察到的协变量序列。这仅适用于支持过去协变量的模型。

• future_covariates (Optional[TimeSeries, None]) – 可选参数，未来已知的协变量序列。这仅适用于支持未来协变量的模型。

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

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

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

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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]) – 在分割模式下用于验证的时间序列实例。如果提供，此序列必须紧接在 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 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”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/pipeline

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

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

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

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

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

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

返回类型

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

返回

• TimeSeries – 当 last_points_only=True 时，针对单个 series 的单个历史预测：它仅包含所有历史预测中时间步长 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。外层列表对应于输入序列中提供的序列，内层列表包含每个序列的历史预测。

属性 likelihood: Optional[Likelihood]

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

返回类型

Optional[Likelihood, None]

静态 load(path)

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

参数

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

返回类型

ForecastingModel

属性 min_train_samples: int

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

返回类型

int

属性 model_params: dict

返回类型

dict

属性 output_chunk_length: Optional[int]

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

返回类型

Optional[int, None]

属性 output_chunk_shift: int

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

返回类型

int

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

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

参数

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

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

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

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

返回

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

返回类型

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 配置历史预测的生成方式。

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

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

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

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

  注意：如果 start 不在可训练/可预测点内，则使用最接近有效且是 stride 的整数倍且晚于 start 的有效起始点。如果不存在有效起始点，则引发 ValueError。

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

  注意：如果 start 超出可能的历史预测时间范围，将忽略该参数（None 的默认行为）并从第一个可训练/可预测点开始。

  偏移了 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，以及（返回 bool 的）Callable。如果为 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，将向相应的 retrain 函数参数传递 None。注意：有些模型需要每次都重新训练，并且只支持 retrain=True 以外的值。注意：这也控制着 data_transformers 的重新训练。

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

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

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

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

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

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

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

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

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

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

• (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")

参数

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

• (bool) –

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

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

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

返回类型

None

属性 supports_future_covariates: bool

模型是否支持未来协变量

返回类型

布尔值

属性 supports_likelihood_parameter_prediction: bool

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

返回类型

布尔值

属性 supports_multivariate: bool

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

返回类型

布尔值

属性 supports_optimized_historical_forecasts: bool

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

返回类型

布尔值

属性 supports_past_covariates: bool

模型是否支持过去协变量

返回类型

布尔值

属性 supports_probabilistic_prediction: bool

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

默认情况下返回 False。支持概率预测的模型需要重写此项。

返回类型

布尔值

属性 supports_sample_weight: bool

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

返回类型

布尔值

属性 supports_static_covariates: bool

模型是否支持静态协变量

返回类型

布尔值

属性 supports_transferable_series_prediction: bool

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

返回类型

布尔值

untrained_model()

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

属性 uses_future_covariates: bool

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

返回类型

布尔值

属性 uses_past_covariates: bool

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

返回类型

布尔值

属性 uses_static_covariates: bool

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

返回类型

布尔值

上一页

ARIMA

下一页

块状循环神经网络