Title: Clinical Tolerance Limits for Assessing Agreement
Version: 0.1.0
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>.
License: GPL (≥ 3)
Encoding: UTF-8
RoxygenNote: 7.3.3
Depends: R (≥ 4.1.0)
LazyData: true
Suggests: testthat (≥ 3.0.0), withr (≥ 2.0.0)
Config/testthat/edition: 3
Imports: binom (≥ 1.1-1.1), dplyr (≥ 1.1.0), ggplot2 (≥ 3.3.0), lme4 (≥ 1.1-35), lmtest (≥ 0.9-40), MASS (≥ 7.3-60), mfp2 (≥ 1.0.1), sandwich (≥ 3.0-0), stats, utils
NeedsCompilation: no
Packaged: 2026-03-16 18:02:07 UTC; dl-rookie
Author: Eliane Maalouf ORCID iD [aut], Patrick Taffé ORCID iD [cre, aut, cph]
Maintainer: Patrick Taffé <patrick.taffe@unisante.ch>
Repository: CRAN
Date/Publication: 2026-03-20 10:50:02 UTC

ctlr: 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.

Author(s)

Maintainer: Patrick Taffé patrick.taffe@unisante.ch (ORCID) [copyright holder]

Authors:

Clamp Values Based on Bounds

Description

Restricts values in a vector to fall within specified lower and upper bounds. Depending on the set_NA parameter, values outside the bounds are either clamped to the nearest boundary or set to NA.

Usage

clamp(v, lo_v, up_v, set_NA = FALSE)

Arguments

v

Numeric vector of values to be clamped or filtered.

lo_v

Numeric scalar specifying the lower bound. Values below this threshold will be clamped or set to NA.

up_v

Numeric scalar specifying the upper bound. Values above this threshold will be clamped or set to NA.

set_NA

Logical; if FALSE (default), values are clamped to the nearest bound. If TRUE, values outside ⁠[lo_v, up_v]⁠ are set to NA.

Value

A numeric vector of the same length as v, with values either clamped to the bounds or set to NA for out-of-range values.

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

Estimate Agreement Probabilities

Description

Calculates the conditional probability of agreement between two measurement methods based on clinical tolerance limits and the distribution of differences between methods.

Usage

estimate_agreement(
  CTLlo,
  CTLup,
  BLUP_x,
  differential_bias,
  proportional_bias,
  sig2_res_y2,
  sig2_res_y1
)

Arguments

CTLlo

Numeric vector specifying the lower clinical tolerance limit.

CTLup

Numeric vector specifying the upper clinical tolerance limit.

BLUP_x

Numeric vector of Best Linear Unbiased Predictor (BLUP) estimates of the true latent trait.

differential_bias

Numeric scalar representing the differential bias estimate between the two methods.

proportional_bias

Numeric scalar representing the proportional bias estimate between the two methods.

sig2_res_y2

Numeric scalar for the residuals variance of the reference method (y2).

sig2_res_y1

Numeric scalar for the residuals variance of the new method (y1).

Value

A list with six components:

Agreement

Numeric vector of agreement probabilities for each observation.

logit_Agreement

Numeric vector of logit-transformed agreement probabilities.

z_lo

Numeric vector of standardized lower limits.

z_up

Numeric vector of standardized upper limits.

diffs_mean

Numeric vector of expected mean differences between methods.

diffs_var

Numeric scalar for the variance of differences.

Estimate Variance of Agreement with Delta Method

Description

Estimate Variance of Agreement with Delta Method

Usage

estimate_agreement_variance(
  CTLlo,
  CTLup,
  BLUP_x,
  V_BLUP_x,
  z_lo,
  z_up,
  differential_bias,
  proportional_bias,
  diffs_mean,
  diffs_var,
  sig_res_y2,
  sig_res_y1,
  Agreement,
  Vdifferential_bias,
  Vproportional_bias,
  COVbias,
  Vtheta2_0e,
  Vtheta2_1e,
  COVtheta2e,
  Vtheta1_0e,
  Vtheta1_1e,
  COVtheta1e,
  theta2_1e,
  theta1_1e
)

Arguments

CTLlo

Lower clinical tolerance limit

CTLup

Upper clinical tolerance limit

BLUP_x

BLUP estimates of the true latent trait

V_BLUP_x

Variance of BLUP_x

z_lo

Lower z-score

z_up

Upper z-score

differential_bias

Differential bias estimate

proportional_bias

Proportional bias estimate

diffs_mean

Mean of differences

diffs_var

Variance of differences

sig_res_y2

Standard deviation of residuals for y2

sig_res_y1

Standard deviation of residuals for y1

Agreement

Agreement probability

Vdifferential_bias

Variance of differential bias estimate

Vproportional_bias

Variance of proportional bias estimate

COVbias

Covariance between differential and proportional bias

Vtheta2_0e

Variance of theta2_0e (intercept for y2 residual variance)

Vtheta2_1e

Variance of theta2_1e (slope for y2 residual variance)

COVtheta2e

Covariance between theta2_0e and theta2_1e

Vtheta1_0e

Variance of theta1_0e (intercept for y1 residual variance)

Vtheta1_1e

Variance of theta1_1e (slope for y1 residual variance)

COVtheta1e

Covariance between theta1_0e and theta1_1e

theta2_1e

Slope parameter for y2 residual variance

theta1_1e

Slope parameter for y1 residual variance

Value

A list with variance and SD of logit_Agreement

Find Empirical Quantile

Description

Computes the empirical quantile across simulations.

Usage

find_empirical_quantile(sims, prob = 95)

Arguments

sims

Numeric matrix where rows represent observations and columns represent simulation iterations.

prob

Numeric scalar specifying the desired probability level for the quantile (default is 95).

Value

A numeric scalar representing the empirical quantile at the specified probability level.

Generate Adaptive Axis Breaks

Description

Creates adaptive axis breaks that extend slightly beyond the data range with a reasonable number of tick locations.

Usage

generate_adaptive_breaks(x, n_ticks)

Arguments

x

Numeric vector of values to create breaks for.

n_ticks

Numeric vector of length 2 specifying the range for number of ticks.

Value

A list with two components:

breaks

Numeric vector of major break locations.

minor_breaks

Numeric vector of minor break locations.

Make Conditional Probability of Agreement Plot

Description

Generates a ggplot2 visualization showing the conditional probability of agreement as a function of the true latent trait, with pointwise and/or simultaneous confidence bands.

Usage

make_cpaplot(
  plotting_data,
  ci_type,
  display,
  export_pdf,
  plot_path,
  horizontal_ticks,
  font_size
)

Arguments

plotting_data

A list containing the following components:

Agreement

Numeric vector of agreement probabilities.

BLUP_x

Numeric vector of BLUP estimates of the true latent trait.

ci_bounds

A list containing confidence interval bounds (see Details).

overall_agreement

Overall agreement probability.

overall_agreement_lo

Lower bound of overall agreement 95% CI.

overall_agreement_up

Upper bound of overall agreement 95% CI.

ci_type

Integer indicating which confidence bounds to display:

0

Both pointwise and simultaneous confidence bands.

1

Pointwise confidence bands only.

2

Simultaneous confidence bands only.

display

Logical; if TRUE, the plot is printed to the current graphics device.

export_pdf

Logical; if TRUE, exports the plot as a PDF file to the specified path.

plot_path

Character string specifying the directory path for PDF export.

Details

The ci_bounds component of plotting_data is a list produced by the function simulate_agreement_ci and may contain:

lo_Agreement and up_Agreement

Pointwise lower and upper confidence bounds.

lo_Agreement_sim and up_Agreement_sim

Simultaneous lower and upper confidence bounds.

Value

Invisibly returns the ggplot object.

Compute Pointwise Confidence Interval Bounds from Simulation Results

Description

Calculates pointwise 95\ using standard deviations from simulation data. The bounds are computed on the logit scale, smoothed using fractional polynomial models, and then transformed back to the probability scale.

Usage

make_pointwise_ci_bounds(BLUP_x, logit_Agreement, logit_Agreement_sims)

Arguments

BLUP_x

Numeric vector of BLUP estimates of the true latent trait.

logit_Agreement

Numeric vector of logit-transformed agreement probabilities.

logit_Agreement_sims

Matrix where the first column contains the individual identifier (idvar) and remaining columns contain logit-transformed agreement values from each simulation iteration.

Value

A list with two components:

lo_Agreement

Numeric vector of lower confidence bounds for agreement probabilities. Only the first observation for each unique individual is populated; remaining values are NA.

up_Agreement

Numeric vector of upper confidence bounds for agreement probabilities. Only the first observation for each unique individual is populated; remaining values are NA.

Compute Simultaneous Confidence Interval Bounds

Description

Calculates simultaneous 95% confidence intervals for agreement probabilities using a critical value derived from simulation-based standardized logit agreements. The bounds are computed on the logit scale, smoothed using fractional polynomial models, and then transformed back to the probability scale.

Usage

make_simultaneous_ci_bounds(
  BLUP_x,
  logit_Agreement,
  SDlogit_Agreement_BLUP,
  crit_value
)

Arguments

BLUP_x

Numeric vector of Best Linear Unbiased Predictor (BLUP) estimates of the true latent trait.

logit_Agreement

Numeric vector of logit-transformed agreement probabilities.

SDlogit_Agreement_BLUP

Numeric vector of standard deviations of logit-transformed agreement probabilities.

crit_value

Numeric scalar representing the critical value for simultaneous confidence bands, obtained as an empirical quantile of simulation-based standardized logit agreements (see find_empirical_quantile()).

Value

A list with two components:

lo_Agreement_sim

Numeric vector of lower simultaneous confidence bounds for agreement probabilities.

up_Agreement_sim

Numeric vector of upper simultaneous confidence bounds for agreement probabilities.

Generate Conditional Probability of Agreement Plot

Description

Creates a visualization of the conditional probability of agreement between two measurement methods as a function of the true latent trait. The function estimates agreement probabilities, computes their variances using the delta method, performs Monte Carlo simulations to construct confidence bands, and generates a plot with optional pointwise and/or simultaneous confidence intervals.

Usage

plot_condProb_agreement(
  idvar,
  BLUP_x,
  V_BLUP_x,
  SD_BLUP_x,
  theta2_1e,
  theta2_0e,
  Vtheta2_1e,
  Vtheta2_0e,
  COVtheta2e,
  sig2_res_y2,
  differential_bias,
  proportional_bias,
  Vproportional_bias,
  Vdifferential_bias,
  COVbias,
  theta1_1e,
  theta1_0e,
  Vtheta1_1e,
  Vtheta1_0e,
  COVtheta1e,
  sig2_res_y1,
  CTLlo,
  CTLup,
  intercept,
  slope,
  nbsimul,
  overall_agreement = NULL,
  overall_agreement_lo = NULL,
  overall_agreement_up = NULL,
  pointwise_ci = FALSE,
  simultaneous_ci = FALSE,
  display = TRUE,
  export_pdf = FALSE,
  plot_path = NULL,
  horizontal_ticks = c(5, 10),
  font_size = 14
)

Arguments

idvar

Numeric or character vector of individual identifiers.

BLUP_x

Numeric vector of Best Linear Unbiased Predictor (BLUP) estimates of the true latent trait.

V_BLUP_x

Numeric vector of variances for BLUP_x estimates.

SD_BLUP_x

Numeric vector of standard deviations for BLUP_x estimates.

theta2_1e

Numeric scalar for slope parameter of y2 residual variance.

theta2_0e

Numeric scalar for intercept parameter of y2 residual variance.

Vtheta2_1e

Numeric scalar for variance of theta2_1e.

Vtheta2_0e

Numeric scalar for variance of theta2_0e.

COVtheta2e

Numeric scalar for covariance between theta2_0e and theta2_1e.

sig2_res_y2

Numeric vector of residual variances for the reference method (y2).

differential_bias

Numeric scalar representing the differential bias estimate between the two methods.

proportional_bias

Numeric scalar representing the proportional bias estimate between the two methods.

Vproportional_bias

Numeric scalar for variance of proportional bias estimate.

Vdifferential_bias

Numeric scalar for variance of differential bias estimate.

COVbias

Numeric scalar for covariance between differential and proportional bias.

theta1_1e

Numeric scalar for slope parameter of y1 residual variance.

theta1_0e

Numeric scalar for intercept parameter of y1 residual variance.

Vtheta1_1e

Numeric scalar for variance of theta1_1e.

Vtheta1_0e

Numeric scalar for variance of theta1_0e.

COVtheta1e

Numeric scalar for covariance between theta1_0e and theta1_1e.

sig2_res_y1

Numeric vector of residual variances for the new method (y1).

CTLlo

Numeric vector specifying the lower clinical tolerance limit.

CTLup

Numeric vector specifying the upper clinical tolerance limit.

intercept

Numeric scalar for the intercept of tolerance limits.

slope

Numeric scalar for the slope of tolerance limits.

nbsimul

Integer specifying the number of Monte Carlo simulations to perform for constructing confidence bands.

overall_agreement

Numeric scalar for overall agreement probability, or NULL if not available. If provided, displayed in the plot subtitle.

overall_agreement_lo

Numeric scalar for lower bound of overall agreement 95% CI, or NULL if not available.

overall_agreement_up

Numeric scalar for upper bound of overall agreement 95% CI, or NULL if not available.

pointwise_ci

Logical; if TRUE, compute pointwise confidence bands. Default is FALSE.

simultaneous_ci

Logical; if TRUE, compute simultaneous confidence bands. Default is FALSE.

display

Logical; if TRUE, the plot is displayed in the current graphics device. Default is TRUE.

export_pdf

Logical; if TRUE, exports the plot as a PDF file to the specified path. Default is FALSE.

plot_path

Character string specifying the directory path for PDF export.

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

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 determines which confidence bands to compute based on the values of pointwise_ci and simultaneous_ci:

The ci_bounds component structure matches the ci_type:

ci_type = 0

Contains lo_Agreement, up_Agreement, lo_Agreement_sim, and up_Agreement_sim.

ci_type = 1

Contains lo_Agreement and up_Agreement only.

ci_type = 2

Contains lo_Agreement_sim and up_Agreement_sim only.

Value

A list with three components:

Agreement

Numeric vector of agreement probabilities for each observation.

ci_bounds

A list containing confidence interval bounds, whose structure depends on the combination of pointwise_ci and simultaneous_ci (see Details).

ci_type

Integer indicating which confidence bounds were computed: 0 (both), 1 (pointwise only), or 2 (simultaneous only).

References

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

Generate Tolerance Limits Plot

Description

Creates a scatter plot showing differences between two methods with tolerance limit boundaries. Points within the clinical tolerance limits are displayed in green, while points outside are displayed in red.

Usage

plot_tolerance_limits(
  BLUP_x,
  difference,
  CTLlo,
  CTLup,
  intercept,
  slope,
  within_limits,
  display = TRUE,
  export_pdf = FALSE,
  plot_path = NULL,
  vertical_ticks = c(5, 7),
  horizontal_ticks = c(5, 10),
  font_size = 14
)

Arguments

BLUP_x

Numeric vector of Best Linear Unbiased Predictor (BLUP) estimates of the true latent trait.

difference

Numeric vector of differences between the two methods (y1 - y2).

CTLlo

Numeric vector specifying the lower clinical tolerance limit.

CTLup

Numeric vector specifying the upper clinical tolerance limit.

intercept

Numeric scalar for the intercept of tolerance limits.

slope

Numeric scalar for the slope of tolerance limits.

within_limits

Logical vector indicating whether each observation falls within the tolerance limits.

display

Logical; if TRUE, the plot is displayed in the current graphics device. Default is TRUE.

export_pdf

Logical; if TRUE, exports the plot as a PDF file named 'tl_plot.pdf' to the specified path. Default is FALSE.

plot_path

Character string specifying the directory path for PDF export.

vertical_ticks

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

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

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.

Value

Invisibly returns a ggplot object. The plot is optionally saved as 'tl_plot.pdf' in the specified directory if export_pdf = TRUE.

Sample Data for Agreement Simulation Iterations

Description

Generates simulated parameter values for a single Monte Carlo iteration in the agreement confidence interval estimation process. The function samples BLUP estimates, bias parameters, and residual variance parameters from their respective distributions, ensuring one sample per individual is drawn and then replicated across all observations for that individual.

Usage

sample_simulation_data(
  bias_mean,
  bias_vcov,
  theta2_mean,
  theta2_vcov,
  theta1_mean,
  theta1_vcov,
  BLUP_x,
  SD_BLUP_x,
  idvar
)

Arguments

bias_mean

Numeric vector of length 2 containing mean values for proportional and differential bias (in that order).

bias_vcov

Numeric 2x2 variance-covariance matrix for bias parameters.

theta2_mean

Numeric vector of length 2 containing mean values for theta2_0e and theta2_1e (intercept and slope for y2 residual variance).

theta2_vcov

Numeric 2x2 variance-covariance matrix for theta2 parameters.

theta1_mean

Numeric vector of length 2 containing mean values for theta1_0e and theta1_1e (intercept and slope for y1 residual variance).

theta1_vcov

Numeric 2x2 variance-covariance matrix for theta1 parameters.

BLUP_x

Numeric vector of Best Linear Unbiased Predictor (BLUP) estimates of the true latent trait.

SD_BLUP_x

Numeric vector of standard deviations for BLUP_x estimates.

idvar

Numeric or character vector of individual identifiers.

Value

A list with five components:

BLUP_x

Numeric vector of simulated BLUP values, length N.

differential_bias

Numeric vector of simulated differential bias values, length N.

proportional_bias

Numeric vector of simulated proportional bias values, length N.

sig2_res_y2

Numeric vector of simulated residual variances for the reference method (y2), length N.

sig2_res_y1

Numeric vector of simulated residual variances for the new method (y1), length N.

Simulate Confidence Intervals for Agreement Probabilities

Description

Performs Monte Carlo simulations to generate confidence interval bounds for conditional agreement probabilities. The function simulates BLUP estimates and variance components, recalculates agreement for each simulation, and constructs either pointwise, simultaneous, or both types of confidence bands.

Usage

simulate_agreement_ci(
  idvar,
  BLUP_x,
  V_BLUP_x,
  SD_BLUP_x,
  bias_mean,
  bias_vcov,
  theta2_mean,
  theta2_vcov,
  theta1_mean,
  theta1_vcov,
  CTLlo,
  CTLup,
  logit_Agreement,
  Vdifferential_bias,
  Vproportional_bias,
  COVbias,
  Vtheta2_0e,
  Vtheta2_1e,
  COVtheta2e,
  Vtheta1_0e,
  Vtheta1_1e,
  COVtheta1e,
  theta2_1e,
  theta1_1e,
  SDlogit_Agreement_BLUP,
  nbsimul,
  ci_type
)

Arguments

idvar

Numeric or character vector of individual identifiers.

BLUP_x

Numeric vector of Best Linear Unbiased Predictor (BLUP) estimates of the true latent trait.

V_BLUP_x

Numeric vector of variances for BLUP_x estimates.

SD_BLUP_x

Numeric vector of standard deviations for BLUP_x estimates.

bias_mean

Numeric vector of length 2 containing mean values for proportional and differential bias (in that order).

bias_vcov

Numeric 2x2 variance-covariance matrix for bias parameters.

theta2_mean

Numeric vector of length 2 containing mean values for theta2_0e and theta2_1e (intercept and slope for y2 residual variance).

theta2_vcov

Numeric 2x2 variance-covariance matrix for theta2 parameters.

theta1_mean

Numeric vector of length 2 containing mean values for theta1_0e and theta1_1e (intercept and slope for y1 residual variance).

theta1_vcov

Numeric 2x2 variance-covariance matrix for theta1 parameters.

CTLlo

Numeric vector specifying the lower clinical tolerance limit.

CTLup

Numeric vector specifying the upper clinical tolerance limit.

logit_Agreement

Numeric vector of observed logit-transformed agreement probabilities.

Vdifferential_bias

Numeric scalar for variance of differential bias estimate.

Vproportional_bias

Numeric scalar for variance of proportional bias estimate.

COVbias

Numeric scalar for covariance between differential and proportional bias.

Vtheta2_0e

Numeric scalar for variance of theta2_0e.

Vtheta2_1e

Numeric scalar for variance of theta2_1e.

COVtheta2e

Numeric scalar for covariance between theta2_0e and theta2_1e.

Vtheta1_0e

Numeric scalar for variance of theta1_0e.

Vtheta1_1e

Numeric scalar for variance of theta1_1e.

COVtheta1e

Numeric scalar for covariance between theta1_0e and theta1_1e.

theta2_1e

Numeric scalar for slope parameter of y2 residual variance.

theta1_1e

Numeric scalar for slope parameter of y1 residual variance.

SDlogit_Agreement_BLUP

Numeric vector of standard deviations of logit-transformed agreement probabilities.

nbsimul

Integer specifying the number of Monte Carlo simulations to perform.

ci_type

Integer indicating which type of confidence bounds to compute:

0

Both pointwise and simultaneous confidence bands.

1

Pointwise confidence bands only.

2

Simultaneous confidence bands only.

Value

A list containing confidence interval bounds. The structure depends on ci_type:

ci_type = 0

Returns pointwise bounds—lo_Agreement, up_Agreement—and simulatneous bounds—lo_Agreement_sim, up_Agreement_sim.

ci_type = 1

Returns pointwise bounds lo_Agreement and up_Agreement only.

ci_type = 2

Returns simultaneous bounds lo_Agreement_sim and up_Agreement_sim only.