数据#

加载时间序列预测的数据并不简单——特别是如果包含协变量并且存在缺失值。 PyTorch Forecasting 提供了 TimeSeriesDataSet，它附带了一个 to_dataloader() 方法将其转换为数据加载器，以及一个 from_dataset() 方法，用于创建例如验证 或测试数据集，使用相同的标签编码器和数据归一化从训练数据集中创建。

此外，时间序列通常需要（几乎总是）进行归一化，以便神经网络能够高效学习。PyTorch Forecasting 提供了多种目标归一化器（其中一些也可以用于归一化协变量）。

时间序列数据集#

时间序列数据集是PyTorch Forecasting中的核心数据持有对象。它主要接受一个pandas DataFrame以及一些元数据。请参阅将数据传递给模型的教程以了解更多关于它与模型的耦合信息。

class pytorch_forecasting.data.timeseries.TimeSeriesDataSet(data: DataFrame, time_idx: str, target: str | List[str], group_ids: List[str], weight: str | None = None, max_encoder_length: int = 30, min_encoder_length: int = None, min_prediction_idx: int = None, min_prediction_length: int = None, max_prediction_length: int = 1, static_categoricals: List[str] | None = None, static_reals: List[str] | None = None, time_varying_known_categoricals: List[str] | None = None, time_varying_known_reals: List[str] | None = None, time_varying_unknown_categoricals: List[str] | None = None, time_varying_unknown_reals: List[str] | None = None, variable_groups: Dict[str, List[int]] | None = None, constant_fill_strategy: Dict[str, str | float | int | bool] | None = None, allow_missing_timesteps: bool = False, lags: Dict[str, List[int]] | None = None, add_relative_time_idx: bool = False, add_target_scales: bool = False, add_encoder_length: bool | str = 'auto', target_normalizer: TorchNormalizer | NaN标签编码器 | 编码器归一化器 | str | List[TorchNormalizer | NaN标签编码器 | 编码器归一化器] | Tuple[TorchNormalizer | NaN标签编码器 | 编码器标准化器] | None = 'auto', categorical_encoders: Dict[str, NaN标签编码器] | None = None, scalers: Dict[str, 标准缩放器 | 鲁棒缩放器 | TorchNormalizer | 编码器归一化器] | None = None, randomize_length: None | Tuple[float, float] | bool = False, predict_mode: bool = False)[来源]

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

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

  • 变量的缩放和编码

  • 标准化目标变量

  • 高效地将pandas数据框中的时间序列转换为torch张量

  • 持有关于未来已知和未知的静态和时变变量的信息

  • 保存有关相关类别的信息（例如假期）

  • 用于数据增强的下采样

  • 生成推理、验证和测试数据集

传递数据到模型的教程有助于理解数据集的输出以及它如何与模型耦合。

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

大型数据集：

目前该类仅限于内存操作（可以通过现有的numba安装加速）。 然而，如果您有非常大的数据， 您可以向其传递预拟合的编码器和缩放器以及序列的子集 以构建有效的数据集（此外，可能应该使用EncoderNormalizer来 归一化目标）。 在拟合网络时，您需要创建一个自定义的DataLoader来循环遍历数据集。 目前没有内置的方法来执行此操作。

Parameters:

  • data (pd.DataFrame) – 包含序列数据的dataframe - 每一行可以通过 time_idx 和 group_ids 来识别

  • time_idx (str) – 表示data内时间索引的整数类型列。 此列用于确定样本的顺序。 如果没有缺失的观测值， 时间索引应随每个后续样本增加+1。 每个序列的第一个time_idx不一定 必须是0，允许任何值。

  • target (Union[str, List[str]]) – data 中表示预测目标的列。 可以是分类或连续数据类型。

  • group_ids (List[str]) – 标识data中时间序列实例的列名列表 这意味着group_ids与time_idx一起标识一个样本。 如果你只有一个时间序列，请将其设置为常数列的名称。

  • weight (str, optional, default=None) – 权重的列名。默认为 None。

  • max_encoder_length (int, optional, default=30) – 最大编码长度。 这是时间序列数据集使用的最大历史长度。

  • min_encoder_length (int, optional, default=max_encoder_length) – 允许编码的最小长度。默认为 max_encoder_length。

  • min_prediction_idx (int, optional, default = first time_idx in data) – 从哪个最小的 time_idx 开始预测。 此参数可用于创建验证集或测试集。

  • max_prediction_length (int, optional, default=1) – 最大预测/解码长度 （不要选择太短的长度，因为它有助于收敛）

  • min_prediction_length (int, optional, default=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, optional, default=None) – 未来未知且随时间变化的连续变量列表。 如果目标变量是真实的，则应包含在此处。

  • variable_groups (Dict[str, List[str]], optional, default=None) – 将名称映射到数据中列列表的字典。 该名称应出现在分类或实数类参数中，以便能够按组对列进行编码或缩放。 这将有效地组合分类变量，特别是在分类变量可以同时具有多个值的情况下非常有用。 一个例子是可能重叠的假期。

  • constant_fill_strategy (dict, optional, default=None) – 键必须是字符串，值可以是字符串、浮点数、整数或布尔值。 如果序列中存在缺失值（默认使用前向填充策略），则使用此字典中的列名和常量来填充缺失值。 只有在allow_missing_timesteps=True时才会使用这些值。 一个常见的用例是，如果样本不在数据集中，则表示需求为0。

  • allow_missing_timesteps (bool, optional, default=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, optional, default=False) – 是否添加相对时间索引作为特征，即， 对于每个采样的序列，索引将从-encoder_length到 prediction_length。

  • add_target_scales (bool, 可选, 默认=False) – 是否为目标添加尺度到静态真实特征中，即添加未归一化时间序列的中心和尺度作为特征。

  • add_encoder_length (Union[bool, str], optional, default="auto") – 是否将编码器长度添加到静态实变量列表中。 默认为“auto”，即当min_encoder_length != max_encoder_length时，等同于True。

  • 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 (可选, None, bool, 或 tuple 的 float.) – 如果不随机化长度，则为 None 或 False。 从 beta 分布浓度中采样的概率元组，用于通过二项分布采样新的序列长度。 如果为 True，则默认为 (0.2, 0.05)，即约 1/4 的样本在最小编码器长度附近。 否则默认为 False。

  • predict_mode (bool) – 如果为True，TimeSeriesDataSet将仅为每个时间序列创建一个序列（即仅从最新提供的样本中创建）。 实际上，这将选择由group_ids标识的每个时间序列的最后max_prediction_length个样本作为预测样本，并将之前的所有样本（最多max_encoder_length个样本）作为编码器样本。 如果为False，TimeSeriesDataSet将通过滑动窗口在数据样本上创建子序列。 对于训练用例，最好将predict_mode设置为False以获取所有子序列。 另一方面，predict_mode = True对于验证用例是理想的。

时间序列数据集，用于存储模型的数据。

详情#

有关可用数据编码器和TimeSeriesDataSet的更多详细信息，请参阅API文档：

pytorch_forecasting.data.encoders.EncoderNormalizer([...])

特殊的归一化器，适用于每个编码序列。

pytorch_forecasting.data.encoders.GroupNormalizer([...])

按组进行缩放的标准化器。

pytorch_forecasting.data.encoders.MultiNormalizer(...)

用于多个目标的标准化器。

pytorch_forecasting.data.encoders.NaNLabelEncoder([...])

可以始终将nan和未知类别（在转换中）编码为类别0的标签编码器

pytorch_forecasting.data.encoders.TorchNormalizer([...])

基本的目标转换器，也可以适应于torch张量。

pytorch_forecasting.data.samplers.TimeSynchronizedBatchSampler(sampler)

随机采样小批量数据，但以时间同步的方式进行。

pytorch_forecasting.data.timeseries.TimeSeriesDataSet(...)

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