statistical-power

统计功效与样本量

概述

功效分析回答了研究规划中最重要的问题之一：要多大的样本量，才能可靠地检测到给定大小的效应？而对于你能负担的样本量，又能检测到多大的效应？ 功效不足的研究会浪费资源，得出不确定或无法复现的结果；功效过高的研究则会浪费参与者和经费，而且（在临床研究中）让不必要的更多人承受风险。在收集数据之前做好这项工作，是项目中最具杠杆效应的统计决策。

对于任何给定的检验，以下四个量相互制约：样本量（n）、效应量、显著性水平（α）和功效（1 − β）。固定其中任意三个，第四个就随之确定。本技能中的所有计算都是对这一关系的不同变换。

本技能介绍进行功效分析的两种方法：

• 闭式公式（速度快，适用于标准检验时结果精确）——参见 references/closed_form_recipes.md。
• 模拟／蒙特卡洛（适用于任何可模拟并分析的设计或模型）——参见 references/simulation_based_power.md。

有关效应量的选择和转换（通常是最难的部分），请参见 references/effect_sizes.md。

何时使用本技能

• 在收集数据前确定所需样本量（先验功效分析）
• 针对固定且已确定的样本量，找出最小可检测效应（MDE）
• 为资助申请或研究方案绘制功效曲线（功效与 n 或效应量的关系）
• 为 IRB 申请、资助申请或预注册论证样本量
• 为组间样本量不等或非 1:1 分配的设计计算功效
• 通过模拟为任何没有教科书公式的设计计算功效（混合模型、逻辑回归／泊松回归、整群随机试验、生存分析、中介效应、交互效应）
• 在样本量估算中考虑多重比较、退出／脱落或整群效应

安装

使用 uv。生产环境中应固定版本；探索时可以不固定。

uv pip install "statsmodels>=0.14.6" "scipy>=1.11" "pingouin>=0.6" "numpy>=1.26" matplotlib pandas
# For simulation-based power of advanced models (optional, add as needed):
uv pip install lifelines            # survival
# mixed models and GLMs come with statsmodels

**兼容性说明：**使用 statsmodels>=0.14.6 和 scipy>=1.11，以避免 SciPy 1.16+ 中出现 _lazywhere 导入错误。Pingouin 0.5+ 已重命名功效函数的参数，使其与下文所用名称一致。

---

决定一切的关键选择：效应量

功效分析的可信度取决于输入的效应量。不要凭空编造数字。 大致按以下优先顺序选择：

1. 最小重要效应——实际会改变决策或在科学／临床上有意义的最小效应（即“最小感兴趣效应量”，SESOI）。这是最站得住脚的依据：你的目标是检测重要的效应，而不是期望看到的效应。
2. 试点研究或既往研究的估计值，但要适当缩小——已发表研究和试点研究中的效应会受到发表偏差和赢家诅咒的影响而被高估。直接依据未经调整的试点研究估计值计算功效，往往会导致正式研究的功效不足。
3. 经验惯例（Cohen 的小／中／大效应），仅在最后才采用，并明确说明。

无论选择哪种效应量，都要进行敏感性分析：报告在合理的效应量范围内，所需 n 如何变化，而不是只报告单个数值。只给出一个数字的功效分析掩盖了其最大的一个不确定性来源。效应量基准值以及 d、f、r、η²、优势比和 Cohen's h/w 之间的转换，请参见 references/effect_sizes.md。

避免事后（“观察到的”）功效。 根据刚刚估计的效应量计算功效是循环论证：它只是 p 值的确定性函数，不会提供新信息。如果研究已经完成，而你想知道它能检测到什么，应报告敏感性分析（在实际达到的 n 下的 MDE），或更好地报告观察到的效应的置信区间。这是审稿人常见的异议——即使有人要求，也不要在不指出问题的情况下给出观察到的功效。

---

快速计算方案（闭式解）

随附的 scripts/power.py 将 statsmodels 封装为统一的接口，这样你就不必记住每种检验对应哪个求解器。请在技能目录中运行，或将 scripts/ 添加到 sys.path。

from power import sample_size, power, mde, power_curve

# 1. How many per group to detect Cohen's d = 0.5, two-sided, 80% power?
sample_size(test="t_ind", effect_size=0.5, power=0.80, alpha=0.05)
# -> required n per group

# 2. Two groups, 3:1 allocation (e.g. more controls than cases)
sample_size(test="t_ind", effect_size=0.5, power=0.80, ratio=3.0)

# 3. Fixed n=30/group — what's the minimum detectable d at 80% power?
mde(test="t_ind", nobs1=30, power=0.80, alpha=0.05)

# 4. One-way ANOVA, 4 groups, detect Cohen's f = 0.25
sample_size(test="anova", effect_size=0.25, k_groups=4, power=0.80)

# 5. Two proportions: 0.40 vs 0.55 (auto-converts to Cohen's h)
sample_size(test="two_proportions", prop1=0.40, prop2=0.55, power=0.80)

# 6. Correlation: detect r = 0.30
sample_size(test="correlation", effect_size=0.30, power=0.80)

# 7. Power curve for the grant figure
power_curve(test="t_ind", effect_size=0.5, n_range=range(10, 120, 5),
            save="power_curve.png")

支持的 test= 值：t_ind（两个独立均值）、t_paired/t_one（配对或单样本均值）、anova（单因素）、two_proportions、one_proportion、correlation、chi2（拟合优度／列联分析，通过效应量 w 计算）、linear_regression（R² 增量／f²）。完整的参数表和底层 statsmodels 调用请参阅 references/closed_form_recipes.md。

---

没有公式时：模拟

闭式功效计算仅适用于少数简单检验。对于逻辑回归／Poisson 回归、混合效应／重复测量模型、整群随机试验、生存分析、中介分析、多因素交互，或任何非标准分析，模拟才是合适的工具。其逻辑始终分为以下三步：

1. 模拟：根据假设的真实情况生成数据集（包括你希望检测的效应，以及合理的噪声、基线率、整群结构等）。
2. 分析：使用你计划在真实数据上采用的确切检验／模型进行分析。
3. 重复：重复多次（≥1,000 次；若要在接近 80% 的功效时获得稳定估计，则重复 5,000–10,000 次）。功效即检验显著的重复样本所占比例。

scripts/simulate_power.py 提供了一个可重复使用的框架和实用示例（两组差异、逻辑回归、包含 ICC 的整群随机试验，以及线性混合模型）。核心代码如下：

from simulate_power import simulate_power

def gen_and_test(n, rng):
    # build a dataset of size n under the assumed effect, run the planned test,
    # return True if the result is significant
    ...

est = simulate_power(gen_and_test, n=200, n_sims=2000, alpha=0.05)
print(f"Power at n=200: {est.power:.3f} (95% CI {est.ci_low:.3f}-{est.ci_high:.3f})")

请报告估计值的 Monte Carlo 置信区间（框架会返回该区间），以便读者判断 0.81 和 0.79 的差异究竟是信号还是模拟噪声。完整模式请参阅 references/simulation_based_power.md，其中包括如何搜索达到目标功效所需的样本量 n，以及如何对脱落和整群进行建模。

---

人们常忘记的调整

这些因素经常决定一项研究的功效是否充足。请明确应用这些调整，并说明你已这样做。

• 多重比较。 如果分析使用 Bonferroni 式校正检验 m 个假设，则应按校正后的 α（例如 α/m）计算每项检验的功效，这会增加 n。更好的做法是直接通过模拟，针对家族错误率或 FDR 控制程序计算功效。忽略这一点会导致所有次要终点的功效在不知不觉中不足。
• 脱落／退出／样本不可用。 功效计算给出的是所需的已分析样本量 n。请增加入组样本量：n_enroll = ceil(n_analyzed / (1 − dropout_rate))。脱落率为 20% 时，入组人数需比公式计算结果多 25%。
• 整群（设计效应）。 当观察值呈嵌套结构（患者隶属于诊所、细胞隶属于动物、重复测量来自同一受试者）时，有效样本量小于原始计数。请根据设计效应进行扩增：DEFF = 1 + (m − 1)·ICC，其中 m 为整群大小，ICC 为组内相关系数。将整群数据视为独立数据属于伪重复，会严重高估功效——对于整群随机设计，请改用模拟。
• 单侧检验与双侧检验。 默认采用双侧检验，这几乎总是正确的选择；单侧检验只有在拒绝检测意外方向的效应时，才能提高功效。请说明采用任何单侧检验的理由。
• 分配不均。 固定总 n 时，组间等量分配效率最高。如果设计固定了分配比例（例如治疗组与对照组为 2:1），请传入 ratio=，使计算反映这一比例。

---

工作流

1. 说明设计和计划进行的分析。 你将运行的检验决定了功效计算方法。如果分析采用混合模型或 GLM，请直接使用模拟。
2. 选择效应量，并说明其合理依据（SESOI > 经收缩的先导研究估计 > 惯例）。
3. 设定 α 和目标功效。 常用默认值为 α = 0.05（双侧）和功效 = 0.80；确证性研究或临床研究中常用 0.90。请明确说明。
4. 使用 scripts/power.py（闭式计算）或 scripts/simulate_power.py（模拟）进行计算。
5. 敏感性分析。 在一系列合理的效应量范围内重新计算，并绘制功效曲线。这才是需要交付的内容，而不是单个数字。
6. 应用调整，考虑脱落、聚类和多重性。
7. 按照以下模板报告。

---

报告模板

一份合理的功效说明应包含所有输入，以便读者能够复现。请按需修改：

A priori power analysis was conducted to determine the sample size needed to detect
a [between-group difference of Cohen's d = 0.50], which we considered the smallest
effect of clinical interest. With α = .05 (two-sided) and power = .80, a two-sample
t-test requires n = 64 per group (128 total; computed with statsmodels 0.14).
Allowing for 20% attrition, we will enrol 160 participants. A sensitivity analysis
showed required n ranges from 45 to 105 per group across plausible effects
d = 0.40–0.60 (Figure X).

对于模拟：还要说明数据生成假设（基线率、残差 SD、ICC、聚类大小）、模拟次数和蒙特卡洛 CI。

---

常见问题

1. 臆造效应量或照搬偏大的先导研究估计——这是功效分析出错最常见的原因。
2. 只报告单个 n，而不提供敏感性范围或功效曲线。
3. 事后功效／观测功效——这是循环论证且没有信息价值；应改用敏感性分析或效应量 CI。
4. 忽略聚类（伪重复）——把细胞／测量值当作彼此独立的受试者来计数。
5. 忘记考虑脱落——按实际分析的 n 计算功效，却仍招募相同数量。
6. 混淆 α 和功效，或混淆单侧检验和双侧检验。
7. 只针对主要终点计算功效，却报告需要大得多的 n 才能检验的次要终点／交互作用。
8. 使用与你实际拟合的模型不匹配的 t 检验公式（例如，用基于均值的计算来规划逻辑回归）——功效计算方法应与计划采用的分析相匹配。

---

资源

脚本

• scripts/power.py — 统一的闭式计算接口（sample_size、power、mde、power_curve），基于 statsmodels/pingouin，适用于所有标准检验。
• scripts/simulate_power.py — 蒙特卡洛功效计算工具，包含 simulate_power() 和 find_sample_size()，以及已完成的示例（双组、逻辑回归、整群随机、线性混合模型）。

参考资料

• references/closed_form_recipes.md — 各检验的参数表和精确的 statsmodels/pingouin 调用示例，包括比例、卡方和回归。
• references/simulation_based_power.md — GLM、混合模型、整群设计、生存分析和脱落的完整模拟模式。
• references/effect_sizes.md — 效应量的选择（SESOI）、Cohen 基准，以及 d、f、r、η²/f²、OR、h 和 w 之间的换算。

相关技能

• experimental-design — 确定 n 后，规划实际研究设计（随机化、区组、因子设计／DOE、交叉设计、序贯设计）。
• statistical-analysis — 数据收集后的假设检验、运行检验、效应量计算和 APA 报告。
• statsmodels / pymc — 拟合此处提及的模型。

关键参考文献

• Cohen，J.（1988）。Statistical Power Analysis for the Behavioral Sciences（第 2 版）。
• Lakens，D.（2022）。Sample Size Justification。Collabra: Psychology，8（1）。
• Arnold，B. F. 等（2011）。用于估计设计功效的模拟方法。BMC Medical Research Methodology，11:94。

Agent 操作流程

1. 检查环境。 明确研究目标、约束条件（预算、时间、伦理）以及用户需要做出的决策。
2. 确定输入。 根据数据或用户确认格式、标识符和参数。任何会影响结果的值都应询问用户，而不是猜测。
3. 先运行小规模版本。 在扩大范围前，先提出一份简短的候选方案清单，并明确说明假设。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 说明假设，按照明确的标准比较备选方案，统计计划则应包括统计功效和分析选项。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及还有哪些不确定之处。

如果发生以下情况	请执行以下操作
设计选择取决于未知的效应量或成本	提供乐观、预期和悲观情景，而不是只给出一个猜测值。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自身的文档（help()、--help、官方文档），进行调整，并告知用户。切勿虚构 API。
所需输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所采用的假设。

诚信原则

• 切勿伪造结果、参数、标识符、引文或统计数据。如果某项内容无法运行或验证，请如实说明。
• 将推测标记为推测；区分已确立的证据与新假设。
• 本文中与版本相关的细节可能已经过时：请对照已安装版本的官方文档进行确认。
• 对于需要花钱、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征得同意。