时态融合 Transformer (TFT)

class darts.models.forecasting.tft_model.TFTModel(input_chunk_length, output_chunk_length, output_chunk_shift=0, hidden_size=16, lstm_layers=1, num_attention_heads=4, full_attention=False, feed_forward='GatedResidualNetwork', dropout=0.1, hidden_continuous_size=8, categorical_embedding_sizes=None, add_relative_index=False, loss_fn=None, likelihood=None, norm_type='LayerNorm', use_static_covariates=True, **kwargs)

基类: MixedCovariatesTorchModel

用于可解释时间序列预测的时态融合 Transformer (TFT)。

这是 [1] 中概述的 TFT 架构实现。

内部子模型采用自 pytorch-forecasting 的 TemporalFusionTransformer 实现。

该模型支持过去协变量（在预测时间之前 input_chunk_length 点已知）、未来协变量（在预测时间之后 output_chunk_length 点已知）、静态协变量以及概率预测。

TFT 在强制性的 future_covariates 的未来输入上应用多头注意力查询。通过 add_encoders 指定未来编码器（阅读下方内容）可以自动生成未来协变量，并允许在使用模型时无需向 fit() 和 predict() 传递任何 future_covariates。

默认情况下，该模型使用 QuantileRegression 似然模型，这意味着其预测是概率性的；建议使用 num_samples >> 1 调用 :func`predict()` 以获得有意义的结果。

参数

• input_chunk_length (int) – 作为模型输入（每块）的过去时间步长数。适用于目标序列以及过去和/或未来协变量（如果模型支持）。也称为：编码器长度。

• output_chunk_length (int) – 内部模型一次（每块）预测的时间步长数。此外，从未来协变量用作模型输入（如果模型支持未来协变量）的未来值数量。这与在 predict() 中使用的预测范围 n 不同，后者是使用一次性预测或自回归预测生成的期望预测点数。设置 n <= output_chunk_length 可防止自回归。当协变量没有充分延伸到未来时，或者为了禁止模型使用过去和/或未来协变量的未来值进行预测时（取决于模型的协变量支持），这很有用。也称为：解码器长度。

• output_chunk_shift (int) – 可选，输出块的起始点相对于输入块结束点向前移动的步数。这将在输入和输出之间产生一个间隙。如果模型支持 future_covariates，则从移位的输出块中提取未来值。预测将从目标 series 结束点之后的 output_chunk_shift 步开始。如果设置了 output_chunk_shift，则模型无法生成自回归预测（n > output_chunk_length）。

• hidden_size (Union[int, list[int]]) – TFT 的隐藏状态大小。它是主要超参数，在内部 TFT 架构中通用。

• lstm_layers (int) – 用于长短期记忆 (LSTM) 编码器和解码器的层数（1 是一个很好的默认值）。

• num_attention_heads (int) – 注意力头数（4 是一个很好的默认值）。

• full_attention (bool) – 如果为 False，则仅关注解码器中先前的时间步。如果为 True，则关注先前、当前和未来的时间步。默认为 False。

• feed_forward (str) – 前馈网络是带有激活函数的全连接层。可以是 glu 变体的前馈网络 (FFN) [2] 之一。glu 变体的前馈网络是一系列旨在更好地与基于 Transformer 的模型配合使用的 FFN。默认为 "GatedResidualNetwork"。[“GLU”, “Bilinear”, “ReGLU”, “GEGLU”, “SwiGLU”, “ReLU”, “GELU”] 或 TFT 原始前馈网络 [“GatedResidualNetwork”]。

• dropout (float) – 受 dropout 影响的神经元比例。这与推理时的 Monte Carlo dropout 兼容，用于模型不确定性估计（预测时通过设置 mc_dropout=True 启用）。

• hidden_continuous_size (int) – 处理连续变量的默认隐藏层大小。

• categorical_embedding_sizes (Optional[dict[str, Union[int, tuple[int, int]]], None]) – 用于为分类静态协变量构建嵌入的字典。键是分类静态协变量的列名。每个值可以是单个整数或整数元组。对于单个整数，请给出相应变量的唯一类别数 (n)。例如 {"some_column": 64}。嵌入大小将由 min(round(1.6 * n**0.56), 100) 自动确定。对于整数元组，请给出 (唯一类别数，嵌入大小)。例如 {"some_column": (64, 8)}。请注意，TorchForecastingModels 只支持数字数据。请考虑使用 darts.dataprocessing.transformers.static_covariates_transformer.StaticCovariatesTransformer 对数据进行转换/编码。

• add_relative_index (bool) – 是否向未来协变量添加位置值。默认为 False。这允许在使用 TFTModel 时无需向 fit() 和 train() 传递 future_covariates。它为输入块和输出块中每个步骤的位置（相对于预测点）赋予一个值。这些值使用 input_chunk_length 进行归一化。

• loss_fn (nn.Module) – 用于训练的 PyTorch 损失函数。默认情况下，TFT 模型是概率性的，并使用 likelihood（QuantileRegression）。要使模型确定性，可以将 ` likelihood` 设置为 None 并提供 loss_fn 参数。

• likelihood (Optional[TorchLikelihood, None]) – 用于概率预测的似然模型。默认情况下，TFT 使用 QuantileRegression 似然模型。

• norm_type (str | nn.Module) – 使用的 LayerNorm 变体类型。默认值：LayerNorm。可用选项包括 [“LayerNorm”, “RMSNorm”, “LayerNormNoBias”]，或者提供自定义 nn.Module。

• use_static_covariates (bool) – 如果传递给 fit() 的输入 series 包含静态协变量，模型是否应该使用静态协变量信息。如果为 True 且在拟合时静态协变量可用，则会强制所有目标 series 在 fit() 和 predict() 中具有相同的静态协变量维度。

• **kwargs – 用于初始化 pytorch_lightning.Module、pytorch_lightning.Trainer 和 Darts 的 TorchForecastingModel 的可选参数。

• torch_metrics – 用于评估的 torch metric 或 MetricCollection。可用的指标的完整列表可在 https://torchmetrics.readthedocs.io/en/latest/ 找到。默认值：None。

• optimizer_cls – 将使用的 PyTorch 优化器类。默认值：torch.optim.Adam。

• optimizer_kwargs – 可选，用于 PyTorch 优化器的一些关键字参数（例如，{'lr': 1e-3} 用于指定学习率）。否则，将使用选定的 optimizer_cls 的默认值。默认值：None。

• lr_scheduler_cls – 可选，将使用的 PyTorch 学习率调度器类。指定 None 对应于使用固定学习率。默认值：None。

• lr_scheduler_kwargs – 可选，用于 PyTorch 学习率调度器的一些关键字参数。默认值：None。

• use_reversible_instance_norm – 是否使用可逆实例归一化 RINorm 来应对分布偏移，如 [3] 所示。它仅应用于目标序列的特征，而不应用于协变量。

• batch_size – 每次训练过程中使用的时间序列（输入和输出序列）数量。默认值：32。

• n_epochs – 训练模型的 Epoch 数。默认值：100。

• model_name – 模型名称。用于创建检查点和保存 tensorboard 数据。如果未指定，则默认为字符串 "YYYY-mm-dd_HH_MM_SS_torch_model_run_PID"，其中名称的初始部分按本地日期和时间格式化，而 PID 是进程 ID（防止不同进程同时生成的模型共享相同的 model_name）。例如，"2021-06-14_09_53_32_torch_model_run_44607"。

• work_dir – 工作目录路径，用于保存检查点和 Tensorboard 摘要。默认值：当前工作目录。

• log_tensorboard – 如果设置，则使用 Tensorboard 记录不同的参数。日志将位于："{work_dir}/darts_logs/{model_name}/logs/"。默认值：False。

• nr_epochs_val_period – 在评估验证损失之前等待的 Epoch 数（如果将验证 TimeSeries 传递给 fit() 方法）。默认值：1。

• force_reset – 如果设置为 True，则任何先前存在的同名模型将被重置（所有检查点都将被丢弃）。默认值：False。

• save_checkpoints – 是否自动保存未训练的模型和训练检查点。要从检查点加载模型，请调用 MyModelClass.load_from_checkpoint()，其中 MyModelClass 是使用的 TorchForecastingModel 类（例如 TFTModel、NBEATSModel 等）。如果设置为 False，仍然可以使用 save() 手动保存模型，并使用 load() 加载。

• add_encoders –

  可以使用 add_encoders 自动生成大量过去和未来协变量。这可以通过添加多个预定义的索引编码器和/或用作索引编码器的自定义用户函数来完成。此外，可以添加一个转换器，例如 Darts 的 Scaler 来转换生成的协变量。所有这些都在一个框架下完成，只需要在模型创建时指定。阅读 SequentialEncoder 以了解更多关于 add_encoders 的信息。默认值：None。下面展示了 add_encoders 部分功能的示例

  def encode_year(idx):
      return (idx.year - 1950) / 50
  
  add_encoders={
      'cyclic': {'future': ['month']},
      'datetime_attribute': {'future': ['hour', 'dayofweek']},
      'position': {'past': ['relative'], 'future': ['relative']},
      'custom': {'past': [encode_year]},
      'transformer': Scaler(),
      'tz': 'CET'
  }
  

• random_state – 控制权重初始化的随机性。请参阅此 链接 了解更多详情。默认值：None。

• pl_trainer_kwargs –

  默认情况下，TorchForecastingModel 创建一个带有几个有用预设的 PyTorch Lightning Trainer，用于执行训练、验证和预测过程。这些预设包括自动检查点、tensorboard 日志记录、设置 torch 设备等。使用 pl_trainer_kwargs，您可以添加额外的 kwargs 来实例化 PyTorch Lightning trainer 对象。请查看 PL Trainer 文档 以了解更多关于支持的 kwargs 的信息。默认值：None。使用 GPU(s) 运行也是可能的，通过在 pl_trainer_kwargs 字典中指定键 "accelerator", "devices", and "auto_select_gpus"。以下是在 pl_trainer_kwargs dict 中设置设备的一些示例

  • {"accelerator": "cpu"} 用于 CPU，

  • {"accelerator": "gpu", "devices": [i]} 只使用 GPU i（i 必须是整数），

  • {"accelerator": "gpu", "devices": -1, "auto_select_gpus": True} 使用所有可用的 GPU。

  更多信息，请参阅此处：https://pytorch-lightning.readthedocs.io/en/stable/common/trainer.html#trainer-flags 和 https://pytorch-lightning.readthedocs.io/en/stable/accelerators/gpu_basic.html#train-on-multiple-gpus

  参数 "callbacks" 允许您将自定义或 PyTorch-Lightning 内置的回调添加到 Darts 的 TorchForecastingModel 中。下面是一个将 EarlyStopping 添加到训练过程的示例。如果验证损失 val_loss 未按规定改善，模型将提前停止训练。有关回调的更多信息，请访问：PyTorch Lightning Callbacks

  from pytorch_lightning.callbacks.early_stopping import EarlyStopping
  
  # stop training when validation loss does not decrease more than 0.05 (`min_delta`) over
  # a period of 5 epochs (`patience`)
  my_stopper = EarlyStopping(
      monitor="val_loss",
      patience=5,
      min_delta=0.05,
      mode='min',
  )
  
  pl_trainer_kwargs={"callbacks": [my_stopper]}
  

  请注意，您还可以在 fit() 和 predict() 中使用可选参数 trainer 使用自定义的 PyTorch Lightning Trainer 进行训练和预测。

• show_warnings – 是否显示 PyTorch Lightning 引起的警告。有助于检测您的预测用例的潜在问题。默认值：False。

参考文献

1

https://arxiv.org/pdf/1912.09363.pdf

2

Shazeer, Noam, “GLU Variants Improve Transformer”, 2020. arVix https://arxiv.org/abs/2002.05202。

3

T. Kim et al. “Reversible Instance Normalization for Accurate Time-Series Forecasting against Distribution Shift”, https://openreview.net/forum?id=cGDAkQo1C0p

示例

>>> from darts.datasets import WeatherDataset
>>> from darts.models import TFTModel
>>> series = WeatherDataset().load()
>>> # predicting atmospheric pressure
>>> target = series['p (mbar)'][:100]
>>> # optionally, past observed rainfall (pretending to be unknown beyond index 100)
>>> past_cov = series['rain (mm)'][:100]
>>> # future temperatures (pretending this component is a forecast)
>>> future_cov = series['T (degC)'][:106]
>>> # by default, TFTModel is trained using a `QuantileRegression` making it a probabilistic forecasting model
>>> model = TFTModel(
>>>     input_chunk_length=6,
>>>     output_chunk_length=6,
>>>     n_epochs=5,
>>> )
>>> # future_covariates are mandatory for `TFTModel`
>>> model.fit(target, past_covariates=past_cov, future_covariates=future_cov)
>>> # TFTModel is probabilistic by definition; using `num_samples >> 1` to generate probabilistic forecasts
>>> pred = model.predict(6, num_samples=100)
>>> # shape : (forecast horizon, components, num_samples)
>>> pred.all_values().shape
(6, 1, 100)
>>> # showing the first 3 samples for each timestamp
>>> pred.all_values()[:,:,:3]
array([[[-0.06414202, -0.7188093 ,  0.52541292]],
       [[ 0.02928407, -0.40867163,  1.19650033]],
       [[ 0.77252372, -0.50859694,  0.360166  ]],
       [[ 0.9586113 ,  1.24147138, -0.01625545]],
       [[ 1.06863863,  0.2987822 , -0.69213369]],
       [[-0.83076568, -0.25780816, -0.28318784]]])

注意

TFT 示例 notebook 介绍了可用于提高预测质量（相较于此简单使用示例）的技术。

属性

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

epochs_trained
input_chunk_length
model_created
model_params

方法

backtest(series[, past_covariates, ...])	计算模型对（可能多个）series 上的历史预测产生的误差值。
fit(series[, past_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 or int): 预测时间（训练序列的结束点）的时间戳

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

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

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

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

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

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

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

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

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

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

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

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

• data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –

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

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

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

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

  • metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – 传递给 metric() 的额外参数，例如用于并行化的 ‘n_jobs’、用于减少分量维度指标的 ‘component_reduction’、用于 scaled metrics 的季节性参数 ‘m’ 等。将参数分别传递给每个指标，并且仅在相应指标签名中存在时传递。Scaled metrics（例如 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 并使用 backtest reduction，返回单个回测分数。

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

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

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

  • 包括 series_reduction 的多个单变量/多变量序列，并且至少有一个 component_reduction=None 或 time_reduction=None（用于“按时间步长指标”）。

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

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

• 属性 considers_static_covariates: bool

• 布尔值

属性 epochs_trained: int

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

返回

整型

属性 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。

注意

最大目标滞后（第二个值）不能为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, val_series=None, val_past_covariates=None, val_future_covariates=None, trainer=None, verbose=None, epochs=0, max_samples_per_ts=None, dataloader_kwargs=None, sample_weight=None, val_sample_weight=None)

在一个或多个序列上拟合/训练模型。

此方法封装了 fit_from_dataset()，为该模型构建了默认训练数据集。如果您需要更精细地控制如何对时间序列进行切片以进行训练，请考虑调用 fit_from_dataset() 并使用自定义的 darts.utils.data.TrainingDataset。

训练是使用 PyTorch Lightning Trainer 执行的。它使用预设和模型创建时使用的 pl_trainer_kwargs 中的默认 Trainer 对象。您也可以使用可选参数 trainer 指定自定义 Trainer。有关 PyTorch Lightning Trainers 的更多信息，请查看 此链接。

此函数可以调用多次以进行额外的训练。如果指定了 epochs，模型将额外训练 epochs 个周期，无论模型构造函数中提供了什么 n_epochs 值。

下面记录了所有可能的参数，但并非所有模型都支持所有参数。例如，所有的 PastCovariatesTorchModel 只支持 past_covariates，不支持 future_covariates。如果您尝试使用错误的协变量参数拟合模型，Darts 将会报错。

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

参数

• 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 匹配）

• val_sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 与 sample_weight 相同，但用于评估数据集。

• trainer (Optional[Trainer, None]) – 可选参数，用于执行训练的自定义 PyTorch-Lightning Trainer 对象。使用自定义 trainer 将覆盖 Darts 的默认 trainer。

• 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”）以实现无缝预测。更改这些参数时应谨慎，以避免意外行为。

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 可选参数，应用于目标 series 标签的样本权重。这些权重应用于每个观测值、每个标签（output_chunk_length 中的每一步）和每个分量。如果是一个时间序列或时间序列序列，则使用这些权重。如果权重时间序列只有一个分量/列，则这些权重会全局应用于 series 中的所有分量。否则，对于特定分量的权重，分量数量必须与 series 的分量数量匹配。如果是字符串，则使用内置权重函数生成权重。可用选项为 “linear”（线性）或 “exponential”（指数）衰减 - 过去越远，权重越低。根据 series 中最长的时间序列的长度全局计算权重。然后对于每个时间序列，从全局权重的末尾提取权重。这使得所有时间序列具有共同的时间权重。

• val_sample_weight – 与 sample_weight 相同，但用于评估数据集。

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

拟合后的模型。

返回

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 个周期，无论模型构造函数中提供了什么 n_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”）以实现无缝预测。更改这些参数时应谨慎，以避免意外行为。

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

拟合后的模型。

返回

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]) – 可选参数，拟合模型时使用的未来已知协变量的时间序列或时间序列序列。

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

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

返回

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]) – 可选参数，打算用于预测的未来已知协变量时间序列。其维度必须与用于训练的协变量的维度匹配。

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

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

返回

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]) – 可选参数，打算用于预测的未来已知协变量时间序列。其维度必须与用于训练的协变量的维度匹配。

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

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

返回

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

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

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

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

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

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

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

参数

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

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

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

• past_covariates (Optional[TimeSeries, None]) – 可选参数，一个过去观测协变量时间序列。仅当模型支持过去协变量时适用。

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

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

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

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

  仅在扩展窗口模式中使用。可选参数，计算预测的第一个时间点。此参数支持：float、int、pandas.Timestamp 和 None。如果是 float 类型，它表示在第一个预测点之前应占用的时间序列比例。如果是 int 类型，它表示对于具有 pd.DatetimeIndex 的 series 的第一个预测点索引位置，或者对于具有 pd.RangeIndex 的 series 的索引值。

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

  • 后者可以使用 start_format=”position” 更改为索引位置。如果是 pandas.Timestamp，它表示第一个预测点的时间戳。如果为 None，则第一个预测点将自动设置为第一个可训练点（如果 retrain 为 True 或 int，给定 train_lengthretrain 是可调用对象 (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) – 两次连续预测之间的时间步长数。

• 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，则使用与拟合值的比较。如果 model_class 没有 fitted_values 属性，则引发错误。

• metric (Callable[[TimeSeries, TimeSeries], float]) –

  一个度量函数，它返回两个 TimeSeries 之间的误差作为浮点值。必须是 Darts 的“随时间聚合”度量之一（参见 此处），或者是一个自定义度量，它以两个 TimeSeries 作为输入并返回误差

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

• verbose – 是否打印进度。

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

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

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

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

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

  • metric_kwargs (Union[dict[str, Any], list[dict[str, Any]], None]) – 传递给 metric() 的额外参数，例如用于并行化的 ‘n_jobs’、用于减少分量维度指标的 ‘component_reduction’、用于 scaled metrics 的季节性参数 ‘m’ 等。将参数分别传递给每个指标，并且仅在相应指标签名中存在时传递。Scaled metrics（例如 mase`, rmsse, …）的参数 ‘insample’ 被忽略，因为它在内部处理。

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

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

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

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

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

一个元组，包含使用最佳超参数创建的未训练的 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 or int): 预测时间（训练序列的结束点）的时间戳

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

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

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

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

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

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

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

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

• 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’、用于 scaled metrics 的季节性参数 ‘m’ 等。将参数分别传递给每个指标，并且仅在相应指标签名中存在时传递。Scaled metrics（例如 mase`, rmsse, …）的参数 ‘insample’ 被忽略，因为它在内部处理。

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

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

返回

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

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

• TimeSeries – 对于单个 series 且 last_points_only=True 时返回单个历史预测：它只包含所有历史预测中步长为 forecast_horizon 的预测点。

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

  • series 序列（列表）且 last_points_only=True 时：对于每个时间序列，它只包含所有历史预测中步长为 forecast_horizon 的预测点。

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

• List[List[TimeSeries]] – 对于 series 序列且 last_points_only=False 时返回的历史预测列表的列表。对于每个时间序列和历史预测，它包含整个范围 forecast_horizon。外部列表对应输入序列中提供的时间序列，内部列表包含每个时间序列的历史预测。

property input_chunk_length: int

返回

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

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，则会尝试恢复最佳检查点（如果 best 为 True）或最新检查点（如果 best 为 False）从‘{work_dir}/darts_logs/{model_name}/checkpoints/’。

将保存在 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 (Optional[str, None]) – 模型的名称，用于检索检查点文件夹的名称。

• work_dir (Optional[str, None]) – 工作目录（包含检查点文件夹）。默认为当前工作目录。

• file_name (Optional[str, None]) – 检查点文件的名称。如果未指定，则使用最新的一个。

• best (bool) – 如果设置，将检索最佳模型（根据验证损失）而不是最新模型。仅在给定 file_name 时忽略此参数。

• **kwargs –

  Additional kwargs for PyTorch Lightning’s LightningModule.load_from_checkpoint() method, such as map_location to load the model onto a different device than the one from which it was saved. For more information, read the official documentation.

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

相应的已训练 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() 方法的额外 kwargs，例如 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()，它也会重新加载 trainer、优化器和学习率调度器的状态。

对于手动保存的模型，请考虑使用 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() 方法的额外 kwargs，例如 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 的更多信息，请查看 此链接。如果 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 的默认 trainer。

• 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

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

包含 LR 扫描结果的 Lightning 的 _LRFinder 对象。

返回

lr_finder

property min_train_samples: int

训练模型的最小样本数。

返回

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

property model_created: bool

返回

整型

property model_params: dict

返回

字典

property output_chunk_length: int

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

返回

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

property output_chunk_shift: int

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

返回

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

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 执行。它使用预设中的默认 Trainer 对象以及模型创建时使用的 pl_trainer_kwargs。您还可以使用带有可选参数 trainer 的自定义 Trainer。有关 PyTorch Lightning Trainers 的更多信息，请查看此链接。

下面记录了所有可能的参数，但并非所有模型都支持所有参数。例如，所有 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 就会正确处理它们。如果它们的跨度不足，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 的默认 trainer。

• 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。这通过指定学习模型上的隐式先验来实现贝叶斯近似。

• data_transformers (Optional[dict[str, Union[BaseDataTransformer, Pipeline]], None]) –

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

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

包含 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 执行。它使用预设中的默认 Trainer 对象以及模型创建时使用的 pl_trainer_kwargs。您还可以使用带有可选参数 trainer 的自定义 Trainer。有关 PyTorch Lightning Trainers 的更多信息，请查看此链接。

参数

• n (int) – 在训练时间序列结束后要生成预测的时间步长数量

• input_series_dataset (InferenceDataset) – 可选参数，一个或一系列时间序列，表示要预测其未来的目标系列的历史。如果指定，该方法返回这些系列的预测结果。否则，该方法返回（单个）训练系列的预测结果。

• trainer (Optional[Trainer, None]) – 可选参数，用于执行预测的自定义 PyTorch-Lightning Trainer 对象。使用自定义的 trainer 将覆盖 Darts 的默认 trainer。

• 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 的参数而不是目标。仅支持具有 likelihood 的概率模型，且要求 num_samples = 1 和 n<=output_chunk_length。默认值：False

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

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

返回

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

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

• 创建并返回 TimeSeries（或使用 values_only=True 时仅返回 np.ndarray），其中包含历史预测的时间索引，以及按组件和时间步计算的指标值。

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

参数

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

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

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

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

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

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

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

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

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

  • 如果 retrain 为 False，或 retrain 是一个 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 or int): 预测时间（训练序列的结束点）的时间戳

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

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

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

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

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

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

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

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

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

  Darts 的“每时间步”指标之一（参见这里），或一个具有与 Darts 的“每时间步”指标相同签名的自定义指标，使用装饰器 multi_ts_support() 和 multi_ts_support()，并返回每个时间步的一个值。

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

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

• data_transformers (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’、用于 scaled metrics 的季节性参数 ‘m’ 等。将参数分别传递给每个指标，并且仅在相应指标签名中存在时传递。Scaled metrics（例如 mase`, rmsse, …）的参数 ‘insample’ 被忽略，因为它在内部处理。

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

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

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

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

返回

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

使用 last_points_only=True 生成的 historical_forecasts，返回单个回测分数。

• TimeSeries – 使用 last_points_only=True 生成的单个 series 和 historical_forecasts 的残差 TimeSeries。

• List[TimeSeries] – 使用 last_points_only=True 生成的 series 序列（列表）的残差 TimeSeries 列表。残差列表的长度为 len(series)。

• List[List[TimeSeries]] – 使用 last_points_only=False 生成的 series 序列的残差 TimeSeries 的列表的列表。外部残差列表的长度为 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() 和其他预测方法。

返回

无

property supports_future_covariates: bool

模型是否支持未来协变量。

返回

整型

property supports_likelihood_parameter_prediction: bool

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

返回

整型

property supports_multivariate: bool

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

返回

整型

property supports_optimized_historical_forecasts: bool

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

返回

整型

property supports_past_covariates: bool

模型是否支持过去协变量。

返回

整型

property supports_probabilistic_prediction: bool

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

默认情况下返回 False。需要由支持概率预测的模型进行覆盖。

返回

整型

property supports_sample_weight: bool

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

返回

整型

property supports_static_covariates: bool

模型是否支持静态协变量。

返回

整型

property supports_transferable_series_prediction: bool

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

返回

整型

to_cpu()

更新 PyTorch Lightning Trainer 参数，以便下次调用 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 的 torch.onnx.export() 方法的附加关键字参数（参数 file_path、input_sample、input_name 除外）。更多信息请阅读官方文档。

untrained_model()

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

property uses_future_covariates: bool

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

返回

整型

property uses_past_covariates: bool

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

返回

整型

property uses_static_covariates: bool

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

返回

整型

上一页

时间卷积网络

下一页

<无标题>