diff --git a/docs/assets/api/en/getInsights.md b/docs/assets/api/en/getInsights.md new file mode 100644 index 00000000..a45163ff --- /dev/null +++ b/docs/assets/api/en/getInsights.md @@ -0,0 +1,153 @@ +# getInsights + +## Interface Description + +The getInsights interface generates insights for the current chart based on the VChart Spec configuration and insight options. The final insights are sorted in descending order of confidence scores. + +## Interface Parameters + +```typescript +getInsights(spec: any, options?: DataInsightOptions): { insights: Insights[], usage: Usage }; + +export interface DataInsightOptions { + /** Maximum number of insights to generate */ + maxNum?: number; + /** Maximum number of insights for each specific insight type, which takes precedence over maxNum */ + detailMaxNum?: { + types: InsightType[]; + maxNum: number; + }[]; + /** Algorithms to use */ + algorithms?: AlgorithmType[]; + /** Hyperparameter settings for each algorithm */ + algorithmOptions?: AlgorithmOptions; + /** Whether to consider chart type for insight results, e.g., clustering algorithms are only used in scatter plots */ + isLimitedbyChartType?: boolean; + /** Whether to use a large model for text polishing */ + usePolish?: boolean; + /** answer language */ + language?: 'chinese' | 'english'; +} +``` + +### Insight Types +The specific insight types are as follows, comprising 12 types in total. +```ts +export enum InsightType { + /** Minimum value */ + Min = 'min', + /** Maximum value */ + Max = 'max', + /** Average value */ + Avg = 'avg', + /** Outlier */ + Outlier = 'outlier', + /** Extreme value */ + ExtremeValue = 'extreme_value', + /** Majority value with significant contribution */ + MajorityValue = 'majority_value', + /** Turning point */ + TurningPoint = 'turning_point', + /** Overall trend */ + OverallTrend = 'overall_trend', + /** Abnormal trend */ + AbnormalTrend = 'abnormal_trend', + /** Abnormal band */ + AbnormalBand = 'abnormal_band', + /** Correlation */ + Correlation = 'correlation', + /** Volatility */ + Volatility = 'volatility' +} +``` + +### Built-in Algorithms +All built-in algorithms in VMind are as follows: +```ts +export enum AlgorithmType { + /** Overall/abnormal trend, using Mann-Kendall Test for trend detection */ + OverallTrending = 'overallTrend', + AbnormalTrend = 'abnormalTrend', + /** Pearson Correlation Coefficient / Spearman Correlation for correlation detection */ + PearsonCorrelation = 'pearsonCorrelation', + SpearmanCorrelation = 'spearmanCorrelation', + /** Statistical extreme values and majority values */ + ExtremeValue = 'extremeValue', + MajorityValue = 'majorityValue', + /** zScore global outlier detection and IQR (Interquartile Range) global outlier detection algorithms as the main statistical methods */ + StatisticsAbnormal = 'statisticsAbnormal', + /** Basic indicators, including maximum, minimum, average values */ + StatisticsBase = 'statisticsBase', + /** DBSCAN-based outlier detection algorithm */ + DbscanOutlier = 'dbscanOutlier', + /** LOF (Local Outlier Factor) local outlier factor detection algorithm */ + LOFOutlier = 'lofOutlier', + /** Bayesian Inference turning point detection algorithm */ + TurningPoint = 'turningPoint', + /** Page-Hinkley Test for time series anomaly detection */ + PageHinkley = 'pageHinkley', + /** Coefficient of Variation for periodicity detection based on the coefficient of variation */ + Volatility = 'volatility' +} +``` + +### Default Values +By default, VMind enables `isLimitedbyChartType` and `usePolish`, and all algorithms are enabled by default. + +## Return Value Type +The return value `insight` is an array of insights, with a single insight type as follows: +```ts +export interface Insight { + /** Insight name */ + name: string; + /** Insight type */ + type: InsightType; + /** Specific data corresponding to the insight */ + data: { + /** Index number */ + index: number; + /** Specific data item */ + dataItem: DataItem; + }[]; + /** Data field ID corresponding to the outlier, e.g., sales, growth rate, etc. */ + fieldId?: string; + /** Specific series name, e.g., "Northeast" | "Apple" or other specific category data names */ + seriesName?: DataCell | DataCell[]; + /** Semantic data expression, including placeholders */ + textContent?: { + // Original text content + content: string; + // Plain text after parsing variable placeholders + plainText: string; + // Mapping of variables + variables?: Record; + }; + // Specific value of the insight + value?: number | string; + /** Confidence score of the insight, used for insight sorting, the higher the score, the more important the insight */ + significant: number; + info?: { [key: string]: any }; // Additional information about this insight +} + +export interface InsightTextContent { + /** Parsed value */ + value: DataCell; + /** Formatted value */ + formatValue?: string; // Formatted value + /** Field name */ + fieldName: string; + /** Current color */ + color?: string; + /** Type of value, e.g., ascending trend or descending trend */ + valueType?: 'ascendTrend' | 'descendTrend' | string; + /** Icon type, e.g., ratio, ascending trend, or descending trend */ + icon?: 'ratio' | 'ascendTrend' | 'descendTrend' | string; + /** Whether it is a measure value */ + isMeasure?: boolean; + /** Whether it is a dimension value */ + isDimValue?: boolean; +} +``` + +### Specific Examples and Related Tutorials +[Intelligent Insights](../guide/Basic_Tutorial/Chart_Insight) diff --git a/docs/assets/api/menu.json b/docs/assets/api/menu.json index 78c47981..2c3905d9 100644 --- a/docs/assets/api/menu.json +++ b/docs/assets/api/menu.json @@ -42,6 +42,13 @@ "zh": "generateChart", "en": "generateChart" } + }, + { + "path": "getInsights", + "title": { + "zh": "getInsights", + "en": "getInsights" + } } ] -} +} \ No newline at end of file diff --git a/docs/assets/api/zh/getInsights.md b/docs/assets/api/zh/getInsights.md new file mode 100644 index 00000000..1790fead --- /dev/null +++ b/docs/assets/api/zh/getInsights.md @@ -0,0 +1,153 @@ +# getInsights + +## 接口描述 + +getInsights接口会根据VChart Spec配置和洞察配置，产生当前图表的洞察结果，最终洞察结果会按照洞察置信度得分从高到低排序。 + +## 接口参数 + +```typescript +getInsights(spec: any, options?: DataInsightOptions): { insights: Insights[], usage: Usage}; + +export interface DataInsightOptions { + /** 最多产生的洞察数量 */ + maxNum?: number; + /** 具体每个洞察类型最多产生的洞察数量，优先级高于maxNum */ + detailMaxNum?: { + types: InsightType[]; + maxNum: number; + }[]; + /** 使用哪些算法 */ + algorithms?: AlgorithmType[]; + /** 每个算法的超参数设定 */ + algorithmOptions?: AlgorithmOptions; + /** 洞察结果是否考虑图表类型，例如聚类算法只在散点图中使用 */ + isLimitedbyChartType?: boolean; + /** 是否用大模型进行文本润色 */ + usePolish?: boolean; + /** 生成文本的语言 */ + language?: 'chinese' | 'english'; +} +``` + +### 洞察类型 +具体的洞察类型如下所示，共包含12种洞察类型。 +```ts +export enum InsightType { + /** 最小值 */ + Min = 'min', + /** 最大值 */ + Max = 'max', + /** 平均值 */ + Avg = 'avg', + /** 异常点 */ + Outlier = 'outlier', + /** 极值 */ + ExtremeValue = 'extreme_value', + /** 贡献占比巨大值 */ + MajorityValue = 'majority_value', + /** 转折点 */ + TurningPoint = 'turning_point', + /** 整体趋势 */ + OverallTrend = 'overall_trend', + /** 异常趋势 */ + AbnormalTrend = 'abnormal_trend', + /** 异常区间 */ + AbnormalBand = 'abnormal_band', + /** 相关性 */ + Correlation = 'correlation', + /** 周期性 */ + Volatility = 'volatility' +} +``` + +### 内置算法 +VMind所有内置算法如下： +```ts +export enum AlgorithmType { + /** 整体/异常趋势，使用Mann-Kendall Test 趋势检测算法 */ + OverallTrending = 'overallTrend', + AbnormalTrend = 'abnormalTrend', + /** Pearson Correlation Coefficient / SpearmanCorrelation 相关性检测 */ + PearsonCorrelation = 'pearsonCorrelation', + SpearmanCorrelation = 'spearmanCorrelation', + /** 统计极值和占比贡献巨大值 */ + ExtremeValue = 'extremeValue', + MajorityValue = 'majorityValue', + /** zScore 全局异常点检测和IQR (Interquartile Range) 四分位全局异常检测算法 为主的统计学方法 */ + StatisticsAbnormal = 'statisticsAbnormal', + /** 基础指标，包括最大，最小，平均值 */ + StatisticsBase = 'statisticsBase', + /** 以DBSCAN为主的离群点检测算法 */ + DbscanOutlier = 'dbscanOutlier', + /** LOF(Local Outlier Factor) 局部异常因子检测算法 */ + LOFOutlier = 'lofOutlier', + /** Bayesian Inference 转折点检测算法 */ + TurningPoint = 'turningPoint', + /** Page-Hinkley Test 时序数据异常检测算法 */ + PageHinkley = 'pageHinkley', + /** Coefficient of Variation 基于变异系数的周期性检测 */ + Volatility = 'volatility' +} +``` + +### 默认值 +默认VMind会开启`isLimitedbyChartType`以及`usePolish`，同时默认开启所有算法 + +## 返回值类型 +返回值`insight`为洞察数组，单个洞察类型如下所示： +```ts +export interface Insight { + /** 洞察名称 */ + name: string; + /** 洞察类型 */ + type: InsightType; + /** 洞察对应的具体数据 */ + data: { + /** index编号 */ + index: number; + /** 具体数据项 */ + dataItem: DataItem; + }[]; + /** 异常点对应的数据字段id，例如为销售额。增长率等 */ + fieldId?: string; + /** 具体的图元系列名称，例如可能是"东北" ｜ "苹果"等具体的分类数据名称 */ + seriesName?: DataCell | DataCell[]; + /** 语义化数据表达，包含占位符 */ + textContent?: { + // 原始文本内容 + content: string; + // 将变量占位符解析为文本后的纯文本 + plainText: string; + // 变量的映射 + variables?: Record; + }; + // 洞察的具体值 + value?: number | string; + /** 洞察的置信度的粉，用于洞察排序，分数越高代表洞察越重要 */ + significant: number; + info?: { [key: string]: any }; // 关于此洞察的附加信息 +} + +export interface InsightTextContent { + /** 解析值 */ + value: DataCell; + /** 格式化后的值 */ + formatValue?: string; // 格式化后的值 + /** 字段名称 */ + fieldName: string; + /** 当前颜色 */ + color?: string; + /** 值的类型，例如上升趋势或下降趋势 */ + valueType?: 'ascendTrend' | 'descendTrend' | string; + /** 图标类型，例如比率、上升趋势或下降趋势 */ + icon?: 'ratio' | 'ascendTrend' | 'descendTrend' | string; + /** 是否为度量值 */ + isMeasure?: boolean; + /** 是否为维度值 */ + isDimValue?: boolean; +} +``` + +### 具体案例和相关教程 +[智能洞察](../guide/Basic_Tutorial/Chart_Insight) diff --git a/docs/assets/guide/en/Basic_Tutorial/Chart_Insight.md b/docs/assets/guide/en/Basic_Tutorial/Chart_Insight.md new file mode 100644 index 00000000..368db1e6 --- /dev/null +++ b/docs/assets/guide/en/Basic_Tutorial/Chart_Insight.md @@ -0,0 +1,183 @@ +# Intelligent Insights + +In the era of data-driven decision-making, charts serve as a core tool for data visualization, providing an intuitive way to present complex data relationships. However, relying solely on human observation and analysis of charts often makes it difficult to quickly and comprehensively uncover the hidden insights behind the data. + +This tutorial will introduce you to the intelligent insights feature in VMind, demonstrating how to quickly obtain various types of insights from charts using the `getInsights` function, along with some examples. + +## getInsights + +The `getInsights` function in VMind is a powerful tool that helps you extract chart insights and generate semantic explanations. This function requires the following two parameters: +- spec: The specific spec configuration of the current VChart chart +- options (DataInsightOptions): Insight-related configurations that control the number of specific insights, the algorithms used, and the specific configurations of the corresponding algorithms + +During the process of generating intelligent insights, VMind primarily performs two tasks: +- First, it uses built-in statistical algorithms to extract data insights contained in the current chart; +- Then, these identified insights are passed to a large model, which polishes and semantically explains these insights. During the polishing process, VMind passes field information and insight types to the large model but **does not pass any data details to the large model**. + +The second step of polishing by the large model is not mandatory and can be disabled through `options.usePolish`, in which case you will receive data insights and templated semantic content. + +### Built-in Algorithms + +Currently, VMind's built-in algorithms are primarily related to statistics, as listed below: +- LOF (Local Outlier Factor) for local outlier detection +- zScore for global outlier detection +- IQR (Interquartile Range) for global outlier detection +- Page-Hinkley Test for time series anomaly detection +- Bayesian Inference for change point detection +- Mann-Kendall Test for trend detection +- Pearson Correlation Coefficient / Spearman Correlation for correlation detection +- DBSCAN (Density-Based Spatial Clustering of Applications with Noise) algorithm +- Coefficient of Variation for periodicity detection based on the coefficient of variation +- Basic statistical indicators, such as maximum/minimum/average value/proportion anomalies, etc. + +### Large Model Polishing + +In intelligent insights, the large model serves only as a text polishing function, enhancing the readability of the final results, and is an optional configuration. + +## Insight Types + +Based on the existing built-in algorithms, VMind can identify the following 9 types of insights: +- Outliers +- Time series outliers +- Change points +- Points with significant contribution to proportion +- Anomalous intervals +- Overall trends +- Anomalous trends +- Correlations +- Basic statistical indicators + +Depending on different insight results, users can choose different annotation/highlighting methods to present them in charts. + +## Usage Example + +Below is an example of using `getInsights`: +```ts +import VMind from '@visactor/vmind'; + +const specJson = { + type: 'line', + xField: ['Year'], + yField: ['College Admission Rate'], + data: [ + { + id: 'data', + values: [ + {"Year": 1977, "College Admission Rate": 0.05}, + {"Year": 1978, "College Admission Rate": 0.07}, + {"Year": 1979, "College Admission Rate": 0.06}, + {"Year": 1980, "College Admission Rate": 0.08}, + {"Year": 1981, "College Admission Rate": 0.11}, + {"Year": 1982, "College Admission Rate": 0.17}, + {"Year": 1983, "College Admission Rate": 0.23}, + {"Year": 1984, "College Admission Rate": 0.29}, + {"Year": 1985, "College Admission Rate": 0.96}, + {"Year": 1986, "College Admission Rate": 0.3}, + {"Year": 1987, "College Admission Rate": 0.27}, + {"Year": 1988, "College Admission Rate": 0.25}, + {"Year": 1989, "College Admission Rate": 0.23}, + {"Year": 1990, "College Admission Rate": 0.22}, + {"Year": 1991, "College Admission Rate": 0.21}, + {"Year": 1992, "College Admission Rate": 0.25}, + {"Year": 1993, "College Admission Rate": 0.34}, + {"Year": 1994, "College Admission Rate": 0.36}, + {"Year": 1995, "College Admission Rate": 0.37}, + {"Year": 1996, "College Admission Rate": 0.4}, + {"Year": 1997, "College Admission Rate": 0.36}, + {"Year": 1998, "College Admission Rate": 0.34}, + {"Year": 1999, "College Admission Rate": 0.56}, + {"Year": 2000, "College Admission Rate": 0.59}, + {"Year": 2001, "College Admission Rate": 0.59}, + {"Year": 2002, "College Admission Rate": 0.63}, + {"Year": 2003, "College Admission Rate": 0.62}, + {"Year": 2004, "College Admission Rate": 0.61}, + {"Year": 2005, "College Admission Rate": 0.57}, + {"Year": 2006, "College Admission Rate": 0.57}, + {"Year": 2007, "College Admission Rate": 0.56}, + {"Year": 2008, "College Admission Rate": 0.57}, + {"Year": 2009, "College Admission Rate": 0.62}, + {"Year": 2010, "College Admission Rate": 0.69}, + {"Year": 2011, "College Admission Rate": 0.72}, + {"Year": 2012, "College Admission Rate": 0.75}, + {"Year": 2013, "College Admission Rate": 0.75}, + {"Year": 2014, "College Admission Rate": 0.74}, + {"Year": 2015, "College Admission Rate": 0.74}, + {"Year": 2016, "College Admission Rate": 0.75}, + {"Year": 2017, "College Admission Rate": 0.74}, + {"Year": 2018, "College Admission Rate": 0.81}, + {"Year": 2019, "College Admission Rate": 0.8}, + {"Year": 2020, "College Admission Rate": 0.8}, + {"Year": 2021, "College Admission Rate": 0.93}, + {"Year": 2022, "College Admission Rate": 0.96} + ] + } + ] + }; +const vmind = new VMind(options) +const { insights } = await vmind.getInsights(specJson, { + /** Generate up to maxNum insights */ + maxNum: numLimits, +}); +``` + +The final result accurately identifies the overall trend and the significantly anomalous college admission rate in 1985. + +![](https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vmind_insight_en_1.jpeg) +### Return Structure + +Taking the overall trend as an example, the structured content returned is as follows: +```ts +const outlierInsight = { + /** Type is outlier Insight */ + type: 'outlier', + /** Specific outlier data */ + data: [ + { + index: 8, + dataItem: { + Year: 1985, + College Admission Rate: 0.96, + } + } + ], + /** Numerical field */ + fieldId: 'College Admission Rate', + /** Current outlier value */ + value: 0.96, + /** Insight confidence score */ + significant: 1, + /** Current series name, since the current chart does not have a seriesField configuration, it only contains one series, so it is the default value of vmind */ + seriesName: 'vmind_default_series', + /** Detected by the pageHinkley algorithm */ + name: 'pageHinkley', + /** Specific textual meaning */ + textContent: { + /** Specific text template */ + content: '${b} period shows a significant anomaly, with a value of ${c}.', + /** Variable parsing in the template */ + variables: { + b: { + isDimValue: true, + value: 1985, + fieldName: 'Year' + }, + c: { + value: 0.96, + isMeasure: true, + fieldName: 'College Admission Rate' + } + }, + /** Result of directly replacing template variables with values */ + plainText: '1985 period shows a significant anomaly, with a value of 0.96.' + } +} +``` + +### Adding Insights + +After identifying chart insights, we can use VChart's powerful annotation capabilities to add these contents to the chart, as shown in the final effect below: +![](https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vmind_insight_en_2.jpeg) + +## Parameter Details + +For detailed parameter explanations, see: [getInsights](../../api/getInsights) \ No newline at end of file diff --git a/docs/assets/guide/menu.json b/docs/assets/guide/menu.json index c7bbf002..09b9d03a 100644 --- a/docs/assets/guide/menu.json +++ b/docs/assets/guide/menu.json @@ -84,6 +84,13 @@ "zh": "基于规则的图表生成", "en": "Rule-based Chart Generation" } + }, + { + "path": "Chart_Insight", + "title": { + "zh": "智能洞察", + "en": "Auto Insight" + } } ] } diff --git a/docs/assets/guide/zh/Basic_Tutorial/Chart_Insight.md b/docs/assets/guide/zh/Basic_Tutorial/Chart_Insight.md new file mode 100644 index 00000000..06243243 --- /dev/null +++ b/docs/assets/guide/zh/Basic_Tutorial/Chart_Insight.md @@ -0,0 +1,179 @@ +# 智能洞察 + +在数据驱动决策的时代，图表作为数据可视化的核心工具，能够直观地呈现复杂的数据关系。然而，单纯依赖人眼观察和分析图表，往往难以快速、全面地挖掘出数据背后隐藏的洞察。 + +本教程将向你介绍VMind中智能洞察功能，如何通过`getInsights`快速从图表中获取各种类型的洞察，并提供一些示例。 + +## getInsights +VMind的`getInsights`函数是一个强大的工具，它可以帮你从图表中获取图表洞察，并产生语义化的解释。这个函数只需要如下两个参数： +- spec: 当前VChart图表的具体spec配置 +- options (DataInsightOptions): 洞察相关配置，控制了具体洞察的数量，使用的算法和对应算法的具体配置 + +在产生智能洞察的过程中，VMind主要做了两件事情， +- 先通过内置的统计学算法，获取当前图表中蕴含的数据洞察； +- 再这些识别出来的洞察传递给大模型；让大模型对这些洞察进行润色和语义化解释，在润色过程中，VMind会将字段信息和洞察类型传递给大模型，**并不会把任何数据细节传递给大模型**； + +其中第二部大模型润色并不是必须的，可以通过`options.usePolish`对其进行关闭，此时会得到数据洞察和模版化的语义内容。 + +### 内置算法 +目前VMind内置的算法主要为统计学相关算法，具体如下所示： +- LOF(Local Outlier Factor) 局部异常因子检测算法 +- zScore 全局异常点检测 +- IQR (Interquartile Range) 四分位全局异常检测算法 +- Page-Hinkley Test 时序数据异常检测算法 +- Bayesian Inference 转折点检测算法 +- Mann-Kendall Test 趋势检测算法 +- Pearson Correlation Coefficient / SpearmanCorrelation 相关性检测 +- DBSCAN (Density-Based Spatial Clustering of Applications with Noise) 算法 +- Coefficient of Variation 基于变异系数的周期性检测 +- 基础的统计指标，例如最大/最小/平均值/占比异常等等 + +### 大模型润色 +大模型在智能洞察中，只是起到了一个文本润色功能，使得最终的结果有着较强的可读性，是个可选配置。 + +## 洞察类型 +目前根据已有的内置算法，VMind可以识别出以下9类不同的洞察类型： + - 异常点 + - 时序异常点 + - 转折点 + - 占比贡献巨大点 + - 异常区间 + - 整体趋势 + - 异常趋势 + - 相关性 + - 基础统计指标 + +根据不同的洞察结果，用户可以选取不同的标注/高亮方式在图表中进行呈现。 + +## 使用案例 +下面是一个使用`getInsights`的例子: +```ts +import VMind from '@visactor/vmind'; + +const specJson = { + type: 'line', + xField: ['年份'], + yField: ['高考录取率'], + data: [ + { + id: 'data', + values: [ + {"年份": 1977, "高考录取率": 0.05}, + {"年份": 1978, "高考录取率": 0.07}, + {"年份": 1979, "高考录取率": 0.06}, + {"年份": 1980, "高考录取率": 0.08}, + {"年份": 1981, "高考录取率": 0.11}, + {"年份": 1982, "高考录取率": 0.17}, + {"年份": 1983, "高考录取率": 0.23}, + {"年份": 1984, "高考录取率": 0.29}, + {"年份": 1985, "高考录取率": 0.96}, + {"年份": 1986, "高考录取率": 0.3}, + {"年份": 1987, "高考录取率": 0.27}, + {"年份": 1988, "高考录取率": 0.25}, + {"年份": 1989, "高考录取率": 0.23}, + {"年份": 1990, "高考录取率": 0.22}, + {"年份": 1991, "高考录取率": 0.21}, + {"年份": 1992, "高考录取率": 0.25}, + {"年份": 1993, "高考录取率": 0.34}, + {"年份": 1994, "高考录取率": 0.36}, + {"年份": 1995, "高考录取率": 0.37}, + {"年份": 1996, "高考录取率": 0.4}, + {"年份": 1997, "高考录取率": 0.36}, + {"年份": 1998, "高考录取率": 0.34}, + {"年份": 1999, "高考录取率": 0.56}, + {"年份": 2000, "高考录取率": 0.59}, + {"年份": 2001, "高考录取率": 0.59}, + {"年份": 2002, "高考录取率": 0.63}, + {"年份": 2003, "高考录取率": 0.62}, + {"年份": 2004, "高考录取率": 0.61}, + {"年份": 2005, "高考录取率": 0.57}, + {"年份": 2006, "高考录取率": 0.57}, + {"年份": 2007, "高考录取率": 0.56}, + {"年份": 2008, "高考录取率": 0.57}, + {"年份": 2009, "高考录取率": 0.62}, + {"年份": 2010, "高考录取率": 0.69}, + {"年份": 2011, "高考录取率": 0.72}, + {"年份": 2012, "高考录取率": 0.75}, + {"年份": 2013, "高考录取率": 0.75}, + {"年份": 2014, "高考录取率": 0.74}, + {"年份": 2015, "高考录取率": 0.74}, + {"年份": 2016, "高考录取率": 0.75}, + {"年份": 2017, "高考录取率": 0.74}, + {"年份": 2018, "高考录取率": 0.81}, + {"年份": 2019, "高考录取率": 0.8}, + {"年份": 2020, "高考录取率": 0.8}, + {"年份": 2021, "高考录取率": 0.93}, + {"年份": 2022, "高考录取率": 0.96} + ] + } + ] + }; +const vmind = new VMind(options) +const { insights } = await vmind.getInsights(specJson, { + /** 最多产生 maxNum个洞察内容 */ + maxNum: numLimits, +}); +``` + +最终产生的结果如下： + +![](https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vmind_insight_1.jpeg) + +可以准确识别出整体的趋势以及1985年明显异常的高考录取率 + +### 返回结构 +以整体趋势为例，返回的结构化内容如下： +```ts +const outlierInsight = { + /** 类型为异常点Insight */ + type: 'outlier', + /** 具体的异常点数据 */ + data: [ + { + index: 8, + dataItem: { + 年份: 1985, + 高考录取率: 0.96, + } + } + ], + /** 数值字段 */ + fieldId: '高考录取率', + /** 当前异常点数值 */ + value: 0.96, + /** 洞察置信度得分 */ + significant: 1, + /** 当前系列名称，因为当前图表没有进行seriesField配置，只包含一个系列，因此为vmind的默认值 */ + seriesName: 'vmind_default_series', + /** 通过pageHinkley算法检测得到 */ + name: 'pageHinkley', + /** 具体的文本话含义 */ + textContent: { + /** 具体的文本模版 */ + content: '${b}期间出现显著异常，值为${c}。', + /** 模版中的变量解析 */ + variables: { + b: { + isDimValue: true, + value: 1985, + fieldName: '年份' + }, + c: { + value: 0.96, + isMeasure: true, + fieldName: '高考录取率' + } + }, + /** 直接将模版变量进行数值替换的结果 */ + plainText: '1985期间出现显著异常，值为0.96。' + } +} +``` + +### 洞察添加 + +识别出图表洞察后，我们可以借助VChart强大的标注能力，将这些内容添加到图表中，最终效果可以如下图所示： +![](https://lf9-dp-fe-cms-tos.byteorg.com/obj/bit-cloud/vmind_insight_2.jpeg) + +## 参数详解 +具体参数详解可见：[getInsights](../../api/getInsights) \ No newline at end of file diff --git a/packages/vmind/__tests__/browser/src/pages/NewChartGeneration/DataInput.tsx b/packages/vmind/__tests__/browser/src/pages/NewChartGeneration/DataInput.tsx index 5b6a2584..80eadff1 100644 --- a/packages/vmind/__tests__/browser/src/pages/NewChartGeneration/DataInput.tsx +++ b/packages/vmind/__tests__/browser/src/pages/NewChartGeneration/DataInput.tsx @@ -5,9 +5,7 @@ import { Avatar, Input, Divider, Button, Message, Select, Radio, Modal } from '@ import { chartGenerationMockData } from '../../constants/chartGeneratorData'; import type { DataTable, FieldInfo } from '../../../../../src/index'; import VMind from '../../../../../src/index'; -import { Model, AtomName, Schedule, LLMManage } from '../../../../../src/index'; -import type { SimpleFieldInfo } from '../../../../../src/common/typings'; -import { DataType } from '../../../../../src/common/typings'; +import { Model, AtomName, Schedule, LLMManage, DataType } from '../../../../../src/index'; const TextArea = Input.TextArea; const Option = Select.Option; @@ -42,7 +40,7 @@ function dataTypeTransfer(dataType: string): DataType { } } -function transferFieldInfoInSimpleFieldInfo(fieldInfo: FieldInfo[]): SimpleFieldInfo[] { +function transferFieldInfoInSimpleFieldInfo(fieldInfo: FieldInfo[]): FieldInfo[] { return fieldInfo.map(item => ({ fieldName: item.fieldName, description: item.description, diff --git a/packages/vmind/__tests__/experiment/src/pages/DataExtraction/verify.tsx b/packages/vmind/__tests__/experiment/src/pages/DataExtraction/verify.tsx index 78682d64..ed322f33 100644 --- a/packages/vmind/__tests__/experiment/src/pages/DataExtraction/verify.tsx +++ b/packages/vmind/__tests__/experiment/src/pages/DataExtraction/verify.tsx @@ -1,10 +1,9 @@ /* eslint-disable @typescript-eslint/no-explicit-any */ /* eslint-disable no-console */ import { stringSimilarity } from 'string-similarity-js'; -import { DataType } from '../../../../../src'; +import { DataType, ROLE } from '../../../../../src'; import type { DataCell, DataExtractionCtx, FieldInfo, DataTable } from '../../../../../src'; import { getRoleByFieldType } from '../../../../../src/utils/field'; -import { ROLE } from '../../../../../src/common/typings'; import type { DataExtractionCase, DataExtractionResult, ScoreDetail } from './type'; import { isNumber } from '@visactor/vutils'; diff --git a/packages/vmind/src/applications/types.ts b/packages/vmind/src/applications/types.ts deleted file mode 100644 index 1c3dae12..00000000 --- a/packages/vmind/src/applications/types.ts +++ /dev/null @@ -1,87 +0,0 @@ -import type { - BasemapOption, - ChartType, - ILLMOptions, - SimpleFieldInfo, - VMindDataset, - ChartTheme -} from '../common/typings'; -import type { Cell } from './chartGeneration/types'; -import type { InsightAlgorithm, VMindInsight } from './IngelligentInsight/types'; -import type { CombinationBasicChartType } from '../common/typings'; - -//context of the DataExtraction Application -export type DataExtractionContext = { - llmOptions: ILLMOptions; - userInput: string; - dataText: string; - chartTypeList: ChartType[]; //supported chart list -}; - -//output of the DataExtraction Application -export type DataExtractionOutput = { - instruction: string; - dataset: VMindDataset; - fieldInfo: SimpleFieldInfo[]; -}; - -//context of the DataAggregation Application -export type DataAggregationContext = { - llmOptions: ILLMOptions; - userInput: string; - fieldInfo: SimpleFieldInfo[]; - sourceDataset: VMindDataset; //original dataset -}; - -//output of the DataAggregation Application -export type DataAggregationOutput = { - dataset: VMindDataset; //dataset after aggregation - fieldInfo: SimpleFieldInfo[]; //fieldInfo after aggregation - usage: any; //token usage of the LLM -}; - -export type ChartGenerationContext = { - llmOptions: ILLMOptions; - userInput: string; - fieldInfo: SimpleFieldInfo[]; - dataset?: VMindDataset; - chartTypeList: ChartType[]; //supported chart list - basemapOption: BasemapOption; // only use in map chart -} & { - totalTime?: number; - colors?: string[]; - chartTheme?: ChartTheme | string; -}; - -export type ChartGenerationOutput = { - chartType: ChartType; - subChartType?: CombinationBasicChartType[]; - cells?: Cell[]; - datasets?: VMindDataset[]; - spec: any; - chartSource: string; - usage: any; //token usage of the LLM - time?: { totalTime: number; frameArr: any[] }; -}; - -export enum InsightLanguage { - ZH = 'zh', - EN = 'en' -} -export type InsightContext = { - spec?: any; - chartType: ChartType; - dataset?: VMindDataset; - fieldInfo?: SimpleFieldInfo[]; - cell?: Cell; - llmOptions: ILLMOptions; - insightAlgorithms?: InsightAlgorithm[]; - insightNumberLimit?: number; - generateText?: boolean; - language?: InsightLanguage; -}; - -export type InsightOutput = { - spec: any; //spec with annotations - insights: VMindInsight[]; -}; diff --git a/packages/vmind/src/atom/dataInsight/index.ts b/packages/vmind/src/atom/dataInsight/index.ts index f47a8fb2..3aab9793 100644 --- a/packages/vmind/src/atom/dataInsight/index.ts +++ b/packages/vmind/src/atom/dataInsight/index.ts @@ -44,8 +44,8 @@ export class DataInsightAtom extends BaseAtom