docs(ava/insight): add guidance and demo for insightPatternsExtractor

site/docs/api/insight/auto-insights.en.md

@@ -1,6 +1,6 @@
 ---
 title: getInsights
-order: 3
+order: 1
 ---
 
 <embed src='@/docs/common/style.md'></embed>
@@ -27,6 +27,7 @@ Run different algorithms from multi-dimensional data to discover interesting pat
 | impactWeight |  `number ∈(0, 1)` | Insight score = Impact score * impactWeight + Significance * (1 - impactWeight). | `0.3` |
 | homogeneous |  `boolean` | on/off extra homogeneous insight extraction. | `false` |
 | ignoreSubspace |  `boolean` | Whether to close the search for subspaces. | `false` |
+| algorithmParameter | `AlgorithmParameter` | Adjustable algorithm parameters | `{}` |
 
 * ***InsightVisualizationOptions*** Insight output visualization options
 
@@ -46,6 +47,7 @@ Run different algorithms from multi-dimensional data to discover interesting pat
 | visualizationSpecs |  `InsightVisualizationSpec[]` | The insight visualization scheme, including chart type, title, insight description, and chart configuration (based on G2Spec) | `[{ type: 'column_chart', caption: string, narrativeSpec: string[] \| IPhrase[][], chartSpec: G2Spec }]` |
 
 <embed src='@/docs/common/phrase.en.md'></embed>
+
 ### Usage
 
 * Specify the measures and dimensions involved in the calculation, and the number of insights returned.

site/docs/api/insight/auto-insights.zh.md

@@ -1,6 +1,6 @@
 ---
 title: getInsights
-order: 3
+order: 1
 ---
 
 <embed src='@/docs/common/style.md'></embed>
@@ -30,6 +30,7 @@ order: 3
 | impactWeight |  `number ∈(0, 1)` | 指定洞察分数计算的Impact权重： Insight score = Impact score * impactWeight + Significance * (1 - impactWeight). | `0.3` |
 | homogeneous |  `boolean` | 是否提取数据中的共性洞察 | `false` |
 | ignoreSubspace |  `boolean` | 是否关闭对子空间的洞察提取 | `false` |
+| algorithmParameter | `AlgorithmParameter` | 可调的算法参数 | `{}` |
 
 * ***InsightVisualizationOptions*** 可视化输出配置
 
@@ -51,6 +52,7 @@ order: 3
 
 
 <embed src='@/docs/common/phrase.zh.md'></embed>
+
 ### 用例
 
 * 指定参与计算的指标和维度，以及返回的洞察数量。

site/docs/api/insight/insight-patterns-extractor.en.md

@@ -0,0 +1,61 @@
+---
+title: insightPatternsExtractor
+order: 2
+---
+
+<embed src='@/docs/common/style.md'></embed>
+
+
+Extract specified types of insights from the data.
+
+## **insightPatternsExtractor**
+
+<i>(props: InsightExtractorProps): PatternInfo[]</i>
+
+
+* ***InsightExtractorProps*** configuration of insightPatternsExtractor
+
+| Properties | Type | Description | Default|  
+| ----| ---- | ---- | -----|
+| data | `Datum[]` | data | `[{ value: 1000, year: 2023 }, { value: 900, year: 2022 }]` |
+| measures | `Measure[]` | Specify the fields as measures and the corresponding aggregation methods | `[{ fieldName: 'value', method: 'SUM' }]` |
+| dimensions | `Dimensions[]` | Specify the dimensions involved in the calculation | `[fieldName: 'year']` |
+| insightType |  `InsightType[]` | Specify the types of insight | `['category_outlier', 'trend', 'change_point', 'time_series_outlier', 'majority','low_variance', 'correlation']`(All supported types) |
+| options |  `InsightExtractorOptions` | optional configuration |  |
+
+* ***InsightExtractorOptions*** optional configuration
+
+| Properties | Type | Description | Default|  
+| ----| ---- | ---- | -----|
+| algorithmParameter | `AlgorithmParameter` | Adjustable algorithm parameters | `{}` |
+| filterInsight | `boolean` | Whether to filter significant insights | `false` |
+| dataValidation | `boolean` | Whether to verify whether the data meets the requirements | `false` |
+| dataProcessInfo | `Extra` | Configuration of data processing during data verification | `{}` |
+| visualizationOptions | `InsightVisualizationOptions` | visualization options | `{ lang: 'zh-CN' }` |
+
+* ***PatternInfo*** Includes the following types of insights
+
+| Type | Description | Example|  
+| ----| ---- | ---- |
+| TrendInfo | trend | `{ type: 'trend', significance: 0.99, trend: 'decreasing', regression: {} }`|
+| TimeSeriesOutlierInfo | time series outlier | `{ type: 'time_series_outlier', significance: 0.96, baselines: [], thresholds: [], x: 12, y: 32, index: 2 }` |
+| CategoryOutlierInfo |  category outlier | `{ type: 'category_outlier', significance: 0.97, x: 12, y: 32, index: 2 }` |
+| LowVarianceInfo |  low variance | `{ type: 'low_variance', significance: 0.99, dimension: 'year', measure: 'country', mean: 43 }` |
+| ChangePointInfo |  change point | `{ type: 'change_point', significance: 0.90, x: 12, y: 32, index: 2 }` |
+| CorrelationInfo |  correlation | `{ type: 'correlation', significance: 0.96, pcorr: 0.9, measure: [] }` |
+| MajorityInfo |  majority | `{ type: 'majority', significance: 0.98, proportion: 0.6, x: 12, y: 32, index: 2 }` |
+
+### 用例
+
+* Extract trend insights from the data.
+
+```ts
+import { insightPatternsExtractor } from '@antv/ava';
+
+insightPatternsExtractor({
+  data,
+  measures: [{ fieldName: 'life_expect', method: 'MEAN' }],
+  dimensions: [{ fieldName: 'date' }],
+  insightType: 'trend',
+});
+```

site/docs/api/insight/insight-patterns-extractor.zh.md

@@ -0,0 +1,61 @@
+---
+title: insightPatternsExtractor
+order: 2
+---
+
+<embed src='@/docs/common/style.md'></embed>
+
+
+从数据中提取的指定类型的洞察。
+
+## **insightPatternsExtractor**
+
+<i>(props: InsightExtractorProps): PatternInfo[]</i>
+
+
+* ***InsightExtractorProps*** 配置项
+
+| 属性 | 类型 | 描述 | 示例 |  
+| ----| ---- | ---- | -----|
+| data | `Datum[]` | 数据 | `[{ value: 1000, year: 2023 }, { value: 900, year: 2022 }]` |
+| measures | `Measure[]` | 指定作为指标的字段和对应的聚合方法 | `[{ fieldName: 'value', method: 'SUM' }]` |
+| dimensions | `Dimensions[]` | 指定参与计算的维度 | `[fieldName: 'year']` |
+| insightType |  `InsightType[]` | 指定计算的洞察类型 | `['category_outlier', 'trend', 'change_point', 'time_series_outlier', 'majority','low_variance', 'correlation']`(所有支持类型) |
+| options |  `InsightExtractorOptions` | 可选配置项 |  |
+
+* ***InsightExtractorOptions*** 可选配置项
+
+| 属性 | 类型 | 描述 | 默认值 |  
+| ----| ---- | ---- | -----|
+| algorithmParameter | `AlgorithmParameter` | 可调的算法参数 | `{}` |
+| filterInsight | `boolean` | 是否过滤有效洞察 | `false` |
+| dataValidation | `boolean` | 是否校验数据是否符合要求 | `false` |
+| dataProcessInfo | `Extra` | 数据校验时数据处理的配置 | `{}` |
+| visualizationOptions | `InsightVisualizationOptions` | 可视化spec配置 | `{ lang: 'zh-CN' }` |
+
+* ***PatternInfo*** 包含以下几种洞察类型
+
+| 类型 | 描述 | 示例 |  
+| ----| ---- | ---- |
+| TrendInfo | 趋势 | `{ type: 'trend', significance: 0.99, trend: 'decreasing', regression: {} }`|
+| TimeSeriesOutlierInfo | 时序异常 | `{ type: 'time_series_outlier', significance: 0.96, baselines: [], thresholds: [], x: 12, y: 32, index: 2 }` |
+| CategoryOutlierInfo |  类别 | `{ type: 'category_outlier', significance: 0.97, x: 12, y: 32, index: 2 }` |
+| LowVarianceInfo |  低方差 | `{ type: 'low_variance', significance: 0.99, dimension: 'year', measure: 'country', mean: 43 }` |
+| ChangePointInfo |  突变点 | `{ type: 'change_point', significance: 0.90, x: 12, y: 32, index: 2 }` |
+| CorrelationInfo |  相关性 | `{ type: 'correlation', significance: 0.96, pcorr: 0.9, measure: [] }` |
+| MajorityInfo |  主要影响因素 | `{ type: 'majority', significance: 0.98, proportion: 0.6, x: 12, y: 32, index: 2 }` |
+
+### 用例
+
+* 指定从数据中提取趋势类型的洞察结果。
+
+```ts
+import { insightPatternsExtractor } from '@antv/ava';
+
+insightPatternsExtractor({
+  data,
+  measures: [{ fieldName: 'life_expect', method: 'MEAN' }],
+  dimensions: [{ fieldName: 'date' }],
+  insightType: 'trend',
+});
+```

site/docs/guide/insight/intro.en.md

@@ -22,6 +22,10 @@ The pipeline of Auto-Insights:
 
 ## 🔨 Usage
 
+### getInsights Usage
+
+The `getInsights` method runs different algorithms from multi-dimensional data to discover interesting patterns in the data, and perform unified evaluation of different types of patterns, and return high-quality data insights based on scores. Detailed input and output parameters are described in the [getInsights API](../../api/insight/auto-insight.en.md).
+
 
 ```ts
 import { getInsights } from '@antv/ava';
@@ -36,6 +40,22 @@ getInsights(data, {
 });
 ```
 
+### insightPatternsExtractor Usage
+
+If you only want to get insights of a specific type, `insightPatternsExtractor` will be your first choice. Detailed input and output parameters are described in the [insightPatternsExtractor API](../../api/insight/insight-patterns-extractor.en.md).
+
+
+```ts
+import { insightPatternsExtractor } from '@antv/ava';
+
+insightPatternsExtractor({
+  data,
+  measures: [{ fieldName: 'life_expect', method: 'MEAN' }],
+  dimensions: [{ fieldName: 'date' }],
+  insightType: 'trend',
+});
+```
+
 ## 📖 Documentation
 
 For more usages, please check the [API Reference](../../api/insight/auto-insights).

site/docs/guide/insight/intro.zh.md

@@ -23,6 +23,10 @@ order: 0
 
 ## 🔨 使用
 
+### getInsights 使用
+
+`getInsights` 方法用于从多维数据中运行不同算法来发现数据中有趣的模式，并将不同类型的模式进行统一评估，按照分数返回高质量的数据洞察结果。输入输出参数详见 [getInsights API](../../api/insight/auto-insight.zh.md)。
+
 
 ```ts
 import { getInsights } from '@antv/ava';
@@ -37,6 +41,21 @@ getInsights(data, {
 });
 ```
 
+### insightPatternsExtractor 使用
+
+如果只想获取指定类型的洞察结果，那么`insightPatternsExtractor`将是你的首选。输入输出参数详见 [insightPatternsExtractor API](../../api/insight/insight-patterns-extractor.zh.md)。
+
+
+```ts
+import { insightPatternsExtractor } from '@antv/ava';
+
+insightPatternsExtractor({
+  data,
+  measures: [{ fieldName: 'life_expect', method: 'MEAN' }],
+  dimensions: [{ fieldName: 'date' }],
+  insightType: 'trend',
+});
+```
 
 ## 📖 文档
 

site/examples/insight/basic/demo/meta.json

@@ -19,6 +19,14 @@
         "en": "Custom measures and dimensions"
       },
       "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/ixkElKx8UT/li-custom-measures.gif"
+    },
+    {
+      "filename": "specify-type.jsx",
+      "title": {
+        "zh": "指定洞察类型",
+        "en": "Extract specified types of insights"
+      },
+      "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/zt2jXO97%262/li-basic.gif"
     }
   ]
 }