Merge pull request #28754 from taosdata/doc/analysis

doc: update analytics docs.

docs/zh/06-advanced/06-TDgpt/04-forecast/02-arima.md

@@ -51,4 +51,4 @@ FORECAST(i32, "algo=arima,alpha=95,period=10,start_p=1,max_p=5,start_q=1,max_q=5
 
 ### 参考文献
 - 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
+- [https://baike.baidu.com/item/自回归滑动平均模型/5023931](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)

docs/zh/06-advanced/06-TDgpt/04-forecast/index.md

@@ -3,7 +3,7 @@ title: 预测算法
 description: 预测算法
 ---
 
-时序数据预测处理以持续一个时间段的时序数据作为输入，预测接下来一个连续时间区间内时间序列数据分布及运行的趋势。用户可以指定输出的（预测）时间序列数据点的数量，因此其输出的结果行数不确定。为此，我们引入了 `FORECAST` 函数提供预测服务。基础数据（用于预测的历史时间序列数据）是该函数的输入，预测结果是该函数的输出。用户可以通过 `FORECASTD` 函数调用 Anode 提供的预测算法提供的服务。
+时序数据预测处理以持续一个时间段的时序数据作为输入，预测接下来一个连续时间区间内时间序列数据分布及运行的趋势。用户可以指定输出的（预测）时间序列数据点的数量，因此其输出的结果行数不确定。为此，我们引入了 `FORECAST` 函数提供预测服务。基础数据（用于预测的历史时间序列数据）是该函数的输入，预测结果是该函数的输出。用户可以通过 `FORECAST` 函数调用 Anode 提供的预测算法提供的服务。
 
 ##### 语法
 ```SQL

docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/02-anomaly-detection.md

@@ -18,7 +18,7 @@ sidebar_label: "异常检测算法"
 |k|标准差倍数|选填|3|
 
 
-- IQR<sup>[2]</sup>：四分位距 (Interquartile range, IQR) 是一种衡量变异性的方法. 四分位数将一个按等级排序的数据集划分为四个相等的部分。即 Q1（第 1 个四分位数）、Q2（第 2 个四分位数）和 Q3（第 3 个四分位数）。IQR 定义为 Q3–Q1，位于 Q3+1.5。无输入参数。
+- IQR<sup>[2]</sup>：四分位距 (Interquartile range, IQR) 是一种衡量变异性的方法. 四分位数将一个按等级排序的数据集划分为四个相等的部分。即 Q1（第 1 个四分位数）、Q2（第 2 个四分位数）和 Q3（第 3 个四分位数）。IQR 定义为 $Q3–Q1$，位于 $Q3+1.5$。无输入参数。
 
 - Grubbs<sup>[3]</sup>: 又称为 Grubbs' test，即最大标准残差测试。Grubbs 通常用作检验最大值、最小值偏离均值的程度是否为异常，该单变量数据集遵循近似标准正态分布。非正态分布数据集不能使用该方法。无输入参数。
 
@@ -26,19 +26,19 @@ sidebar_label: "异常检测算法"
   
 |参数|说明|是否必选|默认值|
 |---|---|---|---|
-|k|异常点在输入数据集中占比，范围是$`1\le K \le 49.9`$ |选填|5|
+|k|异常点在输入数据集中占比，范围是 $1\le K \le 49.9$ |选填|5|
 
 
 ### 基于数据密度的检测方法
-LOF<sup>[5]</sup>: 局部离群因子（LOF，又叫局部异常因子）算法是 Breunig 于 2000 年提出的一种基于密度的局部离群点检测算法，该方法适用于不同类簇密度分散情况迥异的数据。根据数据点周围的数据密集情况，首先计算每个数据点的一个局部可达密度，然后通过局部可达密度进一步计算得到每个数据点的一个离群因子，该离群因子即标识了一个数据点的离群程度，因子值越大，表示离群程度越高，因子值越小，表示离群程度越低。最后，输出离群程度最大的 top(n) 个点。
+LOF<sup>[5]</sup>: 局部离群因子（LOF，又叫局部异常因子）算法是 Breunig 于 2000 年提出的一种基于密度的局部离群点检测算法，该方法适用于不同类簇密度分散情况迥异的数据。根据数据点周围的数据密集情况，首先计算每个数据点的一个局部可达密度，然后通过局部可达密度进一步计算得到每个数据点的一个离群因子，该离群因子即标识了一个数据点的离群程度，因子值越大，表示离群程度越高，因子值越小，表示离群程度越低。最后，输出离群程度最大的 $top(n)$ 个点。
 
 
-### 基于深度学习的检测方法
+### 基于自编码器的检测方法
 使用自动编码器的异常检测模型。可以对具有周期性的数据具有较好的检测结果。但是使用该模型需要针对输入的时序数据进行训练，同时将训练完成的模型部署到服务目录中，才能够运行与使用。
 
 
 ### 参考文献
-1. https://en.wikipedia.org/wiki/68%E2%80%9395%E2%80%9399.7_rule
+1. [https://en.wikipedia.org/wiki/68–95–99.7 rule](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).

docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/index.md

@@ -3,6 +3,8 @@ title: 异常检测算法
 description: 异常检测算法
 ---
 
+import ad from '../pic/anomaly-detection.png';
+
 时序数据异常检测，在TDengine 查询处理中以异常窗口的形式服务。因此，可以将异常检测获得的窗口视为一种特殊的**事件窗口**，区别在于异常窗口的触发条件和结束条件不是用户指定，而是检测算法自动识别。因此，可以应用在事件窗口上的函数均可应用在异常窗口中。由于异常检测结果是一个时间窗口，因此调用异常检测的方式也与使用事件窗口的方式相同，在 `WHERE` 子句中使用 `ANOMALY_WINDOW` 关键词即可调用时序数据异常检测服务，同时窗口伪列（`_WSTART`, `_WEND`, `_WDURATION`）也能够像其他窗口函数一样使用。例如：
 
 ```SQL
@@ -11,9 +13,9 @@ FROM foo
 ANOMALY_WINDOW(i32, "algo=iqr");
 ```
 
-如下图所示，Anode 将返回时序数据异常窗口 [10:51:30, 10:53:40] 
+如下图所示，Anode 将返回时序数据异常窗口 $[10:51:30, 10:53:40]$ 
 
-<img src="../pic/anomaly-detection.png" width="560" alt="异常检测" />
+<img src={ad} width="760" alt="异常检测" />
 
 在此基础上，用户可以针对异常窗口内的时序数据进行查询聚合、变换处理等操作。
 

docs/zh/06-advanced/06-TDgpt/06-dev/03-ad.md

@@ -8,7 +8,7 @@ sidebar_label: "异常检测"
 
 ### 输出约定
 `execute` 方法执行完成后的返回值是长度与 `self.list` 相同的数组，数组位置 -1 的标识异常值点。
-> 例如：对于输入测量值序列 [2, 2, 2, 2, 100]， 假设 100 是异常点，那么方法返回的结果数组则为 [1, 1, 1, 1, -1]。
+> 例如：对于输入测量值序列 $[2, 2, 2, 2, 100]$， 假设 100 是异常点，那么方法返回的结果数组则为 $[1, 1, 1, 1, -1]$。
 
 
 ### 示例代码

docs/zh/06-advanced/06-TDgpt/06-dev/index.md

@@ -29,7 +29,7 @@ TDgpt 是一个可扩展的时序数据高级分析平台，用户仅按照简
 
 |目录|说明|
 |---|---|
-|taos|Python 源代码目录，其下包含了算法具体保存目录 algo，放置杂项目录 misc，单元测试和集成测试目录 test。 algo 目录下 ad 保存异常检测算法代码，fc 目录保存预测算法代码|
+|taosanalytics| 源代码目录，其下包含了算法具体保存目录 algo，放置杂项目录 misc，单元测试和集成测试目录 test。 algo 目录下 ad 保存异常检测算法代码，fc 目录保存预测算法代码|
 |script|是安装脚本和发布脚本放置目录|
 |model|放置针对数据集完成的训练模型|
 |cfg|配置文件目录|
@@ -42,7 +42,7 @@ TDgpt 是一个可扩展的时序数据高级分析平台，用户仅按照简
 
 ### 类命名规范
 
-由于算法采用自动加载，因此其只识别按照特定命名方式的类。算法类的名称需要以下划线开始，以 Service 结尾。例如：_KsigmaService 是  KSigma 异常检测算法类。
+由于算法采用自动加载，因此其只识别按照特定命名方式的类。算法类的名称需要以下划线开始，以 Service 结尾。例如：`_KsigmaService` 是  KSigma 异常检测算法类。
 
 ### 类继承约定
 
@@ -60,33 +60,23 @@ TDgpt 是一个可扩展的时序数据高级分析平台，用户仅按照简
 SELECT COUNT(*) FROM foo ANOMALY_DETECTION(col_name, 'algo=algo_name')
 ```
   
-## 需要模型的算法
+## 添加具有训练模型的分析算法
 
-针对特定数据集，进行模型训练的算法，在训练完成后。需要将训练得到的模型保存在 model 目录中。需要注意的是，针对每个算法，需要建立独立的文件夹。例如 auto_encoder 的训练算法在 model 目录下建立 autoencoder 的目录，使用该算法针对不同数据集训练得到的模型，均需要放置在该目录下。
+某些深度学习的分析算法需要使用输入时间序列数据进行训练，然后生成针对训练数据集的分析模型。这种情况下，同一个分析算法对应不同的输入数据集有不同的分析模型。
+这种类型的分析算法要添加到 TDgpt 中，首先需要在 `model` 目录中建立目录，将采用该算法针对不同的输入时间序列数据生成的训练模型均保存在该目录下。如下图所示，针对不同的数据集，采用自编码器训练的数据异常检测算法生成的模型均保存在该目录下。为了确保模型能够正常读取加载，要求存储的模型使用`joblib`库进行序列化保存。
+采用训练-保存模型的方式可以一次训练，多次调用的优势。避免动态训练调用所带来的反复训练开销。
 
-训练完成后的模型，使用 joblib 进行保存。
-
-并在 model 目录下建立对应的文件夹存放该模型。
-
-保存模型的调用，可参考  encoder.py 的方式，用户通过调用  set_params 方法，并指定参数 `{"model": "ad_encoder_keras"}` 的方式，可以调用该模型进行计算。
-
-具体的调用方式如下：
+调用已经保存的模型，需要首先调用`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)
 ```