Package 'ctlr'

Title: Clinical Tolerance Limits for Assessing Agreement
Description: Implements clinical tolerance limits (CTL) methodology for assessing agreement between two measurement methods. Estimates the true latent trait using Best Linear Unbiased Predictors (BLUP), models bias and variance components, and calculates overall and conditional agreement probabilities. Provides visualization tools including tolerance limit plots and conditional probability of agreement plots with confidence bands. This package is based on methods described in Taffé (2016) <doi:10.1177/0962280216666667>, Taffé (2019) <doi:10.1177/0962280219844535>, and 'Stata' package Taffé (2025) <doi:10.1177/1536867X251365501>.
Authors: Eliane Maalouf [aut] (ORCID: <https://orcid.org/0000-0003-1549-7948>), Patrick Taffé [cre, aut, cph] (ORCID: <https://orcid.org/0000-0002-2049-6651>)
Maintainer: Patrick Taffé <[email protected]>
License: GPL (>= 3)
Version: 0.1.0
Built: 2026-05-19 09:35:19 UTC
Source: https://github.com/cran/ctlr

Help Index

Clinical Tolerance Limits for Assessing Agreement

Description

Assesses agreement between two measurement methods using clinical tolerance limits (CTL). The function estimates the true latent trait, models bias and variance components, calculates overall and conditional agreement probabilities, and optionally generates tolerance limits or conditional probability of agreement plots.

Usage

ctl(
  data,
  idvar,
  ynew,
  yref,
  intercept = 0,
  slope = 0,
  nbsimul = 1000L,
  seed = 123456789L,
  tlplot = FALSE,
  cpaplot = FALSE,
  pointwise = FALSE,
  simultaneous = FALSE,
  plots_to_file = FALSE,
  results_to_file = FALSE,
  outputs_path = NULL,
  horizontal_ticks = c(5, 10),
  vertical_ticks = c(5, 7),
  font_size = 14
)

Arguments

data

A data frame containing the measurements.
idvar

Character string specifying the name of the ID variable (subject identifier).
ynew

Character string specifying the name of the new method variable.
yref

Character string specifying the name of the reference method variable.
intercept

Numeric scalar for the intercept of tolerance limits. Default is 0.
slope

Numeric scalar for the slope of tolerance limits. Default is 0.
nbsimul

Integer specifying the number of Monte Carlo simulations for confidence bands. Default is 1000.
seed

Integer specifying the random seed for reproducibility. Default is 123456789.
tlplot

Logical; if TRUE, generates a tolerance limits plot. Default is FALSE.
cpaplot

Logical; if TRUE, generates a conditional probability of agreement (CPA) plot. Default is FALSE.
pointwise

Logical; if TRUE, includes pointwise confidence bands in the CPA plot. Default is FALSE.
simultaneous

Logical; if TRUE, includes simultaneous confidence bands in the CPA plot. Default is FALSE.
plots_to_file

Logical; if TRUE, exports generated plots as PDF files to the "ctl_outputs/" directory. Default is FALSE.
results_to_file

Logical; if TRUE, saves the results dataset to "ctl_outputs/ctl_results.rda". Default is FALSE.
outputs_path

Character string specifying the directory path where an "ctl_outputs" directory can be created to store the results' file and/or the plots, as required by plots_to_file and results_to_file arguments. Default is NULL and causes an error message if one of plots_to_file or results_to_file is TRUE.
horizontal_ticks

Numeric vector of length 2 specifying the range for the number of ticks on the x-axis (true latent trait). Default is c(5, 10).
vertical_ticks

Numeric vector of length 2 specifying the range for the number of ticks on the y-axis. Only relevant for tlplot. Default is c(5, 7).
font_size

Numeric scalar specifying the base font size for plot text elements in points. Default is 14. Title, axis labels, and other text elements are scaled relative to this base font size.

Details

The function performs the following steps:

  1. Estimates Best Linear Unbiased Predictors (BLUP) for the true latent trait using the reference method with a linear mixed model.

  2. Models residual variance for the reference method (y2) as a function of the latent trait.

  3. Estimates differential and proportional bias between methods using heteroscedasticity-consistent standard errors.

  4. Models residual variance for the new method as a function of the latent trait.

  5. Calculates overall agreement as the proportion of observations falling within the clinical tolerance limits, with 95% confidence intervals using the Agresti-Coull method.

  6. Optionally generates tolerance limits plots and/or conditional probability of agreement plots with confidence bands.

The function creates a "ctl_outputs" directory at the specified outputs_path to store generated plots and results when requested.

When cpaplot = TRUE and results = TRUE, the saved dataset includes agreement probabilities and confidence bounds. The structure depends on the pointwise and simultaneous arguments.

Value

Invisibly returns ctl_results. The function is called for: printing results to the console, generating plots, and optionally saving results and plots to files. Console messages are suppressable with suppressMessages().

References

Taffé P. (2016) "Effective plots to assess bias and precision in method comparison studies" Statistical Methods in Medical Research, 27, Number 6, pp. 1650-1660. doi:10.1177/0962280216666667

Taffé P. (2019) "Assessing bias, precision, and agreement in method comparison studies" Statistical Methods in Medical Research, 29, Number 3, pp. 778-796. doi:10.1177/0962280219844535

Taffé, P. (2025). "ctl: A package for assessing agreement based on clinical tolerance limits" The Stata Journal, 25, Number 3, pp. 659–676. doi:10.1177/1536867X251365501

Examples

withr::with_tempdir({
   # Tolerance limit plot
   ctl(ctl_dataset1, idvar = "id", ynew = "y1", yref = "y2", intercept = 5, slope = 0.15,
       tlplot = TRUE, plots_to_file = TRUE, results_to_file = TRUE, outputs_path = ".")

   ctl(ctl_dataset2, idvar = "id", ynew = "y1", yref = "y2", intercept = 1, slope = 0.2,
       seed = 11446158, tlplot = TRUE, plots_to_file = TRUE, results_to_file = TRUE,
       outputs_path = ".")

   # Conditional probability of agreement plot
   ctl(ctl_dataset1, idvar = "id", ynew = "y1", yref = "y2", intercept = 5, slope = 0.15,
       nbsimul = 100, cpaplot = TRUE, plots_to_file = TRUE, results_to_file = TRUE,
       outputs_path = ".")

   ctl(ctl_dataset1, idvar = "id", ynew = "y1", yref = "y2", intercept = 0, slope = 0.15,
       nbsimul = 100, cpaplot = TRUE, pointwise = TRUE, plots_to_file = TRUE,
       results_to_file = TRUE, outputs_path = ".")

   ctl(ctl_dataset2, idvar = "id", ynew = "y1", yref = "y2", intercept = 1, slope = 0.2,
       seed = 11446158, nbsimul = 100, cpaplot = TRUE, simultaneous = TRUE)
})

ctl_dataset1

Description

A simulated dataset where the number of individuals is 100 and the number of repeated measurements per individual is 5 for both methods.

Usage

ctl_dataset1

Format

ctl_dataset1

A data frame with 500 rows and 4 variables:

id

represents the individual

t

the index for the repeated measurements

y1

the measurements made by method 1

y2

the measurements made by method 2

Source

Taffé, P. (2025). "ctl: A package for assessing agreement based on clinical tolerance limits" The Stata Journal, 25, Number 3, pp. 659–676. doi:10.1177/1536867X251365501

ctl_dataset2

Description

A simulated dataset where the number of individuals is 100 and the number of repeated measurements per individual varies between 1 to 3 for method 1 and between 5 to 10 for method 2.

Usage

ctl_dataset2

Format

ctl_dataset2

A data frame with 745 rows and 4 variables:

id

represents the individual

t

the index for the repeated measurements

y1

the measurements made by method 1

y2

the measurements made by method 2

Source

Taffé, P. (2025). "ctl: A package for assessing agreement based on clinical tolerance limits" The Stata Journal, 25, Number 3, pp. 659–676. doi:10.1177/1536867X251365501