时间序列数据集#

基础： Dataset

用于拟合时间序列模型的PyTorch数据集。

该数据集自动化了常见任务，例如

变量的缩放和编码
对目标变量进行归一化
高效地将pandas数据框中的时间序列转换为torch张量
持有关于未来已知和未知的静态和时间变化变量的信息
包含有关相关类别的信息（例如节假日）
用于数据增强的下采样
生成推断、验证和测试数据集

关于将数据传递给模型的教程有助于理解数据集的输出以及它是如何与模型相结合的。

每个样本都是完整时间序列的一个子序列。子序列由给定时间序列的编码器和解码器/预测时间点组成。此类构建了一个索引，定义了哪些子序列存在并可以被采样（index 属性）。索引中的样本由各种参数定义，传递给类（编码器和预测长度、最小预测长度、随机长度和预测关键字）。如何将样本采样到训练批次中，由 DataLoader 确定。该类提供了to_dataloader()方法将数据集转换为数据加载器。

大规模数据集：

目前该类仅限于内存操作（可以通过现有的numba安装加速）。然而，如果您有非常大的数据，您可以将预先拟合的编码器和缩放器传递给它，以及一部分序列以构造有效的数据集（此外，可能应该使用EncoderNormalizer来标准化目标）。在拟合网络时，您将需要创建一个自定义DataLoader来轮换数据集。目前没有内置的方法来做到这一点。

Parameters:

data (pd.DataFrame) – 带有序列数据的数据框 - 每行可以通过 time_idx 和 group_ids 来识别
time_idx (str) – 表示时间索引的整数类型列，位于 data 中。此列用于确定样本的顺序。如果没有缺失的观测值，时间索引应为每个后续样本增加 +1。每个系列的第一个 time_idx 不一定必须是 0，但允许任何值。
target (Union[str, List[str]]) – data 中表示预测目标的列。可以是分类或连续数据类型。
group_ids (列表[字符串]) – 标识时间序列实例的列名列表在 data 中这意味着 group_ids 将样本与 time_idx 一起标识。如果您只有一个时间序列，请将其设置为常量列的名称。
weight (str, 可选, 默认=None) – 权重的列名。默认为 None。
max_encoder_length (int, optional, default=30) – 最大编码长度。这是时间序列数据集使用的最大历史长度。
min_encoder_length (int, 可选, 默认=max_encoder_length) – 允许编码的最小长度。默认为max_encoder_length。
min_prediction_idx (int, 可选, 默认 = 数据中的第一个 time_idx) – 开始预测的最小 time_idx。这个参数可以用于创建验证集或测试集。
max_prediction_length (int, optional, default=1) – 最大预测/解码长度（选择时不要太短，因为这有助于收敛）
min_prediction_length (int, 可选, 默认=max_prediction_length) – 最小预测/解码长度
static_categoricals (list of str, optional, default=None) – 不随时间变化的分类变量列表，在 data 中，条目也可以是一起编码的列表（例如，对于产品类别很有用）
static_reals (list of str, optional, default=None) – 不随时间变化的连续变量列表
time_varying_known_categoricals (list of str, optional, default=None) – 一系列随时间变化并且已知未来的分类变量，条目也可以是列表，然后一起编码（例如，对于特殊日期或促销类别非常有用）
time_varying_known_reals (list of str, optional, default=None) – 一系列随时间变化并在未来已知的连续变量（例如产品价格，但不是产品需求）
time_varying_unknown_categoricals (list of str, optional, default=None) – 不知道未来的分类变量列表，并且随时间变化。条目也可以是列表，然后一起编码（例如，对于天气类别很有用）。如果是分类的目标变量，应该包括在这里。
time_varying_unknown_reals (list of str, 可选, 默认=None) – 一系列在未来未知并随时间变化的连续变量。如果是真实的，目标变量应包含在此处。
variable_groups (字典[str, 列表[str]], 可选, 默认=None) – 将名称映射到数据中列列表的字典。该名称应在分类或实际类参数中出现，以便能够按组编码或缩放列。这将有效地组合分类变量，特别是在分类变量可以同时具有多个值时非常有用。一个例子是节假日，它们可能会重叠。
constant_fill_strategy (dict, optional, default=None) – 键必须是字符串，值可以是字符串、浮点数、整数或布尔值。包含常数以填补缺失值的列名字典，如果序列中存在缺口（默认情况下使用前向填充策略）。只有当 allow_missing_timesteps=True 时，值才会被使用。一个常见的用例是如果样本不在数据集中，则表示需求为 0。
allow_missing_timesteps (bool, 可选, 默认值=False) – 是否允许缺失的时间步，这些时间步将自动填充。缺失值是指在time_idx中的间隙，例如，如果一个特定的时间序列只有1, 2, 4, 5的样本，则3的样本将被动态生成。允许缺失并不处理NA值。在将数据框传递给TimeSeriesDataSet之前，您应该填充NA值。
lags (Dict[str, List[int]], optional, default=None) – 将变量名称映射到应滞后的时间步长列表的字典。滞后可以用来为模型指示季节性。如果已知数据的季节性，则添加这些信息非常有用。在这种情况下，建议添加目标变量及其相应的滞后以提高性能。滞后必须不大于最短的时间序列，因为所有时间序列将按最大的滞后值裁剪以防止出现NA值。滞后变量必须出现在时间变化的变量中。如果您只想要滞后值而不想要当前值，请手动在输入数据中滞后，使用 data[lagged_varname] = `` ``data.sort_values(time_idx).groupby(group_ids, observed=True).shift(lag)。
add_relative_time_idx (bool, 可选, 默认=False) – 是否将相对时间索引添加为特征，即，对于每一个采样序列，索引范围将从 -encoder_length 到 prediction_length。
add_target_scales (bool, optional, default=False) – 是否为静态真实特征添加目标的尺度，即将未归一化时间序列的中心和尺度作为特征添加。
add_encoder_length (Union[bool, str], optional, default="auto") – 是否将编码器长度添加到静态实际变量列表中。默认为“auto”，这与 True 相同，如果 min_encoder_length != max_encoder_length。
target_normalizer (torch transformer, str, list, tuple, optional, default="auto") – 变换器，接受 group_ids、target 和 time_idx 以归一化目标。您可以选择 TorchNormalizer, GroupNormalizer, NaNLabelEncoder, EncoderNormalizer （在这些上面的过拟合测试将失败）或 None 来不使用任何归一化器。对于多个目标，请使用 :py:class`~pytorch_forecasting.data.encoders.MultiNormalizer`。默认情况下，将自动选择合适的归一化器。
categorical_encoders (dict[str, BaseEstimator]) – scikit learn 标签转换器的字典。如果您在未来有未观察到的类别 / 冷启动问题，您可以使用 NaNLabelEncoder 和 add_nan=True。默认有效地使用 sklearn 的 LabelEncoder()。已经拟合的编码器将不会再次拟合。
scalers (可选, 具有字符串键和torch或sklearn缩放器的字典) – scikit-learn或torch缩放器的字典。默认为sklearn的 StandardScaler()。其他选项包括EncoderNormalizer、GroupNormalizer或scikit-learn的 StandarScaler()、RobustScaler()或 None 以不使用归一化器 / 使用 center=0 和 scale=1 的归一化器 (method="identity")。预先拟合的编码器将不会再次拟合（除了EncoderNormalizer会在每个编码器序列上拟合）。
randomize_length (可选, 无, 布尔值, 或 浮点数的元组.) – 如果不随机化长度则为无或假。 从中抽样概率的贝塔分布浓度的元组，这些概率用于使用二项分布抽样新的序列长度。如果为真，则默认为 (0.2, 0.05)，即约为最小编码器长度的四分之一的样本。否则默认为假。
predict_mode (bool) – 如果为 True，TimeSeriesDataSet 将只为每个时间序列创建一个序列（即仅使用最新提供的样本）。实际上，这将选择由 group_ids 标识的每个时间序列的最后 max_prediction_length 样本作为预测样本，并将之前的样本（最多到 max_encoder_length 样本）作为编码器样本。如果为 False，TimeSeriesDataSet 将通过在数据样本上滑动窗口来创建子序列。对于训练用例，最好将 predict_mode 设置为 False 以获取所有子序列。另一方面，predict_mode = True 非常适合验证案例。

持有模型数据的时间序列数据集。

Inherited-members:

方法

`calculate_decoder_length`(time_last, ...)	计算解码器的长度。
`filter`(filter_func[, copy])	过滤数据集中的子序列。
`from_dataset`(数据集, 数据[, ...])	使用不同的数据构建数据集，相同的变量编码器、缩放器等。
`from_parameters`(参数, 数据[, ...])	构建具有不同数据、相同变量编码器、缩放器等的数据集。
`get_parameters`()	获取自我的参数作为字典。
`get_transformer`(名称[, 组_ID])	获取变量的变压器。
`load`(fname)	从磁盘加载数据集
`plot_randomization`([betas, length, min_length])	绘制预期的随机长度分布。
`reset_overwrite_values`()	重置用于覆盖样本特征的值。
`save`(fname)	将数据集保存到磁盘
`set_overwrite_values`(values, variable[, target])	为特定变量覆盖解码器或编码器（或两者）的值。
`to_dataloader`([训练, 批处理大小, 批处理采样器])	从数据集构建数据加载器，以便在模型中使用。
`transform_values`(name, values[, data, ...])	缩放和编码值。
`x_to_index`(x)	从x解码数据框索引。

属性

`categoricals`	用于建模的分类变量。
`decoded_index`	获取可解释的索引版本。
`dropout_categoricals`	在没有观察到的历史记录时进行预测时未知的分类变量列表
`flat_categoricals`	输入数据中定义的分类变量。
`lagged_targets`	滞后变量的子集，作为滞后目标的变量。
`lagged_variables`	滞后变量。
`max_lag`	时间步长变量的最大滞后数。
`min_lag`	变量滞后的最小时间步数。
`multi_target`	如果数据集编码了一个或多个目标。
`reals`	用于建模的连续变量。
`target_names`	目标列表。
`target_normalizers`	与 `target_names` 对齐的目标归一化器列表。
`variable_to_group_mapping`	将分类变量映射到输入数据中的变量。

计算解码器的长度。

Parameters:

time_last (Union[int, pd.Series, np.ndarray]) – 序列的最后时间索引
sequence_length (Union[int, pd.Series, np.ndarray]) – 序列的总长度

Returns:

解码器长度（秒）

Return type:

联合[int, pd.Series, np.ndarray]

filter(filter_func: Callable, copy: bool = True) → 时间序列数据集[来源]#

过滤数据集中的子序列。

使用可解释的索引版本 decoded_index() 来过滤数据集中的子序列。

Parameters:

filter_func (可调用) – 用于过滤的函数。应该将decoded_index()数据框作为唯一参数，该数据框包含组ID和时间索引列。
copy (bool, optional, default=True) – 是否返回数据集的副本（True）或就地过滤（False）。

Returns:

筛选后的数据集

Return type:

时间序列数据集

classmethod from_dataset(dataset, data: DataFrame, stop_randomization: bool = False, predict: bool = False, **update_kwargs)[来源]#

构建具有不同数据、相同变量编码器、缩放器等的数据集。

在后台调用 from_parameters()。

可以使用 update_kwargs 重写参数。

Parameters:

数据集 (TimeSeriesDataSet) – 用于复制参数的数据集
data (pd.DataFrame) – 将从中生成新数据集的数据
stop_randomization (bool, 可选, 默认=None) – 是否停止随机化编码器和解码器的长度，适用于验证集。
predict (bool, optional, default=False) – 是否在时间索引的最后条目上预测解码器长度（即每组仅进行一次预测）。
**update_kwargs – 关键字参数覆盖，传递给新数据集的构造函数

Returns:

新数据集

Return type:

时间序列数据集

classmethod from_parameters(parameters: Dict[str, Any], data: DataFrame, stop_randomization: bool = None, predict: bool = False, **update_kwargs)[来源]#

构建具有不同数据、相同变量编码器、缩放器等的数据集。

返回与自相同参数的TimeSeriesDataSet，但数据不同。可能会用update_kwargs覆盖参数。

Parameters:

参数 (字典[字符串, 任意]) – 用于新数据集的数据集参数
data (pd.DataFrame) – 从中生成新数据集的数据
stop_randomization (bool, 可选, 默认=None) – 是否停止随机化编码器和解码器的长度，适用于验证集。
predict (bool, optional, default=False) – 是否在时间索引的最后条目上预测解码器长度（即每组仅进行一次预测）。
**update_kwargs – 关键字参数覆盖，传递给新数据集的构造函数

Returns:

新数据集

Return type:

时间序列数据集

get_parameters() → Dict[str, Any][来源]#

获取自我的参数作为字典。

这些可以与 from_parameters() 一起使用，以创建具有相同缩放器的新数据集。

Returns:: 字典[str, 任何]
Return type:: 参数字典

get_transformer(name: str, group_id: bool = False)[来源]#

获取变量的变压器。

Parameters:

name (str) – 变量名称
group_id (bool, 可选, 默认=False) – 是否传入的名称指的是一个组id，针对这些使用不同的编码器。

Return type:

变换器

classmethod load(fname: str)[来源]#

从磁盘加载数据集

Parameters:: fname (str) – 要加载的文件名
Returns:: 时间序列数据集

plot_randomization(betas: Tuple[float, float] = None, length: int = None, min_length: int = None)[来源]#

绘制预期的随机长度分布。

Parameters:

betas (元组[浮点数, 浮点数], 可选, 默认=随机化长度 of 数据集) – betas的元组，例如 (0.2, 0.05) 用于随机化。
length (int, 可选, 默认为dataset的max_encoder_length) – 绘制的序列长度。
min_length (int, 可选, 默认为dataset的min_encoder_length) – 绘制的序列的最小长度。

Returns:

基于1000个样本的图形和直方图的元组

Return type:

元组[plt.Figure, torch.Tensor]

reset_overwrite_values() → None[来源]#: 重置用于覆盖样本特征的值。

save(fname: str) → None[来源]#

将数据集保存到磁盘

Parameters:: fname (str) – 要保存的文件名

set_overwrite_values(values: float | Tensor, variable: str, target: str | slice = 'decoder') → None[来源]#

为特定变量覆盖解码器或编码器（或两者）的值。

Parameters:

values (Union[float, torch.Tensor]) – 用于覆盖的值。
变量 (str) – 应该被覆盖值的变量。
target (Union[str, slice], optional)) – 要覆盖的位置。可以是“decoder”、“encoder”或“all”，也可以是一个切片对象，直接用于覆盖索引，例如，slice(-5, None)将覆盖最后5个值。默认值为“decoder”。

to_dataloader(train: bool = True, batch_size: int = 64, batch_sampler: Sampler | str = None, **kwargs) → DataLoader[来源]#

从数据集构建数据加载器，以便在模型中使用。

Parameters:

train (bool, 可选, 默认=Trze) – 数据加载器是否用于训练 (True) 或预测 (False)。
如果为 True，将打乱并丢弃最后一个批次。默认值为 True。
batch_size (int, 可选, 默认值=64) – 用于训练模型的批处理大小。默认为64。
batch_sampler (Sampler, str, or None, optional, default=None) –
torch 批量采样器或字符串。以下之一
- ”synchronized”: 确保解码器中的样本时间上对齐。
  不支持数据集中缺失值。这仅在底层算法利用时间上对齐的值时才有意义。
- PyTorch Sampler 实例：任何 PyTorch 采样器，
  例如， the WeightedRandomSampler()
- None: 样本是从时间序列中随机抽取的。
**kwargs （传递给DataLoader构造函数的附加参数）

Returns:

数据加载器 – 第一个条目是 x，一个包含张量的字典，条目和形状在括号中。

encoder_catlong (batch_size x n_encoder_time_steps x n_features)
编码分类变量的长张量，用于编码器
encoder_contfloat (batch_size x n_encoder_time_steps x n_features)
缩放后的连续变量的浮点张量，用于编码器
encoder_targetfloat (batch_size x n_encoder_time_steps) or list thereof
如果是列表，每个条目对应不同的目标。未缩放的连续目标的浮点张量或编码的分类目标，多个目标的张量列表
encoder_lengthslong (batch_size)
包含编码器时间序列长度的长张量。没有条目会大于 n_encoder_time_steps
decoder_catlong (batch_size x n_decoder_time_steps x n_features)
编码分类变量的长张量，用于解码器
decoder_contfloat (batch_size x n_decoder_time_steps x n_features)
缩放后的连续变量的浮点张量，用于解码器
decoder_targetfloat (batch_size x n_decoder_time_steps) or list thereof
如果是列表，每个条目对应不同的目标。未缩放的（连续）或编码的（分类）目标，解码器的目标 - 这对应于 y 的第一个条目，多个目标的张量列表
decoder_lengthslong (batch_size)
包含解码器时间序列长度的长张量。没有条目会大于 n_decoder_time_steps
group_idsfloat (batch_size x number_of_ids)
编码的组 ID，用于标识数据集中的时间序列
target_scalefloat (batch_size x scale_size) or list thereof.
如果是列表，每个条目对应不同的目标。用于标准化目标的参数。通常这些是均值和标准差。多个目标的张量列表。

第二个条目是 y，形式为 (target, weight) 的元组

targetfloat (batch_size x n_decoder_time_steps) or list thereof
如果是列表，每个条目对应不同的目标。未缩放（连续）或编码（分类）目标，多个目标的张量列表
weightNone or float (batch_size x n_decoder_time_steps)
每个目标的权重，如果没有使用权重则为 None（= 相等权重）

Return type:

返回元组的数据加载器。

示例

用于训练的样本权重：

from torch.utils.data import WeightedRandomSampler

# length of probabilties for sampler have to be equal to the length of index
probabilities = np.sqrt(1 + data.loc[dataset.index, "target"])
sampler = WeightedRandomSampler(probabilities, len(probabilities))
dataset.to_dataloader(train=True, sampler=sampler, shuffle=False)

transform_values(name: str, values: Series | Tensor | ndarray, data: DataFrame = None, inverse=False, group_id: bool = False, **kwargs) → ndarray[来源]#

缩放和编码值。

Parameters:

name (str) – 变量的名称
values (Union[pd.Series, torch.Tensor, np.ndarray]) – 要编码/缩放的值
data (pd.DataFrame, 可选, 默认=None) – 用于缩放的额外数据（例如，具有分组列的数据框）
inverse (bool, optional, default=False) – 是否转换为普通形式 (True) 或逆变换 (False)
group_id (bool, 可选, 默认=False) – 传入的名称是否指代一个组id - 使用不同的编码器来处理这些
**kwargs (transform/inverse_transform 方法的附加参数)

Returns:

（解码/编码）/(解缩放) 值

Return type:

np.ndarray

x_to_index(x: Dict[str, Tensor]) → DataFrame[来源]#

从x解码数据框索引。

Returns:: 用于第一次预测和组ID的带时间索引列的数据框

property categoricals: List[str]#

用于建模的分类变量。

Returns:: 变量列表
Return type:: 列表[str]

property decoded_index: DataFrame#

获取可解释的索引版本。

DataFrame包含 - group_id列以原始编码 - time_idx_first列：子序列的第一个时间索引 - time_idx_last列：子序列的最后一个时间索引 - time_idx_first_prediction列：解码器中的第一个时间索引

Returns:: 可以通过原始数据理解的索引
Return type:: pd.DataFrame

property dropout_categoricals: List[str]#: 在没有观察历史的情况下进行预测时，不知道的分类变量列表

property flat_categoricals: List[str]#

输入数据中定义的分类变量。

Returns:: 变量列表
Return type:: 列表[str]

property lagged_targets: Dict[str, str]#

滞后变量的子集，作为滞后目标的变量。

Parameters:

字典[str – 与滞后变量对应的变量名称的字典，映射到滞后变量
str] – 对应于滞后变量的变量名称字典，映射到滞后变量

property lagged_variables: Dict[str, str]#

滞后变量。

Parameters:

字典[str – 对应于滞后变量的变量名称的字典，映射到被滞后的变量
str] – 与滞后变量对应的变量名称字典，映射到滞后变量

property max_lag: int#

时间步长变量的最大滞后数。

Returns:: 整数
Return type:: 最大滞后

property min_lag: int#

变量滞后的最小时间步数。

Returns:: 整数
Return type:: 最小滞后

property multi_target: bool#

如果数据集编码了一个或多个目标。

Returns:: 如果有多个目标则为真
Return type:: 布尔值

property reals: List[str]#

用于建模的连续变量。

Returns:: 变量列表
Return type:: 列表[str]

property target_names: List[str]#

目标列表。

Returns:: 目标列表
Return type:: 列表[str]

property target_normalizers: List[TorchNormalizer]#

与 target_names 对齐的目标归一化器列表。

Returns:: 目标归一化器列表
Return type:: 列表[TorchNormalizer]

property variable_to_group_mapping: Dict[str, str]#

将分类变量映射到输入数据中的变量。

Returns:: 字典，将 categorical() 映射到 flat_categoricals()。
Return type:: 字典[str, str]

时间序列数据集#

此页面