statistical-power

用途

统计功效与样本量分析用于研究规划阶段回答两个核心问题：需要多大样本才能可靠检测到给定大小的效应；以及在可负担的样本量下能检测到多大效应。样本量、效应量、显著性水平（α）与功效（1 − β）四个量相互锁定，固定其中三个即可确定第四个，本技能的所有计算都是这一关系的重新排列。

主要能力

闭式公式计算：覆盖两独立均值 t 检验、配对/单样本均值检验、单因素方差分析、两比例、单比例、相关、卡方（拟合优度/列联表，通过效应量 w）、线性回归（R² 增量 / f²）等标准检验。
模拟/蒙特卡洛功效：适用于逻辑/泊松回归、混合效应/重复测量模型、整群随机试验、生存分析、中介、多向交互等无教科书公式的设计。
效应量选择与转换：提供 d、f、r、η²、优势比、Cohen's h/w 之间的基准与换算指导。
校正处理：多重比较、脱落/失访、聚类（设计效应）等常被忽略的调整。
敏感性分析与功效曲线：跨合理效应量范围重算，输出功效 vs n 或功效 vs 效应量的曲线。

使用方式

安装（使用 uv，生产环境建议固定版本）：

uv pip install "statsmodels>=0.14.6" "scipy>=1.11" "pingouin>=0.6" "numpy>=1.26" matplotlib pandas
# 高级模型的模拟功效（可选，按需添加）：
uv pip install lifelines            # 生存分析
# 混合模型与 GLM 随 statsmodels 提供

兼容性说明：使用 statsmodels>=0.14.6 搭配 scipy>=1.11，以避免 SciPy 1.16+ 上的 _lazywhere 导入错误。Pingouin 0.5+ 重命名了功效函数参数以匹配下文名称。

闭式公式快速示例（scripts/power.py 将 statsmodels 封装为统一接口）：

from power import sample_size, power, mde, power_curve

# 1. 检测 Cohen's d = 0.5，双侧，80% 功效，每组需要多少样本？
sample_size(test="t_ind", effect_size=0.5, power=0.80, alpha=0.05)

# 2. 两组，3:1 分配
sample_size(test="t_ind", effect_size=0.5, power=0.80, ratio=3.0)

# 3. 固定每组 n=30，80% 功效下的最小可检测 d？
mde(test="t_ind", nobs1=30, power=0.80, alpha=0.05)

# 4. 单因素方差分析，4 组，检测 Cohen's f = 0.25
sample_size(test="anova", effect_size=0.25, k_groups=4, power=0.80)

# 5. 两比例：0.40 vs 0.55（自动转换为 Cohen's h）
sample_size(test="two_proportions", prop1=0.40, prop2=0.55, power=0.80)

# 6. 相关：检测 r = 0.30
sample_size(test="correlation", effect_size=0.30, power=0.80)

# 7. 用于基金申请图表的功效曲线
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。

模拟路径（scripts/simulate_power.py 提供可复用框架与示例）：

from simulate_power import simulate_power

def gen_and_test(n, rng):
    # 在假定效应下构建大小为 n 的数据集，运行计划中的检验，
    # 若结果显著则返回 True
    ...

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})")

模拟逻辑固定为三步：从假定真值模拟数据集；用计划在真实数据上使用的同一检验/模型分析；重复多次（≥1,000 次；接近 80% 时用 5,000–10,000 次以获得稳定估计）。功效即显著重复所占比例。应报告蒙特卡洛置信区间。

适用场景

收集数据前确定所需样本量（先验功效分析）。
在固定样本量下求最小可检测效应（MDE）。
为基金申请或研究方案生成功效曲线。
为 IRB 提交、基金申请或预注册论证样本量。
不等组样本量或非 1:1 分配的设计。
无教科书公式的设计（混合模型、逻辑/泊松回归、整群随机试验、生存分析、中介、交互）通过模拟计算。
在样本量估计中考虑多重比较、脱落或聚类。

限制与注意事项

功效计算的可信度取决于所输入的效应量，不应凭空编造数字。优先使用最小重要效应（SESOI），其次为收缩后的预试验/既往研究估计，最后才用 Cohen 惯例值并明确说明。
应避免事后（“观测”）功效：由刚估计出的效应量计算功效是循环论证，是 p 值的确定性函数，不提供新信息；应报告敏感性分析（在已实现 n 下的 MDE）或观测效应的置信区间。
常被遗忘的校正：多重比较（按校正后 α 计算功效）、脱落/失访（n_enroll = ceil(n_analyzed / (1 − dropout_rate))）、聚类（设计效应 DEFF = 1 + (m − 1)·ICC）、单侧 vs 双侧、不等分配。
常见错误：编造效应量或照搬膨胀的预试验估计；只报告单一 n 而非敏感性范围；忽略聚类（伪重复）；忘记脱落；混淆 α 与功效或单侧与双侧；只对主要终点计算功效；对实际不会拟合的模型使用 t 检验公式。
报告应包含全部输入以便复现，模拟还需说明数据生成假设、模拟次数与蒙特卡洛置信区间。
版本相关细节可能过时，应以所安装版本的官方文档为准；不得编造 API。

关键参考文献

Cohen, J. (1988). Statistical Power Analysis for the Behavioral Sciences (2nd ed.). Lakens, D. (2022). Sample Size Justification. Collabra: Psychology, 8(1). Arnold, B. F. et al. (2011). Simulation methods to estimate design power. BMC Medical Research Methodology, 11:94.

技能介绍

用途