Transformer 模型¶
- class darts.models.forecasting.transformer_model.TransformerModel(input_chunk_length, output_chunk_length, output_chunk_shift=0, d_model=64, nhead=4, num_encoder_layers=3, num_decoder_layers=3, dim_feedforward=512, dropout=0.1, activation='relu', norm_type=None, custom_encoder=None, custom_decoder=None, **kwargs)[源代码]¶
基类:
PastCovariatesTorchModelTransformer 模型
Transformer 是 2017 年引入的先进深度学习模型。它是一种编码器-解码器架构，其核心特征是“多头注意力”机制，该机制能够捕捉输入向量内部和输出向量内部（“自注意力”）以及输入和输出向量之间的相互依赖关系（“编码器-解码器注意力”）。多头注意力机制高度并行化，这使得 Transformer 架构非常适合使用 GPU 进行训练。
这里实现的 Transformer 架构基于 [1]。
该模型支持过去协变量（在预测时间点之前已知 input_chunk_length 个点）。
- 参数
input_chunk_length (
int) – 作为模型输入（每块）的过去时间步长数量。应用于目标序列以及过去和/或未来协变量（如果模型支持）。output_chunk_length (
int) – 内部模型一次预测（每块）的时间步长数量。也是用作模型输入（如果模型支持未来协变量）的未来协变量未来值的数量。它与 predict() 中使用的预测范围 n 不同，预测范围 n 是使用一次性预测或自回归预测生成的所需预测点数量。设置 n <= output_chunk_length 可防止自回归。这在协变量不够远时非常有用，或者用于禁止模型使用过去和/或未来协变量的未来值进行预测（取决于模型的协变量支持）。output_chunk_shift (
int) – 可选，将输出块的起始点向未来偏移的步数（相对于输入块的末尾）。这将创建输入和输出之间的间隔。如果模型支持 future_covariates，则从偏移的输出块中提取未来值。预测将从目标 series 结束后的 output_chunk_shift 步开始。如果设置了 output_chunk_shift，模型将无法生成自回归预测（n > output_chunk_length）。d_model (
int) – Transformer 编码器/解码器输入中预期特征的数量 (默认=64)。nhead (
int) – 多头注意力机制中的头数量 (默认=4)。num_encoder_layers (
int) – 编码器中的编码器层数量 (默认=3)。num_decoder_layers (
int) – 解码器中的解码器层数量 (默认=3)。dim_feedforward (
int) – 前馈网络模型维度 (默认=512)。dropout (
float) – 受 Dropout 影响的神经元比例 (默认=0.1)。activation (
str) – 编码器/解码器中间层的激活函数 (默认='relu')。可以是 GLU 变体前馈网络 (FFN) [2] 中的一个。前馈网络是一个带有激活函数的全连接层。GLU 变体前馈网络是一系列旨在与基于 Transformer 的模型更好地配合的 FFN。[“GLU”, “Bilinear”, “ReGLU”, “GEGLU”, “SwiGLU”, “ReLU”, “GELU”] 或 pytorch 内部激活函数之一 [“relu”, “gelu”]norm_type (str | nn.Module) – 要使用的 LayerNorm 变体类型。默认值:
None。可用选项包括 ["LayerNorm", "RMSNorm", "LayerNormNoBias"]，或者提供自定义 nn.Module。custom_encoder (
Optional[Module,None]) – 用于 Transformer 的自定义用户提供编码器模块 (默认=None)。custom_decoder (
Optional[Module,None]) – 用于 Transformer 的自定义用户提供解码器模块 (默认=None)。**kwargs – 初始化 pytorch_lightning.Module, pytorch_lightning.Trainer 和 Darts 的
TorchForecastingModel的可选参数。loss_fn – 用于训练的 PyTorch 损失函数。对于概率模型，如果指定了
likelihood参数，此参数将被忽略。默认值:torch.nn.MSELoss()。likelihood – Darts 的
Likelihood模型之一，用于概率预测。默认值:None。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 来对抗分布偏移，如 [R55d9314a45ae-3] 所示。它仅应用于目标序列的特征，而不应用于协变量。
batch_size – 每次训练通过使用的时序序列（输入和输出序列）数量。默认值:
32。n_epochs – 训练模型的轮次数量。默认值:
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 – 在评估验证损失之前等待的轮次数量（如果将验证
TimeSeries传递给fit()方法）。默认值:1。force_reset – 如果设置为
True，任何先前存在的同名模型将被重置（所有检查点将被丢弃）。默认值:False。save_checkpoints – 是否自动保存未经训练的模型和训练生成的检查点。要从检查点加载模型，请调用
MyModelClass.load_from_checkpoint()，其中MyModelClass是使用的TorchForecastingModel类（例如TFTModel、NBEATSModel等）。如果设置为False，仍然可以使用save()手动保存模型，并使用load()加载模型。默认值:False。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。使用pl_trainer_kwargs并指定键"accelerator", "devices", 和 "auto_select_gpus"也可以在 GPU 上运行。以下是设置pl_trainer_kwargs字典中设备的示例{"accelerator": "cpu"}用于 CPU，{"accelerator": "gpu", "devices": [i]}仅使用 GPUi(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 Callbacksfrom 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]}
show_warnings – 是否显示 PyTorch Lightning 引发的警告。对于检测预测用例的潜在问题很有用。默认值:
False。
参考文献
- 1
Ashish Vaswani, Noam Shazeer, Niki Parmar, Jakob Uszkoreit, Llion Jones, Aidan N Gomez, Lukasz Kaiser,
and Illia Polosukhin, “Attention Is All You Need”, 2017. In Advances in Neural Information Processing Systems, pages 6000-6010. https://arxiv.org/abs/1706.03762. .. [R55d9314a45ae-2] Shazeer, Noam, “GLU Variants Improve Transformer”, 2020. arVix https://arxiv.org/abs/2002.05202. .. [R55d9314a45ae-3] T. Kim et al. “Reversible Instance Normalization for Accurate Time-Series Forecasting against
Distribution Shift”, https://openreview.net/forum?id=cGDAkQo1C0p
注意
免责声明：当前实现是完全功能的，已经可以产生一些不错的预测。但是，它在使用 Transformer 架构方面仍然有限，因为 torch.nn.Transformer 的 tgt 输入没有得到充分利用。目前，我们简单地将 src 输入的最后一个值传递给 tgt。为了更接近 Transformer 在语言模型中的常用方式，我们应该允许模型将其自身的输出作为 tgt 参数的一部分使用，这样在预测序列值时，随着 Transformer 模型的输出被添加到 tgt 参数的输入将随之增长。当然，模型的训练也必须相应调整。
示例
>>> from darts.datasets import WeatherDataset >>> from darts.models import TransformerModel >>> series = WeatherDataset().load() >>> # predicting atmospheric pressure >>> target = series['p (mbar)'][:100] >>> # optionally, use past observed rainfall (pretending to be unknown beyond index 100) >>> past_cov = series['rain (mm)'][:100] >>> model = TransformerModel( >>> input_chunk_length=6, >>> output_chunk_length=6, >>> n_epochs=20 >>> ) >>> model.fit(target, past_covariates=past_cov) >>> pred = model.predict(6) >>> pred.values() array([[5.40498034], [5.36561899], [5.80616883], [6.48695488], [7.63158655], [5.65417736]])
注意
Transformer 示例 notebook 展示了可用于提高预测质量的技术，相比于这个简单的使用示例。
属性
模型是否考虑静态协变量（如果有）。
一个 8 元组，按顺序包含：(最小目标滞后，最大目标滞后，最小过去协变量滞后，最大过去协变量滞后，最小未来协变量滞后，最大未来协变量滞后，输出偏移，最大目标滞后训练 (仅适用于 RNNModel))。
返回模型用于概率预测的似然模型（如果有）。
训练模型所需的最少样本数。
模型一次预测的时间步长数量，未为统计模型定义。
输出/预测开始于输入结束后的时间步长数量。
模型实例是否支持直接预测似然参数
模型是否考虑时序序列中的多个变量。
模型是否支持优化的历史预测
模型是否支持过去协变量
检查此配置的预测模型是否支持概率预测。
模型是否支持训练时的样本权重。
模型是否支持静态协变量
模型是否支持对任意输入 series 进行预测。
模型拟合后是否使用未来协变量。
模型拟合后是否使用过去协变量。
模型拟合后是否使用静态协变量。
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实例进行预测。重置模型对象并移除所有存储的数据 - 模型、检查点、日志记录器和训练历史。
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()方法（官方文档）。返回一个使用相同参数创建的新的（未经训练的）模型实例。
- 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。
是领先于 start 的 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。
- 注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会向未来偏移 output_chunk_shift 个点。
向未来偏移 output_chunk_shift 个点。
- 注意：如果 start 在可能的历史预测时间之外，则将忽略该参数（使用
None时的默认行为），并从第一个可训练/可预测点开始。 （
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 函数参数。注意：有些模型需要每次重新训练，并且不支持除 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 函数和
historical_forecasts 使用 last_points_only=True 生成的
historical_forecasts 使用 last_points_only=False 生成并使用回测 reduction
np.ndarray – 回测得分的 numpy 数组。对于单个序列和其中一个
单个 metric 函数，historical_forecasts 使用 last_points_only=False 和回测 reduction=None 生成。输出形状为 (n 预测，*)。
多个 metric 函数和 historical_forecasts 使用 last_points_only=False 生成。使用回测 reduction 时输出形状为 (*, n 评估指标)，当 reduction=None 时输出形状为 (n 预测，*, n 评估指标)
包含 series_reduction 的多个单变量/多变量序列，并且至少有一个 component_reduction=None 或 time_reduction=None 用于“每时间步评估指标”
List[float] – 与 float 类型相同，但针对序列。返回的评估指标列表长度为 len(series)，包含每个输入 series 的 float 评估指标。
List[np.ndarray] – 与 np.ndarray 类型相同，但针对序列。返回的评估指标列表长度为 len(series)，包含每个输入 series 的 np.ndarray 评估指标。
- property considers_static_covariates: bool¶
模型是否考虑静态协变量（如果有）。
- 返回类型
模型是否考虑静态协变量（如果有）。
- property epochs_trained: 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, 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()，为该模型构建了一个默认的训练数据集。如果您需要更精细地控制训练时如何切分时间序列，请考虑使用自定义的darts.utils.data.TrainingDataset调用fit_from_dataset()。训练使用 PyTorch Lightning Trainer 进行。它使用预设和模型创建时使用的
pl_trainer_kwargs中的默认 Trainer 对象。您也可以使用带有可选参数trainer的自定义 Trainer。有关 PyTorch Lightning Trainer 的更多信息，请参阅此链接。此函数可以多次调用以进行额外的训练。如果指定了
epochs，模型将训练（额外）epochs个 epoch，无论提供给模型构造函数的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个（额外的）epoch，无论提供给模型构造函数的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 相同，但用于评估数据集。
- 返回
拟合后的模型。
- 返回类型
self
- fit_from_dataset(train_dataset, val_dataset=None, trainer=None, verbose=None, epochs=0, dataloader_kwargs=None)¶
使用特定的
darts.utils.data.TrainingDataset实例训练模型。这些数据集实现了 PyTorchDataset，并指定了如何切分目标和协变量进行训练。如果您不确定使用哪种训练数据集，请考虑调用fit()，它将创建适合此模型的默认训练数据集。训练使用 PyTorch Lightning Trainer 进行。它使用预设和模型创建时使用的
pl_trainer_kwargs中的默认 Trainer 对象。您也可以使用带有可选参数trainer的自定义 Trainer。有关 PyTorch Lightning Trainer 的更多信息，请参阅此链接。此函数可以多次调用以进行额外的训练。如果指定了
epochs，模型将训练（额外）epochs个 epoch，无论提供给模型构造函数的n_epochs是多少。- 参数
train_dataset (
TrainingDataset) – 类型与此模型匹配的训练数据集（例如，PastCovariatesTrainingDataset适用于PastCovariatesTorchModel）。val_dataset (
Optional[TrainingDataset,None]) – 类型与此模型匹配的训练数据集（例如，PastCovariatesTrainingDataset适用于 :class:`PastCovariatesTorchModel`s），代表验证集（用于跟踪验证损失）。trainer (
Optional[Trainer,None]) – 可选参数，用于执行预测的自定义 PyTorch-Lightning Trainer 对象。使用自定义的 trainer 将覆盖 Darts 的默认 trainer。verbose (
Optional[bool,None]) – 是否打印进度。如果在 pl_trainer_kwargs 中有 ProgressBar 回调，则忽略此参数。epochs (
int) – 如果指定，模型将训练epochs个（额外的）epoch，无论提供给模型构造函数的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 种操作模式：扩展窗口模式、分割模式和拟合值模式。这三种操作模式通过实例化 ForecastingModel 的 model_class 子类，并根据 metric 函数评估 parameters 字典中提供的超参数值的每种可能组合，最后返回性能最佳的模型。metric 函数应返回一个误差值，因此将选择产生最小 metric 输出的模型。
训练数据和测试数据之间的关系取决于操作模式。
扩展窗口模式（传递 forecast_horizon 时激活）：对于每个超参数组合，模型在 series 的不同切分上重复训练和评估。此过程通过使用
backtest()函数作为子程序来实现，生成从 start 开始的历史预测，并与 series 的真实值进行比较。注意，模型会针对每个单独的预测重新训练，因此此模式速度较慢。分割窗口模式（传递 val_series 时激活）：当传递 val_series 参数时将使用此模式。对于每个超参数组合，模型在 series 上训练，并在 val_series 上进行评估。
拟合值模式（use_fitted_values 设置为 True 时激活）：对于每个超参数组合，模型在 series 上训练，并根据生成的拟合值进行评估。并非所有模型都具有拟合值，如果模型没有 fitted_values 成员，此方法会引发错误。拟合值是模型在 series 上拟合的结果。与拟合值进行比较是评估模型的一种快速方法，但无法看出模型是否过拟合了序列。
派生类必须确保模型的单一实例不与其他实例共享参数，例如将模型保存到同一路径。否则，在并行运行多个模型（当
n_jobs != 1时）时，可能会出现意外行为。如果无法避免，则应重新定义 gridsearch，强制设置n_jobs = 1。目前，此方法仅支持确定性预测（即当模型的预测只有 1 个样本时）。
- 参数
model_class – 将针对“series”进行调优的 ForecastingModel 子类。
parameters (
dict) – 一个字典，键是超参数名称，值是对应超参数值的列表。series (
TimeSeries) – 用作训练输入和目标的序列。past_covariates (
Optional[TimeSeries,None]) – 可选参数，一个历史观测协变量序列。此参数仅当模型支持历史协变量时适用。future_covariates (
Optional[TimeSeries,None]) – 可选参数，一个已知未来协变量序列。此参数仅当模型支持已知未来协变量时适用。forecast_horizon (
Optional[int,None]) – 预测范围的整数值。激活扩展窗口模式。stride (
int) – 仅在扩展窗口模式下使用。两次连续预测之间的时间步数。start (
Union[Timestamp,float,int,None]) –仅在扩展窗口模式下使用。可选参数，计算预测的第一个时间点。此参数支持：
float、int、pandas.Timestamp和None。如果是float，则表示第一个预测点之前的时间序列比例。如果是int，则对于使用 pd.DatetimeIndex 索引的 series，它是第一个预测点的索引位置；对于使用 pd.RangeIndex 索引的 series，它是第一个预测点的索引值。后者可以通过 start_format=”position” 更改为索引位置。如果是pandas.Timestamp，则它是第一个预测点的时间戳。如果是None，则第一个预测点将自动设置为如果 retrain 为
False，或者 retrain 是 Callable 且第一个可预测点早于第一个可训练点，则设置为第一个可预测点。如果 retrain 是
True或int（给定 train_length），则为第一个可训练点；或者如果 retrain 是一个 Callable 且第一个可训练点早于第一个可预测点，则为第一个可训练点。否则设置为第一个可训练点（给定 train_length）
- 注意：如果 start 不在可训练/可预测点范围内，则使用最接近的有效起始点，该点是 start 之前 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。
是领先于 start 的 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。
- 注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会向未来偏移 output_chunk_shift 个点。
向未来偏移 output_chunk_shift 个点。
- 注意：如果 start 在可能的历史预测时间之外，则将忽略该参数（使用
None时的默认行为），并从第一个可训练/可预测点开始。 （
None时的默认行为）并从第一个可训练/可预测点开始。
start_format (
Literal[‘position’, ‘value’]) – 仅在扩展窗口模式下使用。定义 start 格式。仅当 start 是整数且 series 使用 pd.RangeIndex 索引时有效。如果设置为“position”，则 start 对应于第一个预测点的索引位置，范围为(-len(series), len(series) - 1)。如果设置为“value”，则 start 对应于第一个预测点的索引值/标签。如果该值不在 series 的索引中，将引发错误。默认值：'value'last_points_only (
bool) – 仅在扩展窗口模式下使用。是使用整个预测结果，还是仅使用每个预测结果的最后一个点来计算误差。show_warnings (
bool) – 仅在扩展窗口模式下使用。是否显示与 start 参数相关的警告。val_series (
Optional[TimeSeries,None]) – 在分割模式下用于验证的 TimeSeries 实例。如果提供，此序列必须紧接在 series 结尾之后开始；以便可以对预测结果进行适当的比较。use_fitted_values (
bool) – 如果为 True，则使用与拟合值的比较。如果 model_class 没有fitted_values属性，则引发错误。拟合值是模型在 series 上拟合的结果。与拟合值进行比较是评估模型的一种快速方法，但无法看出模型是否过拟合了序列。metric (
Callable[[TimeSeries,TimeSeries],float]) –一个度量函数，返回两个 TimeSeries 之间的误差作为浮点值。必须是 Darts 的“时间聚合”度量之一（参见此处），或者是一个以两个 TimeSeries 作为输入并返回误差的自定义度量。
reduction (
Callable[[ndarray],float]) – 一个归约函数（将数组映射到浮点数），描述如何在回测时聚合在不同验证序列上获得的误差。默认情况下，它将计算误差的平均值。verbose – 是否打印进度。
n_jobs (
int) – 并行运行的作业数。仅当有两个或更多参数组合需要评估时创建并行作业。每个作业将实例化、训练和评估不同的模型实例。默认为 1（顺序）。将参数设置为 -1 表示使用所有可用核心。n_random_samples (
Union[int,float,None]) – 从完整参数网格中选择的超参数组合的数量/比例。这将执行随机搜索而非使用完整网格。如果是一个整数，n_random_samples 是从完整网格中选择的参数组合数量，必须在 0 和总参数组合数量之间。如果是一个浮点数，n_random_samples 是从完整网格中选择的参数组合比例，必须在 0 和 1 之间。默认为 None，此时将忽略随机选择。data_transformers (
Optional[dict[str,Union[BaseDataTransformer,Pipeline]],None]) –可选，一个 BaseDataTransformer 或 Pipeline 字典，应用于相应的序列（可能的键包括：“series”、“past_covariates”、“future_covariates”）。如果提供，所有输入序列必须处于未转换的空间中。对于可拟合转换器/流水线
如果 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” 衰减——越远的过去，权重越低。权重是根据 series 中最长序列的长度全局计算的。然后对于每个序列，从全局权重的末尾提取相应的权重。这为所有序列提供了通用的时间加权。
- 返回
一个元组，包含根据性能最佳的超参数创建的未训练 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。
是领先于 start 的 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。
- 注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会向未来偏移 output_chunk_shift 个点。
向未来偏移 output_chunk_shift 个点。
- 注意：如果 start 在可能的历史预测时间之外，则将忽略该参数（使用
None时的默认行为），并从第一个可训练/可预测点开始。 （
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 函数参数。注意：有些模型需要每次重新训练，并且不支持除 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¶
- 返回类型
已训练的轮次数量。
- 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()方法的附加关键字参数，例如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 –
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()，它也会重新加载 trainer、optimizer 和学习率调度器的状态。对于手动保存的模型，请考虑使用
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 的更多信息，请查看 此链接。如果 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个（额外的）epoch，无论提供给模型构造函数的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 扫描的结果。
- 返回类型
lr_finder
- property min_train_samples: int¶
训练模型所需的最少样本数。
- 返回类型
已训练的轮次数量。
- property model_created: bool¶
- 返回类型
模型是否考虑静态协变量（如果有）。
- property model_params: dict¶
- 返回类型
dict
- property output_chunk_length: int¶
模型一次预测的时间步长数量，未为统计模型定义。
- 返回类型
已训练的轮次数量。
- property output_chunk_shift: 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 执行的。它使用预设中的默认 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范围内）。需要这些未来协变量的“历史”值（在过去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。这允许通过指定对学习模型的隐式先验进行贝叶斯近似。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实例进行预测。这些数据集实现了 PyTorchDataset，并指定了目标和协变量如何切片用于推理。在大多数情况下，您会更希望调用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
- 返回
返回一个或多个时间序列的预测。
- 返回类型
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。
是领先于 start 的 stride 的整数倍。如果不存在有效的起始点，则引发 ValueError。
- 注意：如果模型使用偏移输出（output_chunk_shift > 0），则第一个预测点也会向未来偏移 output_chunk_shift 个点。
向未来偏移 output_chunk_shift 个点。
- 注意：如果 start 在可能的历史预测时间之外，则将忽略该参数（使用
None时的默认行为），并从第一个可训练/可预测点开始。 （
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 函数参数。注意：有些模型需要每次重新训练，并且不支持除 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’ 等。仅当参数存在于相应的度量签名中时才传递参数。忽略归约参数 “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 和使用 last_points_only=True 生成的 historical_forecasts 的残差 TimeSeries。
List[TimeSeries] – 对于具有 last_points_only=True 的时间序列序列（列表）的残差 TimeSeries 列表。残差列表的长度为 len(series)。
List[List[TimeSeries]] – 对于具有 last_points_only=False 的时间序列序列的残差 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() 和其他预测方法。
- 返回类型
None
- supports_future_covariates = False¶
- 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_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()方法的附加 kwargs（参数file_path、input_sample、input_name除外）。有关更多信息，请阅读官方文档。
- untrained_model()¶
返回一个使用相同参数创建的新的（未经训练的）模型实例。
- property uses_future_covariates: bool¶
模型拟合后是否使用未来协变量。
- 返回类型
模型是否考虑静态协变量（如果有）。
- property uses_past_covariates: bool¶
模型拟合后是否使用过去协变量。
- 返回类型
模型是否考虑静态协变量（如果有）。
- property uses_static_covariates: bool¶
模型拟合后是否使用静态协变量。
- 返回类型
模型是否考虑静态协变量（如果有）。