1  ivdtools Package Overview

1.1 Package Positioning

ivdtools is an R statistical toolkit for in vitro diagnostic (IVD) reagent evaluation, providing a set of reproducible workflows spanning data inspection, statistical analysis, and result summarization and visualization. The current version is 0.1.1, requires R >= 4.1.0, and is released under the MIT license.

The package covers method comparison, ROC, qualitative agreement, precision, reference intervals, stability, quality control, curve fitting, analytical sensitivity, outlier and normality assessment, and sample-size calculation. Statistical results should be interpreted in the context of a pre-specified study protocol, applicable standards, laboratory requirements, and clinical or analytical allowable limits, and cannot substitute for professional judgment.

1.2 Design Features

1.2.1 Standalone Workflows

Standalone interfaces complete one task at a time, for example:

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

1.2.2 Progressive Workflows

Modules such as method comparison, ROC, qualitative analysis, and precision organize the analysis process using S3 objects:

  1. A constructor function creates an analysis object and stores the raw data and metadata;
  2. An analysis method receives the object, computes results, and returns the updated object;
  3. summary() summarizes the analyses that have been completed;
  4. plot() produces plots from results already present in the object;
  5. predict() performs prediction in supported modules.
data -> constructor -> analysis method -> updated object -> summary/plot/predict

The progressive interface requires reassignment:

Code 
obj <- analysis_method(obj)

If you call only analysis_method(obj) without the obj <-, the new results will not accumulate into the original object.

1.3 Functional Modules

Module Main entry Key features
Method comparison mcr() Descriptive statistics, correlation, OLS/WLS, Deming, weighted Deming, Passing–Bablok, Bland–Altman, bias and outlier analysis
ROC roc() ROC curve, AUC, optimal cutoff, multivariate logistic regression and prediction
Qualitative analysis raw_to_table(), counts_to_table() Four-fold table, diagnostic accuracy metrics, Kappa agreement and McNemar test
Precision precision() Variance components, confidence intervals, outliers, normality and Sadler precision profile
Reference interval reference_interval() Percentile, parametric and robust reference intervals
Bottle/lot ANOVA bottle_anova() One-way or nested ANOVA, Tukey HSD and compact letter display
Stability stability_bias(), stability_regression() Bias, stability regression, time to exceed limit, stability plan, MKT and Arrhenius models
Quality control qc_chart(), youden_plot() Levey–Jennings chart, Westgard rules and Youden plot
Curve fitting fit_equation() Linear, exponential, 4PLC, 5PLC and other equation fits, weighted/constrained fits and model comparison
Analytical sensitivity lob_lod_loq() Limit of blank, limit of detection, limit of quantitation determination
Outliers and distribution outliers_test(), normal_test() Grubbs, ESD, Dixon, IQR and multiple normality tests
Sample size sample_size_*() Bland–Altman agreement, single-proportion confidence interval and one-arm target-value test

1.4 Quick Start

The following code uses the deterministic example data bundled with the package. See 《Installing and Using the Analysis Environment》 for installation and loading instructions.

1.4.1 Method Comparison

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

Regression methods include OLS, WLS, Deming, weighted Deming, and Passing-Bablok. The specific method, weights, confidence level, and outlier-handling strategy should be decided before analysis.

1.4.2 ROC

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

The reference variable must be binary. If the original reference result is continuous, first use continuous_to_binary(), and explicitly record the threshold and the positive direction.

1.4.3 Qualitative Agreement

Code 
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)

When TP, FP, TN, FN counts are already available, you can also create an object with counts_to_table().

1.4.4 Reference Interval

Code 
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)

The percentile, parametric, or robust method should be chosen based on sample source, sample size, distribution characteristics, and the study protocol.

1.4.5 Bottle/Lot ANOVA

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

posthoc <- tukey(ba)
print(posthoc)

1.4.6 Standalone Tools

Code 
# Outliers and normality
outliers_test(ri_data, "value", method = "grubbs")
normal_test(ri_data, "value", method = "shapiro")

# View available fit equations and Westgard rules
list_equation()
list_westgard()

# Sample size / power
sample_size_bland_altman(
  power = 0.80,
  mu = 0.2,
  sd = 1,
  delta = 2.5
)

1.4.7 Getting Help

View the function documentation:

Code 
help(mcr,"ivdtools")

View the help documentation and browse topic-specific files.

Code 
vignette("ivdtools")

Visit the project homepage to view/download the complete function manual and help documentation.

1.5 AI Automated Analysis

The ivdtools R package provides statistical functions, while the ivdtools-analysis Skill provides a constrained automated analysis workflow for AI. Once the user supplies the data file, study design, and analysis requirements, the Skill uses ivdtools as its statistical engine to organize data pre-check, parameter confirmation, statistical analysis, result verification, and Chinese report generation.

The value of using the Skill in a conversation is not to “replace statistical judgment” but to standardize repetitive technical steps, and to save the data source, analysis parameters, excluded records, warnings, result tables, figures, and software environment together, reducing the risk of omissions and manual copy errors.

ivdtools-analysis is not installed with ivdtools; it can be obtained from the project homepage.

1.6 Dependencies

ivdtools mainly depends on ggplot2, ggrepel, VCA, VFP, minpack.lm, nloptr, nls2, nortest, and rlang.

1.7 Scope of Use

  • Software output does not automatically constitute a pass/fail determination; acceptance criteria should be defined before analysis.
  • Before use in regulated scenarios, applicable software validation, process verification, and result review should be completed.

1.8 Project Information