docs/04_datafact_generator.md

数据洞察模块 (datafact_generator)

数据洞察模块（datafact_generator）是 ChartPipeline 框架的第二个处理环节，负责分析数据并提取关键洞察，用于增强可视化的信息价值。

功能简介

本模块通过统计分析和模式识别，从数据中提取有意义的洞察（datafacts），包括趋势、比例关系、显著差异、异常值等。这些洞察按重要性排序，可用于指导可视化设计和标注，强化数据叙事。

输入与输出

输入

模块接收包含 chart_type 字段的数据对象，主要关注：

• data.columns: 列定义
• data.data: 实际数据记录
• chart_type: 图表类型推荐结果

输出

模块向输入数据添加 datafacts 字段，结构如下：

{
  "datafacts": [
    {
      "type": "trend",
      "subtype": "increase",
      "data_points": [
        {
          "emergency_count": "1",
          "status": "active",
          "year": "1976"
        },
        {
          "emergency_count": "15",
          "status": "active",
          "year": "2022"
        }
      ],
      "score": 0.95,
      "annotation": "紧急状态宣布数量总体呈上升趋势",
      "reason": "从1976年至2022年，每十年宣布的国家紧急状态总数从1个增长到平均每十年超过15个"
    },
    {
      "type": "proportion",
      "subtype": "majority",
      "data_points": [
        {
          "emergency_count": "15",
          "status": "active",
          "year": "2019"
        },
        {
          "emergency_count": "3",
          "status": "ended",
          "year": "2019"
        }
      ],
      "score": 0.92,
      "annotation": "2010年代83%的紧急状态仍然活跃",
      "reason": "在2010-2019期间宣布的18个紧急状态中，15个仍处于活跃状态，只有3个已结束"
    },
    {
      "type": "difference",
      "subtype": "maximum",
      "data_points": [
        {
          "emergency_count": "14",
          "status": "ended",
          "year": "1999"
        },
        {
          "emergency_count": "5",
          "status": "ended",
          "year": "1989"
        }
      ],
      "score": 0.88,
      "annotation": "90年代结束的紧急状态最多",
      "reason": "1990-1999年期间有14个紧急状态被结束，比1980年代的5个增加了9个，是所有时期中最高的"
    },
    {
      "type": "trend",
      "subtype": "decrease",
      "data_points": [
        {
          "emergency_count": "3",
          "status": "ended",
          "year": "2022"
        }
      ],
      "score": 0.85,
      "annotation": "结束的紧急状态比例逐年减少",
      "reason": "从1980年代的100%结束率到2020年代仅11%的结束率，显示出明显下降趋势"
    },
    {
      "type": "value",
      "subtype": "total",
      "data_points": [
        {
          "emergency_count": "41",
          "status": "active",
          "year": "2022"
        }
      ],
      "score": 0.82,
      "annotation": "总计41个紧急状态仍然活跃",
      "reason": "所有时期加总，仍处于活跃状态的紧急状态数量为41个，远高于已结束的30个"
    }
  ]
}

每个数据洞察包含以下字段：

字段	类型	描述
type	字符串	洞察类型
subtype	字符串	洞察的具体子类型
data_points	对象数组	该洞察涉及的具体数据点，每个数据点包含多个列的值
score	浮点数	重要性评分（0-1）
annotation	字符串	简短的洞察描述，适合作为图表标注
reason	字符串	详细的解释和支持该洞察的数据依据

支持的洞察类型和子类型

模块能够识别以下类型的数据洞察及其子类型：

• trend（趋势）
  • increase: 上升趋势
  • decrease: 下降趋势
  • stable: 稳定趋势
  • increase_then_decrease: 先升后降
  • increase_then_decrease: 先降后升
• proportion（比例）
  • value_majority: 单个样本多数
  • value_minority: 单个样本少数
  • total_majority: 样本总和多数
  • total_minority: 样本总和少数
• difference（差异）
  • maximum_large: 最大值较大
  • maximum_small: 最大值较小
  • minimum_large: 最小值较大
  • minimum_small: 最小值较小
  • average_large: 平均值较大
  • average_small: 平均值较小
  • sudden_increase: 时序数据陡增
  • sudden_decrease: 时序数据陡降
  • sudden_change: 类别数据差异明显
• value（数值）
  • total: 总和
  • average: 平均值
  • maximum: 最大值
  • minimum: 最小值
• correlation（相关性）
  • positive: 正相关
  • negative: 负相关

适应图表类型

模块考虑推荐的图表类型，优先提取与该类型最相关的洞察。例如：

• 对于趋势图表，重点识别趋势和变化
• 对于比较图表，重点识别差异和对比
• 对于分布图表，重点识别分布特征和异常值

使用示例

命令行调用

python -m modules.datafact_generator.datafact_generator --input input_data.json --output output_data.json

程序调用

from modules.datafact_generator.datafact_generator import process

success = process(input_data='input_data.json', output='output_data.json')
if success:
    print("数据洞察生成完成")
else:
    print("数据洞察生成失败")

常见问题

Q: 如何控制生成的洞察数量？
A: 模块默认返回评分最高的5个洞察，可以通过修改模块参数调整数量。

Q: 洞察是如何排序的？
A: 洞察按评分（score）从高到低排序，评分反映该洞察的重要性和显著性。

Q: 如何处理小数据集？
A: 对于小数据集，模块会调整统计方法以避免过度解读，并相应降低置信度。