data-dictionary

数据字典生成器

v1.0 — 从 .dta 文件自动生成全面的代码本

读取 Stata .dta 文件，并生成结构化的 Markdown 数据字典，包含变量名、类型、标签、值标签、汇总统计和缺失情况。输出可直接使用的代码本文档。

参数： $ARGUMENTS

• .dta 文件路径或包含 .dta 文件的目录

模式（追加到参数后）：

• summary（默认）—— 一页概览：变量列表、类型、标签和缺失情况
• full —— 完整代码本：概览 + 值标签 + 汇总统计 + 关键变量的分布
• analysis —— 适用于分析的版本：完整代码本 + 关于哪些变量是结果变量或控制变量、哪些是指数或组成部分的说明

标志：

• vars:consumption,assets —— 仅记录与这些模式匹配的变量
• output:path/to/output.md —— 自定义输出路径（默认与输入文件在同一目录，命名为 codebook_[filename].md）
• format:md（默认）| format:csv —— 输出格式

示例：/data-dictionary data/for_analysis/endline_analysis.dta full 示例：/data-dictionary . vars:consumption,exp_ 示例：/data-dictionary data/for_analysis/ summary

---

说明

步骤 0：定位并加载数据

1. 解析 $ARGUMENTS 以查找 .dta 文件：
   • 如果是文件路径：直接读取该文件
   • 如果是目录：在其中 glob 查找 *.dta 文件
   • 如果是裸名称：在当前工作目录及其子目录（data/、data/for_analysis/、output/）中搜索
2. 对于包含多个文件（>10 个）的目录，生成索引页和各个代码本
3. 从 $ARGUMENTS 解析模式和标志。默认使用 summary。

步骤 1：提取元数据

编写临时 Python 脚本（使用 uv run python 或 python3）。绝不使用 python -c。

import pandas as pd
import pyreadstat

df, meta = pyreadstat.read_dta("path/to/file.dta",
                                apply_value_formats=False)

# Available metadata:
# meta.column_names          — variable names (list)
# meta.column_labels          — variable labels (dict: name -> label)
# meta.variable_value_labels  — value label mappings (dict: name -> {code: label})
# meta.original_variable_types — Stata storage types (dict: name -> type string)
# meta.number_columns         — count of numeric columns
# meta.number_rows            — row count
# meta.file_label              — dataset label
# meta.notes                   — dataset notes

针对每个变量，提取：

• 名称：列名
• 标签：来自 meta.column_labels（可能为空）
• 类型：来自 meta.original_variable_types（例如，float、double、byte、int、long、str#）
• 值标签：来自 meta.variable_value_labels（分类映射）
• 非缺失数量：非空值的数量
• 缺失数量：空值的数量
• 缺失百分比：缺失值所占百分比
• 唯一值：nunique

步骤 2：汇总统计（full 和 analysis 模式）

对于数值变量：

• 均值、标准差、最小值、P25、中位数、P75、最大值
• 标记：通常应为正值的变量中出现负值的情况

对于字符串变量：

• 唯一值数量
• 出现频率最高的 5 个值及其计数
• 最大字符串长度

对于二元（0/1）变量：

• 1 的比例（含计数）

对于分类变量（带有值标签的变量）：

• 频数表：代码、标签、计数、百分比

步骤 3：变量分类（仅限 analysis 模式）

尝试根据命名模式对变量角色进行分类：

模式	分类
hhid、id、*_id	标识符
treat*、arm*、t_*	处理变量
strat*、block*、pair*	分层变量
i_*、idx_*、index_*	指数/综合变量
z_*	Z 分数
exp_*、cons_*、income_*	结果变量（经济）
is_*、has_*、any_*	二元指示变量
mi_*、miss_*	缺失标志
_wins、_w、_tr	缩尾/截尾变量
bl_*、base_*	基线变量
wt_*、weight*	抽样权重

将分类结果作为建议而非定论呈现。包含“未分类”类别。

步骤 4：变量间关系（仅限 analysis 模式）

• 指数分解：对于指数变量（i_、idx_），识别可能的组成变量并报告相关性
• 处理组平衡性：如果检测到处理变量，报告关键变量按处理组分组的均值（前 10 个数值变量）
• 缺失模式：识别缺失情况相关的变量簇

第 5 步：生成输出

输出位置：

• 默认：与输入文件相同的目录，文件名为 codebook_[filename]_[YYYY-MM-DD].md
• 使用 output: 标志覆盖
• 对于目录输入：生成 codebook_index_[YYYY-MM-DD].md 和各个代码簿

告知用户输出文件的完整绝对路径。

---

输出格式 — 摘要模式

# Data Dictionary: [filename]

**Generated:** [YYYY-MM-DD]
**Source:** [full path]
**Dataset label:** [meta.file_label if available]
**Observations:** [N rows]
**Variables:** [N columns]

---

## Variable List

| # | Variable | Label | Type | Non-missing | Missing % | Unique |
|---|----------|-------|------|-------------|-----------|--------|
| 1 | hhid | Household ID | long | 5,000 | 0.0% | 5,000 |
| 2 | treat | Treatment arm | byte | 5,000 | 0.0% | 3 |
| ... | ... | ... | ... | ... | ... | ... |

---

## Variables Without Labels

[List any variables that have no label — these may need documentation]

---

## Notes

- [N] variables are entirely missing (0 non-missing values)
- [N] variables have >50% missing values
- [N] categorical variables have value labels defined

输出格式 — 完整模式

在摘要的基础上添加：

---

## Summary Statistics — Numeric Variables

| Variable | N | Mean | SD | Min | P25 | Median | P75 | Max |
|----------|---|------|-----|-----|-----|--------|-----|-----|
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

---

## Summary Statistics — Binary Variables

| Variable | Label | N | Prop = 1 | Count = 1 |
|----------|-------|---|----------|-----------|
| ... | ... | ... | ... | ... |

---

## Value Labels — Categorical Variables

### [variable_name]: [label]

| Code | Label | Count | Percent |
|------|-------|-------|---------|
| 0 | Control | 2,500 | 50.0% |
| 1 | Treatment | 2,500 | 50.0% |

[Repeat for each categorical variable with value labels]

---

## String Variables

| Variable | Label | N | Unique | Max Length | Top Values |
|----------|-------|---|--------|------------|------------|
| ... | ... | ... | ... | ... | [val1 (N), val2 (N), ...] |

---

## High Missingness Variables (>20%)

| Variable | Label | Missing % | Non-missing N |
|----------|-------|-----------|---------------|
| ... | ... | ... | ... |

输出格式 — 分析模式

在完整模式的基础上添加：

---

## Variable Classification (suggested)

### Identifiers
| Variable | Label |
|----------|-------|
| hhid | Household ID |

### Treatment & Stratification
| Variable | Label | Values |
|----------|-------|--------|
| treat | Treatment arm | 0: Control, 1: Treatment |

### Outcome Indices
| Variable | Label | Mean | SD | Likely Components |
|----------|-------|------|-----|-------------------|
| i_consumption | Consumption index | 0.00 | 1.00 | exp_food, exp_nonfood, ... |

### Outcome Variables
[table]

### Control Variables / Baseline
[table]

### Missing Flags
[table]

### Unclassified
[table]

---

## Treatment Balance (first 10 numeric variables)

| Variable | Control Mean | Treatment Mean | Diff | p-value |
|----------|-------------|----------------|------|---------|
| ... | ... | ... | ... | ... |

---

原则

• 全面但便于浏览。 该字典既应作为参考文档（使用 ctrl+F 查找变量），也应便于快速概览（浏览摘要表）。
• 优先使用元数据。 始终使用 Stata 自带的元数据（标签、值标签、类型），而不是自行推断。仅在缺少元数据时进行推断。
• 标明缺漏。 未加标签的变量、未记录的值标签和较高的缺失率都值得标明——它们最容易造成困惑。
• 分析模式仅供参考，不具规定性。 变量分类基于命名模式，可能有误。应将其作为建议呈现。
• 可复现。 输出包含源路径和生成日期，以明确记录的是哪个版本的数据。