charting-vega-lite

概要

このスキルは、アップロードされたデータからインタラクティブな Vega-Lite の可視化を作成します。ワークフロー：

1. データの構造とコンテキストを分析します
2. データが表す内容に基づいて、意味のあるグラフの種類を5～10個選択します
3. プログラムでグラフ仕様を構築します
4. 可視化を埋め込んだ React アーティファクトを生成します

重要な技術的制約：インラインデータアイランド

Claude アーティファクトでは、computer:// URL に対して fetch() を使用できません。

すべてのデータをインライン JavaScript 定数として埋め込む必要があります：

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

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

以下は行わないでください：

• 外部ファイルの読み込みに fetch() を使用する
• 外部データ URL を参照する
• 個別のデータファイルを作成する

Claude のアーティファクト環境で機能するのは、この方法だけです。

メインワークフロー：データのアップロード → グラフエクスプローラー

ユーザーがグラフの種類を指定せずにデータをアップロードした場合、次の手順を実行します：

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. データのコンテキストを把握する

サンプルデータと列名から、データが何を表しているかを推測します：

• 生物医学データですか？ → バイオマーカー、患者の転帰、臨床的意義
• 金融データですか？ → 傾向、比較、パフォーマンス指標
• センサーデータですか？ → 時間的パターン、異常、相関関係
• Eコマースデータですか？ → 売上傾向、製品比較、コンバージョン

確認すること： このデータを分析する人は、どのような問いへの答えを求めているでしょうか？

例：

• アッセイデータ：最も強いバイオマーカーはどれか？サンプル間にどのようなパターンがあるか？変動性はどの程度か？
• 金融：どのような傾向があるか？変動性はどの程度か？季節的なパターンはあるか？
• IoT：時間的なパターンはあるか？異常はあるか？センサー間に相関はあるか？

3. 意味のあるグラフを選択する（推奨5～10個）

コンテキストと読みやすさに基づいて、analyze_data.py の推奨候補を絞り込みます：

読みやすさの基準を適用します：

• カテゴリーが7個を超える円グラフ → スキップします（判読しにくいため）
• 軸ごとのカテゴリーが50個を超えるヒートマップ → まず集約します
• 系列が10個を超える複数折れ線グラフ → ファセット化を検討します

分野に関する問いに答えられるグラフを優先します：

• 比較が必要 → 棒グラフ、箱ひげ図、グループ化棒グラフ
• 分布の分析 → ヒストグラム、箱ひげ図
• パターンの認識 → ヒートマップ、散布図
• 時間的な傾向 → 折れ線グラフ、面グラフ
• 全体に対する各要素の割合 → 積み上げ棒グラフ（カテゴリーが7個未満の場合に限り円グラフ）

データ型が一致するというだけでグラフを推奨せず、洞察を引き出せるグラフを選択してください。

4. グラフ仕様を生成する

analyze_data.py のエンコーディングを使って、仕様をプログラムで構築します：

推奨するグラフの種類ごとに、次のものを使って仕様を構築します：

• 基本的な種類（棒、折れ線、散布図、円、ヒートマップ、面）のテンプレート：assets/templates/
• バリエーション（ヒストグラム、箱ひげ図、グループ化棒グラフなど）のビルダーパターン：references/spec-builder-patterns.md
• 一般的でない種類の Vega-Lite の例：references/vega-lite-examples-inventory.md

各グラフを次の形式で構成します：

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

5. インラインデータアイランドを使ってアーティファクトを作成する

データを読み込み、テンプレートを読み取り、__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. アーティファクトを作成する

メインワークフローの手順5と同じ方法を使いますが、グラフは1つだけにします。

エラーの防止

よくある失敗：

1. アーティファクト内で 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 を読みます

データの領域（生物医学、金融、IoT など）に詳しくない場合は、領域別の例をさらに確認するために 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 を使用する - アーティファクトの作成時に XML の競合を防ぎます
5. コンテンツではなくリンクを提供する - 出力トークンを効率的に使用します