Skip to contents

PLAN QC 技術リファレンス

Source: vignettes/qc-plan-jp.Rmd
qc-plan-jp.Rmd

PLAN QCは、一般的な解析計画やコーディング仕様から、研究固有の内容を推測せずにRコードを作成できるかを確認するスキルです。

QCスキルガイドに戻る

English version

目的と適用範囲

PLAN QCの目的は、解析計画をR実装仕様へ変換したときに、データ抽出、変数導出、統計処理、出力生成の各処理が一意に定まるかを評価することです。評価対象は文書の文章品質ではなく、実装可能性、内部整合性、追跡可能性、未承認の仮定が混入するリスクです。

PLAN QCは、一般的な解析計画またはコーディング仕様に適用します。臨床試験SAPにはSAP QCを使用し、解析目的やデータの意味自体が未確定の場合はCONTEXT QCへ戻ります。

開始条件

入力 要件
解析計画またはコーディング仕様 必須。レビュー対象の版を識別できること
解析依頼・CONTEXT QC 推奨。目的と前提の整合性確認に使用
データ定義・変数一覧 R実装可能性を判定する場合は原則必要
出力仕様・モック 表・図の実装可能性を判定する場合は必要
QC_STATUS.md 任意。未解決事項の継続確認に使用

使用するタイミング

  • 記述統計、クロス集計、疫学研究、レジストリ研究の計画を作成した後
  • 探索的解析の仕様を作成した後
  • Rコード作成へ進む前
  • 実装担当者から計画の曖昧さを指摘されたとき
  • RESULT QCで計画不足が見つかったとき

臨床試験SAPを確認する場合は、通常、PLAN QCではなくSAP QCを使用します。

確認対象

  • 解析目的と仮説
  • 対象集団と解析単位
  • 評価項目と変数
  • 解析時点と時間の定義
  • 統計手法とモデル
  • 欠測データの扱い
  • サブグループ解析と感度分析
  • 出力仕様
  • R実装とパッケージ
  • 既知の制約、仮定、未解決事項

CONTEXT QCで確認した内容やQC_STATUS.mdがある場合は、計画との整合性も確認します。

確認する主要領域

1. 解析目的

  • 何を記述、比較、推定または予測するか
  • 主要解析と補足・探索的解析が区別されているか
  • 比較方向と解釈対象が明確か

2. 対象集団と解析単位

  • 対象集団の選択・除外条件が実装可能か
  • 1人1行、1観察1行など、解析単位が明確か
  • 複数時点、複数イベント、クラスタリングの扱いが明確か
  • 分母と解析対象フラグが定義されているか

3. 評価項目と変数

  • 使用する列名または導出元が特定されているか
  • 単位、カテゴリ、基準値、評価時点が明確か
  • 導出式、ウィンドウ、優先順位、タイブレーク規則があるか
  • ベースライン値と変化量の定義が明確か

4. 時間に関する仕様

生存時間解析や縦断解析では、少なくとも次を確認します。

  • 時間原点
  • イベント定義
  • 打ち切り規則
  • 競合イベント
  • 評価期間
  • visit window
  • 同日イベントの優先順位

これらが曖昧なままでは、見かけ上動作するコードでも異なる解析結果を生む可能性があります。

5. 統計手法

  • 各目的・評価項目に対応する手法が指定されているか
  • 効果指標、信頼区間、検定、両側・片側が明確か
  • モデル式、調整変数、層別因子、交互作用が明確か
  • 基準カテゴリと比較方向を一意に特定できるか
  • モデル仮定と診断方法が必要か

単に「回帰分析を行う」だけでは、モデル、分布、リンク関数、共変量、推定対象が決まりません。

6. 欠測データ

  • 欠測の定義とコード
  • 完全ケース、補完、モデル内処理などの方法
  • 欠測による除外をどの段階で行うか
  • 欠測数と解析対象者数をどのように報告するか
  • 感度分析が必要か

7. サブグループ解析と感度分析

  • 事前指定か探索的か
  • サブグループ変数とカテゴリ
  • 各群内推定か交互作用検定か
  • 多重性への配慮
  • 主解析と異なる条件

8. 出力仕様

  • 表・図・モデル出力の種類
  • 行、列、群、時点、統計量
  • 件数、分母、欠測の表示
  • 桁数、単位、信頼区間、p値
  • 表題、脚注、略語、保存先、ファイル名

9. R実装

  • データ読み込みと前処理の責任範囲
  • 使用予定の関数またはパッケージ
  • パッケージの利用可能性やバージョン確認
  • 乱数シード、ログ、sessionInfo()
  • 中間データと最終出力の保存先

パッケージが指定されていても、インストール済みであることや実行可能であることを未確認のまま断定しません。

実装可能性の判断

準備状況は、対象となる次工程ごとに判定します。

状態 適用条件
Ready 研究固有の推測なしに実装できる
Mostly ready 限定的な確認または軽微な修正後に実装できる
Partially ready 一部は実装できるが、重要な仕様が未解決である
Not ready 重要な仕様不足または矛盾があり、実装を開始すべきでない
Cannot assess 計画または関連資料が不足し、準備状況を判定できない
Not applicable 当該次工程が今回のタスクに該当しない

計画の一部だけがReadyの場合は、実装してよい範囲と保留する範囲を分けて記録します。

AIによる仮定リスク

特に次の項目をAIに推測させないようにします。

  • 対象集団と除外条件
  • 評価項目の元変数と導出
  • 時間原点、イベント、打ち切り
  • 欠測処理
  • モデル式と調整変数
  • 基準カテゴリと比較方向
  • サブグループ定義
  • 表の分母と出力形式

AIが候補を提案する場合は、計画上の事実と区別し、ユーザーの承認が必要な提案として記録します。

判定規則と根拠要件

実装可能性は、少なくとも次の三条件で評価します。

  1. 一意性：同じ仕様を別の実装者が読んでも、主要な抽出条件、導出、モデル、出力が一致する
  2. 追跡可能性：計画上の各仕様を、解析目的、変数定義または出力要求へ対応付けられる
  3. 実行可能性：必要な入力、処理順序、パッケージ制約、保存先が識別されている

各ドメインにはOK、Needs clarification、Problem、Cannot assess、Not applicableを使用します。CriticalまたはMajorのIssueがある場合、そのIssueに依存するR実装をReadyとして扱いません。

Evidenceには、計画の節名、表番号、変数名、式、モック表番号、ユーザー決定、参照したCONTEXT QCのIssue IDを記録します。外部知識や一般的慣行だけを、研究固有の仕様の根拠には使用しません。

出力ファイル 

ai_project/qc/plan-qc-001.md

再レビューではplan-qc-002.mdのように番号を増やし、以前のレポートを残します。

出力スキーマ

標準レポートは、Skill information、Overall judgment、Readiness by next step、Materials reviewed、Domain assessment、Issues、Cannot-assess items、AI assumption risks、Required clarification questions、Recommended next actions、Quick assessment、Handoffの12セクションで構成します。

Issues表にはID、Severity、Issue、Evidence、Recommended actionを含めます。実装可能性を妨げるIssueには、影響を受ける処理または出力を明記します。

判定例

Readyの例 

Endpoint and variable clarity: OK
Evidence: plan.md「3.2 Primary outcome」、definition.csvのSBP_BLとSBP_W12
Assessment: 主要評価項目はSBP_W12 - SBP_BL。単位はmmHg。欠測時は導出しない。
R implementation readiness: Ready

Not readyの例 

Method clarity: Problem
Issue: 「群間比較を行う」とだけ記載され、効果指標、モデル、調整変数が未指定。
Severity: Major
Impact: モデル式と主要推定値を一意に実装できない。
R implementation readiness: Not ready

確認範囲

PLAN QCは、計画の明確性とR実装可能性を確認します。統計手法が研究目的に対して最適であること、コードや計算結果が正しいこと、科学的結論が妥当であることを保証するものではありません。