From a2b1841c4f724b6e2faab383832a4e6426e6e2c3 Mon Sep 17 00:00:00 2001 From: "yihe.lxg" Date: Tue, 21 Nov 2023 15:19:52 +0800 Subject: [PATCH] docs(ava/insight): add guidance and demo for insightPatternsExtractor --- site/docs/api/insight/auto-insights.en.md | 4 +- site/docs/api/insight/auto-insights.zh.md | 4 +- .../insight/insight-patterns-extractor.en.md | 61 ++++++ .../insight/insight-patterns-extractor.zh.md | 61 ++++++ site/docs/guide/insight/intro.en.md | 20 ++ site/docs/guide/insight/intro.zh.md | 19 ++ site/examples/insight/basic/demo/meta.json | 8 + .../insight/basic/demo/specify-type.jsx | 193 ++++++++++++++++++ 8 files changed, 368 insertions(+), 2 deletions(-) create mode 100644 site/docs/api/insight/insight-patterns-extractor.en.md create mode 100644 site/docs/api/insight/insight-patterns-extractor.zh.md create mode 100644 site/examples/insight/basic/demo/specify-type.jsx diff --git a/site/docs/api/insight/auto-insights.en.md b/site/docs/api/insight/auto-insights.en.md index 1e3aa890c..cf41e571a 100644 --- a/site/docs/api/insight/auto-insights.en.md +++ b/site/docs/api/insight/auto-insights.en.md @@ -1,6 +1,6 @@ --- title: getInsights -order: 3 +order: 1 --- @@ -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 }]` | + ### Usage * Specify the measures and dimensions involved in the calculation, and the number of insights returned. diff --git a/site/docs/api/insight/auto-insights.zh.md b/site/docs/api/insight/auto-insights.zh.md index d633c5d6b..ab67c250f 100644 --- a/site/docs/api/insight/auto-insights.zh.md +++ b/site/docs/api/insight/auto-insights.zh.md @@ -1,6 +1,6 @@ --- title: getInsights -order: 3 +order: 1 --- @@ -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 + ### 用例 * 指定参与计算的指标和维度，以及返回的洞察数量。 diff --git a/site/docs/api/insight/insight-patterns-extractor.en.md b/site/docs/api/insight/insight-patterns-extractor.en.md new file mode 100644 index 000000000..716432c8d --- /dev/null +++ b/site/docs/api/insight/insight-patterns-extractor.en.md @@ -0,0 +1,61 @@ +--- +title: insightPatternsExtractor +order: 2 +--- + + + + +Extract specified types of insights from the data. + +## **insightPatternsExtractor** + +(props: InsightExtractorProps): PatternInfo[] + + +* ***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', +}); +``` diff --git a/site/docs/api/insight/insight-patterns-extractor.zh.md b/site/docs/api/insight/insight-patterns-extractor.zh.md new file mode 100644 index 000000000..19f19039f --- /dev/null +++ b/site/docs/api/insight/insight-patterns-extractor.zh.md @@ -0,0 +1,61 @@ +--- +title: insightPatternsExtractor +order: 2 +--- + + + + +从数据中提取的指定类型的洞察。 + +## **insightPatternsExtractor** + +(props: InsightExtractorProps): PatternInfo[] + + +* ***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', +}); +``` diff --git a/site/docs/guide/insight/intro.en.md b/site/docs/guide/insight/intro.en.md index c158e223b..e9a5a0f08 100644 --- a/site/docs/guide/insight/intro.en.md +++ b/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). diff --git a/site/docs/guide/insight/intro.zh.md b/site/docs/guide/insight/intro.zh.md index 9146f6950..7774ef569 100644 --- a/site/docs/guide/insight/intro.zh.md +++ b/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', +}); +``` ## 📖 文档 diff --git a/site/examples/insight/basic/demo/meta.json b/site/examples/insight/basic/demo/meta.json index f748d8126..6d0628a51 100644 --- a/site/examples/insight/basic/demo/meta.json +++ b/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" } ] } diff --git a/site/examples/insight/basic/demo/specify-type.jsx b/site/examples/insight/basic/demo/specify-type.jsx new file mode 100644 index 000000000..fd602f100 --- /dev/null +++ b/site/examples/insight/basic/demo/specify-type.jsx @@ -0,0 +1,193 @@ +import React, { useState, useEffect, useMemo } from 'react'; + +import ReactDOM from 'react-dom'; +import { Spin } from 'antd'; +import { insightPatternsExtractor } from '@antv/ava'; +import { JSONView, TableView, StepBar } from 'antv-site-demo-rc'; + +const App = () => { + const data = useMemo( + () => [ + { + date: '2019-08-01', + discount_price: 727.12, + }, + { + date: '2019-08-02', + discount_price: 729.59, + }, + { + date: '2019-08-03', + discount_price: 730.21, + }, + { + date: '2019-08-04', + discount_price: 732.11, + }, + { + date: '2019-08-05', + discount_price: 733.22, + }, + { + date: '2019-08-06', + discount_price: 741.19, + }, + { + date: '2019-08-07', + discount_price: 742.37, + }, + { + date: '2019-08-08', + discount_price: 752.34, + }, + { + date: '2019-08-09', + discount_price: 761.12, + }, + { + date: '2019-08-10', + discount_price: 783.99, + }, + { + date: '2019-08-11', + discount_price: 791.23, + }, + { + date: '2019-08-12', + discount_price: 781.99, + }, + { + date: '2019-08-13', + discount_price: 835.71, + }, + { + date: '2019-08-14', + discount_price: 839.24, + }, + { + date: '2019-08-15', + discount_price: 883.51, + }, + { + date: '2019-08-16', + discount_price: 873.98, + }, + { + date: '2019-08-17', + discount_price: 802.78, + }, + { + date: '2019-08-18', + discount_price: 807.05, + }, + { + date: '2019-08-19', + discount_price: 885.12, + }, + { + date: '2019-08-20', + discount_price: 1018.85, + }, + { + date: '2019-08-21', + discount_price: 934.49, + }, + { + date: '2019-08-22', + discount_price: 908.74, + }, + { + date: '2019-08-23', + discount_price: 930.55, + }, + { + date: '2019-08-24', + discount_price: 978.53, + }, + { + date: '2019-08-25', + discount_price: 931.47, + }, + { + date: '2019-08-26', + discount_price: 891, + }, + { + date: '2019-08-27', + discount_price: 836.41, + }, + { + date: '2019-08-28', + discount_price: 826.11, + }, + { + date: '2019-08-29', + discount_price: 820.11, + }, + { + date: '2019-08-30', + discount_price: 811.11, + }, + ], + [] + ); + const [result, setResult] = useState([]); + const [insightLoading, setInsightLoading] = useState(true); + const [currentStep, setCurrentStep] = useState(0); + + const getMyInsights = async () => { + if (data) { + const insightResult = insightPatternsExtractor({ + data, + dimensions: [{ fieldName: 'date' }], + measures: [{ fieldName: 'discount_price', method: 'SUM' }], + insightType: 'time_series_outlier', + options: { + dataValidation: true, + algorithmParameter: { + outlier: { + method: 'IQR', + iqrK: 1.5, + }, + }, + }, + }); + setResult(insightResult); + setInsightLoading(false); + } + }; + + useEffect(() => { + getMyInsights(); + }, []); + + const dataContent = ; + + const insightsContent = ; + + const steps = [ + { + title: 'Data', + desc: 'Source data:', + content: dataContent, + }, + { + title: 'Insights', + desc: 'Insights extracted from data:', + content: insightsContent, + }, + ]; + + return ( + <> + +

{steps[currentStep].desc}

+ +
+ {steps[currentStep].content} +
+ + ); +}; + +ReactDOM.render(, document.getElementById('container'));