代码
library(ivdtools)11 样本量计算
11.1 分析目的
样本量计算在研究设计与性能评价方案阶段确定所需样本数或可获得的检验效能。ivdtools 提供三个 独立函数，分别对应三类常见问题：
sample_size_bland_altman()：Bland–Altman 一致性评价的样本量/效能（Lu 等 2016）；sample_size_proportion_ci()：单比例置信区间达到指定半宽所需样本量；sample_size_proportion()：单臂目标值检验（单样本比例对已知目标）的样本量/效能/显著性。
三个函数都由参数驱动、不需要原始数据文件。它们返回带属性的标量，print() 给出友好解释， as.numeric() 取出数值结果。示例中的参数（效能、置信水平、允许半宽等）均为教学设定，正式研究 必须使用方案规定的参数。
11.2 函数概述
| 函数 | 主要用途 | 求解方向 |
|---|---|---|
sample_size_bland_altman() |
BA 一致性评价 | 由 power 求 n，或由 n 求 power |
sample_size_proportion_ci() |
单比例置信区间 | 由 d 求 n，或由 n 求 d |
sample_size_proportion() |
单臂目标值检验 | 任意两个给定 n/alpha/power 求第三个 |
11.3 示例一：Bland–Altman 一致性评价的样本量
11.3.1 由目标效能求样本量
代码
n_ba <- sample_size_bland_altman(
power = 0.80,
mu = 0.2,
sd = 1,
delta = 2.5
)
print(n_ba)Sample size for Bland-Altman agreement assessment
Mode : Compute n from power
Mean difference : 0.2000
SD of differences: 1.0000
Clinical limit : 2.5000
Confidence level : 0.9500
Agreement level : 0.9500
Sample size (n) : 201
Power : 0.800300代码
as.numeric(n_ba)[1] 201在平均差异 mu = 0.2、差异 SD sd = 1、临床一致性限 delta = 2.5 的设定下，达到 80% 效能 约需 201 对样本。
参数说明：
mu为平均差异，sd为差异标准差（>0），delta为临床可接受的一致性限（>0）。conf.level是一致性限置信区间的置信水平，agree.level是 LoA 的覆盖度，两者是不同层次—— 前者影响估计的可靠性，后者决定 LoA 本身的宽度。
11.3.2 由样本量求效能
给定已有样本量，反查能达到的效能：
代码
sample_size_bland_altman(n = 201, mu = 0.2, sd = 1, delta = 2.5)Sample size for Bland-Altman agreement assessment
Mode : Compute power from n
Mean difference : 0.2000
SD of differences: 1.0000
Clinical limit : 2.5000
Confidence level : 0.9500
Agreement level : 0.9500
Sample size (n) : 201
Power : 0.800300与上面互为验证，n=201 恰好对应效能 0.80。
11.4 示例二：单比例置信区间的样本量
11.4.1 由目标半宽求样本量
代码
n_pci <- sample_size_proportion_ci(p = 0.3, d = 0.05)
print(n_pci)Single proportion confidence interval
Mode : Compute n from p and d
Method : wilson
Target proportion: 0.3000
Confidence level : 0.9500
Sample size (n) : 320
Half-width (d) : 0.050000对预期比例 p = 0.3，要使 95% 置信区间半宽不超过 0.05，约需 320 例。
11.4.2 由样本量求半宽
代码
sample_size_proportion_ci(p = 0.3, n = 320)Single proportion confidence interval
Mode : Compute d from p and n
Method : wilson
Target proportion: 0.3000
Confidence level : 0.9500
Sample size (n) : 320
Half-width (d) : 0.049967n=320 时半宽约为 0.05，与上面互为验证。
参数说明：
p为预期比例（必须给定，0<p<1），d为期望半宽（0<d≤0.5）。method可选 7 种置信区间方法（默认"wilson"，另有"wald"、"wald-cc"、"agresti-coull"、"jeffreys"、"wilson-cc"、"clopper-pearson"），方法选择影响所需样本量，应在方案中说明。
11.5 示例三：单臂目标值检验的样本量
11.5.1 求样本量
代码
n_sp <- sample_size_proportion(
p0 = 0.2,
p1 = 0.35,
alpha = 0.05,
power = 0.8,
alternative = "greater",
method = "wilson"
)
print(n_sp)Sample size for a single-arm target value test
Mode : Compute n from alpha and power
Method : wilson
H0: p <= 0.2000
H1: p > 0.2000
Expected p : 0.3500
Sample size (n) : 47
Alpha : 0.050000
Power : 0.815687
Critical x : 14在 p0 = 0.2（目标/零假设比例）与 p1 = 0.35（预期比例）、单侧 α = 0.05、效能 0.80 的设定下， 约需 47 例。
参数说明：
alternative可取"greater"（此时要求 p1 > p0）、"less"或"two.sided"。 该方法基于置信区间反演：给定n/alpha/power中任意两个求第三个；三个都给出时作为一致性校验。
11.5.2 求效能
代码
sample_size_proportion(
p0 = 0.2,
p1 = 0.35,
n = 47,
alpha = 0.05,
alternative = "greater"
)Sample size for a single-arm target value test
Mode : Compute power from n and alpha
Method : wilson
H0: p <= 0.2000
H1: p > 0.2000
Expected p : 0.3500
Sample size (n) : 47
Alpha : 0.050000
Power : 0.815687
Critical x : 1411.5.3 求显著性水平（alpha）
代码
sample_size_proportion(
p0 = 0.2,
p1 = 0.35,
n = 47,
power = 0.8,
alternative = "greater"
)Sample size for a single-arm target value test
Mode : Compute alpha from n and power
Method : wilson
H0: p <= 0.2000
H1: p > 0.2000
Expected p : 0.3500
Sample size (n) : 47
Alpha : 0.046728
Power : 0.815687
Critical x : 14三种求解方向互相印证，结果一致（n=47、power=0.8、alpha≈0.05）。
11.6 结果判读要点
- 参数先行：样本量计算前确定效能、置信水平、允许误差/半宽、预期比例与单双侧方向。
- 结果是有条件的：样本量只在所设参数成立时有效，参数估计不准会导致样本量不准。
- 方法一致：比例类问题应提前确定 CI 方法（Wilson 等），不能事后挑选。
- 方向约束：单臂检验注意
alternative与 p0/p1 大小关系的一致性。 - 方案留档：把参数、函数调用与输出一并写入研究方案，便于复核与更新。