darts.utils.data.tabularization.add_static_covariates_to_lagged_data(features, target_series, uses_static_covariates=True, last_shape=None)

为 RegressionModels 的特征表添加静态协变量。如果 uses_static_covariates=True，则在 fit() 和 predict() 中使用的所有目标序列必须具有相同维度的静态协变量。否则，将不考虑静态协变量。

静态协变量按照以下约定添加到滞后特征的右侧：对于一个 2 分量的序列，每个分量有 2 个静态协变量 -> scov_1_comp_1 | scov_1_comp_2 | scov_2_comp_1 | scov_2_comp_2

参数

• features (Union[ndarray, Sequence[ndarray]]) – 将添加静态协变量的特征 numpy 数组。可以是单个特征矩阵，也可以是特征矩阵的 Sequence；在后一种情况下，静态协变量将添加到此 Sequence 中的每个特征矩阵。

• target_series (Union[TimeSeries, Sequence[TimeSeries]]) – 从中读取静态协变量的目标序列。

• uses_static_covariates (bool) – 模型是否使用/期望静态协变量。如果 True，则强制要求所有目标序列的静态协变量必须具有相同的形状。

• last_shape (Optional[tuple[int, int], None]) – 可选参数，静态协变量的最后观察到的形状。在拟合之前或当 uses_static_covariates 为 False 时，此值为 None。

返回值

附加了静态协变量列的特征数组。如果 features 输入作为 np.array 的 Sequence 传递，则也返回一个 Sequence；如果 features 作为 np.array 传递，则返回一个 np.array。last_shape 是静态协变量的形状。

返回类型

(features, last_shape)

darts.utils.data.tabularization.create_lagged_component_names(target_series=None, past_covariates=None, future_covariates=None, lags=None, lags_past_covariates=None, lags_future_covariates=None, output_chunk_length=1, concatenate=True, use_static_covariates=False)

用于检索使用 create_lagged_data() 创建的特征和标签数组名称的辅助函数。特征的顺序如下

沿着 n_lagged_features 轴，X 具有以下结构

滞后目标 | 滞后过去协变量 | 滞后未来协变量 | 静态协变量

对于 *_lags=[-2,-1] 和 *_series.n_components = 2 (滞后在所有分量中共享)，每个 lagged_* 具有以下结构（按滞后分组）

comp0_*_lag-2 | comp1_*_lag-2 | comp0_*_lag_-1 | comp1_*_lag-1

对于 *_lags={‘comp0’:[-3, -1], ‘comp1’:[-5, -3]} 和 *_series.n_components = 2 (分量特定滞后)，每个 lagged_* 具有以下结构（按滞后排序，然后按分量排序）

comp1_*_lag-5 | comp0_*_lag-3 | comp1_*_lag_-3 | comp0_*_lag-1

对于静态协变量（作用于 2 个目标分量的 2 个静态协变量）

cov0_*_target_comp0 | cov0_*_target_comp1 | cov1_*_target_comp0 | cov1_*_target_comp1

沿着 n_lagged_labels 轴，y 具有以下结构（对于 output_chunk_length=4 和 target_series.n_components=2）

comp0_target_lag0 | comp1_target_lag0 | … | comp0_target_lag3 | comp1_target_lag3

注意：将仅使用 target_series、past_covariates、future_covariates 和 static_covariates 中第一个序列的分量名称。

目标、过去和未来协变量滞后的命名约定为："{name}_{type}_lag{i}"，其中

• {name} 为（第一个）序列的分量名称

• {type} 为特征类型，是 “target”, “pastcov”, 和 “futcov” 之一

• {i} 为滞后值

静态协变量的命名约定为："{name}_statcov_target_{comp}"，其中

• {name} 为（第一个）序列的静态协变量名称

• {comp} 为静态协变量作用于的（第一个）目标分量名称。如果静态

  协变量全局作用于一个多元目标序列，则显示“global”。

标签的命名约定为："{name}_target_hrz{i}"，其中

• {name} 为（第一个）序列的分量名称

• {i} 为预测范围中的步长

返回类型

tuple[list[list[str]], list[list[str]]]

返回值

• features_cols_name – 由 create_lagged_data() 生成的 X 数组中滞后特征的名称，格式为 List[str]。如果 concatenate=True，则也包含 y 数组（在右侧）的列名。

• labels_cols_name –

  由 create_lagged_data() 生成的 y 数组中滞后特征的名称

  格式为 List[str]。

另请参阅

tabularization.create_lagged_data

生成滞后特征和标签为数组（列表）。

darts.utils.data.tabularization.create_lagged_data(target_series=None, past_covariates=None, future_covariates=None, lags=None, lags_past_covariates=None, lags_future_covariates=None, output_chunk_length=1, output_chunk_shift=0, uses_static_covariates=True, last_static_covariates_shape=None, max_samples_per_ts=None, multi_models=True, check_inputs=True, use_moving_windows=True, is_training=True, concatenate=True, sample_weight=None, show_warnings=True)

当 is_training = True 时，创建特征数组 X 和标签数组 y 以训练滞后变量回归模型（例如 sklearn 模型）；或者，当 is_training = False 时，创建特征数组 X 以从已训练的回归模型生成一系列预测。在这两种情况下，还会返回一个对应于每个生成观测值的时间索引列表。

注意

建议不要直接调用 create_lagged_data，而是

• 如果希望创建 X 和 y 数组以训练回归模型，应调用 create_lagged_training_data。— 如果希望创建从已训练回归模型生成预测所需的 X 数组，应调用 create_lagged_prediction_data。

to train a regression model. - create_lagged_prediction_data be called if one wishes to create the X array required to generate a prediction from an already-trained regression model.

这是因为尽管这两个函数都只是 create_lagged_data 的包装函数，但它们的调用签名比 create_lagged_data 更易于理解。例如，create_lagged_prediction_data 不接受 output_chunk_length 和 multi_models 作为输入，因为在构建预测数据时不使用这些输入。类似地，create_lagged_prediction_data 只返回 X 和 times 作为输出，而不是返回 y 为 None 以及 X 和 times。

X 数组由最多三个独立时序的滞后值构建而成。

1. target_series，包含我们试图预测的值。使用其预测目标的先前值的回归模型被称为 自回归 模型；有关自回归时序模型的更多详细信息，请参阅 [1]。2. 过去协变量序列，包含未来未知的 值。然而，与目标序列不同，过去协变量 不是 由回归模型预测的。3. 未来协变量（也称“外生”协变量）序列，包含未来已知的值，甚至超出 target_series 和 past_covariates 中的数据。

有关目标、过去和未来协变量的更详细讨论，请参阅 [2]。相反，y 仅由 target_series 的滞后值组成。

X 的形状为

X.shape = (n_observations, n_lagged_features, n_samples),

其中 n_observations 等于所有指定序列共享的时间点数量，或 max_samples_per_ts，取两者中较小者。y 的形状为

y.shape = (n_observations, output_chunk_length, n_samples),

如果 multi_models = True，否则

y.shape = (n_observations, 1, n_samples).

沿着 n_lagged_features 轴，X 具有以下结构（对于 *_lags=[-2,-1] 和 *_series.n_components = 2）

滞后目标 | 滞后过去协变量 | 滞后未来协变量

其中每个 lagged_* 具有以下结构

lag_-2_comp_1_* | lag_-2_comp_2_* | lag_-1_comp_1_* | lag_-1_comp_2_*

沿着 n_lagged_labels 轴，y 具有以下结构（对于 output_chunk_length=4 和 target_series.n_components=2）

lag_+0_comp_1_target | lag_+0_comp_2_target | … | lag_+3_comp_1_target | lag_+3_comp_2_target

lags 和 lags_past_covariates 必须只包含小于或等于 -1 的值。换句话说，不能使用这些序列在时间 t 的值来预测目标序列在同一时间 t 的值；这是因为根据定义，在预测时无法获得 target_series 和 past_covariates 在时间 t 的值。相反，由于 future_covariates 的值在未来是已知的，lags_future_covariates 可以包含负、正和/或零滞后值（即，我们 可以 使用 future_covariates 在时间 t 或之后的值来预测 target_series 在时间 t 的值）。

构建 X 和 y 的具体方法取决于所有指定时序是否具有相同的频率。

• 如果所有指定时序具有相同的频率，则使用 strided_moving_window 来提取

每个时序的连续时间块；然后从每个窗口中提取滞后变量。— 如果所有指定时序 不 具有相同的频率，则首先使用 find_shared_times 查找所有三个时序共有的时间，然后通过将这些共有时间的时间索引偏移请求的滞后量来提取滞后特征。

在可以有效应用的情况下，“移动窗口”方法预计比“时间交集”方法更快。然而，在仅提取少量滞后量但滞后值之间差异较大的特殊情况（例如 lags = [-1, -1000]）下，“移动窗口”方法预计会消耗更多内存，因为它在实际提取特定请求的滞后值之前，将最大和最小滞后值之间的所有序列值提取为“窗口”。

为了将序列的滞后特征添加到 X，必须同时指定该序列和相应的滞后量；如果仅指定序列而未指定相应的滞后量，则该序列将被忽略且不添加到 X 中。X 和 y 数组是独立地在每个序列的样本维度（即第二个轴）上构建的。

如果提供的序列是随机的（即 series.n_components > 1），则将为每个样本构建一个 X 和 y 数组；对应于每个样本的数组沿着 X 和 y 的第 2 个轴连接在一起。换句话说，create_lagged_data 在 target_series、past_covariates 和 future_covariates 输入的样本轴上进行了向量化。重要的是，如果提供了随机序列，每个序列必须具有相同数量的样本，否则将引发错误。

每个序列输入（即 target_series、past_covariates 和 future_covariates）可以指定为单个 TimeSeries，或指定为 TimeSeries 的 Sequence；然而，指定的序列必须都是相同类型（即，要么都是 TimeSeries，要么都是 Sequence[TimeSeries]）。如果指定了 Sequence[TimeSeries]，则将使用每个 Sequence 中对应的 TimeSeries 构建特征矩阵 X 和标签数组 y（即，使用每个 Sequence 中的第一个 TimeSeries 创建一个 X 和 y，然后使用每个 Sequence 中的第二个 TimeSeries 创建一个 X 和 y，依此类推）。如果 concatenate = True，这些 X 和 y 将沿着第 0 个轴连接；否则，将返回 X 和 y 数组的列表。请注意，即使在 concatenate = True 时，times 仍始终作为 Sequence[pd.Index] 返回。

参数

• target_series (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，用于回归模型预测的序列。如果 is_training = True，则必须指定。可以指定为单个 TimeSeries 或 Sequence[TimeSeries]。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，回归模型将用作输入的过去协变量序列。与 target_series 不同，past_covariates 不是 由回归模型预测的。可以指定为单个 TimeSeries 或 Sequence[TimeSeries]。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – 可选参数，回归模型将用作输入的未来协变量（即外生协变量）序列。可以指定为单个 TimeSeries 或 Sequence[TimeSeries]。

• lags (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作（自回归）特征的目标序列的滞后。如果未指定，则不会向 X 添加自回归特征。每个滞后值都假定为负数（例如，lags = [-3, -1] 将提取与当前值相距 3 个时间步长和 1 个时间步长的 target_series 值）。如果滞后以字典形式提供，则滞后值特定于目标序列中的每个组件。

• lags_past_covariates (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作特征的 past_covariates 的滞后。与 lags 一样，每个滞后值都假定小于或等于 -1。如果滞后以字典形式提供，则滞后值特定于过去协变量序列中的每个组件。

• lags_future_covariates (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作特征的 future_covariates 的滞后。与 lags 和 lags_past_covariates 不同，lags_future_covariates 值可以为正数（即使用时间 t *之后*的值来预测时间 t 的目标）、零（即使用时间 t *当时*的值来预测时间 t 的目标）和/或负数（即使用时间 t *之前*的值来预测时间 t 的目标）。如果 output_chunk_shift > 0，则滞后值相对于偏移的输出块的第一个时间步长。如果滞后以字典形式提供，则滞后值特定于未来协变量序列中的每个组件。

• output_chunk_length (int) – （可选）回归模型要预测的未来时间步长数。如果 is_training = True，则必须指定此参数。

• output_chunk_shift (int) – （可选）将输出块向未来偏移的时间步长数。

• uses_static_covariates (bool) – 模型是否使用/期望静态协变量。如果为 True，则强制所有目标序列的静态协变量必须具有相同的形状。

• last_static_covariates_shape (Optional[tuple[int, int], None]) – （可选）最后观察到的静态协变量的形状。在拟合之前或当 uses_static_covariates 为 False 时，此值为 None。

• max_samples_per_ts (Optional[int, None]) – （可选）用于训练/验证的最大采样数；仅保留最新的采样。理论上，指定较小的 max_samples_per_ts 应能减少计算时间，尤其是在可以生成许多观测值的情况下。

• multi_models (bool) – （可选）指定回归模型是否预测未来的多个时间步长。如果为 True，则假定回归模型预测从时间 t 到 t+output_chunk_length 的所有时间步长。如果为 False，则假定回归模型*仅*预测 t+output_chunk_length 时间步长。如果 is_training = False，则忽略此输入。

• check_inputs (bool) – （可选）指定是否应检查 lags_* 和 series_* 输入的有效性。如果输入已检查过有效性（例如，在类的 __init__ 内部），则应将其设置为 False，否则应设置为 True。

• use_moving_windows (bool) – （可选）指定如果所有提供的序列具有相同的频率，则应使用“滑动窗口”方法来构建 X 和 y。如果 use_moving_windows = False，即使所有提供的序列具有相同的频率，也始终使用“时间交集”方法。一般来说，设置为 True 可以加快表格化速度，但可能会增加内存使用。有关更多详细信息，请参阅注释。

• is_training (bool) – （可选）指定构建的滞后数据是否用于训练回归模型（即 is_training = True），或用于从已训练的回归模型生成预测（即 is_training = False）。如果 is_training = True，则必须指定 target_series 和 output_chunk_length，使用 multi_models 输入，并返回标签数组 y。相反，如果 is_training = False，则无需指定 target_series 和 output_chunk_length，忽略 multi_models 输入，并且返回的 y 值为 None。

• concatenate (bool) – （可选）指定 X 和 y 是否应作为单个 np.ndarray 返回，而不是作为 Sequence[np.ndarray] 返回。如果每个序列输入都指定为 Sequence[TimeSeries] 且 concatenate = False，则 X 和 y 将是列表，其第 i 个元素对应于每个 Sequence[TimeSeries] 输入中第 i 个 TimeSeries 形成的特征矩阵或标签数组。相反，如果在提供 Sequence[TimeSeries] 时 concatenate = True，则 X 和 y 将是沿着第 0 个轴连接每个 TimeSeries 形成的所有特征/标签数组而创建的数组。注意，即使 concatenate = True，times 仍返回为 Sequence[pd.Index]。

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

• show_warnings (bool) – 是否显示警告。

返回类型

tuple[Union[ndarray, Sequence[ndarray]], Union[None, ndarray, Sequence[ndarray]], Sequence[Index], Optional[tuple[int, int], None], Union[ndarray, Sequence[ndarray], None]]

返回值

• X – 构建的特征数组，形状为 (n_observations, n_lagged_features, n_samples)。如果序列输入指定为 Sequence[TimeSeries] 且 concatenate = False，则 X 以 Sequence[np.array] 形式返回；否则，X 以单个 np.array 形式返回。

• y – 构建的标签数组。如果 multi_models = True，则 y 是形状为 (n_observations, output_chunk_length, n_samples) 的数组；相反，如果 multi_models = False，则 y 是形状为 (n_observations, 1, n_samples) 的数组。如果序列输入指定为 Sequence[TimeSeries] 且 concatenate = False，则 y 以 Sequence[np.array] 形式返回；否则，y 以单个 np.array 形式返回。

• times – X 和 y 中每个观测值的时间索引，以 pd.Index 的 Sequence 形式返回。如果序列输入指定为 Sequence[TimeSeries]，则列表的第 i 个元素给出使用每个 Sequence 中第 i 个 TimeSeries 对象形成的那些观测值的时间。否则，如果序列输入指定为 TimeSeries，则唯一元素是使用单个 TimeSeries 输入形成的那些观测值的时间。

• last_static_covariates_shape – 最后观察到的静态协变量的形状。当 uses_static_covariates 为 False 时，此值为 None。

• sample_weight – 要应用于 X 中每个观测值和输出步长 y 的权重，以 np.ndarray 的 Sequence 形式返回。

Raises

• ValueError – 如果指定的时间序列没有共享任何可以构建特征（以及标签，如果 is_training = True）的时间。

• ValueError – 如果未指定任何滞后，或者任何指定的滞后值为非负数。

• ValueError – 如果任何序列太短，无法为请求的滞后和 output_chunk_length 值创建特征和/或标签。

• ValueError – 如果 is_training = True 时未指定 target_series 和/或 output_chunk_length。

• ValueError – 如果提供的序列不共享相同类型的 time_index（例如，target_series 使用 pd.RangeIndex，但 future_covariates 使用 pd.DatetimeIndex）。

References

1

https://otexts.com/fpp2/AR.html#AR

2

https://unit8.com/resources/time-series-forecasting-using-past-and-future-external-data-with-darts/

另请参阅

tabularization.create_lagged_component_names

返回滞后特征名称列表（字符串形式）。

darts.utils.data.tabularization.create_lagged_prediction_data(target_series=None, past_covariates=None, future_covariates=None, lags=None, lags_past_covariates=None, lags_future_covariates=None, uses_static_covariates=True, last_static_covariates_shape=None, max_samples_per_ts=None, check_inputs=True, use_moving_windows=True, concatenate=True, show_warnings=True)

创建特征数组 X 以从已训练的回归模型生成一系列预测；每个观测值的时间索引值也会返回。

注意

此函数只是 create_lagged_data 的一个包装器；有关 X 结构的更多详细信息，请参阅 help(create_lagged_data)。

参数

• target_series (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）回归模型要预测的序列。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）回归模型将用作输入的过去协变量序列。与 target_series 不同，回归模型*不会*预测 past_covariates。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）回归模型将用作输入的未来协变量（即外生协变量）序列。

• lags (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作（自回归）特征的目标序列的滞后。如果未指定，则不会向 X 添加自回归特征。每个滞后值都假定为负数（例如，lags = [-3, -1] 将提取与当前值相距 3 个时间步长和 1 个时间步长的 target_series 值）。如果滞后以字典形式提供，则滞后值特定于目标序列中的每个组件。

• lags_past_covariates (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作特征的 past_covariates 的滞后。与 lags 一样，每个滞后值都假定小于或等于 -1。如果滞后以字典形式提供，则滞后值特定于过去协变量序列中的每个组件。

• lags_future_covariates (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作特征的 future_covariates 的滞后。与 lags 和 lags_past_covariates 不同，lags_future_covariates 值可以为正数（即使用时间 t *之后*的值来预测时间 t 的目标）、零（即使用时间 t *当时*的值来预测时间 t 的目标）和/或负数（即使用时间 t *之前*的值来预测时间 t 的目标）。如果滞后以字典形式提供，则滞后值特定于未来协变量序列中的每个组件。

• uses_static_covariates (bool) – 模型是否使用/期望静态协变量。如果为 True，则强制所有目标序列的静态协变量必须具有相同的形状。

• last_static_covariates_shape (Optional[tuple[int, int], None]) – （可选）最后观察到的静态协变量的形状。在拟合之前或当 uses_static_covariates 为 False 时，此值为 None。

• max_samples_per_ts (Optional[int, None]) – （可选）用于训练/验证的最大采样数；仅保留最新的采样。理论上，指定较小的 max_samples_per_ts 应能减少计算时间，尤其是在可以生成许多观测值的情况下。

• check_inputs (bool) – （可选）指定是否应检查 lags_* 和 series_* 输入的有效性。如果输入已检查过有效性（例如，在类的 __init__ 内部），则应将其设置为 False，否则应设置为 True。

• use_moving_windows (bool) – （可选）指定如果所有提供的序列具有相同的频率，则应使用“滑动窗口”方法来构建 X 和 y。如果 use_moving_windows = False，即使所有提供的序列具有相同的频率，也始终使用“时间交集”方法。一般来说，设置为 True 可以加快表格化速度，但可能会增加内存使用。有关更多详细信息，请参阅注释。

• concatenate (bool) – （可选）指定 X 应作为单个 np.ndarray 返回，而不是作为 Sequence[np.ndarray] 返回。如果每个序列输入指定为 Sequence[TimeSeries] 且 concatenate = False，则 X 将是一个列表，其第 i 个元素对应于每个 Sequence[TimeSeries] 输入中第 i 个 TimeSeries 形成的特征矩阵或标签数组。相反，如果在提供 Sequence[TimeSeries] 时 concatenate = True，则 X 将是沿着第 0 个轴连接每个 TimeSeries 形成的所有特征数组而创建的数组。注意，即使 concatenate = True，times 仍返回为 Sequence[pd.Index]。

• show_warnings (bool) – 是否显示警告。

返回类型

tuple[Union[ndarray, Sequence[ndarray]], Sequence[Index]]

返回值

• X – 构建的特征数组，形状为 (n_observations, n_lagged_features, n_samples)。如果序列输入指定为 Sequence[TimeSeries] 且 concatenate = False，则 X 以 Sequence[np.array] 形式返回；否则，X 以单个 np.array 形式返回。

• times – X 和 y 中每个观测值的时间索引，以 pd.Index 的 Sequence 形式返回。如果序列输入指定为 Sequence[TimeSeries]，则列表的第 i 个元素给出使用每个 Sequence 中第 i 个 TimeSeries 对象形成的那些观测值的时间。否则，如果序列输入指定为 TimeSeries，则唯一元素是使用单个 TimeSeries 输入形成的那些观测值的时间。

Raises

• ValueError – 如果指定的时间序列没有共享任何可以构建特征的时间。

• ValueError – 如果未指定任何滞后，或者任何指定的滞后值为非负数。

• ValueError – 如果任何序列太短，无法为请求的滞后值创建特征。

• ValueError – 如果提供的序列不共享相同类型的 time_index（例如，target_series 使用 pd.RangeIndex，但 future_covariates 使用 pd.DatetimeIndex）。

darts.utils.data.tabularization.create_lagged_training_data(target_series, output_chunk_length, output_chunk_shift, past_covariates=None, future_covariates=None, lags=None, lags_past_covariates=None, lags_future_covariates=None, uses_static_covariates=True, last_static_covariates_shape=None, max_samples_per_ts=None, multi_models=True, check_inputs=True, use_moving_windows=True, concatenate=True, sample_weight=None)

创建特征数组 X 和标签数组 y 以训练滞后变量回归模型（例如 sklearn 模型）；每个观测值的时间索引值也会返回。

注意

此函数只是 create_lagged_data 的一个包装器；有关 X 结构的更多详细信息，请参阅 help(create_lagged_data)。

参数

• target_series (Union[TimeSeries, Sequence[TimeSeries]]) – 回归模型要预测的序列。

• output_chunk_length (int) – 回归模型要预测的未来时间步长数。

• output_chunk_shift (int) – （可选）将输出块向未来偏移的时间步长数。

• past_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）回归模型将用作输入的过去协变量序列。与 target_series 不同，回归模型*不会*预测 past_covariates。

• future_covariates (Union[TimeSeries, Sequence[TimeSeries], None]) – （可选）回归模型将用作输入的未来协变量（即外生协变量）序列。

• lags (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作（自回归）特征的目标序列的滞后。如果未指定，则不会向 X 添加自回归特征。每个滞后值都假定为负数（例如，lags = [-3, -1] 将提取与当前值相距 3 个时间步长和 1 个时间步长的 target_series 值）。如果滞后以字典形式提供，则滞后值特定于目标序列中的每个组件。

• lags_past_covariates (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作特征的 past_covariates 的滞后。与 lags 一样，每个滞后值都假定小于或等于 -1。如果滞后以字典形式提供，则滞后值特定于过去协变量序列中的每个组件。

• lags_future_covariates (Union[Sequence[int], dict[str, list[int]], None]) – （可选）要用作特征的 future_covariates 的滞后。与 lags 和 lags_past_covariates 不同，lags_future_covariates 值可以为正数（即使用时间 t *之后*的值来预测时间 t 的目标）、零（即使用时间 t *当时*的值来预测时间 t 的目标）和/或负数（即使用时间 t *之前*的值来预测时间 t 的目标）。如果滞后以字典形式提供，则滞后值特定于未来协变量序列中的每个组件。

• uses_static_covariates (bool) – 模型是否使用/期望静态协变量。如果为 True，则强制所有目标序列的静态协变量必须具有相同的形状。

• last_static_covariates_shape (Optional[tuple[int, int], None]) – （可选）最后观察到的静态协变量的形状。在拟合之前或当 uses_static_covariates 为 False 时，此值为 None。

• max_samples_per_ts (Optional[int, None]) – （可选）用于训练/验证的最大采样数；仅保留最新的采样。理论上，指定较小的 max_samples_per_ts 应能减少计算时间，尤其是在可以生成许多观测值的情况下。

• multi_models (bool) – （可选）指定回归模型是否预测未来的多个时间步长。如果为 True，则假定回归模型预测从时间 t 到 t+output_chunk_length 的所有时间步长。如果为 False，则假定回归模型*仅*预测 t+output_chunk_length 时间步长。

• check_inputs (bool) – （可选）指定是否应检查 lags_* 和 series_* 输入的有效性。如果输入已检查过有效性（例如，在类的 __init__ 内部），则应将其设置为 False，否则应设置为 True。

• use_moving_windows (bool) – （可选）指定如果所有提供的序列具有相同的频率，则应使用“滑动窗口”方法来构建 X 和 y。如果 use_moving_windows = False，即使所有提供的序列具有相同的频率，也始终使用“时间交集”方法。一般来说，设置为 True 可以加快表格化速度，但可能会增加内存使用。有关更多详细信息，请参阅注释。

• concatenate (bool) – （可选）指定 X 和 y 是否应作为单个 np.ndarray 返回，而不是作为 Sequence[np.ndarray] 返回。如果每个序列输入都指定为 Sequence[TimeSeries] 且 concatenate = False，则 X 和 y 将是列表，其第 i 个元素对应于每个 Sequence[TimeSeries] 输入中第 i 个 TimeSeries 形成的特征矩阵或标签数组。相反，如果在提供 Sequence[TimeSeries] 时 concatenate = True，则 X 和 y 将是沿着第 0 个轴连接每个 TimeSeries 形成的所有特征/标签数组而创建的数组。注意，即使 concatenate = True，times 仍返回为 Sequence[pd.Index]。

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

返回类型

tuple[Union[ndarray, Sequence[ndarray]], Union[None, ndarray, Sequence[ndarray]], Sequence[Index], Optional[tuple[int, int], None], Union[ndarray, Sequence[ndarray], None]]

返回值

• X – 构建的特征数组，形状为 (n_observations, n_lagged_features, n_samples)。如果序列输入指定为 Sequence[TimeSeries] 且 concatenate = False，则 X 以 Sequence[np.array] 形式返回；否则，X 以单个 np.array 形式返回。

• y – 构建的标签数组。如果 multi_models = True，则 y 是形状为 (n_observations, output_chunk_length, n_samples) 的数组；相反，如果 multi_models = False，则 y 是形状为 (n_observations, 1, n_samples) 的数组。如果序列输入指定为 Sequence[TimeSeries] 且 concatenate = False，则 y 以 Sequence[np.array] 形式返回；否则，y 以单个 np.array 形式返回。

• times – X 和 y 中每个观测值的时间索引，以 pd.Index 的 Sequence 形式返回。如果序列输入指定为 Sequence[TimeSeries]，则列表的第 i 个元素给出使用每个 Sequence 中第 i 个 TimeSeries 对象形成的那些观测值的时间。否则，如果序列输入指定为 TimeSeries，则唯一元素是使用单个 TimeSeries 输入形成的那些观测值的时间。

• sample_weight – 要应用于 X 中每个观测值和输出步长 y 的权重，以 np.ndarray 的 Sequence 形式返回。

Raises

• ValueError – 如果指定的时间序列没有共享任何可以构建特征和标签的时间。

• ValueError – 如果未指定任何滞后，或者任何指定的滞后值为非负数。

• ValueError – 如果任何序列太短，无法为请求的滞后和 output_chunk_length 值创建特征和标签。

• ValueError – 如果提供的序列不共享相同类型的 time_index（例如，target_series 使用 pd.RangeIndex，但 future_covariates 使用 pd.DatetimeIndex）。

darts.utils.data.tabularization.get_shared_times(*series_or_times, sort=True)

返回所有指定的 TimeSeries 或时间索引共享的时间（即所有这些时间的交集）。如果 sort = True，则这些共享时间按从最早到最晚排序。忽略 series_or_times 中未指定（即为 None）的任何 TimeSeries 或时间索引。

参数

• series_or_times (Union[TimeSeries, Index, None]) – 应进行“交集”运算的 TimeSeries 和/或时间索引。

• sort (bool) – （可选）指定返回的共享时间应按从最早到最晚排序。

返回值

所有指定的 TimeSeries 和/或时间索引中存在的时间索引。

返回类型

shared_times

Raises

TypeError – 如果指定的 TimeSeries 和/或时间索引不都共享相同类型的时间索引（即，必须都是 pd.DatetimeIndex 或都是 pd.RangeIndex）。

darts.utils.data.tabularization.get_shared_times_bounds(*series_or_times)

返回所有非 None series_or_times 中最晚的 start_time 和最早的 end_time；这些分别是所有这些 series_or_times 的交集的（非紧密）下界和上界。如果所有指定序列之间不存在潜在的重叠，则返回 None。

注意

如果所有指定的 series_or_times 具有相同的频率，则 get_shared_times_bounds 返回紧密边界（即返回所有时间序列交集中最早和最晚的时间）。例如，假设我们有三个具有不同观测时间的等频率序列

序列 1: —— 序列 2: —— 序列 3: ——

在此，每个 - 表示特定时间的一个观测值。在此示例中，find_time_overlap_bounds 将返回 LB 和 UB 的时间

LB

序列 1: —|---| 序列 2: |---|— 序列 3: –|---|-

UB

如果指定的时间序列*不*具有相同的频率，则返回的边界可能不是紧密的（即 LB <= intersection.start_time() < intersection.end_time() <= UB，其中 intersection 是所有指定时间序列共享的时间）

参数

series_or_times (Sequence[Union[TimeSeries, Index, None]]) – 用于计算交集边界的 TimeSeries 和/或 pd.Index 值；忽略任何提供的 None 值。

返回值

包含所有指定时间序列中最晚 start_time 和最早 end time 的元组，按此顺序排列。如果指定序列之间不存在潜在的重叠，则返回 None。同样，如果未指定任何非 None 的 series_or_times，则返回 None。

返回类型

bounds

Raises

TypeError – 如果 series_or_times 中的序列和/或时间不都共享相同类型的时间索引（即，必须都是 pd.DatetimeIndex 或 pd.RangeIndex）。

darts.utils.data.tabularization.strided_moving_window(x, window_len, stride=1, axis=0, check_inputs=True)

沿指定的 axis 提取数组 x 的滑动窗口视图，每个窗口的长度为 window_len，连续窗口之间通过 stride 索引分隔。提取的窗口总数等于 num_windows = (x.shape[axis] - window_len)//stride + 1。

注意

此函数类似于 np.lib.stride_tricks 中的 sliding_window_view，但有以下区别

1. strided_moving_window 允许连续窗口之间通过指定的 stride 分隔，而 sliding_window_view 不允许。 2. strided_moving_window 只能沿单个轴操作，而 sliding_window_view 可以沿多个轴操作。

此外，与 sliding_window_view 不同，使用 strided_moving_window 不需要 numpy >= 1.20.0。

参数

• x (ndarray) – 要从中提取滑动窗口的数组。

• window_len (int) – 提取的滑动窗口的大小。

• stride (int) – （可选）连续窗口之间的间隔。

• axis (int) – （可选）应沿其提取滑动窗口的轴。

• check_inputs (bool) – （可选）指定是否应检查输入的有效性。如果输入已检查过有效性（例如，在类的 __init__ 内部），则应将其设置为 False，否则应设置为 True。有关更多详细信息，请参阅[1]。

返回值

从 x 中提取的滑动窗口。提取的窗口沿最后一个轴堆叠，并且提取窗口的 axis 被“修整”，使其长度等于提取窗口的数量。更具体地说，windows.shape = x_trimmed_shape + (window_len,)，其中 x_trimmed_shape 等于 x.shape，除了 x_trimmed_shape[axis] = num_windows。

返回类型

windows

Raises

• ValueError – 如果 check_inputs = True 且 window_len 非正数。

• ValueError – 如果 check_inputs = True 且 stride 非正数。

• ValueError – 如果 check_inputs = True 且 axis 大于 x.ndim。

• ValueError – 如果 check_inputs = True 且 window_len 大于 x.shape[axis]。

References

1

https://numpy.com.cn/doc/stable/reference/generated/numpy.lib.stride_tricks.as_strided.html

上一页

偏移训练数据集

下一页

训练数据集基类