define-variables

Define-Variables 技能

将每个暴露、结局、协变量和纳入资格变量映射到规范的指南／共识定义，与可比队列中既往的操作化定义交叉核对，然后映射到可用的 DB 变量。在 /design-study（和 /search-lit）之后、/write-protocol 之前调用。

输入

1. 研究问题（一句话）
2. 候选变量——暴露、结局、关键协变量、纳入资格筛选条件
3. 数据字典路径（xlsx / csv / markdown）或可用 DB 列的明确列表
4. 队列类型（例如，健康筛查、类似 NHANES 的队列、理赔、登记队列）——用于确定要对照的既往研究队列

缺少输入时 → 询问一次，然后继续。

四层流程（DB 代码本 + 节省令牌的文献检索）

Tier 0 — DB 代码本查询（DB 支持的观察性研究必做）

触发条件：项目的 project.yaml::db.dictionary_path 字段指向机器可读的代码本（xlsx/csv/markdown），或用户在输入中提供了字典路径。若两者都没有，则跳至 Tier 1。

对于每个候选 DB 变量，在查阅文献之前打开字典，并逐字记录工作表名称、行号和代码→含义映射。这可以避免最常见的观察性研究错误：想当然地认为某列代码（status == 0、grade == 4）的含义与其表面含义一致，而代码本中的解释却并非如此。

每个变量：

1. 按精确列名在字典中定位变量。
2. 逐字复制：工作表标题、行号，以及完整的代码→含义映射（连续变量则复制单位／取值范围说明）。
3. 将其粘贴到操作化表格的 Dict. sheet & row 和 Dict. verbatim 列中。
4. 如果找不到变量，或代码本未说明某个具体代码值，则向 DB 所有者／数据管理员提出问题。不得根据交叉表推断，不得猜测；在获得逐字答复之前，不得继续处理该变量。

经验检查（值分布、与相关列的交叉表）可在记录代码本的逐字含义之后用于合理性检验，绝不能替代代码本。

建议在项目根目录（或共享配置路径）提交 DICTIONARY_FIRST_POLICY.md，其中注明规范字典路径和升级联系人的信息。

退出门槛：进入 Tier 1 之前，需将每一行的 Dict. sheet & row 和 Dict. verbatim 与源字典交叉核对；不得留空任何由 DB 支持的行。

Tier 1 — 规范索引查询（不调用 API）

在 references/common_definitions.md 中查询变量（肝病学、代谢／内分泌、肾脏、肺部、心血管、肿瘤学／影像偶发发现、酒精暴露）。若找到，记录指南、年份、规范界值和 BibTeX 键。完成——无需调用 /search-lit。

Tier 2 — 定向 /search-lit（仅聚焦查询）

对于 Tier 1 中未收录的变量，或需要亚组依据时（针对亚洲人群的界值、儿科、青年、妊娠等），调用 /search-lit，每个变量使用一条查询——绝不进行泛泛检索，以免淹没有效信息。查询模式：

"{construct} definition {cohort type} {subgroup qualifier}"
e.g., "obstructive sleep apnea prevalence Korean health screening cohort"

一旦最先找到的 1-2 篇论文对同一定义达成一致，就停止检索该变量。如果有五个以上变量需要 Tier 2，则列出这些变量，并在继续检索其余变量前向用户确认。

Tier 3 — 核验

每项定义、界值和时代锚点都必须来自已核实的来源——临床指南、带 DOI 的同行评审论文，或成熟登记系统的数据字典。绝不能采用模型记忆中的表型阈值或引用。定稿之前，对累积的 BibTeX 运行 /verify-refs，确认每条引文都存在于 PubMed／CrossRef 中。没有规范来源的选择须标记为 Ad-hoc: yes，用 1-2 句话说明理由，并在其进入 /write-protocol 或 /analyze-stats 之前取得用户确认。

输出模板

根据 templates/variable_operationalization.md 编写 {project_root}/variable_operationalization.md（或用户指定的路径）。结构要求：

1. 标题：研究问题、队列类型、日期、作者

2. 操作化表格——每个变量一行：

   | 变量 | 角色 | 字典表 & 行 | 字典原文 | 权威来源 | 定义 | 截止值 | DB 变量 | 实现方式 | 临时方案？ |

   • Role：exposure / outcome / covariate / eligibility
   • Dict. sheet & row：例如 5-1.복부초음파 r12——如果存在 DB 字典，则为必填项
   • Dict. verbatim：从字典复制完整的代码→含义字符串——在上述同一条件下为必填项
   • Canonical source：BibTeX 键（例如 @rinella2023_aasld_masld），以便下游技能重新核验
   • Definition：尽可能逐字引用指南中的定义，不超过一行
   • Cutoff：数值 + 单位
   • DB vars：使用的确切字典列名
   • Implementation：SQL/pandas 风格伪代码（例如 bmi>=25 & (b_tg>=150 | b_hdl<40)）
   • Ad-hoc?：yes/no。如果为 yes，在表格下方说明理由

3. 临时方案的理由——为每个 yes 行说明理由

4. 映射缺口——列出方案中没有 DB 对应项的变量；注明代理变量 / 忽略 / 请求的决策

5. 参考文献——BibTeX 区块

不在范围内：统计分析 → /analyze-stats；论文撰写 → /write-paper；数据清理 / 缺失值处理 → /clean-data；样本量 → /calc-sample-size。

需要避免的失误

1. 以列为先的思路——先查看有哪些列，再选择与之匹配的定义。务必反过来：先确定定义，再进行映射。选定列后，Tier 0 仍然适用：使用其取值前，先逐字引用其代码本条目。
2. 截止值偏移——使用了不同于所引指南的截止值，却未说明理由（例如引用 WHO 亚洲人群标准时 BMI≥23，但正文写成 ≥25）。
3. 混淆不同时期的标准——在同一分析中混用 2020 年 MAFLD 标准和 2023 年 MASLD 标准。选定一种，并说明原因。
4. 剂量/时长的结构性缺失——将剂量/时长协变量（包年、戒烟年数、每周饮酒克数）与分类暴露（吸烟状态、饮酒情况）关联进行操作化，却未说明剂量应如何处理参照水平（从不吸烟者、从不饮酒者）。从不吸烟者的包年数是结构性零值，而不是缺失值；将二者混为一谈会导致在完整案例建模中分析样本量缩减，也会让 MICE 为未暴露者虚构非零剂量。必须明确进行操作化——添加一行，设定 Role = covariate 和 Implementation = "IF status == 'never' THEN dose = 0 ELSE measured_value"——并对分类状态变量进行调整，将连续型剂量留作仅针对暴露者的次级分析。/clean-data（分类变量隐含零值标记）和 /analyze-stats（“协变量陷阱”）会在下游环节强制执行此要求。