Data Dictionary

---
name: data-dictionary
description: "从 Stata .dta 文件自动生成完整代码手册（codebook）：变量清单、摘要统计、值标签与缺失情况报告。 Triggers: 帮我生成这个数据集的代码手册、把这个 dta 文件整理成数据字典、这份数据里有哪些变量、帮我看看变量的缺失情况、给这份数据做个 codebook、整理一下变量标签和值标签。"
---

# 数据字典生成器

*v1.0 —— 从 .dta 文件自动生成完整代码手册*

读取 Stata .dta 文件，产出结构化的 Markdown 数据字典，包含变量名、类型、标签、值标签、摘要统计与缺失情况。输出一份可直接使用的代码手册（codebook）文档。

**参数：** `$ARGUMENTS`
- 某个 .dta 文件的路径，或包含 .dta 文件的目录

**模式**（附加在参数后）：
- `summary`（默认）—— 一页总览：变量清单，含类型、标签、缺失情况
- `full` —— 完整代码手册：总览 + 值标签 + 摘要统计 + 关键变量的分布
- `analysis` —— 面向分析：完整版 + 标注哪些变量是结果变量、哪些是控制变量、哪些是指数、哪些是构成项

**标志（Flags）：**
- `vars:consumption,assets` —— 只记录匹配这些模式的变量
- `output:path/to/output.md` —— 自定义输出路径（默认：与输入同目录，命名为 `codebook_[文件名].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`。

```python
import pandas as pd
import pyreadstat

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

# 可用的元数据：
# meta.column_names          — 变量名（list）
# meta.column_labels          — 变量标签（dict: name -> label）
# meta.variable_value_labels  — 值标签映射（dict: name -> {code: label}）
# meta.original_variable_types — Stata 存储类型（dict: name -> type string）
# meta.number_columns         — 数值列个数
# meta.number_rows            — 行数
# meta.file_label              — 数据集标签
# meta.notes                   — 数据集备注
```

对每个变量提取：
- **名称**：列名
- **标签**：取自 `meta.column_labels`（可能为空）
- **类型**：取自 `meta.original_variable_types`（如 `float`、`double`、`byte`、`int`、`long`、`str#`）
- **值标签**：取自 `meta.variable_value_labels`（分类变量的编码映射）
- **非缺失 N**：非空值个数
- **缺失 N**：空值个数
- **缺失 %**：缺失百分比
- **唯一值个数**：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_[文件名]_[YYYY-MM-DD].md`
- 可用 `output:` 标志覆盖
- 目录输入时：`codebook_index_[YYYY-MM-DD].md` + 各文件单独的代码手册

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

---

## 输出格式 —— Summary 模式

```markdown
# 数据字典：[文件名]

**生成日期：** [YYYY-MM-DD]
**来源：** [完整路径]
**数据集标签：** [meta.file_label，如有]
**观测数：** [N 行]
**变量数：** [N 列]

---

## 变量清单

| # | 变量 | 标签 | 类型 | 非缺失 | 缺失 % | 唯一值 |
|---|----------|-------|------|-------------|-----------|--------|
| 1 | hhid | Household ID | long | 5,000 | 0.0% | 5,000 |
| 2 | treat | Treatment arm | byte | 5,000 | 0.0% | 3 |
| ... | ... | ... | ... | ... | ... | ... |

---

## 无标签变量

[列出所有没有标签的变量 —— 这些可能需要补文档]

---

## 备注

- [N] 个变量完全缺失（0 个非缺失值）
- [N] 个变量缺失率 >50%
- [N] 个分类变量定义了值标签
```

## 输出格式 —— Full 模式

在 summary 基础上增加：

```markdown
---

## 摘要统计 —— 数值变量

| 变量 | N | 均值 | 标准差 | 最小值 | P25 | 中位数 | P75 | 最大值 |
|----------|---|------|-----|-----|-----|--------|-----|-----|
| ... | ... | ... | ... | ... | ... | ... | ... | ... |

---

## 摘要统计 —— 二值变量

| 变量 | 标签 | N | 取 1 比例 | 取 1 计数 |
|----------|-------|---|----------|-----------|
| ... | ... | ... | ... | ... |

---

## 值标签 —— 分类变量

### [变量名]: [标签]

| 编码 | 标签 | 计数 | 百分比 |
|------|-------|-------|---------|
| 0 | Control | 2,500 | 50.0% |
| 1 | Treatment | 2,500 | 50.0% |

[对每个带值标签的分类变量重复]

---

## 字符串变量

| 变量 | 标签 | N | 唯一值 | 最大长度 | 高频取值 |
|----------|-------|---|--------|------------|------------|
| ... | ... | ... | ... | ... | [值1 (N), 值2 (N), ...] |

---

## 高缺失变量（>20%）

| 变量 | 标签 | 缺失 % | 非缺失 N |
|----------|-------|-----------|---------------|
| ... | ... | ... | ... |
```

## 输出格式 —— Analysis 模式

在 full 基础上增加：

```markdown
---

## 变量分类（建议）

### 标识符
| 变量 | 标签 |
|----------|-------|
| hhid | Household ID |

### 处理与分层
| 变量 | 标签 | 取值 |
|----------|-------|--------|
| treat | Treatment arm | 0: Control, 1: Treatment |

### 结果指数
| 变量 | 标签 | 均值 | 标准差 | 可能的构成变量 |
|----------|-------|------|-----|-------------------|
| i_consumption | Consumption index | 0.00 | 1.00 | exp_food, exp_nonfood, ... |

### 结果变量
[表格]

### 控制变量 / 基线
[表格]

### 缺失标记
[表格]

### 未分类
[表格]

---

## 处理组平衡性（前 10 个数值变量）

| 变量 | 对照组均值 | 处理组均值 | 差值 | p 值 |
|----------|-------------|----------------|------|---------|
| ... | ... | ... | ... | ... |
```

---

## 原则

- **全面但可扫读。** 字典既要能当参考文档用（ctrl+F 查某个变量），也要能当速览用（扫一眼汇总表）。
- **元数据优先。** 始终使用 Stata 自带的元数据（标签、值标签、类型），不要凭空推断。仅在元数据缺失时才推断。
- **标记缺口。** 无标签变量、无文档的值标签、高缺失率都值得标记 —— 它们是最可能造成困惑的地方。
- **analysis 模式是建议性的，不是规定性的。** 变量分类基于命名规律，可能有误。以建议形式呈现。
- **可复现。** 输出包含来源路径与生成日期，使人清楚记录的是哪个版本的数据。

---

## 来源与许可

上游 [eabeam/econ-skills](https://github.com/eabeam/econ-skills)（实证经济学研究可复用 AI 技能集，含 econ-audit / data-dictionary / lit-review 三个子技能），许可证见上游仓库，2026-09-10 收录（commit 1b0238d）；原文英文，本包译为简体中文。