Package 'ivdtools'

Description

Estimates degradation rates at multiple elevated temperatures, fits the Arrhenius equation, and extrapolates to the target storage temperature to predict shelf life.

Usage

arrhenius(
  data,
  temperature,
  time,
  value,
  target_temp,
  order = c("auto", "zero", "first"),
  direction = c("auto", "decrease", "increase"),
  limit,
  bias_type = c("relative", "absolute"),
  temp_unit = "C",
  time_unit = "d",
  conf.level = 0.95
)

Arguments

Value

An S3 object of class "arrhenius".

Examples

temp_df <- data.frame(temp = rep(c(25,30,37), each = 3),
                      time = rep(c(0,1,3), 3),
                      val = c(100,98,95, 100,96,90, 100,94,85))
arrhenius(temp_df, "temp", "time", "val", target_temp = 5, limit = 10)

Description

Compare two ROC curves evaluated on the common complete cases stored in a single roc() object. A curve can be a marker previously processed by auc() or a named multivariate model produced by mlr().

Usage

## S3 method for class 'roc'
auc_compare(
  x,
  curves,
  method = c("ep24", "delong"),
  conf.level = 0.95,
  rating_method = c("pearson", "kendall"),
  name = NULL,
  ...
)

Arguments

Details

method = "ep24" implements the paired Hanley–McNeil approximation in CLSI EP24-A2. It combines the two single-curve Hanley–McNeil standard errors with the correlation between the paired AUCs. The latter is obtained by linear interpolation of EP24-A2 Table 5 from the average within-group score correlation and average AUC. Coordinates outside the published table are bounded to its range and recorded in the result.

method = "delong" uses the nonparametric DeLong covariance estimator and handles ties with half credit. Both methods test the two-sided null hypothesis that the AUC difference is zero.

Value

The updated roc object, invisibly. The comparison is stored in x$auc_comparisons[[name]] as a roc_auc_comparison object.

Examples

obj <- roc(ivd_roc_example, c("x1", "x2"), "ref")
obj <- auc(obj)
obj <- auc_compare(obj, c("x1", "x2"), method = "ep24")
obj$auc_comparisons[[1L]]

obj <- mlr(obj, name = "combined")
obj <- auc_compare(obj, c("x1", "combined"), method = "delong")

Description

Compute ROC curves and AUC for each evaluation column.

Usage

## S3 method for class 'roc'
auc(x, cols = NULL, ...)

Arguments

Value

Updated roc object with results stored in $auc_list and $auc_table

Examples

obj <- roc(ivd_roc_example, cols = c("x1", "x2"), reference = "ref")
  obj <- auc(obj)
  obj <- auc(obj, cols = "x1")

Description

Compute bias at specified medical decision levels (MDL) based on stored regression results: bias = predicted_candidate - reference = (intercept + slope * x0) - x0 = intercept + (slope - 1) * x0

Usage

## S3 method for class 'mcr'
bias(
  x,
  mdl,
  level = 0.95,
  interval = c("", "confidence", "prediction", "both"),
  ci_method = c("auto", "analytic", "jackknife", "rank", "bootstrap_percentile",
    "bootstrap_standard"),
  bootstrap_replicates = 5000L,
  seed = NULL,
  ...
)

Arguments

Details

Bias follows the conventional candidate-minus-reference direction; a positive value indicates that the candidate method is higher.

Value

Updated mcr object (invisible), results stored in $bias

Examples

obj <- mcr(ivd_mcr_example, "sid", "test", "ref")
  obj <- regression(obj, method = "ols")
  bias(obj, mdl = c(200, 400, 600))
  bias(obj, mdl = c(200, 400, 600), interval = "both")

Description

Calculate Limits of Agreement between two measurement methods, supporting three y-axis metrics: difference, ratio, and percent difference.

Usage

## S3 method for class 'mcr'
bland_altman(
  x,
  type = c("difference", "ratio", "percent"),
  x_axis = c("mean", "candidate", "reference"),
  percent_denominator = c("reference", "mean", "candidate"),
  agree.level = 0.95,
  conf.level = 0.95,
  method = c("parametric", "nonparametric", "hodges_lehmann"),
  median_ci_method = c("order_statistic", "interpolated"),
  bootstrap_replicates = 5000L,
  seed = NULL,
  ...
)

Arguments

Value

Updated mcr object (invisible), with results stored in $bland_altman. The result records the selected method, its centre estimate and center_ci. Method-specific aliases are mean_diff_ci for the parametric mean and median_diff_ci for the nonparametric median. The original mean_diff and sd_diff fields are retained for compatibility.

Examples

obj <- mcr(ivd_mcr_example, "sid", "test", "ref")
  bland_altman(obj)
  bland_altman(obj, type = "ratio")
  bland_altman(obj, type = "percent", x_axis = "reference")
  bland_altman(obj, type = "percent", x_axis = "mean",
                percent_denominator = "mean")

Description

Create a bottle/batch ANOVA analysis object. Supports one-way and nested designs, with automatic assumption checks, missing value reporting, and ANOVA table output.

Usage

bottle_anova(data, formula, conf.level = 0.95)

Arguments

Value

An S3 object of class "bottle_anova" with components:

Examples

# One-way design
  df1 <- data.frame(
    bottle = rep(c("A", "B", "C"), each = 5),
    value  = c(rnorm(5, 10, 1), rnorm(5, 12, 1), rnorm(5, 11, 1))
  )
  obj <- bottle_anova(df1, value ~ bottle)

  # Nested design
  df2 <- data.frame(
    lot   = rep(c("L1", "L2"), each = 10),
    vial  = rep(c("V1", "V2"), each = 5, times = 2),
    value = c(rnorm(5, 10, 1), rnorm(5, 10.5, 1),
              rnorm(5, 12, 1), rnorm(5, 12.5, 1))
  )
  obj2 <- bottle_anova(df2, value ~ lot/vial)

Description

Estimates response values associated with selected probabilities of a qualitative result. The response SD is modeled as a function of the expected response using a VFP precision profile. For direction = "geq", the event is result >= cutoff; for direction = "leq", the event is result <= cutoff. No acceptance decision is made.

Usage

c5_c95(
  data,
  result = NULL,
  sample = NULL,
  cutoff,
  direction = c("geq", "leq"),
  probabilities = c(0.05, 0.95),
  component = NULL,
  model.no = 1:10,
  K = 2,
  search_range = NULL,
  tol = 1e-07
)

Arguments

Value

An object of class c5_c95. Its estimates element contains the estimated response, fitted SD, achieved probability, extrapolation flag, and root-search diagnostics for each cutoff and probability.

Examples

set.seed(1203)
cx_data <- data.frame(
  level = rep(paste0("L", 1:7), each = 20),
  response = unlist(lapply(seq(34, 46, length.out = 7), function(mu)
    stats::rnorm(20, mean = mu, sd = 0.7 + 0.01 * mu)))
)
cx <- c5_c95(cx_data, result = "response", sample = "level",
             cutoff = 40, model.no = 1)
cx$estimates
plot(cx)

Description

Compute confidence intervals for each variance component (SD and %CV) based on Satterthwaite approximation. Requires variance() to be run first to populate the $results slot.

Usage

## S3 method for class 'precision'
ci(x, digits = 4, ...)

Arguments

Details

This method reports intervals for the fitted model components and the total component. EP05 semantic combinations such as multisite within-laboratory precision require the day, run, and site mapping supplied to report.precision and are therefore constructed by report(x, ..., table = "CI").

Value

Updated precision object with results stored in $ci

Examples

data(VCAdata1, package = "VCA")
  obj <- precision(VCAdata1, y ~ day/run, by = "sample")
  obj <- variance(obj)
  obj <- ci(obj)

Description

Extract coefficients from an equation fit

Usage

## S3 method for class 'fit_equation'
coef(object, ...)

Arguments

Value

A named numeric vector of model coefficients.

Examples

df <- data.frame(x = 1:5, y = c(2.1, 4.0, 6.2, 7.9, 10.1))
f <- fit_equation("E01", df, "x", "y")
coef(f)

Description

Implements the statistical calculations for CLSI EP14-A3 Deming-regression prediction intervals, CLSI EP30-A prediction intervals and relative residuals, the IFCC Part 2 difference-in-bias approach, or the IFCC Part 3 calibration-effectiveness approach. The function expects long-format data and does not assess specimen collection, run randomization, reagent lots, or other experimental conduct.

Usage

commutability(
  data,
  sample_id,
  material_type = NULL,
  procedure,
  result,
  position = NULL,
  approach = c("ep14", "ep30", "ifcc", "calibration"),
  scale = c("raw", "log10", "ln"),
  reference_procedure = NULL,
  procedure_pairs = NULL,
  conf.level = 0.95,
  criterion = NULL,
  bias_model = c("constant_global", "constant_local", "linear_local"),
  local_n = NULL,
  coverage_factor = 1.9,
  rm_position = c("pooled", "material_specific"),
  rm_set_size = 1L,
  relative_residual_limit = 2,
  calibration_stage = NULL,
  calibration_replicate_summary = c("mean", "median", "error"),
  exclude_procedures = NULL,
  w3_reference_procedure = NULL,
  material_type_map = NULL
)

Arguments

Details

Sample-size, replicate-count, position-matching, and method-count targets from CLSI and IFCC publications are reported in design_checks; they are not treated as proof of compliance and do not stop a calculation that is statistically defined. Conditions required by the formula itself still produce an error. A local result that cannot be calculated is returned as not_evaluable, while an unavailable secondary statistic is returned as NA.

Value

An object of class commutability_result containing material-level results, model estimates, design checks, IFCC position diagnostics, and the transformed analysis data. Design checks report whether the supplied study meets the sample-size and replication recommendations of the named method; unmet checks do not prevent otherwise computable analyses.

Examples

# Long-format replicate results for eight clinical samples.
clinical <- expand.grid(
  sample = paste0("CS", 1:8), procedure = c("MP1", "MP2"),
  replicate = 1:3, stringsAsFactors = FALSE
)
level <- setNames(seq(10, 80, length.out = 8), paste0("CS", 1:8))
clinical$result <- level[clinical$sample] +
  ifelse(clinical$procedure == "MP2", 1, 0) +
  rep(c(-0.2, 0, 0.2), each = 16)
clinical$material_type <- "clinical"
clinical$position <- NA_integer_

# One reference material measured at three positions, in triplicate.
rm <- expand.grid(
  sample = "RM1", procedure = c("MP1", "MP2"),
  position = 1:3, replicate = 1:3, stringsAsFactors = FALSE
)
rm$result <- 45 + ifelse(rm$procedure == "MP2", 1, 0) +
  rep(c(-0.1, 0, 0.1), each = 6)
rm$material_type <- "rm"
columns <- c("sample", "material_type", "procedure", "result",
             "position", "replicate")
example_data <- rbind(clinical[columns], rm[columns])

ep14 <- commutability(
  example_data, "sample", "material_type", "procedure", "result",
  approach = "ep14"
)
ep14$results

# Explicitly map nonstandard material-type labels.
mapped_data <- example_data
mapped_data$material_type <- ifelse(
  mapped_data$material_type == "clinical", "patient_sample", "candidate_rm"
)
ep14_mapped <- commutability(
  mapped_data, "sample", "material_type", "procedure", "result",
  approach = "ep14",
  material_type_map = c(patient_sample = "clinical", candidate_rm = "rm")
)
ep14_mapped$results

ifcc <- commutability(
  example_data, "sample", "material_type", "procedure", "result",
  position = "position", approach = "ifcc", criterion = 2,
  bias_model = "constant_global"
)
ifcc$results

Description

Fit and compare multiple equations

Usage

compare_equation(data, x = "x", y = "y", eqs = NULL, ...)

Arguments

Value

An object of class "compare_equation" with components:

Examples

df <- data.frame(
  x = c(0.1, 0.3, 1, 3, 10, 30, 100),
  y = c(12, 25, 48, 72, 88, 96, 99)
)
compare_equation(df, "x", "y", eqs = c("E01", "E06", "E07"))

Description

Creates new binary columns (0/1) from existing quantitative columns using specified cutoff values, appending them to the original data frame. New columns are named <col>_binary.

Usage

continuous_to_binary(data, cols, cutoff)

Arguments

Value

data frame with original columns plus new <col>_binary columns

Examples

df <- data.frame(x = 1:10, y = rnorm(10))
  continuous_to_binary(df, "x", 5)
  continuous_to_binary(df, c("x", "y"), c(5, 0))

Description

Perform correlation analysis between the reference method (X) and candidate method (Y), supporting Pearson, Spearman, and Kendall methods.

Usage

## S3 method for class 'mcr'
correlation(x, method = c("pearson", "spearman", "kendall"), ...)

Arguments

Value

Updated mcr object (invisible), results stored in $correlation

Examples

obj <- mcr(ivd_mcr_example, "sid", "test", "ref")
  correlation(obj)
  correlation(obj, method = "spearman")

Description

When raw data are not available and only the four diagnostic test frequencies are known, use this function to directly construct a result object with the same structure as raw_to_table(), compatible with print() for displaying the fourfold table.

Usage

counts_to_table(
  tp,
  fp,
  tn,
  fn,
  candidate = "candidate",
  reference = "reference",
  candidate_levels = c("positive", "negative"),
  reference_levels = c("positive", "negative")
)

Arguments

Value

A fourfold_table object (S3 class "fourfold_table") with the same structure as raw_to_table(): - $freq_raw Long-format frequency data.frame - $table 3x3 matrix with margins - $n Total sample size - $print Print slot - $candidate_levels Levels of the candidate method - $reference_levels Levels of the reference method Use print() directly to display the fourfold table.

Examples

result <- counts_to_table(tp = 45, fp = 12, tn = 80, fn = 5,
                          candidate = "new method", reference = "gold standard")

Description

For each evaluation column, compute diagnostic metrics at all cutoff values, and identify the optimal cutoff (maximum Youden index, closest to (0,1) corner).

Usage

## S3 method for class 'roc'
cutoff(x, cols = NULL, ...)

Arguments

Value

Updated roc object with results stored in $cutoff_table

Examples

obj <- roc(ivd_roc_example, cols = c("x1", "x2"), reference = "ref")
  obj <- auc(obj)
  cutoff(obj)
  cutoff(obj, cols = "x1")

Description

Describe an analysis object

Usage

describe(x, ...)

correlation(x, ...)

regression(x, ...)

bias(x, ...)

bland_altman(x, ...)

report(x, ...)

profile(object, ...)

normal(x, ...)

ci(x, ...)

variance(x, ...)

vc(x, ...)

diagnostics(object, ...)

kappa(x, ...)

mcnemar(x, ...)

cutoff(x, ...)

mlr(x, ...)

auc(x, ...)

auc_compare(x, ...)

tukey(x, ...)

Arguments

Value

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

The value returned by the dispatched method.

Examples

obj <- mcr(ivd_mcr_example, "sid", "test", "ref")
describe(obj)

Description

Print variable description information for a fourfold_table object (from raw_to_table). If the object comes from counts_to_table (no raw data), indicates unavailability.

Usage

## S3 method for class 'fourfold_table'
describe(x, ...)

Arguments

Value

Updated fourfold_table object, with $describe slot filled with description results

Examples

df <- data.frame(
    new    = c("positive","positive","negative","negative","positive","negative"),
    gold   = c("positive","negative","positive","negative","positive","positive"),
    age    = c(45, 52, 38, 61, 47, 55),
    gender = c("M","F","F","M","M","F"),
    id     = c("S001","S002","S003","S004","S005","S006")
  )
  tab <- raw_to_table(df, "new", "gold", id = "id")
  tab <- describe(tab)

Description

Computes data overview (rows/columns/ID duplicates), per-column summaries, and a side-by-side comparison table of candidate, reference, and Diff. Results are stored in x$describe (class mcr_describe) and displayed via print.mcr_describe() (e.g., when calling summary()).

Usage

## S3 method for class 'mcr'
describe(x, cols = NULL, digits = 4L, ...)

Arguments

Value

Updated mcr object (invisible), results stored in x$describe

Examples

obj <- mcr(ivd_mcr_example, "sid", "test", "ref")
  describe(obj)

Description

Print distribution summaries for evaluation columns and the reference column (if numeric). When the reference is binary, evaluation column distributions are shown grouped by positive/negative.

Usage

## S3 method for class 'roc'
describe(x, cols = NULL, digits = 4L, ...)

Arguments

Value

Updated roc object with results stored in $describe

Examples

obj <- roc(ivd_roc_example, cols = "x1", reference = "ref")
  describe(obj)

Description

Diagnostic performance metrics: calculate sensitivity, specificity, likelihood ratios, etc. with confidence intervals for a fourfold_table

Usage

## S3 method for class 'fourfold_table'
diagnostics(
  object,
  conf.level = 0.95,
  ci.method = "wilson",
  prevalence = NULL,
  ...
)

Arguments

Value

Updated fourfold_table object, with diagnostic performance metrics stored in $diagnostics: - $tp / $fp / $fn / $tn / $n Four-fold frequencies and total sample size - $sensitivity Sensitivity with CI - $specificity Specificity with CI - $ppv Positive predictive value with CI - $npv Negative predictive value with CI - $accuracy Accuracy with CI - $prevalence Prevalence with CI - $lr_positive Positive likelihood ratio with CI - $lr_negative Negative likelihood ratio with CI - $odds_ratio Odds ratio with CI - $conf_level Confidence level used - $ci_method Method name used - $prev_specified Whether user specified prevalence

Examples

tab <- raw_to_table(ivd_qualitative_example, "new", "gold",
                      positive = "positive", id = "id")
  tab <- diagnostics(tab)
  tab <- diagnostics(tab, prevalence = 0.3)
  tab <- diagnostics(tab, conf.level = 0.90)
  tab <- diagnostics(tab, ci.method = "clopper-pearson")

Description

Summarizes replicate measurements and calculates target concentration, dilution-corrected concentration, and recovery for each specimen and dilution factor. Across-specimen mean recovery and its Student t confidence interval are calculated for every dilution factor. No acceptance criterion or suitability decision is applied.

Usage

dilution_recovery(
  data,
  sample,
  result,
  dilution_factor,
  assigned = NULL,
  diluent_value = 0,
  conf.level = 0.95
)

Arguments

Value

An object of class dilution_recovery containing results, summary, the retained data, and excluded row indices.

References

CLSI. Establishing and Verifying an Extended Measuring Interval Through Specimen Dilution and Spiking. EP34, 1st ed. 2018.

Examples

dilution_data <- data.frame(
  sample = rep(c("S1", "S2"), each = 6),
  factor = rep(rep(c(1, 2, 4), each = 2), 2),
  result = c(99, 101, 49, 51, 24, 26,
             199, 201, 99, 101, 49, 51)
)
dilution <- dilution_recovery(
  dilution_data, "sample", "result", "factor"
)
dilution$summary

Description

General-purpose equation fitting

Usage

fit_equation(
  eq,
  data,
  x = "x",
  y = "y",
  start = NULL,
  lower = NULL,
  upper = NULL,
  constraints = NULL,
  weights = NULL,
  ...
)

Arguments

Value

an S3 object of class "fit_equation"

Examples

# ==== Response curve fitting ====

# 1) Linear
df <- data.frame(x = 1:5, y = c(2.1, 4.0, 6.2, 7.9, 10.1))
f1 <- fit_equation("E01", df, "x", "y")
print(f1)

# 2) Logarithmic
f2 <- fit_equation("E06", df, "x", "y")
print(f2)

# 3) 4PLC (dose-response, descending)
df4plc <- data.frame(
  conc = c(0.1, 0.3, 1, 3, 10, 30, 100),
  resp = c(99, 96, 88, 72, 48, 25, 12)
)
f3 <- fit_equation("E07", df4plc, "conc", "resp")
print(f3)

# 4) Custom formula
f4 <- fit_equation("a + b * log(x)", df4plc, "conc", "resp")
print(f4)

# 5) Box constraints (parameter bounds)
f5 <- fit_equation("E07", df4plc, "conc", "resp",
  lower = list(D = 0), upper = list(D = 5))
print(f5)

# 6) Inequality constraints (parameter relationship)

# require D > 1 (Hill slope cannot be too shallow)
f6 <- fit_equation("E07", df4plc, "conc", "resp",
  constraints = list(ineq = function(p) 1 - p["D"]))
print(f6)


# 7) Equality constraints (fixed parameter relationship)

# fix b = 0.5 in exponential decay y = a*exp(-b*x)
df_exp <- data.frame(x = 0:5, y = c(10, 6.1, 3.7, 2.2, 1.4, 0.8))
f7 <- fit_equation("E04", df_exp, "x", "y",
  constraints = list(eq = function(p) p["b"] - 0.5))
print(f7)


# 8) Weighted fitting via replicate_to_mean

# data with replicate measurements (8 dose levels, 3 replicates each)
df_rep <- data.frame(
  dose = rep(c(0.3, 0.6, 1.5, 4, 10, 25, 60, 150), each = 3),
  resp = c(4.1, 3.8, 3.9, 8.5, 8.9, 8.6,
           18.2, 17.9, 18.5,
           34.6, 35.1, 34.8,
           54.3, 53.9, 54.7,
           73.0, 73.6, 73.2,
           87.5, 87.1, 87.8,
           97.9, 98.3, 98.0)
)
# first summarize, generate inverse-variance weights
rep <- replicate_to_mean(df_rep, "dose", "resp", weights = "1/sd^2")

# fit 4PLC with summarized means and explicit start values
f8 <- fit_equation("E07", rep, x = "x", y = "y_mean",
  weights = rep$weight,
  start = list(A = 2, B = 100, C = 8, D = -1.5))
print(f8)

Description

Summarizes raw response by known concentration and identifies the first post-peak measured concentration whose mean response is at or below the raw response associated with the ULoQ. The reported hook_concentration is the immediately preceding measured concentration; no interpolation is used. No hook-effect or extended-interval acceptability decision is made.

Usage

hook_effect(
  data,
  concentration,
  response,
  series = NULL,
  uloq,
  uloq_response = NULL,
  conf.level = 0.95
)

Arguments

Value

An object of class hook_effect containing concentration-level summaries and one threshold result per series.

References

CLSI. Establishing and Verifying an Extended Measuring Interval Through Specimen Dilution and Spiking. EP34, 1st ed. 2018.

Examples

hook_data <- data.frame(
  concentration = rep(c(100, 200, 400, 800), each = 2),
  response = c(48, 52, 98, 102, 148, 152, 88, 92)
)
hook <- hook_effect(
  hook_data, "concentration", "response", uloq = 200
)
hook$results

Description

Summarizes replicate results at each interferent concentration relative to an observed baseline concentration. The recommended point-to-point method is the default; a straight-line regression can be requested explicitly.

Usage

interference_dose_response(
  data,
  result,
  concentration,
  by = NULL,
  baseline = 0,
  method = c("point_to_point", "linear"),
  conf.level = 0.95
)

Arguments

Value

An object of class interference_dose_response.

Examples

dose_data <- expand.grid(
  interferent = c("A", "B"), concentration = c(0, 10, 20, 30, 40),
  replicate = 1:5, KEEP.OUT.ATTRS = FALSE
)
dose_data$result <- 100 + ifelse(dose_data$interferent == "A", 0.5, -0.3) *
  dose_data$concentration + stats::rnorm(nrow(dose_data), 0, 0.5)
dose_fit <- interference_dose_response(
  dose_data, "result", "concentration", by = "interferent")
dose_fit$summary

Description

Supports the standard EP07 test/control preparation and two laboratory extensions: analyte spiking in normal/interferent matrices and direct measurement of interferent dissolved in a blank. One row represents one replicate result. Multiple interferents or measurand levels are handled by supplying their columns in by.

Usage

interference_paired(
  data,
  result,
  design = c("ep07", "analyte_spike", "blank"),
  by = NULL,
  condition = NULL,
  test_level = "test",
  control_level = "control",
  matrix = NULL,
  normal_level = "normal",
  interferent_level = "interferent",
  spike = NULL,
  unspiked_level = "unspiked",
  spiked_level = "spiked",
  conf.level = 0.95
)

Arguments

Value

An S3 object of class interference_paired containing effects, cell_summary, issues, and excluded row indices.

Examples

ep07_data <- data.frame(
  interferent = rep(c("bilirubin", "hemoglobin"), each = 10),
  condition = rep(rep(c("control", "test"), each = 5), 2),
  result = c(0.45, 0.56, 0.48, 0.54, 0.47,
             0.24, 0.28, 0.35, 0.37, 0.26,
             5.02, 4.98, 5.08, 4.95, 5.00,
             5.20, 5.12, 5.18, 5.10, 5.15)
)
interference_paired(ep07_data, "result", design = "ep07",
                    condition = "condition", by = "interferent")

spike_data <- expand.grid(
  matrix = c("normal", "interferent"), spike = c("before", "after"),
  replicate = 1:4, KEEP.OUT.ATTRS = FALSE
)
spike_data$result <- with(spike_data,
  ifelse(matrix == "normal", 10, 12) +
  ifelse(spike == "after", ifelse(matrix == "normal", 10, 8), 0))
interference_paired(spike_data, "result", design = "analyte_spike",
                    matrix = "matrix", spike = "spike",
                    unspiked_level = "before", spiked_level = "after")

Description

Averages replicates within specimen and method, then calculates the evaluated procedure result minus the comparative procedure result. Potential interferent concentrations can be supplied as multiple numeric columns and are modeled separately.

Usage

interference_patient(
  data,
  id,
  group,
  method,
  result,
  test_group,
  control_group,
  evaluated_method,
  comparative_method,
  interferent_cols = NULL,
  conf.level = 0.95
)

Arguments

Value

An object of class interference_patient.

Examples

patient_data <- expand.grid(
  id = paste0("S", 1:12), method = c("evaluated", "comparative"),
  replicate = 1:2, KEEP.OUT.ATTRS = FALSE
)
patient_data$group <- ifelse(as.integer(sub("S", "", patient_data$id)) <= 6,
                             "control", "test")
patient_data$bilirubin <- 2 * (as.integer(sub("S", "", patient_data$id)) - 1)
truth <- 50 + as.integer(sub("S", "", patient_data$id))
patient_data$result <- truth +
  ifelse(patient_data$method == "evaluated", 0.08 * patient_data$bilirubin, 0)
patient_fit <- interference_patient(
  patient_data, "id", "group", "method", "result",
  test_group = "test", control_group = "control",
  evaluated_method = "evaluated", comparative_method = "comparative",
  interferent_cols = "bilirubin")
patient_fit$group_summary

Description

Calculates the number of replicate measurements needed in each of the test and control samples. sd and detectable_difference must use the same scale: both absolute units, or both relative units (SD/CV and percent). The calculation is vectorized and reports design parameters only.

Usage

interference_replicates(
  sd,
  detectable_difference,
  alpha = 0.05,
  power = 0.9,
  alternative = c("two.sided", "one.sided"),
  min_replicates = 5L,
  label = NULL
)

Arguments

Value

A data frame of class interference_replicates.

References

CLSI. Interference Testing in Clinical Chemistry. EP07, 3rd ed.

Examples

interference_replicates(sd = c(5, 5),
                        detectable_difference = c(7, 10),
                        label = c("7 percent", "10 percent"))

Description

Small deterministic one-way ANOVA example

Usage

ivd_bottle_example

Format

A data frame with 12 observations from three bottles.

Description

Small deterministic method-comparison example

Usage

ivd_mcr_example

Format

A data frame with 12 rows and columns sid, test, and ref.

Description

Small deterministic qualitative-method example

Usage

ivd_qualitative_example

Format

A data frame with paired binary results and sample identifiers.

Description

Small deterministic ROC example

Usage

ivd_roc_example

Format

A data frame with 12 rows, two markers, and a binary reference.

Description

Calculate Cohen's Kappa coefficient or PABAK (Prevalence-Adjusted Bias-Adjusted Kappa) and its confidence interval, used to evaluate agreement between two binary classification methods.

Usage

## S3 method for class 'fourfold_table'
kappa(x, prevalence = NULL, conf.level = 0.95, ...)

Arguments

Details

When data prevalence is extreme, Cohen's Kappa may be low even when observed agreement is high. In such cases, specify the prevalence parameter to compute PABAK as a correction. PABAK = 2 x p_obs - 1, which assumes expected agreement = 0.5.

Value

Updated fourfold_table object, with Kappa results stored in $kappa: - $kappa Kappa / PABAK coefficient - $se Standard error - $lower / $upper Lower/upper confidence interval bounds - $p_obs Observed agreement - $p_exp Expected agreement - $n Total sample size - $conf_level Confidence level used - $method Method name used

Examples

tab <- counts_to_table(tp = 85, fp = 3, tn = 90, fn = 2,
                         candidate = "new method", reference = "gold standard")
  tab <- kappa(tab)                        # Cohen's Kappa
  tab <- kappa(tab, prevalence = 0.5)      # PABAK

Description

linearity() is a parameter-driven analysis engine rather than a separate validation/verification workflow. The straight-line calculations implement the approach in CLSI EP06-Ed2. Polynomial regression reproduces the superseded EP6-A procedure and is reported as exploratory. Straight-line models are fitted to sample-level means; EP6-A polynomial models are fitted to the retained replicate observations.

Usage

linearity(
  data,
  sample,
  result,
  x,
  method = c("linear", "polynomial"),
  intercept = TRUE,
  weights = c("equal", "level_variance", "pooled", "precision_profile"),
  variance_group = NULL,
  max_degree = 3L,
  poly_alpha = 0.05,
  percent_base = c("predicted", "x", "mean"),
  conf.level = NULL,
  multiplicity = c("familywise", "none"),
  adl = NULL,
  adl_abs = NULL,
  adl_rel = NULL,
  profile_exclude_low = TRUE,
  profile_intercept = FALSE
)

Arguments

Details

With weights = "pooled", variance groups must be supplied explicitly. Within group g, the pooled variance is sum((n[j] - 1) * s[j]^2) / sum(n[j] - 1), and the level-mean regression weight is n[j] / pooled_variance[g]. The function does not infer groups from the number of concentration levels because EP06 grouping also depends on the observed repeatability pattern.

Value

An S3 object of class linearity.

Examples

set.seed(2020)
linearity_data <- data.frame(
  level = rep(1:6, each = 4),
  expected = rep(c(10, 30, 50, 70, 90, 110), each = 4)
)
linearity_data$result <- 2 + 0.98 * linearity_data$expected +
  stats::rnorm(nrow(linearity_data), sd = 1.5)

# Parameter-driven straight-line analysis.
fit_linear <- linearity(
  linearity_data, sample = "level", result = "result", x = "expected",
  method = "linear", intercept = TRUE, weights = "level_variance",
  adl_rel = 5
)
fit_linear$model_comparison
fit_linear$level_summary

# EP6-A polynomial analysis (reported as exploratory under EP06-Ed2).
fit_polynomial <- linearity(
  linearity_data, sample = "level", result = "result", x = "expected",
  method = "polynomial", max_degree = 3
)
fit_polynomial$coefficients

Description

Implements the equations in Appendix J of CLSI EP06-Ed2 for studies in which results outside the measuring interval cannot be obtained.

Usage

linearity_endpoints(
  lloq = NULL,
  uloq = NULL,
  cv_high = NULL,
  cv_at_lloq = NULL,
  cv_at_k_lloq = NULL,
  k = 3,
  cv_scale = c("percent", "proportion")
)

## S3 method for class 'linearity_endpoints'
print(x, ...)

Arguments

Value

A list of class linearity_endpoints.

The unchanged x, invisibly.

Examples

linearity_endpoints(
  lloq = 10, uloq = 1000,
  cv_high = 5, cv_at_lloq = 20, cv_at_k_lloq = 15
)

Description

Design a HIGH/LOW linearity panel

Usage

linearity_panel(
  proportion_high,
  high,
  low = 0,
  total_volume = NULL,
  sample = NULL
)

## S3 method for class 'linearity_panel'
print(x, ...)

Arguments

Value

A data frame containing proportions, expected values, relative concentrations, and (when requested) component volumes.

The unchanged x, invisibly.

Examples

linearity_panel(
  proportion_high = c(1, 0.75, 0.5, 0.25, 0),
  high = 210, low = 10, total_volume = 1
)

Description

Calculates the minimum number of replicates from the imprecision and allowable deviation from linearity (ADL), following CLSI EP06-Ed2. Relative inputs use percentage units (for example, 5 means 5%). Absolute inputs must use the same measurement unit for imprecision, adl, and true_deviation.

Usage

linearity_replicates(
  imprecision,
  adl,
  type = c("relative", "absolute"),
  level_probability = 0.99,
  levels = NULL,
  family_error = NULL,
  true_deviation = 0,
  min_replicates = 2L
)

## S3 method for class 'linearity_replicates'
print(x, ...)

Arguments

Value

A data frame of class linearity_replicates.

The unchanged x, invisibly.

Examples

# Relative ADL: both CV and ADL are expressed in percent.
linearity_replicates(imprecision = c(3, 5), adl = 5)

# Choose the per-level probability from a 10% family-wise failure risk.
linearity_replicates(5, 5, levels = 9, family_error = 0.10)

Description

Print the equation registry

Usage

list_equation(category = NULL, engine = NULL)

Arguments

Value

invisible data.frame (matching rows), prints a formatted table to the console

Examples

# All equations
list_equation()

# Response only
list_equation(category = "Response")

# lm engine only
list_equation(engine = "lm")

Description

List Sadler precision profile model equations

Usage

list_sadler()

Arguments

This function has no arguments.

Details

List the 10 candidate Sadler precision profile model formulas and types used in the VFP package. Includes: Constant SD, Constant CV, Linear (variance), Power model, Exponential model, etc.

Value

Invisibly returns NULL. The model table is printed to the console as a side effect.

Examples

list_sadler()

Description

Prints commonly used Westgard multi-rule QC rules and their meanings. Rule names printed here can be passed to qc_chart(rules = "...").

Usage

list_westgard(brief = FALSE)

Arguments

Value

A named character vector of rule descriptions (invisibly).

Examples

list_westgard()

Description

Perform McNemar's test on a 2x2 paired contingency table to evaluate whether there is a systematic difference between two binary classification methods (i.e., whether marginal probabilities are equal).

Usage

## S3 method for class 'fourfold_table'
mcnemar(x, conf.level = 0.95, ...)

Arguments

Details

When discordant pairs (b + c) are few (< 25), automatically uses the exact binomial test (binom.test); otherwise uses McNemar's chi-squared test with continuity correction.

Value

Updated fourfold_table object, with McNemar results stored in $mcnemar: - $chi_sq McNemar chi-squared statistic (NA for exact test) - $df Degrees of freedom (NA for exact test) - $p_value Test p-value - $method Test method used - $b Discordant pairs (positive, negative) count - $c Discordant pairs (negative, positive) count - $n_bc Total discordant pairs - $conf.level Confidence level used

Examples

tab <- counts_to_table(tp = 45, fp = 12, tn = 80, fn = 5,
                         candidate = "new method", reference = "gold standard")
  tab <- mcnemar(tab)

Description

Create a method comparison regression (mcr) object containing one summarized row per sample ID. Raw replicate rows must first be summarized with replicate_to_mean() or by the user.

Usage

mcr(
  data,
  id,
  candidate,
  reference,
  weights = NULL,
  candidate_sd = NULL,
  reference_sd = NULL,
  candidate_n = NULL,
  reference_n = NULL
)

Arguments

Value

Returns an S3 "mcr" object containing:

and analysis result storage slots: $correlation, $regression, $outlier, $bland_altman

Examples

df <- data.frame(sid = 1:30,
                   test = rnorm(30, 50, 10),
                   ref  = rnorm(30, 50, 10))
  obj <- mcr(df, "sid", "test", "ref")

Description

Calculates the mean kinetic temperature from one or more temperature probes. Supports equal-interval and time-weighted trapezoidal methods.

Usage

mkt(data, temp_cols, time = NULL, temp_unit = "C", ea = 83.144)

Arguments

Value

An S3 object of class "mkt".

Examples

temp_df <- data.frame(t1 = c(25,26,27), t2 = c(24,25,26), time = 1:3)
mkt(temp_df, c("t1","t2"), "time")

Description

Fit logistic regression using selected evaluation columns, compute AUC of predicted probabilities. Names must be unique; auto-generated as MLR01, MLR02 ... when not specified.

Usage

## S3 method for class 'roc'
mlr(x, cols = NULL, name = NULL, ...)

Arguments

Value

Updated roc object with results stored in $mlr_results[name]

Examples

obj <- roc(ivd_roc_example, cols = c("x1", "x2"), reference = "ref")
  obj <- auc(obj)
  obj <- mlr(obj)                     # -> MLR01
  obj <- mlr(obj)                     # -> MLR02
  obj <- mlr(obj, name = "my_model")  # -> my_model

Description

Performs normality tests on a single numeric column of a data frame. Plots are generated separately via plot().

Usage

normal_test(
  data,
  col,
  method = c("auto", "shapiro", "sw", "ad", "lillie", "cvm"),
  level = 0.95
)

Arguments

Value

An S3 object of class "normal_test" containing:

call

Function call.

data_name

Data object name.

col

Column name.

method

User-specified method.

level

Confidence level.

n_total

Total number of rows.

n

Number of finite values (non-missing).

missing

Number of missing values.

test_method

Actual test method used.

statistic

Test statistic.

p_value

p-value.

y

Clean numeric vector, used by plot().

Examples

df <- data.frame(x = rnorm(50))
  normal_test(df, "x")
  normal_test(df, "x", method = "ad")
  plot(normal_test(df, "x"))
  plot(normal_test(df, "x"), type = "his")
  plot(normal_test(df, "x"), type = c("qq", "his"))

Description

Perform normality tests on the response values for each sample, underlying call to normal_test(). Supports automatic test selection (Shapiro-Wilk, Anderson-Darling, Lilliefors, CVM).

Usage

## S3 method for class 'precision'
normal(
  x,
  method = c("auto", "shapiro", "sw", "ad", "lillie", "cvm"),
  level = 0.95,
  ...
)

Arguments

Value

Updated precision object with results stored in $normal. Each sample entry contains test_method, statistic_name, statistic, p_value, and n; W is retained as a legacy alias only for Shapiro-Wilk results.

Examples

data(VCAdata1, package = "VCA")
  obj <- precision(VCAdata1, y ~ day/run, by = "sample")
  obj <- normal(obj)

Description

Detect outliers in an analysis object

Usage

outlier(x, ...)

Arguments

Value

The value returned by the dispatched method.

Examples

obj <- mcr(ivd_mcr_example, "sid", "test", "ref")
  outlier(obj, method = "grubbs")

Description

Perform outlier detection based on the difference or percent difference between two measurements. Reuses four methods from ../precision/outliers.R.

Usage

## S3 method for class 'mcr'
outlier(
  x,
  method = c("grubbs", "esd", "dixon", "iqr"),
  type = c("difference", "percent"),
  percent_denominator = c("reference", "mean", "candidate"),
  alpha = 0.05,
  coef = 1.5,
  ...
)

Arguments

Value

Updated mcr object (invisible), results stored in $outlier

Examples

obj <- mcr(ivd_mcr_example, "sid", "test", "ref")
  outlier(obj, method = "grubbs")
  outlier(obj, method = "iqr", type = "percent")

Description

Detect outliers in the response values for each sample, supporting Grubbs test and IQR method. Underlying call to outliers_test() (from outliers-and-normal.R).

Usage

## S3 method for class 'precision'
outlier(x, alpha = 0.05, method = c("grubbs", "iqr"), ...)

Arguments

Value

Updated precision object with results stored in $outlier

Examples

data(VCAdata1, package = "VCA")
  obj <- precision(VCAdata1, y ~ day/run, by = "sample")
  obj <- outlier(obj, method = "iqr")

Description

Integrates Grubbs test, generalized ESD test, Dixon Q test, and IQR method under a consistent API with an S3 print method.

Usage

outliers_test(data, col, method = c("grubbs", "esd", "dixon", "iqr"), ...)

Arguments

Value

An S3 object of class "outliers_test" containing:

method

Method name used.

data_name

Name of the input data.

col

Column name tested.

n_total

Total number of rows.

n

Number of finite observations used.

missing

Number of missing (non-finite) values.

parameters

List of method parameters.

n_outliers

Number of outliers detected.

indices

Indices of outliers in the original vector (1-based).

values

Outlier values.

details

Method-specific details (statistics, critical values, bounds, etc.).

Examples

set.seed(123)
df <- data.frame(x = c(rnorm(20), 10, -8))
outliers_test(df, "x", "grubbs")
outliers_test(df, "x", "esd", r = 3)
outliers_test(df, "x", "dixon")
outliers_test(df, "x", "iqr", coef = 2)

Description

Plot Arrhenius stability analysis

Usage

## S3 method for class 'arrhenius'
plot(x, ...)

Arguments

Value

A named list of ggplot objects, invisibly. The kinetic-fit and Arrhenius-regression plots are also drawn.

Examples

d <- data.frame(
  temperature = rep(c(25, 30, 37), each = 3),
  time = rep(c(0, 1, 3), 3),
  value = c(100, 98, 95, 100, 96, 90, 100, 94, 85)
)
fit <- arrhenius(d, "temperature", "time", "value",
                 target_temp = 5, limit = 10)
plot(fit)

Description

Plot C5 and C95 results

Usage

## S3 method for class 'c5_c95'
plot(x, type = c("probability", "profile"), ...)

Arguments

Value

A ggplot object.

Examples

set.seed(95)
d <- data.frame(level = rep(1:6, each = 12),
                y = stats::rnorm(72, rep(seq(36, 44, length.out = 6), each = 12), 1))
z <- c5_c95(d, "y", "level", cutoff = 40, model.no = 1)
plot(z, type = "probability")

Description

Plot a commutability assessment

Usage

## S3 method for class 'commutability_result'
plot(x, method = NULL, ...)

Arguments

Value

A ggplot object, invisibly.

Examples

clinical <- expand.grid(
  sample = paste0("CS", 1:8), procedure = c("MP1", "MP2"),
  replicate = 1:3, stringsAsFactors = FALSE
)
level <- setNames(seq(10, 80, length.out = 8), paste0("CS", 1:8))
clinical$result <- level[clinical$sample] +
  ifelse(clinical$procedure == "MP2", 1, 0) +
  rep(c(-0.2, 0, 0.2), each = 16)
clinical$material_type <- "clinical"
clinical$position <- NA_integer_
rm <- expand.grid(
  sample = "RM1", procedure = c("MP1", "MP2"),
  position = 1:3, replicate = 1:3, stringsAsFactors = FALSE
)
rm$result <- 45 + ifelse(rm$procedure == "MP2", 1, 0) +
  rep(c(-0.1, 0, 0.1), each = 6)
rm$material_type <- "rm"
columns <- c("sample", "material_type", "procedure", "result",
             "position", "replicate")
example_data <- rbind(clinical[columns], rm[columns])
assessment <- commutability(
  example_data, "sample", "material_type", "procedure", "result"
)
plot(assessment)

Description

Plot dilution-recovery results

Usage

## S3 method for class 'dilution_recovery'
plot(x, type = c("recovery", "summary", "observed"), ...)

Arguments

Value

A ggplot object, invisibly.

Examples

dilution_data <- data.frame(
  sample = rep(c("S1", "S2"), each = 6),
  factor = rep(rep(c(1, 2, 4), each = 2), 2),
  result = c(99, 101, 49, 51, 24, 26,
             199, 201, 99, 101, 49, 51)
)
dilution <- dilution_recovery(
  dilution_data, "sample", "result", "factor"
)
plot(dilution)

Description

Plot an equation fit

Usage

## S3 method for class 'fit_equation'
plot(x, interval = "confidence", level = 0.95, frame = FALSE, ...)

Arguments

Value

x, invisibly.

Examples

df4plc <- data.frame(
  conc = c(0.1, 0.3, 1, 3, 10, 30, 100),
  resp = c(12, 25, 48, 72, 88, 96, 99)
)
f <- fit_equation("E07", df4plc, "conc", "resp")
plot(f)
plot(f, interval = "prediction", frame = TRUE)

Description

Plot a high-dose hook-effect experiment

Usage

## S3 method for class 'hook_effect'
plot(x, ...)

Arguments

Value

A ggplot object, invisibly.

Examples

hook_data <- data.frame(
  series = rep("S1", 8),
  concentration = rep(c(10, 20, 40, 80, 160, 320, 640, 1280), each = 2),
  response = c(10, 11, 20, 21, 39, 40, 70, 71,
               95, 94, 80, 79, 55, 54, 30, 29)
)
hook <- hook_effect(hook_data, "concentration", "response",
                    series = "series", uloq = 320)
plot(hook)

Description

Plot interference dose-response results

Usage

## S3 method for class 'interference_dose_response'
plot(x, type = c("response", "absolute", "percent"), ...)

Arguments

Value

A ggplot object.

Examples

d <- expand.grid(conc = c(0, 10, 20), rep = 1:5)
d$result <- 100 + 0.5 * d$conc
plot(interference_dose_response(d, "result", "conc"), type = "percent")

Description

Plot paired interference estimates

Usage

## S3 method for class 'interference_paired'
plot(x, ...)

Arguments

Value

A ggplot object.

Examples

d <- data.frame(group = rep(c("control", "test"), each = 5),
                result = c(10, 10.1, 9.9, 10.2, 9.8, 11, 11.1, 10.9, 11.2, 10.8))
plot(interference_paired(d, "result", "ep07", condition = "group"))

Description

Plot patient-specimen interference results

Usage

## S3 method for class 'interference_patient'
plot(x, type = c("difference", "interferent"), interferent = NULL, ...)

Arguments

Value

A ggplot object.

Examples

d <- expand.grid(id = paste0("S", 1:8), method = c("test", "ref"), rep = 1:2)
d$group <- ifelse(as.integer(sub("S", "", d$id)) <= 4, "control", "selected")
d$bilirubin <- 2 * (as.integer(sub("S", "", d$id)) - 1)
d$result <- 20 + as.integer(sub("S", "", d$id)) +
  ifelse(d$method == "test", 0.1 * d$bilirubin, 0)
fit <- interference_patient(d, "id", "group", "method", "result",
  "selected", "control", "test", "ref", "bilirubin")
plot(fit, type = "difference")

Description

Plot a linearity analysis

Usage

## S3 method for class 'linearity'
plot(
  x,
  type = c("fit", "replicates", "precision", "residual", "difference"),
  ...
)

Arguments

Value

A ggplot object.

Examples

set.seed(6)
d <- data.frame(level = rep(1:5, each = 3), x = rep(1:5, each = 3))
d$y <- 1 + 2 * d$x + stats::rnorm(nrow(d), sd = 0.2)
fit <- linearity(d, "level", "y", "x")
plot(fit, type = "fit")
plot(fit, type = "residual")

Description

Draw one of four plot types for an mcr object.

Usage

## S3 method for class 'mcr'
plot(
  x,
  type = c("scatter", "regression", "bland_altman", "bias"),
  interval = c("none", "confidence", "prediction", "both"),
  conf.level = NULL,
  mdl = NULL,
  ...
)

Arguments

Value

Invisible ggplot object

Examples

obj <- mcr(ivd_mcr_example, "sid", "test", "ref")
  plot(obj)
  plot(obj, type = "scatter")
  obj <- regression(obj)
  plot(obj, type = "regression", interval = "confidence")
  obj <- bland_altman(obj)
  plot(obj, type = "bland_altman")
  obj <- bias(obj, mdl = c(200, 400))
  plot(obj, type = "bias")

Description

Plot normality diagnostics

Usage

## S3 method for class 'normal_test'
plot(x, type = c("qq", "his"), ...)

Arguments