共形模型

一组用于预训练全局预测模型的共形预测模型。

class darts.models.forecasting.conformal_models.ConformalModel(model, quantiles, symmetric=True, cal_length=None, cal_stride=1, cal_num_samples=500, random_state=None)

基类: GlobalForecastingModel, ABC

基础共形预测模型。

任何共形预测模型的基类。共形模型可以校准任何预训练全局预测模型的预测结果。它不需要进行训练，可以直接使用底层的训练好的预测模型生成校准后的预测。由于它是一个概率模型，您可以通过两种方式生成预测（调用 predict()、historical_forecasts() 等方法时）：

• 直接预测校准后的分位数区间：将参数 predict_likelihood_parameters=True 和 num_samples=1 传递给预测方法。

• 从校准后的分位数区间预测随机样本：将参数 predict_likelihood_parameters=False 和 num_samples>>1 传递给预测方法。

共形模型可以应用于 Darts 中的任何全局预测模型，只要模型已经拟合过。通常，模型生成校准后的预测的流程如下：

• 提取校准集：每个共形预测的校准集会自动从输入序列相对于预测起始点的最新历史数据中提取。要考虑的校准示例数量（预测误差 / 非一致性分数）可以在创建模型时通过参数 cal_length 定义。请注意，当使用 cal_stride>1 时，需要更长的历史数据，因为校准示例是通过带有步长的历史预测生成的。

• 在校准集上（使用预测模型）以 cal_stride 步长生成历史预测。

• 计算这些历史预测的误差/非一致性分数（特定于每个共形模型）

• 从误差/非一致性分数计算分位数（使用在模型创建时通过参数 quantiles 设置的期望分位数）。

• 计算共形预测：使用这些分位数，为预测模型的预测结果添加校准后的区间（或调整现有区间）。

注意事项

• 计算 historical_forecasts()、backtest()、residuals() 等方法时，上述流程应用于每个预测（预测模型的历史预测仅生成一次以提高效率）。

• 对于多步预测，上述流程对预测范围中的每个步骤分别应用。

参数

• model (GlobalForecastingModel) – 一个预训练的全局预测模型。请参见此处获取模型列表。

• quantiles (list[float]) – 要使用的围绕中位数 q=0.5 的分位数列表。例如，分位数 [0.1, 0.2, 0.5, 0.8, 0.9] 对应于两个区间，分别在中位数（模型预测）周围覆盖 (0.9 - 0.1) = 80% 和 (0.8 - 0.2) = 60%。

• symmetric (bool) – 是否使用对称非一致性分数。如果为 False，则使用非对称分数（分别为分位数区间下限和上限计算分数）。

• cal_length (Optional[int, None]) – 对于每个共形预测（以及预测范围中的每个步骤），用于校准的过去预测误差/非一致性分数的数量。如果为 None，则考虑所有分数。

• cal_stride (int) – 在校准集上计算历史预测和非一致性分数时应用的步长。实际的共形预测可以在下游任务中（例如历史预测、回测等）通过参数 stride 设置不同的步长。

• cal_num_samples (int) – 为每个校准预测生成的样本数量（如果 model 是概率预测模型）。非一致性分数是基于这些预测的分位数（使用 quantiles）计算的。对于确定性模型，使用 1 个样本。实际的共形预测可以在下游任务中（例如 predict、historical forecasts 等）通过参数 num_samples 设置不同的样本数量。

• random_state (Optional[int, None]) – 控制不同运行中概率共形预测（样本生成）的随机性。

属性

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

model_params

方法

backtest(series[, past_covariates, ...])	计算模型在（可能多个）series 上的历史预测所产生的误差值。
fit(series[, past_covariates, future_covariates])	在（可能多个）序列上拟合/训练底层预测模型。
generate_fit_encodings(series[, ...])	生成用于模型拟合的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
generate_fit_predict_encodings(n, series[, ...])	生成用于训练和推理/预测的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
generate_predict_encodings(n, series[, ...])	生成用于推理/预测集的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
gridsearch(parameters, series[, ...])	使用网格搜索在给定集合中找到最佳超参数。
historical_forecasts(series[, ...])	通过模拟在提供的（可能多个）series 的整个历史中不同时间点的预测来生成校准后的历史预测。
load(path[, pl_trainer_kwargs])	从给定路径或文件句柄加载模型。
predict(n[, series, past_covariates, ...])	预测 series 结束后的 n 个时间步长的校准分位数区间（或从校准区间中抽样）。
residuals(series[, past_covariates, ...])	计算模型在（可能多个）series 上的历史预测所产生的残差。
save([path, clean])	将共形模型保存到给定路径或文件句柄。
untrained_model()	返回使用相同参数创建的新的（未训练的）模型实例。

backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

计算模型在（可能多个）series 上的历史预测所产生的误差值。

如果提供了 historical_forecasts，则直接对所有预测值和实际值评估指标（由 metric 函数给出）。必须传递用于生成历史预测的相同 series 和 last_points_only 值。最后，该方法返回对所有这些指标分数的 Optional 汇总（默认为平均值）。

如果 historical_forecasts 为 None，则它首先使用以下给定参数生成历史预测（更多信息请参见 ConformalModel.historical_forecasts()），然后按上述方式进行评估。

指标可以通过 metric_kwargs 进一步自定义（例如，控制跨组件、时间步长、多个序列的聚合，或分位数指标所需的其他参数如 q 等）。

注意事项

Darts 有几种评估概率预测的指标。对于共形模型，我们建议使用分位数区间指标（参见此处）。您可以通过设置 metric_kwargs={‘q_interval’: my_intervals} 指定要评估的区间。要检查您的共形模型 my_model 使用的所有区间，可以设置 {'q_interval': my_model.q_interval}。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• 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) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 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]]) – 共形模型当前忽略此参数。

• 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，则直接生成分位数预测。仅支持 num_samples = 1。

• 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]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

返回类型

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

返回

• float – 单个单/多变量序列、单个 metric 函数和使用 last_points_only=True 生成的 historical_forecasts 的单个回测分数。

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

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

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

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

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

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

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

• property considers_static_covariates: bool

bool

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

返回类型

property 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。

注意事项

tuple[Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], int, Optional[int, None]]

示例

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

返回类型

fit(series, past_covariates=None, future_covariates=None, **kwargs)

可选地，可以提供一个或多个过去和/或未来协变量序列，具体取决于使用的预测模型。协变量序列的数量必须与目标序列的数量匹配。

在（可能多个）序列上拟合/训练底层预测模型。

共形模型不需要调用 fit()，因为它们使用预训练的全局预测模型。您可以直接调用 predict()。此外，请确保 predict() 中使用的输入序列对应于校准集，而不是与 fit() 训练时使用的序列相同。

注意事项

series (Union[TimeSeries, Sequence[TimeSeries]]) – 一个或多个目标时间序列。模型将训练来预测这些时间序列。序列可以是单变量或多变量，但如果提供多个序列，它们必须具有相同数量的组件。

参数

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个过去观测的协变量时间序列。这些时间序列不会被预测，但可以被某些模型用作输入。协变量可以是单变量或多变量，但如果提供多个协变量，它们必须具有相同数量的组件。如果提供了 past_covariates，其序列数量必须与 series 相同。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个未来已知的协变量时间序列。这些时间序列不会被预测，但可以被某些模型用作输入。协变量可以是单变量或多变量，但如果提供多个协变量，它们必须具有相同数量的组件。如果提供了 future_covariates，其序列数量必须与 series 相同。

• **kwargs – 可选关键字参数，将传递给底层预测模型的 fit() 方法。

• 拟合的模型。

返回

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

• generate_predict_encodings(n, series, past_covariates=None, future_covariates=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。

series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于预测的目标值序列或序列的序列。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于训练和预测的目标值序列或序列的序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，打算用于预测的过去观测协变量序列。维度必须与训练时使用的协变量维度匹配。

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

• generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)

返回

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

返回类型

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)

此函数有 3 种操作模式：扩展窗口模式、分割模式和拟合值模式。这三种操作模式通过使用 model_class 的子类 ForecastingModel 实例化 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 子类。

参数

• model_class – ForecastingModel 子类，用于对 ‘series’ 进行调优。

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

• series (TimeSeries) – 用作输入和训练目标的 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。

  注意：如果模型使用 shifted output (output_chunk_shift > 0)，则第一个预测点也会

  向未来偏移 output_chunk_shift 个点。

  注意：如果 start 超出可能的历史预测时间范围，则会忽略该参数

  (即使用 None 时的默认行为)，并从第一个可训练/可预测点开始。

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

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

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

• val_series (Optional[TimeSeries, None]) – 在分割模式下用于验证的 TimeSeries 实例。如果提供，该序列必须紧接在 series 的末尾之后开始；以便进行准确的预测比较。

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

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

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

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

• verbose – 是否打印进度信息。

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

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

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

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

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

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

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

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

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

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

返回

一个元组，包含一个从未训练过的 model_class 实例（由表现最佳的超参数创建），以及一个包含这些最佳超参数的字典，以及最佳超参数的指标分数。

返回类型

ForecastingModel, Dict, float

historical_forecasts(series, past_covariates=None, future_covariates=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

通过模拟在提供的（可能是多个）series 整个历史中不同时间点的预测，生成经过校准的历史预测。这个过程包括回溯性地将模型应用于不同的时间步长，就像在那些特定时刻进行实时预测一样。这允许评估模型在整个序列持续时间内的性能，从而深入了解其在不同历史时期的预测准确性和鲁棒性。

目前，共形模型仅支持预训练历史预测模式（retrain=False）。参数 retrain 和 train_length 将被忽略。

预训练模式： 首先，使用底层预训练的全局预测模型生成所有历史预测（更多信息参见 ForecastingModel.historical_forecasts()）。然后，它通过从历史预测的开始处扩展或使用长度为 cal_length 的固定长度滑动窗口，重复构建一个校准集（起始点也可以通过 start 和 start_format 配置）。然后，将长度为 forecast_horizon 的下一个预测在此校准集上进行校准。接着，校准集的结束点向前移动 stride 个时间步长，重复此过程。

默认情况下，当 last_points_only=True 时，此方法返回一个时间序列（当 series 也是序列时，返回一个时间序列序列），该序列由每个校准历史预测的最后一个点组成。因此，此时间序列的频率将是 series.freq * stride。如果 last_points_only=False，则将返回一个列表（或列表序列），其中包含所有长度为 forecast_horizon、频率为 series.freq 的校准历史预测。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）过去观测的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）未来已知的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

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

• num_samples (int) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 start 超出可能的历史预测时间范围，则会忽略此参数（None 时的默认行为）并从第一个可训练/可预测点开始。

• start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，start 对应于第一个预测点的索引值/标签。如果值不在 series 的索引中，将引发错误。默认值：'value'。

• stride (int) – 两次连续预测之间的时间步长数。必须是 cal_stride（在模型创建时设置）的整数倍，且 >=cal_stride。

• retrain (Union[bool, int, Callable[…, bool]]) – 共形模型当前忽略此参数。

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

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

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

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

• predict_likelihood_parameters (bool) – 如果设置为 True，则直接生成分位数预测。仅支持 num_samples = 1。

• 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]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

返回类型

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

返回

• TimeSeries – 对于单个 series 且 last_points_only=True 的单个历史预测：它仅包含所有历史预测中步长为 forecast_horizon 的预测结果。

• TimeSeries 列表 – 以下情况下的历史预测列表：

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

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

• TimeSeries 列表的列表 – 对于一个 series 序列且 last_points_only=False 的历史预测列表的列表。对于每个序列和历史预测，它都包含整个范围 forecast_horizon。外部列表对应于输入序列中提供的系列，内部列表包含每个系列的历史预测。

property likelihood: Likelihood

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

返回类型

Likelihood

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

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

参数

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

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

• **kwargs – 仅当底层预测模型是 TorchForecastingModel 时有效。传递给 PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法的额外 kwargs。更多信息，请阅读 官方文档。

返回类型

ConformalModel

property min_train_samples: int

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

返回类型

int

property model_params: dict

返回类型

dict

property output_chunk_length: Optional[int]

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

返回类型

Optional[int, None]

property output_chunk_shift: int

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

返回类型

int

predict(n, series=None, past_covariates=None, future_covariates=None, num_samples=1, verbose=False, predict_likelihood_parameters=False, show_warnings=True, **kwargs)

预测 series 结束后的 n 个时间步长的校准分位数区间（或从校准区间中抽样）。

重要的是，用于预测的输入序列应对应于一个校准集——一个与用于训练底层预测 model 的序列不同的集合。

由于它是一个概率模型，您可以通过两种方式生成预测结果

• 直接预测校准后的分位数区间：将参数 predict_likelihood_parameters=True 和 num_samples=1 传递给预测方法。

• 从校准后的分位数区间预测随机样本：将参数 predict_likelihood_parameters=False 和 num_samples>>1 传递给预测方法。

在底层，为范围 n 中的每个步骤生成一个校准预测/预报的简化工作流程如下（注意：cal_length 和 cal_stride 可以在模型创建时设置）

• 提取校准集：每个共形预测的校准集会自动从输入序列相对于预测起始点的最新历史数据中提取。要考虑的校准示例数量（预测误差 / 非一致性分数）可以在创建模型时通过参数 cal_length 定义。请注意，当使用 cal_stride>1 时，需要更长的历史数据，因为校准示例是通过带有步长的历史预测生成的。

• 在校准集上（使用预测模型）以 cal_stride 步长生成历史预测。

• 计算这些历史预测的误差/非一致性分数（特定于每个共形模型）

• 从误差/非一致性分数计算分位数（使用在模型创建时通过参数 quantiles 设置的期望分位数）。

• 计算共形预测：使用这些分位数，为预测模型的预测结果添加校准后的区间（或调整现有区间）。

参数

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

• series (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个序列或序列的序列，表示目标序列的历史，其未来将被预测。将使用此序列的过去数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）过去观测的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）未来已知的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• num_samples (int) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

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

• predict_likelihood_parameters (bool) – 如果设置为 True，则直接生成分位数预测。仅支持 num_samples = 1。

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

• **kwargs – 可选的关键字参数，将传递给底层预测模型的 predict() 和 historical_forecasts() 方法。

返回

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

返回类型

Union[TimeSeries, Sequence[TimeSeries]]

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

计算模型在（可能多个）series 上的历史预测所产生的残差。

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

此方法按顺序执行以下操作：

• 使用预先计算的 historical_forecasts 或计算每个序列的历史预测（更多详细信息参见 historical_forecasts()）。历史预测的生成方式可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 进行配置。

• 对历史预测和 series 之间按分量/列和时间步长计算“每个时间步长”的 metric 进行回测（更多详细信息参见 backtest()）。默认情况下，使用残差 err()（误差）作为 metric。

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

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

注意事项

Darts 有几个评估概率预测的指标。对于共形模型，我们推荐使用“每个时间步长”的分位数区间指标（参见 此处）。您可以通过设置 metric_kwargs={‘q_interval’: my_intervals} 来指定要评估的区间。要检查您的共形模型 my_model 使用的所有区间，您可以设置 {'q_interval': my_model.q_interval}。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• 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) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 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]]) – 共形模型当前忽略此参数。

• 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，则直接生成分位数预测。仅支持 num_samples = 1。

• 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’，用于 scaled metrics 的 ‘m’ 等。仅当参数存在于相应的指标签名中时才会传递。忽略归约参数 “series_reduction”, “component_reduction”, “time_reduction”，以及 scaled metrics（例如 mase, rmsse 等）的参数 ‘insample’，因为它们在内部处理。

• fit_kwargs (Optional[dict[str, Any], None]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

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

返回类型

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

返回

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

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

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

save(path=None, clean=False, **pkl_kwargs)

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

此外，如果 self.model 是一个 TorchForecastingModel，还会存储两个文件。

保存和加载 ConformalNaiveModel 的示例

from darts.datasets import AirPassengersDataset
from darts.models import ConformalNaiveModel, LinearRegressionModel

series = AirPassengersDataset().load()
forecasting_model = LinearRegressionModel(lags=4).fit(series)

model = ConformalNaiveModel(
    model=forecasting_model,
    quantiles=[0.1, 0.5, 0.9],
)

model.save("my_model.pkl")
model_loaded = ConformalNaiveModel.load("my_model.pkl")

参数

• path (Union[str, PathLike, BinaryIO, None]) – 保存集成模型当前状态的路径或文件句柄。如果未指定路径，集成模型将自动保存为 "{ConformalNaiveModel}_{YYYY-mm-dd_HH_MM_SS}.pkl"。如果预测模型是 TorchForecastingModel，则两个文件（模型对象和检查点）将保存为 "{path}.{ModelClass}.pt" 和 "{path}.{ModelClass}.ckpt"。

• clean (bool) –

  是否存储模型的清理版本。如果为 True，则移除训练序列和协变量。如果底层预测 model 是一个 TorchForecastingModel，还会额外移除所有 Lightning Trainer 相关的参数。

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

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

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

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

property supports_likelihood_parameter_prediction: bool

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

返回类型

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

property supports_multivariate: bool

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

返回类型

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

property supports_optimized_historical_forecasts: bool

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

返回类型

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

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

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

property supports_probabilistic_prediction: bool

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

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

返回类型

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

property supports_sample_weight: bool

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

返回类型

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

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

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

property supports_transferable_series_prediction: bool

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

返回类型

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

untrained_model()

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

property uses_future_covariates: bool

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

返回类型

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

property uses_past_covariates: bool

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

返回类型

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

property uses_static_covariates: bool

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

返回类型

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

class darts.models.forecasting.conformal_models.ConformalNaiveModel(model, quantiles, symmetric=True, cal_length=None, cal_stride=1, cal_num_samples=500, random_state=None)

Bases: ConformalModel

朴素共形预测模型。

一个概率模型，它在预训练的全局预测模型的中位数预测周围添加校准区间。它无需训练，可以直接使用底层训练好的预测模型生成校准预测。它支持两种对称模式：

• symmetric=True:

  • 下限和上限区间以相同的幅度进行校准。

  • 非一致性分数：使用指标 ae()（参见绝对误差 ae()）计算校准集上的非一致性分数。

• symmetric=False

  • 下限和上限区间分别进行校准。

  • 非一致性分数：使用指标 err()（参见误差 err()）计算校准集上上限的非一致性分数，使用 -err() 计算下限的非一致性分数。

由于它是一个概率模型，您可以通过两种方式生成预测结果（调用 predict(), historical_forecasts() 等方法时）

• 直接预测校准后的分位数区间：将参数 predict_likelihood_parameters=True 和 num_samples=1 传递给预测方法。

• 从校准后的分位数区间预测随机样本：将参数 predict_likelihood_parameters=False 和 num_samples>>1 传递给预测方法。

共形模型可以应用于 Darts 中的任何全局预测模型，只要模型已经拟合过。通常，模型生成校准后的预测的流程如下：

• 提取校准集：每个共形预测的校准集会自动从输入序列相对于预测起始点的最新历史数据中提取。要考虑的校准示例数量（预测误差 / 非一致性分数）可以在创建模型时通过参数 cal_length 定义。请注意，当使用 cal_stride>1 时，需要更长的历史数据，因为校准示例是通过带有步长的历史预测生成的。

• 在校准集上（使用预测模型）以 cal_stride 步长生成历史预测。

• 根据这些历史预测计算误差/非一致性分数（如上定义）

• 从误差/非一致性分数计算分位数（使用在模型创建时通过参数 quantiles 设置的期望分位数）。

• 计算共形预测：使用这些分位数，向预测模型的预测结果添加校准区间。

注意事项

• 计算 historical_forecasts()、backtest()、residuals() 等方法时，上述流程应用于每个预测（预测模型的历史预测仅生成一次以提高效率）。

• 对于多步预测，上述流程对预测范围中的每个步骤分别应用。

参数

• model (GlobalForecastingModel) –

  一个预训练的全局预测模型。模型列表参见 此处。

• quantiles (list[float]) – 要使用的围绕中位数 q=0.5 的分位数列表。例如，分位数 [0.1, 0.2, 0.5, 0.8, 0.9] 对应于两个区间，分别在中位数（模型预测）周围覆盖 (0.9 - 0.1) = 80% 和 (0.8 - 0.2) = 60%。

• symmetric (bool) – 是否使用对称的非一致性分数。如果为 True，则使用指标 ae()（参见 ae()）计算非一致性分数。如果为 False，则使用指标 -err()（参见 err()）计算下分位数区间的非一致性分数，使用 err() 计算上分位数区间的非一致性分数。

• cal_length (Optional[int, None]) – 对于每个共形预测（以及预测范围中的每个步骤），用于校准的过去预测误差/非一致性分数的数量。如果为 None，则考虑所有分数。

• cal_stride (int) – 在校准集上计算历史预测和非一致性分数时应用的步长。实际的共形预测可以在下游任务中（例如历史预测、回测等）通过参数 stride 设置不同的步长。

• cal_num_samples (int) – 为每个校准预测生成的样本数量（如果 model 是概率预测模型）。非一致性分数是基于这些预测的分位数（使用 quantiles）计算的。对于确定性模型，使用 1 个样本。实际的共形预测可以在下游任务中（例如 predict、historical forecasts 等）通过参数 num_samples 设置不同的样本数量。

• random_state (Optional[int, None]) – 控制不同运行中概率共形预测（样本生成）的随机性。

属性

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

model_params

方法

backtest(series[, past_covariates, ...])	计算模型在（可能多个）series 上的历史预测所产生的误差值。
fit(series[, past_covariates, future_covariates])	在（可能多个）序列上拟合/训练底层预测模型。
generate_fit_encodings(series[, ...])	生成用于模型拟合的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
generate_fit_predict_encodings(n, series[, ...])	生成用于训练和推理/预测的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
generate_predict_encodings(n, series[, ...])	生成用于推理/预测集的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
gridsearch(parameters, series[, ...])	使用网格搜索在给定集合中找到最佳超参数。
historical_forecasts(series[, ...])	通过模拟在提供的（可能多个）series 的整个历史中不同时间点的预测来生成校准后的历史预测。
load(path[, pl_trainer_kwargs])	从给定路径或文件句柄加载模型。
predict(n[, series, past_covariates, ...])	预测 series 结束后的 n 个时间步长的校准分位数区间（或从校准区间中抽样）。
residuals(series[, past_covariates, ...])	计算模型在（可能多个）series 上的历史预测所产生的残差。
save([path, clean])	将共形模型保存到给定路径或文件句柄。
untrained_model()	返回使用相同参数创建的新的（未训练的）模型实例。

backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

计算模型在（可能多个）series 上的历史预测所产生的误差值。

如果提供了 historical_forecasts，则直接对所有预测值和实际值评估指标（由 metric 函数给出）。必须传递用于生成历史预测的相同 series 和 last_points_only 值。最后，该方法返回对所有这些指标分数的 Optional 汇总（默认为平均值）。

如果 historical_forecasts 为 None，则它首先使用以下给定参数生成历史预测（更多信息请参见 ConformalModel.historical_forecasts()），然后按上述方式进行评估。

指标可以通过 metric_kwargs 进一步自定义（例如，控制跨组件、时间步长、多个序列的聚合，或分位数指标所需的其他参数如 q 等）。

注意事项

Darts 有几种评估概率预测的指标。对于共形模型，我们建议使用分位数区间指标（参见此处）。您可以通过设置 metric_kwargs={‘q_interval’: my_intervals} 指定要评估的区间。要检查您的共形模型 my_model 使用的所有区间，可以设置 {'q_interval': my_model.q_interval}。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• 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) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 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]]) – 共形模型当前忽略此参数。

• 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，则直接生成分位数预测。仅支持 num_samples = 1。

• 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]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

返回类型

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

返回

• float – 单个单/多变量序列、单个 metric 函数和使用 last_points_only=True 生成的 historical_forecasts 的单个回测分数。

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

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

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

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

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

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

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

• property considers_static_covariates: bool

property considers_static_covariates: bool

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

返回类型

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

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

参见下面的示例。

如果模型未拟合：

目标（仅限 RegressionModels）：则第一个元素应为 None。

• 过去协变量：则第三和第四个元素应为 None。

• 未来协变量：则第五和第六个元素应为 None。

• 使用过去或未来协变量的模型和/或最小目标滞后和最大目标滞后可能不同于 -1 和 0 的模型应覆盖此方法。

最大目标滞后（第二个值）不能为 None，且总是大于或等于 0。

注意事项

tuple[Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], int, Optional[int, None]]

示例

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

返回类型

fit(series, past_covariates=None, future_covariates=None, **kwargs)

fit(series, past_covariates=None, future_covariates=None, **kwargs)

在（可能多个）序列上拟合/训练底层预测模型。

共形模型不需要调用 fit()，因为它们使用预训练的全局预测模型。您可以直接调用 predict()。此外，请确保 predict() 中使用的输入序列对应于校准集，而不是与 fit() 训练时使用的序列相同。

注意事项

series (Union[TimeSeries, Sequence[TimeSeries]]) – 一个或多个目标时间序列。模型将训练来预测这些时间序列。序列可以是单变量或多变量，但如果提供多个序列，它们必须具有相同数量的组件。

参数

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个过去观测的协变量时间序列。这些时间序列不会被预测，但可以被某些模型用作输入。协变量可以是单变量或多变量，但如果提供多个协变量，它们必须具有相同数量的组件。如果提供了 past_covariates，其序列数量必须与 series 相同。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个未来已知的协变量时间序列。这些时间序列不会被预测，但可以被某些模型用作输入。协变量可以是单变量或多变量，但如果提供多个协变量，它们必须具有相同数量的组件。如果提供了 future_covariates，其序列数量必须与 series 相同。

• **kwargs – 可选关键字参数，将传递给底层预测模型的 fit() 方法。

• 拟合的模型。

返回

self

返回类型

generate_fit_encodings(series, past_covariates=None, future_covariates=None)

generate_fit_encodings(series, past_covariates=None, future_covariates=None)

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)

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)

n (int) – 打算用于预测的、在 series 结束后的预测时间步长数量。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于训练和预测的目标值序列或序列的序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，打算用于训练和预测的过去观测协变量序列。维度必须与训练时使用的协变量维度匹配。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，打算用于预测的未来已知协变量序列。维度必须与训练时使用的协变量维度匹配。

• generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)

返回

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

返回类型

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)

generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)

series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于预测的目标值序列或序列的序列。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于训练和预测的目标值序列或序列的序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，打算用于预测的过去观测协变量序列。维度必须与训练时使用的协变量维度匹配。

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

• generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)

返回

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

返回类型

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)

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)

使用网格搜索在给定集合中找到最佳超参数。

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

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

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

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

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

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

model_class – 要针对“series”调整的 ForecastingModel 子类。

参数

• model_class – ForecastingModel 子类，用于对 ‘series’ 进行调优。

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

• series (TimeSeries) – 用作输入和训练目标的 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。

  注意：如果模型使用 shifted output (output_chunk_shift > 0)，则第一个预测点也会

  向未来偏移 output_chunk_shift 个点。

  注意：如果 start 超出可能的历史预测时间范围，则会忽略该参数

  (即使用 None 时的默认行为)，并从第一个可训练/可预测点开始。

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

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

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

• val_series (Optional[TimeSeries, None]) – 在分割模式下用于验证的 TimeSeries 实例。如果提供，该序列必须紧接在 series 的末尾之后开始；以便进行准确的预测比较。

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

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

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

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

• verbose – 是否打印进度信息。

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

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

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

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

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

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

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

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

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

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

返回

一个元组，包含一个从未训练过的 model_class 实例（由表现最佳的超参数创建），以及一个包含这些最佳超参数的字典，以及最佳超参数的指标分数。

返回类型

ForecastingModel, Dict, float

historical_forecasts(series, past_covariates=None, future_covariates=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

通过模拟在提供的（可能是多个）series 整个历史中不同时间点的预测，生成经过校准的历史预测。这个过程包括回溯性地将模型应用于不同的时间步长，就像在那些特定时刻进行实时预测一样。这允许评估模型在整个序列持续时间内的性能，从而深入了解其在不同历史时期的预测准确性和鲁棒性。

目前，共形模型仅支持预训练历史预测模式（retrain=False）。参数 retrain 和 train_length 将被忽略。

预训练模式： 首先，使用底层预训练的全局预测模型生成所有历史预测（更多信息参见 ForecastingModel.historical_forecasts()）。然后，它通过从历史预测的开始处扩展或使用长度为 cal_length 的固定长度滑动窗口，重复构建一个校准集（起始点也可以通过 start 和 start_format 配置）。然后，将长度为 forecast_horizon 的下一个预测在此校准集上进行校准。接着，校准集的结束点向前移动 stride 个时间步长，重复此过程。

默认情况下，当 last_points_only=True 时，此方法返回一个时间序列（当 series 也是序列时，返回一个时间序列序列），该序列由每个校准历史预测的最后一个点组成。因此，此时间序列的频率将是 series.freq * stride。如果 last_points_only=False，则将返回一个列表（或列表序列），其中包含所有长度为 forecast_horizon、频率为 series.freq 的校准历史预测。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）过去观测的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）未来已知的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

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

• num_samples (int) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 start 超出可能的历史预测时间范围，则会忽略此参数（None 时的默认行为）并从第一个可训练/可预测点开始。

• start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，start 对应于第一个预测点的索引值/标签。如果值不在 series 的索引中，将引发错误。默认值：'value'。

• stride (int) – 两次连续预测之间的时间步长数。必须是 cal_stride（在模型创建时设置）的整数倍，且 >=cal_stride。

• retrain (Union[bool, int, Callable[…, bool]]) – 共形模型当前忽略此参数。

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

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

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

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

• predict_likelihood_parameters (bool) – 如果设置为 True，则直接生成分位数预测。仅支持 num_samples = 1。

• 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]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

返回类型

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

返回

• TimeSeries – 对于单个 series 且 last_points_only=True 的单个历史预测：它仅包含所有历史预测中步长为 forecast_horizon 的预测结果。

• TimeSeries 列表 – 以下情况下的历史预测列表：

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

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

• TimeSeries 列表的列表 – 对于一个 series 序列且 last_points_only=False 的历史预测列表的列表。对于每个序列和历史预测，它都包含整个范围 forecast_horizon。外部列表对应于输入序列中提供的系列，内部列表包含每个系列的历史预测。

property likelihood: Likelihood

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

返回类型

Likelihood

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

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

参数

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

• pl_trainer_kwargs (Optional[dict, None]) –

  仅当底层预测模型是 TorchForecastingModel 时有效。可选地，一组 kwargs 用于创建一个新的 Lightning Trainer，以配置模型用于下游任务（例如预测）。一些示例包括指定批处理大小或将模型移动到 CPU/GPU(s)。请查阅 Lightning Trainer 文档，了解更多关于支持的 kwargs 信息。

• **kwargs –

  仅当底层预测模型是 TorchForecastingModel 时有效。传递给 PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法的额外 kwargs。更多信息，请阅读 官方文档。

返回类型

ConformalModel

property min_train_samples: int

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

返回类型

int

property model_params: dict

返回类型

dict

property output_chunk_length: Optional[int]

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

返回类型

Optional[int, None]

property output_chunk_shift: int

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

返回类型

int

predict(n, series=None, past_covariates=None, future_covariates=None, num_samples=1, verbose=False, predict_likelihood_parameters=False, show_warnings=True, **kwargs)

预测 series 结束后的 n 个时间步长的校准分位数区间（或从校准区间中抽样）。

重要的是，用于预测的输入序列应对应于一个校准集——一个与用于训练底层预测 model 的序列不同的集合。

由于它是一个概率模型，您可以通过两种方式生成预测结果

• 直接预测校准后的分位数区间：将参数 predict_likelihood_parameters=True 和 num_samples=1 传递给预测方法。

• 从校准后的分位数区间预测随机样本：将参数 predict_likelihood_parameters=False 和 num_samples>>1 传递给预测方法。

在底层，为范围 n 中的每个步骤生成一个校准预测/预报的简化工作流程如下（注意：cal_length 和 cal_stride 可以在模型创建时设置）

• 提取校准集：每个共形预测的校准集会自动从输入序列相对于预测起始点的最新历史数据中提取。要考虑的校准示例数量（预测误差 / 非一致性分数）可以在创建模型时通过参数 cal_length 定义。请注意，当使用 cal_stride>1 时，需要更长的历史数据，因为校准示例是通过带有步长的历史预测生成的。

• 在校准集上（使用预测模型）以 cal_stride 步长生成历史预测。

• 计算这些历史预测的误差/非一致性分数（特定于每个共形模型）

• 从误差/非一致性分数计算分位数（使用在模型创建时通过参数 quantiles 设置的期望分位数）。

• 计算共形预测：使用这些分位数，为预测模型的预测结果添加校准后的区间（或调整现有区间）。

参数

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

• series (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个序列或序列的序列，表示目标序列的历史，其未来将被预测。将使用此序列的过去数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）过去观测的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）未来已知的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• num_samples (int) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

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

• predict_likelihood_parameters (bool) – 如果设置为 True，则直接生成分位数预测。仅支持 num_samples = 1。

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

• **kwargs – 可选的关键字参数，将传递给底层预测模型的 predict() 和 historical_forecasts() 方法。

返回

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

返回类型

Union[TimeSeries, Sequence[TimeSeries]]

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

计算模型在（可能多个）series 上的历史预测所产生的残差。

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

此方法按顺序执行以下操作：

• 使用预先计算的 historical_forecasts 或计算每个序列的历史预测（更多详细信息参见 historical_forecasts()）。历史预测的生成方式可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 进行配置。

• 对历史预测和 series 之间按分量/列和时间步长计算“每个时间步长”的 metric 进行回测（更多详细信息参见 backtest()）。默认情况下，使用残差 err()（误差）作为 metric。

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

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

注意事项

Darts 有几个评估概率预测的指标。对于共形模型，我们推荐使用“每个时间步长”的分位数区间指标（参见 此处）。您可以通过设置 metric_kwargs={‘q_interval’: my_intervals} 来指定要评估的区间。要检查您的共形模型 my_model 使用的所有区间，您可以设置 {'q_interval': my_model.q_interval}。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• 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) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 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]]) – 共形模型当前忽略此参数。

• 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，则直接生成分位数预测。仅支持 num_samples = 1。

• 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’，用于 scaled metrics 的 ‘m’ 等。仅当参数存在于相应的指标签名中时才会传递。忽略归约参数 “series_reduction”, “component_reduction”, “time_reduction”，以及 scaled metrics（例如 mase, rmsse 等）的参数 ‘insample’，因为它们在内部处理。

• fit_kwargs (Optional[dict[str, Any], None]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

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

返回类型

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

返回

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

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

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

save(path=None, clean=False, **pkl_kwargs)

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

此外，如果 self.model 是一个 TorchForecastingModel，还会存储两个文件。

保存和加载 ConformalNaiveModel 的示例

from darts.datasets import AirPassengersDataset
from darts.models import ConformalNaiveModel, LinearRegressionModel

series = AirPassengersDataset().load()
forecasting_model = LinearRegressionModel(lags=4).fit(series)

model = ConformalNaiveModel(
    model=forecasting_model,
    quantiles=[0.1, 0.5, 0.9],
)

model.save("my_model.pkl")
model_loaded = ConformalNaiveModel.load("my_model.pkl")

参数

• path (Union[str, PathLike, BinaryIO, None]) – 保存集成模型当前状态的路径或文件句柄。如果未指定路径，集成模型将自动保存为 "{ConformalNaiveModel}_{YYYY-mm-dd_HH_MM_SS}.pkl"。如果预测模型是 TorchForecastingModel，则两个文件（模型对象和检查点）将保存为 "{path}.{ModelClass}.pt" 和 "{path}.{ModelClass}.ckpt"。

• clean (bool) –

  是否存储模型的清理版本。如果为 True，则移除训练序列和协变量。如果底层预测 model 是一个 TorchForecastingModel，还会额外移除所有 Lightning Trainer 相关的参数。

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

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

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

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

property supports_likelihood_parameter_prediction: bool

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

返回类型

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

property supports_multivariate: bool

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

返回类型

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

property supports_optimized_historical_forecasts: bool

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

返回类型

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

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

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

property supports_probabilistic_prediction: bool

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

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

返回类型

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

property supports_sample_weight: bool

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

返回类型

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

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

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

property supports_transferable_series_prediction: bool

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

返回类型

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

untrained_model()

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

property uses_future_covariates: bool

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

返回类型

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

property uses_past_covariates: bool

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

返回类型

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

property uses_static_covariates: bool

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

返回类型

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

class darts.models.forecasting.conformal_models.ConformalQRModel(model, quantiles, symmetric=True, cal_length=None, cal_stride=1, cal_num_samples=500, random_state=None)

Bases: ConformalModel

对称化分位数回归模型。

一种概率模型，用于校准来自预训练概率全局预测模型的分位数预测。它不需要训练，可以直接使用底层训练好的预测模型生成校准后的预测。它支持两种对称模式：

• symmetric=True:

  • 下限和上限分位数预测以相同的幅度进行校准。

  • 不一致分数：使用指标 incs_qr(symmetric=True)（参见分位数回归的不一致分数 incs_qr()）来计算标定集上的不一致分数。

• symmetric=False

  • 下限和上限分位数预测分别进行校准。

  • 不一致分数：使用指标 incs_qr(symmetric=False)（参见分位数回归的不一致分数 incs_qr()）来分别计算上限和下限的不一致分数。

由于它是一个概率模型，您可以通过两种方式生成预测结果（调用 predict(), historical_forecasts() 等方法时）

• 直接预测校准后的分位数区间：将参数 predict_likelihood_parameters=True 和 num_samples=1 传递给预测方法。

• 从校准后的分位数区间预测随机样本：将参数 predict_likelihood_parameters=False 和 num_samples>>1 传递给预测方法。

共形模型可以应用于 Darts 中的任何全局预测模型，只要模型已经拟合过。通常，模型生成校准后的预测的流程如下：

• 提取校准集：每个共形预测的校准集会自动从输入序列相对于预测起始点的最新历史数据中提取。要考虑的校准示例数量（预测误差 / 非一致性分数）可以在创建模型时通过参数 cal_length 定义。请注意，当使用 cal_stride>1 时，需要更长的历史数据，因为校准示例是通过带有步长的历史预测生成的。

• 以步长 cal_stride 在标定集上生成历史预测（分位数预测，使用预测模型）。

• 计算这些历史分位数预测的误差/不一致分数（如上定义）。

• 从误差/非一致性分数计算分位数（使用在模型创建时通过参数 quantiles 设置的期望分位数）。

• 计算一致预测：使用这些分位数，校准预测模型预测结果中的预测分位数。

注意事项

• 计算 historical_forecasts()、backtest()、residuals() 等方法时，上述流程应用于每个预测（预测模型的历史预测仅生成一次以提高效率）。

• 对于多步预测，上述流程对预测范围中的每个步骤分别应用。

参数

• model (GlobalForecastingModel) –

  一个预训练的全局预测模型。模型列表参见 此处。

• quantiles (list[float]) – 要使用的围绕中位数 q=0.5 的分位数列表。例如，分位数 [0.1, 0.2, 0.5, 0.8, 0.9] 对应于两个区间，分别在中位数（模型预测）周围覆盖 (0.9 - 0.1) = 80% 和 (0.8 - 0.2) = 60%。

• symmetric (bool) – 是否使用对称不一致分数。如果为 True，则使用对称指标 incs_qr(…, symmetric=True)（参见 incs_qr()）来计算不一致分数。如果为 False，则使用非对称指标 incs_qr(…, symmetric=False)，分别计算下限和上限分位数区间界限的单独分数。

• cal_length (Optional[int, None]) – 对于每个共形预测（以及预测范围中的每个步骤），用于校准的过去预测误差/非一致性分数的数量。如果为 None，则考虑所有分数。

• cal_stride (int) – 在校准集上计算历史预测和非一致性分数时应用的步长。实际的共形预测可以在下游任务中（例如历史预测、回测等）通过参数 stride 设置不同的步长。

• cal_num_samples (int) – 为每个校准预测生成的样本数量（如果 model 是概率预测模型）。非一致性分数是基于这些预测的分位数（使用 quantiles）计算的。对于确定性模型，使用 1 个样本。实际的共形预测可以在下游任务中（例如 predict、historical forecasts 等）通过参数 num_samples 设置不同的样本数量。

• random_state (Optional[int, None]) – 控制不同运行中概率共形预测（样本生成）的随机性。

属性

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

model_params

方法

backtest(series[, past_covariates, ...])	计算模型在（可能多个）series 上的历史预测所产生的误差值。
fit(series[, past_covariates, future_covariates])	在（可能多个）序列上拟合/训练底层预测模型。
generate_fit_encodings(series[, ...])	生成用于模型拟合的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
generate_fit_predict_encodings(n, series[, ...])	生成用于训练和推理/预测的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
generate_predict_encodings(n, series[, ...])	生成用于推理/预测集的协变量编码，并返回一个元组，包含过去和未来协变量序列，以及原始和编码后的协变量堆叠在一起的结果。
gridsearch(parameters, series[, ...])	使用网格搜索在给定集合中找到最佳超参数。
historical_forecasts(series[, ...])	通过模拟在提供的（可能多个）series 的整个历史中不同时间点的预测来生成校准后的历史预测。
load(path[, pl_trainer_kwargs])	从给定路径或文件句柄加载模型。
predict(n[, series, past_covariates, ...])	预测 series 结束后的 n 个时间步长的校准分位数区间（或从校准区间中抽样）。
residuals(series[, past_covariates, ...])	计算模型在（可能多个）series 上的历史预测所产生的残差。
save([path, clean])	将共形模型保存到给定路径或文件句柄。
untrained_model()	返回使用相同参数创建的新的（未训练的）模型实例。

backtest(series, past_covariates=None, future_covariates=None, historical_forecasts=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=False, metric=<function mape>, reduction=<function mean>, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, metric_kwargs=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

计算模型在（可能多个）series 上的历史预测所产生的误差值。

如果提供了 historical_forecasts，则直接对所有预测值和实际值评估指标（由 metric 函数给出）。必须传递用于生成历史预测的相同 series 和 last_points_only 值。最后，该方法返回对所有这些指标分数的 Optional 汇总（默认为平均值）。

如果 historical_forecasts 为 None，则它首先使用以下给定参数生成历史预测（更多信息请参见 ConformalModel.historical_forecasts()），然后按上述方式进行评估。

指标可以通过 metric_kwargs 进一步自定义（例如，控制跨组件、时间步长、多个序列的聚合，或分位数指标所需的其他参数如 q 等）。

注意事项

Darts 有几种评估概率预测的指标。对于共形模型，我们建议使用分位数区间指标（参见此处）。您可以通过设置 metric_kwargs={‘q_interval’: my_intervals} 指定要评估的区间。要检查您的共形模型 my_model 使用的所有区间，可以设置 {'q_interval': my_model.q_interval}。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• 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) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 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]]) – 共形模型当前忽略此参数。

• 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，则直接生成分位数预测。仅支持 num_samples = 1。

• 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]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

返回类型

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

返回

• float – 单个单/多变量序列、单个 metric 函数和使用 last_points_only=True 生成的 historical_forecasts 的单个回测分数。

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

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

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

  • 单个 metric 函数，historical_forecasts 生成时使用 last_points_only=False 且回溯测试 reduction=None。输出形状为 (N个预测, *)。

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

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

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

• property considers_static_covariates: bool

property considers_static_covariates: bool

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

返回类型

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

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

参见下面的示例。

如果模型未拟合：

目标（仅限 RegressionModels）：则第一个元素应为 None。

• 过去协变量：则第三和第四个元素应为 None。

• 未来协变量：则第五和第六个元素应为 None。

• 使用过去或未来协变量的模型和/或最小目标滞后和最大目标滞后可能不同于 -1 和 0 的模型应覆盖此方法。

最大目标滞后（第二个值）不能为 None，且总是大于或等于 0。

注意事项

tuple[Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], Optional[int, None], int, Optional[int, None]]

示例

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

返回类型

fit(series, past_covariates=None, future_covariates=None, **kwargs)

fit(series, past_covariates=None, future_covariates=None, **kwargs)

在（可能多个）序列上拟合/训练底层预测模型。

共形模型不需要调用 fit()，因为它们使用预训练的全局预测模型。您可以直接调用 predict()。此外，请确保 predict() 中使用的输入序列对应于校准集，而不是与 fit() 训练时使用的序列相同。

注意事项

series (Union[TimeSeries, Sequence[TimeSeries]]) – 一个或多个目标时间序列。模型将训练来预测这些时间序列。序列可以是单变量或多变量，但如果提供多个序列，它们必须具有相同数量的组件。

参数

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个过去观测的协变量时间序列。这些时间序列不会被预测，但可以被某些模型用作输入。协变量可以是单变量或多变量，但如果提供多个协变量，它们必须具有相同数量的组件。如果提供了 past_covariates，其序列数量必须与 series 相同。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个或多个未来已知的协变量时间序列。这些时间序列不会被预测，但可以被某些模型用作输入。协变量可以是单变量或多变量，但如果提供多个协变量，它们必须具有相同数量的组件。如果提供了 future_covariates，其序列数量必须与 series 相同。

• **kwargs – 可选关键字参数，将传递给底层预测模型的 fit() 方法。

• 拟合的模型。

返回

self

返回类型

generate_fit_encodings(series, past_covariates=None, future_covariates=None)

generate_fit_encodings(series, past_covariates=None, future_covariates=None)

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)

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)

n (int) – 打算用于预测的、在 series 结束后的预测时间步长数量。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于训练和预测的目标值序列或序列的序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，打算用于训练和预测的过去观测协变量序列。维度必须与训练时使用的协变量维度匹配。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，打算用于预测的未来已知协变量序列。维度必须与训练时使用的协变量维度匹配。

• generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)

返回

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

返回类型

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)

generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)

series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于预测的目标值序列或序列的序列。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 打算用于训练和预测的目标值序列或序列的序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，打算用于预测的过去观测协变量序列。维度必须与训练时使用的协变量维度匹配。

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

• generate_predict_encodings(n, series, past_covariates=None, future_covariates=None)

返回

Tuple[Union[TimeSeries, Sequence[TimeSeries]], Union[TimeSeries, Sequence[TimeSeries]]]

返回类型

generate_fit_predict_encodings(n, series, past_covariates=None, future_covariates=None)

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)

使用网格搜索在给定集合中找到最佳超参数。

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

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

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

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

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

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

model_class – 要针对“series”调整的 ForecastingModel 子类。

参数

• model_class – ForecastingModel 子类，用于对 ‘series’ 进行调优。

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

• series (TimeSeries) – 用作输入和训练目标的 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。

  注意：如果模型使用 shifted output (output_chunk_shift > 0)，则第一个预测点也会

  向未来偏移 output_chunk_shift 个点。

  注意：如果 start 超出可能的历史预测时间范围，则会忽略该参数

  (即使用 None 时的默认行为)，并从第一个可训练/可预测点开始。

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

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

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

• val_series (Optional[TimeSeries, None]) – 在分割模式下用于验证的 TimeSeries 实例。如果提供，该序列必须紧接在 series 的末尾之后开始；以便进行准确的预测比较。

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

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

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

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

• verbose – 是否打印进度信息。

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

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

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

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

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

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

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

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

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

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

返回

一个元组，包含一个从未训练过的 model_class 实例（由表现最佳的超参数创建），以及一个包含这些最佳超参数的字典，以及最佳超参数的指标分数。

返回类型

ForecastingModel, Dict, float

historical_forecasts(series, past_covariates=None, future_covariates=None, forecast_horizon=1, num_samples=1, train_length=None, start=None, start_format='value', stride=1, retrain=True, overlap_end=False, last_points_only=True, verbose=False, show_warnings=True, predict_likelihood_parameters=False, enable_optimization=True, data_transformers=None, fit_kwargs=None, predict_kwargs=None, sample_weight=None)

通过模拟在提供的（可能是多个）series 整个历史中不同时间点的预测，生成经过校准的历史预测。这个过程包括回溯性地将模型应用于不同的时间步长，就像在那些特定时刻进行实时预测一样。这允许评估模型在整个序列持续时间内的性能，从而深入了解其在不同历史时期的预测准确性和鲁棒性。

目前，共形模型仅支持预训练历史预测模式（retrain=False）。参数 retrain 和 train_length 将被忽略。

预训练模式： 首先，使用底层预训练的全局预测模型生成所有历史预测（更多信息参见 ForecastingModel.historical_forecasts()）。然后，它通过从历史预测的开始处扩展或使用长度为 cal_length 的固定长度滑动窗口，重复构建一个校准集（起始点也可以通过 start 和 start_format 配置）。然后，将长度为 forecast_horizon 的下一个预测在此校准集上进行校准。接着，校准集的结束点向前移动 stride 个时间步长，重复此过程。

默认情况下，当 last_points_only=True 时，此方法返回一个时间序列（当 series 也是序列时，返回一个时间序列序列），该序列由每个校准历史预测的最后一个点组成。因此，此时间序列的频率将是 series.freq * stride。如果 last_points_only=False，则将返回一个列表（或列表序列），其中包含所有长度为 forecast_horizon、频率为 series.freq 的校准历史预测。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）过去观测的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）未来已知的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

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

• num_samples (int) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 start 超出可能的历史预测时间范围，则会忽略此参数（None 时的默认行为）并从第一个可训练/可预测点开始。

• start_format (Literal[‘position’, ‘value’]) – 定义 start 的格式。如果设置为 'position'，start 对应于第一个预测点的索引位置，范围为 (-len(series), len(series) - 1)。如果设置为 'value'，start 对应于第一个预测点的索引值/标签。如果值不在 series 的索引中，将引发错误。默认值：'value'。

• stride (int) – 两次连续预测之间的时间步长数。必须是 cal_stride（在模型创建时设置）的整数倍，且 >=cal_stride。

• retrain (Union[bool, int, Callable[…, bool]]) – 共形模型当前忽略此参数。

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

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

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

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

• predict_likelihood_parameters (bool) – 如果设置为 True，则直接生成分位数预测。仅支持 num_samples = 1。

• 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]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

返回类型

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

返回

• TimeSeries – 对于单个 series 且 last_points_only=True 的单个历史预测：它仅包含所有历史预测中步长为 forecast_horizon 的预测结果。

• TimeSeries 列表 – 以下情况下的历史预测列表：

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

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

• TimeSeries 列表的列表 – 对于一个 series 序列且 last_points_only=False 的历史预测列表的列表。对于每个序列和历史预测，它都包含整个范围 forecast_horizon。外部列表对应于输入序列中提供的系列，内部列表包含每个系列的历史预测。

property likelihood: Likelihood

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

返回类型

Likelihood

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

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

参数

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

• pl_trainer_kwargs (Optional[dict, None]) –

  仅当底层预测模型是 TorchForecastingModel 时有效。可选地，一组 kwargs 用于创建一个新的 Lightning Trainer，以配置模型用于下游任务（例如预测）。一些示例包括指定批处理大小或将模型移动到 CPU/GPU(s)。请查阅 Lightning Trainer 文档，了解更多关于支持的 kwargs 信息。

• **kwargs –

  仅当底层预测模型是 TorchForecastingModel 时有效。传递给 PyTorch Lightning 的 LightningModule.load_from_checkpoint() 方法的额外 kwargs。更多信息，请阅读 官方文档。

返回类型

ConformalModel

property min_train_samples: int

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

返回类型

int

property model_params: dict

返回类型

dict

property output_chunk_length: Optional[int]

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

返回类型

Optional[int, None]

property output_chunk_shift: int

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

返回类型

int

predict(n, series=None, past_covariates=None, future_covariates=None, num_samples=1, verbose=False, predict_likelihood_parameters=False, show_warnings=True, **kwargs)

预测 series 结束后的 n 个时间步长的校准分位数区间（或从校准区间中抽样）。

重要的是，用于预测的输入序列应对应于一个校准集——一个与用于训练底层预测 model 的序列不同的集合。

由于它是一个概率模型，您可以通过两种方式生成预测结果

• 直接预测校准后的分位数区间：将参数 predict_likelihood_parameters=True 和 num_samples=1 传递给预测方法。

• 从校准后的分位数区间预测随机样本：将参数 predict_likelihood_parameters=False 和 num_samples>>1 传递给预测方法。

在底层，为范围 n 中的每个步骤生成一个校准预测/预报的简化工作流程如下（注意：cal_length 和 cal_stride 可以在模型创建时设置）

• 提取校准集：每个共形预测的校准集会自动从输入序列相对于预测起始点的最新历史数据中提取。要考虑的校准示例数量（预测误差 / 非一致性分数）可以在创建模型时通过参数 cal_length 定义。请注意，当使用 cal_stride>1 时，需要更长的历史数据，因为校准示例是通过带有步长的历史预测生成的。

• 在校准集上（使用预测模型）以 cal_stride 步长生成历史预测。

• 计算这些历史预测的误差/非一致性分数（特定于每个共形模型）

• 从误差/非一致性分数计算分位数（使用在模型创建时通过参数 quantiles 设置的期望分位数）。

• 计算共形预测：使用这些分位数，为预测模型的预测结果添加校准后的区间（或调整现有区间）。

参数

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

• series (Union[TimeSeries, Sequence[TimeSeries], None]) – 一个序列或序列的序列，表示目标序列的历史，其未来将被预测。将使用此序列的过去数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）过去观测的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选，对于 series 中的每个输入时间序列，提供（一个或一系列）未来已知的协变量时间序列。它们的维度必须与训练时使用的过去协变量维度匹配。将使用此序列进行校准。

• num_samples (int) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

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

• predict_likelihood_parameters (bool) – 如果设置为 True，则直接生成分位数预测。仅支持 num_samples = 1。

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

• **kwargs – 可选的关键字参数，将传递给底层预测模型的 predict() 和 historical_forecasts() 方法。

返回

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

返回类型

Union[TimeSeries, Sequence[TimeSeries]]

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

计算模型在（可能多个）series 上的历史预测所产生的残差。

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

此方法按顺序执行以下操作：

• 使用预先计算的 historical_forecasts 或计算每个序列的历史预测（更多详细信息参见 historical_forecasts()）。历史预测的生成方式可以通过参数 num_samples、train_length、start、start_format、forecast_horizon、stride、retrain、last_points_only、fit_kwargs 和 predict_kwargs 进行配置。

• 对历史预测和 series 之间按分量/列和时间步长计算“每个时间步长”的 metric 进行回测（更多详细信息参见 backtest()）。默认情况下，使用残差 err()（误差）作为 metric。

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

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

注意事项

Darts 有几个评估概率预测的指标。对于共形模型，我们推荐使用“每个时间步长”的分位数区间指标（参见 此处）。您可以通过设置 metric_kwargs={‘q_interval’: my_intervals} 来指定要评估的区间。要检查您的共形模型 my_model 使用的所有区间，您可以设置 {'q_interval': my_model.q_interval}。

参数

• series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于连续计算历史预测的（一个或一系列）目标时间序列。将使用此序列的历史数据进行校准。该序列不应与用于训练预测模型的序列有任何重叠。

• 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) – 使用分位数之间的线性插值从校准后的分位数预测中采样的次数。值越大，样本分布越接近校准后的分位数预测。

• train_length (Optional[int, None]) – 共形模型当前忽略此参数。

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

  可选，计算预测的第一个时间点。此参数支持：int、pandas.Timestamp 和 None。如果是 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）

  注意：如果模型使用移位输出（output_chunk_shift > 0），则第一个预测点也会向未来移位 output_chunk_shift 个点。注意：如果 start 生成的时间超出 series 的时间索引范围，则会引发 ValueError。注意：如果 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]]) – 共形模型当前忽略此参数。

• 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，则直接生成分位数预测。仅支持 num_samples = 1。

• 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’，用于 scaled metrics 的 ‘m’ 等。仅当参数存在于相应的指标签名中时才会传递。忽略归约参数 “series_reduction”, “component_reduction”, “time_reduction”，以及 scaled metrics（例如 mase, rmsse 等）的参数 ‘insample’，因为它们在内部处理。

• fit_kwargs (Optional[dict[str, Any], None]) – 共形模型当前忽略此参数。

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

• sample_weight (Union[TimeSeries, Sequence[TimeSeries], str, None]) – 共形模型当前忽略此参数。

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

返回类型

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

返回

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

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

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

save(path=None, clean=False, **pkl_kwargs)

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

此外，如果 self.model 是一个 TorchForecastingModel，还会存储两个文件。

保存和加载 ConformalNaiveModel 的示例

from darts.datasets import AirPassengersDataset
from darts.models import ConformalNaiveModel, LinearRegressionModel

series = AirPassengersDataset().load()
forecasting_model = LinearRegressionModel(lags=4).fit(series)

model = ConformalNaiveModel(
    model=forecasting_model,
    quantiles=[0.1, 0.5, 0.9],
)

model.save("my_model.pkl")
model_loaded = ConformalNaiveModel.load("my_model.pkl")

参数

• path (Union[str, PathLike, BinaryIO, None]) – 保存集成模型当前状态的路径或文件句柄。如果未指定路径，集成模型将自动保存为 "{ConformalNaiveModel}_{YYYY-mm-dd_HH_MM_SS}.pkl"。如果预测模型是 TorchForecastingModel，则两个文件（模型对象和检查点）将保存为 "{path}.{ModelClass}.pt" 和 "{path}.{ModelClass}.ckpt"。

• clean (bool) –

  是否存储模型的清理版本。如果为 True，则移除训练序列和协变量。如果底层预测 model 是一个 TorchForecastingModel，还会额外移除所有 Lightning Trainer 相关的参数。

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

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

返回类型

None

property supports_future_covariates: bool

模型是否支持未来协变量

返回类型

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

property supports_likelihood_parameter_prediction: bool

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

返回类型

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

property supports_multivariate: bool

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

返回类型

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

property supports_optimized_historical_forecasts: bool

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

返回类型

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

property supports_past_covariates: bool

模型是否支持过去协变量

返回类型

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

property supports_probabilistic_prediction: bool

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

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

返回类型

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

property supports_sample_weight: bool

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

返回类型

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

property supports_static_covariates: bool

模型是否支持静态协变量

返回类型

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

property supports_transferable_series_prediction: bool

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

返回类型

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

untrained_model()

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

property uses_future_covariates: bool

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

返回类型

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

property uses_past_covariates: bool

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

返回类型

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

property uses_static_covariates: bool

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

返回类型

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

上一个

CatBoost 模型

下一个

D-Linear