拓冰网站定制 
TDengine TDgpt Theta 预测算法实战指南原理、参数、SQL 与置信区间解析【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine本文聚焦 TDengine 内置时序分析组件 TDgpt 中的ThetaTheta 方法预测算法。Theta 方法将输入时间序列转换为不同曲率的 theta 线分别预测后再合并适合具有长期趋势与相对规则季节性的单变量序列。读完本文你将掌握FORECAST函数调用 Theta 的全部参数、输入数据约束、完整 SQL 写法、结果与置信区间的解析方式并能从源码与测试层面理解该算法的底层实现与校验逻辑。Theta 方法在 TDgpt 中的定位TDgpt 是 TDengine 中提供时序分析与预测的组件通过FORECAST函数在 anode 上调用预测算法提供服务其函数语法与通用参数说明见 时序预测总览。FORECAST的输入是一段连续的历史时序数据输出是未来连续一段时间的预测值预测行数由用户通过rows参数指定。预测通常针对子表或跨表的同一时间序列执行。Theta 是 TDgpt 内置的预测算法之一与 ARIMA、HoltWinters、Prophet、CES、ETS 以及各类机器学习/深度学习模型并列相关算法清单可在 时序预测总览文档 中查看。本节聚焦的关联文档为 Theta 算法文档。算法原理什么是 Theta 方法Theta 方法的核心思想是把输入时间序列变换为多条具有不同曲率的 theta 线theta lines分别对每条线做预测再将各条线的预测结果合并为最终预测值。它特别适用于带有趋势的单变量时间序列对于存在季节性的数据可以在预测前先进行季节性分解分解后的序列再应用 Theta 方法从而支持周期性序列的预测。此外Theta 方法会为预测结果提供置信区间confidence intervals这一点与 CES、ETS 等模型一致便于评估预测的不确定性。参数详解调用 Theta 算法时通过FORECAST的选项参数keyvalue形式多个参数用逗号分隔进行配置。除algotheta外Theta 有两个专属参数见下表参数描述是否必填period每个周期包含的数据点数。若未指定或设为 0则使用非季节性模型。否decomposition_type季节性分解类型取值为additive或multiplicative默认值为multiplicative。否如何选择分解类型当季节波动幅度相对恒定时使用additive加法分解季节分量以固定绝对值叠加在趋势上当季节波动幅度与序列水平成比例即波动随序列整体大小同比例放大或缩小时使用multiplicative乘法分解季节分量以比例形式作用于趋势。一个重要的约束是乘法分解要求输入数据全部为正。这源于乘法模型对零值和负值在数学上的不适用性详见下文源码验证部分。输入数据要求输入数据只能包含有限数值finite numeric values即不能包含NaN、Infinity或-Infinity非季节性预测period为 0至少需要2 个输入值当period大于 0 时输入数据必须包含至少两个完整周期。需要说明的是FORECAST函数通用约束要求预测至少 10 行输入、至多 40000 行部分模型有更严格限制Theta 在通用约束之上还有上述模型级要求。完整 SQL 示例关联文档给出的示例对i32列执行预测每 12 个数据点构成一个周期并使用乘法季节分解。算法调用写法如下FORECAST(i32, algotheta,period12,decomposition_typemultiplicative)完整的 SQL 语句为SELECT _frowts, FORECAST(i32, algotheta,period12,decomposition_typemultiplicative) from foo其中_frowts是预测结果的伪列表示预测数据的时间戳。除_frowts外预测查询还会引入_FLOW置信区间下界与_FHIGH置信区间上界两个伪列可用于获取每个预测点对应的置信区间TDgpt 的预测结果时间序列可以通过_frowts、_flow、_fhigh与预测值组合查询完整示例见 时序预测总览。返回结果结构FORECAST返回的 JSON 结构如下{ rows: rows, // Rows returned period: period, // Period of results algo: theta, // Algorithm mse: mse, // Mean square error (MSE) res: res // Forecast results and confidence intervals in column format }字段含义rows返回的预测行数period结果的周期algo算法标识此处固定为thetamse均方误差Mean Square Error衡量拟合优度res按列组织的预测结果与置信区间数据。从源码实现看见下文res的第一列是预测时间戳序列其后是预测均值列以及当返回置信区间时下界lo-*与上界hi-*列。与其他预测算法的选择在 时序预测总览 中给出了 CES、Theta、ETS 三者的选型建议可帮助判断何时该用 Theta数据特征推荐算法原因季节模式复杂或不符常规加法/乘法模式CESCES 能用复值状态表示季节行为并可自动选择模型形式序列具有清晰长期趋势且季节性相对规则ThetaTheta 是紧凑的趋势聚焦方法季节振幅稳定选加法分解季节振幅成比例选乘法分解希望获得误差、趋势、季节分量可解释的组合ETSETS 可自动选择或显式配置加法/乘法分量并支持阻尼趋势当分量结构未知时可先用自动选择CES 的modelZ或 ETS 的modelZZZ。Theta 乘法分解与任何显式乘法 ETS 分量都要求输入严格为正做季节预测时需设置period并提供至少两个完整周期的历史数据。Theta 的姊妹算法文档可参考 CES 与 ETS。源码级实现解析Theta 算法在仓库中的实现位于 theta.py其类_ThetaService继承自AbstractStatsForecastService底层依赖 StatsForecast 提供的标准 Theta 模型。参数解析与校验在set_params中decomposition_type默认取multiplicative并统一转为小写若取值不在additive与multiplicative两者之间会直接抛出ValueError源码见 theta.pyself.decomposition_type str( params.get(decomposition_type, multiplicative) ).lower() if self.decomposition_type not in (additive, multiplicative): raise ValueError( decomposition_type parameter can only be additive or multiplicative )输入值校验_validate_input_values专门校验 Theta 的模型级输入约束当采用乘法分解时若输入序列中存在任意 0的值将抛出异常源码见 theta.py这与文档乘法分解要求正输入的说明完全对应。此外在基类AbstractStatsForecastService.execute中源码见 base.py还有以下通用校验与处理min_rows max(2, self.period * 2)当设置周期时要求至少两个完整周期未设置时至少 2 行——这与文档的输入要求一致输入数据被转为float数组后若存在NaN或无穷值np.isfinite检查失败抛出 input data contains NaN or infinite values 异常预测时间戳按start_ts index * time_step生成共rows个返回{mse: ..., model_info: Theta, res: [...]}结构。模型拟合_fit_model中当period大于 0 时取season_length period否则取 1非季节性随后构造 StatsForecast 的Theta(season_length..., decomposition_type...)模型并拟合源码见 theta.py。period本身在基类AbstractForecastService.set_params中被解析为整数并拒绝负值rows必须大于 0conf取值范围为[0, 1)这些通用参数含every、start、timeout等的完整语义可查阅 时序预测总览。置信区间与 MSE 的计算置信区间与均方误差在基类AbstractStatsForecastService._format_forecast_result中完成源码见 base.pylevel由conf参数换算默认0.95预测时调用fitted_model.predict(hself.rows, level[level])得到均值列与lo-*、hi-*置信区间列若return_conf为 0 则只返回均值列。MSE 则通过样本内拟合值fitted_model.predict_in_sample()[fitted]与原始值的均方误差计算fitted fitted_model.predict_in_sample()[fitted] mse float(np.nanmean((values - fitted) ** 2))这就是返回 JSON 中mse与res中置信区间列的数据来源。conf、return_conf等参数在 base.py 中解析conf默认0.95且要求位于[0, 1.0)。测试用例验证仓库测试文件 forecast_test.py 对 Theta 算法做了系统验证可以从行为层面佐证文档描述test_theta_forecast第 369 行起加载theta服务设置rows10、period12、decomposition_typemultiplicative执行预测并断言结果结构与行数同时绘制预测结果test_theta_invalid_params第 390 行起传入非法decomposition_type断言抛出ValueErrortest_theta_rejects_non_finite_input第 406 行起将输入序列中某个值替换为NaN、inf、-inf断言执行时抛出 NaN or infinite 异常——对应输入数据必须只含有限数值的约束test_theta_multiplicative_requires_positive_input第 426 行起将输入中的值替换为0与-1在乘法分解模式下断言抛出异常——对应乘法分解要求正输入的约束。这些测试用例与 theta.py 的实现互相印证构成了文档所述规则的代码级证据。参考Theta 方法的理论背景可参考以下资料关联文档中给出的原始出处标准 Theta 模型StatsForecast 实现的模型文档论文《The Theta model: a decomposition approach to forecasting》Elsevier 期刊论文DOI: 10.1016/S0169-2070(00)00066-2该论文首次系统阐述了 Theta 方法的分解式预测思想。结合本仓库的 Theta 算法文档、时序预测总览 与 theta.py 源码即可在 TDengine 中快速落地基于 Theta 方法的时序趋势与季节预测。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 TDengine TDgpt Theta 预测算法实战指南：原理、参数、SQL 与置信区间解析
TDengine TDgpt Theta 预测算法实战指南原理、参数、SQL 与置信区间解析【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine本文聚焦 TDengine 内置时序分析组件 TDgpt 中的ThetaTheta 方法预测算法。Theta 方法将输入时间序列转换为不同曲率的 theta 线分别预测后再合并适合具有长期趋势与相对规则季节性的单变量序列。读完本文你将掌握FORECAST函数调用 Theta 的全部参数、输入数据约束、完整 SQL 写法、结果与置信区间的解析方式并能从源码与测试层面理解该算法的底层实现与校验逻辑。Theta 方法在 TDgpt 中的定位TDgpt 是 TDengine 中提供时序分析与预测的组件通过FORECAST函数在 anode 上调用预测算法提供服务其函数语法与通用参数说明见 时序预测总览。FORECAST的输入是一段连续的历史时序数据输出是未来连续一段时间的预测值预测行数由用户通过rows参数指定。预测通常针对子表或跨表的同一时间序列执行。Theta 是 TDgpt 内置的预测算法之一与 ARIMA、HoltWinters、Prophet、CES、ETS 以及各类机器学习/深度学习模型并列相关算法清单可在 时序预测总览文档 中查看。本节聚焦的关联文档为 Theta 算法文档。算法原理什么是 Theta 方法Theta 方法的核心思想是把输入时间序列变换为多条具有不同曲率的 theta 线theta lines分别对每条线做预测再将各条线的预测结果合并为最终预测值。它特别适用于带有趋势的单变量时间序列对于存在季节性的数据可以在预测前先进行季节性分解分解后的序列再应用 Theta 方法从而支持周期性序列的预测。此外Theta 方法会为预测结果提供置信区间confidence intervals这一点与 CES、ETS 等模型一致便于评估预测的不确定性。参数详解调用 Theta 算法时通过FORECAST的选项参数keyvalue形式多个参数用逗号分隔进行配置。除algotheta外Theta 有两个专属参数见下表参数描述是否必填period每个周期包含的数据点数。若未指定或设为 0则使用非季节性模型。否decomposition_type季节性分解类型取值为additive或multiplicative默认值为multiplicative。否如何选择分解类型当季节波动幅度相对恒定时使用additive加法分解季节分量以固定绝对值叠加在趋势上当季节波动幅度与序列水平成比例即波动随序列整体大小同比例放大或缩小时使用multiplicative乘法分解季节分量以比例形式作用于趋势。一个重要的约束是乘法分解要求输入数据全部为正。这源于乘法模型对零值和负值在数学上的不适用性详见下文源码验证部分。输入数据要求输入数据只能包含有限数值finite numeric values即不能包含NaN、Infinity或-Infinity非季节性预测period为 0至少需要2 个输入值当period大于 0 时输入数据必须包含至少两个完整周期。需要说明的是FORECAST函数通用约束要求预测至少 10 行输入、至多 40000 行部分模型有更严格限制Theta 在通用约束之上还有上述模型级要求。完整 SQL 示例关联文档给出的示例对i32列执行预测每 12 个数据点构成一个周期并使用乘法季节分解。算法调用写法如下FORECAST(i32, algotheta,period12,decomposition_typemultiplicative)完整的 SQL 语句为SELECT _frowts, FORECAST(i32, algotheta,period12,decomposition_typemultiplicative) from foo其中_frowts是预测结果的伪列表示预测数据的时间戳。除_frowts外预测查询还会引入_FLOW置信区间下界与_FHIGH置信区间上界两个伪列可用于获取每个预测点对应的置信区间TDgpt 的预测结果时间序列可以通过_frowts、_flow、_fhigh与预测值组合查询完整示例见 时序预测总览。返回结果结构FORECAST返回的 JSON 结构如下{ rows: rows, // Rows returned period: period, // Period of results algo: theta, // Algorithm mse: mse, // Mean square error (MSE) res: res // Forecast results and confidence intervals in column format }字段含义rows返回的预测行数period结果的周期algo算法标识此处固定为thetamse均方误差Mean Square Error衡量拟合优度res按列组织的预测结果与置信区间数据。从源码实现看见下文res的第一列是预测时间戳序列其后是预测均值列以及当返回置信区间时下界lo-*与上界hi-*列。与其他预测算法的选择在 时序预测总览 中给出了 CES、Theta、ETS 三者的选型建议可帮助判断何时该用 Theta数据特征推荐算法原因季节模式复杂或不符常规加法/乘法模式CESCES 能用复值状态表示季节行为并可自动选择模型形式序列具有清晰长期趋势且季节性相对规则ThetaTheta 是紧凑的趋势聚焦方法季节振幅稳定选加法分解季节振幅成比例选乘法分解希望获得误差、趋势、季节分量可解释的组合ETSETS 可自动选择或显式配置加法/乘法分量并支持阻尼趋势当分量结构未知时可先用自动选择CES 的modelZ或 ETS 的modelZZZ。Theta 乘法分解与任何显式乘法 ETS 分量都要求输入严格为正做季节预测时需设置period并提供至少两个完整周期的历史数据。Theta 的姊妹算法文档可参考 CES 与 ETS。源码级实现解析Theta 算法在仓库中的实现位于 theta.py其类_ThetaService继承自AbstractStatsForecastService底层依赖 StatsForecast 提供的标准 Theta 模型。参数解析与校验在set_params中decomposition_type默认取multiplicative并统一转为小写若取值不在additive与multiplicative两者之间会直接抛出ValueError源码见 theta.pyself.decomposition_type str( params.get(decomposition_type, multiplicative) ).lower() if self.decomposition_type not in (additive, multiplicative): raise ValueError( decomposition_type parameter can only be additive or multiplicative )输入值校验_validate_input_values专门校验 Theta 的模型级输入约束当采用乘法分解时若输入序列中存在任意 0的值将抛出异常源码见 theta.py这与文档乘法分解要求正输入的说明完全对应。此外在基类AbstractStatsForecastService.execute中源码见 base.py还有以下通用校验与处理min_rows max(2, self.period * 2)当设置周期时要求至少两个完整周期未设置时至少 2 行——这与文档的输入要求一致输入数据被转为float数组后若存在NaN或无穷值np.isfinite检查失败抛出 input data contains NaN or infinite values 异常预测时间戳按start_ts index * time_step生成共rows个返回{mse: ..., model_info: Theta, res: [...]}结构。模型拟合_fit_model中当period大于 0 时取season_length period否则取 1非季节性随后构造 StatsForecast 的Theta(season_length..., decomposition_type...)模型并拟合源码见 theta.py。period本身在基类AbstractForecastService.set_params中被解析为整数并拒绝负值rows必须大于 0conf取值范围为[0, 1)这些通用参数含every、start、timeout等的完整语义可查阅 时序预测总览。置信区间与 MSE 的计算置信区间与均方误差在基类AbstractStatsForecastService._format_forecast_result中完成源码见 base.pylevel由conf参数换算默认0.95预测时调用fitted_model.predict(hself.rows, level[level])得到均值列与lo-*、hi-*置信区间列若return_conf为 0 则只返回均值列。MSE 则通过样本内拟合值fitted_model.predict_in_sample()[fitted]与原始值的均方误差计算fitted fitted_model.predict_in_sample()[fitted] mse float(np.nanmean((values - fitted) ** 2))这就是返回 JSON 中mse与res中置信区间列的数据来源。conf、return_conf等参数在 base.py 中解析conf默认0.95且要求位于[0, 1.0)。测试用例验证仓库测试文件 forecast_test.py 对 Theta 算法做了系统验证可以从行为层面佐证文档描述test_theta_forecast第 369 行起加载theta服务设置rows10、period12、decomposition_typemultiplicative执行预测并断言结果结构与行数同时绘制预测结果test_theta_invalid_params第 390 行起传入非法decomposition_type断言抛出ValueErrortest_theta_rejects_non_finite_input第 406 行起将输入序列中某个值替换为NaN、inf、-inf断言执行时抛出 NaN or infinite 异常——对应输入数据必须只含有限数值的约束test_theta_multiplicative_requires_positive_input第 426 行起将输入中的值替换为0与-1在乘法分解模式下断言抛出异常——对应乘法分解要求正输入的约束。这些测试用例与 theta.py 的实现互相印证构成了文档所述规则的代码级证据。参考Theta 方法的理论背景可参考以下资料关联文档中给出的原始出处标准 Theta 模型StatsForecast 实现的模型文档论文《The Theta model: a decomposition approach to forecasting》Elsevier 期刊论文DOI: 10.1016/S0169-2070(00)00066-2该论文首次系统阐述了 Theta 方法的分解式预测思想。结合本仓库的 Theta 算法文档、时序预测总览 与 theta.py 源码即可在 TDengine 中快速落地基于 Theta 方法的时序趋势与季节预测。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考