差异转换器¶

class darts.dataprocessing.transformers.diff.Diff(lags=1, dropna=True, name='Diff', n_jobs=1, verbose=False)[源代码]¶

基类：FittableDataTransformer, InvertibleDataTransformer

差分数据转换器。

差分通常应用于时间序列以使其平稳；有关更多详细信息，请参见 [1]。该变换独立地应用于时间序列的每个维度（分量）和样本。

提示

Diff 按顺序对时间序列应用一系列 \(m\) 滞后差分操作（即 \(y\prime_t = y_t - y_{t-m}\)）；关于滞后差分的更多细节，请参阅 [2]。每个差分操作使用的 \(m\) 值由 lags 参数指定；例如，设置 lags = [1, 12] 首先对时间序列应用 1 滞后差分，然后对 1 滞后差分后的序列应用 12 滞后差分。

lags 中的每个元素代表一个一阶差分操作，因此差分的’总阶数’等于 len(lags)。要指定二阶差分（即相当于 series.diff(n=2)），则应指定 `lags = [1,1]`（即两个连续的1阶差分）；有关二阶差分的更多详细信息，请参见 [3]。

在计算每个 \(m\) 滞后差分时，时间序列的前 \(m\) 个值会’丢失’，因为这些值无法计算差分。因此，通过 Diff(lags=lags) 转换的 series 的长度将是 series.n_timesteps - sum(lags)。

参数

name (str) – 变压器的特定名称
lags (Union[int, Sequence[int]]) – 指定每个一阶差分操作使用的滞后值（即 \(y'_t = y_t - y_{t-m}\) 中的 \(m\) 值）。如果提供一个整数，则只进行一次具有此指定滞后值的差分操作。如果提供一个整数序列，则使用 lags 中的每个值依次进行多次差分操作。例如，指定 lags = [2, 3] 将有效地计算 series.diff(n=1, periods=2).diff(n=1, periods=3)。
dropna (bool) – 可选地，指定是否应删除无法进行差分的值（即在序列开始时）。请注意，如果 dropna = True，则不能指定 component_mask，因为未差分的组件的长度将与差分组件的长度不同。
n_jobs (int) – 要并行运行的作业数量。仅当输入为 Sequence[TimeSeries] 时才会创建并行作业，并行化不同 TimeSeries 的操作。默认为 1`（顺序执行）。将参数设置为 `-1 表示使用所有可用处理器。注意：对于少量数据，并行化开销可能会最终增加总所需时间。
verbose (bool) – 是否打印操作进度

实际案例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.dataprocessing.transformers import Diff
>>> series = AirPassengersDataset().load()
>>> first_order_diff = Diff(lags=1, dropna=True).fit_transform(series)
>>> print(first_order_diff.head())
<TimeSeries (DataArray) (Month: 5, component: 1, sample: 1)>
array([[[ 6.]],
    [[14.]],
    [[-3.]],
    [[-8.]],
    [[14.]]])
Coordinates:
* Month      (Month) datetime64[ns] 1949-02-01 1949-03-01 ... 1949-06-01
* component  (component) object '#Passengers'
>>> second_order_diff = Diff(lags=[1, 2], dropna=False).fit_transform(series)
>>> print(second_order_diff.head())
<TimeSeries (DataArray) (Month: 5, component: 1, sample: 1)>
array([[[ nan]],
    [[ nan]],
    [[ nan]],
    [[ -9.]],
    [[-22.]]])
Coordinates:
* Month      (Month) datetime64[ns] 1949-01-01 1949-02-01 ... 1949-05-01
* component  (component) object '#Passengers'

引用

1: https://otexts.com/fpp2/stationarity.html
2: https://otexts.com/fpp2/stationarity.html#seasonal-differencing
3: https://otexts.com/fpp2/stationarity.html#second-order-differencing

属性

name

数据转换器的名称。

方法

`apply_component_mask`(series[, ...])	从 series 中提取由 component_mask 指定的组件
`fit`(series, *args[, component_mask])	通过调用用户实现的 ts_fit 方法，将转换器拟合到一个（序列的）`TimeSeries`。
`fit_transform`(series, *args[, 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_fit`(series, params, **kwargs)	当调用 `fit()` 时，将应用于每个序列的函数。
`ts_inverse_transform`(series, params, **kwargs)	当调用 `inverse_transform()` 时，将应用于每个序列的函数。
`ts_transform`(series, params, **kwargs)	当调用 `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

fit(series, *args, component_mask=None, **kwargs)¶

通过调用用户实现的 ts_fit 方法，将转换器拟合到一个（序列的）`TimeSeries`。

ts_fit 返回的拟合参数存储在 self._fitted_params 属性中。如果将 Sequence[TimeSeries] 作为 series 数据传递，则会发生以下两种结果之一：

1. If the global_fit attribute was set to False, then a different set of parameters will be individually fitted to each TimeSeries in the Sequence. In this case, this function automatically parallelises this fitting process over all of the multiple TimeSeries that have been passed. 2. If the global_fit attribute was set to True, then all of the TimeSeries objects will be used fit a single set of parameters.

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – （序列的）系列以适应变换器。
args – 用于 ts_fit() 方法的附加位置参数
component_mask (Optional[np.ndarray] = None) – 可选地，一个长度为 series.n_components 的 1-D 布尔型 np.ndarray，用于指定变换应拟合 series 的哪些基础组件。
kwargs – 用于 ts_fit() 方法的额外关键字参数

返回

拟合的转换器。

返回类型

FittableDataTransformer

fit_transform(series, *args, component_mask=None, **kwargs)¶

将转换器拟合到（序列的）系列并返回转换后的输入。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 要转换的（序列）系列。
args – 传递给 ts_transform() 和 ts_fit() 方法的额外位置参数。
component_mask (Optional[np.ndarray] = None) – 可选地，一个长度为 series.n_components 的 1-D 布尔型 np.ndarray，用于指定变换应拟合和应用于 series 的哪些底层组件。
kwargs – 传递给 ts_transform() 和 ts_fit() 方法的额外关键字参数。

返回

转换后的数据。

返回类型

Union[TimeSeries, Sequence[TimeSeries]]

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

static ts_fit(series, params, **kwargs)[源代码]¶

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

如果 global_fit 属性设置为 False，那么 ts_fit 应该接受一个 TimeSeries 作为第一个参数，并返回一组适合该单独 TimeSeries 的参数。相反，如果 global_fit 属性设置为 True，那么 ts_fit 应该接受一个 Sequence[TimeSeries]，并返回一组适合所有提供的 TimeSeries 的参数。所有这些参数将存储在 self._fitted_params 中，这些参数可以在后续的转换步骤中使用。

无论 global_fit 属性设置为 True 还是 False，ts_fit 也应该接受一个包含固定参数值的字典作为第二个参数（即 `params[‘fixed’] 包含数据转换器的固定参数）。

传递给 fit 方法的任何额外位置和/或关键字参数都将作为位置/关键字参数传递给 ts_fit。

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

如果在派生类中添加了更多参数作为输入，则应相应地重新定义 _fit_iterator()，以生成此函数所需的参数（有关详细信息，请参阅 _fit_iterator()）

参数

(Union[TimeSeries (series) – TimeSeries 是缩放器将拟合的对象。
Sequence[TimeSeries]]) – TimeSeries 是缩放器将拟合的对象。

提示

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

返回类型: Any

static ts_inverse_transform(series, params, **kwargs)[源代码]¶

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

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

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

Box-Cox 变换器

可适应数据转换器基类