Light Data Engineering

数据处理、质量分析与数据集构建

核心原则

数据先行：在 m03 提 idea 之前，先回答四问——数据是否足以支撑研究？质量是否可靠？规模是否足够？特征是否有挖掘价值？避免脱离数据基础的空想。"规模是否足够"可先跑 scripts/sample_size_check.py 拿经验预警（分类每类最小样本/回归样本特征比 EPV/检测每类实例数），它给 ok/warn/insufficient 粗筛——但不是 power analysis，主结论样本量仍须正式功效论证。

输入 / 触发

• 上游（idea 前，主线）：用户原始数据 / 现成数据集 / 自建需求 → 出四问结论喂给 m03/m04。
• 回边（实验阶段，来自 m05）：可接收 research-plan 实验矩阵「派生数据规格」区块的派生数据需求（基础数据集 + 变换类型 + 关键参数 + 划分策略），据此产出对应的加噪/缺失/跨域/扫参评测集与 dataset_card，回填 db04 供 ROB/GEN/SEN 实验使用。派生集构建沿用下文「处理流程」「划分」「自建数据集规划」的方法与防泄漏铁律。

数据体检（先做）

1. 概览：行列、类型、内存、样例。

• 中小数据 pandas：读入即定 dtype/parse_dates，df.info(memory_usage='deep') 看真实内存，df.isna().mean() 一行得缺失率，df.describe(include='all')。object 列转 category 省内存。
• 大数据按场景选引擎：单机想要快+查询优化用 Polars 惰性管线 pl.scan_csv(...).filter(...).group_by(...).collect()，超大开 collect(streaming=True)；想用 SQL 直查 parquet/csv 且 out-of-core 用 DuckDB（duckdb.sql("SELECT ... FROM 'data/*.parquet'")，超内存自动 spill）；想保持 pandas 写法又超内存用 Dask dd.read_csv("*.csv")...compute()。（引擎选型矩阵以 a09 tool-selection decision_matrix.md 为单一口径；旧推荐的 Vaex 2023 后已停维护、勿新用。）

1. 质量画像：按需各取所长，别只跑一个。

• ydata-profiling 出整体 EDA 报告：ProfileReport(df, title=...).to_file("r.html")；列多/行多务必 minimal=True，时序 tsmode=True；对比清洗前后/train-test 用 r1.compare(r2)。看报告 Alerts（高相关、高基数、常量、缺失）。
• Deepchecks 跑结构化校验套件：Dataset(df, label=, cat_features=[...]) 后 data_integrity().run(ds)（重复/混合类型/特征-标签泄漏/异常值）、train_test_validation().run(train_ds, test_ds)（漂移/新类别/train-test 样本重叠泄漏）。
• Great Expectations 做可复现质量门禁：gx.get_context() → Data Source/Asset/Batch → Expectation Suite（ExpectColumnValuesToNotBeNull/ToBeBetween/ToBeInSet/ToBeUnique/ToMatchRegex）→ Validation Definition → Checkpoint，产出 Data Docs。注意 GX 1.x 与 0.x API 断层，认版本。
• 标准化交换/发布元数据用 Frictionless：frictionless describe 推断 Table Schema，frictionless validate datapackage.json 出 cell/row 级错误报告。

1. 质量结论：给出“可直接用 / 需清洗 / 不足以支撑 / 需补采”的明确判断与理由。

EDA 与统计分析流程

• EDA 七步：结构概览→缺失分析（missingno matrix/heatmap 看缺失模式）→单变量（数值直方图+箱线、类别频次）→双变量（散点+相关、分组箱线、交叉表/卡方）→多变量（相关热力图、pairplot、PCA）→目标关系（特征 vs 目标，初判预测力与泄漏）→质量小结。EDA 结论只是假设，别用同一份数据既探索又下统计定论。
• 统计检验决策：先查前提——正态性（Shapiro-Wilk，大样本改看 QQ 图，因其过敏感）、方差齐性（Levene）。两组数值正态→t 检验（方差不齐用 Welch）；非正态→Mann-Whitney U；配对→配对 t/Wilcoxon；多组→ANOVA/Kruskal-Wallis；类别关联→卡方/Fisher。必报效应量（Cohen's d、Cramér's V、r/ρ）与置信区间，不只报 p。多检验必校正：FDR(Benjamini-Hochberg) 优先，Bonferroni 更保守。警惕 p-hacking 与 HARKing。

处理流程

• 清洗：去重、类型修正、统一编码/单位、文本规范化。
• 缺失值：分机制(MCAR/MAR/MNAR)选策略——删除/均值中位数/模型插补/标记位。
• 异常值：IQR/z-score/孤立森林/业务规则，区分错误 vs 真实极端。
• 特征工程：编码、缩放、构造、选择(过滤/包裹/嵌入)、降维。
• 数据增强：按模态选工具，先划分再增强、只增训练折（验证/测试保持原始分布，否则指标虚高）——图像 albumentations（bbox/mask 同步变换）、文本 nlpaug（同义词/上下文/回译，注意别翻转标签语义）、时序 tsaug（TimeWarp/Drift/加噪，注意别破坏因果引入泄漏）、表格 SMOTE 等只在训练折拟合。各模态用法与红线见 references「数据增强」节。
• 划分（scikit-learn）——命名方法论锚点(db04 卡 recommendedsplits/preprocessingsteps 指针引用，跨数据集单点维护)：train_test_split(..., stratify=y, random_state=) 分类必分层；交叉验证按数据性质选——SPLIT-01(time-forward 防未来穿越) 时序用 TimeSeriesSplit、SPLIT-02(按组/患者/牧场/地点分域防泄漏) 重复个体用 GroupKFold/StratifiedGroupKFold、一般分类用 StratifiedKFold。LEAK-01(只在训练折 fit)：缩放/插补/编码/特征选择全部放进 Pipeline+ColumnTransformer，只在训练折 fit，绝不在划分前对全量 fit_transform。记录随机种子。（safe_split.py 已对 LEAK-01 做折内 refit 断言。）

自建数据集规划

采集方式、标注规范、数据格式、数据说明文档(datasheet)、隐私合规(脱敏/授权/许可)、发布方式(Zenodo/HF/Figshare + DOI + license)。产出 dataset_card（见 db04 字段）。

• 标注规范用模板 [templates/annotationguide.md](templates/annotationguide.md)：类目定义 / 边界案例判定规则 / LLM 辅助标注+人工审核闭环 / 质检抽样率 / IAA 一致性指标。一致性指标复用 code_assets/agreement.py（Cohen's κ / 二次加权 κ 用于有序评分 / Fleiss' κ ≥3 标注者 / ICC(2,1) 连续值，已对齐 sklearn），不重写；κ 工件落位：用 scripts/emit_artifacts.py --check 核三件套（qualityreport.md / datacard.md / data_feasibility.md）是否落到 §6.1 标准名，--register 打印 passport 登记命令（委托 a01 orchestrator 的 passport.py），保证 orchestrator 台账与 a07 一致性回扫扫得到。

衔接

结论喂给 m03/m04；流水线交 a03 实现；数据集登记 db04 与项目库 db09。隐私/许可问题上报 a10。

随技能脚本（可直接运行，纯 python + 合成自测，无网络依赖）

所有脚本带 --selftest（无需数据，内置合成数据 + 断言验证检测器真的触发）。

• scripts/data_doctor.py：CSV → Markdown 数据体检报告（形状/类型/真实内存/缺失/重复/常量列/全空列/高基数/IQR 异常值/强相关/目标泄漏提示/ID-like 列/inf 无穷值/混合类型列/类不均衡/强偏态/稀有类别，按 HIGH/MED/LOW 给问题摘要）。泄漏检测覆盖数值目标（|corr|≥0.98）与分类目标（数值特征 η² 相关比、类别特征条件纯度，纯 numpy/pandas 算单特征近乎可分）；低基数整数目标自动当分类处理；ID-like 列（近乎逐行唯一）单列提示；高基数阈值随行数自适应。
• 自测：python scripts/data_doctor.py --selftest
• 用法：python scripts/data_doctor.py --csv data.csv --target y --out report.md（--sample N 先抽样防大表卡死）。
• scripts/safe_split.py：按 --task clf/reg/timeseries/group 构建 Pipeline+ColumnTransformer（数值 median 插补+标准化、类别 mostfrequent 插补+OneHot）并自动选 CV——StratifiedKFold/KFold/TimeSeriesSplit/GroupKFold/StratifiedGroupKFold。内置泄漏断言：证明预处理在每折单独 refit（折内 mean ≠ 全量 mean），杜绝划分前 fittransform。时序正确性护栏：timeseries 任务用 --time-col 按时间升序重排并校验单调（不给则显式警告，不静默用乱序数据跑出穿越结果）。group 分类/回归显式声明 --group-clf/--group-reg（不再靠 `nunique0.25 显著。以 PSI 效应量为主、p 为辅(大样本 p 过敏)，检出漂移≠有害。
• 自测：python scripts/drift_check.py --selftest
• 用法：python scripts/drift_check.py --ref train.csv --cur test.csv --out drift.md。
• scripts/derive_eval_set.py：m05 派生数据回边的可执行实现。据派生规格 JSON(基础集 + 变换 + 参数)生成鲁棒性/泛化/敏感性评测集 + 对齐 db04 的 datasetcard 字段。变换：noise(加噪)/missing(MCAR缺失)/subset(跨域子集)/scale(扫参)。铁律：默认只动特征不碰标签(targetsafe)、固定 seed 记入卡、仅作评测不回流训练折。规格示例见 examples/derive_spec.example.json，产出 card_fields 可喂 croissant_export.py 回填 db04。
• 自测：python scripts/derive_eval_set.py --selftest
• 用法：python scripts/derive_eval_set.py --base data.csv --spec derive_spec.json --outdir derived/。
• scripts/emit_artifacts.py：m02 标准工件落位守门——--check 核 qualityreport.md/datacard.md/data_feasibility.md 是否落到 §6.1 标准名，--register 打印委托 orchestrator passport.py 的登记命令(artifacts 路径是 a07 回扫权威清单)。纯标准库。
• 自测：python scripts/emit_artifacts.py --selftest
• 用法：python scripts/emit_artifacts.py --check --dir .。
• 统计检验/效应量/多重校正请复用仓库根的 code_assets/stats_tests.py（相对本技能为 ../../code_assets/，含 welcht、benjaminihochberg、wilson_ci 等），标注一致性复用 agreement.py，长尾重采样复用 longtail_resample.py，不要重造。

---

工具的真实端点/API/参数与已知坑详见 references.md（逐工具核查笔记）。

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Light0305
• Source: Light0305/Light-skills
• License: MIT
• Homepage: https://github.com/Light0305/Light-skills#readme

Install and usage instructions live in the source repository linked above.