stl_decomposer#

使用 STL 从时间序列中移除趋势和季节性的组件。

模块内容#

类摘要#

STLDecomposer

使用 STL 算法从时间序列中移除趋势和季节性。

目录#

class evalml.pipelines.components.transformers.preprocessing.stl_decomposer.STLDecomposer(time_index: str = None, series_id: str = None, degree: int = 1, period: int = None, periods: dict = None, seasonal_smoother: int = 7, random_seed: int = 0, **kwargs)[source]#

使用 STL 算法从时间序列中移除趋势和季节性。

https://statsmodels.cn/dev/generated/statsmodels.tsa.seasonal.STL.html

参数

time_index (str) – 指定 X 中提供 datetime 对象的列的名称。默认为 None。
series_id (str) – 指定 X 中提供多序列 series_id 对象的列的名称。默认为 None。
degree (int) – 当前未使用。STL 具有 3 个“类似度”的值。目前无法设置任何值。默认为 1。
period (int) – 时间序列数据中对应于一个周期性信号周期的条目数。例如，如果已知数据具有每周季节性信号，且数据是每日数据，则周期可能应为 7。对于具有年度季节性信号的每日数据，周期可能应为 365。如果为 None，则 statsmodels 将根据频率推断周期。默认为 None。
seasonal_smoother (int) – 底层 STL 算法使用的季节平滑器长度。为兼容性起见，必须为奇数。如果提供偶数，将使用下一个最高的奇数。默认为 7。
random_seed (int) – 随机数生成器的种子。默认为 0。

属性

hyperparameter_ranges	None
invalid_frequencies	[]
modifies_features	False
modifies_target	True
name	STL 分解器
needs_fitting	True
training_only	False

方法

`clone`	使用相同的参数和随机状态构造新组件。
`default_parameters`	返回此组件的默认参数。
`describe`	描述组件及其参数。
`determine_periodicity`	使用自相关方法确定季节性信号最可能重要周期的函数。
`fit`	拟合 STLDecomposer 并确定季节性信号。
`fit_transform`	从目标变量中移除已拟合的趋势和季节性。
`get_trend_dataframe`	返回包含 4 列的数据帧列表：signal, trend, seasonality, residual。
`get_trend_prediction_intervals`	计算趋势数据的预测区间。
`inverse_transform`	将已拟合的趋势和季节性加回目标变量。
`is_freq_valid`	确定给定字符串是否代表此分解器的有效频率。
`load`	从文件路径加载组件。
`parameters`	返回用于初始化组件的参数。
`plot_decomposition`	绘制目标信号的分解图。
`save`	将组件保存到文件路径。
`set_period`	根据目标的季节性设置组件季节周期的函数。
`transform`	通过移除 STL 趋势和季节性来转换目标数据。
`update_parameters`	更新组件的参数字典。

clone(self)#

使用相同的参数和随机状态构造新组件。

返回值: 一个具有相同参数和随机状态的此组件的新实例。

default_parameters(cls)#

返回此组件的默认参数。

我们的约定是 Component.default_parameters == Component().parameters。

返回值: 此组件的默认参数。
返回类型: dict

describe(self, print_name=False, return_dict=False)#

描述组件及其参数。

参数

print_name (bool, optional) – 是否打印组件名称
return_dict (bool, optional) – 是否以字典格式 {"name": name, "parameters": parameters} 返回描述

返回值

如果 return_dict 为 True，则返回字典，否则返回 None。

返回类型

None 或 dict

classmethod determine_periodicity(cls, X: pandas.DataFrame, y: pandas.Series, acf_threshold: float = 0.01, rel_max_order: int = 5)#

使用自相关方法确定季节性信号最可能重要周期的函数。

参数

X (pandas.DataFrame) – 时间序列问题的特征数据。
y (pandas.Series) – 时间序列问题的目标数据。
acf_threshold (float) – 确定周期的自相关函数阈值。任何低于阈值的值都被视为 0，不会被考虑用于确定周期。默认为 0.01。
rel_max_order (int) – 用于确定周期的相对最大值阶数。默认为 5。

返回值

时间序列数据中，目标数据季节性部分重复的整数条目数。: 如果时间序列数据是以天为单位，那么这是目标季节性信号重复所需的天数。注意：目标数据可能包含多个季节性信号。此函数只会返回更强的那个。例如，如果目标数据同时具有每周和每年的季节性，该函数可能会返回“7”或“365”，具体取决于哪个季节性的自相关性更强。如果未检测到周期，则返回 None。

返回类型

int

fit(self, X: pandas.DataFrame, y: Union[pandas.Series, pandas.DataFrame] = None) → STLDecomposer[source]#

拟合 STLDecomposer 并确定季节性信号。

使用组件存储的参数实例化 statsmodels STL 分解对象并进行拟合。由于 statsmodels 对象不符合 sklearn API，它不会在 _component_obj 的 __init__() 期间保存，而是在每次调用 fit 时重新实例化。

为了模拟 sklearn API，当 STL 分解器拟合时，会保存完整的季节性分量、季节性分量的单周期样本、完整的趋势-周期分量和残差。

y(t) = S(t) + T(t) + R(t)

参数

X (pd.DataFrame, optional) – 有条件地用于构建 datetime 索引。
y (pd.Series or pd.DataFrame) – 需要去趋势和去季节化的目标变量。

返回值

self

抛出

ValueError – 如果 y 为 None。
ValueError – 如果目标数据没有 DatetimeIndex 且特征数据中没有 Datetime 特征

fit_transform(self, X: pandas.DataFrame, y: pandas.Series = None) → tuple[pandas.DataFrame, pandas.Series]#

从目标变量中移除已拟合的趋势和季节性。

参数

X (pd.DataFrame, optional) – 忽略。
y (pd.Series) – 需要去趋势和去季节化的目标变量。

返回值

第一个元素是未修改返回的输入特征。: 第二个元素是已移除拟合趋势的目标变量 y。

返回类型

pd.DataFrame, pd.Series 的元组

get_trend_dataframe(self, X, y)[source]#

返回包含 4 列的数据帧列表：signal, trend, seasonality, residual。

参数

X (pd.DataFrame) – 索引中包含时间序列数据的输入数据。
y (pd.Series or pd.DataFrame) – 针对单变量问题以 Series 形式提供的目标变量数据，或针对多变量问题以 DataFrame 形式提供。

返回值

每个 DataFrame 包含列“signal”、“trend”、“seasonality”和“residual”，: 后 3 列的值是目标数据的分解元素。“signal”列只是输入目标信号，但使用 datetime 索引重新索引以匹配输入特征。

(多序列) 列表字典：系列 ID 映射到 pd.DataFrame 列表，每个 DataFrame 包含列“signal”、“trend”、“seasonality”和“residual”

返回类型

(单序列) pd.DataFrame 列表

抛出

TypeError – 如果 X 的索引中不包含时间序列数据。
ValueError – 如果 X 的时间序列索引没有推断出的频率。
ValueError – 如果与去趋势器关联的预测器尚未拟合。
TypeError – 如果 y 不是以 pandas Series 或 DataFrame 的形式提供。

get_trend_prediction_intervals(self, y, coverage=None)[source]#

计算趋势数据的预测区间。

参数

y (pd.Series or pd.DataFrame) – 目标数据。
coverage (list[float]) – 一个包含介于 0 和 1 之间的浮点数列表，应计算预测区间的上限和下限。

返回值

预测区间，键的格式为 {coverage}_lower 或 {coverage}_upper。(多序列) pd.Series 字典的字典：每个系列 ID 映射到预测区间的字典

返回类型

(单序列) pd.Series 字典

inverse_transform(self, y_t: Union[pandas.Series, pandas.DataFrame]) → Union[pandas.Series, pandas.DataFrame][source]#

将已拟合的趋势和季节性加回目标变量。

STL 趋势被预测以覆盖整个请求的目标范围，然后加回信号中。然后，季节性被向前预测并加回信号中。

参数: y_t (pd.Series or pd.DataFrame) – 目标变量。
返回值: 已将趋势和季节性加回的目标变量 y。
返回类型: pd.Series 或 pd.DataFrame
抛出: ValueError – 如果 y 为 None。

classmethod is_freq_valid(cls, freq: str)#

确定给定字符串是否代表此分解器的有效频率。

参数: freq (str) – 需要验证的频率。有关选项，请参阅 pandas 文档：https://pandas.ac.cn/pandas-docs/stable/user_guide/timeseries.html#offset-aliases。
返回值: 表示频率是否有效的布尔值。

static load(file_path)#

从文件路径加载组件。

参数: file_path (str) – 加载文件的位置。
返回值: ComponentBase 对象

property parameters(self)#: 返回用于初始化组件的参数。

plot_decomposition(self, X: pandas.DataFrame, y: Union[pandas.Series, pandas.DataFrame], show: bool = False) → Union[tuple[matplotlib.pyplot.Figure, list], dict[str, tuple[matplotlib.pyplot.Figure]]]#

绘制目标信号的分解图。

参数

X (pd.DataFrame) – 索引中包含时间序列数据的输入数据。
y (pd.Series or pd.DataFrame) – 针对单变量问题以 Series 形式提供的目标变量数据，或针对多变量问题以 DataFrame 形式提供。
show (bool) – 是否显示绘图。默认为 False。

返回值

包含分解图的图形和坐标轴: 绘制在上面
(多序列) dict[str, (matplotlib.pyplot.Figure, list[matplotlib.pyplot.Axes])]：一个将系列 ID 映射到的字典: 包含分解图的图形和坐标轴

返回类型

(单序列) matplotlib.pyplot.Figure, list[matplotlib.pyplot.Axes]

save(self, file_path, pickle_protocol=cloudpickle.DEFAULT_PROTOCOL)#

将组件保存到文件路径。

参数

file_path (str) – 保存文件的位置。
pickle_protocol (int) – pickle 数据流格式。

set_period(self, X: pandas.DataFrame, y: pandas.Series, acf_threshold: float = 0.01, rel_max_order: int = 5)#

根据目标的季节性设置组件季节周期的函数。

参数

X (pandas.DataFrame) – 时间序列问题的特征数据。
y (pandas.Series) – 时间序列问题的目标数据。
acf_threshold (float) – 确定周期的自相关函数阈值。任何低于阈值的值都被视为 0，不会被考虑用于确定周期。默认为 0.01。
rel_max_order (int) – 用于确定周期的相对最大值阶数。默认为 5。

transform(self, X: pandas.DataFrame, y: Union[pandas.Series, pandas.DataFrame] = None) → Union[tuple[pandas.DataFrame, pandas.Series], tuple[pandas.DataFrame,pandas.DataFrame]][source]#

通过移除 STL 趋势和季节性来转换目标数据。

使用 ARIMA 模型向前预测加性趋势并将其移除。然后，利用在 .fit() 函数中确定的第一个周期的季节性数据来外推要转换数据的季节性信号。此季节性信号也被假定为加性并被移除。

参数

X (pd.DataFrame, optional) – 有条件地用于构建 datetime 索引。
y (pd.Series or pd.DataFrame) – 需要去趋势和去季节化的目标变量。

返回值

输入特征列表未修改地返回。目标变量: y 已去趋势和去季节化。
(多序列) pd.DataFrame, pd.DataFrame：输入特征列表未修改地返回。目标变量: y 已去趋势和去季节化。

返回类型

(单序列) pd.DataFrame, pd.Series

抛出

ValueError – 如果目标数据没有 DatetimeIndex 且特征数据中没有 Datetime 特征

update_parameters(self, update_dict, reset_fit=True)#

更新组件的参数字典。

参数

update_dict (dict) – 要更新的参数字典。
reset_fit (bool, optional) – 如果为 True，将 _is_fitted 设置为 False。