diff --git a/site/docs/api/insight/auto-insights.en.md b/site/docs/api/insight/auto-insights.en.md index cf41e571..a60287b6 100644 --- a/site/docs/api/insight/auto-insights.en.md +++ b/site/docs/api/insight/auto-insights.en.md @@ -27,7 +27,25 @@ 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 | `{}` | +| algorithmParameter | `AlgorithmParameter` | Adjustable algorithm parameters | none | +| dataProcessInfo | `Extra` | Configuration of data processing during data verification | none | + +* ***AlgorithmParameter*** Adjustable algorithm parameters + +| Properties | Type | Description | Default| +| ----| ---- | ---- | -----| +| outlier | `OutlierParameter` | parameter of category outlier and time series outlier algorithm | `{ method: 'IQR', iqrK: 1.5, confidenceInterval: 0.95 }` | +| trend | `CommonParameter` | Parameters of the trend algorithm | `{ threshold： 0.05 }` | +| changePoint | `CommonParameter` | Parameter of the change point algorithm | `{ threshold： 0.05 }` | +| correlation | `PCorrTestParameter` | Parameter of the correlation algorithm | `{ alpha 0.05, alternative: 'two-sided', rho: 0 }` | +| lowVariance | `LowVarianceParameter` | Parameter of the low variance algorithm | `{ cvThreshold 0.15 }` | +| majority | `MajorityParameter` | Parameter of the majority algorithm | `{ limit 0.6 }` | + +* ***Extra*** Parameter passed through to the data frame during data pre-processing + +| Properties | Type | Description | Default| +| ----| ---- | ---- | -----| +| strictDatePattern | `boolean` | Whether only the main standard symbols recommended in ISO 8601 can be recognized as date fields | `true` | * ***InsightVisualizationOptions*** Insight output visualization options diff --git a/site/docs/api/insight/auto-insights.zh.md b/site/docs/api/insight/auto-insights.zh.md index ab67c250..50a1bc66 100644 --- a/site/docs/api/insight/auto-insights.zh.md +++ b/site/docs/api/insight/auto-insights.zh.md @@ -30,7 +30,26 @@ order: 1 | impactWeight | `number ∈(0, 1)` | 指定洞察分数计算的Impact权重： Insight score = Impact score * impactWeight + Significance * (1 - impactWeight). | `0.3` | | homogeneous | `boolean` | 是否提取数据中的共性洞察 | `false` | | ignoreSubspace | `boolean` | 是否关闭对子空间的洞察提取 | `false` | -| algorithmParameter | `AlgorithmParameter` | 可调的算法参数 | `{}` | +| algorithmParameter | `AlgorithmParameter` | 可调的算法参数 | 无 | +| dataProcessInfo | `Extra` | 数据校验时数据处理的配置 | 无 | + +* ***AlgorithmParameter*** 可调的算法参数 + +| 属性 | 类型 | 描述 | 默认值 | +| ----| ---- | ---- | -----| +| outlier | `OutlierParameter` | 类别异常（category_outlier）和时序异常（time_series_outlier）的算法参数 | `{ method: 'IQR', iqrK: 1.5, confidenceInterval: 0.95 }` | +| trend | `CommonParameter` | 趋势（trend）洞察算法的参数 | `{ threshold： 0.05 }` | +| changePoint | `CommonParameter` | 突变点算法（change_point）的参数 | `{ threshold： 0.05 }` | +| correlation | `PCorrTestParameter` | 相关性算法（correlation） 的参数 | `{ alpha 0.05, alternative: 'two-sided', rho: 0 }` | +| lowVariance | `LowVarianceParameter` | 低方差算法（low_variance）的参数 | `{ cvThreshold 0.15 }` | +| majority | `MajorityParameter` | 主要影响因素算法（majority）的参数 | `{ limit 0.6 }` | + +* ***Extra*** 数据处理配置 + +| 属性 | 类型 | 描述 | 默认值 | +| ----| ---- | ---- | -----| +| strictDatePattern | `boolean` | 是否按照ISO标准识别日期字段 | `true` | + * ***InsightVisualizationOptions*** 可视化输出配置 diff --git a/site/docs/api/insight/get-specific-insight.en.md b/site/docs/api/insight/get-specific-insight.en.md new file mode 100644 index 00000000..4e9bb607 --- /dev/null +++ b/site/docs/api/insight/get-specific-insight.en.md @@ -0,0 +1,66 @@ +--- +title: getSpecificInsight +order: 3 +--- + + + + +Extract insight of a specified type from the data and corresponding visualization specs. + +## **getSpecificInsight** + +(props: SpecificInsightProps): SpecificInsightResult + +* ***SpecificInsightProps*** is the same as `InsightExtractorProps`. See [InsightExtractorProps API](./insight-patterns-extractor.en.md) for more details. + +* ***SpecificInsightResult*** output + +| Properties | Type | Description | Example| +| ----| ---- | ---- | -----| +| subspace | `Subspace` | The subspace of the data subject | `[{ dimension: 'Year', value: '2000' }]`(subspace: Year = 2000) | +| dimensions | `string[]` | The dimensions of the data subject | `['country']` | +| measures | `Measure[]` | The measures of the data subject | `[{ field: 'life_expect', method: 'MEAN' }]` | +| data | `Datum[]` | data | `[{ country: 'China', life_expect: 61 }]` | +| patterns | `PatternInfo[]` | The collection of patterns in the data | `[{ type: 'outlier', significance: 0.98, dimension: 'country', measure: 'life_expect', index: 5, x: 'china', y: '43' }, ...]` | +| 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 + +* Extract time series outlier insights from the data. + +```ts +import { getSpecificInsight } from '@antv/ava'; + +getSpecificInsight({ + data, + measures: [{ fieldName: 'life_expect', method: 'MEAN' }], + dimensions: [{ fieldName: 'date' }], + insightType: 'time_series_outlier', +}); +``` + +* Custom algorithm parameters + +```ts +import { getSpecificInsight } from '@antv/ava'; + +const insightResult = getSpecificInsight({ + data, + measures: [{ fieldName: 'life_expect', method: 'MEAN' }], + dimensions: [{ fieldName: 'date' }], + insightType: 'time_series_outlier', + options: { + // Filter out not significant insights + filterInsight: true, + // Verify whether the input meets the algorithm requirements + dataValidation: true, + // Adjust the significance test threshold + algorithmParameter: { + outlier: { + threshold: 0.05, + }, + }, + } +}); +``` diff --git a/site/docs/api/insight/get-specific-insight.zh.md b/site/docs/api/insight/get-specific-insight.zh.md new file mode 100644 index 00000000..b850f809 --- /dev/null +++ b/site/docs/api/insight/get-specific-insight.zh.md @@ -0,0 +1,66 @@ +--- +title: getSpecificInsight +order: 3 +--- + + + +从数据中提取的指定类型的洞察和对应的可视化spec。 + +## **getSpecificInsight** + +(props: SpecificInsightProps): SpecificInsightResult + +* ***SpecificInsightProps*** 和`InsightExtractorProps`相同，详见 [InsightExtractorProps API](./insight-patterns-extractor.zh.md)。 + +* ***SpecificInsightResult*** 输出内容 + +| 属性 | 类型 | 描述 | 示例 | +| ----| ---- | ---- | -----| +| subspace | `Subspace` | 该洞察数据主体的子空间信息（Subspace）。 | `[{ dimension: 'Year', value: '2000' }]`(子空间为 Year = 2000) | +| dimensions | `string[]` | 该洞察数据主体的维度, 并且作为下一轮子空间划分的分组维度。 | `[fieldName: 'country']` | +| measures | `Measure[]` | 该洞察数据主体的计算指标。 | `[{ field: 'life_expect', method: 'MEAN' }]` | +| data | `Datum[]` | 该洞察数据主体的相关数据。 | `[{ country: 'China', life_expect: 61 }]` | +| patterns | `PatternInfo[]` | 该洞察数据主体上的模式集合 | `[{ type: 'outlier', significance: 0.98, dimension: 'country', measure: 'life_expect', index: 5, x: 'china', y: '43' }, ...]` | +| visualizationSpecs | `visualizationSpec[]` | 该洞察的可视化方案，包含图表类型、标题、洞察描述以及图表配置（基于G2Plot） | `[{ type: 'column_chart', caption: string, narrativeSpec: string[] \| IPhrase[][], chartSpec: G2PlotConfig }]` | + +### 用例 + +* 指定从数据中提取时序异常类型的洞察结果。 + +```ts +import { getSpecificInsight } from '@antv/ava'; + +getSpecificInsight({ + data, + measures: [{ fieldName: 'life_expect', method: 'MEAN' }], + dimensions: [{ fieldName: 'date' }], + insightType: 'time_series_outlier', +}); +``` + +* 自定义算法参数 + +```ts +import { getSpecificInsight } from '@antv/ava'; + +const insightResult = getSpecificInsight({ + data, + measures: [{ fieldName: 'life_expect', method: 'MEAN' }], + dimensions: [{ fieldName: 'date' }], + insightType: 'time_series_outlier', + options: { + // 筛选显著的洞察结果 + filterInsight: true, + // 进行数据校验 + dataValidation: true, + // 调整显著性检验的相关参数 + algorithmParameter: { + outlier: { + method: 'IQR', + iqrK: 1.5, + }, + }, + } +}); +``` diff --git a/site/docs/api/insight/insight-patterns-extractor.en.md b/site/docs/api/insight/insight-patterns-extractor.en.md index 716432c8..59413901 100644 --- a/site/docs/api/insight/insight-patterns-extractor.en.md +++ b/site/docs/api/insight/insight-patterns-extractor.en.md @@ -6,7 +6,7 @@ order: 2 -Extract specified types of insights from the data. +Extract insight of a specified type from the data. ## **insightPatternsExtractor** @@ -15,29 +15,31 @@ Extract specified types of insights from the data. * ***InsightExtractorProps*** configuration of insightPatternsExtractor -| Properties | Type | Description | Default| +| Properties | Type | Description | Example | | ----| ---- | ---- | -----| | 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 | | +| options | `InsightExtractorOptions` | optional configuration | none | * ***InsightExtractorOptions*** optional configuration +The contents of `dataProcessInfo`, `algorithmParameter` and `visualizationOptions` can be seen in [InsightOptions API](./auto-insights.en.md). No further details will be given here. + | Properties | Type | Description | Default| | ----| ---- | ---- | -----| -| algorithmParameter | `AlgorithmParameter` | Adjustable algorithm parameters | `{}` | +| algorithmParameter | `AlgorithmParameter` | Adjustable algorithm parameters | none | | 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 | `{}` | +| dataProcessInfo | `Extra` | Configuration of data processing during data verification | none | | 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: {} }`| +| TrendInfo | trend | `{ type: 'trend', significance: 0.99, trend: 'decreasing', regression: { r2: 0.5, points: [], equation: [] } }`| | 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 }` | @@ -45,7 +47,7 @@ Extract specified types of insights from the data. | 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 }` | -### 用例 +### Usage * Extract trend insights from the data. @@ -59,3 +61,28 @@ insightPatternsExtractor({ insightType: 'trend', }); ``` + +* Custom algorithm parameters + +```ts +import { getSpecificInsight } from '@antv/ava'; + +const insightResult = getSpecificInsight({ + data, + measures: [{ fieldName: 'life_expect', method: 'MEAN' }], + dimensions: [{ fieldName: 'date' }], + insightType: 'trend', + options: { + // Keep insignificant insights + filterInsight: false, + // Verify whether the input meets the algorithm requirements + dataValidation: true, + // Adjust the significance test threshold + algorithmParameter: { + trend: { + threshold: 0.05, + }, + }, + } +}); +``` diff --git a/site/docs/api/insight/insight-patterns-extractor.zh.md b/site/docs/api/insight/insight-patterns-extractor.zh.md index 19f19039..2ac33772 100644 --- a/site/docs/api/insight/insight-patterns-extractor.zh.md +++ b/site/docs/api/insight/insight-patterns-extractor.zh.md @@ -21,23 +21,25 @@ order: 2 | 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` | 可选配置项 | | +| options | `InsightExtractorOptions` | 可选配置项 | 见下方`InsightExtractorOptions`的详细介绍 | * ***InsightExtractorOptions*** 可选配置项 +其中`dataProcessInfo`，`algorithmParameter`和`visualizationOptions`的内容可见 [InsightOptions API](./auto-insights.zh.md)。此处不再赘述。 + | 属性 | 类型 | 描述 | 默认值 | | ----| ---- | ---- | -----| -| algorithmParameter | `AlgorithmParameter` | 可调的算法参数 | `{}` | +| algorithmParameter | `AlgorithmParameter` | 可调的算法参数 | 无 | | filterInsight | `boolean` | 是否过滤有效洞察 | `false` | | dataValidation | `boolean` | 是否校验数据是否符合要求 | `false` | -| dataProcessInfo | `Extra` | 数据校验时数据处理的配置 | `{}` | +| dataProcessInfo | `Extra` | 数据校验时数据处理的配置 | 无 | | visualizationOptions | `InsightVisualizationOptions` | 可视化spec配置 | `{ lang: 'zh-CN' }` | * ***PatternInfo*** 包含以下几种洞察类型 | 类型 | 描述 | 示例 | | ----| ---- | ---- | -| TrendInfo | 趋势 | `{ type: 'trend', significance: 0.99, trend: 'decreasing', regression: {} }`| +| TrendInfo | 趋势 | `{ type: 'trend', significance: 0.99, trend: 'decreasing', regression: { r2: 0.5, points: [], equation: [] } }`| | 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 }` | @@ -59,3 +61,28 @@ insightPatternsExtractor({ insightType: 'trend', }); ``` + +* 自定义算法参数 + +```ts +import { getSpecificInsight } from '@antv/ava'; + +const insightResult = getSpecificInsight({ + data, + measures: [{ fieldName: 'life_expect', method: 'MEAN' }], + dimensions: [{ fieldName: 'date' }], + insightType: 'trend', + options: { + // 保留不显著的洞察结果 + filterInsight: false, + // 进行数据校验 + dataValidation: true, + // 调整显著性检验的相关参数 + algorithmParameter: { + trend: { + threshold: 0.05, + }, + }, + } +}); +``` diff --git a/site/docs/guide/insight/intro.en.md b/site/docs/guide/insight/intro.en.md index e9a5a0f0..c1e61a19 100644 --- a/site/docs/guide/insight/intro.en.md +++ b/site/docs/guide/insight/intro.en.md @@ -56,6 +56,24 @@ insightPatternsExtractor({ }); ``` +### getSpecificInsight 使用 + +The `getSpecificInsight` method can not only obtain the specified type of insight, but also output a visual spec. Combined with the `InsightCard` component, the insight results can be presented in a visual way. Input parameters are the same as the `insightPatternsExtractor` method. Detailed output parameters are described in the [InsightInfo API](../../api/insight/auto-insight.zh.md)。 + + +```ts +import { getSpecificInsight } from '@antv/ava'; + +const insightResult = getSpecificInsight({ + 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 7774ef56..6878cfc8 100644 --- a/site/docs/guide/insight/intro.zh.md +++ b/site/docs/guide/insight/intro.zh.md @@ -57,6 +57,24 @@ insightPatternsExtractor({ }); ``` +### getSpecificInsight 使用 + +`getSpecificInsight`方法不仅能获取指定类型的洞察结果，还能输出可视化spec，结合`InsightCard`组件就能通过可视化的方式呈现指定类型的洞察结果。输入输出参数详见 [getSpecificInsight API](../../api/insight/get-specific-insight.zh.md)。 + + +```ts +import { getSpecificInsight } from '@antv/ava'; + +const insightResult = getSpecificInsight({ + data, + measures: [{ fieldName: 'life_expect', method: 'MEAN' }], + dimensions: [{ fieldName: 'date' }], + insightType: 'trend', +}); + + +``` + ## 📖 文档 更多用法请移步至 [API](../../api/insight/auto-insights)。 diff --git a/site/examples/insight/basic/demo/meta.json b/site/examples/insight/basic/demo/meta.json index 6d0628a5..ae5a9040 100644 --- a/site/examples/insight/basic/demo/meta.json +++ b/site/examples/insight/basic/demo/meta.json @@ -24,7 +24,7 @@ "filename": "specify-type.jsx", "title": { "zh": "指定洞察类型", - "en": "Extract specified types of insights" + "en": "Extract insight of a specified type" }, "screenshot": "https://gw.alipayobjects.com/zos/antfincdn/zt2jXO97%262/li-basic.gif" }