clean-data

数据分析与清理技能

分三个阶段对临床数据集进行分析、标记并生成清理代码，每个阶段都以用户审批关卡结束。你生成代码和报告；不会自动清理数据。每项清理决策都需要研究人员明确确认，因为临床数据清理需要领域知识。

优先处理 PHI。 如果数据集包含 PHI 或 PII，请先运行 /deidentify，并在工作目录中存在 *_deidentified.* 文件时使用这些文件。否则，仅依据数据字典 / 代码本开展工作，或在无法访问网络的纯本地环境中工作。此技能会编写可在数据上运行的代码；编写代码无需查看原始数据行。

三阶段工作流

阶段 1：分析

输入：CSV/Excel 文件路径，或数据字典/代码本

1. 根据数据集调整 ${CLAUDE_SKILL_DIR}/references/profiling_template.py（pandas）。该脚本会报告：变量和行数、数据类型；每个变量的缺失数量和百分比；分类变量的唯一值数量；数值变量的最小值/最大值/均值/中位数/标准差；直方图和条形图。
2. 如果用户提供了代码本，请交叉核对变量名、预期类型和预期范围。切勿猜测列名或编码方式：如果映射不确定，请写入 [VERIFY: variable_name]，并请用户对照数据字典确认。
3. 展示摘要（参见输出格式）。所有计数和统计值都必须来自已执行脚本的输出。

关卡：由用户审核分析结果。询问是否继续进入阶段 2（标记），以及是否要排除或重点关注任何变量。

阶段 2：标记

阅读 ${CLAUDE_SKILL_DIR}/references/cleaning_patterns.md，了解缺失数据机制、异常值决策规则、重复项检测、日期处理和临床陷阱（带不等号前缀的实验室值、混合单位、哨兵值）。标记以下类别的问题：

1. 缺失值：缺失比例 >5% 的变量；模式分析（MCAR/MAR/MNAR 启发式判断）。
2. 统计异常值：IQR 方法（Q1 - 1.5IQR、Q3 + 1.5IQR）和 Z 分数（|z| > 3）。
3. 重复项：完全重复的行，以及近似重复项（同一患者 ID、不同日期）。
4. 类型不匹配：以字符串形式存储的数值、格式不一致的日期。
5. 不合乎常理的值：根据代码本的有效范围进行标记；如果代码本未说明，则根据 references/implausible_value_rules.md §1 中的领域默认生理硬性边界进行标记。不合乎常理的值很可能是数据录入、单位或哨兵值错误（予以更正或设为缺失）；统计异常值（#2）在生物学上可能存在（保留并进行敏感性分析）。判定边界违规为错误之前，先检查单位。切勿自动修正。 5b. 跨字段不一致：根据 references/implausible_value_rules.md §2 检查逻辑矛盾——时间顺序（出生 ≤ 事件 ≤ 死亡、入院 ≤ 出院）、派生值与源值（重新计算 BMI/年龄；子集 ≤ 超集；总量 = 各部分之和）、性别或状态特定字段，以及最小值 ≤ 最大值 / 舒张压 < 收缩压等字段对。指出触发的规则；严重矛盾的严重程度为高。
6. 类别不一致：分类值中的拼写错误和变体（“Male”、“male”、“M”、“MALE”）。
7. 由类别隐含的零值：当某个类别定义了剂量或时长变量的自然零值时（smoking_status == 'never' 表示 pack_years == 0；alcohol_use == 'never' 表示 grams_per_week == 0），标记将该隐含零值存为 NULL 的记录。这属于矛盾，而非缺失数据模式：完整案例模型会悄然丢弃这些从不吸烟者，MICE 则会为其插补非零剂量，从而破坏暴露对比。建议操作：“当 category == reference level 时，将 dose 设为 0；仅对暴露组的剩余缺失值进行插补。”给定类别↔剂量映射后，可通过 scripts/check_structural_zero.py 检测；与 /analyze-stats 的“协变量陷阱：结构性零值与剂量/时长变量”配合使用。
8. 反向编码量表条目：对于混合正向和反向措辞条目的多题 Likert 量表，必须在计算量表总分或 Cronbach's alpha 之前，将每个反向条目重新编码为 (min+max) - x。未重新编码的反向条目与其余条目呈负相关，会使 alpha 大幅下降，甚至变成负值。负 alpha 表示反向编码错误，而非“多维结构”。建议操作：“重新编码反向措辞条目，然后重新计算信度。”给定量表条目列后，可通过 scripts/check_reverse_coding.py 检测（条目与其余条目的相关性为负，且原始 alpha 为负）；重新编码由下游的 /analyze-stats likert_summary.py --reverse-items 执行。

将标记报告整理成表格：

变量	问题类型	数量	严重程度	建议操作
age	异常值（IQR）	3	中	检查：值为 150、200、-5
pack_years	由类别隐含的零值	12421	高	当 smoking_status=='never' 时设为 0（结构性零值，而非缺失）

严重程度级别：

• 高：很可能是会影响分析的数据错误（类型不匹配、不可能的值）
• 中：需要专家审查的潜在问题（统计异常值、中度缺失）
• 低：容易修正的轻微不一致（类别标签、尾随空格）

关卡：用户为每一行标记 (A) 批准建议的操作、(R) 拒绝 / 保持原样，或 (M) 修改操作。只有获批的操作才会生成清理代码。

阶段 3：代码生成

对于用户仅已批准的操作，生成 Python（或用户要求时使用 R）代码：

• 缺失值处理：按行删除、均值／中位数插补，或设置 MICE（仅提供代码，由用户运行并选择变量和方法）
• 异常值处理：缩尾处理、删除，或保留并标记
• 删除重复项：精确去重并记录日志
• 类型转换：统一日期格式、解析数值
• 类别统一：为不一致的标签创建映射表

所有生成的代码必须包含：

• 在控制台打印处理前后的行数
• 将每项修改记录到清理日志 DataFrame
• 保证可复现：在适用时使用 np.random.seed(42) 和 random.seed(42)
• 输出：清理后的 CSV（新文件；绝不覆盖输入文件）以及 cleaning_log.csv
• 清晰的注释，说明每个清理步骤

生成的脚本须以以下声明结尾：

“此代码仅执行你已批准的清理规则。请检查输出文件 cleaning_log.csv，确认所有更改后再继续分析。”

不在处理范围内：从临床笔记中提取自由文本，以及图像数据或 DICOM 元数据。清理完成后，移交给 /analyze-stats。引用只能取自 /search-lit，不得凭记忆提供。

输出格式

使用以下模板构建所有报告：

## Data Profiling Report

### Dataset Overview
- Rows: [N]
- Columns: [N]
- File size: [size]
- Date range: [if applicable]

### Variable Summary
| Variable | Type | Missing N (%) | Unique | Min | Max | Mean | SD |
|----------|------|---------------|--------|-----|-----|------|-----|
| ...      | ...  | ...           | ...    | ... | ... | ...  | ... |

### Flags
| Variable | Issue | Count | Severity | Suggested Action |
|----------|-------|-------|----------|-----------------|
| ...      | ...   | ...   | ...      | ...             |

### Cleaning Code
[Python/R script -- only for approved actions]

### Cleaning Log
[What was changed, how many rows affected, before/after counts]