SAV 数据合并

纵向合并多个 SAV 文件（追加行），保留完整元数据。

核心流程

必须先分析、展示差异、获得用户确认，再执行合并。

第一步：分析差异

python scripts/sav_merge.py analyze "file1.sav" "file2.sav" -o diff_report.json

输出 JSON 包含：

files: 各文件行数、列数
common_variable_count: 共同变量数
differences: 仅某文件独有的变量（含变量名、标签、位置、值标签）
value_label_differences: 共同变量中值标签不一致的情况
variable_label_differences: 共同变量中变量标签不一致的情况
common_vars_same_order: 共同变量顺序是否一致

第二步：向用户展示差异

将分析结果翻译为可读格式，逐项列出：

文件概况 — 各文件行数 × 变量数
独有变量 — 哪些变量只存在于某个文件，附变量标签和值标签
值标签差异 — 同名变量的值标签不同（可能影响数据含义）
变量标签差异 — 同名变量的标签文字不同（通常不影响合并）
变量顺序 — 是否一致

对每个差异项，询问用户如何处理：

独有变量：保留（其他文件填缺失值）/ 丢弃 / 重命名
值标签差异：以哪个文件为准，或合并
变量顺序：以哪个文件为基准

第三步：构建策略并执行合并

根据用户反馈生成 strategy.json：

{
  "variable_order_source": 1,
  "extra_vars": {
    "H4": "keep",
    "X1": "drop",
    "OLD_NAME": "rename:NEW_NAME"
  },
  "insert_positions": {
    "H4": "after:G1_其他"
  }
}

字段说明：

variable_order_source: 以哪个文件的变量顺序为基准（0=第一个文件）
extra_vars: 独有变量处理方式（keep / drop / rename:新名）
insert_positions: 保留的独有变量插入位置（after:变量名 / before:变量名），不指定则自动推断

执行合并：

python scripts/sav_merge.py merge "file1.sav" "file2.sav" -o output.sav --strategy strategy.json

第四步：验证结果

合并后读取输出文件，验证：

总行数 = 各文件行数之和
变量数正确
独有变量的缺失值填充正确
值标签保留完整

用户交互要点

不要自行决定丢弃或保留变量，必须列出差异等用户确认
差异展示要简洁清晰：变量名 + 标签 + 位于哪个文件 + 位置上下文
如果没有任何差异（变量完全一致），告知用户可直接合并，无需额外确认
如果差异项多（>10），分类汇总后列出，避免信息过载

双引擎读取

脚本优先使用 pyreadstat，失败时自动回退到纯 Python 读取器，处理 pmStation 等非标准 SAV 文件。

依赖

pandas
pyreadstat
numpy

sav-merge