可逆数据转换器基类¶

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_inverse_transform() 方法的实现方式应与 ts_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`s 应用于传递给 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) – 输入 TimeSeries，将馈送到转换器。
component_mask (Optional[ndarray, None]) – 可选，形状为 (n_components, 1) 的 np.ndarray 布尔掩码，指定要从 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

inverse_transform(series, *args, component_mask=None, series_idx=None, **kwargs)[源]¶

通过调用用户实现的 ts_inverse_transform 方法对（一系列）时间序列进行逆转换。

如果输入数据是序列或列表的列表，此函数负责并行处理序列中的多个时间序列。此外，如果在实例化 InvertibleDataTransformer 时将 mask_components 属性设置为 True，则任何提供的 component_mask`s 将自动应用于每个输入 TimeSeries；关于分量掩码的更多详细信息，请参阅“注意”。

任何额外指定的 *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 的一维布尔型 np.ndarray，指定逆转换应考虑底层时间序列的哪些分量。
series_idx (Union[int, Sequence[int], None]) – 可选，每个时间序列对应于用于拟合转换器的序列中的位置的索引（用于检索相应的转换器参数）。
kwargs – ts_inverse_transform() 方法的附加关键字参数

返回

逆转换后的数据。

返回类型

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

注意

如果在实例化 InvertibleDataTransformer 时将 mask_components 属性设置为 True，则任何提供的 component_mask`s 将自动应用于要转换的每个 TimeSeries 输入；component_mask`s 只是形状为 (series.n_components,) 的布尔数组，用于指定每个 series 的哪些分量应使用 ts_inverse_transform 进行转换，哪些不应。如果 component_mask[i] 为 True，则每个 series 的第 i 个分量将由 ts_inverse_transform 进行转换。反之，如果 component_mask[i] 为 False，则在将每个 series 传递给 ts_inverse_transform 之前，第 i 个分量将从 series 中移除；在转换此掩码系列后，未转换的第 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 或形状为 (n_timesteps, n_components, n_samples) 的 np.ndarray。
返回: 形状为 (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`s 将自动应用于每个输入 TimeSeries；关于分量掩码的更多详细信息，请参阅“注意”。

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

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 要转换的（一系列）时间序列。
args – 每次调用 ts_transform() 方法的附加位置参数
component_mask (Optional[np.ndarray] = None) – 可选，一个长度为 series.n_components 的一维布尔型 np.ndarray，指定转换应考虑底层时间序列的哪些分量。如果在实例化 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`s 将自动应用于要转换的每个 TimeSeries 输入；component_mask`s 只是形状为 (series.n_components,) 的布尔数组，用于指定每个 series 的哪些分量应使用 ts_transform 进行转换，哪些不应。如果 component_mask[i] 为 True，则每个 series 的第 i 个分量将由 ts_transform 进行转换。反之，如果 component_mask[i] 为 False，则在将每个 series 传递给 ts_transform 之前，第 i 个分量将从 series 中移除；在转换此掩码系列后，未转换的第 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’] 存储转换的固定参数（即在调用 super().__init__() 之前在最子类别 __init__ 中定义的属性）；params[‘fixed’] 本身是一个字典，其键是固定参数属性的名称。例如，如果在最子类别中将 _my_fixed_param 定义为属性，则可以通过 params[‘fixed’][‘_my_fixed_param’] 访问此固定参数值。2. 如果转换继承自 FittableDataTransformer 类，则 params[‘fitted’] 将存储转换的拟合参数；拟合参数就是 ts_fit 函数返回的输出，无论这些输出是什么。关于拟合参数的更多详细信息，请参阅 FittableDataTransformer。

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

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

参数

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’] 存储转换的固定参数（即在调用 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_components 属性设置为 False，则提供给 transform 的 component_mask 将作为附加关键字参数传递给 ts_transform。

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

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

参数

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

返回

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) – 要“取消堆叠”的形状为 (n_timesteps * n_samples, n_components) 的 np.ndarray。
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

上一条

可拟合数据转换器基类

下一条

Mapper 和 InvertibleMapper