窗口变换器

class 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)[源代码]

基类：BaseDataTransformer

一个应用于 TimeSeries 或 TimeSeries 序列的窗口变换的转换器。它期望一个字典或字典列表，指定要应用的窗口变换。序列中的所有系列将使用相同的变换进行转换。

参数

  • transforms (Union[dict, List[dict]]) –

    一个字典或字典列表。每个字典指定一个不同的窗口变换。

    字典可以包含以下键：

    "function"

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

    "mode"

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

    "components"

    可选。指定应在其上应用转换的时间序列组件的字符串或字符串列表。如果未指定，转换将应用于所有组件。

    "function_name"

    可选。一个字符串，指定作为转换输出名称一部分引用的函数名称。例如，给定一个用户提供的函数转换，在组件“comp”上使用5个滚动窗口大小，默认的转换输出名称是“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）。Darts 重用了 pandas 的默认值，即在“rolling”和“expanding”模式下为1，在“ewm”模式下为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]) – 指定如何处理由窗口转换在结果时间序列开始时添加的缺失值。默认情况下，Darts 会在结果时间序列中保留 NaNs。此参数可以是以下之一： * :"dropna": 截断时间序列并删除包含缺失值的时间步。如果多个列包含不同数量的缺失值，则仅删除最少数量的行。此操作可能会减少结果时间序列的长度。 * :"bfill" 或 "backfill": 指定应使用最后一个转换的有效观察值填充 NaNs。如果原始时间序列以 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 返回的二维数组重新整形为形状为 (n_timesteps, n_components, n_samples) 的数组；这 '撤销' 了 stack_samples 的重塑。
static apply_component_mask(series, component_mask=None, return_ts=False)

从 series 中提取由 component_mask 指定的组件

参数

  • series (TimeSeries) – 输入时间序列以供转换器处理。

  • component_mask (Optional[ndarray, None]) – 可选地，形状为 (n_components, 1) 的 np.ndarray 布尔掩码，指定从 series 中提取哪些组件。仅当 component_mask[i] = True 时，保留 series 的第 i 个组件。如果未指定，则不执行掩码操作。

  • return_ts (bool) – 可选地，指定应返回 TimeSeries，而不是 np.ndarray。

返回

TimeSeries`（如果 `return_ts = True）或 np.ndarray`（如果 `return_ts = False），仅保留由 component_mask 指定的那些组件。

返回类型

masked

property name

数据转换器的名称。

set_n_jobs(value)

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

参数

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

set_verbose(value)

设置详细状态。

True 表示启用关于缩放器操作进度的详细报告，False 表示不提供额外信息。

参数

value (bool) – 新的详细状态

static stack_samples(vals)

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

返回数组的每一列对应于序列的一个分量（维度），并且由将所有与该分量相关的样本连接在一起形成。更具体地说，第 i 列由连接 [component_i_sample_1, component_i_sample_2, …, component_i_sample_n] 形成。

堆叠在实现对时间序列中每个时间步应用相同更改的转换时非常有用。在这种情况下，每个组件的样本可以堆叠在一起形成单个列，然后可以对每个列应用转换，从而在所有该组件的样本上’向量化’转换；然后可以使用 unstack_samples 方法来重塑输出。对于依赖于 time_index 或观测值的时间顺序的转换，不应使用堆叠。

参数

vals (Union[ndarray, TimeSeries]) – Timeseries 或 np.ndarray 形状为 (n_timesteps, n_components, n_samples) 的数组将被 ‘堆叠’。

返回

np.ndarray 形状为 (n_timesteps * n_samples, n_components)，其中第 i 列是通过将 vals 中第 i 个分量的所有样本连接形成的。

返回类型

stacked

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

通过调用用户实现的 ts_transform 方法，转换一个（序列的）序列。

如果输入数据是 Sequence[TimeSeries] ，此函数会负责并行处理序列中多个时间序列的转换。此外，如果在实例化 BaseDataTransformer 时将 mask_components 属性设置为 True，那么任何提供的 component_mask 都将自动应用于每个输入的 TimeSeries；请参阅 ‘Notes’ 以获取有关组件掩码的更多详细信息。

任何额外指定的 *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。详见 ‘Notes’。

  • kwargs – 每个 ts_transform() 方法调用的额外关键字参数

返回

转换后的数据。

返回类型

Union[TimeSeries, List[TimeSeries]]

提示

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

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

static ts_transform(series, params)[源代码]

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

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

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

params 字典 可以 包含最多两个键：

1. params[‘fixed’] stores the fixed parameters of the transformation (i.e. attributed defined in the __init__ method of the child-most class before super().__init__ is called); params[‘fixed’] is a dictionary itself, whose keys are the names of the fixed parameter attributes. For example, if _my_fixed_param is defined as an attribute in the child-most class, then this fixed parameter value can be accessed through params[‘fixed’][‘_my_fixed_param’]. 2. If the transform inherits from the FittableDataTransformer class, then params[‘fitted’] will store the fitted parameters of the transformation; the fitted parameters are simply the output(s) returned by the ts_fit function, whatever those output(s) may be. See FittableDataTransformer for further details about fitted parameters.

传递给 transform 方法的任何位置/关键字参数都会作为位置/关键字参数传递给 ts_transform；因此，如果传递了位置/关键字参数，ts_transform 也应该接受 *args 和/或 **kwargs。请注意，如果 BaseDataTransformer 的 mask_components 属性设置为 False，那么传递给 transform 的 component_mask 将作为额外的关键字参数传递给 ts_transform。

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

1. The apply_component_mask and unapply_component_mask methods, which apply and ‘unapply’ component_mask`s to a `TimeSeries respectively; these methods are automatically called in transform if the mask_component attribute of BaseDataTransformer is set to True, but you may want to manually call them if you set mask_components to False and wish to manually specify how component_mask`s are applied to a `TimeSeries. 2. The stack_samples method, which stacks all the samples in a TimeSeries along the component axis, so that the TimeSeries goes from shape (n_timesteps, n_components, n_samples) to shape (n_timesteps, n_components * n_samples). This stacking is useful if a pointwise transform is being implemented (i.e. transforming the value at time t depends only on the value of the series at that time t). Once transformed, the stacked TimeSeries can be ‘unstacked’ using the unstack_samples method.

参数

  • series (TimeSeries) – 要转换的系列。

  • params (Mapping[str, Any]) – 包含转换函数参数的字典。固定参数（即在调用 super.__init__() 之前在转换的最子类中定义的属性）存储在 ‘fixed’ 键下。如果转换继承自 FittableDataTransformer 类，那么转换的拟合参数（即 ts_fit 返回的值）存储在 ‘fitted’ 键下。

  • args – 除了 series 之外提供的任何位置参数

  • kwargs – 提供给 transform 的任何额外关键字参数。请注意，如果 BaseDataTransformer 的 mask_component 属性设置为 False，那么 component_mask 将作为关键字参数传递。

提示

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

返回类型

TimeSeries

static unapply_component_mask(series, vals, component_mask=None)

在 apply_component_mask 方法中，恢复之前被 component_mask 移除的组件。

参数

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 输入到转换器中的时间序列。

  • vals (Union[ndarray, Sequence[ndarray], TimeSeries, Sequence[TimeSeries]]) – np.ndarray 或 TimeSeries 以 ‘unmask’

  • component_mask (Optional[ndarray, None]) – 可选地，形状为 (n_components, 1) 的 np.ndarray 布尔掩码，指定从 series 中提取了哪些组件。如果给出，将 vals 插回到原始数组的列中。如果未指定，则不进行 ‘unmasked’。

返回

TimeSeries`（如果 `vals 是 TimeSeries）或 np.ndarray`（如果 `vals 是 np.ndarray），这些组件之前通过 component_mask 被移除，现在被’重新添加’。

返回类型

unmasked

static unstack_samples(vals, n_timesteps=None, n_samples=None, series=None)

将 stack_samples 返回的二维数组重新整形为形状为 (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 由此推断。

返回

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

返回类型

unstacked

上一页

静态协变量转换器

下一页

管道