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

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

基类：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.pydata.org/docs/user_guide/timeseries.html#dateoffset-对象

属性

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，并行化由 transform 和/或 inverse_transform 处理（参见 InvertibleDataTransformer.__init__() 文档字符串）。
`ts_inverse_transform`(series, params)	通过检索原始高频部分并重塑数值，将序列转换回高频。
`ts_transform`(series, params)	使用混合数据采样方法将序列从高频转换为低频。
`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, *args, **kwargs)[源代码]¶

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

返回类型: Union[Dict[str, Any], List[Dict[str, Any]]]

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

通过检索原始高频部分并重塑数值，将序列转换回高频。

在转换为/从可锚定的偏移量 [1] 时，如果序列不从锚定日期开始，则索引会向后滚动以保留所有值。

步骤：

重塑值以展平由变换引入的组件
消除填充了NaN的行，以方便时间索引调整
获取原始组件名称
在适用的情况下，将时间索引的开始时间向前推移
生成一个新的高频时间索引

引用

1: https://pandas.pydata.org/pandas-docs/stable/user_guide/timeseries.html#锚定偏移

返回类型: TimeSeries

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

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

在转换为/自可锚定的偏移量 [1]_ 时，如果序列不从锚定日期开始，则索引会向后滚动以保留所有值。

步骤：

将系列转换为 pd.DataFrame 并获取 PeriodIndex 的频率字符串
对序列进行下采样，然后再对其进行上采样
如果输入序列不是 ‘full’，则将其替换为未采样的序列
将高频序列的每一列转换为低频序列的多列
将低频序列转换回时间序列

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

Mapper 和 InvertibleMapper

缺失值填充器