数据转换器基类¶

class darts.dataprocessing.transformers.base_data_transformer.BaseDataTransformer(name='BaseDataTransformer', n_jobs=1, verbose=False, parallel_params=False, mask_components=True)[source]¶

基类：ABC

数据转换器的抽象类。

所有派生类都必须实现静态方法 ts_transform()；然后可以通过调用 transform() 方法将这个实现的方法应用于 TimeSeries 或 Sequence[TimeSeries] 输入。在内部，transform() 会对传递给它的所有 TimeSeries 输入并行执行 func:ts_transform。关于如何在用户自定义类中实现此方法的详细信息，请参阅 func:ts_transform 方法文档。

在调用 transform() 之前需要先拟合的数据转换器应改派生自 FittableDataTransformer。可逆的数据转换器应改派生自 InvertibleDataTransformer。同时可拟合和可逆的转换器应同时继承自 FittableDataTransformer 和 InvertibleDataTransformer。

所有数据转换器都可以存储 固定参数，这些参数会自动传递给 func:ts_transform；数据转换器对象的固定参数被认为是子类中最深层类 __init__ 方法中定义的所有属性，位于调用 super().__init__ *之前*。然后可以在 func:ts_transform 方法中通过 params 字典参数访问固定参数值。更具体地说，params[‘fixed’] 存储一个包含所有固定参数值的字典，其中键是每个固定参数的属性名称（例如，通过 params[‘fixed’][‘_my_param’] 访问 self._my_param 固定参数属性）。

继承自 FittableDataTransformer 的数据转换器也可以在固定参数旁边存储拟合参数；有关详细信息，请参阅 FittableDataTransformer 文档。

注意：ts_transform() 方法被设计为静态方法而非实例方法，以便在定标器实例存储大量数据时也能实现高效并行化。使用实例方法意味着要在多个进程之间复制实例的数据，这很容易引入瓶颈并抵消并行化的好处。

参数

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（如果提供）将作为关键字参数传递，但不会自动应用于输入时间序列。有关详细信息，请参阅 apply_component_mask。

示例

>>> from darts.dataprocessing.transformers import BaseDataTransformer
>>> from darts.utils.timeseries_generation import linear_timeseries
>>>
>>> class SimpleTransform(BaseDataTransformer):
>>>
>>>         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
>>>
>>> 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

None

hierarchy¶: None

>>> series = SimpleTransform(a=2).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

None

hierarchy¶: None

属性

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 的塑形。

static apply_component_mask(series, component_mask=None, return_ts=False)[source]¶

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

参数

series (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

property name¶: 数据转换器的名称。

set_n_jobs(value)[source]¶

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

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

set_verbose(value)[source]¶

设置详细程度状态。

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

参数: value (bool) – 新的详细程度状态

static stack_samples(vals)[source]¶

从 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)[source]¶

通过调用用户实现的 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 的一维布尔 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` 将自动应用于每个输入到 transform 的 `TimeSeries；component_mask` 只是形状为 (series.n_components,) 的布尔数组，用于指定每个 series 的哪些组件应使用 ts_transform 进行转换，哪些不应转换。如果 component_mask[i] 为 True，则每个 series 的第 i 个组件将由 ts_transform 转换。反之，如果 component_mask[i] 为 False，则在传递给 ts_transform 之前将从每个 series 中移除第 i 个组件；在转换此屏蔽后的时间序列后，未转换的第 i 个组件将“添加回”输出中。请注意，自动 component_mask`ing 只能在 `ts_transform 不改变每个时间序列的时间步数时执行；如果发生这种情况，转换后和未转换的组件将无法沿组件轴连接在一起。

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

abstract static ts_transform(series, params)[source]¶

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

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

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

params 字典可以包含最多两个键: 1. params[‘fixed’] 存储转换的固定参数（即在调用 super.__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` 应用和“解除应用”到 `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 的时间序列值），则此堆叠很有用。转换后，可以使用 unstack_samples 方法对堆叠后的 TimeSeries 进行“解除堆叠”。

参数

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

备注

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

返回类型: TimeSeries

static unapply_component_mask(series, vals, component_mask=None)[source]¶

添加回之前在 apply_component_mask 方法中通过 component_mask 移除的组件。

参数

series (Union[TimeSeries, Sequence[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)[source]¶

将 stack_samples 返回的 2D 数组重新塑形回形状为 (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

darts.dataprocessing.transformers.base_data_transformer.component_masking(transformer_method)[source]¶: 将组件屏蔽应用于馈送到任何 transform 方法的时间序列，然后为最终输出时间序列恢复屏蔽。

上一个

数据转换器

下一个

Box-Cox 转换器