数据一键处理 Skill

这是一个适合初学者使用的 CSV / Excel 数据自动处理项目。只需要提供一个数据文件，程序就会自动完成数据检查、基础清洗、异常值检测、目标列识别、数据集划分，并生成 Markdown 报告。

程序不会修改原始文件，不会删除字段，也不会自动删除异常值。

增强版还支持 JSON 配置、日期字段识别、HTML 报告、机器学习就绪数据导出和可复用预处理器。

安装依赖

建议先创建 Python 虚拟环境，然后安装依赖：

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

macOS / Linux 激活虚拟环境：

source .venv/bin/activate

如何运行

在项目根目录运行：

python scripts/process_data.py --input examples/sample_input.csv --output_dir outputs --target_col label

使用配置文件并生成机器学习就绪数据：

python scripts/process_data.py --input examples/sample_input.csv --output_dir outputs --target_col label --config examples/config.json --prepare_ml

参数说明：

• --input：必填，CSV 或 Excel 文件路径。
• --output_dir：可选，输出目录，默认是 outputs。
• --target_col：可选，机器学习目标列名称。
• --config：可选，JSON 配置文件路径，可设置划分比例、随机种子、日期字段等。
• --prepare_ml：可选，生成编码和标准化后的 ML 数据及预处理器。

不指定目标列：

python scripts/process_data.py --input examples/sample_input.csv

输入文件要求

• 支持 .csv、.xlsx 和 .xls；其中 openpyxl 用于 .xlsx，xlrd 用于旧版 .xls。
• CSV 文件建议使用 UTF-8 编码；程序也会尝试 utf-8-sig 和 gb18030。
• Excel 默认读取第一个工作表。
• 第一行必须是字段名，字段名不能重复。
• 不建议直接使用超大文件；当前版本会将完整数据读入内存。

输出文件说明

所有结果都会保存到 --output_dir：

• cleaned_data.csv：清洗后的完整数据。
• train.csv：训练集，约占 80%。
• val.csv：验证集，约占 10%。
• test.csv：测试集，约占 10%。
• data_processing_report.md：数据概况、处理动作、异常值、风险提示和建议。
• data_processing_report.html：可直接使用浏览器打开的数据报告。
• processing_metadata.json：输入、配置、目标列、任务类型和输出文件元数据。
• ml_train.csv、ml_val.csv、ml_test.csv：使用 --prepare_ml 时生成。
• preprocessing_pipeline.joblib：只在训练集上拟合的可复用预处理器。

程序会做什么

• 删除完全重复的行。
• 去除文本字段前后空格。
• 将空字符串、None、null、nan 等统一为缺失值。
• 数值列缺失值用中位数填充。
• 低基数类别列缺失值用众数填充。
• 高基数文本列缺失值用空字符串填充。
• 使用 IQR 方法检测数值异常值，但不删除它们。
• 尝试使用分层抽样划分分类数据。
• 根据字段名和配置谨慎识别日期字段。
• 可通过 JSON 配置调整数据划分比例和随机种子。
• ML 导出时对数值列标准化、类别列独热编码，并避免在验证集和测试集上拟合。

常见问题

为什么没有使用分层划分？

样本太少、某些类别数量太少，或目标列无法识别时，分层划分可能失败。程序会自动退化为普通随机划分，并在报告中说明。

为什么某些字符串列被当作类别列？

程序使用唯一值数量和唯一值比例判断。低基数字符串列按类别列处理，高基数字符串列按文本列处理。

会删除异常值吗？

不会。异常值只会记录在报告中，需要结合业务含义人工判断。

会覆盖我的数据吗？

不会。程序拒绝把输出文件写到输入文件本身。

配置文件示例

{
  "random_state": 42,
  "train_ratio": 0.8,
  "val_ratio": 0.1,
  "test_ratio": 0.1,
  "detect_dates": true,
  "date_columns": [],
  "date_parse_success_ratio": 0.8,
  "duplicate_warning_ratio": 0.1
}

后续扩展方向

• 支持真正的大文件流式和分块处理。
• 支持图表、数据漂移检查和更丰富的特征工程。
• 支持通过 YAML 配置自定义每个字段的清洗策略。