可逆数据变换器基类

class darts.dataprocessing.transformers.invertible_data_transformer.InvertibleDataTransformer(name='InvertibleDataTransformer', n_jobs=1, verbose=False, parallel_params=False, mask_components=True)[源代码]

基类：BaseDataTransformer

可逆变换器的抽象类。

所有派生类都必须实现静态方法 ts_transform() 和 ts_inverse_transform()。有关如何实现 ts_transform() 方法的信息，请参阅 BaseDataTransformer 文档。

应该以与 ts_transform() 方法几乎相同的方式实现 ts_inverse_transform() 方法：它应该接受一个 TimeSeries 作为第一个参数，以及一个固定参数的字典（如果变换也继承自 FittableDataTransformer，则还包括拟合参数）作为第二个参数。此外，如果预期传递额外的位置/关键字参数，ts_inverse_transform() 还应该接受 *args 和 **kwargs。ts_inverse_transform() 和 ts_transform() 之间的唯一区别是前者应该 ‘撤销’ 后者对 TimeSeries 所做的变换。请参阅 ts_inverse_transform() 文档以获取更多信息。

此类负责在可能的情况下并行化多个 TimeSeries 的转换。

参数

  • name (str) – 数据转换器的名称

  • n_jobs (int) – 要并行运行的作业数量。只有在将 Sequence[TimeSeries] 作为输入传递给方法时，才会创建并行作业，并行处理不同的 TimeSeries 操作。默认为 1`（顺序执行）。将参数设置为 `-1 意味着使用所有可用的处理器。注意：对于少量数据，并行化开销可能会最终增加总所需时间。

  • verbose (bool) – 可选地，是否打印操作进度

  • parallel_params (Union[bool, Sequence[str]]) – 可选地，指定哪些固定参数（即在子类中最底层的 __init__ 中初始化的属性）在不同的并行作业中取不同的值。由 parallel_params 指定的固定参数被假定为一个 Sequence 值，该值应为每个并行作业中的该参数使用；此 Sequence 的长度应等于并行作业的数量。如果 parallel_params=True，每个固定参数将为每个并行作业取不同的值。如果 parallel_params=False，每个固定参数将为每个并行作业取相同的值。如果 parallel_params 是一个固定属性名称的 Sequence，则只有那些指定的属性名称会在不同的并行作业之间取不同的值。

  • mask_components (bool) – 可选地，是否自动应用提供的 component_mask 到传递给 transform、fit、inverse_transform 或 fit_transform 的 TimeSeries 输入。如果为 True，任何指定的 component_mask 将在传递给调用方法之前应用于每个输入时间序列；被屏蔽的组件也将在返回的 TimeSeries 中自动 ‘解屏蔽’。如果为 False，则 component_mask`（如果提供）将作为关键字参数传递，但不会自动应用于输入时间序列。有关更多详细信息，请参阅 `BaseDataTransformer 的 apply_component_mask 方法。

提示

注意：ts_transform() 和 ts_inverse_transform() 方法被设计为静态方法而不是实例方法，以便在缩放器实例存储了不可忽略的数据量时也能进行有效的并行化。使用实例方法将意味着通过多个进程复制实例的数据，这很容易引入瓶颈并抵消并行化的好处。

示例

>>> from darts.dataprocessing.transformers import InvertibleDataTransformer
>>> from darts.utils.timeseries_generation import linear_timeseries
>>>
>>> class SimpleTransform(InvertibleDataTransformer):
>>>
>>>         def __init__(self, a):
>>>             self._a = a
>>>             super().__init__()
>>>
>>>         @staticmethod
>>>         def ts_transform(series, params, **kwargs):
>>>             a = params['fixed']['_a']
>>>             b = kwargs.pop('b')
>>>             return a*series + b
>>>
>>>         @staticmethod
>>>         def ts_inverse_transform(series, params, **kwargs):
>>>             a = params['fixed']['_a']
>>>             b = kwargs.pop('b')
>>>             return (series - b) / a
>>>
>>> series = linear_timeseries(length=5)
>>> print(series)
<TimeSeries (DataArray) (time: 5, component: 1, sample: 1)>
array([[[0.  ]],

[[0.25]],

[[0.5 ]]

[[0.75]],

[[1. ]]])

坐标: * time (time) datetime64[ns] 2000-01-01 2000-01-02 … 2000-01-05 * component (component) object ‘linear’ 没有坐标的维度: sample .. 属性:: static_covariates

无

hierarchy

无

>>> transform = SimpleTransform(a=2)
>>> series = transform.transform(series, b=3)
>>> print(series)
<TimeSeries (DataArray) (time: 5, component: 1, sample: 1)>
array([[[3. ]],

[[3.5]],

[[4. ]]

[[4.5]],

[[5. ]]])

坐标: * time (time) datetime64[ns] 2000-01-01 2000-01-02 … 2000-01-05 * component (component) object ‘linear’ 没有坐标的维度: sample .. 属性:: static_covariates

无

hierarchy

无

>>> series = transform.inverse_transform(series, b=3)
>>> print(series)
<TimeSeries (DataArray) (time: 5, component: 1, sample: 1)>
array([[[0.  ]],

[[0.25]],

[[0.5 ]]

[[0.75]],

[[1. ]]])

坐标: * time (time) datetime64[ns] 2000-01-01 2000-01-02 … 2000-01-05 * component (component) object ‘linear’ 没有坐标的维度: sample .. 属性:: static_covariates

无

hierarchy

无

属性

name

数据转换器的名称。

方法

apply_component_mask(series[, ...])

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

inverse_transform(series, *args[, ...])

通过调用用户实现的 ts_inverse_transform 方法，对（序列的）序列进行逆变换。

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_inverse_transform(series, params)

当调用 inverse_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

inverse_transform(series, *args, component_mask=None, **kwargs)[源代码]

通过调用用户实现的 ts_inverse_transform 方法，对（序列的）序列进行逆变换。

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

任何额外指定的 *args 和 **kwargs 都会自动传递给 ts_inverse_transform。

参数

  • series (Union[TimeSeries, Sequence[TimeSeries], Sequence[Sequence[TimeSeries]]]) – 要进行逆变换的序列。如果是一个单独的 TimeSeries，则返回一个单独的序列。如果是一个 TimeSeries 序列，则返回一个序列列表。序列的顺序应与用于拟合变换器的序列相同。如果是一个 TimeSeries 列表的列表，则返回一个序列列表的列表。例如，这可以是使用多个序列时 ForecastingModel.historical_forecasts() 的输出。每个内部列表应包含与同一序列相关的 TimeSeries。内部列表的顺序应与用于拟合变换器的序列相同。

  • args – 用于 ts_inverse_transform() 方法的附加位置参数

  • component_mask (Optional[np.ndarray] = None) – 可选地，一个长度为 series.n_components 的 1-D 布尔型 np.ndarray，用于指定逆变换应考虑 series 的哪些成分。

  • kwargs – 用于 ts_inverse_transform() 方法的额外关键字参数

返回

逆变换后的数据。

返回类型

Union[TimeSeries, List[TimeSeries], List[List[TimeSeries]]]

提示

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

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

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 应用于每个序列。

abstract static ts_inverse_transform(series, params)[源代码]

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

该函数必须将 TimeSeries 对象作为第一个参数，并将包含转换的固定和/或拟合参数的字典作为第二个参数；然后，该函数应返回一个逆转换的 TimeSeries 对象（即 ts_inverse_transform 应撤销 ts_transform 执行的转换）。

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_inverse_transform；因此，如果传递了位置/关键字参数给 transform，ts_inverse_transform 也应该接受 *args 和/或 **kwargs。注意，如果 InvertibleDataTransformer 的 mask_components 属性设置为 False，那么提供给 transform 的 component_mask 将作为额外的关键字参数传递给 ts_inverse_transform。

BaseDataTransformer 类，InvertibleDataTransformer 继承自该类，包含一些辅助方法，这些方法在实现 ts_inverse_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 InvertibleDataTransformer 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 inverse 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 – 提供给 inverse_transform 的任何额外关键字参数。

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

提示

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

返回类型

TimeSeries

abstract 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

上一页

可适应数据转换器基类

下一页

Mapper 和 InvertibleMapper