1 ivdtools包总体介绍

ivdtools 是面向体外诊断（in vitro diagnostic，IVD）试剂评价的 R 统计工具包，提供从数据检查、统计分析到结果汇总和可视化的一组可复现工作流。包覆盖方法学比较、ROC、定性一致性、精密度、线性、干扰、稀释与加标、C5/C95、测量不确定度、互换性、参考物质偏倚、参考区间、稳定性、质量控制、曲线拟合、分析灵敏度、异常值和正态性评估以及样本量计算。统计结果应结合预先制定的研究方案、适用标准、实验室要求和临床或分析允许限进行解释。

1.1 功能模块

模块	主要入口	主要功能
方法学比较	`mcr()`	描述统计、相关、回归、Bland–Altman、偏倚和异常值
互换性	`commutability()`	EP14、 EP30 和 IFCC 互换性评价
ROC	`roc()`	ROC 曲线、cutoff、多变量 Logistic 回归和预测
定性分析	`raw_to_table()`、 `counts_to_table()`	四格表、诊断准确性指标、Kappa 一致性和 McNemar 检验
精密度	`precision()`	方差分量、置信区间、异常值、正态性和 Sadler 精密度剖面
线性	`linearity()`、`linearity_*()`	试验设计、HIGH/LOW 配制、直线/多项式分析、权重、ADL 与区间
干扰	`interference_*()`	重复数、配对试验、剂量响应和患者样本比较
稀释与加标	`dilution_recovery()`、 `spike_recovery()`、 `hook_effect()`	稀释回收、加标回收和高剂量钩状效应
C5/C95	`c5_c95()`	连续测量值的定性试剂 C5/C95 估计
测量不确定度	`uncertainty_*()`	Type A/B、IQC、偏倚、均匀性、稳定性、合成与传播
参考物质偏倚	`reference_bias()`	偏倚、测量均值不确定度与参考物质不确定度合成区间
参考区间	`reference_interval()`	EP28 非参数、biweight、type 6、参数和 Huber 参考区间
瓶/批 ANOVA	`bottle_anova()`	单因素或嵌套 ANOVA、Tukey HSD 和紧凑字母标记
稳定性	`stability_bias()`、 `stability_regression()`	偏倚、稳定性回归、超限时间、稳定性方案、MKT 和 Arrhenius 模型
质量控制	`qc_chart()`、`youden_plot()`	Levey–Jennings 图、Westgard 规则和 Youden 图
校准与响应曲线	`fit_equation()`	线性校准、指数、4PLC、5PLC 等响应方程的加权、约束拟合和模型比较；不用于方法学线性评价
分析灵敏度	`sensitivity_lob()` / `sensitivity_lod()` / `sensitivity_loq()`	空白限、检出限、定量限建立与验证
异常值与分布	`outliers_test()`、`normal_test()`	Grubbs、ESD、Dixon、IQR 及多种正态性检验
样本量	`sample_size_*()`	Bland–Altman 一致性、单比例置信区间和单臂目标值检验

1.2 设计特点

1.2.1 常规工作流

独立接口一次完成一个任务，绝大部分分析采用此设计，示例：

代码

normal_test(dat, col = "candidate")
reference_interval(dat, col = "candidate")

1.2.2 渐进式工作流

方法比较、ROC、定性分析和精密度等模块采用 S3 对象组织分析过程：

%%{init: {"theme":"base","themeVariables":{"primaryColor":"#EAF2FB","primaryBorderColor":"#2780E3","primaryTextColor":"#212529","lineColor":"#6C757D","secondaryColor":"#EAF7E6","tertiaryColor":"#FFF4E8","fontSize":"13px"},"flowchart":{"nodeSpacing":18,"rankSpacing":24,"padding":6}}}%%

flowchart LR
    A["原始数据"] --> B["构造函数<br/>建立分析对象"]
    B --> C["分析方法<br/>累积统计结果"]
    C --> D["更新后的对象"]
    D --> E["summary()"]
    D --> F["plot()"]
    D --> G["predict()<br/>支持的模块"]

    classDef input fill:#EAF2FB,stroke:#2780E3,color:#212529
    classDef process fill:#EAF7E6,stroke:#3FB618,color:#212529
    classDef output fill:#F4EEFB,stroke:#9954BB,color:#212529
    class A input
    class B,C process
    class D,E,F,G output

渐进式接口必须重新赋值：

代码

obj <- analysis_method(obj)

如果只调用 analysis_method(obj) 而没有执行 obj <-，新结果不会累积到原对象中。

1.3 快速开始

以下代码仅用于分析过程演示。

1.3.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")

1.3.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, curves = "all", cutpoint = "Youden")

1.3.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)

1.3.4 瓶间差异

代码

ba <- bottle_anova(
  ivd_bottle_example,
  value ~ bottle
)
print(ba)

posthoc <- tukey(ba)
print(posthoc)

1.4 依赖

ivdtools 主要依赖 ggplot2、ggrepel、VCA、VFP、minpack.lm、 nloptr、nls2、nortest、rlang 和 ppwdeming。