混合数据采样 (MIDAS) 变换器

class darts.dataprocessing.transformers.midas.MIDAS(low_freq, strip=True, drop_static_covariates=False, name='MIDAS', n_jobs=1, verbose=False)[source]

基类：FittableDataTransformer, InvertibleDataTransformer

混合数据采样变换器。

一种使用混合数据采样将高频时间序列转换为低频时间序列的变换器；详见[1]。这使得可以在预测低频目标序列时使用高频协变量。例如，使用月度输入来预测季度目标。

注意

高输入频率与低目标频率的比例应始终保持一致。例如，一个季度总是包含三个月。但是，每个月的天数是变化的。在后一种情况下，MIDAS 变换不起作用，变换器将引发错误。

对于锚定的低频，变换后的序列必须至少包含 2 个样本，以便能够检索原始时间索引。

参数

  • low_freq (str) – 对应于目标低频的 pd.DateOffset 字符串别名[2]。传递给 pandas.DataFrame.resample() 的 rule 参数。

  • strip (bool) – 是否移除变换后序列开头和结尾的 NaN 值。

  • drop_static_covariates (bool) – 如果设置为 True，则输入序列的静态协变量将不会传递到输出。这对于具有组件特定静态协变量的多元序列可能很有用。

  • name (str) – 变换器的特定名称

  • n_jobs (int) – 并行运行的任务数量。仅当将 Sequence[TimeSeries] 作为输入传递给方法时，才会创建并行任务，从而并行处理不同的 TimeSeries 的操作。默认为 1 (顺序执行)。将参数设置为 -1 表示使用所有可用的处理器。注意：对于少量数据，并行化的开销最终可能会增加所需的总时间。

  • verbose (bool) – 可选参数，是否打印操作进度

示例

>>> from darts.datasets import AirPassengersDataset
>>> from darts.dataprocessing.transformers import MIDAS
>>> monthly_series = AirPassengersDataset().load()
>>> print(monthly_series.time_index[:4])
DatetimeIndex(['1949-01-01', '1949-02-01', '1949-03-01', '1949-04-01'], dtype='datetime64[ns]',
name='Month', freq='MS')
>>> print(monthly_series.values()[:4])
[[112.], [118.], [132.], [129.]]
>>> midas = MIDAS(low_freq="QS")
>>> quarterly_series = midas.fit_transform(monthly_series)
>>> print(quarterly_series.time_index[:3])
DatetimeIndex(['1949-01-01', '1949-04-01', '1949-07-01'], dtype='datetime64[ns]', name='Month', freq='QS-JAN')
>>> print(quarterly_series.values()[:3])
[[112. 118. 132.], [129. 121. 135.], [148. 148. 136.]]
>>> inversed_quaterly = midas.inverse_transform(quarterly_series)
>>> print(inversed_quaterly.time_index[:4])
DatetimeIndex(['1949-01-01', '1949-02-01', '1949-03-01', '1949-04-01'], dtype='datetime64[ns]',
name='time', freq='MS')
>>> print(inversed_quaterly.values()[:4])
[[112.], [118.], [132.], [129.]]

参考

1

https://en.wikipedia.org/wiki/Mixed-data_sampling

2

https://pandas.ac.cn/docs/user_guide/timeseries.html#dateoffset-objects

属性

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, *args, **kwargs)

MIDAS 需要高频周期名称以便轻松地对 TimeSeries 进行 reverse_transform，并行化由 transform 和/或 inverse_transform 处理（参见 InvertibleDataTransformer.__init__() 的文档字符串）。

ts_inverse_transform(series, params)

通过检索原始高频并重塑值，将序列变换回高频。

ts_transform(series, params)

使用混合数据采样方法将序列从高频变换到低频。使用并依赖于 pandas.DataFrame.resample。

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

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 个组件将被“添加回来”到输出中。注意，只有在 ts_inverse_transform 不改变每个序列中的时间步数时，才能执行自动 component_mask 操作；如果时间步数发生改变，则变换后和未变换的组件将无法沿着组件轴连接回来。

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

property name

数据变换器的名称。

数据变换器的名称。

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

参数

set_n_jobs(value)

value (int) – 新的 n_jobs 值。设置为 -1 表示使用所有可用的核心。

设置详细程度状态。

set_verbose(value)

参数

True 表示启用关于变换器操作进度的详细报告，False 表示不显示额外信息。

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

从 TimeSeries 或 TimeSeries 的 array_values 创建形状为 (n_timesteps * n_samples, n_components) 的数组。

static stack_samples(vals)

返回数组的每一列对应于序列的一个组件（维度），由该组件关联的所有样本连接而成。更具体地说，第 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

通过调用用户实现的 ts_transform 方法对（序列）系列进行变换。

transform(series, *args, component_mask=None, series_idx=None, **kwargs)

如果将 Sequence[TimeSeries] 作为输入数据传递，此函数负责同时并行处理序列中多个序列的变换。此外，如果在实例化 BaseDataTransformer 时将 mask_components 属性设置为 True，则提供的任何 component_mask 将自动应用于每个输入的 TimeSeries；有关组件掩码的更多详细信息，请参阅“注意”。

参数

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

  • series (Union[TimeSeries, Sequence[TimeSeries]]) – 要变换的（序列）序列。

  • args – 每次调用 ts_transform() 方法时的额外位置参数

  • series_idx (Union[int, Sequence[int], None]) – 可选参数，每个序列的索引，对应于其在用于拟合变换器的序列中的位置（用于检索适当的变换器参数）。

  • component_mask (Optional[np.ndarray] = None) – 可选参数，一个长度为 series.n_components 的一维布尔型 np.ndarray，指定变换器应考虑的基础 series 的哪些组件。如果在实例化 BaseDataTransformer 时将 mask_components 属性设置为 True，则组件掩码将自动应用于每个输入的 TimeSeries。否则，component_mask 将作为附加关键字参数提供给 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 个组件将被“添加回来”到输出中。注意，只有在 ts_transform 不改变每个序列中的时间步数时，才能执行自动 component_mask 操作；如果时间步数发生改变，则变换后和未变换的组件将无法沿着组件轴连接回来。

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

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

MIDAS 需要高频周期名称以便轻松地对 TimeSeries 进行 reverse_transform，并行化由 transform 和/或 inverse_transform 处理（参见 InvertibleDataTransformer.__init__() 的文档字符串）。

返回类型

Union[dict[str, Any], list[dict[str, Any]]]

static ts_inverse_transform(series, params)[source]

通过检索原始高频并重塑值，将序列变换回高频。

当转换到/来自可锚定偏移量[1]时，如果序列未在锚定日期开始，则索引将向后滚动以保留所有值。

步骤

  1. 重塑值以展平变换引入的组件

  2. 消除填充有 NaNs 的行，以方便时间索引调整

  3. 检索原始组件名称

  4. 适用时，将时间索引的起始点向后移

  5. 生成具有高频的新时间索引

参考

1

https://pandas.ac.cn/pandas-docs/stable/user_guide/timeseries.html#anchored-offsets

返回类型

TimeSeries

static ts_transform(series, params)[source]

使用混合数据采样方法将序列从高频变换到低频。使用并依赖于 pandas.DataFrame.resample。

当转换到/来自可锚定偏移量[1]_时，如果序列未在锚定日期开始，则索引将向后滚动以保留所有值。

步骤

  1. 将序列变换为 pd.DataFrame 并获取 PeriodIndex 的频率字符串

  2. 对序列进行降采样，然后再升采样一次

  3. 如果输入序列不是“完整”的，则使用未采样的序列替换它

  4. 将高频序列的每一列变换为低频序列的多个列

  5. 将低频序列变换回 TimeSeries

返回类型

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

上一页

映射器和可逆映射器

下一页

缺失值填充器