csv-analyzer

CSV アナライザー

概要

包括的な CSV データ分析・可視化エンジンです。スクリプトを実行した後、このガイドを使って結果を解釈し、ユーザーにインサイトを提供してください。

クイックスタート

cd ~/.claude/skills/csv-analyzer/scripts
export $(grep -v '^#' /path/to/project/.env | xargs 2>/dev/null)
python3 analyze_csv.py /path/to/data.csv

チャート選択の判断ツリー

重要：ユーザーが理解したい内容に基づいてチャートを選択してください。

What is the user trying to understand?
│
├── "What does my data look like?" (Overview)
│   └── Run with defaults → overview_dashboard.png
│
├── "Is my data clean?" (Quality)
│   └── Check: quality_score, missing_values, duplicates
│   └── Show: missing_values.png if problems exist
│
├── "What's the distribution?" (Single Variable)
│   ├── Numeric → numeric_distributions.png (histogram + KDE)
│   ├── Categorical → categorical_distributions.png (bar chart)
│   └── Time-based → time_series.png
│
├── "Are there outliers?" (Anomalies)
│   └── box_plots.png → points beyond whiskers are outliers
│
├── "How are variables related?" (Relationships)
│   ├── 2 numeric vars → correlation_heatmap.png
│   ├── 2-6 numeric vars → pairplot.png (scatter matrix)
│   ├── Numeric vs Categorical → violin_plot.png
│   └── All numeric → correlation_heatmap.png
│
└── "Can I predict X from Y?" (Predictive)
    └── correlation_heatmap.png → |r| > 0.5 suggests predictive power

結果の解釈方法（Claude 向け）

品質スコアの解釈

スコア	評価	ユーザーへの説明
90-100	A	「データの品質は非常に高く、分析にすぐ使えます」
80-89	B	「データの品質は良好ですが、注意すべき軽微な問題があります」
70-79	C	「品質は中程度です。重要な分析を行う前に、欠損値に対処してください」
60-69	D	「品質に重大な問題があります。まずデータをクリーニングすることをおすすめします」
<60	F	「重大な問題があります。データには大幅なクリーニングが必要です」

相関の解釈

|r| 値	強さ	説明
0.9 - 1.0	非常に強い	「X と Y は非常に強く関連しており、ほぼ決定論的です」
0.7 - 0.9	強い	「X と Y には強い関係があります。X は Y の予測に役立つ可能性があります」
0.5 - 0.7	中程度	「X と Y には中程度の相関があり、ある程度の予測価値があります」
0.3 - 0.5	弱い	「X と Y の関係は弱く、予測力は限られています」
0.0 - 0.3	ほぼなし	「X と Y は関連していないようです」

符号も重要です：

• 正： 「X が増加すると、Y も増加する傾向があります」
• 負： 「X が増加すると、Y は減少する傾向があります」

歪度の解釈

歪度	分布の形状	推奨事項
< -1	左側の裾が重い	「値の大半は高く、非常に低い外れ値がいくつかあります」
-1 to -0.5	軽度の左への歪み	「高い外れ値よりも、低い外れ値がやや多くあります」
-0.5 to 0.5	対称	「バランスの取れた分布で、多くの分析に適しています」
0.5 to 1	軽度の右への歪み	「低い外れ値よりも、高い外れ値がやや多くあります」
> 1	右側の裾が重い	「値の大半は低く、非常に高い外れ値がいくつかあります。モデリングでは対数変換を検討してください。」

外れ値の評価

外れ値を報告する際は、次のように説明してください。

• 外れ値が少ない（<1%）：「調査が必要と思われる極端な値がいくつかあります」
• 外れ値が中程度（1-5%）：「無視できない外れ値があります。エラーなのか、実際の極端値なのかを確認してください」
• 外れ値が多い（>5%）：「外れ値の割合が高く、データに問題があるか、正規分布ではない可能性があります」

インサイト生成フレームワーク

分析の実行後、次の順序でインサイトを提示してください。

1. データの概要（必ず提示）

"Your dataset has [rows] records and [cols] columns:
- [n] numeric columns: [list top 3]
- [n] categorical columns: [list top 3]
- Data quality score: [score]/100 ([grade])"

2. 主な調査結果（関連性の高いものを選択）

品質に問題がある場合：

"I noticed some data quality concerns:
- [X]% missing values in [column] - [recommend: drop/impute/investigate]
- [N] duplicate rows detected - [recommend: keep first/remove all/investigate]"

強い相関が見つかった場合：

"Interesting relationships I found:
- [col1] and [col2] are strongly correlated (r=[value]) - [interpretation]
- This suggests [actionable insight]"

外れ値が検出された場合：

"I detected outliers in [columns]:
- [column]: [n] values beyond normal range ([min outlier] to [max outlier])
- These could be [data errors / genuine extremes / worth investigating]"

分布に歪みがある場合：

"[Column] has a [right/left]-skewed distribution:
- Most values cluster around [median]
- But there are extreme values up to [max]
- For modeling, consider [log transform / robust methods]"

3. 推奨事項（調査結果に基づく）

調査結果	推奨事項
列の欠損率が20%超	「この列を削除するか、欠損している理由を調査することを検討してください」
欠損が散在し、5%未満	「中央値（数値）または最頻値（カテゴリ）で補完しても問題ありません」
相関が高い（>0.9）	「これらの列は重複している可能性があります。いずれか一方だけを残すことを検討してください」
外れ値が多い	「ロバスト統計量（平均値ではなく中央値）を使用するか、データ収集方法を調査してください」
分布の歪みが大きい	「線形モデリングの前に対数変換を適用してください」
品質スコアが低い	「分析の前にデータクリーニングを優先してください」

複数チャートのダッシュボードを求められた場合

ユーザーが「ダッシュボード」または「包括的なビュー」を求めた場合：

# Generate all visualizations
python3 analyze_csv.py data.csv --format html --max-charts 10

次の順序でチャートを提示してください。

1. overview_dashboard.png - 「データの全体像をご覧ください」
2. correlation_heatmap.png - 「変数間の主な関係」
3. numeric_distributions.png - 「数値データの分布」
4. box_plots.png - 「外れ値の分析」
5. categorical_distributions.png - 「カテゴリの内訳」（該当する場合）

コマンドリファレンス

基本的な分析

python3 analyze_csv.py data.csv

すべてのチャートを含む完全なレポート

python3 analyze_csv.py data.csv --format markdown --max-charts 10

クイック分析（チャートなし）

python3 analyze_csv.py data.csv --no-charts

大容量ファイル（>100MB）

python3 analyze_csv.py huge.csv --sample 50000

特定の日付列

python3 analyze_csv.py data.csv --date-columns created_at updated_at

プログラムでの使用向け JSON

python3 analyze_csv.py data.csv --format json --no-charts

カスタム出力先

python3 analyze_csv.py data.csv --output-dir /path/to/project/.tmp/analysis

チャートの説明（ユーザーへの説明用）

チャート	表示するタイミング	説明方法
overview_dashboard.png	最初に全体像を見るときは常に	「データの全体像をご覧ください」
missing_values.png	欠損データがある場合	「データのどこに欠損があるかを示しています」
numeric_distributions.png	分布を調べるとき	「数値がどのように分布しているかを示しています」
box_plots.png	外れ値を確認するとき	「箱の外側にある点は、外れ値の可能性があります」
correlation_heatmap.png	関係性を調べるとき	「色が濃いほど、関係性が強いことを示します」
categorical_distributions.png	カテゴリを分析するとき	「カテゴリの内訳を示しています」
time_series.png	時系列データの場合	「データが時間とともにどのように変化するかをご覧ください」
pairplot.png	多変量データを調べるとき	「各セルは、2つの変数の関係を示しています」
violin_plot.png	グループを比較するとき	「グループ間で分布がどのように異なるかを示しています」

よくあるユーザーの質問 → アクション

ユーザーの発言	アクション
「この CSV を分析して」	全体分析を実行し、概要と主なインサイトを表示します
「データはきれいですか？」	quality_score、欠損値、重複に注目します
「パターンを見つけて」	correlation_heatmap を表示し、強い相関を強調します
「外れ値はありますか？」	box_plots を表示し、列ごとの外れ値の数を一覧表示します
「Y に対する X を比較して」	数値 X とカテゴリ Y の violin_plot を生成します
「傾向を見せて」	datetime 列がある場合、time_series を生成します
「ダッシュボードを作成して」	すべてのチャートを生成し、整理した概要を提示します
「何をクリーニングすればいいですか？」	欠損率が 5% を超える列、重複、外れ値を一覧表示します

出力先

チャートの保存先：

• デフォルト：~/.claude/skills/csv-analyzer/scripts/.tmp/csv_analysis/
• カスタム：--output-dir /path/to/project/.tmp/analysis を使用します

チャートを確認できるよう、必ずユーザーのプロジェクトの .tmp にコピーしてください：

cp ~/.claude/skills/csv-analyzer/scripts/.tmp/csv_analysis/*.png /path/to/project/.tmp/csv_analysis/

費用

無料です。pandas、matplotlib、seaborn、scipy を使用して、すべてローカルで実行されます。

依存関係

pip install pandas matplotlib seaborn scipy numpy