全局基线模型（朴素）¶

一系列简单的基准模型，可处理单变量、多变量、单序列和多序列。

GlobalNaiveAggregate
GlobalNaiveDrift
GlobalNaiveSeasonal

class darts.models.forecasting.global_baseline_models.GlobalNaiveAggregate(input_chunk_length, output_chunk_length, output_chunk_shift=0, agg_fn='mean', **kwargs)[source]¶

基类： _NoCovariatesMixin, _GlobalNaiveModel

全局朴素聚合模型。

模型为每个 series 生成预测，具体描述如下

从每个目标分量的最后 input_chunk_length 个点计算一个聚合值（使用 agg_fn，默认：均值）
预测是将该分量聚合值重复 output_chunk_length 次

根据调用 model.predict() 时使用的预测期 n，预测结果可以是

如果 n <= output_chunk_length，则为常数聚合值（默认：均值），或者
如果 n > output_chunk_length，则为移动聚合值，这是自回归预测的结果。

此模型等同于

NaiveMean，当 input_chunk_length 等于输入目标 series 的长度且 agg_fn=’mean’ 时。
NaiveMovingAverage，当 input_chunk_length 和 output_chunk_length=1 相同且 agg_fn=’mean’ 时。

注意

全局朴素模型不支持使用 save_checkpoints=True 进行模型检查点保存，也不支持使用 load_from_checkpoint() 和 load_weights_from_checkpoint() 加载检查点。

参数

input_chunk_length (int) – 输入给模型的输入序列的长度。
output_chunk_length (int) – 模型输出的预测序列和输出序列的长度。
output_chunk_shift (int) – 可选参数，将输出块的开始位置向未来偏移的步数（相对于输入块的结束）。这将创建输入和输出之间的间隙。如果模型支持 future_covariates，则从偏移后的输出块中提取未来值。预测将从目标 series 结束后的 output_chunk_shift 步开始。如果设置了 output_chunk_shift，则模型无法生成自回归预测（即 n > output_chunk_length）。
agg_fn (Union[str, Callable[[Tensor, int], Tensor]]) –
要使用的聚合函数。如果是字符串，则必须是可以直接从 torch 导入的 torch 函数名称（例如，torch.mean 用 “mean”，torch.sum 用 “sum”）。该函数必须具有下面的签名。如果是 Callable，它也必须具有下面的签名。
```
def agg_fn(x: torch.Tensor, dim: int, *args, **kwargs) -> torch.Tensor:
    # x has shape `(batch size, input_chunk_length, n targets)`, `dim` is always `1`.
    # function must return a tensor of shape `(batch size, n targets)`
    return torch.mean(x, dim=dim)
```
**kwargs – 可选参数，用于初始化 pytorch_lightning.Module, pytorch_lightning.Trainer 和 Darts 的 TorchForecastingModel。由于朴素模型不进行训练，以下参数将无效：loss_fn, likelihood, optimizer_cls, optimizer_kwargs, lr_scheduler_cls, lr_scheduler_kwargs, n_epochs, save_checkpoints 以及部分 pl_trainer_kwargs。

示例

>>> from darts.datasets import IceCreamHeaterDataset
>>> from darts.models import GlobalNaiveAggregate
>>> # create list of multivariate series
>>> series_1 = IceCreamHeaterDataset().load()
>>> series_2 = series_1 + 100.
>>> series = [series_1, series_2]
>>> # predict 3 months, take mean over last 60 months
>>> horizon, icl = 3, 60
>>> # naive mean over last 60 months (with `output_chunk_length = horizon`)
>>> model = GlobalNaiveAggregate(input_chunk_length=icl, output_chunk_length=horizon)
>>> # predict after end of each multivariate series
>>> pred = model.fit(series).predict(n=horizon, series=series)
>>> [p.values() for p in pred]
[array([[29.666668, 50.983337],
       [29.666668, 50.983337],
       [29.666668, 50.983337]]), array([[129.66667, 150.98334],
       [129.66667, 150.98334],
       [129.66667, 150.98334]])]
>>> # naive moving mean (with `output_chunk_length < horizon`)
>>> model = GlobalNaiveAggregate(input_chunk_length=icl, output_chunk_length=1, agg_fn="mean")
>>> pred = model.fit(series).predict(n=horizon, series=series)
>>> [p.values() for p in pred]
[array([[29.666668, 50.983337],
       [29.894447, 50.88306 ],
       [30.109352, 50.98111 ]]), array([[129.66667, 150.98334],
       [129.89445, 150.88307],
       [130.10936, 150.98111]])]
>>> # naive moving sum (with `output_chunk_length < horizon`)
>>> model = GlobalNaiveAggregate(input_chunk_length=icl, output_chunk_length=1, agg_fn="sum")
>>> pred = model.fit(series).predict(n=horizon, series=series)
>>> [p.values() for p in pred]
[array([[ 1780.,  3059.],
       [ 3544.,  6061.],
       [ 7071., 12077.]]), array([[ 7780.,  9059.],
       [15444., 17961.],
       [30771., 35777.]])]

属性

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

epochs_trained
input_chunk_length
model_created
model_params
supports_future_covariates
supports_past_covariates
supports_static_covariates

方法

`backtest`(series[, past_covariates, ...])	计算模型对（可能多个）series 的历史预测所产生的误差值。
`fit`(series[, past_covariates, future_covariates])	在一个（或可能多个）序列上拟合/训练模型。
`fit_from_dataset`(train_dataset[, ...])	使用特定的 `darts.utils.data.TrainingDataset` 实例训练模型。
`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])	从给定文件路径加载模型。
`load_from_checkpoint`(model_name[, work_dir, ...])	从 '{work_dir}/darts_logs/{model_name}/checkpoints/' 下自动保存的检查点加载模型。
`load_weights`(path[, load_encoders, skip_checks])	从手动保存的模型（使用 `save()` 保存）加载权重。
`load_weights_from_checkpoint`([model_name, ...])	仅从 '{work_dir}/darts_logs/{model_name}/ checkpoints/' 下自动保存的检查点加载权重。
`lr_find`(series[, past_covariates, ...])	PyTorch Lightning 的 Tuner.lr_find() 的包装器。
`predict`(n[, series, past_covariates, ...])	预测训练序列或指定的 `series` 结束后的 `n` 个时间步。
`predict_from_dataset`(n, input_series_dataset)	此方法允许使用特定的 `darts.utils.data.InferenceDataset` 实例进行预测。
`reset_model`()	重置模型对象并移除所有存储的数据 - 模型、检查点、日志记录器和训练历史。
`residuals`(series[, past_covariates, ...])	计算模型对（可能多个）series 的历史预测所产生的残差。
`save`([path, clean])	在给定路径下保存模型。
`to_cpu`()	更新 PyTorch Lightning Trainer 参数，以便下次调用 :fun:`fit()` 或 `predict()` 时将模型移动到 CPU。
`to_onnx`([path])	将模型导出为 ONNX 格式以优化推理，封装了 PyTorch Lightning 的 `torch.onnx.export()` 方法（官方文档）。
`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 是一个 Callable 且第一个可预测点早于第一个可训练点，则为第一个可预测点。
- 如果 retrain 为 True 或 int>（给定 train_length），或 retrain 是一个 Callable 且第一个可训练点早于第一个可预测点，则为第一个可训练点。
注意：如果 start 不在可训练/可预测点范围内，则使用最接近的有效起始点，该点在 start 之前是 stride 的整数倍。如果不存在有效的起始点，则会引发 ValueError。注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会向未来偏移 output_chunk_shift 个点。注意：如果 start 超出了可能的历史预测时间范围，则会忽略该参数（默认行为为 None）并从第一个可训练/可预测点开始。


start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

metric (Union[Callable[…, Union[float, list[float], ndarray, list[ndarray]]], list[Callable[…, Union[float, list[float], ndarray, list[ndarray]]]]]) – 一个指标函数或指标函数列表。每个指标必须是 Darts 指标（详见 这里），或具有与 Darts 指标相同签名、使用 multi_ts_support() 和 multi_ts_support() 装饰器并返回指标得分的自定义指标。
reduction (Optional[Callable[…, float], None]) – 用于组合当 last_points_only 设置为 False 时获得的单个误差得分的函数。提供多个指标函数时，该函数将接收参数 axis = 1，以便为每个指标函数获得一个单一值。如果明确设置为 None，则该方法将返回单个误差得分列表。默认为 np.mean。
verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – 传递给 metric() 的附加参数，例如用于并行化的 ‘n_jobs’，用于减少组件维度指标的 ‘component_reduction’，用于缩放指标的季节性参数 ‘m’ 等。将为每个指标分别传递参数，并且仅当它们出现在相应的指标签名中时。缩放指标（例如 mase`, rmsse 等）的参数 ‘insample’ 将被忽略，因为它在内部处理。
fit_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 fit() 方法的一些附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 predict() 方法的一些附加参数。
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于训练目标 series 标签的样本权重。仅当 retrain 不为 False 时有效。权重按观测、按标签（output_chunk_length 中的每个步骤）和按组件应用。如果是一个或多个序列，则使用这些权重。如果权重序列只有一个分量/列，则将权重全局应用于 series 中的所有分量。否则，对于特定于分量的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置的加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减 - 过去越远，权重越低。权重按时间 series 计算。


返回类型
Union[float, ndarray, list[float], list[ndarray]]

返回

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

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测得分
使用 last_points_only=False 生成的 historical_forecasts 并使用回测 reduction，返回单个回测得分


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

单个 metric 函数，使用 last_points_only=False 和回测 reduction=None 生成的 historical_forecasts。输出形状为 (n forecasts, *)。
多个 metric 函数和使用 last_points_only=False 生成的 historical_forecasts。使用回测 reduction 时，输出形状为 (*, n metrics)，而 reduction=None 时，形状为 (n forecasts, *, n metrics)。
包括 series_reduction 的多个单变量/多变量序列，以及至少一个 component_reduction=None 或 time_reduction=None（用于“按时间步指标”）。


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





property considers_static_covariates: bool¶
模型是否考虑静态协变量（如果存在）。

返回类型
bool






property epochs_trained: int¶

返回类型
int






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, *args, **kwargs)¶
在一个（或可能多个）序列上拟合/训练模型。此方法仅为朴素基线模型实现，以便与其他预测模型提供统一的拟合/预测 API。
模型并未真正基于输入进行训练，但 fit() 用于根据输入序列设置模型。此外，它存储了训练 series，以防只传递了一个 TimeSeries。这使得可以在不传递单个 series 的情况下调用 predict()。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用作目标（即模型将训练预测的内容）的一个或多个序列
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定过去观测协变量的一个或多个序列
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定未来已知协变量的一个或多个序列
**kwargs – 可选参数，一些关键字参数。


返回
拟合的模型。

返回类型
self






fit_from_dataset(train_dataset, val_dataset=None, trainer=None, verbose=None, epochs=0, dataloader_kwargs=None)¶
使用特定的 darts.utils.data.TrainingDataset 实例训练模型。这些数据集实现了 PyTorch Dataset，并指定了如何对目标和协变量进行切片以进行训练。如果您不确定使用哪个训练数据集，可以考虑调用 fit() 方法，它将为此模型创建一个合适的默认训练数据集。
训练是使用 PyTorch Lightning Trainer 进行的。它使用预设和模型创建时使用的 pl_trainer_kwargs 中的默认 Trainer 对象。您还可以使用可选参数 trainer 使用自定义 Trainer。有关 PyTorch Lightning Trainers 的更多信息，请查看 此链接。
此函数可以多次调用以进行额外的训练。如果指定了 epochs，模型将训练额外的 epochs 个周期。

参数

train_dataset (TrainingDataset) – 类型与此模型匹配的训练数据集（例如，PastCovariatesTorchModel 使用 PastCovariatesTrainingDataset）。
val_dataset (Optional[TrainingDataset, None]) – 类型与此模型匹配的训练数据集（例如，PastCovariatesTorchModel 使用 :class:`PastCovariatesTorchModel`s），表示验证集（用于跟踪验证损失）。
trainer (Optional[Trainer, None]) – 可选参数，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认 trainer。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
epochs (int) – 如果指定，模型将训练额外的 epochs 个周期，无论模型构造函数中提供了多少 n_epochs。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选参数，用于创建训练和验证数据集的 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改这些参数时应小心，以避免意外行为。



返回
拟合的模型。

返回类型
self






generate_fit_encodings(series, past_covariates=None, future_covariates=None)¶
生成用于拟合模型的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入用于训练/拟合模型的相同的 series、past_covariates 和 future_covariates。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于拟合模型时带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，用于拟合模型时带有过去观测协变量的时间序列或时间序列序列。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，用于拟合模型时带有未来已知协变量的时间序列或时间序列序列。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶
生成用于训练和推理/预测的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入你打算用于训练和预测的相同的 series、past_covariates 和 future_covariates。

参数

n (int) – 在 series 结束之后，打算用于预测的时间步数。
series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于训练和预测的带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于训练和预测的过去观测协变量时间序列。维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的未来已知协变量时间序列。维度必须与训练时使用的协变量匹配。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶
生成用于推理/预测集的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入你打算用于预测的相同的 series、past_covariates 和 future_covariates。

参数

n (int) – 在 series 结束之后，打算用于预测的时间步数。
series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于预测的带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的过去观测协变量时间序列。维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的未来已知协变量时间序列。维度必须与训练时使用的协变量匹配。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






classmethod gridsearch(parameters, series, past_covariates=None, future_covariates=None, forecast_horizon=None, stride=1, start=None, start_format='value', last_points_only=False, show_warnings=True, val_series=None, use_fitted_values=False, metric=<function mape>, reduction=<function mean>, verbose=False, n_jobs=1, n_random_samples=None, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)¶
使用网格搜索在给定集合中找到最佳超参数。
此函数有 3 种操作模式：扩展窗口模式、拆分模式和拟合值模式。这三种操作模式通过使用 parameters 字典中提供的每种超参数值组合来实例化 ForecastingModel 的 model_class 子类，并评估每种组合，返回在 metric 函数方面性能最佳的模型。metric 函数应返回误差值，因此将选择产生最小 metric 输出的模型。
训练数据和测试数据的关系取决于操作模式。
扩展窗口模式（当传递 forecast_horizon 时激活）：对于每种超参数组合，模型在 series 的不同拆分上重复进行训练和评估。此过程通过使用 backtest() 函数作为子程序来实现，该子程序从 start 开始生成历史预测，并将这些预测与 series 的真实值进行比较。请注意，对于每次预测，模型都会重新训练，因此此模式速度较慢。
拆分窗口模式（当传递 val_series 时激活）：当传递 val_series 参数时，将使用此模式。对于每种超参数组合，模型将在 series 上训练，并在 val_series 上进行评估。
拟合值模式（当 use_fitted_values 设置为 True 时激活）：对于每种超参数组合，模型将在 series 上训练，并在生成的拟合值上进行评估。并非所有模型都有拟合值，如果模型没有 fitted_values 成员，此方法将引发错误。拟合值是模型在 series 上拟合的结果。与拟合值进行比较是评估模型的一种快速方法，但无法看出模型是否对时间序列过拟合。
派生类必须确保模型的单个实例不会与其他实例共享参数，例如，将模型保存在同一路径下。否则，在并行运行多个模型时（当 n_jobs != 1 时）可能会出现意外行为。如果无法避免这种情况，则应重新定义 gridsearch，强制设置 n_jobs = 1。
目前，此方法仅支持确定性预测（即当模型的预测只有 1 个样本时）。

参数

model_class – ForecastingModel 子类，用于对 ‘series’ 进行调优。
parameters (dict) – 一个字典，其中键为超参数名称，值为相应超参数值的列表。
series (TimeSeries) – 用作训练的输入和目标时间序列。
past_covariates (Optional[TimeSeries, None]) – 可选参数，过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Optional[TimeSeries, None]) – 可选参数，未来已知协变量时间序列。仅当模型支持未来协变量时适用。
forecast_horizon (Optional[int, None]) – 预测范围的整数值。激活扩展窗口模式。
stride (int) – 仅在扩展窗口模式下使用。两次连续预测之间的时间步数。
start (Union[Timestamp, float, int, None]) –
仅在扩展窗口模式下使用。可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果为 float，则表示时间序列在第一个预测点之前应占的比例。如果为 int，则对于带有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于带有 pd.RangeIndex 的 series，它是索引值。后一种情况可以通过 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则为第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

如果 retrain 为 False，或 retrain 是一个 Callable 且第一个可预测点早于第一个可训练点，则为第一个可预测点。
如果 retrain 为 True 或 int（给定 train_length），则为第一个可训练点；或者如果 retrain 是一个可调用对象 (Callable)，且第一个可训练点早于第一个可预测点。
否则为第一个可训练点（给定 train_length）


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

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

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



start_format (Literal[‘position’, ‘value’]) – 仅在扩展窗口模式下使用。定义 start 的格式。仅当 start 是整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，则 start 对应于第一个预测点的索引位置，范围可以在 (-len(series), len(series) - 1) 之间。如果设置为 ‘value’，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，则会引发错误。默认值：'value'
last_points_only (bool) – 仅在扩展窗口模式下使用。是使用整个预测序列还是仅使用每个预测的最后一个点来计算误差。
show_warnings (bool) – 仅在扩展窗口模式下使用。是否显示与 start 参数相关的警告。
val_series (Optional[TimeSeries, None]) – 在拆分模式下用于验证的时间序列实例。如果提供，此序列必须紧接在 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（顺序执行）。将参数设置为 -1 表示使用所有可用核心。
n_random_samples (Union[int, float, None]) – 从完整参数网格中选择的超参数组合的数量/比例。这将执行随机搜索而不是使用完整网格。如果为整数，n_random_samples 是从完整网格中选择的参数组合数量，必须介于 0 和总参数组合数量之间。如果为浮点数，n_random_samples 是从完整网格中选择的参数组合比例，必须介于 0 和 1 之间。默认为 None，此时将忽略随机选择。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

fit_kwargs (Optional[dict[str, Any], None]) – 传递给模型 fit() 方法的附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 传递给模型 predict() 方法的附加参数。
sample_weight (Union[TimeSeries, str, None]) – 可选参数，应用于目标 series 标签进行训练的样本权重。仅当 retrain 不为 False 时有效。它们按观测值、按标签（output_chunk_length 中的每个步骤）和按分量应用。如果是一个时间序列，则使用这些权重。如果权重时间序列只有一个分量/列，则权重将全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear”（线性）或 “exponential”（指数）衰减——时间越远，权重越低。


返回
一个元组，包含根据最佳超参数创建的未训练的 model_class 实例，以及一个包含这些最佳超参数的字典，以及最佳超参数的指标得分。

返回类型
ForecastingModel, Dict, float






historical_forecasts(series, past_covariates=None, future_covariates=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)¶
通过在提供的（可能多个）series 的整个历史记录中的各个时间点模拟预测，生成历史预测。此过程涉及将模型回顾性地应用于不同的时间步，就像在那些特定时刻进行了实时预测一样。这允许评估模型在整个序列持续时间内的性能，提供有关其在不同历史时期的预测准确性和鲁棒性的见解。
此方法有两种主要模式

重新训练模式（默认，retrain=True）：在模拟的每个步骤中，模型都会重新训练，并使用更新后的模型生成预测。如果存在多个时间序列，模型会在每个序列上独立重新训练（尚不支持全局训练）。
预训练模式（retrain=False）：在模拟的每个步骤中生成预测，无需重新训练。仅支持预训练的全局预测模型。此模式显著更快，因为它跳过了重新训练步骤。

通过选择合适的模式，可以在计算效率和更新模型训练需求之间取得平衡。
重新训练模式：此模式通过从 series 的开头扩展或使用固定长度的 train_length（起始点也可以通过 start 和 start_format 配置）重复构建训练集。然后在此训练集上训练模型，并生成长度为 forecast_horizon 的预测。随后，训练集的结束点向前移动 stride 个时间步，并重复此过程。
预训练模式：此模式仅支持预训练的全局预测模型。它使用与 重新训练模式 相同的模拟步骤（忽略 train_length），但直接生成预测，无需重新训练。
默认情况下，当 last_points_only=True 时，此方法返回一个由每个历史预测的最后一个点组成的单一时间序列（或时间序列序列）。因此，此时间序列的频率将是 series.freq * stride。如果 last_points_only=False，它将改为返回一个列表（或列表序列），其中包含完整的历史预测时间序列，每个序列的频率为 series.freq。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于依次训练（如果 retrain 不为 False）和计算历史预测的（序列）目标时间序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。
forecast_horizon (int) – 预测的预测期。
num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用大于 1 的值。
train_length (Optional[int, None]) – 可选参数，对每个构建的训练集使用固定的长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。
start (Union[Timestamp, float, int, None]) –
可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果是 float，则表示应位于第一个预测点之前的时间序列的比例。如果是 int，则对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果是 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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


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

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

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



start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

fit_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 fit() 方法的一些附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 predict() 方法的一些附加参数。
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于训练目标 series 标签的样本权重。仅当 retrain 不为 False 时有效。权重按观测、按标签（output_chunk_length 中的每个步骤）和按组件应用。如果是一个或多个序列，则使用这些权重。如果权重序列只有一个分量/列，则将权重全局应用于 series 中的所有分量。否则，对于特定于分量的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置的加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减 - 过去越远，权重越低。权重按时间 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 预测范围。外层列表对应于输入序列中提供的序列，内层列表包含每个序列的历史预测。








property input_chunk_length: int¶

返回类型
int






property likelihood: Optional[TorchLikelihood]¶
返回模型用于概率预测的似然（如果存在）。

返回类型
Optional[TorchLikelihood, None]






static load(path, pl_trainer_kwargs=None, **kwargs)¶
从给定文件路径加载模型。
从 RNNModel 的通用保存加载示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path)



从 CPU 训练的 RNNModel 加载到 GPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path, pl_trainer_kwargs={"accelerator": "gpu"})



从 GPU 保存的 RNNModel 加载到 CPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path, map_location="cpu", pl_trainer_kwargs={"accelerator": "gpu"})




参数

path (str) – 加载模型的路径。如果保存模型时未指定路径，则必须提供以 “.pt” 结尾的自动生成路径。
pl_trainer_kwargs (Optional[dict, None]) – 可选参数，用于创建一个新的 Lightning Trainer 的一组 kwargs，用于配置模型以进行下游任务（例如预测）。一些示例包括指定批量大小或将模型移动到 CPU/GPU。有关支持的 kwargs 的更多信息，请查看Lightning Trainer 文档。
**kwargs –
PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法的附加 kwargs，例如 map_location，用于将模型加载到与保存时不同的设备上。有关更多信息，请阅读官方文档。



返回类型
TorchForecastingModel






static load_from_checkpoint(model_name, work_dir=None, file_name=None, best=True, **kwargs)¶
从自动保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 下的检查点加载模型。此方法用于创建时设置了 save_checkpoints=True 的模型。
如果你手动保存了模型，请考虑使用 load()。
从检查点加载 RNNModel 的示例（model_name 是模型创建时使用的 model_name）

from darts.models import RNNModel

model_loaded = RNNModel.load_from_checkpoint(model_name, best=True)



如果给定了 file_name，则返回保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/{file_name}’ 下的模型。
如果未给定 file_name，将尝试从 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 恢复最佳检查点（如果 best 为 True）或最新检查点（如果 best 为 False）。
将保存在 GPU 上的 RNNModel 检查点加载到 CPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load_from_checkpoint(model_name, best=True, map_location="cpu")
model_loaded.to_cpu()




参数

model_name (str) – 模型名称，用于检索检查点文件夹的名称。
work_dir (Optional[str, None]) – 工作目录（包含检查点文件夹）。默认为当前工作目录。
file_name (Optional[str, None]) – 检查点文件的名称。如果未指定，则使用最新的一个。
best (bool) – 如果设置，将检索最佳模型（根据验证损失）而不是最新的模型。仅当给定 file_name 时忽略。
**kwargs –
附加 kwargs，用于 PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法，例如 map_location，用于将模型加载到与保存时不同的设备上。有关更多信息，请阅读官方文档。



返回
相应的训练好的 TorchForecastingModel。

返回类型
TorchForecastingModel






load_weights(path, load_encoders=True, skip_checks=False, **kwargs)¶
从手动保存的模型（使用 save() 保存）加载权重。
注意：此方法需要能够访问 darts 模型检查点 (.pt 文件) 才能加载编码器并对模型参数执行健全性检查。

参数

path (str) – 加载模型权重的路径。如果保存模型时未指定路径，则必须提供以 “.pt” 结尾的自动生成路径。
load_encoders (bool) – 如果设置，将从模型加载编码器，以启用直接调用 fit() 或 predict()。默认值：True。
skip_checks (bool) – 如果设置，将禁用加载编码器和对模型参数的健全性检查（不推荐）。不能与 load_encoders=True 一起使用。默认值：False。
**kwargs –
附加 kwargs，用于 PyTorch 的 load() 方法，例如 map_location，用于将模型加载到与保存时不同的设备上。有关更多信息，请阅读官方文档。








load_weights_from_checkpoint(model_name=None, work_dir=None, file_name=None, best=True, strict=True, load_encoders=True, skip_checks=False, **kwargs)¶
仅从自动保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 下的检查点加载权重。此方法用于创建时设置了 save_checkpoints=True 且需要使用不同的优化器或学习率调度器进行重新训练或微调的模型。但是，它也可以用于加载权重进行推理。
要恢复中断的训练，请考虑使用 load_from_checkpoint()，它也会重新加载训练器、优化器和学习率调度器的状态。
对于手动保存的模型，请考虑改用 load() 或 load_weights()。
注意：此方法需要能够访问 darts 模型检查点 (.pt 文件) 才能加载编码器并对模型参数执行健全性检查。

参数

model_name (Optional[str, None]) – 模型名称，用于检索检查点文件夹的名称。默认值：self.model_name。
work_dir (Optional[str, None]) – 工作目录（包含检查点文件夹）。默认为当前工作目录。
file_name (Optional[str, None]) – 检查点文件的名称。如果未指定，则使用最新的一个。
best (bool) – 如果设置，将检索最佳模型（根据验证损失）而不是最新的模型。仅当给定 file_name 时忽略。默认值：True。
strict (bool) –
如果设置，将严格执行 state_dict 中的键与此模块 state_dict() 返回的键匹配。默认值：True。有关更多信息，请阅读官方文档。

load_encoders (bool) – 如果设置，将从模型加载编码器，以启用直接调用 fit() 或 predict()。默认值：True。
skip_checks (bool) – 如果设置，将禁用加载编码器和对模型参数的健全性检查（不推荐）。不能与 load_encoders=True 一起使用。默认值：False。
**kwargs –
附加 kwargs，用于 PyTorch 的 load() 方法，例如 map_location，用于将模型加载到与保存时不同的设备上。有关更多信息，请阅读官方文档。








lr_find(series, past_covariates=None, future_covariates=None, val_series=None, val_past_covariates=None, val_future_covariates=None, sample_weight=None, val_sample_weight=None, trainer=None, verbose=None, epochs=0, max_samples_per_ts=None, dataloader_kwargs=None, min_lr=1e-08, max_lr=1, num_training=100, mode='exponential', early_stop_threshold=4.0)¶
PyTorch Lightning 的 Tuner.lr_find() 的一个包装器。执行一个好的初始学习率范围测试，以减少选择一个好的起始学习率时的猜测。有关 PyTorch Lightning Tuner 的更多信息，请查看此链接。如果调优器未给出令人满意的结果，建议增加 epochs 的数量。考虑使用建议的学习率创建一个新的模型对象，例如使用模型创建参数 optimizer_cls、optimizer_kwargs、lr_scheduler_cls 和 lr_scheduler_kwargs。
使用 RNNModel 的示例

import torch
from darts.datasets import AirPassengersDataset
from darts.models import NBEATSModel

series = AirPassengersDataset().load()
train, val = series[:-18], series[-18:]
model = NBEATSModel(input_chunk_length=12, output_chunk_length=6, random_state=42)
# run the learning rate tuner
results = model.lr_find(series=train, val_series=val)
# plot the results
results.plot(suggest=True, show=True)
# create a new model with the suggested learning rate
model = NBEATSModel(
    input_chunk_length=12,
    output_chunk_length=6,
    random_state=42,
    optimizer_cls=torch.optim.Adam,
    optimizer_kwargs={"lr": results.suggestion()}
)




参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用作目标（即模型将训练预测的内容）的一个或多个序列
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定过去观测协变量的一个或多个序列
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定未来已知协变量的一个或多个序列
val_series (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，一个或多个验证目标时间序列，将在训练过程中用于计算验证损失并跟踪性能最佳的模型。
val_past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，与验证序列对应的过去协变量（必须与 covariates 匹配）
val_future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，与验证序列对应的未来协变量（必须与 covariates 匹配）
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于目标 series 标签的样本权重。它们按观测值、按标签（output_chunk_length 中的每个步骤）和按分量应用。如果是一个时间序列或时间序列序列，则使用这些权重。如果权重时间序列只有一个分量/列，则权重将全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear”（线性）或 “exponential”（指数）衰减——时间越远，权重越低。权重是根据 series 中最长序列的长度全局计算的。然后对于每个序列，从全局权重的末尾提取权重。这为所有序列提供了共同的时间权重。
val_sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 与 sample_weight 相同，但用于评估数据集。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行训练。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
epochs (int) – 如果指定，模型将训练额外的 epochs 个周期，无论模型构造函数中提供了多少 n_epochs。
max_samples_per_ts (Optional[int, None]) – 可选地，每个时间序列使用的最大样本数。模型通过构建 (输入, 输出) 示例切片以监督方式进行训练。对于长时间序列，这可能导致训练样本数量不必要地庞大。此参数限制每个时间序列的训练样本数上限（仅取每个序列的最新样本）。留空（设置为 None）则不应用任何上限。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选参数，用于创建训练和验证数据集的 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改这些参数时应小心，以避免意外行为。

min_lr (float) – 要探索的最小学习率
max_lr (float) – 要探索的最大学习率
num_training (int) – 要测试的学习率数量
mode (str) – 在每个批次后更新学习率的搜索策略：‘exponential’：指数增加学习率。‘linear’：线性增加学习率。
early_stop_threshold (float) – 停止搜索的阈值。如果在任何时候损失大于 early_stop_threshold*best_loss，则停止搜索。要禁用，请设置为 None


返回
Lightning 的 _LRFinder 对象，包含学习率扫描的结果。

返回类型
lr_finder






property min_train_samples: int¶
模型训练所需的最小样本数。

返回类型
int






property model_created: bool¶

返回类型
bool






property model_params: dict¶

返回类型
字典






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

返回类型
int






property output_chunk_shift: int¶
输出/预测开始于输入结束之后的时间步数。

返回类型
int






predict(n, series=None, past_covariates=None, future_covariates=None, trainer=None, batch_size=None, verbose=None, n_jobs=1, roll_size=None, num_samples=1, dataloader_kwargs=None, mc_dropout=False, predict_likelihood_parameters=False, show_warnings=True)¶
预测训练序列或指定的 series 结束后的 n 个时间步。
预测使用 PyTorch Lightning Trainer 进行。它使用预设和 pl_trainer_kwargs 在模型创建时使用的默认 Trainer 对象。您也可以使用带有可选参数 trainer 的自定义 Trainer。有关 PyTorch Lightning Trainer 的更多信息，请查看 此链接。
下面记录了所有可能的参数，但并非所有模型都支持所有参数。例如，所有 PastCovariatesTorchModel 只支持 past_covariates 而不支持 future_covariates。如果您尝试使用错误的协变量参数调用模型上的 predict()，Darts 将会报错。
如果提供的协变量没有足够的时间跨度，Darts 也会报错。一般来说，并非所有模型都需要相同的协变量时间跨度。


依赖过去协变量的模型需要知道 past_covariates 的最后一个 input_chunk_length
点在预测时已知。对于预测范围值 n > output_chunk_length，这些模型
还需要知道至少接下来的 n - output_chunk_length 未来值。



依赖未来协变量的模型需要知道接下来的 n 值。
此外（对于 DualCovariatesTorchModel 和 MixedCovariatesTorchModel），它们也
需要这些未来协变量的“历史”值（在过去 input_chunk_length 的范围内）。



在处理协变量时，Darts 将尝试使用目标和协变量的时间轴来确定正确的时间切片。因此，协变量可以比所需的更长；只要时间轴正确，Darts 就会正确处理它们。如果其时间跨度不足，它也会报错。

参数

n (int) – 训练时间序列结束后需要生成预测的时间步数
series (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个序列或序列列表，代表要预测其未来的目标序列的历史。如果指定，该方法返回这些序列的预测。否则，该方法返回（单个）训练序列的预测。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，作为模型输入所需的过去观测协变量序列。它们的维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，作为模型输入所需的未来已知协变量序列。它们的维度必须与训练时使用的协变量匹配。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
batch_size (Optional[int, None]) – 预测期间的批次大小。默认为模型的训练 batch_size 值。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
n_jobs (int) – 并行运行的作业数量。-1 表示使用所有处理器。默认为 1。
roll_size (Optional[int, None]) – 对于自消耗预测，即 n > output_chunk_length，决定了在每次将预测目标（以及可选的未来协变量）反馈到模型时，模型的多少输出会被反馈。如果未提供此参数，它将默认为 output_chunk_length。
num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选地，一个用于为推理/预测数据集创建 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改它们时应谨慎，以避免意外行为。

mc_dropout (bool) – 可选地，为基于神经网络的模型预测启用蒙特卡洛 dropout。这可以通过指定学习模型的隐式先验来实现贝叶斯近似。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
show_warnings (bool) – 可选地，控制是否显示警告。并非对所有模型都有效。


返回
一个或多个包含 series 预测值的时间序列，或者如果未指定 series 且模型在单个序列上训练，则为训练序列的预测值。

返回类型
Union[TimeSeries, Sequence[TimeSeries]]






predict_from_dataset(n, input_series_dataset, trainer=None, batch_size=None, verbose=None, n_jobs=1, roll_size=None, num_samples=1, dataloader_kwargs=None, mc_dropout=False, predict_likelihood_parameters=False)¶
此方法允许使用特定的 darts.utils.data.InferenceDataset 实例进行预测。这些数据集实现了 PyTorch Dataset，并指定了如何为推理切分目标和协变量。在大多数情况下，您更希望调用 predict()，它将为您创建一个合适的 InferenceDataset。
预测使用 PyTorch Lightning Trainer 进行。它使用预设和 pl_trainer_kwargs 在模型创建时使用的默认 Trainer 对象。您也可以使用带有可选参数 trainer 的自定义 Trainer。有关 PyTorch Lightning Trainer 的更多信息，请查看 此链接。

参数

n (int) – 训练时间序列结束后需要生成预测的时间步数
input_series_dataset (InferenceDataset) – 可选地，一个序列或序列列表，代表要预测其未来的目标序列的历史。如果指定，该方法返回这些序列的预测。否则，该方法返回（单个）训练序列的预测。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
batch_size (Optional[int, None]) – 预测期间的批次大小。默认为模型的 batch_size 值。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
n_jobs (int) – 并行运行的作业数量。-1 表示使用所有处理器。默认为 1。
roll_size (Optional[int, None]) – 对于自消耗预测，即 n > output_chunk_length，决定了在每次将预测目标（以及可选的未来协变量）反馈到模型时，模型的多少输出会被反馈。如果未提供此参数，它将默认为 output_chunk_length。
num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选地，一个用于为推理/预测数据集创建 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改它们时应谨慎，以避免意外行为。

mc_dropout (bool) – 可选地，为基于神经网络的模型预测启用蒙特卡洛 dropout。这可以通过指定学习模型的隐式先验来实现贝叶斯近似。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 和 n<=output_chunk_length 的概率模型。默认值：False


返回
返回一个或多个时间序列的预测值。

返回类型
Sequence[TimeSeries]






reset_model()¶
重置模型对象并移除所有存储的数据 - 模型、检查点、日志记录器和训练历史。




residuals(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, metric=<function err>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None, values_only=False)¶
计算模型对（可能多个）series 的历史预测所产生的残差。
此函数计算来自 series 的实际观测值与通过在 series 上训练模型（或使用预训练模型并设置 retrain=False）获得的拟合值之间的差异（或 Darts 的“每时间步”指标之一）。并非所有模型都支持拟合值，因此我们使用历史预测作为它们的近似值。
此方法按顺序执行

使用预先计算的 historical_forecasts 或为每个序列计算历史预测（更多详细信息请参见 historical_forecasts()）。如何生成历史预测可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 来配置。
使用“每时间步” metric 指标计算历史预测与 series 之间的回测（针对每个分量/列和时间步）（更多详细信息请参见 backtest()）。默认情况下，使用残差 err() (误差) 作为 metric。
创建并返回带有历史预测时间索引和每个分量/时间步指标值的 TimeSeries（或者仅返回一个 np.ndarray 数组，如果设置了 values_only=True）。

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

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于依次训练（如果 retrain 不为 False）和计算历史预测的（序列）目标时间序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – 可选参数，要评估的（或序列/序列的序列）历史预测时间序列。对应于 historical_forecasts() 的输出。必须传递与生成历史预测时使用的相同的 series 和 last_points_only 值。如果提供，将跳过历史预测，并忽略除 series, last_points_only, metric 和 reduction 之外的所有参数。
forecast_horizon (int) – 预测的预测期。
num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用大于 1 的值。
train_length (Optional[int, None]) – 可选参数，对每个构建的训练集使用固定的长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。
start (Union[Timestamp, float, int, None]) –
可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果是 float，则表示应位于第一个预测点之前的时间序列的比例。如果是 int，则对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果是 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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


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

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

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



start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

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

verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

metric_kwargs (Optional[dict[str, Any], None]) – 传递给 metric() 的额外参数，例如用于并行的 ‘n_jobs’，用于缩放指标的 ‘m’ 等。仅当参数存在于相应的指标签名中时才会传递。忽略 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 计算。
values_only (bool) – 是否将残差作为 np.ndarray 返回。如果设置为 False，则将残差作为 TimeSeries 返回。


返回类型
Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

返回

TimeSeries – 单个 series 的残差 TimeSeries，以及使用 last_points_only=True 生成的 historical_forecasts。
List[TimeSeries] – 序列（列表）series 的残差 TimeSeries 列表，并设置了 last_points_only=True。残差列表的长度为 len(series)。
List[List[TimeSeries]] – 序列 series 的残差 TimeSeries 列表的列表，并设置了 last_points_only=False。外部残差列表的长度为 len(series)。内部列表包含所有可能的序列特定历史预测的残差。








save(path=None, clean=False)¶
在给定路径下保存模型。
在 path（模型对象）和 path.ckpt（检查点）下创建两个文件。
注意：使用自定义类保存模型时可能会出现 Pickle 错误。在这种情况下，请考虑使用 clean 标志从保存的模型中移除与训练相关的属性。
保存和加载 RNNModel 的示例

from darts.models import RNNModel

model = RNNModel(input_chunk_length=4)

model.save("my_model.pt")
model_loaded = RNNModel.load("my_model.pt")




参数

path (Optional[str, None]) – 用于保存模型当前状态的路径。请避免使用以“last-”或“best-”开头的路径，以避免与 Pytorch-Lightning 检查点冲突。如果未指定路径，模型将自动保存到 "{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.pt" 下。例如，"RNNModel_2020-01-01_12_00_00.pt"。
clean (bool) –
是否存储模型的清理版本。如果设置为 True，则训练序列和协变量将被移除。此外，还将移除所有与 Lightning Trainer 相关的参数（在模型创建时通过 pl_trainer_kwargs 传递）。
注意：加载使用 clean=True 存储的模型后，必须将 series 传递给 ‘predict()’、‘historical_forecasts()’ 和其他预测方法。



返回类型
None






property supports_future_covariates: bool¶
模型是否支持未来协变量

返回类型
bool






property supports_likelihood_parameter_prediction: bool¶
模型实例是否支持直接预测似然参数

返回类型
bool






property supports_multivariate: bool¶
模型是否考虑时间序列中的多个变量。

返回类型
bool






property supports_optimized_historical_forecasts: bool¶
模型是否支持优化后的历史预测

返回类型
bool






property supports_past_covariates: bool¶
模型是否支持过去协变量

返回类型
bool






property supports_probabilistic_prediction: bool¶
检查具有此配置的预测模型是否支持概率预测。
默认返回 False。需要由支持概率预测的模型覆盖。

返回类型
bool






property supports_sample_weight: bool¶
模型是否支持训练时的样本权重。

返回类型
bool






property supports_static_covariates: bool¶
模型是否支持静态协变量

返回类型
bool






property supports_transferable_series_prediction: bool¶
模型是否支持对任何输入 series 进行预测。

返回类型
bool






to_cpu()¶
更新 PyTorch Lightning Trainer 参数，以便下次调用 :fun:`fit()` 或 predict() 时将模型移动到 CPU。




to_onnx(path=None, **kwargs)¶
将模型导出为 ONNX 格式以进行优化推理，封装了 PyTorch Lightning 的 torch.onnx.export() 方法（官方文档）。
注意：需要安装 onnx 库（可选依赖）。
导出 DLinearModel 的示例
from darts.datasets import AirPassengersDataset
from darts.models import DLinearModel

series = AirPassengersDataset().load()
model = DLinearModel(input_chunk_length=4, output_chunk_length=1)
model.fit(series, epochs=1)
model.to_onnx("my_model.onnx")



参数

path (Optional[str, None]) – 保存模型当前状态的路径。如果未指定路径，模型将自动保存到 "{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.onnx" 下。
**kwargs –
PyTorch 的 load() 方法的额外关键字参数（除了参数 file_path、input_sample、input_name）。更多信息，请阅读 官方文档。








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




property uses_future_covariates: bool¶
模型在拟合后是否使用未来协变量。

返回类型
bool






property uses_past_covariates: bool¶
模型在拟合后是否使用过去协变量。

返回类型
bool






property uses_static_covariates: bool¶
模型在拟合后是否使用静态协变量。

返回类型
bool





class darts.models.forecasting.global_baseline_models.GlobalNaiveDrift(input_chunk_length, output_chunk_length, output_chunk_shift=0, **kwargs)[源文件]¶
基类： _NoCovariatesMixin, _GlobalNaiveModel
全局朴素漂移模型。
模型为每个 series 生成预测，具体描述如下

在每个目标分量的 input_chunk_length`th 和 `series 结束前的最后一个点之间，取斜率 m。
每个分量的预测值为 m * x + c，其中 x 是值 range(1 + output_chunk_shift, 1 + output_chunk_length + output_chunk_shift)，而 c 是每个目标分量的最后一个值。

根据调用 model.predict() 时使用的预测期 n，预测结果可以是

如果 n <= output_chunk_length，则为线性漂移，或者
如果 n > output_chunk_length，则为移动漂移，这是自回归预测的结果。

此模型等同于

NaiveDrift，当 input_chunk_length 等于输入目标 series 的长度且 output_chunk_length=n 时。


注意

全局朴素模型不支持使用 save_checkpoints=True 进行模型检查点保存，也不支持使用 load_from_checkpoint() 和 load_weights_from_checkpoint() 加载检查点。



参数

input_chunk_length (int) – 输入给模型的输入序列的长度。
output_chunk_length (int) – 模型输出的预测序列和输出序列的长度。
output_chunk_shift (int) – 可选参数，将输出块的开始位置向未来偏移的步数（相对于输入块的结束）。这将创建输入和输出之间的间隙。如果模型支持 future_covariates，则从偏移后的输出块中提取未来值。预测将从目标 series 结束后的 output_chunk_shift 步开始。如果设置了 output_chunk_shift，则模型无法生成自回归预测（即 n > output_chunk_length）。
**kwargs – 可选参数，用于初始化 pytorch_lightning.Module, pytorch_lightning.Trainer 和 Darts 的 TorchForecastingModel。由于朴素模型不进行训练，以下参数将无效：loss_fn, likelihood, optimizer_cls, optimizer_kwargs, lr_scheduler_cls, lr_scheduler_kwargs, n_epochs, save_checkpoints 以及部分 pl_trainer_kwargs。



示例
>>> from darts.datasets import IceCreamHeaterDataset
>>> from darts.models import GlobalNaiveDrift
>>> # create list of multivariate series
>>> series_1 = IceCreamHeaterDataset().load()
>>> series_2 = series_1 + 100.
>>> series = [series_1, series_2]
>>> # predict 3 months, use drift over the last 60 months
>>> horizon, icl = 3, 60
>>> # linear drift (with `output_chunk_length = horizon`)
>>> model = GlobalNaiveDrift(input_chunk_length=icl, output_chunk_length=horizon)
>>> # predict after end of each multivariate series
>>> pred = model.fit(series).predict(n=horizon, series=series)
>>> [p.values() for p in pred]
[array([[24.135593, 74.28814 ],
       [24.271187, 74.57627 ],
       [24.40678 , 74.86441 ]]), array([[124.13559, 174.28813],
       [124.27119, 174.57628],
       [124.40678, 174.86441]])]
>>> # moving drift (with `output_chunk_length < horizon`)
>>> model = GlobalNaiveDrift(input_chunk_length=icl, output_chunk_length=1)
>>> pred = model.fit(series).predict(n=horizon, series=series)
>>> [p.values() for p in pred]
[array([[24.135593, 74.28814 ],
       [24.256536, 74.784546],
       [24.34563 , 75.45886 ]]), array([[124.13559, 174.28813],
       [124.25653, 174.78455],
       [124.34563, 175.45886]])]


属性






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

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

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

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

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

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

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

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

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

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

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

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

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

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

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









epochs_trained


input_chunk_length


model_created


model_params


supports_future_covariates


supports_past_covariates


supports_static_covariates




方法






backtest(series[, past_covariates, ...])¶
计算模型对（可能多个）series 的历史预测所产生的误差值。

fit(series[, past_covariates, future_covariates])¶
在一个（或可能多个）序列上拟合/训练模型。

fit_from_dataset(train_dataset[, ...])¶
使用特定的 darts.utils.data.TrainingDataset 实例训练模型。

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])¶
从给定文件路径加载模型。

load_from_checkpoint(model_name[, work_dir, ...])¶
从 '{work_dir}/darts_logs/{model_name}/checkpoints/' 下自动保存的检查点加载模型。

load_weights(path[, load_encoders, skip_checks])¶
从手动保存的模型（使用 save() 保存）加载权重。

load_weights_from_checkpoint([model_name, ...])¶
仅从 '{work_dir}/darts_logs/{model_name}/ checkpoints/' 下自动保存的检查点加载权重。

lr_find(series[, past_covariates, ...])¶
PyTorch Lightning 的 Tuner.lr_find() 的包装器。

predict(n[, series, past_covariates, ...])¶
预测训练序列或指定的 series 结束后的 n 个时间步。

predict_from_dataset(n, input_series_dataset)¶
此方法允许使用特定的 darts.utils.data.InferenceDataset 实例进行预测。

reset_model()
重置模型对象并移除所有存储的数据 - 模型、检查点、日志记录器和训练历史。

residuals(series[, past_covariates, ...])¶
计算模型对（可能多个）series 的历史预测所产生的残差。

save([path, clean])¶
在给定路径下保存模型。

to_cpu()
更新 PyTorch Lightning Trainer 参数，以便下次调用 :fun:`fit()` 或 predict() 时将模型移动到 CPU。

to_onnx([path])¶
将模型导出为 ONNX 格式以优化推理，封装了 PyTorch Lightning 的 torch.onnx.export() 方法（官方文档）。


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 是一个 Callable 且第一个可预测点早于第一个可训练点，则为第一个可预测点。
如果 retrain 为 True 或 int>（给定 train_length），或 retrain 是一个 Callable 且第一个可训练点早于第一个可预测点，则为第一个可训练点。

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


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

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

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



start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

metric (Union[Callable[…, Union[float, list[float], ndarray, list[ndarray]]], list[Callable[…, Union[float, list[float], ndarray, list[ndarray]]]]]) –
一个指标函数或指标函数列表。每个指标必须是 Darts 指标之一（参见 此处），或者一个自定义指标，其签名与 Darts 指标相同，使用装饰器 multi_ts_support() 和 multi_ts_support()，并返回指标分数。

reduction (Optional[Callable[…, float], None]) – 用于组合当 last_points_only 设置为 False 时获得的单个误差得分的函数。提供多个指标函数时，该函数将接收参数 axis = 1，以便为每个指标函数获得一个单一值。如果明确设置为 None，则该方法将返回单个误差得分列表。默认为 np.mean。
verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – 传递给 metric() 的附加参数，例如用于并行化的 ‘n_jobs’，用于减少组件维度指标的 ‘component_reduction’，用于缩放指标的季节性参数 ‘m’ 等。将为每个指标分别传递参数，并且仅当它们出现在相应的指标签名中时。缩放指标（例如 mase`, rmsse 等）的参数 ‘insample’ 将被忽略，因为它在内部处理。
fit_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 fit() 方法的一些附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 predict() 方法的一些附加参数。
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于训练目标 series 标签的样本权重。仅当 retrain 不为 False 时有效。权重按观测、按标签（output_chunk_length 中的每个步骤）和按组件应用。如果是一个或多个序列，则使用这些权重。如果权重序列只有一个分量/列，则将权重全局应用于 series 中的所有分量。否则，对于特定于分量的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置的加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减 - 过去越远，权重越低。权重按时间 series 计算。


返回类型
Union[float, ndarray, list[float], list[ndarray]]

返回

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

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测得分
使用 last_points_only=False 生成的 historical_forecasts 并使用回测 reduction，返回单个回测得分


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

单个 metric 函数，使用 last_points_only=False 生成的 historical_forecasts，并设置回测 reduction=None。输出形状为 (n forecasts, *)。
多个 metric 函数和使用 last_points_only=False 生成的 historical_forecasts。使用回测 reduction 时，输出形状为 (*, n metrics)，而当 reduction=None 时，输出形状为 (n forecasts, *, n metrics)
包括 series_reduction 的多个单变量/多变量序列，以及至少一个 component_reduction=None 或 time_reduction=None（用于“按时间步指标”）。


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








property considers_static_covariates: bool¶
模型是否考虑静态协变量（如果存在）。

返回类型
bool






property epochs_trained: int¶

返回类型
int






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, *args, **kwargs)¶
在一个（或可能多个）序列上拟合/训练模型。此方法仅为朴素基线模型实现，以便与其他预测模型提供统一的拟合/预测 API。
模型并未真正基于输入进行训练，但 fit() 用于根据输入序列设置模型。此外，它存储了训练 series，以防只传递了一个 TimeSeries。这使得可以在不传递单个 series 的情况下调用 predict()。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用作目标（即模型将训练预测的内容）的一个或多个序列
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定过去观测协变量的一个或多个序列
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定未来已知协变量的一个或多个序列
**kwargs – 可选参数，一些关键字参数。


返回
拟合的模型。

返回类型
self






fit_from_dataset(train_dataset, val_dataset=None, trainer=None, verbose=None, epochs=0, dataloader_kwargs=None)¶
使用特定的 darts.utils.data.TrainingDataset 实例训练模型。这些数据集实现了 PyTorch Dataset，并指定了如何为训练切分目标和协变量。如果您不确定使用哪种训练数据集，请考虑调用 fit()，它将为此模型创建一个默认的训练数据集。
训练是使用 PyTorch Lightning Trainer 进行的。它使用预设和模型创建时使用的 pl_trainer_kwargs 中的默认 Trainer 对象。您还可以使用可选参数 trainer 使用自定义 Trainer。有关 PyTorch Lightning Trainers 的更多信息，请查看 此链接。
此函数可以多次调用以进行额外的训练。如果指定了 epochs，模型将训练额外的 epochs 个周期。

参数

train_dataset (TrainingDataset) – 类型与此模型匹配的训练数据集（例如，PastCovariatesTorchModel 使用 PastCovariatesTrainingDataset）。
val_dataset (Optional[TrainingDataset, None]) – 一个类型与此模型匹配的训练数据集（例如，:class:`PastCovariatesTorchModel`s 的 PastCovariatesTrainingDataset），代表验证集（用于跟踪验证损失）。
trainer (Optional[Trainer, None]) – 可选参数，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认 trainer。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
epochs (int) – 如果指定，模型将训练额外的 epochs 个周期，无论模型构造函数中提供了多少 n_epochs。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选参数，用于创建训练和验证数据集的 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改这些参数时应小心，以避免意外行为。



返回
拟合的模型。

返回类型
self






generate_fit_encodings(series, past_covariates=None, future_covariates=None)¶
生成用于拟合模型的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入用于训练/拟合模型的相同的 series、past_covariates 和 future_covariates。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于拟合模型时带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，用于拟合模型时带有过去观测协变量的时间序列或时间序列序列。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，用于拟合模型时带有未来已知协变量的时间序列或时间序列序列。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶
生成用于训练和推理/预测的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入你打算用于训练和预测的相同的 series、past_covariates 和 future_covariates。

参数

n (int) – 在 series 结束之后，打算用于预测的时间步数。
series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于训练和预测的带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于训练和预测的过去观测协变量时间序列。维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的未来已知协变量时间序列。维度必须与训练时使用的协变量匹配。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶
生成用于推理/预测集的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入你打算用于预测的相同的 series、past_covariates 和 future_covariates。

参数

n (int) – 在 series 结束之后，打算用于预测的时间步数。
series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于预测的带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的过去观测协变量时间序列。维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的未来已知协变量时间序列。维度必须与训练时使用的协变量匹配。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






classmethod gridsearch(parameters, series, past_covariates=None, future_covariates=None, forecast_horizon=None, stride=1, start=None, start_format='value', last_points_only=False, show_warnings=True, val_series=None, use_fitted_values=False, metric=<function mape>, reduction=<function mean>, verbose=False, n_jobs=1, n_random_samples=None, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)¶
使用网格搜索在给定集合中找到最佳超参数。
此函数有 3 种操作模式：扩展窗口模式、拆分模式和拟合值模式。这三种操作模式通过使用 parameters 字典中提供的每种超参数值组合来实例化 ForecastingModel 的 model_class 子类，并评估每种组合，返回在 metric 函数方面性能最佳的模型。metric 函数应返回误差值，因此将选择产生最小 metric 输出的模型。
训练数据和测试数据的关系取决于操作模式。
扩展窗口模式（当传递 forecast_horizon 时激活）：对于每个超参数组合，模型会在 series 的不同分割上重复训练和评估。这个过程通过使用 backtest() 函数作为子程序来实现，生成从 start 开始的历史预测，并与 series 的真实值进行比较。请注意，模型会为每个单独的预测重新训练，因此此模式较慢。
拆分窗口模式（当传递 val_series 时激活）：当传递 val_series 参数时，将使用此模式。对于每种超参数组合，模型将在 series 上训练，并在 val_series 上进行评估。
拟合值模式（当 use_fitted_values 设置为 True 时激活）：对于每种超参数组合，模型将在 series 上训练，并在生成的拟合值上进行评估。并非所有模型都有拟合值，如果模型没有 fitted_values 成员，此方法将引发错误。拟合值是模型在 series 上拟合的结果。与拟合值进行比较是评估模型的一种快速方法，但无法看出模型是否对时间序列过拟合。
派生类必须确保模型的单个实例不会与其他实例共享参数，例如，将模型保存在同一路径下。否则，在并行运行多个模型时（当 n_jobs != 1 时）可能会出现意外行为。如果无法避免这种情况，则应重新定义 gridsearch，强制设置 n_jobs = 1。
目前，此方法仅支持确定性预测（即当模型的预测只有 1 个样本时）。

参数

model_class – ForecastingModel 子类，用于对 ‘series’ 进行调优。
parameters (dict) – 一个字典，其中键为超参数名称，值为相应超参数值的列表。
series (TimeSeries) – 用作训练的输入和目标时间序列。
past_covariates (Optional[TimeSeries, None]) – 可选参数，过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Optional[TimeSeries, None]) – 可选参数，未来已知协变量时间序列。仅当模型支持未来协变量时适用。
forecast_horizon (Optional[int, None]) – 预测范围的整数值。激活扩展窗口模式。
stride (int) – 仅在扩展窗口模式下使用。两次连续预测之间的时间步数。
start (Union[Timestamp, float, int, None]) –
仅在扩展窗口模式下使用。可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果为 float，则表示时间序列在第一个预测点之前应占的比例。如果为 int，则对于带有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于带有 pd.RangeIndex 的 series，它是索引值。后一种情况可以通过 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则为第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

如果 retrain 为 False，或 retrain 是一个 Callable 且第一个可预测点早于第一个可训练点，则为第一个可预测点。
如果 retrain 为 True 或 int（给定 train_length），则为第一个可训练点；或者如果 retrain 是一个可调用对象 (Callable)，且第一个可训练点早于第一个可预测点。
否则为第一个可训练点（给定 train_length）


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

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

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



start_format (Literal[‘position’, ‘value’]) – 仅在扩展窗口模式下使用。定义 start 的格式。仅当 start 是整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，则 start 对应于第一个预测点的索引位置，范围可以在 (-len(series), len(series) - 1) 之间。如果设置为 ‘value’，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，则会引发错误。默认值：'value'
last_points_only (bool) – 仅在扩展窗口模式下使用。是使用整个预测序列还是仅使用每个预测的最后一个点来计算误差。
show_warnings (bool) – 仅在扩展窗口模式下使用。是否显示与 start 参数相关的警告。
val_series (Optional[TimeSeries, None]) – 在拆分模式下用于验证的时间序列实例。如果提供，此序列必须紧接在 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（顺序执行）。将参数设置为 -1 表示使用所有可用核心。
n_random_samples (Union[int, float, None]) – 从完整参数网格中选择的超参数组合的数量/比例。这将执行随机搜索而不是使用完整网格。如果为整数，n_random_samples 是从完整网格中选择的参数组合数量，必须介于 0 和总参数组合数量之间。如果为浮点数，n_random_samples 是从完整网格中选择的参数组合比例，必须介于 0 和 1 之间。默认为 None，此时将忽略随机选择。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

fit_kwargs (Optional[dict[str, Any], None]) – 传递给模型 fit() 方法的附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 传递给模型 predict() 方法的附加参数。
sample_weight (Union[TimeSeries, str, None]) – 可选参数，应用于目标 series 标签进行训练的样本权重。仅当 retrain 不为 False 时有效。它们按观测值、按标签（output_chunk_length 中的每个步骤）和按分量应用。如果是一个时间序列，则使用这些权重。如果权重时间序列只有一个分量/列，则权重将全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear”（线性）或 “exponential”（指数）衰减——时间越远，权重越低。


返回
一个元组，包含根据最佳超参数创建的未训练的 model_class 实例，以及一个包含这些最佳超参数的字典，以及最佳超参数的指标得分。

返回类型
ForecastingModel, Dict, float






historical_forecasts(series, past_covariates=None, future_covariates=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)¶
通过在提供的（可能多个）series 的整个历史记录中的各个时间点模拟预测，生成历史预测。此过程涉及将模型回顾性地应用于不同的时间步，就像在那些特定时刻进行了实时预测一样。这允许评估模型在整个序列持续时间内的性能，提供有关其在不同历史时期的预测准确性和鲁棒性的见解。
此方法有两种主要模式

重新训练模式（默认，retrain=True）：在模拟的每个步骤中，模型都会重新训练，并使用更新后的模型生成预测。如果存在多个时间序列，模型会在每个序列上独立重新训练（尚不支持全局训练）。
预训练模式（retrain=False）：在模拟的每个步骤中生成预测，无需重新训练。仅支持预训练的全局预测模型。此模式显著更快，因为它跳过了重新训练步骤。

通过选择合适的模式，可以在计算效率和更新模型训练需求之间取得平衡。
重新训练模式：此模式通过从 series 的开头扩展或使用固定长度的 train_length（起始点也可以通过 start 和 start_format 配置）重复构建训练集。然后在此训练集上训练模型，并生成长度为 forecast_horizon 的预测。随后，训练集的结束点向前移动 stride 个时间步，并重复此过程。
预训练模式：此模式仅支持预训练的全局预测模型。它使用与 重新训练模式 相同的模拟步骤（忽略 train_length），但直接生成预测，无需重新训练。
默认情况下，当 last_points_only=True 时，此方法返回一个由每个历史预测的最后一个点组成的单一时间序列（或时间序列序列）。因此，此时间序列的频率将是 series.freq * stride。如果 last_points_only=False，它将改为返回一个列表（或列表序列），其中包含完整的历史预测时间序列，每个序列的频率为 series.freq。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于依次训练（如果 retrain 不为 False）和计算历史预测的（序列）目标时间序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。
forecast_horizon (int) – 预测的预测期。
num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用大于 1 的值。
train_length (Optional[int, None]) – 可选参数，对每个构建的训练集使用固定的长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。
start (Union[Timestamp, float, int, None]) –
可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果是 float，则表示应位于第一个预测点之前的时间序列的比例。如果是 int，则对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果是 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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


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

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

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



start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

fit_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 fit() 方法的一些附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 predict() 方法的一些附加参数。
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于训练目标 series 标签的样本权重。仅当 retrain 不为 False 时有效。权重按观测、按标签（output_chunk_length 中的每个步骤）和按组件应用。如果是一个或多个序列，则使用这些权重。如果权重序列只有一个分量/列，则将权重全局应用于 series 中的所有分量。否则，对于特定于分量的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置的加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减 - 过去越远，权重越低。权重按时间 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 预测范围。外层列表对应于输入序列中提供的序列，内层列表包含每个序列的历史预测。








property input_chunk_length: int¶

返回类型
int






property likelihood: Optional[TorchLikelihood]¶
返回模型用于概率预测的似然（如果存在）。

返回类型
Optional[TorchLikelihood, None]






static load(path, pl_trainer_kwargs=None, **kwargs)¶
从给定文件路径加载模型。
从 RNNModel 的通用保存加载示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path)



从 CPU 训练的 RNNModel 加载到 GPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path, pl_trainer_kwargs={"accelerator": "gpu"})



从 GPU 保存的 RNNModel 加载到 CPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path, map_location="cpu", pl_trainer_kwargs={"accelerator": "gpu"})




参数

path (str) – 加载模型的路径。如果保存模型时未指定路径，则必须提供以 “.pt” 结尾的自动生成路径。
pl_trainer_kwargs (Optional[dict, None]) –
可选地，一组用于创建新的 Lightning Trainer 的关键字参数，用于配置模型以执行下游任务（例如预测）。一些示例包括指定批次大小或将模型移动到 CPU/GPU。查看 Lightning Trainer 文档 以获取有关支持的关键字参数的更多信息。

**kwargs –
PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法的附加 kwargs，例如 map_location，用于将模型加载到与保存时不同的设备上。有关更多信息，请阅读官方文档。



返回类型
TorchForecastingModel






static load_from_checkpoint(model_name, work_dir=None, file_name=None, best=True, **kwargs)¶
从自动保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 下的检查点加载模型。此方法用于创建时设置了 save_checkpoints=True 的模型。
如果你手动保存了模型，请考虑使用 load()。
从检查点加载 RNNModel 的示例（model_name 是模型创建时使用的 model_name）

from darts.models import RNNModel

model_loaded = RNNModel.load_from_checkpoint(model_name, best=True)



如果给定了 file_name，则返回保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/{file_name}’ 下的模型。
如果未给定 file_name，将尝试从 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 恢复最佳检查点（如果 best 为 True）或最新检查点（如果 best 为 False）。
将保存在 GPU 上的 RNNModel 检查点加载到 CPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load_from_checkpoint(model_name, best=True, map_location="cpu")
model_loaded.to_cpu()




参数

model_name (str) – 模型名称，用于检索检查点文件夹的名称。
work_dir (Optional[str, None]) – 工作目录（包含检查点文件夹）。默认为当前工作目录。
file_name (Optional[str, None]) – 检查点文件的名称。如果未指定，则使用最新的一个。
best (bool) – 如果设置，将检索最佳模型（根据验证损失）而不是最新的模型。仅当给定 file_name 时忽略。
**kwargs –
附加 kwargs，用于 PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法，例如 map_location，用于将模型加载到与保存时不同的设备上。有关更多信息，请阅读官方文档。



返回
相应的训练好的 TorchForecastingModel。

返回类型
TorchForecastingModel






load_weights(path, load_encoders=True, skip_checks=False, **kwargs)¶
从手动保存的模型（使用 save() 保存）加载权重。
注意：此方法需要能够访问 darts 模型检查点 (.pt 文件) 才能加载编码器并对模型参数执行健全性检查。

参数

path (str) – 加载模型权重的路径。如果保存模型时未指定路径，则必须提供以 “.pt” 结尾的自动生成路径。
load_encoders (bool) – 如果设置，将从模型加载编码器，以启用直接调用 fit() 或 predict()。默认值：True。
skip_checks (bool) – 如果设置，将禁用加载编码器和对模型参数的健全性检查（不推荐）。不能与 load_encoders=True 一起使用。默认值：False。
**kwargs –
PyTorch 的 load() 方法的额外关键字参数，例如用于将模型加载到与保存时不同设备的 map_location。更多信息，请阅读 官方文档。








load_weights_from_checkpoint(model_name=None, work_dir=None, file_name=None, best=True, strict=True, load_encoders=True, skip_checks=False, **kwargs)¶
仅从自动保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 下的检查点加载权重。此方法用于创建时设置了 save_checkpoints=True 且需要使用不同的优化器或学习率调度器进行重新训练或微调的模型。但是，它也可以用于加载权重进行推理。
要恢复中断的训练，请考虑使用 load_from_checkpoint()，它也会重新加载训练器、优化器和学习率调度器的状态。
对于手动保存的模型，请考虑改用 load() 或 load_weights()。
注意：此方法需要能够访问 darts 模型检查点 (.pt 文件) 才能加载编码器并对模型参数执行健全性检查。

参数

model_name (Optional[str, None]) – 模型名称，用于检索检查点文件夹的名称。默认值：self.model_name。
work_dir (Optional[str, None]) – 工作目录（包含检查点文件夹）。默认为当前工作目录。
file_name (Optional[str, None]) – 检查点文件的名称。如果未指定，则使用最新的一个。
best (bool) – 如果设置，将检索最佳模型（根据验证损失）而不是最新的模型。仅当给定 file_name 时忽略。默认值：True。
strict (bool) –
如果设置，将严格执行 state_dict 中的键与此模块 state_dict() 返回的键匹配。默认值：True。有关更多信息，请阅读官方文档。

load_encoders (bool) – 如果设置，将从模型加载编码器，以启用直接调用 fit() 或 predict()。默认值：True。
skip_checks (bool) – 如果设置，将禁用加载编码器和对模型参数的健全性检查（不推荐）。不能与 load_encoders=True 一起使用。默认值：False。
**kwargs –
PyTorch 的 load() 方法的额外关键字参数，例如用于将模型加载到与保存时不同设备的 map_location。更多信息，请阅读 官方文档。








lr_find(series, past_covariates=None, future_covariates=None, val_series=None, val_past_covariates=None, val_future_covariates=None, sample_weight=None, val_sample_weight=None, trainer=None, verbose=None, epochs=0, max_samples_per_ts=None, dataloader_kwargs=None, min_lr=1e-08, max_lr=1, num_training=100, mode='exponential', early_stop_threshold=4.0)¶
PyTorch Lightning 的 Tuner.lr_find() 的一个包装器。执行一个好的初始学习率范围测试，以减少选择一个好的起始学习率时的猜测。有关 PyTorch Lightning Tuner 的更多信息，请查看此链接。如果调优器未给出令人满意的结果，建议增加 epochs 的数量。考虑使用建议的学习率创建一个新的模型对象，例如使用模型创建参数 optimizer_cls、optimizer_kwargs、lr_scheduler_cls 和 lr_scheduler_kwargs。
使用 RNNModel 的示例

import torch
from darts.datasets import AirPassengersDataset
from darts.models import NBEATSModel

series = AirPassengersDataset().load()
train, val = series[:-18], series[-18:]
model = NBEATSModel(input_chunk_length=12, output_chunk_length=6, random_state=42)
# run the learning rate tuner
results = model.lr_find(series=train, val_series=val)
# plot the results
results.plot(suggest=True, show=True)
# create a new model with the suggested learning rate
model = NBEATSModel(
    input_chunk_length=12,
    output_chunk_length=6,
    random_state=42,
    optimizer_cls=torch.optim.Adam,
    optimizer_kwargs={"lr": results.suggestion()}
)




参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用作目标（即模型将训练预测的内容）的一个或多个序列
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定过去观测协变量的一个或多个序列
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定未来已知协变量的一个或多个序列
val_series (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，一个或多个验证目标时间序列，将在训练过程中用于计算验证损失并跟踪性能最佳的模型。
val_past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，与验证序列对应的过去协变量（必须与 covariates 匹配）
val_future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，与验证序列对应的未来协变量（必须与 covariates 匹配）
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于目标 series 标签的样本权重。它们按观测值、按标签（output_chunk_length 中的每个步骤）和按分量应用。如果是一个时间序列或时间序列序列，则使用这些权重。如果权重时间序列只有一个分量/列，则权重将全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear”（线性）或 “exponential”（指数）衰减——时间越远，权重越低。权重是根据 series 中最长序列的长度全局计算的。然后对于每个序列，从全局权重的末尾提取权重。这为所有序列提供了共同的时间权重。
val_sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 与 sample_weight 相同，但用于评估数据集。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行训练。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
epochs (int) – 如果指定，模型将训练额外的 epochs 个周期，无论模型构造函数中提供了多少 n_epochs。
max_samples_per_ts (Optional[int, None]) – 可选地，每个时间序列使用的最大样本数。模型通过构建 (输入, 输出) 示例切片以监督方式进行训练。对于长时间序列，这可能导致训练样本数量不必要地庞大。此参数限制每个时间序列的训练样本数上限（仅取每个序列的最新样本）。留空（设置为 None）则不应用任何上限。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选参数，用于创建训练和验证数据集的 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改这些参数时应小心，以避免意外行为。

min_lr (float) – 要探索的最小学习率
max_lr (float) – 要探索的最大学习率
num_training (int) – 要测试的学习率数量
mode (str) – 在每个批次后更新学习率的搜索策略：‘exponential’：指数增加学习率。‘linear’：线性增加学习率。
early_stop_threshold (float) – 停止搜索的阈值。如果在任何时候损失大于 early_stop_threshold*best_loss，则停止搜索。要禁用，请设置为 None


返回
Lightning 的 _LRFinder 对象，包含学习率扫描的结果。

返回类型
lr_finder






property min_train_samples: int¶
模型训练所需的最小样本数。

返回类型
int






property model_created: bool¶

返回类型
bool






property model_params: dict¶

返回类型
字典






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

返回类型
int






property output_chunk_shift: int¶
输出/预测开始于输入结束之后的时间步数。

返回类型
int






predict(n, series=None, past_covariates=None, future_covariates=None, trainer=None, batch_size=None, verbose=None, n_jobs=1, roll_size=None, num_samples=1, dataloader_kwargs=None, mc_dropout=False, predict_likelihood_parameters=False, show_warnings=True)¶
预测训练序列或指定的 series 结束后的 n 个时间步。
预测使用 PyTorch Lightning Trainer 进行。它使用预设和 pl_trainer_kwargs 在模型创建时使用的默认 Trainer 对象。您也可以使用带有可选参数 trainer 的自定义 Trainer。有关 PyTorch Lightning Trainer 的更多信息，请查看 此链接。
下面记录了所有可能的参数，但并非所有模型都支持所有参数。例如，所有 PastCovariatesTorchModel 只支持 past_covariates 而不支持 future_covariates。如果您尝试使用错误的协变量参数调用模型上的 predict()，Darts 将会报错。
如果提供的协变量没有足够的时间跨度，Darts 也会报错。一般来说，并非所有模型都需要相同的协变量时间跨度。


依赖过去协变量的模型需要知道 past_covariates 的最后一个 input_chunk_length
点在预测时已知。对于预测范围值 n > output_chunk_length，这些模型
还需要知道至少接下来的 n - output_chunk_length 未来值。



依赖未来协变量的模型需要知道接下来的 n 值。
此外（对于 DualCovariatesTorchModel 和 MixedCovariatesTorchModel），它们也
需要这些未来协变量的“历史”值（在过去 input_chunk_length 的范围内）。



在处理协变量时，Darts 将尝试使用目标和协变量的时间轴来确定正确的时间切片。因此，协变量可以比所需的更长；只要时间轴正确，Darts 就会正确处理它们。如果其时间跨度不足，它也会报错。

参数

n (int) – 训练时间序列结束后需要生成预测的时间步数
series (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个序列或序列列表，代表要预测其未来的目标序列的历史。如果指定，该方法返回这些序列的预测。否则，该方法返回（单个）训练序列的预测。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，作为模型输入所需的过去观测协变量序列。它们的维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，作为模型输入所需的未来已知协变量序列。它们的维度必须与训练时使用的协变量匹配。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
batch_size (Optional[int, None]) – 预测期间的批次大小。默认为模型的训练 batch_size 值。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
n_jobs (int) – 并行运行的作业数量。-1 表示使用所有处理器。默认为 1。
roll_size (Optional[int, None]) – 对于自消耗预测，即 n > output_chunk_length，决定了在每次将预测目标（以及可选的未来协变量）反馈到模型时，模型的多少输出会被反馈。如果未提供此参数，它将默认为 output_chunk_length。
num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选地，一个用于为推理/预测数据集创建 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改它们时应谨慎，以避免意外行为。

mc_dropout (bool) – 可选地，为基于神经网络的模型预测启用蒙特卡洛 dropout。这可以通过指定学习模型的隐式先验来实现贝叶斯近似。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
show_warnings (bool) – 可选地，控制是否显示警告。并非对所有模型都有效。


返回
一个或多个包含 series 预测值的时间序列，或者如果未指定 series 且模型在单个序列上训练，则为训练序列的预测值。

返回类型
Union[TimeSeries, Sequence[TimeSeries]]






predict_from_dataset(n, input_series_dataset, trainer=None, batch_size=None, verbose=None, n_jobs=1, roll_size=None, num_samples=1, dataloader_kwargs=None, mc_dropout=False, predict_likelihood_parameters=False)¶
此方法允许使用特定的 darts.utils.data.InferenceDataset 实例进行预测。这些数据集实现了 PyTorch Dataset，并指定了目标和协变量如何用于推理。在大多数情况下，您会更倾向于调用 predict()，它将为您创建一个合适的 InferenceDataset。
预测使用 PyTorch Lightning Trainer 进行。它使用预设和 pl_trainer_kwargs 在模型创建时使用的默认 Trainer 对象。您也可以使用带有可选参数 trainer 的自定义 Trainer。有关 PyTorch Lightning Trainer 的更多信息，请查看 此链接。

参数

n (int) – 训练时间序列结束后需要生成预测的时间步数
input_series_dataset (InferenceDataset) – 可选地，一个序列或序列列表，代表要预测其未来的目标序列的历史。如果指定，该方法返回这些序列的预测。否则，该方法返回（单个）训练序列的预测。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
batch_size (Optional[int, None]) – 预测期间的批次大小。默认为模型的 batch_size 值。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
n_jobs (int) – 并行运行的作业数量。-1 表示使用所有处理器。默认为 1。
roll_size (Optional[int, None]) – 对于自消耗预测，即 n > output_chunk_length，决定了在每次将预测目标（以及可选的未来协变量）反馈到模型时，模型的多少输出会被反馈。如果未提供此参数，它将默认为 output_chunk_length。
num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选地，一个用于为推理/预测数据集创建 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改它们时应谨慎，以避免意外行为。

mc_dropout (bool) – 可选地，为基于神经网络的模型预测启用蒙特卡洛 dropout。这可以通过指定学习模型的隐式先验来实现贝叶斯近似。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 和 n<=output_chunk_length 的概率模型。默认值：False


返回
返回一个或多个时间序列的预测值。

返回类型
Sequence[TimeSeries]






reset_model()¶
重置模型对象并移除所有存储的数据 - 模型、检查点、日志记录器和训练历史。




residuals(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, metric=<function err>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None, values_only=False)¶
计算模型对（可能多个）series 的历史预测所产生的残差。
此函数计算来自 series 的实际观测值与通过在 series 上训练模型（或使用预训练模型并设置 retrain=False）获得的拟合值之间的差异（或 Darts 的“每时间步”指标之一）。并非所有模型都支持拟合值，因此我们使用历史预测作为它们的近似值。
此方法按顺序执行

使用预先计算的 historical_forecasts 或为每个序列计算历史预测（更多详细信息请参见 historical_forecasts()）。如何生成历史预测可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 来配置。
使用“每时间步” metric 指标计算历史预测与 series 之间的回测（针对每个分量/列和时间步）（更多详细信息请参见 backtest()）。默认情况下，使用残差 err() (误差) 作为 metric。
创建并返回带有历史预测时间索引和每个分量/时间步指标值的 TimeSeries（或者仅返回一个 np.ndarray 数组，如果设置了 values_only=True）。

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

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于依次训练（如果 retrain 不为 False）和计算历史预测的（序列）目标时间序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – 可选参数，要评估的（或序列/序列的序列）历史预测时间序列。对应于 historical_forecasts() 的输出。必须传递与生成历史预测时使用的相同的 series 和 last_points_only 值。如果提供，将跳过历史预测，并忽略除 series, last_points_only, metric 和 reduction 之外的所有参数。
forecast_horizon (int) – 预测的预测期。
num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用大于 1 的值。
train_length (Optional[int, None]) – 可选参数，对每个构建的训练集使用固定的长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。
start (Union[Timestamp, float, int, None]) –
可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果是 float，则表示应位于第一个预测点之前的时间序列的比例。如果是 int，则对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果是 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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


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

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

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



start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

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

verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

metric_kwargs (Optional[dict[str, Any], None]) – 传递给 metric() 的额外参数，例如用于并行的 ‘n_jobs’，用于缩放指标的 ‘m’ 等。仅当参数存在于相应的指标签名中时才会传递。忽略 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 计算。
values_only (bool) – 是否将残差作为 np.ndarray 返回。如果设置为 False，则将残差作为 TimeSeries 返回。


返回类型
Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

返回

TimeSeries – 单个 series 的残差 TimeSeries，以及使用 last_points_only=True 生成的 historical_forecasts。
List[TimeSeries] – 序列（列表）series 的残差 TimeSeries 列表，并设置了 last_points_only=True。残差列表的长度为 len(series)。
List[List[TimeSeries]] – 序列 series 的残差 TimeSeries 列表的列表，并设置了 last_points_only=False。外部残差列表的长度为 len(series)。内部列表包含所有可能的序列特定历史预测的残差。








save(path=None, clean=False)¶
在给定路径下保存模型。
在 path（模型对象）和 path.ckpt（检查点）下创建两个文件。
注意：使用自定义类保存模型时可能会出现 Pickle 错误。在这种情况下，请考虑使用 clean 标志从保存的模型中移除与训练相关的属性。
保存和加载 RNNModel 的示例

from darts.models import RNNModel

model = RNNModel(input_chunk_length=4)

model.save("my_model.pt")
model_loaded = RNNModel.load("my_model.pt")




参数

path (Optional[str, None]) – 用于保存模型当前状态的路径。请避免使用以“last-”或“best-”开头的路径，以避免与 Pytorch-Lightning 检查点冲突。如果未指定路径，模型将自动保存到 "{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.pt" 下。例如，"RNNModel_2020-01-01_12_00_00.pt"。
clean (bool) –
是否存储模型的清理版本。如果设置为 True，则训练序列和协变量将被移除。此外，还将移除所有与 Lightning Trainer 相关的参数（在模型创建时通过 pl_trainer_kwargs 传递）。
注意：加载使用 clean=True 存储的模型后，必须将 series 传递给 ‘predict()’、‘historical_forecasts()’ 和其他预测方法。



返回类型
None






property supports_future_covariates: bool¶
模型是否支持未来协变量

返回类型
bool






property supports_likelihood_parameter_prediction: bool¶
模型实例是否支持直接预测似然参数

返回类型
bool






property supports_multivariate: bool¶
模型是否考虑时间序列中的多个变量。

返回类型
bool






property supports_optimized_historical_forecasts: bool¶
模型是否支持优化后的历史预测

返回类型
bool






property supports_past_covariates: bool¶
模型是否支持过去协变量

返回类型
bool






property supports_probabilistic_prediction: bool¶
检查具有此配置的预测模型是否支持概率预测。
默认返回 False。需要由支持概率预测的模型覆盖。

返回类型
bool






property supports_sample_weight: bool¶
模型是否支持训练时的样本权重。

返回类型
bool






property supports_static_covariates: bool¶
模型是否支持静态协变量

返回类型
bool






property supports_transferable_series_prediction: bool¶
模型是否支持对任何输入 series 进行预测。

返回类型
bool






to_cpu()¶
更新 PyTorch Lightning Trainer 参数，以便下次调用 :fun:`fit()` 或 predict() 时将模型移动到 CPU。




to_onnx(path=None, **kwargs)¶
将模型导出为 ONNX 格式以进行优化推理，封装了 PyTorch Lightning 的 torch.onnx.export() 方法（官方文档）。
注意：需要安装 onnx 库（可选依赖）。
导出 DLinearModel 的示例
from darts.datasets import AirPassengersDataset
from darts.models import DLinearModel

series = AirPassengersDataset().load()
model = DLinearModel(input_chunk_length=4, output_chunk_length=1)
model.fit(series, epochs=1)
model.to_onnx("my_model.onnx")



参数

path (Optional[str, None]) – 保存模型当前状态的路径。如果未指定路径，模型将自动保存到 "{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.onnx" 下。
**kwargs –
PyTorch 的 load() 方法的额外关键字参数（除了参数 file_path、input_sample、input_name）。更多信息，请阅读 官方文档。








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




property uses_future_covariates: bool¶
模型在拟合后是否使用未来协变量。

返回类型
bool






property uses_past_covariates: bool¶
模型在拟合后是否使用过去协变量。

返回类型
bool






property uses_static_covariates: bool¶
模型在拟合后是否使用静态协变量。

返回类型
bool








class darts.models.forecasting.global_baseline_models.GlobalNaiveSeasonal(input_chunk_length, output_chunk_length, output_chunk_shift=0, **kwargs)[source]¶
基类： _NoCovariatesMixin, _GlobalNaiveModel
全局朴素季节模型。
模型为每个 series 生成预测，具体描述如下

取每个目标分量在目标 series 结束前 input_chunk_length 个点处的值。
预测值是将该分量值重复 output_chunk_length 次。

根据调用 model.predict() 时使用的预测期 n，预测结果可以是

如果 n <= output_chunk_length，则为常数值，或者
如果 n > output_chunk_length，则为移动（季节性）值，作为自回归预测的结果。

此模型等同于

NaiveSeasonal，当 input_chunk_length 等于输入目标 series 的长度且 output_chunk_length=1 时。


注意

全局朴素模型不支持使用 save_checkpoints=True 进行模型检查点保存，也不支持使用 load_from_checkpoint() 和 load_weights_from_checkpoint() 加载检查点。



参数

input_chunk_length (int) – 输入给模型的输入序列的长度。
output_chunk_length (int) – 模型输出的预测序列和输出序列的长度。
output_chunk_shift (int) – 可选参数，将输出块的开始位置向未来偏移的步数（相对于输入块的结束）。这将创建输入和输出之间的间隙。如果模型支持 future_covariates，则从偏移后的输出块中提取未来值。预测将从目标 series 结束后的 output_chunk_shift 步开始。如果设置了 output_chunk_shift，则模型无法生成自回归预测（即 n > output_chunk_length）。
**kwargs – 可选参数，用于初始化 pytorch_lightning.Module, pytorch_lightning.Trainer 和 Darts 的 TorchForecastingModel。由于朴素模型不进行训练，以下参数将无效：loss_fn, likelihood, optimizer_cls, optimizer_kwargs, lr_scheduler_cls, lr_scheduler_kwargs, n_epochs, save_checkpoints 以及部分 pl_trainer_kwargs。



示例
>>> from darts.datasets import IceCreamHeaterDataset
>>> from darts.models import GlobalNaiveSeasonal
>>> # create list of multivariate series
>>> series_1 = IceCreamHeaterDataset().load()
>>> series_2 = series_1 + 100.
>>> series = [series_1, series_2]
>>> # predict 3 months, use value from 12 months ago
>>> horizon, icl = 3, 12
>>> # repeated seasonal value (with `output_chunk_length = horizon`)
>>> model = GlobalNaiveSeasonal(input_chunk_length=icl, output_chunk_length=horizon)
>>> # predict after end of each multivariate series
>>> pred = model.fit(series).predict(n=horizon, series=series)
>>> [p.values() for p in pred]
[array([[ 21., 100.],
       [ 21., 100.],
       [ 21., 100.]]), array([[121., 200.],
       [121., 200.],
       [121., 200.]])]
>>> # moving seasonal value (with `output_chunk_length < horizon`)
>>> model = GlobalNaiveSeasonal(input_chunk_length=icl, output_chunk_length=1)
>>> pred = model.fit(series).predict(n=horizon, series=series)
>>> [p.values() for p in pred]
[array([[ 21., 100.],
       [ 21.,  68.],
       [ 24.,  51.]]), array([[121., 200.],
       [121., 168.],
       [124., 151.]])]


属性






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

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

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

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

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

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

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

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

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

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

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

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

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

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

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









epochs_trained


input_chunk_length


model_created


model_params


supports_future_covariates


supports_past_covariates


supports_static_covariates




方法






backtest(series[, past_covariates, ...])
计算模型对（可能多个）series 的历史预测所产生的误差值。

fit(series[, past_covariates, future_covariates])
在一个（或可能多个）序列上拟合/训练模型。

fit_from_dataset(train_dataset[, ...])
使用特定的 darts.utils.data.TrainingDataset 实例训练模型。

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])
从给定文件路径加载模型。

load_from_checkpoint(model_name[, work_dir, ...])
从 '{work_dir}/darts_logs/{model_name}/checkpoints/' 下自动保存的检查点加载模型。

load_weights(path[, load_encoders, skip_checks])
从手动保存的模型（使用 save() 保存）加载权重。

load_weights_from_checkpoint([model_name, ...])
仅从 '{work_dir}/darts_logs/{model_name}/ checkpoints/' 下自动保存的检查点加载权重。

lr_find(series[, past_covariates, ...])
PyTorch Lightning 的 Tuner.lr_find() 的包装器。

predict(n[, series, past_covariates, ...])
预测训练序列或指定的 series 结束后的 n 个时间步。

predict_from_dataset(n, input_series_dataset)
此方法允许使用特定的 darts.utils.data.InferenceDataset 实例进行预测。

reset_model()
重置模型对象并移除所有存储的数据 - 模型、检查点、日志记录器和训练历史。

residuals(series[, past_covariates, ...])
计算模型对（可能多个）series 的历史预测所产生的残差。

save([path, clean])
在给定路径下保存模型。

to_cpu()
更新 PyTorch Lightning Trainer 参数，以便下次调用 :fun:`fit()` 或 predict() 时将模型移动到 CPU。

to_onnx([path])
将模型导出为 ONNX 格式以优化推理，封装了 PyTorch Lightning 的 torch.onnx.export() 方法（官方文档）。


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 是一个 Callable 且第一个可预测点早于第一个可训练点，则为第一个可预测点。
如果 retrain 为 True 或 int>（给定 train_length），或 retrain 是一个 Callable 且第一个可训练点早于第一个可预测点，则为第一个可训练点。

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


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

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

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



start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

metric (Union[Callable[…, Union[float, list[float], ndarray, list[ndarray]]], list[Callable[…, Union[float, list[float], ndarray, list[ndarray]]]]]) –
一个指标函数或指标函数列表。每个指标必须是 Darts 指标之一（参见 此处），或者一个自定义指标，其签名与 Darts 指标相同，使用装饰器 multi_ts_support() 和 multi_ts_support()，并返回指标分数。

reduction (Optional[Callable[…, float], None]) – 用于组合当 last_points_only 设置为 False 时获得的单个误差得分的函数。提供多个指标函数时，该函数将接收参数 axis = 1，以便为每个指标函数获得一个单一值。如果明确设置为 None，则该方法将返回单个误差得分列表。默认为 np.mean。
verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – 传递给 metric() 的附加参数，例如用于并行化的 ‘n_jobs’，用于减少组件维度指标的 ‘component_reduction’，用于缩放指标的季节性参数 ‘m’ 等。将为每个指标分别传递参数，并且仅当它们出现在相应的指标签名中时。缩放指标（例如 mase`, rmsse 等）的参数 ‘insample’ 将被忽略，因为它在内部处理。
fit_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 fit() 方法的一些附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 predict() 方法的一些附加参数。
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于训练目标 series 标签的样本权重。仅当 retrain 不为 False 时有效。权重按观测、按标签（output_chunk_length 中的每个步骤）和按组件应用。如果是一个或多个序列，则使用这些权重。如果权重序列只有一个分量/列，则将权重全局应用于 series 中的所有分量。否则，对于特定于分量的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置的加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减 - 过去越远，权重越低。权重按时间 series 计算。


返回类型
Union[float, ndarray, list[float], list[ndarray]]

返回

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

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测得分
使用 last_points_only=False 生成的 historical_forecasts 并使用回测 reduction，返回单个回测得分


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

单个 metric 函数，historical_forecasts 生成时使用 last_points_only=False 且回测 reduction=None。输出的形状为 (n forecasts, *)。
多个 metric 函数，historical_forecasts 生成时使用 last_points_only=False。使用回测 reduction 时，输出的形状为 (*, n metrics)，当 reduction=None 时，输出的形状为 (n forecasts, *, n metrics)。
包括 series_reduction 的多个单变量/多变量序列，以及至少一个 component_reduction=None 或 time_reduction=None（用于“按时间步指标”）。


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








property considers_static_covariates: bool¶
模型是否考虑静态协变量（如果存在）。

返回类型
bool






property epochs_trained: int¶

返回类型
int






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, *args, **kwargs)¶
在一个（或可能多个）序列上拟合/训练模型。此方法仅为朴素基线模型实现，以便与其他预测模型提供统一的拟合/预测 API。
模型并未真正基于输入进行训练，但 fit() 用于根据输入序列设置模型。此外，它存储了训练 series，以防只传递了一个 TimeSeries。这使得可以在不传递单个 series 的情况下调用 predict()。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用作目标（即模型将训练预测的内容）的一个或多个序列
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定过去观测协变量的一个或多个序列
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定未来已知协变量的一个或多个序列
**kwargs – 可选参数，一些关键字参数。


返回
拟合的模型。

返回类型
self






fit_from_dataset(train_dataset, val_dataset=None, trainer=None, verbose=None, epochs=0, dataloader_kwargs=None)¶
使用特定的 darts.utils.data.TrainingDataset 实例训练模型。这些数据集实现了 PyTorch Dataset，并指定了目标和协变量如何用于训练。如果您不确定使用哪种训练数据集，可以考虑调用 fit()，它将为您创建一个适合此模型的默认训练数据集。
训练是使用 PyTorch Lightning Trainer 进行的。它使用预设和模型创建时使用的 pl_trainer_kwargs 中的默认 Trainer 对象。您还可以使用可选参数 trainer 使用自定义 Trainer。有关 PyTorch Lightning Trainers 的更多信息，请查看 此链接。
此函数可以多次调用以进行额外的训练。如果指定了 epochs，模型将训练额外的 epochs 个周期。

参数

train_dataset (TrainingDataset) – 类型与此模型匹配的训练数据集（例如，PastCovariatesTorchModel 使用 PastCovariatesTrainingDataset）。
val_dataset (Optional[TrainingDataset, None]) – 与此模型类型匹配的训练数据集（例如，:class:`PastCovariatesTorchModel`s），代表验证集（用于跟踪验证损失）。
trainer (Optional[Trainer, None]) – 可选参数，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认 trainer。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
epochs (int) – 如果指定，模型将训练额外的 epochs 个周期，无论模型构造函数中提供了多少 n_epochs。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选参数，用于创建训练和验证数据集的 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改这些参数时应小心，以避免意外行为。



返回
拟合的模型。

返回类型
self






generate_fit_encodings(series, past_covariates=None, future_covariates=None)¶
生成用于拟合模型的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入用于训练/拟合模型的相同的 series、past_covariates 和 future_covariates。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于拟合模型时带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，用于拟合模型时带有过去观测协变量的时间序列或时间序列序列。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，用于拟合模型时带有未来已知协变量的时间序列或时间序列序列。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶
生成用于训练和推理/预测的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入你打算用于训练和预测的相同的 series、past_covariates 和 future_covariates。

参数

n (int) – 在 series 结束之后，打算用于预测的时间步数。
series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于训练和预测的带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于训练和预测的过去观测协变量时间序列。维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的未来已知协变量时间序列。维度必须与训练时使用的协变量匹配。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)¶
生成用于推理/预测集的协变量编码，并返回一个元组，其中包含过去协变量和未来协变量的时间序列，原始协变量和编码后的协变量堆叠在一起。编码是由模型创建时使用参数 add_encoders 定义的编码器生成的。请传入你打算用于预测的相同的 series、past_covariates 和 future_covariates。

参数

n (int) – 在 series 结束之后，打算用于预测的时间步数。
series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于预测的带有目标值的时间序列或时间序列序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的过去观测协变量时间序列。维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，打算用于预测的未来已知协变量时间序列。维度必须与训练时使用的协变量匹配。


返回
一个元组，包含（过去协变量，未来协变量）。每个协变量都包含原始协变量和编码后的协变量。

返回类型
Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]






classmethod gridsearch(parameters, series, past_covariates=None, future_covariates=None, forecast_horizon=None, stride=1, start=None, start_format='value', last_points_only=False, show_warnings=True, val_series=None, use_fitted_values=False, metric=<function mape>, reduction=<function mean>, verbose=False, n_jobs=1, n_random_samples=None, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)¶
使用网格搜索在给定集合中找到最佳超参数。
此函数有 3 种操作模式：扩展窗口模式、拆分模式和拟合值模式。这三种操作模式通过使用 parameters 字典中提供的每种超参数值组合来实例化 ForecastingModel 的 model_class 子类，并评估每种组合，返回在 metric 函数方面性能最佳的模型。metric 函数应返回误差值，因此将选择产生最小 metric 输出的模型。
训练数据和测试数据的关系取决于操作模式。
扩展窗口模式（当传递 forecast_horizon 时激活）：对于每种超参数组合，模型会在 series 的不同切片上重复进行训练和评估。此过程通过使用 backtest() 函数作为子程序来完成，生成从 start 开始的历史预测值，并与 series 的真实值进行比较。请注意，模型会为每个单独的预测进行重新训练，因此此模式较慢。
拆分窗口模式（当传递 val_series 时激活）：当传递 val_series 参数时，将使用此模式。对于每种超参数组合，模型将在 series 上训练，并在 val_series 上进行评估。
拟合值模式（当 use_fitted_values 设置为 True 时激活）：对于每种超参数组合，模型将在 series 上训练，并在生成的拟合值上进行评估。并非所有模型都有拟合值，如果模型没有 fitted_values 成员，此方法将引发错误。拟合值是模型在 series 上拟合的结果。与拟合值进行比较是评估模型的一种快速方法，但无法看出模型是否对时间序列过拟合。
派生类必须确保模型的单个实例不会与其他实例共享参数，例如，将模型保存在同一路径下。否则，在并行运行多个模型时（当 n_jobs != 1 时）可能会出现意外行为。如果无法避免这种情况，则应重新定义 gridsearch，强制设置 n_jobs = 1。
目前，此方法仅支持确定性预测（即当模型的预测只有 1 个样本时）。

参数

model_class – ForecastingModel 子类，用于对 ‘series’ 进行调优。
parameters (dict) – 一个字典，其中键为超参数名称，值为相应超参数值的列表。
series (TimeSeries) – 用作训练的输入和目标时间序列。
past_covariates (Optional[TimeSeries, None]) – 可选参数，过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Optional[TimeSeries, None]) – 可选参数，未来已知协变量时间序列。仅当模型支持未来协变量时适用。
forecast_horizon (Optional[int, None]) – 预测范围的整数值。激活扩展窗口模式。
stride (int) – 仅在扩展窗口模式下使用。两次连续预测之间的时间步数。
start (Union[Timestamp, float, int, None]) –
仅在扩展窗口模式下使用。可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果为 float，则表示时间序列在第一个预测点之前应占的比例。如果为 int，则对于带有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于带有 pd.RangeIndex 的 series，它是索引值。后一种情况可以通过 start_format=”position” 更改为索引位置。如果为 pandas.Timestamp，则为第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为

如果 retrain 为 False，或 retrain 是一个 Callable 且第一个可预测点早于第一个可训练点，则为第一个可预测点。
如果 retrain 为 True 或 int（给定 train_length），则为第一个可训练点；或者如果 retrain 是一个可调用对象 (Callable)，且第一个可训练点早于第一个可预测点。
否则为第一个可训练点（给定 train_length）


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

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

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



start_format (Literal[‘position’, ‘value’]) – 仅在扩展窗口模式下使用。定义 start 的格式。仅当 start 是整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为 ‘position’，则 start 对应于第一个预测点的索引位置，范围可以在 (-len(series), len(series) - 1) 之间。如果设置为 ‘value’，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，则会引发错误。默认值：'value'
last_points_only (bool) – 仅在扩展窗口模式下使用。是使用整个预测序列还是仅使用每个预测的最后一个点来计算误差。
show_warnings (bool) – 仅在扩展窗口模式下使用。是否显示与 start 参数相关的警告。
val_series (Optional[TimeSeries, None]) – 在拆分模式下用于验证的时间序列实例。如果提供，此序列必须紧接在 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（顺序执行）。将参数设置为 -1 表示使用所有可用核心。
n_random_samples (Union[int, float, None]) – 从完整参数网格中选择的超参数组合的数量/比例。这将执行随机搜索而不是使用完整网格。如果为整数，n_random_samples 是从完整网格中选择的参数组合数量，必须介于 0 和总参数组合数量之间。如果为浮点数，n_random_samples 是从完整网格中选择的参数组合比例，必须介于 0 和 1 之间。默认为 None，此时将忽略随机选择。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

fit_kwargs (Optional[dict[str, Any], None]) – 传递给模型 fit() 方法的附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 传递给模型 predict() 方法的附加参数。
sample_weight (Union[TimeSeries, str, None]) – 可选参数，应用于目标 series 标签进行训练的样本权重。仅当 retrain 不为 False 时有效。它们按观测值、按标签（output_chunk_length 中的每个步骤）和按分量应用。如果是一个时间序列，则使用这些权重。如果权重时间序列只有一个分量/列，则权重将全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear”（线性）或 “exponential”（指数）衰减——时间越远，权重越低。


返回
一个元组，包含根据最佳超参数创建的未训练的 model_class 实例，以及一个包含这些最佳超参数的字典，以及最佳超参数的指标得分。

返回类型
ForecastingModel, Dict, float






historical_forecasts(series, past_covariates=None, future_covariates=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)¶
通过在提供的（可能多个）series 的整个历史记录中的各个时间点模拟预测，生成历史预测。此过程涉及将模型回顾性地应用于不同的时间步，就像在那些特定时刻进行了实时预测一样。这允许评估模型在整个序列持续时间内的性能，提供有关其在不同历史时期的预测准确性和鲁棒性的见解。
此方法有两种主要模式

重新训练模式（默认，retrain=True）：在模拟的每个步骤中，模型都会重新训练，并使用更新后的模型生成预测。如果存在多个时间序列，模型会在每个序列上独立重新训练（尚不支持全局训练）。
预训练模式（retrain=False）：在模拟的每个步骤中生成预测，无需重新训练。仅支持预训练的全局预测模型。此模式显著更快，因为它跳过了重新训练步骤。

通过选择合适的模式，可以在计算效率和更新模型训练需求之间取得平衡。
重新训练模式：此模式通过从 series 的开头扩展或使用固定长度的 train_length（起始点也可以通过 start 和 start_format 配置）重复构建训练集。然后在此训练集上训练模型，并生成长度为 forecast_horizon 的预测。随后，训练集的结束点向前移动 stride 个时间步，并重复此过程。
预训练模式：此模式仅支持预训练的全局预测模型。它使用与 重新训练模式 相同的模拟步骤（忽略 train_length），但直接生成预测，无需重新训练。
默认情况下，当 last_points_only=True 时，此方法返回一个由每个历史预测的最后一个点组成的单一时间序列（或时间序列序列）。因此，此时间序列的频率将是 series.freq * stride。如果 last_points_only=False，它将改为返回一个列表（或列表序列），其中包含完整的历史预测时间序列，每个序列的频率为 series.freq。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于依次训练（如果 retrain 不为 False）和计算历史预测的（序列）目标时间序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。
forecast_horizon (int) – 预测的预测期。
num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用大于 1 的值。
train_length (Optional[int, None]) – 可选参数，对每个构建的训练集使用固定的长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。
start (Union[Timestamp, float, int, None]) –
可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果是 float，则表示应位于第一个预测点之前的时间序列的比例。如果是 int，则对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果是 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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


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

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

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



start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

fit_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 fit() 方法的一些附加参数。
predict_kwargs (Optional[dict[str, Any], None]) – 可选参数，传递给模型 predict() 方法的一些附加参数。
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于训练目标 series 标签的样本权重。仅当 retrain 不为 False 时有效。权重按观测、按标签（output_chunk_length 中的每个步骤）和按组件应用。如果是一个或多个序列，则使用这些权重。如果权重序列只有一个分量/列，则将权重全局应用于 series 中的所有分量。否则，对于特定于分量的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置的加权函数生成权重。可用选项是 “linear” 或 “exponential” 衰减 - 过去越远，权重越低。权重按时间 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 预测范围。外层列表对应于输入序列中提供的序列，内层列表包含每个序列的历史预测。








property input_chunk_length: int¶

返回类型
int






property likelihood: Optional[TorchLikelihood]¶
返回模型用于概率预测的似然（如果存在）。

返回类型
Optional[TorchLikelihood, None]






static load(path, pl_trainer_kwargs=None, **kwargs)¶
从给定文件路径加载模型。
从 RNNModel 的通用保存加载示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path)



从 CPU 训练的 RNNModel 加载到 GPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path, pl_trainer_kwargs={"accelerator": "gpu"})



从 GPU 保存的 RNNModel 加载到 CPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load(path, map_location="cpu", pl_trainer_kwargs={"accelerator": "gpu"})




参数

path (str) – 加载模型的路径。如果保存模型时未指定路径，则必须提供以 “.pt” 结尾的自动生成路径。
pl_trainer_kwargs (Optional[dict, None]) –
可选地，一组用于创建新的 Lightning Trainer 的关键字参数，用于配置模型以执行下游任务（例如预测）。一些示例包括指定批次大小或将模型移动到 CPU/GPU。查看 Lightning Trainer 文档 以获取有关支持的关键字参数的更多信息。

**kwargs –
PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法的附加 kwargs，例如 map_location，用于将模型加载到与保存时不同的设备上。有关更多信息，请阅读官方文档。



返回类型
TorchForecastingModel






static load_from_checkpoint(model_name, work_dir=None, file_name=None, best=True, **kwargs)¶
从自动保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 下的检查点加载模型。此方法用于创建时设置了 save_checkpoints=True 的模型。
如果你手动保存了模型，请考虑使用 load()。
从检查点加载 RNNModel 的示例（model_name 是模型创建时使用的 model_name）

from darts.models import RNNModel

model_loaded = RNNModel.load_from_checkpoint(model_name, best=True)



如果给定了 file_name，则返回保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/{file_name}’ 下的模型。
如果未给定 file_name，将尝试从 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 恢复最佳检查点（如果 best 为 True）或最新检查点（如果 best 为 False）。
将保存在 GPU 上的 RNNModel 检查点加载到 CPU 的示例

from darts.models import RNNModel

model_loaded = RNNModel.load_from_checkpoint(model_name, best=True, map_location="cpu")
model_loaded.to_cpu()




参数

model_name (str) – 模型名称，用于检索检查点文件夹的名称。
work_dir (Optional[str, None]) – 工作目录（包含检查点文件夹）。默认为当前工作目录。
file_name (Optional[str, None]) – 检查点文件的名称。如果未指定，则使用最新的一个。
best (bool) – 如果设置，将检索最佳模型（根据验证损失）而不是最新的模型。仅当给定 file_name 时忽略。
**kwargs –
附加 kwargs，用于 PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法，例如 map_location，用于将模型加载到与保存时不同的设备上。有关更多信息，请阅读官方文档。



返回
相应的训练好的 TorchForecastingModel。

返回类型
TorchForecastingModel






load_weights(path, load_encoders=True, skip_checks=False, **kwargs)¶
从手动保存的模型（使用 save() 保存）加载权重。
注意：此方法需要能够访问 darts 模型检查点 (.pt 文件) 才能加载编码器并对模型参数执行健全性检查。

参数

path (str) – 加载模型权重的路径。如果保存模型时未指定路径，则必须提供以 “.pt” 结尾的自动生成路径。
load_encoders (bool) – 如果设置，将从模型加载编码器，以启用直接调用 fit() 或 predict()。默认值：True。
skip_checks (bool) – 如果设置，将禁用加载编码器和对模型参数的健全性检查（不推荐）。不能与 load_encoders=True 一起使用。默认值：False。
**kwargs –
PyTorch 的 load() 方法的附加关键字参数，例如 map_location 用于将模型加载到与保存模型时不同的设备上。更多信息请参阅官方文档。








load_weights_from_checkpoint(model_name=None, work_dir=None, file_name=None, best=True, strict=True, load_encoders=True, skip_checks=False, **kwargs)¶
仅从自动保存在 ‘{work_dir}/darts_logs/{model_name}/checkpoints/’ 下的检查点加载权重。此方法用于创建时设置了 save_checkpoints=True 且需要使用不同的优化器或学习率调度器进行重新训练或微调的模型。但是，它也可以用于加载权重进行推理。
要恢复中断的训练，请考虑使用 load_from_checkpoint()，它也会重新加载训练器、优化器和学习率调度器的状态。
对于手动保存的模型，请考虑改用 load() 或 load_weights()。
注意：此方法需要能够访问 darts 模型检查点 (.pt 文件) 才能加载编码器并对模型参数执行健全性检查。

参数

model_name (Optional[str, None]) – 模型名称，用于检索检查点文件夹的名称。默认值：self.model_name。
work_dir (Optional[str, None]) – 工作目录（包含检查点文件夹）。默认为当前工作目录。
file_name (Optional[str, None]) – 检查点文件的名称。如果未指定，则使用最新的一个。
best (bool) – 如果设置，将检索最佳模型（根据验证损失）而不是最新的模型。仅当给定 file_name 时忽略。默认值：True。
strict (bool) –
如果设置，将严格执行 state_dict 中的键与此模块 state_dict() 返回的键匹配。默认值：True。有关更多信息，请阅读官方文档。

load_encoders (bool) – 如果设置，将从模型加载编码器，以启用直接调用 fit() 或 predict()。默认值：True。
skip_checks (bool) – 如果设置，将禁用加载编码器和对模型参数的健全性检查（不推荐）。不能与 load_encoders=True 一起使用。默认值：False。
**kwargs –
PyTorch 的 load() 方法的附加关键字参数，例如 map_location 用于将模型加载到与保存模型时不同的设备上。更多信息请参阅官方文档。








lr_find(series, past_covariates=None, future_covariates=None, val_series=None, val_past_covariates=None, val_future_covariates=None, sample_weight=None, val_sample_weight=None, trainer=None, verbose=None, epochs=0, max_samples_per_ts=None, dataloader_kwargs=None, min_lr=1e-08, max_lr=1, num_training=100, mode='exponential', early_stop_threshold=4.0)¶
PyTorch Lightning 的 Tuner.lr_find() 的一个包装器。执行一个好的初始学习率范围测试，以减少选择一个好的起始学习率时的猜测。有关 PyTorch Lightning Tuner 的更多信息，请查看此链接。如果调优器未给出令人满意的结果，建议增加 epochs 的数量。考虑使用建议的学习率创建一个新的模型对象，例如使用模型创建参数 optimizer_cls、optimizer_kwargs、lr_scheduler_cls 和 lr_scheduler_kwargs。
使用 RNNModel 的示例

import torch
from darts.datasets import AirPassengersDataset
from darts.models import NBEATSModel

series = AirPassengersDataset().load()
train, val = series[:-18], series[-18:]
model = NBEATSModel(input_chunk_length=12, output_chunk_length=6, random_state=42)
# run the learning rate tuner
results = model.lr_find(series=train, val_series=val)
# plot the results
results.plot(suggest=True, show=True)
# create a new model with the suggested learning rate
model = NBEATSModel(
    input_chunk_length=12,
    output_chunk_length=6,
    random_state=42,
    optimizer_cls=torch.optim.Adam,
    optimizer_kwargs={"lr": results.suggestion()}
)




参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用作目标（即模型将训练预测的内容）的一个或多个序列
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定过去观测协变量的一个或多个序列
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，指定未来已知协变量的一个或多个序列
val_series (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，一个或多个验证目标时间序列，将在训练过程中用于计算验证损失并跟踪性能最佳的模型。
val_past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，与验证序列对应的过去协变量（必须与 covariates 匹配）
val_future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，与验证序列对应的未来协变量（必须与 covariates 匹配）
sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于目标 series 标签的样本权重。它们按观测值、按标签（output_chunk_length 中的每个步骤）和按分量应用。如果是一个时间序列或时间序列序列，则使用这些权重。如果权重时间序列只有一个分量/列，则权重将全局应用于 series 中的所有分量。否则，对于分量特定的权重，分量数量必须与 series 的分量数量匹配。如果是一个字符串，则使用内置权重函数生成权重。可用选项为 “linear”（线性）或 “exponential”（指数）衰减——时间越远，权重越低。权重是根据 series 中最长序列的长度全局计算的。然后对于每个序列，从全局权重的末尾提取权重。这为所有序列提供了共同的时间权重。
val_sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 与 sample_weight 相同，但用于评估数据集。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行训练。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
epochs (int) – 如果指定，模型将训练额外的 epochs 个周期，无论模型构造函数中提供了多少 n_epochs。
max_samples_per_ts (Optional[int, None]) – 可选地，每个时间序列使用的最大样本数。模型通过构建 (输入, 输出) 示例切片以监督方式进行训练。对于长时间序列，这可能导致训练样本数量不必要地庞大。此参数限制每个时间序列的训练样本数上限（仅取每个序列的最新样本）。留空（设置为 None）则不应用任何上限。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选参数，用于创建训练和验证数据集的 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改这些参数时应小心，以避免意外行为。

min_lr (float) – 要探索的最小学习率
max_lr (float) – 要探索的最大学习率
num_training (int) – 要测试的学习率数量
mode (str) – 在每个批次后更新学习率的搜索策略：‘exponential’：指数增加学习率。‘linear’：线性增加学习率。
early_stop_threshold (float) – 停止搜索的阈值。如果在任何时候损失大于 early_stop_threshold*best_loss，则停止搜索。要禁用，请设置为 None


返回
Lightning 的 _LRFinder 对象，包含学习率扫描的结果。

返回类型
lr_finder






property min_train_samples: int¶
模型训练所需的最小样本数。

返回类型
int






property model_created: bool¶

返回类型
bool






property model_params: dict¶

返回类型
字典






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

返回类型
int






property output_chunk_shift: int¶
输出/预测开始于输入结束之后的时间步数。

返回类型
int






predict(n, series=None, past_covariates=None, future_covariates=None, trainer=None, batch_size=None, verbose=None, n_jobs=1, roll_size=None, num_samples=1, dataloader_kwargs=None, mc_dropout=False, predict_likelihood_parameters=False, show_warnings=True)¶
预测训练序列或指定的 series 结束后的 n 个时间步。
预测使用 PyTorch Lightning Trainer 进行。它使用预设和 pl_trainer_kwargs 在模型创建时使用的默认 Trainer 对象。您也可以使用带有可选参数 trainer 的自定义 Trainer。有关 PyTorch Lightning Trainer 的更多信息，请查看 此链接。
下面记录了所有可能的参数，但并非所有模型都支持所有参数。例如，所有 PastCovariatesTorchModel 都只支持 past_covariates 而不支持 future_covariates。如果您尝试使用错误的协变量参数调用模型的 predict() 方法，Darts 会报错。
如果提供的协变量没有足够的时间跨度，Darts 也会报错。一般来说，并非所有模型都需要相同的协变量时间跨度。


依赖过去协变量的模型需要知道 past_covariates 的最后一个 input_chunk_length
点在预测时已知。对于预测范围值 n > output_chunk_length，这些模型
还需要知道至少接下来的 n - output_chunk_length 未来值。



依赖未来协变量的模型需要知道接下来的 n 值。
此外（对于 DualCovariatesTorchModel 和 MixedCovariatesTorchModel），它们也
需要这些未来协变量的“历史”值（在过去 input_chunk_length 的范围内）。



在处理协变量时，Darts 将尝试使用目标和协变量的时间轴来确定正确的时间切片。因此，协变量可以比所需的更长；只要时间轴正确，Darts 就会正确处理它们。如果其时间跨度不足，它也会报错。

参数

n (int) – 训练时间序列结束后需要生成预测的时间步数
series (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，一个序列或序列列表，代表要预测其未来的目标序列的历史。如果指定，该方法返回这些序列的预测。否则，该方法返回（单个）训练序列的预测。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，作为模型输入所需的过去观测协变量序列。它们的维度必须与训练时使用的协变量匹配。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选地，作为模型输入所需的未来已知协变量序列。它们的维度必须与训练时使用的协变量匹配。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
batch_size (Optional[int, None]) – 预测期间的批次大小。默认为模型的训练 batch_size 值。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
n_jobs (int) – 并行运行的作业数量。-1 表示使用所有处理器。默认为 1。
roll_size (Optional[int, None]) – 对于自消耗预测，即 n > output_chunk_length，决定了在每次将预测目标（以及可选的未来协变量）反馈到模型时，模型的多少输出会被反馈。如果未提供此参数，它将默认为 output_chunk_length。
num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选地，一个用于为推理/预测数据集创建 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改它们时应谨慎，以避免意外行为。

mc_dropout (bool) – 可选地，为基于神经网络的模型预测启用蒙特卡洛 dropout。这可以通过指定学习模型的隐式先验来实现贝叶斯近似。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
show_warnings (bool) – 可选地，控制是否显示警告。并非对所有模型都有效。


返回
一个或多个包含 series 预测值的时间序列，或者如果未指定 series 且模型在单个序列上训练，则为训练序列的预测值。

返回类型
Union[TimeSeries, Sequence[TimeSeries]]






predict_from_dataset(n, input_series_dataset, trainer=None, batch_size=None, verbose=None, n_jobs=1, roll_size=None, num_samples=1, dataloader_kwargs=None, mc_dropout=False, predict_likelihood_parameters=False)¶
此方法允许使用特定的 darts.utils.data.InferenceDataset 实例进行预测。这些数据集实现了 PyTorch Dataset，并指定了目标和协变量如何用于推理。在大多数情况下，您会更倾向于调用 predict()，它将为您创建一个合适的 InferenceDataset。
预测使用 PyTorch Lightning Trainer 进行。它使用预设和 pl_trainer_kwargs 在模型创建时使用的默认 Trainer 对象。您也可以使用带有可选参数 trainer 的自定义 Trainer。有关 PyTorch Lightning Trainer 的更多信息，请查看 此链接。

参数

n (int) – 训练时间序列结束后需要生成预测的时间步数
input_series_dataset (InferenceDataset) – 可选地，一个序列或序列列表，代表要预测其未来的目标序列的历史。如果指定，该方法返回这些序列的预测。否则，该方法返回（单个）训练序列的预测。
trainer (Optional[Trainer, None]) – 可选地，一个自定义的 PyTorch-Lightning Trainer 对象用于执行预测。使用自定义的 trainer 将覆盖 Darts 的默认训练器。
batch_size (Optional[int, None]) – 预测期间的批次大小。默认为模型的 batch_size 值。
verbose (Optional[bool, None]) – 是否打印进度。如果在 pl_trainer_kwargs 中存在 ProgressBar 回调函数，则忽略此参数。
n_jobs (int) – 并行运行的作业数量。-1 表示使用所有处理器。默认为 1。
roll_size (Optional[int, None]) – 对于自消耗预测，即 n > output_chunk_length，决定了在每次将预测目标（以及可选的未来协变量）反馈到模型时，模型的多少输出会被反馈。如果未提供此参数，它将默认为 output_chunk_length。
num_samples (int) – 从概率模型中采样预测的次数。对于确定性模型，必须为 1。
dataloader_kwargs (Optional[dict[str, Any], None]) –
可选地，一个用于为推理/预测数据集创建 PyTorch DataLoader 实例的关键字参数字典。有关 DataLoader 的更多信息，请查看 此链接。默认情况下，Darts 配置参数（“batch_size”, “shuffle”, “drop_last”, “collate_fn”, “pin_memory”）以实现无缝预测。更改它们时应谨慎，以避免意外行为。

mc_dropout (bool) – 可选地，为基于神经网络的模型预测启用蒙特卡洛 dropout。这可以通过指定学习模型的隐式先验来实现贝叶斯近似。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 和 n<=output_chunk_length 的概率模型。默认值：False


返回
返回一个或多个时间序列的预测值。

返回类型
Sequence[TimeSeries]






reset_model()¶
重置模型对象并移除所有存储的数据 - 模型、检查点、日志记录器和训练历史。




residuals(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, metric=<function err>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None, values_only=False)¶
计算模型对（可能多个）series 的历史预测所产生的残差。
此函数计算来自 series 的实际观测值与通过在 series 上训练模型（或使用预训练模型并设置 retrain=False）获得的拟合值之间的差异（或 Darts 的“每时间步”指标之一）。并非所有模型都支持拟合值，因此我们使用历史预测作为它们的近似值。
此方法按顺序执行

使用预先计算的 historical_forecasts 或为每个序列计算历史预测（更多详细信息请参见 historical_forecasts()）。如何生成历史预测可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 来配置。
使用“每时间步” metric 指标计算历史预测与 series 之间的回测（针对每个分量/列和时间步）（更多详细信息请参见 backtest()）。默认情况下，使用残差 err() (误差) 作为 metric。
创建并返回带有历史预测时间索引和每个分量/时间步指标值的 TimeSeries（或者仅返回一个 np.ndarray 数组，如果设置了 values_only=True）。

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

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于依次训练（如果 retrain 不为 False）和计算历史预测的（序列）目标时间序列。
past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）过去观测协变量时间序列。仅当模型支持过去协变量时适用。
future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，为 series 中的每个输入时间序列提供的（序列）未来已知协变量时间序列。仅当模型支持未来协变量时适用。
historical_forecasts (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]], None]) – 可选参数，要评估的（或序列/序列的序列）历史预测时间序列。对应于 historical_forecasts() 的输出。必须传递与生成历史预测时使用的相同的 series 和 last_points_only 值。如果提供，将跳过历史预测，并忽略除 series, last_points_only, metric 和 reduction 之外的所有参数。
forecast_horizon (int) – 预测的预测期。
num_samples (int) – 从概率模型中采样预测的次数。仅对概率模型使用大于 1 的值。
train_length (Optional[int, None]) – 可选参数，对每个构建的训练集使用固定的长度/时间步数（滚动窗口模式）。仅当 retrain 不为 False 时有效。默认值为 None，此时使用直到预测时间的所有时间步（扩展窗口模式）。如果大于可用时间步数，则使用扩展模式。需要至少为 min_train_series_length。
start (Union[Timestamp, float, int, None]) –
可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果是 float，则表示应位于第一个预测点之前的时间序列的比例。如果是 int，则对于具有 pd.DatetimeIndex 的 series，它是第一个预测点的索引位置；对于具有 pd.RangeIndex 的 series，它是索引值。后者可以通过 start_format=”position” 更改为索引位置。如果是 pandas.Timestamp，则是第一个预测点的时间戳。如果为 None，第一个预测点将自动设置为

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

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


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

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

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



start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，则 start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'。
stride (int) – 两个连续预测之间的时间步数。
retrain (Union[bool, int, Callable[…, bool]]) –
是否以及/或在何种条件下在预测前重新训练模型。此参数支持 3 种不同的类型：bool、（正）int 和 Callable（返回 bool）。对于 bool：每一步都重新训练模型（True），或从不重新训练模型（False）。对于 int：模型每 retrain 次迭代重新训练一次。对于 Callable：只要 Callable 返回 True，就重新训练模型。Callable 必须具有以下位置参数

counter (int): 当前 retrain 迭代次数
pred_time (pd.Timestamp 或 int): 预测时间的时间戳（训练序列的结束时间）
train_series (TimeSeries): 直到 pred_time 的训练序列
past_covariates (TimeSeries): 直到 pred_time 的过去协变量序列
future_covariates (TimeSeries): 直到 min(pred_time + series.freq * forecast_horizon, series.end_time()) 的未来协变量序列

注意：如果任何可选的 *_covariates 未传递给 historical_forecast，则会将 None 传递给相应的重新训练函数参数。注意：某些模型要求每次都重新训练，并且不支持 retrain=True 之外的任何值。注意：这也控制 data_transformers 的重新训练。

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

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

verbose (bool) – 是否打印进度。
show_warnings (bool) – 是否显示与历史预测优化或参数 start 和 train_length 相关的警告。
predict_likelihood_parameters (bool) – 如果设置为 True，模型将预测其 likelihood 的参数而不是目标。仅支持具有似然函数、num_samples = 1 且 n<=output_chunk_length 的概率模型。默认值：False。
enable_optimization (bool) – 在支持和可用时是否使用优化版本的 historical_forecasts。默认值：True。
data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –
可选参数，一个 BaseDataTransformer 或 Pipeline 字典，用于应用于相应的序列（可能的键：“series”, “past_covariates”, “future_covariates”）。如果提供，所有输入序列必须处于未转换空间。对于可拟合的转换器/管道

如果 retrain=True，则数据转换器在每个历史预测步骤重新拟合训练数据。
如果 retrain=False，则数据转换器在所有预测之前转换一次序列。

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

metric_kwargs (Optional[dict[str, Any], None]) – 传递给 metric() 的额外参数，例如用于并行的 ‘n_jobs’，用于缩放指标的 ‘m’ 等。仅当参数存在于相应的指标签名中时才会传递。忽略 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 计算。
values_only (bool) – 是否将残差作为 np.ndarray 返回。如果设置为 False，则将残差作为 TimeSeries 返回。


返回类型
Union[TimeSeries, list[TimeSeries], list[list[TimeSeries]]]

返回

TimeSeries – 单个 series 的残差 TimeSeries，以及使用 last_points_only=True 生成的 historical_forecasts。
List[TimeSeries] – 序列（列表）series 的残差 TimeSeries 列表，并设置了 last_points_only=True。残差列表的长度为 len(series)。
List[List[TimeSeries]] – 序列 series 的残差 TimeSeries 列表的列表，并设置了 last_points_only=False。外部残差列表的长度为 len(series)。内部列表包含所有可能的序列特定历史预测的残差。








save(path=None, clean=False)¶
在给定路径下保存模型。
在 path（模型对象）和 path.ckpt（检查点）下创建两个文件。
注意：使用自定义类保存模型时可能会出现 Pickle 错误。在这种情况下，请考虑使用 clean 标志从保存的模型中移除与训练相关的属性。
保存和加载 RNNModel 的示例

from darts.models import RNNModel

model = RNNModel(input_chunk_length=4)

model.save("my_model.pt")
model_loaded = RNNModel.load("my_model.pt")




参数

path (Optional[str, None]) – 用于保存模型当前状态的路径。请避免使用以“last-”或“best-”开头的路径，以避免与 Pytorch-Lightning 检查点冲突。如果未指定路径，模型将自动保存到 "{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.pt" 下。例如，"RNNModel_2020-01-01_12_00_00.pt"。
clean (bool) –
是否存储模型的清理版本。如果设置为 True，则训练序列和协变量将被移除。此外，还将移除所有与 Lightning Trainer 相关的参数（在模型创建时通过 pl_trainer_kwargs 传递）。
注意：加载使用 clean=True 存储的模型后，必须将 series 传递给 ‘predict()’、‘historical_forecasts()’ 和其他预测方法。



返回类型
None






property supports_future_covariates: bool¶
模型是否支持未来协变量

返回类型
bool






property supports_likelihood_parameter_prediction: bool¶
模型实例是否支持直接预测似然参数

返回类型
bool






property supports_multivariate: bool¶
模型是否考虑时间序列中的多个变量。

返回类型
bool






property supports_optimized_historical_forecasts: bool¶
模型是否支持优化后的历史预测

返回类型
bool






property supports_past_covariates: bool¶
模型是否支持过去协变量

返回类型
bool






property supports_probabilistic_prediction: bool¶
检查具有此配置的预测模型是否支持概率预测。
默认返回 False。需要由支持概率预测的模型覆盖。

返回类型
bool






property supports_sample_weight: bool¶
模型是否支持训练时的样本权重。

返回类型
bool






property supports_static_covariates: bool¶
模型是否支持静态协变量

返回类型
bool






property supports_transferable_series_prediction: bool¶
模型是否支持对任何输入 series 进行预测。

返回类型
bool






to_cpu()¶
更新 PyTorch Lightning Trainer 参数，以便下次调用 :fun:`fit()` 或 predict() 时将模型移动到 CPU。




to_onnx(path=None, **kwargs)¶
将模型导出为 ONNX 格式以进行优化推理，封装了 PyTorch Lightning 的 torch.onnx.export() 方法（官方文档）。
注意：需要安装 onnx 库（可选依赖）。
导出 DLinearModel 的示例
from darts.datasets import AirPassengersDataset
from darts.models import DLinearModel

series = AirPassengersDataset().load()
model = DLinearModel(input_chunk_length=4, output_chunk_length=1)
model.fit(series, epochs=1)
model.to_onnx("my_model.onnx")



参数

path (Optional[str, None]) – 保存模型当前状态的路径。如果未指定路径，模型将自动保存到 "{ModelClass}_{YYYY-mm-dd_HH_MM_SS}.onnx" 下。
**kwargs –
PyTorch 的 load() 方法的额外关键字参数（除了参数 file_path、input_sample、input_name）。更多信息，请阅读 官方文档。








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




property uses_future_covariates: bool¶
模型在拟合后是否使用未来协变量。

返回类型
bool






property uses_past_covariates: bool¶
模型在拟合后是否使用过去协变量。

返回类型
bool






property uses_static_covariates: bool¶
模型在拟合后是否使用静态协变量。

返回类型
bool


              
              
              
 
       上一页
 <无标题>
 
    下一页
 卡尔曼滤波预测器