charting-vega-lite

概述

此技能可根据上传的数据创建交互式 Vega-Lite 可视化。工作流：

1. 分析数据结构和上下文
2. 根据数据所代表的内容选择 5-10 种有意义的图表类型
3. 以编程方式构建图表规范
4. 生成嵌入可视化内容的 React artifact

关键技术限制：内联数据岛

Claude artifact 无法对 computer:// URL 使用 fetch()。

所有数据都必须嵌入为内联 JavaScript 常量：

const DATA = [ /* embedded data array */ ];

// Later in chart specs:
spec.data = { values: DATA };

请勿：

• 使用 fetch() 加载外部文件
• 引用外部数据 URL
• 创建单独的数据文件

这是在 Claude artifact 环境中唯一可行的模式。

主要工作流：上传数据 → 图表浏览器

用户上传数据但未指定图表类型时，按以下顺序执行：

1. 分析数据结构

python /mnt/skills/user/charting-vega-lite/scripts/analyze_data.py /mnt/user-data/uploads/<filename>

从输出中提取：

• fields[]（包含类型和统计信息）
• suggested_charts[]（包含建议的图表类型及编码）
• sample_data（前 10 行，用于了解上下文）

如果脚本失败： 使用 pandas 手动分析

import pandas as pd
df = pd.read_csv('/mnt/user-data/uploads/<filename>')
# Classify: numeric→quantitative, datetime→temporal, <20 unique→nominal

2. 了解数据上下文

阅读样本数据和列名，推断数据所代表的内容：

• 生物医学数据？ → 生物标志物、患者结局、临床相关性
• 金融数据？ → 趋势、比较、绩效指标
• 传感器数据？ → 时间模式、异常、相关性
• 电子商务？ → 销售趋势、产品比较、转化

思考： 分析这类数据的人希望获得哪些问题的答案？

示例：

• 分析数据：哪些生物标志物最强？样本之间有哪些模式？存在怎样的差异？
• 金融：有哪些趋势？波动性如何？有哪些季节性模式？
• IoT：有哪些时间模式？是否存在异常？传感器之间有何相关性？

3. 选择有意义的图表（5-10 项建议）

根据上下文和可读性筛选 analyze_data.py 的建议：

应用可读性筛选规则：

• 饼图类别数 >7 → 跳过（难以阅读）
• 热力图任一轴上的类别数 >50 → 先聚合
• 多折线图系列数 >10 → 考虑分面

优先选择能回答领域问题的图表：

• 需要比较 → 条形图、箱线图、分组条形图
• 分布分析 → 直方图、箱线图
• 模式识别 → 热力图、散点图
• 时间趋势 → 折线图、面积图
• 部分与整体 → 堆叠条形图（仅在类别数 <7 时使用饼图）

不要只因数据类型匹配就建议图表——应选择能够揭示洞察的图表。

4. 生成图表规范

使用 analyze_data.py 的编码，以编程方式构建规范：

对于每种建议的图表类型，使用以下内容构建规范：

• assets/templates/ 中的基础类型模板（bar、line、scatter、pie、heatmap、area）
• references/spec-builder-patterns.md 中的构建器模式（histogram、boxplot、grouped-bar 等变体）
• references/vega-lite-examples-inventory.md 中的 Vega-Lite 示例（不常见类型）

将每张图表组织为：

{"type": "Chart Name", "reason": "Why this chart", "spec": {/* vega-lite spec */}}

5. 使用内联数据岛创建 artifact

加载数据，读取模板，替换 __DATA__ 和 __CHART_SPECS__ 占位符，然后使用 bash heredoc 写入。

6. 提供链接

[View chart explorer](computer:///mnt/user-data/outputs/ChartExplorer.jsx)

Created 7 contextually relevant charts for your data.

次要工作流：指定图表请求

用户指定图表类型时（例如“制作条形图”）：

1. 分析数据

python /mnt/skills/user/charting-vega-lite/scripts/analyze_data.py /mnt/user-data/uploads/<filename>

2. 验证图表是否适用于数据

检查要求：

• 条形图：需要 1 个名义型变量 + 1 个定量变量
• 折线图：需要 1 个时间型变量 + 1 个定量变量
• 散点图：需要 2 个定量变量
• 热力图：需要 2 个名义型变量 + 1 个定量变量
• 饼图：需要 1 个名义型变量 + 1 个定量变量，且类别数 <7

如果数据不适用：

• 解释：“条形图需要分类数据，但所有列都是数值型”
• 建议 2-3 种替代方案
• 使用主要工作流创建包含替代方案的浏览器

3. 生成规范

根据图表类型的复杂程度，使用模板或以编程方式构建。

4. 创建 artifact

采用与主要工作流第 5 步相同的模式，但只创建一张图表。

错误预防

常见故障：

1. 在 artifacts 中使用 fetch()

   • 解决方案：始终使用内联数据岛模式
   • 切勿创建外部数据文件

2. 图表无法呈现

   • 验证脚本加载顺序：Vega → Vega-Lite → Vega-Embed
   • 检查是否已注入数据：spec.data = {values: DATA}
   • 确认字段名称与数据列匹配

3. 图表建议泛泛或随机

   • 解决方案：考虑数据的上下文和含义
   • 筛选建议，确保相关性和可读性
   • 优先选择能够回答有意义问题的图表

资源

脚本：

• scripts/analyze_data.py - 分析结构并推荐 8-12 种图表类型

组件：

• assets/components/ChartExplorer.jsx - 多图表浏览器模板

模板：

• assets/templates/*.json - 6 个基础图表模板（条形图、折线图、散点图、饼图、热力图、面积图）

参考资料 - 渐进式披露：

以编程方式构建图表（直方图、箱线图、分组/堆叠条形图、多折线图等）时，阅读 spec-builder-patterns.md

当用户要求使用 spec-builder-patterns 中未涵盖的少见图表类型时，阅读 vega-lite-examples-inventory.md

在验证特定图表需求，或用户询问“……该用什么图表？”时，阅读 chart-types.md

要查看专业图表（桑基图、瀑布图、小提琴图、复杂分层组合图）的完整规范，请阅读 advanced-charts.md

如果不熟悉数据领域（生物医学、金融、物联网等），请阅读 contextual-chart-selection.md，了解更多领域示例

要获取 Vega-Lite 文档以了解高级功能（自定义选择、转换、条件编码），请阅读 online-resources.md

完整工作流示例

用户上传检测数据 CSV（51 个检测项，74 个样本）

# 1. Analyze
python /mnt/skills/user/charting-vega-lite/scripts/analyze_data.py /mnt/user-data/uploads/assay_data.csv

# 2. Understand context: Multi-analyte immunoassay
#    Questions: Which biomarkers strongest? Patterns across samples? Variability?

# 3. Build contextual charts (5-7 specs)
#    Bar: Mean signal by assay
#    Heatmap: Sample × Assay
#    Box plot: Signal distribution by assay
#    Histogram: Overall signal distribution
#    etc.

# 4. Load data and template
df = pd.read_csv('/mnt/user-data/uploads/assay_data.csv')
data = df.to_dict(orient='records')
template = open('/mnt/skills/user/charting-vega-lite/assets/components/ChartExplorer.jsx').read()

# 5. Replace placeholders and write
artifact = template.replace('__DATA__', json.dumps(data)).replace('__CHART_SPECS__', json.dumps(charts))
# Use bash heredoc to avoid XML conflicts in tool parameters

# 6. Provide link

查看图表浏览器

已为你的检测数据创建 7 个图表：条形图展示生物标志物信号，热力图揭示样本模式，箱线图展示变异性。

重要规则

1. 始终使用内联数据岛模式——不使用 fetch()，不创建外部文件
2. 考虑数据上下文——根据数据代表的含义选择有意义的图表，而不只是看数据类型
3. 按可读性筛选——避免使用类别过多的图表
4. 使用 bash heredoc 创建文件——避免创建 artifacts 时出现 XML 冲突
5. 提供链接，不提供内容——提高输出 token 效率