define-variables

Define-Variables Skill

各曝露変数、アウトカム変数、共変量、適格性変数を、標準的なガイドライン／コンセンサス定義に対応付け、類似コホートにおける過去の操作的定義と照合したうえで、利用可能なDB変数に対応付けます。/design-study（および/search-lit）の後、/write-protocolの前に実行します。

入力

1. 研究課題（1文）
2. 候補変数 — 曝露、アウトカム、主要な共変量、適格性フィルター
3. データディクショナリのパス（xlsx / csv / markdown）、または利用可能なDB列の明示的なリスト
4. コホートの種類（例：健診、NHANES相当、請求、レジストリ）— 比較対象とする先行研究のコホートを選ぶ際に使用します

入力が不足している場合 → 1回確認してから続行します。

4段階のパイプライン（DBコードブック＋トークン効率の高い文献検索）

Tier 0 — DBコードブックの照会（DBに基づく観察研究では必須）

実行条件：プロジェクトに、機械可読なコードブック（xlsx/csv/markdown）を指すproject.yaml::db.dictionary_pathフィールドがある、または入力でユーザーがディクショナリのパスを指定した場合。どちらにも該当しない場合は、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に該当しない変数、またはサブグループ別の根拠が必要な場合（アジア人向けカットオフ、小児、若年成人、妊娠など）は、変数ごとに1つのクエリを指定して/search-litを呼び出します。一般的な一括検索は行いません。関連する情報が埋もれてしまうためです。クエリの形式：

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

最初の1～2本の論文で同じ定義が確認できた時点で、その変数の検索を終了します。Tier 2が必要な変数が5つを超える場合は、対象を一覧にして、残りの検索を実行する前にユーザーに確認します。

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. 操作的定義の表 — 変数ごとに1行：

   | 変数 | 役割 | 辞書のシートと行 | 辞書の原文 | 標準的な情報源 | 定義 | カットオフ | DB 変数 | 実装 | 独自定義？ |

   • Role：曝露／アウトカム／共変量／適格性
   • Dict. sheet & row：例：5-1.복부초음파 r12 — DB 辞書が存在する場合は必須
   • Dict. verbatim：辞書からそのまま転記したコード→意味の文字列全体 — 同じ条件下で必須
   • Canonical source：BibTeX キー（例：@rinella2023_aasld_masld）。後続のスキルで再検証できます
   • Definition：可能な限りガイドラインの原文をそのまま用いた1行の定義
   • Cutoff：数値＋単位
   • DB vars：使用する辞書の列名を正確に記載
   • Implementation：SQL／pandas 形式の疑似コード（例：bmi>=25 & (b_tg>=150 | b_hdl<40)）
   • Ad-hoc?：はい／いいえ。「はい」の場合は表の下に根拠を記載

3. 独自定義の根拠 — 「はい」の各行について記載

4. マッピング上の不足 — プロトコル内に DB の対応項目がない変数を列挙し、代替指標／除外／照会の判断を記載

5. 参考文献 — BibTeX ブロック

対象外：統計解析 → /analyze-stats；論文原稿の執筆 → /write-paper；データクリーニング／欠測値 → /clean-data；サンプルサイズ → /calc-sample-size

避けるべき失敗パターン

1. 列を起点にした定義 — まず利用可能な列を確認してから、それに合う定義を選ぶこと。順序を逆にしてください。まず定義を決め、その後に対応付けます。列を選んだ後は、Tier 0 が引き続き適用されます。値を使う前に、コードブックの項目をそのまま引用してください。
2. カットオフのずれ — 正当な根拠なく、引用したガイドラインとは異なるカットオフを使用すること（例：本文では≥25と記載しながら、WHOのアジア人向け基準としてBMI≥23を引用する）。
3. 異なる時期の基準の混在 — 同じ解析で2020年のMAFLD基準と2023年のMASLD基準を混在させること。どちらか一方を選び、その理由を記載してください。
4. 用量／期間の構造的欠測 — カテゴリカルな曝露（喫煙状況、飲酒状況）に基づく用量／期間の共変量（pack-years、禁煙後の年数、週あたりのアルコール摂取量）を操作的に定義する際、基準値（非喫煙者、非飲酒者）における用量の扱いを明示しないこと。非喫煙者のpack-yearsは構造的なゼロであり、欠測値ではありません。この2つを混同すると、完全症例解析で解析対象者数が減り、MICEによって非曝露者にゼロ以外の用量が補完されるおそれがあります。明示的に操作的定義を記載してください。Role = covariate および Implementation = "IF status == 'never' THEN dose = 0 ELSE measured_value" の行を追加し、カテゴリカルな状況変数で調整してください。連続値の用量は、曝露者のみを対象とする副次解析用に確保します。/clean-data（カテゴリカル変数からゼロを推定するフラグ）と/analyze-stats（「共変量の落とし穴」）で、この方針を後続工程に適用します。