静态协变量转换器¶

class darts.dataprocessing.transformers.static_covariates_transformer.StaticCovariatesTransformer(transformer_num=None, transformer_cat=None, cols_num=None, cols_cat=None, name='StaticCovariatesTransformer', n_jobs=1, verbose=False)[source]¶

基类: FittableDataTransformer, InvertibleDataTransformer

静态协变量缩放器/编码器/转换器的通用包装类。此转换器仅作用于传递给 fit()、transform()、fit_transform() 和 inverse_transform() 方法的序列的静态协变量。它既可以对数值特征进行缩放，也可以对类别特征进行编码。

底层的 transformer_num 和 transformer_cat 必须实现 fit()、transform() 和 inverse_transform() 方法（通常来自 scikit-learn）。

默认情况下，数值和类别列/特征会被推断并分别分配给 transformer_num 和 transformer_cat。或者，可以使用 cols_num 和 cols_cat 马 指定要缩放/转换哪些列。

transformer_num 和 transformer_cat 都会在传递给 StaticCovariatesTransformer.fit() 的所有序列的静态协变量数据上进行全局拟合。

参数

transformer_num – 用于转换数值静态协变量列的转换器。它必须提供 fit()、transform() 和 inverse_transform() 方法。默认值: sklearn.preprocessing.MinMaxScaler(feature_range=(0, 1)); 这会将所有值缩放到 0 到 1 之间。
transformer_cat – 用于转换类别静态协变量列的编码器。它必须提供 fit()、transform() 和 inverse_transform() 方法。默认值: sklearn.preprocessing.OrdinalEncoder(); 这会将类别转换为整数值数组，其中每个整数代表一个特定的类别。
cols_num (Optional[list[str], None]) – 可选参数，一个列名列表，将对这些列应用数值转换器 transformer_num。默认情况下，转换器将根据类型推断所有数值特征，并使用 transformer_num 对其进行缩放。如果列表为空，则不进行任何列的缩放。
cols_cat (Optional[list[str 马], None]) – 可选参数，一个列名列表，将对这些列应用类别转换器 transformer_cat。默认情况下，转换器将根据类型推断所有类别特征，并使用 transformer_cat 对其进行转换。如果列表为空，则不进行任何列的转换。
name – 为 StaticCovariatesTransformer 指定的名称。
n_jobs (int) – 并行运行的作业数量。只有当输入方法是一个 Sequence[TimeSeries] 时才会创建并行作业，以并行化处理不同的 TimeSeries。默认为 1（顺序执行）。将参数设置为 -1 表示使用所有可用的处理器。注意：对于少量数据，并行化开销可能会增加所需的总时间。
verbose (bool) – 可选参数，是否打印操作进度。

示例

>>> import numpy as np
>>> import pandas as pd
>>> from darts import TimeSeries
>>> from darts.dataprocessing.transformers import StaticCovariatesTransformer
>>> static_covs = pd.DataFrame(data={"num": [0, 2, 1], "cat": ["a", "c", "b"]})
>>> series = TimeSeries.from_values(
>>>     values=np.random.random((10, 3)),
>>>     columns=["comp1", "comp2", "comp3"],
>>>     static_covariates=static_covs,
>>> )
>>> transformer = StaticCovariatesTransformer()
>>> series_transformed = transformer.fit_transform(series)
>>> print(series.static_covariates)
static_covariates  num cat
component
comp1               0.0   a
comp2               2.0   c
comp3               1.0   b
>>> print(series_transformed.static_covariates)
static_covariates  num  cat
component
comp1               0.0  0.0
comp2               1.0  2.0
comp3               0.5  1.0

属性

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)	True 表示启用关于缩放器操作进度的详细报告，False 表示不提供额外信息。
`stack_samples`(vals)	从 TimeSeries 或 TimeSeries 的 array_values 创建形状为 (n_timesteps * n_samples, n_components) 的数组。
`transform`(series, *args[, component_mask, ...])	通过调用用户实现的 ts_transform 方法，转换（序列）序列。
`ts_fit`(series, params, args, *kwargs)	整理所有提供的 TimeSeries 的静态协变量，并拟合以下参数
`ts_inverse_transform`(series, params, *args, ...)	当调用 `inverse_transform()` 时，将应用于每个序列的函数。
`ts_transform`(series, params, args, *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。

返回

仅包含由 component_mask 指定的分量的 TimeSeries (如果 return_ts = True) 或 np.ndarray (如果 return_ts = False)。

返回类型

masked

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

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

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

1. 如果 global_fit 属性设置为 False，则会分别为 Sequence 中的每个 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 将自动应用于每个用于转换的 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 之前，将从每个 series 中移除第 i 个分量；在转换此掩码序列后，未转换的第 i 个分量将被 '添加回' 到输出中。请注意，自动 component_mask 只能在 ts_inverse_transform 不改变每个序列的时间步数时执行；如果发生这种情况，则转换后和未转换的分量将无法沿着分量轴重新连接在一起。
如果在实例化 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 表示不提供额外信息。
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]) – 形状为 (n_timesteps * n_samples, n_components) 的 Timeseries 或 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 将自动应用于每个用于转换的 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 只能在 ts_transform 不改变每个序列的时间步数时执行；如果发生这种情况，则转换后和未转换的分量将无法沿着分量轴重新连接在一起。
如果在实例化 BaseDataTransformer 时将 mask_components 设置为 False，则提供的任何 component_mask 将作为关键字参数传递给 ts_transform；用户随后可以手动指定如何将 component_mask 应用于每个序列。




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

整理所有提供的 TimeSeries 的静态协变量，并拟合以下参数

transformer_num，拟合后的数值静态协变量转换器。
transformer_cat，拟合后的类别静态协变量转换器。

3. mask_num，一个包含两个布尔数组的字典：一个指示 未转换 静态协变量的哪些分量是数值，另一个指示 已转换 静态协变量的哪些分量是数值。 4. mask_cat，一个包含两个布尔数组的字典：一个指示 未转换 静态协变量的哪些分量是类别，另一个指示 已转换 静态协变量的哪些分量是类别。 5. n_cat_cols，一个字典，存储在未转换和已转换的静态协变量中预期的类别列数。






static ts_inverse_transform(series, params, *args, **kwargs)[source]¶
当调用 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。
InvertibleDataTransformer 继承的 BaseDataTransformer 类包含一些辅助方法，这些方法在实现 ts_inverse_transform 函数时可能有用

1. apply_component_mask 和 unapply_component_mask 方法，分别将 component_mask 应用和 '撤销应用' 到 TimeSeries；如果在 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)。如果正在实现点式逆转换（即时间 t 的值转换仅取决于该时间点 t 的序列值），则此堆叠很有用。转换后，可以使用 unstack_samples 方法对堆叠的 TimeSeries 进行 '解堆叠'。

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

参数

series (TimeSeries) – 要逆转换的序列。
params (dict[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, *args, **kwargs)[source]¶
当调用 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 应用和 '撤销应用' 到 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)。


参数

series (TimeSeries) – 要逆转换的序列。
params (dict[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]) – 可选参数，形状为 (n_components, 1) 的 np.ndarray 布尔掩码，指定从 series 中提取了哪些分量。如果给定，将 vals 插回原始数组的列中。如果未指定，则不进行任何 '解除掩码'。


返回
包含之前由 component_mask 移除、现已 '添加回' 的分量的 TimeSeries (如果 vals 是 TimeSeries) 或 np.ndarray (如果 vals 是 np.ndarray)。

返回类型
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


              
              
              
 
       上一页
 Scaler
 
    下一页
 窗口转换器