窗口变换器¶

类 darts.dataprocessing.transformers.window_transformer.WindowTransformer(transforms, treat_na=None, forecasting_safe=True, keep_non_transformed=False, include_current=True, keep_names=False, name='WindowTransformer', n_jobs=1, verbose=False)[source]¶

基类：BaseDataTransformer

一个对 TimeSeries 或 TimeSeries 序列应用窗口变换的变换器。它需要一个字典或字典列表来指定要应用的窗口变换。序列中的所有时间序列都将使用相同的变换进行转换。

参数

transforms (Union[dict, list[dict]]) –
一个字典或字典列表。每个字典指定一种不同的窗口变换。

字典可以包含以下键：

"function"

必需。pandas 内置变换函数之一的名称，或可应用于输入时间序列的可调用函数。pandas 函数可以在文档中找到。

"mode"

可选。应用 `"function"` 的 pandas 窗口模式名称。选项有 “rolling”、“expanding” 和 “ewm”。如果未提供，Darts 默认为 “expanding”。用户自定义函数可以使用 “rolling” 或 “expanding” 模式。有关 pandas 窗口操作的更多信息可以在文档中找到。

"components"

可选。一个字符串或字符串列表，指定应应用变换的 TimeSeries 分量。如果未指定，变换将应用于所有分量。

"function_name"

可选。一个字符串，指定作为变换输出名称一部分引用的函数名称。例如，对于用户提供的对分量“comp”在大小为 5 的 rolling 窗口上进行的函数变换，默认变换输出名称为 “rolling_udf_5_comp”，其中 “udf” 指的是 “用户自定义函数”。如果指定了 `"function_name"`，它将替换默认名称 “udf”。同样，`"function_name"` 也将替换输出名称中 pandas 内置变换函数名称。

提供的所有其他字典项将作为窗口模式（即 `"rolling/ewm/expanding"`）或该模式中特定函数（即 `"pandas.DataFrame.rolling.mean/std/max/min..."` 或 `"pandas.DataFrame.ewm.mean/std/sum"`）的关键字参数处理。这通过提供例如以下参数，增加了配置变换的灵活性：
- "window"
  
  “rolling” 模式下移动窗口的大小。如果是整数，表示每个窗口使用的固定观测数量。如果是偏移量，则表示每个窗口的时间段，数据类型为 pandas.Timedelta，代表固定时长。
- "min_periods"
  
  窗口中需要值的最小观测数（否则为 NaN）。对于 “rolling” 和 “expanding” 模式，Darts 重用 pandas 默认值 1；对于 “ewm” 模式，重用 pandas 默认值 0。
- "win_type"
  
  应用于窗口元素的加权类型。如果提供，应该是 scipy.signal.windows 之一。
- "center"
  
  True/False 用于将当前时间步长的观测值设置在窗口的中心（当 forecasting_safe 为 True 时，Darts 将 "center" 强制设置为 False）。
- "closed"
  
  "right"/"left"/"both"/"neither" 用于指定窗口的右端、左端、两端是否包含在窗口内，或两者都不包含。Darts 默认为 "both"。
有关可用函数及其参数的更多信息可以在 Pandas 文档中找到。

对于用户提供的函数，变换字典中的额外关键字参数会传递给用户自定义函数。默认情况下，Darts 期望用户自定义函数接收 numpy 数组作为输入。这可以通过在变换字典中添加项 "raw": False 来修改。期望函数为每个窗口返回一个单一值。其他可能的配置可以在 pandas.DataFrame.rolling().apply() 文档和 pandas.DataFrame.expanding().apply() 文档中找到。
treat_na (Union[str, int, float, None]) –
指定如何处理窗口变换在结果 TimeSeries 开头添加的缺失值。默认情况下，Darts 会在结果 TimeSeries 中保留 NaNs。此参数可以是以下之一：
- "dropna"
  
  截断 TimeSeries 并删除包含缺失值的时间步长。如果多列包含不同数量的缺失值，则仅删除最小行数。此操作可能会缩短结果 TimeSeries 的长度。
- "bfill" 或 "backfill"
  
  指定 NaNs 应填充为最后一个已变换且有效的观测值。如果原始 TimeSeries 以 NaNs 开头，则这些 NaNs 会被保留。当 forecasting_safe 为 True 时，此选项会抛出异常，以避免未来观测值污染过去。
- 一个整数或浮点数
  
  在这种情况下，NaNs 将填充此值。所有列都将填充为提供的同一值。
forecasting_safe (Optional[bool, None]) – 如果为 True，Darts 会强制结果 TimeSeries 可以安全地用作预测模型的目标或特征。窗口变换不允许在当前时间步长的计算中包含未来值。默认值为 True。“ewm” 和 “expanding” 模式默认是预测安全的。“rolling” 模式在保证 "center": False 时是预测安全的。
keep_non_transformed (Optional[bool, None]) – False 只返回变换后的分量，True 返回所有原始分量以及变换后的分量。默认值为 False。如果时间序列具有层次结构，则必须设置为 False。
include_current (Optional[bool, None]) – True 将当前时间步长包含在窗口中，False 将其排除。默认值为 True。
keep_names (Optional[bool, None]) – 变换后的分量是否应保留原始分量名称。如果 keep_non_transformed = True 或变换数量大于 1，则必须设置为 False。
name (str) – 变换器的特定名称。
n_jobs (int) – 并行运行的作业数量。仅当将 Sequence[TimeSeries] 作为输入传递给方法时才会创建并行作业，以并行处理不同的 TimeSeries。默认为 1。
verbose (bool) – 是否打印操作进度。

属性

name

数据变换器的名称。

方法

`apply_component_mask`(series[, ...])	从 series 中提取由 component_mask 指定的分量
`set_n_jobs`(value)	设置变换器在处理多个 `TimeSeries` 时使用的处理器数量。
`set_verbose`(value)	设置详细输出状态。
`stack_samples`(vals)	从 TimeSeries 或 TimeSeries 的 array_values 创建形状为 (n_timesteps * n_samples, n_components) 的数组。
`transform`(series, *args[, component_mask, ...])	通过调用用户实现的 ts_transform 方法变换一个（序列）时间序列。
`ts_transform`(series, params)	调用 `transform()` 时将应用于每个时间序列的函数。
`unapply_component_mask`(series, vals[, ...])	在 apply_component_mask 方法中添加回先前由 component_mask 删除的分量。
`unstack_samples`(vals[, n_timesteps, ...])	将 stack_samples 返回的 2D 数组重新整形为形状为 (n_timesteps, n_components, n_samples) 的数组；这“撤销”了 stack_samples 的重塑操作。

静态 apply_component_mask(series, component_mask=None, return_ts=False)¶

从 series 中提取由 component_mask 指定的分量

参数

series (TimeSeries) – 要馈送到变换器的输入 TimeSeries。
component_mask (Optional[ndarray, None]) – 可选，np.ndarray 布尔掩码，形状为 (n_components, 1)，指定从 series 中提取哪些分量。series 的第 i 个分量仅在 component_mask[i] = True 时保留。如果未指定，则不执行掩码操作。
return_ts (bool) – 可选，指定应返回 TimeSeries 对象，而不是 np.ndarray。

返回

TimeSeries（如果 return_ts = True）或 np.ndarray（如果 return_ts = False），仅保留由 component_mask 指定的分量。

返回类型

masked

属性 name¶: 数据变换器的名称。

set_n_jobs(value)¶

设置变换器在处理多个 TimeSeries 时使用的处理器数量。

参数: value (int) – 新的 n_jobs 值。设置为 -1 使用所有可用核心。

set_verbose(value)¶

设置详细输出状态。

True 启用有关定标器操作进度的详细报告，False 不提供额外信息。

参数: value (bool) – 新的详细输出状态

静态 stack_samples(vals)¶

从 TimeSeries 或 TimeSeries 的 array_values 创建形状为 (n_timesteps * n_samples, n_components) 的数组。

返回数组的每一列对应于时间序列的一个分量（维度），由将与该分量相关联的所有样本连接起来形成。更具体地说，第 i 列由将 [分量_i_样本_1, 分量_i_样本_2, …, 分量_i_样本_n] 连接形成。

当实现对时间序列中每个时间步长应用完全相同更改的变换时，堆叠很有用。在这种情况下，每个分量的样本可以堆叠到单个列中，然后可以将变换应用于每列，从而在该分量的所有样本上“向量化”变换；然后可以使用 unstack_samples 方法来重新整形输出。对于依赖于 time_index 或观测值时间顺序的变换，则不应使用堆叠。

参数: vals (Union[ndarray, TimeSeries]) – 要“堆叠”的 Timeseries 或 np.ndarray，形状为 (n_timesteps, n_components, n_samples)。
返回: 形状为 (n_timesteps * n_samples, n_components) 的 np.ndarray，其中第 i 列由将 vals 中第 i 个分量的所有样本连接起来形成。
返回类型: stacked

transform(series, *args, component_mask=None, series_idx=None, **kwargs)¶

通过调用用户实现的 ts_transform 方法变换一个（序列）时间序列。

如果将 Sequence[TimeSeries] 作为输入数据传递，此函数会处理序列中多个时间序列同时进行变换的并行化。此外，如果在实例化 BaseDataTransformer 时将 mask_components 属性设置为 True，则任何提供的 component_mask` 将自动应用于每个输入 `TimeSeries；有关分量掩码的更多详细信息，请参阅“注意”。

任何额外指定的 *args 和 **kwargs 将自动传递给 ts_transform。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 要变换的（序列）时间序列。
args – 每次调用 ts_transform() 方法的附加位置参数
component_mask (Optional[np.ndarray] = None) – 可选，一个长度为 series.n_components 的 1-D 布尔 np.ndarray，指定变换应考虑底层 series 的哪些分量。如果在实例化 BaseDataTransformer 时将 mask_components 属性设置为 True，则分量掩码将自动应用于每个 TimeSeries 输入。否则，component_mask 将作为附加关键字参数提供给 ts_transform。有关更多详细信息，请参阅“注意”。
series_idx (Union[int, Sequence[int], None]) – 可选，每个时间序列的索引，对应于它们在用于拟合变换器的时间序列中的位置（用于检索适当的变换器参数）。
kwargs – 每次调用 ts_transform() 方法的附加关键字参数

返回

变换后的数据。

返回类型

Union[TimeSeries, List[TimeSeries]]

注意

如果在实例化 BaseDataTransformer 时将 mask_components 属性设置为 True，则任何提供的 component_mask` 将自动应用于要变换的每个输入 `TimeSeries；component_mask` 只是形状为 (series.n_components,) 的布尔数组，指定每个 series 的哪些分量应该使用 ts_transform 进行变换，哪些不应该。如果 component_mask[i] 为 True，则每个 series 的第 i 个分量将由 ts_transform 变换。相反，如果 component_mask[i] 为 False，则第 i 个分量在传递给 ts_transform 之前将从每个 series 中移除；在变换此掩码系列后，未变换的第 i 个分量将“添加回”到输出中。注意，只有在 ts_transform 不改变每个时间序列的时间步长数量的情况下，才能执行自动 component_mask`ing；如果发生这种情况，则变换后的和未变换的分量将无法沿着分量轴连接回来。

如果在实例化 BaseDataTransformer 时将 mask_components 设置为 False，则任何提供的 component_masks 将作为关键字参数传递给 ts_transform；用户可以手动指定 component_mask 应如何应用于每个时间序列。

静态 ts_transform(series, params)[source]¶

调用 transform() 时将应用于每个时间序列的函数。

此方法未在基类中实现，必须在派生类中实现。

该函数必须将 TimeSeries 对象作为第一个参数，将包含变换的固定和/或拟合参数的字典作为第二个参数；然后该函数应返回一个变换后的 TimeSeries 对象。

params 字典最多可以包含两个键: 1. params[‘fixed’] 存储变换的固定参数（即在调用 super().__init__() 之前在最子类中的 __init__ 方法中定义的属性）；params[‘fixed’] 本身是一个字典，其键是固定参数属性的名称。例如，如果在最子类中将 _my_fixed_param 定义为一个属性，则可以通过 params[‘fixed’][‘_my_fixed_param’] 访问此固定参数值。2. 如果变换继承自 FittableDataTransformer 类，则 params[‘fitted’] 将存储变换的拟合参数；拟合参数只是 ts_fit 函数返回的输出（无论输出是什么）。有关拟合参数的更多详细信息，请参阅 FittableDataTransformer。

提供给 transform 方法的任何位置/关键字参数都将作为位置/关键字参数传递给 ts_transform；因此，如果位置/关键字参数传递给 transform，则 ts_transform 也应接受 *args 和/或 **kwargs。注意，如果 BaseDataTransformer 的 mask_component 属性设置为 False，则提供给 transform 的 component_mask 将作为附加关键字参数传递给 ts_transform。

BaseDataTransformer 类包含一些在实现 ts_transform 函数时可能很有用的辅助方法

1. apply_component_mask 和 unapply_component_mask 方法，分别将 component_mask 应用和“取消应用”到 TimeSeries；如果在 BaseDataTransformer 中将 mask_component 属性设置为 True，则这些方法会在 transform 中自动调用，但如果将 mask_components 设置为 False 并希望手动指定如何将 component_mask 应用于 TimeSeries，则可能需要手动调用它们。2. stack_samples 方法，将 TimeSeries 中的所有样本沿着分量轴堆叠，以便 TimeSeries 的形状从 (n_timesteps, n_components, n_samples) 变为 (n_timesteps, n_components * n_samples)。如果正在实现逐点变换（即时间 t 的值变换仅取决于时间 t 处时间序列的值），则此堆叠很有用。变换后，堆叠的 TimeSeries 可以使用 unstack_samples 方法“取消堆叠”。

参数

series (TimeSeries) – 要变换的时间序列。
params (Mapping[str, Any]) – 包含变换函数参数的字典。固定参数（即在调用 super.__init__() 之前在变换的最子类中定义的属性）存储在 ‘fixed’ 键下。如果变换继承自 FittableDataTransformer 类，则变换的拟合参数（即 ts_fit 返回的值）存储在 ‘fitted’ 键下。
args – 调用时除了 series 外提供的任何位置参数
kwargs – 提供给 transform 的任何附加关键字参数。注意，如果 BaseDataTransformer 的 mask_component 属性设置为 False，则 component_mask 将作为关键字参数传递。

注意

此方法设计为静态方法而非实例方法，以便在定标器实例存储大量数据时也能实现高效并行化。使用实例方法意味着通过多个进程复制实例数据，这很容易引入瓶颈并抵消并行化优势。

返回类型: TimeSeries

静态 unapply_component_mask(series, vals, component_mask=None)¶

在 apply_component_mask 方法中添加回先前由 component_mask 删除的分量。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 馈送到变换器的输入 TimeSeries。
vals (Union[ndarray, Sequence[ndarray], TimeSeries, Sequence[TimeSeries]]) – 要“取消掩码”的 np.ndarray 或 TimeSeries。
component_mask (Optional[ndarray, None]) – 可选，np.ndarray 布尔掩码，形状为 (n_components, 1)，指定从 series 中提取了哪些分量。如果给定，将 vals 插入回原始数组的列中。如果未指定，则不执行“取消掩码”操作。

返回

TimeSeries（如果 vals 是 TimeSeries）或 np.ndarray（如果 vals 是 np.ndarray），之前由 component_mask 删除的分量现已“添加回”。

返回类型

unmasked

静态 unstack_samples(vals, n_timesteps=None, n_samples=None, series=None)¶

将 stack_samples 返回的 2D 数组重新整形为形状为 (n_timesteps, n_components, n_samples) 的数组；这“撤销”了 stack_samples 的重塑操作。必须指定 n_components、n_samples 或 series 之一。

参数

vals (ndarray) – 要“取消堆叠”的 np.ndarray，形状为 (n_timesteps * n_samples, n_components)。
n_timesteps (Optional[int, None]) – 可选，最初传递给 stack_samples 的数组中的时间步长数量。如果指定了 series，则不需要提供此参数。
n_samples (Optional[int, None]) – 可选，最初传递给 stack_samples 的数组中的样本数量。如果指定了 series，则不需要提供此参数。
series (Optional[TimeSeries, None]) – 可选，用于创建 vals 的 TimeSeries 对象；n_samples 会从此对象推断。

返回

形状为 (n_timesteps, n_components, n_samples) 的 np.ndarray。

返回类型

unstacked

静态协变量变换器

管道