/charting-vega-lite

name: charting-vega-lite
description: Create interactive data visualizations using Vega-Lite declarative JSON grammar. Supports 20+ chart types (bar, line, scatter, histogram, boxplot, grouped/stacked variations, etc.) via templates and programmatic builders. Use when users upload data for charting, request specific chart types, or mention visualizations. Produces portable JSON specs with inline data islands that work in Claude artifacts and can be adapted for production.
metadata:
  version: 0.1.0

Overview

This skill creates interactive Vega-Lite visualizations from uploaded data. The workflow: 1. Analyze data structure and context 2. Select 5-10 meaningful chart types based on what the data represents 3. Build chart specifications programmatically 4. Generate React artifact with embedded visualizations

Critical Technical Constraint: Inline Data Island

**Claude artifacts cannot use fetch() for computer:// URLs.**

All data must be embedded as an inline JavaScript constant:

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

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

**DO NOT:**

• Use fetch() to load external files
• Reference external data URLs
• Create separate data files

This is the only pattern that works in Claude's artifact environment.

Primary Workflow: Data Upload → Chart Explorer

Execute this sequence when user uploads data without specifying chart type:

1. Analyze Data Structure

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

**Extract from output:**

• `fields[]` (with types and statistics)
• `suggested_charts[]` (suggested chart types with encodings)
• `sample_data` (first 10 rows for understanding context)

**If script fails:** Use manual pandas analysis

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

2. Understand Data Context

**Read sample data and column names to infer what the data represents:**

• **Biomedical data?** → Biomarkers, patient outcomes, clinical relevance
• **Financial data?** → Trends, comparisons, performance metrics
• **Sensor data?** → Temporal patterns, anomalies, correlations
• **E-commerce?** → Sales trends, product comparisons, conversions

**Ask:** What questions would someone analyzing this data want answered?

Examples:

• Assay data: Which biomarkers strongest? Patterns across samples? Variability?
• Financial: What are trends? How volatile? Seasonal patterns?
• IoT: Temporal patterns? Anomalies? Sensor correlations?

3. Select Meaningful Charts (5-10 suggestions)

**Filter analyze_data.py suggestions based on context and readability:**

**Apply readability filters:**

• Pie chart with >7 categories → Skip (unreadable)
• Heatmap with >50 categories per axis → Aggregate first
• Multi-line with >10 series → Consider faceting

**Prioritize charts that answer domain questions:**

• Comparison needs → Bar, box plot, grouped bar
• Distribution analysis → Histogram, box plot
• Pattern recognition → Heatmap, scatter
• Temporal trends → Line, area
• Part-to-whole → Stacked bar (pie only if <7 categories)

**Don't suggest charts just because data types match - choose charts that reveal insights.**

4. Generate Chart Specs

**Build specs programmatically using analyze_data.py encodings:**

For each suggested chart type, construct spec using:

• Templates from `assets/templates/` for basic types (bar, line, scatter, pie, heatmap, area)
• Builder patterns from `references/spec-builder-patterns.md` for variations (histogram, boxplot, grouped-bar, etc.)
• Vega-Lite examples from `references/vega-lite-examples-inventory.md` for uncommon types

Structure each chart as:

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

5. Create Artifact with Inline Data Island

Load data, read template, replace `__DATA__` and `__CHART_SPECS__` placeholders, write using bash heredoc.

6. Provide Link

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

Created 7 contextually relevant charts for your data.

Secondary Workflow: Specific Chart Request

When user specifies chart type (e.g., "make a bar chart"):

1. Analyze Data

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

2. Validate Chart Fits Data

**Check requirements:**

• Bar: needs 1 nominal + 1 quantitative
• Line: needs 1 temporal + 1 quantitative
• Scatter: needs 2 quantitative
• Heatmap: needs 2 nominal + 1 quantitative
• Pie: needs 1 nominal + 1 quantitative + <7 categories

**If data doesn't fit:**

• Explain: "Bar chart needs categorical data, but all columns are numeric"
• Suggest 2-3 alternatives
• Use Primary Workflow to create explorer with alternatives

3. Generate Spec

Use templates or programmatic builders based on chart type complexity.

4. Create Artifact

Same pattern as Primary Workflow step 5, but with single chart.

Error Prevention

**Common failures:**

1. **Using fetch() in artifacts**

• Solution: Always use inline data island pattern
• Never create external data files

2. **Chart doesn't render**

• Verify scripts load: Vega → Vega-Lite → Vega-Embed
• Check data is injected: `spec.data = {values: DATA}`
• Confirm field names match data columns

3. **Generic/random chart suggestions**

• Solution: Consider data context and meaning
• Filter suggestions for relevance and readability
• Prioritize charts that answer meaningful questions

Resources

**Scripts:**

• `scripts/analyze_data.py` - analyze structure, suggest 8-12 chart types

**Components:**

• `assets/components/ChartExplorer.jsx` - multi-chart explorer template

**Templates:**

• `assets/templates/*.json` - 6 basic chart templates (bar, line, scatter, pie, heatmap, area)

**References - Progressive Disclosure:**