diff --git a/docs/zh/06-advanced/06-data-analysis/01-arima.md b/docs/zh/06-advanced/06-data-analysis/01-arima.md index 1668da453c..6799d48887 100644 --- a/docs/zh/06-advanced/06-data-analysis/01-arima.md +++ b/docs/zh/06-advanced/06-data-analysis/01-arima.md @@ -3,8 +3,52 @@ title: "ARIMA" sidebar_label: "ARIMA" --- -本节讲述如何 ARIMA 算法的使用方法。 +本节讲述 ARIMA 算法模型的使用方法。 ## 功能概述 -…… \ No newline at end of file +ARIMA 即自回归移动平均模型(Autoregressive Integrated Moving Average, ARIMA)，也记作 ARIMA(p,d,q)，是统计模型中最常见的一种用来进行时间序列预测的模型。 +ARIMA模型是一种自回归模型，只需要自变量即可预测后续的值。ARIMA模型要求时序数据是**平稳**，或经过差分处理后平稳，如果是不平稳的数据，**无法**获得正确的结果。 + +>平稳的时间序列：其性质不随观测时间的变化而变化。具有趋势或季节性的时间序列不是平稳时间序列——趋势和季节性使得时间序列在不同时段呈现不同性质。 + +以下参数可以动态输入控制预测过程中生成 合适的 ARIMA 的模型。 + +- p= 自回归模型阶数 +- d= 差分阶数 +- q= 移动平均模型阶数 + + +### 参数 +分析平台中使用自动化的 ARIMA 模型进行计算，因此每次计算的时候会根据输入的数据自动拟合最合适的模型，然后根据该模型进行预测输出结果。 +|参数名称|说明|必填项| +|---|---|---| +|period|输入时间序列数据每个周期包含的数据点个数。如果不设置该参数或则该参数设置为 0， 将使用非季节性/周期性的 ARIMA 模型预测。|选填| +|start_p| 自回归模型阶数的 起始值，0 开始的整数，不推荐大于 10 |选填| +|max_p| 自回归模型阶数的 结束值，0 开始的整数，不推荐大于 10 |选填| +|start_q| 移动平均模型阶数的起始值， 0 开始的整数，不推荐大于 10 |选填| +|max_q| 移动平均模型阶数的结束值， 0 开始的整数，不推荐大于 10 |选填| +|d| 差分阶数|选填| + +`start_p`、`max_p` `start_q` `max_q` 四个参数约束了模型在多大的范围内去搜寻合适的最优解。相同输入数据的条件下，参数范围越大，消耗的资源越多，系统响应的时间越长。 + +### 示例及结果 +针对 i32 列进行数据预测，输入列 i32 每 10 个点是一个周期，start_p 起始是 1， 最大拟合是 5，start_q是1，最大值是5，预测结果中返回 95% 置信区间范围边界。 +``` +FORECAST(i32, "algo=arima,alpha=95,period=10, start_p=1, max_p=5, start_q=1, max_q=5") +``` + +```json5 +{ +"rows": fc_rows, // 预测结果的行数 +"period": period, // 返回结果的周期性，同输入 +"alpha": alpha, // 返回结果的置信区间，同输入 +"algo": "arima", // 返回结果使用的算法 +"mse":mse, // 拟合输入时序数据时候生成模型的最小均方误差(MSE) +"res": res // 列模式的结果 +} +``` + +### 参考文献 +- https://en.wikipedia.org/wiki/Autoregressive_moving-average_model +- https://baike.baidu.com/item/%E8%87%AA%E5%9B%9E%E5%BD%92%E6%BB%91%E5%8A%A8%E5%B9%B3%E5%9D%87%E6%A8%A1%E5%9E%8B/5023931?fromtitle=ARMA%E6%A8%A1%E5%9E%8B&fromid=8048415 diff --git a/docs/zh/06-advanced/06-data-analysis/02-holtwinters.md b/docs/zh/06-advanced/06-data-analysis/02-holtwinters.md new file mode 100644 index 0000000000..470ef46253 --- /dev/null +++ b/docs/zh/06-advanced/06-data-analysis/02-holtwinters.md @@ -0,0 +1,43 @@ +--- +title: "HoltWinters" +sidebar_label: "HoltWinters" +--- + +本节讲述 HoltWinters 算法模型的使用方法。 + +## 功能概述 +HoltWinters模型又称为多次指数平滑模型（EMA）。对含有线性趋势和周期波动的非平稳序列适用，利用指数平滑法让模型参数不断适应非平稳序列的变化，并对未来趋势进行**短期**预测。 +HoltWinters有两种不同的季节性组成部分，当季节变化在该时间序列中大致保持不变时，通常选择**加法模型**；而当季节变化与时间序列的水平成比例变化时，通常选择**乘法模型**。 +该模型对于返回数据也不提供计算的置信区间范围结果。在 95% 置信区间的上下界结果与预测结果相同。 + + +### 参数 + +分析平台中使用自动化的 ARIMA 模型进行计算，因此每次计算的时候会根据输入的数据自动拟合最合适的模型，然后根据该模型进行预测输出结果。 +|参数名称|说明|必填项| +|---|---|---| +|period| 输入时间序列数据每个周期包含的数据点个数。如果不设置该参数或则该参数设置为 0， 将使用一次（简单）指数平滑方式进行数据拟合，并据此进行未来数据的预测|选填| +|trend| 趋势模型使用加法模型还是乘法模型|选填| +|seasonal| 季节性采用加法模型还是乘法模型|选填| + +参数 `trend` 和 `seasonal`的均可以选择 `add` （加法模型）或 `mul`（乘法模型）。 + +### 示例及结果 +针对 i32 列进行数据预测，输入列 i32 每 10 个点是一个周期，趋势采用乘法模型，季节采用乘法模型 +``` +FORECAST(i32, "algo=holtwinters,period=10,trend=mul,seasonal=mul") +``` + +```json5 +{ +"rows": rows, // 结果的行数 +"period": period, // 返回结果的周期性， 该结果与输入的周期性相同，如果没有周期性，该值为 0 +"algo": 'holtwinters' // 返回结果使用的计算模型 +"mse":mse, // 最小均方误差（minmum square error） +"res": res // 具体的结果，按照列形式返回的结果。一般意义上包含了 两列[timestamp][fc_results]。 +} +``` + +### 参考文献 +- https://en.wikipedia.org/wiki/Exponential_smoothing +- https://orangematter.solarwinds.com/2019/12/15/holt-winters-forecasting-simplified/ diff --git a/docs/zh/06-advanced/06-data-analysis/03-anomaly-detection.md b/docs/zh/06-advanced/06-data-analysis/03-anomaly-detection.md new file mode 100644 index 0000000000..8f1e1f064a --- /dev/null +++ b/docs/zh/06-advanced/06-data-analysis/03-anomaly-detection.md @@ -0,0 +1,46 @@ +--- +title: "Anomaly-detection" +sidebar_label: "Anomaly-detection" +--- + +本节讲述 异常检测 算法模型的使用方法。 + +## 概述 +分析平台提供了 6 种异常检查模型，6 种异常检查模型分为 3 个类别，分别属于基于统计的异常检测模型、基于数据密度的检测模型、基于深度学习的异常检测模型。在不指定异常检测使用的方法的情况下，默认调用 iqr 的方法进行计算。 + + +### 统计学异常检测方法 + +- k-sigma[1]: 即 ***68–95–99.7 rule*** 。***k***值默认为3， 即序列均值的 3 倍标准差范围为边界，超过边界的是异常值。KSigma 要求数据整体上服从正态分布，如果一个点偏离均值K倍标准差，则该点被视为异常点. + +|参数名称|说明|是否必选|默认值| +|---|---|---|---| +|k|标准差倍数|选填|3| + + +- IQR[2]：四分位距 (Interquartile range, IQR) 是一种衡量变异性的方法. 四分位数将一个按等级排序的数据集划分为四个相等的部分。即 Q1（第 1 个四分位数）、Q2（第 2 个四分位数）和 Q3（第 3 个四分位数）。IQR 定义为 Q3–Q1，位于 Q3+1.5 。无输入参数。 + +- Grubbs[3]: 又称为 Grubbs' test，即最大标准残差测试。Grubbs 通常用作检验最大值、最小值偏离均值的程度是否为异常，该单变量数据集遵循近似标准正态分布。非正态分布数据集不能使用该方法。无输入参数。 + +- SHESD[4]： 带有季节性的 ESD 检测算法。ESD 可以检测时间序列数据的多异常点。需要指定异常点比例的上界***k***，最差的情况是至多49.9%。数据集的异常比例一般不超过5% + +|参数名称|说明|是否必选|默认值| +|---|---|---|---| +|k|异常点在输入数据集中占比，范围是$`1\le K \le 49.9`$ |选填|5| + + +### 基于数据密度的检测方法 +LOF[5]: 局部离群因子(LOF，又叫局部异常因子)算法是Breunig于2000年提出的一种基于密度的局部离群点检测算法，该方法适用于不同类簇密度分散情况迥异的数据。根据数据点周围的数据密集情况，首先计算每个数据点的一个局部可达密度，然后通过局部可达密度进一步计算得到每个数据点的一个离群因子，该离群因子即标识了一个数据点的离群程度，因子值越大，表示离群程度越高，因子值越小，表示离群程度越低。最后，输出离群程度最大的top(n)个点。 + + +### 基于深度学习的检测方法 +使用自动编码器的异常检测模型。可以对具有周期性的数据具有较好的检测结果。但是使用该模型需要针对输入的时序数据进行训练，同时将训练完成的模型部署到服务目录中，才能够运行与使用。 + + +### 参考文献 +1. https://en.wikipedia.org/wiki/68%E2%80%9395%E2%80%9399.7_rule +2. https://en.wikipedia.org/wiki/Interquartile_range +3. Adikaram, K. K. L. B.; Hussein, M. A.; Effenberger, M.; Becker, T. (2015-01-14). "Data Transformation Technique to Improve the Outlier Detection Power of Grubbs's Test for Data Expected to Follow Linear Relation". Journal of Applied Mathematics. 2015: 1–9. doi:10.1155/2015/708948. +4. Hochenbaum, O. S. Vallis, and A. Kejariwal. 2017. Automatic Anomaly Detection in the Cloud Via Statistical Learning. arXiv preprint arXiv:1704.07706 (2017). +5. Breunig, M. M.; Kriegel, H.-P.; Ng, R. T.; Sander, J. (2000). LOF: Identifying Density-based Local Outliers (PDF). Proceedings of the 2000 ACM SIGMOD International Conference on Management of Data. SIGMOD. pp. 93–104. doi:10.1145/335191.335388. ISBN 1-58113-217-4. + diff --git a/docs/zh/06-advanced/06-data-analysis/addins.md b/docs/zh/06-advanced/06-data-analysis/addins.md new file mode 100644 index 0000000000..867bd9ff23 --- /dev/null +++ b/docs/zh/06-advanced/06-data-analysis/addins.md @@ -0,0 +1,167 @@ +--- +title: "addins" +sidebar_label: "addins" +--- + +本节说明如何将自己开发的新预测算法和异常检测算法整合到 TDengine 分析平台， 并能够通过 SQL 语句进行调用。 + +## 目录结构 + +![数据分析功能架构图](./pic/dir.png) + +|目录|说明| +|---|---| +|taos|Python 源代码目录，其下包含了算法具体保存目录 algo，放置杂项目录 misc， 单元测试和集成测试目录 test。 algo目录下 ad 放置异常检测算法代码， fc 放置预测算法代码| +|script|是安装脚本和发布脚本放置目录| +|model|放置针对数据集完成的训练模型| +|cfg| 配置文件目录| + +## 约定与限制 + +定义异常检测算法的 Python 代码文件 需放在 /taos/algo/ad 目录中，预测算法 Python 代码文件需要放在 /taos/algo/fc 目录中，以确保系统启动的时候能够正常加载对应目录下的 Python 文件。 + + +### 类命名规范 + +算法类的名称需要 以下划线开始，以 Service 结尾。例如：_KsigmaService 是 KSigma 异常检测算法的实现类。 + +### 类继承约定 + +异常检测算法需要从 `AbstractAnomalyDetectionService` 继承，并实现其核心抽象方法 `execute`. +预测算法需要从 `AbstractForecastService` 继承，同样需要实现其核心抽象方法 `execute`。 + +### 类属性初始化 +每个算法实现的类需要静态初始化两个类属性，分别是 + +`name`: 的触发调用关键词，全小写英文字母。 +`desc`：该算法的描述信息。 + +### 核心方法输入与输出约定 + +`execute` 是算法处理的核心方法。调用该方法的时候， `self.list` 已经设置好输入数组。 +异常检测输出结果 + +`execute` 的返回值是长度与 `self.list` 相同的数组，数组位置为 -1 的即为异常值点。例如：输入数组是 [2, 2, 2, 2, 100]， 如果 100 是异常点，那么返回值是 [1, 1, 1, 1, -1]。 +预测输出结果 + +对于预测算法， `AbstractForecastService` 的对象属性说明如下： + +|属性名称|说明|默认值| +|---|---|---| +|period|输入时序数据的周期性，多少个数据点表示一个完整的周期。如果没有周期性，那么设置为 0 即可。| 0| +|start_ts|预测数据的开始时间| 0| +|time_step|预测结果的两个数据点之间时间间隔|0 | +|fc_rows|预测结果数量| 0 | +|return_conf|返回结果中是否包含执行区间范围，如果算法计算结果不包含置信区间，那么上界和下界与自身相同| 1| +|conf|执行区间分位数 0.05| + + +预测返回结果如下： +```python +return { + "rows": self.fc_rows, # 预测数据行数 + "period": self.period, # 数据周期性，同输入 + "algo": "holtwinters", # 预测使用的算法 + "mse": mse, # 预测算法的 mse + "res": res # 结果数组 [时间戳数组, 预测结果数组, 预测结果执行区间下界数组，预测结果执行区间上界数组] +} +``` + + +## 示例代码 + +```python +import numpy as np +from service import AbstractAnomalyDetectionService + +# 算法实现类名称 需要以下划线 "_" 开始，并以 Service 结束，如下 _IqrService 是 IQR 异常检测算法的实现类。 +class _IqrService(AbstractAnomalyDetectionService): + """ IQR algorithm 定义类，从 AbstractAnomalyDetectionService 继承，并实现 AbstractAnomalyDetectionService类的抽象函数 """ + + # 定义算法调用关键词，全小写ASCII码(必须添加) + name = 'iqr' + + # 该算法的描述信息(建议添加) + desc = """found the anomaly data according to the inter-quartile range""" + + def __init__(self): + super().__init__() + + def execute(self): + """ execute 是算法实现逻辑的核心实现，直接修改该实现即可 """ + + # self.list 是输入数值列，list 类型，例如：[1,2,3,4,5]。设置 self.list 的方法在父类中已经进行了定义。实现自己的算法，修改该文件即可，以下代码使用自己的实现替换即可。 + #lower = np.quantile(self.list, 0.25) + #upper = np.quantile(self.list, 0.75) + + #min_val = lower - 1.5 * (upper - lower) + #max_val = upper + 1.5 * (upper - lower) + #threshold = [min_val, max_val] + + # 返回值是与输入数值列长度相同的数据列，异常值对应位置是 -1。例如上述输入数据列，返回数值列是 [1, 1, 1, 1, -1],表示 [5] 是异常值。 + return [-1 if k < threshold[0] or k > threshold[1] else 1 for k in self.list] + + + def set_params(self, params): + """该算法无需任何输入参数，直接重载父类该函数，不处理算法参数设置逻辑""" + pass +``` + + +## 单元测试 + +在测试文件目录中的 anomaly_test.py 中增加单元测试用例。 +```python +def test_iqr(self): + """ 测试 _IqrService 类 """ + s = loader.get_service("iqr") + + # 设置需要进行检测的输入数据 + s.set_input_list(AnomalyDetectionTest.input_list) + + # 测试 set_params 的处理逻辑 + try: + s.set_params({"k": 2}) + except ValueError as e: + self.assertEqual(1, 0) + + r = s.execute() + + # 绘制异常检测结果 + draw_ad_results(AnomalyDetectionTest.input_list, r, "iqr") + + # 检查结果 + self.assertEqual(r[-1], -1) + self.assertEqual(len(r), len(AnomalyDetectionTest.input_list)) +``` + +## 需要模型的算法 + +针对特定数据集，进行模型训练的算法，在训练完成后。需要将训练得到的模型保存在 model 目录中。需要注意的是，针对每个算法，需要建立独立的文件夹。例如 auto_encoder 的训练算法在 model 目录下建立了， autoencoder的目录，使用该算法针对不同数据集训练得到的模型，均需要放置在该目录下。 + +训练完成后的模型，使用 joblib 进行保存。 + +并在 model 目录下建立对应的文件夹存放该模型。 + +保存模型的调用，可参考 encoder.py 的方式，用户通过调用 set_params 方法，并指定参数 {"model": "ad_encoder_keras"} 的方式，可以调用该模型进行计算。 + +具体的调用方式如下： + +```python +def test_autoencoder_ad(self): + # 获取特定的算法服务 + s = loader.get_service("ac") + data = self.__load_remote_data_for_ad() + + # 设置异常检查的输入数据 + s.set_input_list(data) + + # 指定调用的模型，该模型是之前针对该数据集进行训练获得 + s.set_params({"model": "ad_encoder_keras"}) + # 执行检查动作，并返回结果 + r = s.execute() + + num_of_error = -(sum(filter(lambda x: x == -1, r))) + self.assertEqual(num_of_error, 109) +``` + diff --git a/docs/zh/06-advanced/06-data-analysis/index.md b/docs/zh/06-advanced/06-data-analysis/index.md index a1ca53d7d0..e3bf2f4158 100644 --- a/docs/zh/06-advanced/06-data-analysis/index.md +++ b/docs/zh/06-advanced/06-data-analysis/index.md @@ -5,9 +5,314 @@ title: 数据分析功能 ## 概述 -TDengine 提供数据分析功能的扩展组件，通过引入 ANode，TDengine 能够支持时间序列的机器学习分析 - -下图展示了数据分析的技术架构。 +TDengine 通过 ANode(AnalysisNode) 是提供数据分析功能的扩展组件，通过 Restful 接口提供分析服务，从而拓展 TDengine 的功能，支持时间序列高级分析功能。 +ANode 是无状态的数据分析节点，集群中可以存在多个 ANode节点，相互之间没有关联。将 ANode 注册到 TDengine 集群以后，通过 SQL 语句即可调用并完成时序分析任务。 +下图是数据分析的技术架构示意图。 ![数据分析功能架构图](./pic/data-analysis.png) +## 安装部署 +### 环境准备 +ANode 的要求节点上准备有 Python 3.10 及以上版本以及相应的Python包自动安装组件 Pip ，同时请确保能够正常连接互联网。 + +### 安装及卸载 +使用专门的 ANode 安装包 TDengine-enterprise-anode-1.x.x.tar.gz 进行 ANode 的安装部署工作，安装过程与 TDengien 的安装流程一致。 + +```bash +tar -xzvf TDengine-enterprise-anode-1.0.0.tar.gz +cd TDengine-enterprise-anode-1.0.0 +sudo ./install.sh +``` + +卸载 ANode，执行命令 `rmtaosanode` 即可。 + +### 其他 +为了避免 ANode 安装后影响目标节点现有的 Python 库。 ANode 使用 Python 虚拟环境运行，安装后的默认 Python 目录处于 `/var/lib/taos/taosanode/venv/`。为了避免反复安装虚拟环境带来的开销，卸载 ANode 并不会自动删除该虚拟环境，如果您确认不需要 Python 的虚拟环境，可以手动删除。 + +## 启动及停止服务 +安装 ANode 以后，可以使用`systemctl`来管理 ANode 的服务。使用如下命令可以启动/停止/检查状态。 + +```bash +systemctl start taosanoded +systemctl stop taosanoded +systemctl status taosanoded +``` + +## 目录及配置说明 +|目录/文件|说明| +|---------------|------| +|/usr/local/taos/taosanode/bin|可执行文件目录| +|/usr/local/taos/taosanode/resource|资源文件目录，链接到文件夹 /var/lib/taos/taosanode/resource/| +|/usr/local/taos/taosanode/lib|库文件目录| +|/var/lib/taos/taosanode/model/|模型文件目录，链接到文件夹 /var/lib/taos/taosanode/model| +|/var/log/taos/taosanode/|日志文件目录| +|/etc/taos/taosanode.ini|配置文件| + +### 配置说明 + +Anode 提供的 RestFul 服务使用 uWSGI 驱动，因此 ANode 的配置和 uWSGI 的配置在同一个配置文件中，具体如下： + +```ini +[uwsgi] +# charset +env=LC_ALL=en_US.UTF-8 + +# ip:port +http = 127.0.0.1:6050 + +# the local unix socket file than communicate to Nginx +#socket = 127.0.0.1:8001 +#socket-timeout=10 + +# base directory +chdir = /usr/local/taos/taosanode/lib + +# initialize python file +wsgi-file = /usr/local/taos/taosanode/lib/app.py + +# invoke app model +callable = app + +# auto remove unix Socket and pid file when stopping +vacuum = true + +# socket exec model +#chmod-socket = 664 + +# uWSGI pid +uid=root + +# uWSGI gid +gid=root + +# main process +master = true + +# the number of worker processes +processes = 2 + +# pid file +pidfile = /usr/local/taos/taosanode/uwsgi.pid + +# enable threads +enable-threads=true + +# the number of threads for each process +threads=2 + +# memory useage report +memory-report = true +reload-mercy = 10 + +# conflict with systemctl, so do NOT uncomment this +# daemonize = /var/log/taos/taosanode/taosanode.log + +# set log +logto = /var/log/taos/taosanode/taosanode.log + +# monitor server +stats = 127.0.0.1:8387 + +# python virtual environment directory +virtualenv = /usr/local/taos/taosanode/venv/ + +[taosanode] +# default app log file +app-log = /var/log/taos/taosanode/taosanode.app.log + +# model storage directory +model-dir=/usr/local/taos/taosanode/model/ + +# default log level +log-level = DEBUG +``` + +**提示** +请勿设置 `daemonize` 参数，该参数会导致 uWSGI 与 systemctl 冲突，从而无法正常启动。 + + +## ANode 基本操作 +### 管理 ANode +#### 创建 ANode +```sql +CREATE ANODE {node_url} +``` +node_url 是提供服务的 ANode 的 IP 和 PORT, 例如：`create anode 'http://localhost:6050'`。启动 ANode 以后如果不注册到 TDengine 集群中，无法提供正常的服务。不建议 ANode 注册到两个或多个集群中。 + +#### 查看 ANode +列出集群中所有的数据分析节点，包括其 `FQDN`, `PORT`, `STATUS`。 +```sql +SHOW ANODES; +``` + +#### 查看提供的时序数据分析服务 + +```SQL +SHOW ANODES FULL; +``` + +#### 强制刷新 TDengine 集群中分析算法缓存 +```SQL +UPDATE ANODE {node_id} +UPDATE ALL ANODES +``` + +#### 删除 ANode +```sql +DROP ANODE {anode_id} +``` +删除 ANode 只是将 ANode 从 TDengine 集群中删除，管理 ANode 的启停仍然需要使用`systemctl`命令。 + +### 时序数据分析功能 + +#### 白噪声检查 + +平台提供 Restful的服务检测输入时间序列是否是白噪声时间序列（White Noise Data, WND），白噪声时间序列及随机数序列。 +此外，分析平台要求输入的数据不能是 , 因此针对的所有数据均默认进行 白噪声检查。当前白噪声检查采用通行的 `Ljung-Box`检验，`Ljung-Box` 统计量检查过程需要遍历整个输入序列并进行计算。 +如果用户能够明确输入序列一定不是白噪声序列，那么可以通过输入参数，指定预测之前忽略该检查，从而节省分析过程的 CPU 计算资源。 +同时支持独立地针对输入序列进行白噪声检测（该检测功能暂不独立对外开放）。 + + +#### 数据重采样和时间戳对齐 + +数据分析平台支持将输入的数据进行重采样的预处理，从而确保输出结果按照用户指定的等间隔进行处理。处理过程分为两种类别： + +- 数据时间戳对齐。由于真实数据时间可能并非严格按照查询指定的时间戳输入。此时数据平台将自动将数据的时间间隔按照指定的时间间隔进行对齐。例如有输入时间序列：[11, 22, 29, 41]，用户指定时间间隔为 10，那么该序列将被对齐重整为以下序列 [10, 20, 30, 40]。 +- 数据时间重采样。用户输入的时间序列其采样频率超过了指定的查询需要获得结果的时间间隔，例如输入原始数据是 5， 但是输出结果的频率是 10. [0， 5， 10， 15， 20， 25， 30]，那么该输入数据列将重采用为间隔 为 10 的输入序列，其结果如下 [0, 10, 20，30]。[5, 15, 25] 处的数据将被丢弃。 + +需要注意的是，数据输入平台不支持缺失数据补齐后进行的预测分析，如果输入时间序列数据[11, 22, 29, 49]，并且用户要求的时间间隔为 10， 重整对齐后的序列是 [10, 20, 30, 50] 那么该序列进行预测分析将返回错误。 + + +#### 时序数据异常检测 +异常检测是针对输入的时序数据，使用预设或用户指定的算法确定时间序列中**可能**出现异常时间序列点，对于时间序列中若干个连续的异常点，将自动合并成为一个连续的（闭区间）异常窗口。对于只有单个点的场景，异常窗口窗口退化成为一个起始时间和结束时间相同的点。 +异常检测生成的异常窗口受检测算法和算法参数的共同影响，对于异常窗口范围内的数据，可以应用 TDengine 提供的聚合和标量函数进行查询或变换处理。 +对于输入时间序列 (1, 20), (2, 22), (3, 91), (4, 120), (5, 18), (6, 19)。系统检测到 (3, 91), (4, 120) 为异常点，那么返回的异常窗口是闭区间 [3, 4]。 + + +##### 语法 + +```SQL +ANOMALY_WINDOW(column_name, option_expr) + +option_expr: {" +algo=expr1 +[,wncheck=1|0] +[,expr2] +"} +``` + +1. `column`：进行时序数据异常检测的输入数据列，当前只支持单列输入，且只能是数值类型，不能是字符类型（例如：`NCHAR` `VARCHAR` `VARBINARY`等类型），**不支持函数表达式**。 +2. `options`：字符串。其中使用 K/V 调用异常检测的算法，及与算法相关的参数。采用 逗号分隔的K/V字符串表示，其中的字符串不需要使用单引号、双引号、或转意号等符号，不能使用中文及其他宽字符。例如：`algo=ksigma, k=2` 表示进行异常检测的算法是 ksigma，该算法接受的输入参数是 2。 +3. 异常检测的结果可以作为外层查询的子查询输入，在 `SELECT` 子句中使用的聚合函数或标量函数与其他类型的窗口查询相同。 +4. 输入数据默认进行白噪声检查，如果检查结果是输入数据是白噪声，将不会有任何（异常）窗口信息返回。 + +**参数说明** +|参数|含义|默认值| +|---|---|---| +|algo|异常检测调用的算法|iqr| +|wncheck|对输入数据列是否进行白噪声检查|取值为0或者1，默认值为 1，表示进行白噪声检查| + +异常检测的返回结果以窗口的形式呈现，因此窗口查询相关的伪列在这种场景下仍然可用。可以使用的伪列如下： +1. `_WSTART`： 异常窗口开始时间戳 +2. `_WEND`：异常窗口结束时间戳 +3. `_WDURATION`：异常窗口持续时间 + +**示例** +```SQL +--- 使用 iqr 算法进行异常检测，检测列 i32 列。 +SELECT _wstart, _wend, SUM(i32) +FROM ai.atb +ANOMALY_WINDOW(i32, "algo=iqr"); + +--- 使用 ksigma 算法进行异常检测，输入参数 k 值为 2，检测列 i32 列 +SELECT _wstart, _wend, SUM(i32) +FROM ai.atb +ANOMALY_WINDOW(i32, "algo=ksigma,k=2"); +``` + +``` +taos> SELECT _wstart, _wend, count(*) FROM ai.atb ANOMAYL_WINDOW(i32); + _wstart | _wend | count(*) | +============================================================================ + 2020-01-01 00:00:16.000 | 2020-01-01 00:00:16.001 | 1 | +Query OK, 1 row(s) in set (0.028946s) +``` + + +**可用异常检测算法** +- iqr +- ksigma +- grubbs +- lof +- shesd +- tac + + +#### 时序数据预测 +数据预测以一段训练数据作为输入，预测接下来一个连续时间区间内，时序数据的趋势。 + +##### 语法 +```SQL +FORECAST(column_expr, option_expr) + +option_expr: {" +algo=expr1 +[,wncheck=1|0] +[,conf=conf_val] +[,every=every_val] +[,rows=rows_val] +[,start=start_ts_val] +[,expr2] +"} + +``` +1. `column_expr`：预测的时序数据列。与异常检测相同，只支持数值类型输入。 +2. `options`：异常检测函数的参数，使用规则与 anomaly_window 相同。预测还支持`conf`, `every`, `rows`, `start`, `rows` 几个参数，其含义如下： + +**参数说明** + +|参数|含义|默认值| +|---|---|---| +|algo|预测分析使用的算法|holtwinters| +|wncheck|白噪声（white noise data）检查|默认值为 1，0 表示不进行检查| +|conf|预测数据的置信区间范围 ，取值范围[0, 100]|95| +|every|预测数据的采样间隔|输入数据的采样间隔| +|start|预测结果的开始时间戳|输入数据最后一个时间戳加上一个采样时间段| +|rows|预测结果的记录数|10| + +1. 预测查询结果新增了三个伪列，具体如下： `_FROWTS`：预测结果的时间戳、`_FLOW`：置信区间下界、`_FHIGH`：置信区间上界, 对于没有置信区间的预测算法，其置信区间同预测结果 +2. 更改参数 `START`：返回预测结果的起始时间，改变这个起始时间不会影响返回的预测数值，只影响起始时间。 +3. `EVERY`：可以与输入数据的采样频率不同。采样频率只能低于或等于输入数据采样频率，不能**高于**输入数据的采样频率。 +4. 对于某些不需要计算置信区间的算法，即使指定了置信区间，返回的结果中其上下界退化成为一个点。 + +**示例** + +```SQL +--- 使用 arima 算法进行预测，预测结果是 10 条记录（默认值），数据进行白噪声检查，默认置信区间 95%. +SELECT _flow, _fhigh, _frowts, FORECAST(i32, "algo=arima") +FROM ai.ftb; + +--- 使用 arima 算法进行预测，输入数据的是周期数据，每10个采样点是一个周期。返回置信区间是 95%. +SELECT _flow, _fhigh, _frowts, FORECAST(i32, "algo=arima,alpha=95,period=10") +FROM ai.ftb; +``` +``` +taos> select _flow, _fhigh, _frowts, forecast(i32) from ai.ftb; + _flow | _fhigh | _frowts | forecast(i32) | +======================================================================================== + 10.5286684 | 41.8038254 | 2020-01-01 00:01:35.001 | 26 | + -21.9861946 | 83.3938904 | 2020-01-01 00:01:36.001 | 30 | + -78.5686035 | 144.6729126 | 2020-01-01 00:01:37.001 | 33 | + -154.9797363 | 230.3057709 | 2020-01-01 00:01:38.001 | 37 | + -253.9852905 | 337.6083984 | 2020-01-01 00:01:39.001 | 41 | + -375.7857971 | 466.4594727 | 2020-01-01 00:01:40.001 | 45 | + -514.8043823 | 622.4426270 | 2020-01-01 00:01:41.001 | 53 | + -680.6343994 | 796.2861328 | 2020-01-01 00:01:42.001 | 57 | + -868.4956665 | 992.8603516 | 2020-01-01 00:01:43.001 | 62 | + -1076.1566162 | 1214.4498291 | 2020-01-01 00:01:44.001 | 69 | +``` + + +**可用预测算法** +- arima +- holtwinters diff --git a/docs/zh/06-advanced/06-data-analysis/pic/data-analysis.png b/docs/zh/06-advanced/06-data-analysis/pic/data-analysis.png index 1598238f2c..44fd82832f 100644 Binary files a/docs/zh/06-advanced/06-data-analysis/pic/data-analysis.png and b/docs/zh/06-advanced/06-data-analysis/pic/data-analysis.png differ diff --git a/docs/zh/06-advanced/06-data-analysis/pic/dir.png b/docs/zh/06-advanced/06-data-analysis/pic/dir.png new file mode 100644 index 0000000000..d5aafb4427 Binary files /dev/null and b/docs/zh/06-advanced/06-data-analysis/pic/dir.png differ