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 到 -0.5	轻微左偏	“低值离群点略多于高值离群点”
-0.5 到 0.5	对称	“分布均衡，适用于大多数分析”
0.5 到 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	探索多变量关系时	“每个单元格都展示了两个变量之间的关系”
violin_plot.png	比较组别时	“这里展示了各组的分布差异”

常见用户问题 → 操作

用户说	操作
“分析这个 CSV”	运行完整分析，展示概览和关键洞见
“我的数据干净吗？”	重点查看 quality_score、缺失值和重复项
“寻找规律”	展示 correlation_heatmap，并突出显示强相关性
“有异常值吗？”	展示 box_plots，并列出每列的异常值数量
“比较 Y 中的 X”	为数值型 X 与类别型 Y 生成 violin_plot
“展示趋势”	如果存在日期时间列，则生成 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