power-analysis

検出力分析ループ

2群比較のための検出力分析と事前登録のループです。成果物は研究の統計計画です。フィードバック信号は2つあり、計画した検定のモンテカルロシミュレーションで推定する統計的検出力と、妥当性上の欠陥の数です。各反復では検出力をシミュレーションし、目標に達するサンプルサイズを算出し、設計に欠陥がないか監査して改訂します。検出力が目標を上回り、かつ欠陥の一覧が空になるまで繰り返します。成果物は、サンプルサイズの根拠に加え、データを見る前に仮説、主要アウトカム、分析、サンプルサイズ、停止ルールを確定する事前登録です。

対象範囲と制限

このループで行うのは、（1）シミュレーションによって2群比較の検出力と必要なサンプルサイズを算出すること、（2）設計に対して固定の妥当性チェックリストを実行すること、（3）****事前登録を作成することの3つだけです。付属の検出力モデル（tools/power_sim.py）が対応しているのは、2標本の平均（連続アウトカム）検定と2標本の比率（二値アウトカム）検定のみです。

これは汎用的な実験設計ツールではありません。要因計画、反復測定、クラスター化／マルチレベル、時系列、適応型、生存時間分析の各設計には対応していません。また、ドメイン知識に基づいてアウトカム指標や操作を選ぶことも、すでに収集済みのデータを分析することもありません。これらの場合、ここで示す検出力の数値は適用できません。設計に適した検出力分析の方法を使用してください。研究が単純な2群比較ではない場合は、その旨を伝えて停止し、計画した分析に合わない検出力を報告しないでください。

使用する場面

主要アウトカムが連続値の平均または二値の割合である、1つの2群比較について、サンプルサイズを決定し事前登録する際に使用します。ユーザーが示した関心のある最小効果を検出できるよう設計するのがデフォルトです。その効果がわからない場合は、楽観的な推測に頼るのではなく、ベースラインと意味のある最小差から設定できるよう支援してください。実際より大きな効果を前提に「検出力あり」とする設計は、実態を反映しません。研究が2群比較でない場合は、停止して設計に適した方法を案内してください。

セットアップ

バインディングは対話形式で確定します。作業ディレクトリに loop.run.yaml が存在する場合は読み込み、値を1行で確認してからループに進みます。存在しない場合は、Claude Code（AskUserQuestion ツールが利用可能）では各バインディングの妥当な値を推測し、推奨候補として提示します。それ以外のホストでは、各項目について引用符付きのプレーンテキストの質問をします。その後、loop.run.yaml（形式：examples/run.example.yaml）を書き込み、ほかのファイルを作成する前に値を確認します。

バインディング	意味	デフォルト	推測方法
<hypothesis>	実験で検証する主張	—	ユーザーに尋ねる
<outcome>	主要アウトカムの種類と関心のある最小効果：連続値（baseline_mean、sd、min_effect）または二値（baseline_rate、min_lift）	—	ユーザーに尋ねる。この値によって検出力を計算する効果量が決まる
<target_power>	設計が満たすべき検出力	0.80	—
<alpha>	有意水準	0.05	—
<power_cmd>	付属シミュレーターの呼び出し方	python3 <skill_dir>/tools/power_sim.py --design <two-sample-mean|two-proportion> --effect <e> [--sd <sd> | --baseline <p0>] --alpha <alpha> --n <n_per_group>	—
<design_doc>	設計書と事前登録の出力ファイル	<sandbox_root>/design.md	—
<sandbox_root>	設計書と記録を保存する場所	./sandbox	—
<budget>	最大反復回数	8	—

<power_cmd> は {"power", "n_per_group", ...} という1つのJSONオブジェクトを出力します。検出力は必ずこれを実行して求めてください。手計算で検出力を推定してはいけません。

反復

このチェックリストをコピーして、項目にチェックを入れてください。

• 反復 0 — <design_doc> に設計案を作成します。最終決定事項はまだ記録しません。
• 検出力をシミュレーションします。現在の n と想定される効果を使って、<power_cmd> を実行します。
• N を求める：検出力が <target_power> 未満の場合は、目標を超えるまで、より大きい n で再実行します（段階的に増やしてから二分探索します）。
• 妥当性を監査します。以下のチェックリストにあるすべての欠陥を列挙します。
• 修正します。最優先の欠陥を修正し、n を検出力の要件を満たす値に設定して、<design_doc>（＋事前登録セクション）を更新します。
• 台帳の行を追加します。検出力が目標を超え、かつ欠陥が残っていない場合、または <budget> に達した場合に停止します。

反復 0 — 作成。 <design_doc> に最初の設計案を記述します。群／条件、分析単位と単位の割り当て方法、主要アウトカムと予定している検定の詳細、想定効果量（<outcome> に基づく）、および最初のサンプルサイズの見積もりを含めます。まだ最終決定事項は記録しません。

停止条件を満たすまで（検出力の達成＋欠陥なし、または予算到達）：

1. 検出力をシミュレーションします。 現在の群あたりの n と想定効果を使い、予定している検定に合致する --design を指定して <power_cmd> を実行します。達成した検出力を記録します。
2. N を求めます。 power < <target_power> の場合は、より大きい n（例：2 倍）でシミュレーションを再実行し、次に二分探索して、検出力が目標を超えるまで続け、その n を採用します。
3. 妥当性を監査します。 設計をチェックリストに照らして確認し、見つかったすべての欠陥を列挙します。
   • 交絡／対照なし — 同時期の対照群がありますか。それとも、他の点でも異なる過去のデータ／別の情報源を基準とした比較ですか。
   • ランダム化 — 単位はランダムに割り当てられていますか。そうでない場合、選択バイアスによって効果の推定が脅かされます。
   • 選択／サンプリング — サンプルは、主張の対象となる母集団を代表していますか。
   • 多重比較 — 補正なしに複数のアウトカム／サブグループを検定していませんか。
   • 任意停止／のぞき見 — 事前に停止ルールを定めていますか。それとも、有意になるまで分析を繰り返しますか。
   • アウトカムと分析の事前指定 — 主要アウトカムと予定している単一の検定は、事前に固定されていますか（データを見た後に選ぶのではなく）。
   • 測定 — アウトカムは信頼性のある方法で測定され、可能な場合は条件を知らされずに測定されていますか。
4. 修正します。 最優先の欠陥（または、同時期の対照群の追加と、その対照群への割り当てのランダム化のように、個別には修正できない密接に関連する欠陥の組み合わせ）を修正し、n を検出力の要件を満たす値に設定します。事前登録セクションを含めて <design_doc> を更新します。このセクションには、仮説、主要アウトカム、予定している唯一の分析、サンプルサイズとその算出方法、ランダム化の方法、停止ルールを記載します。
5. 記録として台帳に 1 行追加し、続行します。

power ≥ <target_power> かつ欠陥リストが空になったとき、または <budget> に達したときに停止します。最終的な設計と事前登録、達成した検出力と必要な n を報告します。予算到達で停止する場合は、未解決の欠陥も報告します。

台帳

<sandbox_root>/ledger.tsv。タブ区切りとし、テキストにカンマは使用しません。ヘッダー：

iter	n_per_group	power	open_flaws	change

例：

iter	n_per_group	power	open_flaws	change
0	50	0.50	2	draft: volunteers vs last-year cohort, n=50
1	100	0.80	1	solved n for 80% power at d=0.4
2	100	0.80	0	randomized concurrent control; pre-specified single primary outcome + stopping rule

最良の反復を報告します。最終的な設計、達成した検出力と必要な n、および予算到達で停止した場合は未解決の欠陥を含めてください。

制約

• 検出力は、楽観的な効果ではなく、関心のある最小効果に基づいて計算します。現実より大きな効果を前提に検出力を設計すると、実際の効果を検出できないためです。また、シミュレーションの --design は、設計で指定した検定と一致している必要があります。tools/power_sim.py は編集しないでください。
• 検出力だけで設計が合格するわけではありません。十分な検出力があっても、交絡がある設計やランダム化されていない設計は不合格です。検出力と欠陥の両方の基準を満たす必要があります。
• データを見る前に事前登録してください。これにより、結果を見た後に選んだ検定ではなく、確証的な検定にできます。分析、アウトカム、サンプルサイズ、停止ルールを事前に固定します。
• 検出力と判定の基準となるのは、主要アウトカム1つと事前に計画した検定1つです。副次的な分析には探索的であることを明記します。
• サンドボックスは自己完結しています。../ で外部に出ないでください。続行するかどうかを尋ねるためにループを中断しないでください。