Theta 方法

class darts.models.forecasting.theta.FourTheta(theta=2, seasonality_period=None, season_mode=SeasonalityMode.MULTIPLICATIVE, model_mode=ModelMode.ADDITIVE, trend_mode=TrendMode.LINEAR, normalization=True)[源代码]

基类：LocalForecastingModel

一个带有可配置 theta 参数的 4Theta 方法的实现。

参见 M4 竞赛 解决方案。

训练时间序列根据 seasonality_period 或推断的季节性周期进行去季节化处理。

season_mode 必须是一个 SeasonalityMode 枚举成员。model_mode 必须是一个 ModelMode 枚举成员。trend_mode 必须是一个 TrendMode 枚举成员。

你可以通过 from darts import SeasonalityMode, TrendMode, ModelMode 访问不同的枚举。

当调用时带有 theta = X，model_mode = Model.ADDITIVE 和 trend_mode = Trend.LINEAR，此模型等同于调用 Theta(theta=X)。

参数

  • theta (int) – theta 参数的值。默认值为 2。如果 theta = 1，则 fourtheta 方法限制为简单的指数平滑（SES）。如果 theta = 0，则 fourtheta 方法限制为简单的 trend_mode 回归。

  • seasonality_period (Optional[int, None]) – 用户定义的季节性周期。如果未设置，将在调用 fit() 时从训练序列中尝试推断。

  • model_mode (ModelMode) – 组合 Theta 线的模型类型。可以是 ModelMode.ADDITIVE 或 ModelMode.MULTIPLICATIVE。默认为 ModelMode.ADDITIVE。

  • season_mode (SeasonalityMode) – 季节性类型。可以是 SeasonalityMode.MULTIPLICATIVE、SeasonalityMode.ADDITIVE 或 SeasonalityMode.NONE。默认为 SeasonalityMode.MULTIPLICATIVE。

  • trend_mode (TrendMode) – 拟合的趋势类型。可以是 TrendMode.LINEAR 或 TrendMode.EXPONENTIAL。默认为 TrendMode.LINEAR。

  • normalization (bool) – 如果 True，数据将被标准化，使得均值为 1。默认为 True。

提示

尽管这个模型是 Theta 的改进版本，但它是对算法的简单实现，可能会更慢。

实际案例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import FourTheta
>>> series = AirPassengersDataset().load()
>>> model = FourTheta(theta=2)
>>> model.fit(series)
>>> pred = model.predict(6)
>>> pred.values()
array([[443.3949283 ],
       [434.39769555],
       [495.28886231],
       [481.08962991],
       [481.78610361],
       [546.61463773]])

属性

considers_static_covariates

模型是否考虑静态协变量，如果有的话。

extreme_lags

一个包含以下顺序的8元组：（最小目标滞后，最大目标滞后，最小过去协变量滞后，最大过去协变量滞后，最小未来协变量滞后，最大未来协变量滞后，输出偏移，最大目标滞后训练（仅适用于RNNModel））。

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_transferrable_series_prediction

模型是否支持对任意输入 序列 的预测。

uses_future_covariates

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

uses_past_covariates

模型是否使用过去的协变量，一旦拟合。

uses_static_covariates

模型是否使用静态协变量，一旦拟合。

模型参数

方法

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, ...])

计算此模型在一个（或一系列）`TimeSeries` 上产生的残差。

save([path])

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

select_best_model(ts[, thetas, m, ...])

在所有超参数上执行网格搜索以选择最佳模型，使用训练序列 ts 上的拟合值。
backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, num_samples=1, train_length=None, start=None, start_format='value', forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

计算模型在使用于（可能多个）`series` 时会产生误差值。

如果提供了 historical_forecasts，则直接在预测值和实际值上评估指标（由 metric 函数给出）。必须传递用于生成历史预测的相同 series。否则，它会反复构建训练集：要么从 series 的开始扩展，要么以固定的 train_length 长度移动。它在训练集上训练当前模型，发出长度等于 forecast_horizon 的预测，然后将训练集的末端向前移动 stride 个时间步。然后，在预测值和实际值上评估指标。最后，该方法返回所有这些指标分数的 `reduction`（默认是平均值）。

默认情况下，此方法使用每个历史预测（整体）来计算误差分数。如果 last_points_only 设置为 True，它将仅使用每个历史预测的最后一个点。在这种情况下，不使用归约。

默认情况下，此方法总是重新在整个可用历史数据上训练模型，对应于扩展窗口策略。如果 retrain 设置为 `False`（对于训练可能耗时的模型（如深度学习模型）很有用），将直接使用已训练的模型来生成预测。

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续训练和评估历史预测的目标时间序列（或一系列时间序列）。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个（或一系列）过去观察到的协变量序列。这仅适用于模型支持过去协变量的情况。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个（或一系列）未来已知的协变量序列。这仅适用于模型支持未来协变量的情况。

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

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

  • train_length (Optional[int, None]) – 我们训练集中的时间步数（用于训练的回测窗口大小）。仅在 retrain 不为 False 时有效。默认设置为 train_length=None，此时会使用所有可用的时间步直到预测时间，否则将使用移动窗口策略。如果大于可用时间步数，则使用所有时间步直到预测时间，如同默认情况。至少需要 min_train_series_length。

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

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

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

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

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

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

    • counter (int): 当前 retrain 迭代

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

    • train_series (TimeSeries): 训练序列，直到 pred_time

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

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

    注意：如果未向 historical_forecast 传递任何可选的 *_covariates，则会将 None 传递给相应的重新训练函数参数。注意：某些模型确实需要每次都重新训练，并且不支持除 retrain=True 以外的任何内容。

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

  • last_points_only (bool) – 是否使用整个历史预测或仅使用每个预测的最后一点来计算误差。

  • 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 相关的警告。

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

  • 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 函数和：

    • historical_forecasts 生成的 last_points_only=True

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

  • np.ndarray – 一个包含回测分数的 numpy 数组。适用于单一系列和以下之一：

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

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

    • 包括 series_reduction 在内的多个单变量/多变量序列，以及至少一个 component_reduction=None 或 time_reduction=None 用于“每时间步长指标”

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

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

property considers_static_covariates: bool

模型是否考虑静态协变量，如果有的话。

返回类型

bool

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

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

请参见下面的示例。

如果模型没有用以下方式拟合：

  • 目标（仅针对回归模型）：那么第一个元素应为 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 – 一个目标时间序列。模型将被训练来预测这个时间序列。

返回

拟合模型。

返回类型

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

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

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

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

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

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

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

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

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

参数

  • model_class – 要为 ‘series’ 调整的 ForecastingModel 子类。

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

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

  • past_covariates (Optional[TimeSeries, None]) – 可选地，一个过去观测到的协变量序列。这仅适用于模型支持过去协变量的情况。

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

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

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

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

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

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

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

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

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

  • metric (Callable[[TimeSeries, TimeSeries], float]) – 一个返回两个 TimeSeries 之间误差的度量函数，作为浮点值。必须是 Darts 的“随时间聚合”度量之一（参见 这里），或者是一个自定义度量，输入两个 TimeSeries 并返回误差。

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

  • verbose – 是否打印进度。

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

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

  • 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, num_samples=1, train_length=None, start=None, start_format='value', forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

计算此模型在（可能多个）`series` 上将获得的历史预测。

此方法反复构建训练集：从 series 的开头扩展或以固定长度 train_length 移动。它在训练集上训练模型，发出长度等于 forecast_horizon 的预测，然后将训练集的末端向前移动 stride 个时间步。

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

默认情况下，此方法总是重新在整个可用历史数据上训练模型，对应于扩展窗口策略。如果 retrain 设置为 False，则模型必须在此之前已经拟合。并非所有模型都支持此操作。

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续训练和计算历史预测的目标时间序列（或一系列时间序列）。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个（或一系列）过去观察到的协变量序列。这仅适用于模型支持过去协变量的情况。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个（或一系列）未来已知的协变量序列。这仅适用于模型支持未来协变量的情况。

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

  • train_length (Optional[int, None]) – 我们训练集中的时间步数（用于训练的回测窗口大小）。仅在 retrain 不为 False 时有效。默认设置为 train_length=None，此时会使用所有可用的时间步直到预测时间，否则将使用移动窗口策略。如果大于可用时间步数，则使用所有时间步直到预测时间，如同默认情况。至少需要 min_train_series_length。

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

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

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

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

  • retrain (Union[bool, int, Callable[…, bool]]) – 在预测之前是否以及/或在什么条件下重新训练模型。此参数支持3种不同的数据类型：bool、（正）``int`` 和 Callable``（返回 ``bool）。如果是 bool：在每一步重新训练模型（True），或者从不重新训练模型（False）。如果是 int：模型每 retrain 次迭代重新训练一次。如果是 Callable：每当可调用对象返回 True 时，模型都会重新训练。可调用对象必须具有以下位置参数：- counter (int): 当前 retrain 迭代 - pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练系列的结束） - train_series (TimeSeries): 直到 pred_time 的训练系列 - past_covariates (TimeSeries): 直到 pred_time 的过去协变量系列 - future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量系列 注意：如果任何可选的 *_covariates 没有传递给 historical_forecast，则相应的重新训练函数参数将传递 None。注意：某些模型确实需要每次都重新训练，并且不支持除 retrain=True 以外的任何内容。

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

  • last_points_only (bool) – 是否仅保留每个历史预测的最后一个点。如果设置为 True，该方法返回一个包含连续点预测的 TimeSeries。否则，返回一个历史 TimeSeries 预测的列表。

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

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

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

  • enable_optimization (bool) – 是否在使用历史预测时使用优化版本（当支持并可用时）。

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

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

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

返回类型

Union[TimeSeries, List[TimeSeries], List[List[TimeSeries]]]

返回

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

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

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

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

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

static load(path)

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

参数

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

返回类型

ForecastingModel

property min_train_samples: int

训练模型的最小样本数。

返回类型

int

property model_params: dict
返回类型

dict

property output_chunk_length: Optional[int]

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

返回类型

Optional[int, None]

property output_chunk_shift: int

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

返回类型

int

predict(n, num_samples=1, verbose=False, show_warnings=True)[源代码]

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

参数

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

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

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

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

返回

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

返回类型

TimeSeries

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

计算此模型在一个（或一系列）`TimeSeries` 上产生的残差。

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

此方法按顺序执行：

  • 为每个序列计算历史预测或使用预计算的 historical_forecasts`（更多详情请参见 :meth:`~darts.models.forecasting.forecasting_model.ForecastingModel.historical_forecasts）。历史预测的生成方式可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 进行配置。

  • 使用“每时间步” metric 计算历史预测与 series 之间的回测，按组件/列和时间步进行（更多详情请参见 backtest()）。默认情况下，使用残差 err() 作为 metric。

  • 创建并返回 TimeSeries`（或仅返回带有 `values_only=True 的 np.ndarray），其中时间索引来自历史预测，值来自每个组件和时间步的指标。

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

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 将为其计算残差的单变量 TimeSeries 实例。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个过去观测到的协变量时间序列。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个未来已知协变量时间序列。

  • forecast_horizon (int) – 用于预测每个拟合值的预测范围。

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

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

  • train_length (Optional[int, None]) – 我们训练集中的时间步数（用于训练的回测窗口大小）。仅在 retrain 不为 False 时有效。默认设置为 train_length=None，此时会使用所有可用的时间步直到预测时间，否则将使用移动窗口策略。如果大于可用时间步数，则使用所有时间步直到预测时间，如同默认情况。至少需要 min_train_series_length。

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

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

  • forecast_horizon – 点预测的预测范围。

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

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

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

    • counter (int): 当前 retrain 迭代

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

    • train_series (TimeSeries): 训练序列，直到 pred_time

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

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

    注意：如果未向 historical_forecast 传递任何可选的 *_covariates，则会将 None 传递给相应的重新训练函数参数。注意：某些模型确实需要每次都重新训练，并且不支持除 retrain=True 以外的任何内容。

  • last_points_only (bool) – 是否使用整个历史预测或仅使用每个预测的最后一点来计算误差。

  • metric (Callable[…, Union[float, List[float], ndarray, List[ndarray]]]) – Darts 的“每时间步”指标之一（参见 这里），或具有与 Darts 的“每时间步”指标相同签名的自定义指标，使用装饰器 multi_ts_support() 和 multi_ts_support()，并返回每个时间步的一个值。

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

  • show_warnings (bool) – 是否显示与参数 start 和 train_length 相关的警告。

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

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

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

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

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

返回

  • 时间序列 – 单个 series 的残差 时间序列 和使用 last_points_only=True 生成的 历史预测。

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

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

save(path=None, **pkl_kwargs)

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

保存和加载 RegressionModel 的示例：

from darts.models import RegressionModel

model = RegressionModel(lags=4)

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

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

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

返回类型

None

static select_best_model(ts, thetas=None, m=None, normalization=True, n_jobs=1)[源代码]

在所有超参数上执行网格搜索以选择最佳模型，使用训练序列 ts 上的拟合值。

使用 ‘LocalForecastingModel.gridsearch’ 并设置 ‘use_fitted_values=True’ 和 ‘metric=metrics.mae`。

参数

  • ts (TimeSeries) – 将用于测试模型的时序数据。

  • thetas (Optional[List[int], None]) – 要循环的 theta 列表。默认为 [1, 2, 3]。

  • m (Optional[int, None]) – 可选地，用于分解时间序列的季节。

  • normalization (bool) – 如果 True，数据将被标准化，使得均值为 1。默认为 True。

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

返回

在时间序列上表现最佳的模型。

返回类型

FourTheta

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

bool

property supports_likelihood_parameter_prediction: bool

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

返回类型

bool

property supports_multivariate: bool

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

返回类型

bool

property supports_optimized_historical_forecasts: bool

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

返回类型

bool

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

bool

property supports_probabilistic_prediction: bool

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

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

返回类型

bool

property supports_sample_weight: bool

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

返回类型

bool

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

bool

property supports_transferrable_series_prediction: bool

模型是否支持对任意输入 序列 的预测。

返回类型

bool

property uses_future_covariates: bool

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

返回类型

bool

property uses_past_covariates: bool

模型是否使用过去的协变量，一旦拟合。

返回类型

bool

property uses_static_covariates: bool

模型是否使用静态协变量，一旦拟合。

返回类型

bool

class darts.models.forecasting.theta.Theta(theta=2, seasonality_period=None, season_mode=SeasonalityMode.MULTIPLICATIVE)[源代码]

基类：LocalForecastingModel

一个带有可配置 theta 参数的 Theta 方法实现。参见 [1]。

训练时间序列根据 seasonality_period 或推断的季节性周期进行去季节化处理。

season_mode 必须是一个 SeasonalityMode 枚举成员。

你可以通过 from darts.utils.utils import SeasonalityMode 访问枚举。

参数

  • theta (int) – theta 参数的值。默认值为 2。不能设置为 0。如果 theta = 1，则 theta 方法限制为简单的指数平滑（SES）。

  • seasonality_period (Optional[int, None]) – 用户定义的季节性周期。如果未设置，将在调用 fit() 时从训练序列中尝试推断。

  • season_mode (SeasonalityMode) – 季节性类型。可以是 SeasonalityMode.MULTIPLICATIVE、SeasonalityMode.ADDITIVE 或 SeasonalityMode.NONE。默认为 SeasonalityMode.MULTIPLICATIVE。

引用

1

揭示Theta方法 <https://robjhyndman.com/papers/Theta.pdf

实际案例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.models import Theta
>>> series = AirPassengersDataset().load()
>>> # using the canonical Theta method
>>> model = Theta(theta=2)
>>> model.fit(series)
>>> pred = model.predict(6)
>>> pred.values()
array([[442.7256909 ],
       [433.74381763],
       [494.54534585],
       [480.36937856],
       [481.06675142],
       [545.80068173]])

属性

considers_static_covariates

模型是否考虑静态协变量，如果有的话。

extreme_lags

一个包含以下顺序的8元组：（最小目标滞后，最大目标滞后，最小过去协变量滞后，最大过去协变量滞后，最小未来协变量滞后，最大未来协变量滞后，输出偏移，最大目标滞后训练（仅适用于RNNModel））。

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_transferrable_series_prediction

模型是否支持对任意输入 序列 的预测。

uses_future_covariates

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

uses_past_covariates

模型是否使用过去的协变量，一旦拟合。

uses_static_covariates

模型是否使用静态协变量，一旦拟合。

模型参数

方法

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, ...])

计算此模型在一个（或一系列）`TimeSeries` 上产生的残差。

save([path])

将模型保存到给定的路径或文件句柄下。
backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, num_samples=1, train_length=None, start=None, start_format='value', forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

计算模型在使用于（可能多个）`series` 时会产生误差值。

如果提供了 historical_forecasts，则直接在预测值和实际值上评估指标（由 metric 函数给出）。必须传递用于生成历史预测的相同 series。否则，它会反复构建训练集：要么从 series 的开始扩展，要么以固定的 train_length 长度移动。它在训练集上训练当前模型，发出长度等于 forecast_horizon 的预测，然后将训练集的末端向前移动 stride 个时间步。然后，在预测值和实际值上评估指标。最后，该方法返回所有这些指标分数的 `reduction`（默认是平均值）。

默认情况下，此方法使用每个历史预测（整体）来计算误差分数。如果 last_points_only 设置为 True，它将仅使用每个历史预测的最后一个点。在这种情况下，不使用归约。

默认情况下，此方法总是重新在整个可用历史数据上训练模型，对应于扩展窗口策略。如果 retrain 设置为 `False`（对于训练可能耗时的模型（如深度学习模型）很有用），将直接使用已训练的模型来生成预测。

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续训练和评估历史预测的目标时间序列（或一系列时间序列）。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个（或一系列）过去观察到的协变量序列。这仅适用于模型支持过去协变量的情况。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个（或一系列）未来已知的协变量序列。这仅适用于模型支持未来协变量的情况。

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

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

  • train_length (Optional[int, None]) – 我们训练集中的时间步数（用于训练的回测窗口大小）。仅在 retrain 不为 False 时有效。默认设置为 train_length=None，此时会使用所有可用的时间步直到预测时间，否则将使用移动窗口策略。如果大于可用时间步数，则使用所有时间步直到预测时间，如同默认情况。至少需要 min_train_series_length。

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

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

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

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

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

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

    • counter (int): 当前 retrain 迭代

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

    • train_series (TimeSeries): 训练序列，直到 pred_time

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

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

    注意：如果未向 historical_forecast 传递任何可选的 *_covariates，则会将 None 传递给相应的重新训练函数参数。注意：某些模型确实需要每次都重新训练，并且不支持除 retrain=True 以外的任何内容。

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

  • last_points_only (bool) – 是否使用整个历史预测或仅使用每个预测的最后一点来计算误差。

  • 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 相关的警告。

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

  • 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 函数和：

    • historical_forecasts 生成的 last_points_only=True

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

  • np.ndarray – 一个包含回测分数的 numpy 数组。适用于单一系列和以下之一：

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

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

    • 包括 series_reduction 在内的多个单变量/多变量序列，以及至少一个 component_reduction=None 或 time_reduction=None 用于“每时间步长指标”

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

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

property considers_static_covariates: bool

模型是否考虑静态协变量，如果有的话。

返回类型

bool

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

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

请参见下面的示例。

如果模型没有用以下方式拟合：

  • 目标（仅针对回归模型）：那么第一个元素应为 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, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

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

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

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

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

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

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

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

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

参数

  • model_class – 要为 ‘series’ 调整的 ForecastingModel 子类。

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

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

  • past_covariates (Optional[TimeSeries, None]) – 可选地，一个过去观测到的协变量序列。这仅适用于模型支持过去协变量的情况。

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

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

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

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

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

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

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

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

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

  • metric (Callable[[TimeSeries, TimeSeries], float]) – 一个返回两个 TimeSeries 之间误差的度量函数，作为浮点值。必须是 Darts 的“随时间聚合”度量之一（参见 这里），或者是一个自定义度量，输入两个 TimeSeries 并返回误差。

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

  • verbose – 是否打印进度。

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

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

  • 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, num_samples=1, train_length=None, start=None, start_format='value', forecast_horizon=1, stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

计算此模型在（可能多个）`series` 上将获得的历史预测。

此方法反复构建训练集：从 series 的开头扩展或以固定长度 train_length 移动。它在训练集上训练模型，发出长度等于 forecast_horizon 的预测，然后将训练集的末端向前移动 stride 个时间步。

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

默认情况下，此方法总是重新在整个可用历史数据上训练模型，对应于扩展窗口策略。如果 retrain 设置为 False，则模型必须在此之前已经拟合。并非所有模型都支持此操作。

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续训练和计算历史预测的目标时间序列（或一系列时间序列）。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个（或一系列）过去观察到的协变量序列。这仅适用于模型支持过去协变量的情况。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个（或一系列）未来已知的协变量序列。这仅适用于模型支持未来协变量的情况。

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

  • train_length (Optional[int, None]) – 我们训练集中的时间步数（用于训练的回测窗口大小）。仅在 retrain 不为 False 时有效。默认设置为 train_length=None，此时会使用所有可用的时间步直到预测时间，否则将使用移动窗口策略。如果大于可用时间步数，则使用所有时间步直到预测时间，如同默认情况。至少需要 min_train_series_length。

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

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

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

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

  • retrain (Union[bool, int, Callable[…, bool]]) – 在预测之前是否以及/或在什么条件下重新训练模型。此参数支持3种不同的数据类型：bool、（正）``int`` 和 Callable``（返回 ``bool）。如果是 bool：在每一步重新训练模型（True），或者从不重新训练模型（False）。如果是 int：模型每 retrain 次迭代重新训练一次。如果是 Callable：每当可调用对象返回 True 时，模型都会重新训练。可调用对象必须具有以下位置参数：- counter (int): 当前 retrain 迭代 - pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练系列的结束） - train_series (TimeSeries): 直到 pred_time 的训练系列 - past_covariates (TimeSeries): 直到 pred_time 的过去协变量系列 - future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量系列 注意：如果任何可选的 *_covariates 没有传递给 historical_forecast，则相应的重新训练函数参数将传递 None。注意：某些模型确实需要每次都重新训练，并且不支持除 retrain=True 以外的任何内容。

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

  • last_points_only (bool) – 是否仅保留每个历史预测的最后一个点。如果设置为 True，该方法返回一个包含连续点预测的 TimeSeries。否则，返回一个历史 TimeSeries 预测的列表。

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

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

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

  • enable_optimization (bool) – 是否在使用历史预测时使用优化版本（当支持并可用时）。

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

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

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

返回类型

Union[TimeSeries, List[TimeSeries], List[List[TimeSeries]]]

返回

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

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

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

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

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

static load(path)

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

参数

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

返回类型

ForecastingModel

property min_train_samples: int

训练模型的最小样本数。

返回类型

int

property model_params: dict
返回类型

dict

property output_chunk_length: Optional[int]

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

返回类型

Optional[int, None]

property output_chunk_shift: int

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

返回类型

int

predict(n, num_samples=1, verbose=False, show_warnings=True)[源代码]

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

参数

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

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

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

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

返回

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

返回类型

TimeSeries

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

计算此模型在一个（或一系列）`TimeSeries` 上产生的残差。

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

此方法按顺序执行：

  • 为每个序列计算历史预测或使用预计算的 historical_forecasts`（更多详情请参见 :meth:`~darts.models.forecasting.forecasting_model.ForecastingModel.historical_forecasts）。历史预测的生成方式可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 进行配置。

  • 使用“每时间步” metric 计算历史预测与 series 之间的回测，按组件/列和时间步进行（更多详情请参见 backtest()）。默认情况下，使用残差 err() 作为 metric。

  • 创建并返回 TimeSeries`（或仅返回带有 `values_only=True 的 np.ndarray），其中时间索引来自历史预测，值来自每个组件和时间步的指标。

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

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 将为其计算残差的单变量 TimeSeries 实例。

  • past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个过去观测到的协变量时间序列。

  • future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个未来已知协变量时间序列。

  • forecast_horizon (int) – 用于预测每个拟合值的预测范围。

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

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

  • train_length (Optional[int, None]) – 我们训练集中的时间步数（用于训练的回测窗口大小）。仅在 retrain 不为 False 时有效。默认设置为 train_length=None，此时会使用所有可用的时间步直到预测时间，否则将使用移动窗口策略。如果大于可用时间步数，则使用所有时间步直到预测时间，如同默认情况。至少需要 min_train_series_length。

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

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

  • forecast_horizon – 点预测的预测范围。

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

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

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

    • counter (int): 当前 retrain 迭代

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

    • train_series (TimeSeries): 训练序列，直到 pred_time

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

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

    注意：如果未向 historical_forecast 传递任何可选的 *_covariates，则会将 None 传递给相应的重新训练函数参数。注意：某些模型确实需要每次都重新训练，并且不支持除 retrain=True 以外的任何内容。

  • last_points_only (bool) – 是否使用整个历史预测或仅使用每个预测的最后一点来计算误差。

  • metric (Callable[…, Union[float, List[float], ndarray, List[ndarray]]]) – Darts 的“每时间步”指标之一（参见 这里），或具有与 Darts 的“每时间步”指标相同签名的自定义指标，使用装饰器 multi_ts_support() 和 multi_ts_support()，并返回每个时间步的一个值。

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

  • show_warnings (bool) – 是否显示与参数 start 和 train_length 相关的警告。

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

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

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

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

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

返回

  • 时间序列 – 单个 series 的残差 时间序列 和使用 last_points_only=True 生成的 历史预测。

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

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

save(path=None, **pkl_kwargs)

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

保存和加载 RegressionModel 的示例：

from darts.models import RegressionModel

model = RegressionModel(lags=4)

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

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

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

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

bool

property supports_likelihood_parameter_prediction: bool

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

返回类型

bool

property supports_multivariate: bool

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

返回类型

bool

property supports_optimized_historical_forecasts: bool

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

返回类型

bool

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

bool

property supports_probabilistic_prediction: bool

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

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

返回类型

bool

property supports_sample_weight: bool

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

返回类型

bool

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

bool

property supports_transferrable_series_prediction: bool

模型是否支持对任意输入 序列 的预测。

返回类型

bool

property uses_future_covariates: bool

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

返回类型

bool

property uses_past_covariates: bool

模型是否使用过去的协变量，一旦拟合。

返回类型

bool

property uses_static_covariates: bool

模型是否使用静态协变量，一旦拟合。

返回类型

bool

上一页

<no title>

下一页

时间序列密集编码器 (TiDE)