codebook-pass — 调查数据清洗Skill

本 Skill 是处理中国综合社会调查（CGSS）、中国家庭收入调查（CHIP）、中国社会科学调查（CSS）等大型调查数据的标准化清洗流程。确保从 codebook 到可用面板数据的每一步都可审计、可复现。

适用场景

• 从 CGSS/CHIP/CSS 等数据库下载原始数据后
• 合并多个年份的调查数据时
• 构建面板数据时
• 论文数据准备阶段

核心理念

调查数据清洗的核心原则：原始数据只读不修改，所有转换操作记录在 processed/ 文件夹中，且必须更新 provenance.json。

三个关键规则：

1. 原始数据不可直接修改——所有操作在 processed/ 文件夹中进行
2. 每一步转换必须有记录——包括变量名、编码、处理方式
3. 缺失值必须明确标注——不得将缺失值默认为 0 或其他有意义的数值

工作流程

原始数据 → 导入检查 → 变量命名规范化 → 缺失值处理 → 异常值处理 → 编码统一 → 合并面板 → 输出报告

Step 1 · 原始数据导入检查

必须执行：

import pandas as pd
import numpy as np

# 读取原始数据
df = pd.read_stata("data/raw/cgss2021.dta")

# 基础检查
print(f"样本量: {len(df)}")
print(f"变量数: {len(df.columns)}")
print(f"\n缺失值概况:")
print(df.isnull().sum()[df.isnull().sum() > 0])

检查项：

检查项	预期结果
样本量	与 codebook 描述一致
变量数	与 codebook 描述一致
极端缺失变量	缺失率 >50% 的变量需标注
数据类型	数值型/字符型与 codebook 一致

Step 2 · 变量命名规范化

统一命名规则（建议采用）：

{数据库缩写}_{年份}_{变量原名}
例如：cgss_2021_income, chip_2018_urban

变量编码记录（必须写入 provenance.json）：

{
  "variable": "cgss_2021_urban",
  "description": "城乡户籍类型",
  "original_codes": {"1": "城市", "2": "农村", "9": "未知"},
  "transformed_codes": {"1": "urban", "2": "rural"},
  "missing_handling": "9 → NaN"
}