data-dictionary

データディクショナリー生成ツール

v1.0 — .dta ファイルから包括的なコードブックを自動生成します

Stata .dta ファイルを読み込み、変数名、型、ラベル、値ラベル、要約統計量、欠損状況を含む、構造化された Markdown データディクショナリーを生成します。そのまま使えるコードブック文書を出力します。

引数： $ARGUMENTS

• .dta ファイル、または .dta ファイルを含むディレクトリのパス

モード（引数に追加）：

• summary（デフォルト）— 1 ページの概要：型、ラベル、欠損状況を含む変数一覧
• full — 包括的なコードブック：概要 + 値ラベル + 要約統計量 + 主要変数の分布
• analysis — 分析用：full の内容 + アウトカムかコントロールか、インデックスか構成要素かについての注記

フラグ：

• 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 ファイルを特定します：
   • ファイルパスの場合：そのファイルを直接読み込みます
   • ディレクトリの場合：その中の *.dta ファイルを glob で検索します
   • ファイル名のみの場合：現在の作業ディレクトリとそのサブディレクトリ（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 から取得（カテゴリの対応関係）
• 非欠損数 N：null でない値の数
• 欠損数 N：null 値の数
• 欠損率 %：欠損値の割合
• ユニーク値数：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 個）
• 欠損パターン：欠損の相関がある変数群を特定します

Step 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 独自のメタデータ（ラベル、値ラベル、型）を使用します。メタデータがない場合に限り、推測します。
• 不足箇所を明示すること。 ラベルのない変数、説明のない値ラベル、欠損率の高さは、いずれも明示する価値があります。これらは混乱の原因になりやすいためです。
• 分析モードは提案であり、指示ではありません。 変数の分類は命名パターンに基づいており、誤っている可能性があります。提案として提示します。
• 再現可能であること。 出力にはソースパスと生成日が含まれ、どのバージョンのデータを文書化したのかが明確になります。