差分变换器¶

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

基类: 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\) 值）。如果提供单个 int，则仅使用此指定的滞后值执行一个差分操作。如果提供 int 序列，则使用 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]) – 可选参数，np.ndarray 布尔掩码，形状为 (n_components, 1)，指定从 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

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

通过调用用户实现的 ts_fit 方法，将变换器拟合到（一个或多个）TimeSeries。

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

1. 如果 global_fit 属性设置为 False，则将为序列中的每个 TimeSeries 单独拟合一组不同的参数。在这种情况下，此函数会自动并行化此拟合过程，以处理传入的多个 TimeSeries。 2. 如果 global_fit 属性设置为 True，则将使用所有 TimeSeries 对象来拟合一组参数。

参数

series (Union[TimeSeries, Sequence[TimeSeries]]) – 用于拟合变换器的一个或多个序列。
args – ts_fit() 方法的附加位置参数
component_mask (Optional[np.ndarray] = None) – 可选参数，一个长度为 series.n_components 的一维布尔 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 的一维布尔 np.ndarray，指定应将变换器拟合和应用于基础 series 的哪些分量。
kwargs – 传递给 ts_transform() 和 ts_fit() 方法的附加关键字参数。

返回

变换后的数据。

返回类型

Union[TimeSeries, Sequence[TimeSeries]]

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

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

如果输入数据是序列或列表的列表，此函数负责并行变换序列中的多个系列。此外，如果在实例化 InvertibleDataTransformer 时将 mask_components 属性设置为 True，则任何提供的 component_mask 将自动应用于每个输入 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 的哪些分量。
series_idx (Union[int, Sequence[int], None]) – 可选参数，每个系列在其用于拟合变换器的序列中的索引（以检索适当的变换器参数）。
kwargs – ts_inverse_transform() 方法的附加关键字参数

返回

逆变换后的数据。

返回类型

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

注意

如果在实例化 InvertibleDataTransformer 时将 mask_components 属性设置为 True，则任何提供的 component_mask 将自动应用于输入到 transform 的每个 TimeSeries；component_mask 只是形状为 (series.n_components,) 的布尔数组，指定每个 series 的哪些分量应使用 ts_inverse_transform 进行变换，哪些不应。如果 component_mask[i] 为 True，则每个 series 的第 i 个分量将由 ts_inverse_transform 变换。相反，如果 component_mask[i] 为 False，则在传递给 ts_inverse_transform 之前，第 i 个分量将从每个 series 中删除；在变换此掩码系列后，未变换的第 i 个分量将“添加回”到输出中。请注意，仅当 ts_inverse_transform 不改变每个系列的时间步长数时，才能执行自动 component_mask 操作；如果时间步长数发生变化，则无法将变换后和未变换的分量沿分量轴连接回去。

如果在实例化 InvertibleDataTransformer 时将 mask_components 设置为 False，则任何提供的 component_mask 将作为关键字参数传递给 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 将自动应用于每个输入 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 之前，第 i 个分量将从每个 series 中删除；在变换此掩码系列后，未变换的第 i 个分量将“添加回”到输出中。请注意，仅当 ts_transform 不改变每个系列的时间步长数时，才能执行自动 component_mask 操作；如果时间步长数发生变化，则无法将变换后和未变换的分量沿分量轴连接回去。

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

static ts_fit(series, params, **kwargs)[source]¶

调用 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) – 缩放器将基于其拟合的时间序列。
Sequence[TimeSeries]) – 缩放器将基于其拟合的时间序列。

注意

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

返回类型: Any

static ts_inverse_transform(series, params, **kwargs)[source]¶

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

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

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_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 方法，分别用于对 TimeSeries 应用和“取消应用” component_mask；如果在实例化 InvertibleDataTransformer 时将 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)。如果正在实现点wise逆变换（即在时间 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

static ts_transform(series, params, **kwargs)[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 方法，分别用于对 TimeSeries 应用和“取消应用” component_mask；如果在实例化 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)。如果正在实现点wise变换（即在时间 t 变换值仅取决于在该时间 t 序列的值），则这种堆叠很有用。变换后，可以使用 unstack_samples 方法对堆叠的 TimeSeries 进行“取消堆叠”。

参数

series (TimeSeries) – 要变换的系列。
params (Mapping[str, Any]) – 包含变换函数参数的字典。固定参数（即在调用 super.__init__() 之前在变换的最子类中定义的属性）存储在 ‘fixed’ 键下。如果该变换继承自 FittableDataTransformer 类，则变换的拟合参数（即 ts_fit 返回的值）存储在 ‘fitted’ 键下。
args – 在调用 transform 时除了 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。
component_mask (Optional[ndarray, None]) – 可选参数，np.ndarray 布尔掩码，形状为 (n_components, 1)，指定从 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

Box-Cox 变换器

可拟合数据变换器基类