代码
normal_test(dat, col = "candidate")
reference_interval(dat, col = "candidate")1 ivdtools包总体介绍
1.1 包定位
ivdtools 是面向体外诊断（in vitro diagnostic，IVD）试剂评价的 R 统计工具包，提供从数据检查、统计分析到结果汇总和可视化的一组可复现工作流。 当前版本为 0.1.1，要求 R >= 4.1.0，采用 MIT 许可证。
包覆盖方法比较、ROC、定性一致性、精密度、参考区间、稳定性、质量控制、 曲线拟合、分析灵敏度、异常值和正态性评估以及样本量计算。统计结果应结合预先制定的研究方案、 适用标准、实验室要求和临床或分析允许限进行解释，不能替代专业判断。
1.2 设计特点
1.2.1 常规工作流
独立接口一次完成一个任务，例如：
1.2.2 渐进式工作流
方法比较、ROC、定性分析和精密度等模块采用 S3 对象组织分析过程：
- 构造函数创建分析对象并保存原始数据和元数据；
- 分析方法接收该对象，计算结果后返回更新后的对象；
summary()汇总已经完成的分析；plot()根据对象中已有的结果绘图；predict()在支持的模块中完成预测。
数据 -> 构造函数 -> 分析方法 -> 更新后的对象 -> 汇总/绘图/预测渐进式接口必须重新赋值：
代码
obj <- analysis_method(obj)如果只调用 analysis_method(obj) 而没有执行 obj <-，新结果不会累积到原对象中。
1.3 功能模块
| 模块 | 主要入口 | 主要功能 |
|---|---|---|
| 方法比较 | mcr() |
描述统计、相关、OLS/WLS、Deming、加权 Deming、Passing–Bablok、Bland–Altman、偏倚和异常值分析 |
| ROC | roc() |
ROC 曲线、AUC、最佳截断值、多变量 Logistic 回归和预测 |
| 定性分析 | raw_to_table()、counts_to_table() |
四格表、诊断准确性指标、Kappa 一致性和 McNemar 检验 |
| 精密度 | precision() |
方差分量、置信区间、异常值、正态性和 Sadler 精密度剖面 |
| 参考区间 | reference_interval() |
百分位数法、参数法和稳健法参考区间 |
| 瓶/批 ANOVA | bottle_anova() |
单因素或嵌套 ANOVA、Tukey HSD 和紧凑字母标记 |
| 稳定性 | stability_bias()、stability_regression() |
偏倚、稳定性回归、超限时间、稳定性方案、MKT 和 Arrhenius 模型 |
| 质量控制 | qc_chart()、youden_plot() |
Levey–Jennings 图、Westgard 规则和 Youden 图 |
| 曲线拟合 | fit_equation() |
线性、指数、4PLC、5PLC 等方程拟合、加权/约束拟合和模型比较 |
| 分析灵敏度 | lob_lod_loq() |
空白限、检出限、定量限建立 |
| 异常值与分布 | outliers_test()、normal_test() |
Grubbs、ESD、Dixon、IQR 及多种正态性检验 |
| 样本量 | sample_size_*() |
Bland–Altman 一致性、单比例置信区间和单臂目标值检验 |
1.4 快速开始
以下代码使用包内置的确定性示例数据。安装和载入方法见 《分析环境安装与使用》。
1.4.1 方法比较
代码
library(ivdtools)
mc <- mcr(
ivd_mcr_example,
id = "sid",
candidate = "test",
reference = "ref"
)
mc <- describe(mc)
mc <- correlation(mc, method = "pearson")
mc <- regression(mc, method = "deming")
mc <- bland_altman(mc, type = "difference")
summary(mc)
plot(mc, type = "regression")
plot(mc, type = "bland_altman")回归方法可选 OLS、WLS、Deming、加权 Deming 和 Passing-Bablok。 具体方法、权重、置信水平和异常值处理策略应在分析前确定。
1.4.2 ROC
代码
ro <- roc(
ivd_roc_example,
cols = c("x1", "x2"),
reference = "ref",
positive = 1
)
ro <- describe(ro)
ro <- auc(ro)
ro <- cutoff(ro)
ro <- mlr(ro, cols = c("x1", "x2"), name = "combined")
summary(ro)
plot(ro, mlr = "all", cutpoint = "Youden")参考变量必须是二分类变量。若原始参考结果为连续变量，应先使用 continuous_to_binary()，并明确记录阈值和阳性方向。
1.4.3 定性一致性
代码
qa <- raw_to_table(
ivd_qualitative_example,
candidate = "new",
reference = "gold",
id = "id",
positive = "positive"
)
qa <- describe(qa)
qa <- diagnostics(qa)
qa <- kappa(qa)
qa <- mcnemar(qa)
summary(qa)已有 TP、FP、TN、FN 计数时，也可以使用 counts_to_table() 创建对象。
1.4.4 参考区间
代码
set.seed(20260806)
ri_data <- data.frame(value = rnorm(160, mean = 100, sd = 15))
ri <- reference_interval(
ri_data,
col = "value",
method = "all"
)
print(ri)
plot(ri)应根据样本来源、样本量、分布特征和研究方案选择百分位数法、参数法或稳健法。
1.4.5 瓶/批 ANOVA
代码
ba <- bottle_anova(ivd_bottle_example, value ~ bottle)
print(ba)
posthoc <- tukey(ba)
print(posthoc)1.4.6 独立工具
代码
# 异常值和正态性
outliers_test(ri_data, "value", method = "grubbs")
normal_test(ri_data, "value", method = "shapiro")
# 查看可用拟合方程和 Westgard 规则
list_equation()
list_westgard()
# 样本量/效能
sample_size_bland_altman(
power = 0.80,
mu = 0.2,
sd = 1,
delta = 2.5
)1.4.7 获取帮助
查看函数介绍：
代码
help(mcr,"ivdtools")查看帮助文档，浏览特定主题文件。
代码
vignette("ivdtools")查看/下载完整函数手册和帮助文档可访问项目主页。
1.5 AI自动分析
ivdtools R 包提供统计函数，ivdtools-analysis Skill 则面向 AI 提供一套受约束的 自动分析工作流。用户给出数据文件、研究设计和分析要求后，Skill 以 ivdtools 为统计 引擎，组织数据预检、参数确认、统计分析、结果核验和中文报告生成。
在对话中使用 Skill 的价值不是“替代统计判断”，而是把重复的技术步骤标准化，并将数据 来源、分析参数、排除记录、警告、结果表、图形和软件环境一起保存，降低遗漏和手工复制 错误的风险。
ivdtools-analysis没有随ivdtools安装，可从项目主页获取。
1.6 依赖
ivdtools 主要依赖 ggplot2、ggrepel、VCA、VFP、minpack.lm、 nloptr、nls2、nortest 和 rlang。
1.7 使用边界
- 软件输出不自动构成合格判定；接受标准应在分析前确定。
- 用于受监管场景前，应完成适用的软件确认、流程验证和结果复核。