exploring-data

探索数据

0. 首先按大小选择路径

ls -la <filepath>   # or: wc -l for row estimate

• < 200MB 且 < ~5M 行 → ydata-profiling 路径（A 节）。提供精确统计信息和交互式 HTML。
• 更大 → 大文件路径（B 节）。ydata-profiling 会将所有内容加载到 pandas 中，运行会非常慢或因内存不足而失败；DuckDB/Sketch 路径在任何大小下都能以固定内存运行。
• 特定任务的操作（任何大小）：重复项、连接可行性、漂移 → C 节。

A. 标准路径（ydata-profiling）

1. 检查是否已安装（即时）

bash /mnt/skills/user/exploring-data/scripts/check_install.sh

返回：installed 或 not_installed

2. 如有需要则安装（一次性，约 19 秒）

if [ "$(bash /mnt/skills/user/exploring-data/scripts/check_install.sh)" = "not_installed" ]; then
    bash /mnt/skills/user/exploring-data/scripts/install_ydata.sh
fi

3. 运行分析（默认始终生成 JSON + HTML）

bash /mnt/skills/user/exploring-data/scripts/analyze.sh <filepath> [minimal|full] [html|json]

默认值： minimal + html（也会生成 JSON）

输出：

• eda_report.html - 提供给用户的交互式报告
• eda_report.json - 供 Claude 分析的机器可读文件

4. 如果 Claude 需要进行分析（用户问“你怎么看？”等）

python /mnt/skills/user/exploring-data/scripts/summarize_insights.py /mnt/user-data/outputs/eda_report.json

Claude 应读取标准输出中的 Markdown 摘要，而不是完整的 JSON 报告。

5. 直观呈现发现（不要只把 ydata HTML 交给用户）

ydata 报告内容全面但信息密集；仅提供链接并不是理想的交付方式。 将 JSON 转换为一份简洁的仪表板，展示重要发现：

python3 /mnt/skills/user/exploring-data/scripts/visualize_findings.py \
    /mnt/user-data/outputs/eda_report.json
# → /mnt/user-data/outputs/eda_findings.html

生成一个独立的 HTML 文件（使用 cdnjs 上的 Chart.js，并支持深色模式）： 按列展示缺失情况（分级标示良好/较差）、以小多图直方图展示偏斜最严重或零膨胀的数值分布，以及展示规模最大的类别细分。--top N 用于限制每个类别的图表数量（默认 6）。该工具也可读取 profile_large.py --json 的输出，因此大文件路径也能获得同样的处理效果。

同时提供两个文件：用于快速了解要点的 eda_findings.html，以及用于完整深入分析的 eda_report.html。在支持内联渲染可视化内容的聊天界面中，优先以内联图表展示实际回答用户问题的两到三个发现，而不是链接文件——让用户自行打开的链接，是最弱的“展示”数据的方式。

模式

最简模式（默认，5-10 秒）： 概览、变量分析、相关性、缺失值、警报 完整模式（10-20 秒）： 最简模式 + 散点矩阵、样本数据、字符分析

完整模式触发词：“全面分析”、“详细 EDA”、“完整分析”、“深入分析”。否则使用最简模式。

时间序列

如果数据有日期时间索引/列，且用户关注时间行为（间隔、趋势、季节性、自相关），则向 ProfileReport 传入 tsmode=True — 直接运行虚拟环境中的 Python，而不是运行 analyze.sh：

ProfileReport(df, tsmode=True, sortby="<datetime_col>", title=...)

这会增加间隔检测、平稳性和季节性检查，而默认报告会省略这些内容。

小文件漂移

比较两个都能放入内存的数据集版本：使用 ydata 内置的比较功能 — ProfileReport(df_a).compare(ProfileReport(df_b)).to_file(...)。 对于无法加载的大文件，或与已不存在的数月前文件进行比较，请使用 C 节中的 sketch 快照/漂移操作。

B. 大文件路径（DuckDB，固定内存）

1. 安装依赖项（可重复执行，首次约 10 秒）

bash /mnt/skills/user/exploring-data/scripts/install_large.sh

2. 分析

python3 /mnt/skills/user/exploring-data/scripts/profile_large.py <file> [--json out.json]

通过 DuckDB 流式处理文件：逐列统计空值百分比、近似去重计数 （HLL）、最小值/最大值/平均值、数值的近似分位数（t-digest）、字符串的前 5 个值，以及质量标记（几乎全为空、常量、类似 ID 的列）。Markdown 会输出到标准输出 — 直接读取即可，无需汇总步骤。支持 csv/tsv/parquet/json/ndjson。分析 1M 行只需几秒； 无论文件大小如何，内存占用都保持不变。

对于同一大型文件的临时后续查询，请直接使用 DuckDB SQL （duckdb.connect().execute("SELECT ... FROM read_csv_auto('...')")），不要将文件加载到 pandas 中。

C. Sketch 操作（任何文件大小，固定内存）

所有操作均通过 scripts/sketch_ops.py 执行（依赖项来自 install_large.sh）。这些操作可回答分析工具无法解答的问题：

近似重复行

python3 sketch_ops.py dups <file> [--threshold 0.9] [--cols a,b,c] [--unweighted]

通过哈希统计完全重复项；通过对行令牌使用 MinHash LSH 检测近似重复项。--threshold 是加权 Jaccard 阈值：某个令牌在一行中出现 c 次，就按 c 次计数，因此 new york new york 和 york new 的得分为 0.5，而不是 1.0。使用 --unweighted 可采用集合语义，此时会丢弃重复项。使用 --cols 限定用于定义身份的列。

键重叠／联接可行性

python3 sketch_ops.py overlap <fileA> <fileB> --key <col> [--key-b <col>]

为每个键列创建 Theta sketch → 估算交集、Jaccard，以及“A 中有多少键也在 B 中”的双向比例——无需加载任何一个文件，即可回答“这次联接能成功吗？”

与已存储基线对比漂移

python3 sketch_ops.py snapshot <file> --out baseline.sketch.json   # ~20KB
python3 sketch_ops.py drift <newfile> --baseline baseline.sketch.json

快照会将 HLL（所有列）和 KLL 分位数 sketch（数值列）序列化为一个小型 JSON。漂移报告会显示架构变更、不同值计数变化超过 10% 的情况，以及相对于 IQR 的分位数变化。快照只有几 KB——保存它（在代码仓库或内存中），下个月交付数据时即可与之比较，无需保留原始文件。

注意：snapshot/dups 会通过 Python 流式处理行（约 1M 行只需几秒）；profile_large 则完全使用 DuckDB，速度更快。快速查看大文件时，先运行 profile；只有在需要回答相应问题时才运行 sketch 操作。