TDI: TDI estimation and inference
In TDIagree: Assessment of Agreement using the Total Deviation Index
TDI R Documentation
TDI estimation and inference
Description
This function implements the estimation of the TDI and its corresponding 100(1-\alpha)\% upper bound (UB),
where \alpha is the significance level, using the methods proposed by Choudhary (2007),
Escaramis et al. (2010), Choudhary (2010) and Perez-Jaume and Carrasco (2015) in the case of two raters.
See Details and References for further information about these methods.
Usage
TDI(data, y, id, met, rep = NA,
method = c("Choudhary P", "Escaramis et al.",
"Choudhary NP", "Perez-Jaume and Carrasco"),
p = 0.9, ub = TRUE, boot.type = c("differences", "cluster"),
type = 8, R = 10000, dec.p = 2, dec.est = 3,
choose.model.ch.p = TRUE, var.equal = TRUE,
choose.model.es = TRUE, int = FALSE, tol = 10^(-8), add.es = NULL,
alpha = 0.05)
Arguments
data
name of the dataset, of class data.frame, containing at least 3 columns (quantitative measurement, subject effect, rater effect).
y
quantitative measurement column name.
id
subject effect column name. The corresponding column of data must be a factor.
met
rater effect column name. The corresponding column of data must be a factor.
rep
replicate effect column name. When there are no replicates the user should use rep = NA. When there are replicates, the corresponding column of data must be a factor.
The default value is NA.
method
name of the method(s) to estimate the TDI and UB. The options are:
"Choudhary P" (Choudhary, 2007), "Escaramis et al." (Escaramis et al., 2010),
"Choudhary NP" (Choudhary, 2010) and "Perez-Jaume and Carrasco" (Perez-Jaume and Carrasco, 2015).
This argument is not case-sensitive and is passed to match.arg.
The default value is c("Choudhary P", "Escaramis et al.", "Choudhary NP", "Perez-Jaume and Carrasco"), so all approaches are executed by default.
p
a value or vector of the proportion(s) for estimation of the TDI, where 0<p<1. Commonly, p\geq 0.80.
The default value is 0.90.
ub
logical asking whether the UBs should be computed.
The default value is TRUE.
boot.type
name of the bootstrap approach(es) to be used in the method of Perez-Jaume and Carrasco (2015). There are two
different options when there are replicates: to bootstrap the vector of the within-subject differences ("differences")
or to bootstrap at subject level ("cluster"). This is, not all the differences coming from the same subject
need to be bootstrapped together in the first one but all the measurements from the same subjects have to be bootstrapped
together in the second one. This argument is passed to match.arg
The default value is c("differences", "cluster"), so all approaches are executed by default.
type
in the method of Perez-Jaume and Carrasco (2015), a quantile is calculated to obtain the estimation of the TDI. This argument is an integer
between 1 and 9 selecting one of the nine quantile algorithms (to be passed to quantile).
We recommend 8 for continuous data and 3 for discrete data.
The default value is 8.
R
in the method of Perez-Jaume and Carrasco (2015), bootstrap is used for the estimation of the UB.
This argument chooses the number of bootstrap replicates (to be passed to boot).
The default value is 10000.
dec.p
number of decimals to display for p in the method print.tdi.
The default value is 2.
dec.est
number of decimals to display for the estimates in the method print.tdi. Up to 4 decimals.
The default value is 3.
choose.model.ch.p
in the parametric method of Choudhary (2007) two methods can be fit, one with equal residual homoscedasticity
between raters and one with unequal residual homoscedasticity. This argument, if TRUE, chooses the
model with the minimum AIC. If FALSE, the argument var.equal must be specified.
The default value is TRUE.
var.equal
logical asking if there is residual homoscedasticity between raters to choose the model in the parametric method of Choudhary (2007).
If choose.model.ch.p is set to TRUE, this argument is ignored.
The default value is TRUE.
choose.model.es
in the method of Escaramis et al. (2010) two methods can be fit, one including the subject–rater interaction
and one that does not. The model with interaction only applies to data with replicates. This argument, if TRUE, chooses the
model with the minimum AIC. If FALSE, the argument int must be specified.
The default value is TRUE.
int
logical asking if there is interaction between subjects and methods to choose the model in the method of Escaramis et al. (2010).
The model with interaction only applies to data with replicates. If choose.model.es is set to TRUE, this argument is ignored.
The default value is FALSE.
tol
tolerance to be used in the method of Escaramis et al. (2010).
The default value is 10^(-8).
add.es
name of the columns in data that will be added to the model (as fixed effects) of the method of Escaramis et al. (2010). It must be passed as a column
name or vector of column names.
The default value, NULL, indicates that no extra variables are to be added in the model.
alpha
significance level for inference on the TDI.
The default value is 0.05.
Details
The methods of Choudhary (2007) and Escaramis et al. (2010) are parametric methods based on linear mixed models
that assume normality of the data and linearity between the response and the effects (subjects, raters and
random errors). The linear mixed models are fitted using the function lme from the nlme package.
The methods of Choudhary (2010) and Perez-Jaume and Carrasco (2015) are non-parametric methods
based on the estimation of quantiles of the absolute value of the differences between raters. Non-parametric
methods are recommended when dealing with skewed data or other non-normally distributed data, such as count data.
In situations of normality, parametric methods are recommended. See References for further details.
Value
An object of class tdi, which is a list with five components:
resultan object of class data.frame with the TDI estimates and UBs of the methods specified for every proportion.
fitted.modelsa list with the fitted models of the parametric methods of Choudhary (2007) and Escaramis et al. (2010).
paramsa list with the values dec.est, dec.p, ub, method and alpha to be used in the method print.tdi
and in the method plot.tdi.
data.longan object of class data.frame with columns y, id, met (and rep if it applies) with the values of the measurement, subject identifiers,
rater (and replicate number if it applies) from the original data frame provided.
data.widean object of class data.frame with either:
columns id, y_met1, y_met2 (in the case of no replicates) with the measurements of each method.
columns id, y_met1rep1,..., y_met1repm, y_met2rep1,..., y_met2repm, with the measurements of each method and each replicate, where m is the number of replicates.
Numbers 1 and 2 after met correspond to the first and second level of the column met in data, respectively.
Numbers 1,..., m after rep correspond to the first,..., m-th level of the column rep in data, respectively.
References
Efron, B., & Tibshirani, R. (1993). An Introduction to the Bootstrap; Chapman and Hall. Inc.: New York, NY, USA, 914.
Lin, L. I. K. (2000). Total deviation index for measuring individual agreement with applications in laboratory performance and bioequivalence. Statistics in Medicine, 19(2):255-270.
Choudhary, P. K. (2007). A tolerance interval approach for assessment of agreement with left censored data. Journal of Biopharmaceutical Statistics, 17(4), 583-594.
Escaramis, G., Ascaso, C., & Carrasco, J. L. (2010). The total deviation index estimated by tolerance intervals to evaluate the concordance of measurement devices. BMC Medical Research Methodology, 10, 1-12.
Choudhary, P. K. (2010). A unified approach for nonparametric evaluation of agreement in method comparison studies. The International Journal of Biostatistics, 6(1).
Perez‐Jaume, S., & Carrasco, J. L. (2015). A non‐parametric approach to estimate the total deviation index for non‐normal data. Statistics in Medicine, 34(25), 3318-3335.
See Also
print.tdi, plot.tdi
Examples
# normal data, parametric methods more suitable
set.seed(2025)
n <- 100
mu.ind <- rnorm(n, 0, 7)
epsA1 <- rnorm(n, 0, 3)
epsA2 <- rnorm(n, 0, 3)
epsB1 <- rnorm(n, 0, 3)
epsB2 <- rnorm(n, 0, 3)
y_A1 <- 50 + mu.ind + epsA1 # rater A, replicate 1
y_A2 <- 50 + mu.ind + epsA2 # rater A, replicate 2
y_B1 <- 40 + mu.ind + epsB1 # rater B, replicate 1
y_B2 <- 40 + mu.ind + epsB2 # rater B, replicate 2
ex_data <- data.frame(y = c(y_A1, y_A2, y_B1, y_B2),
rater = factor(rep(c("A", "B"), each = 2*n)),
replicate = factor(rep(rep(1:2, each = n), 2)),
subj = factor(rep(1:n, 4)))
tdi <- TDI(ex_data, y, subj, rater, replicate, p = c(0.8, 0.9),
method = c("Choudhary P", "Escaramis et al.",
"Choudhary NP", "Perez-Jaume and Carrasco"),
boot.type = "cluster", R = 1000)
tdi$result
tdi$fitted.models
tdi$data.long
tdi$data.wide
# non-normal data, non-parametric methods more suitable
tdi.aml <- TDI(AMLad, mrd, id, met, rep, p = c(0.85, 0.95), boot.type = "cluster",
dec.est = 4, R = 1000)
tdi.aml$result
tdi.aml$fitted.models
tdi.aml$data.long
tdi.aml$data.wide
TDIagree documentation built on June 18, 2025, 9:10 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| TDI | R Documentation |
TDI estimation and inference
Description
This function implements the estimation of the TDI and its corresponding 100(1-\alpha)\% upper bound (UB),
where \alpha is the significance level, using the methods proposed by Choudhary (2007),
Escaramis et al. (2010), Choudhary (2010) and Perez-Jaume and Carrasco (2015) in the case of two raters.
See Details and References for further information about these methods.
Usage
TDI(data, y, id, met, rep = NA,
method = c("Choudhary P", "Escaramis et al.",
"Choudhary NP", "Perez-Jaume and Carrasco"),
p = 0.9, ub = TRUE, boot.type = c("differences", "cluster"),
type = 8, R = 10000, dec.p = 2, dec.est = 3,
choose.model.ch.p = TRUE, var.equal = TRUE,
choose.model.es = TRUE, int = FALSE, tol = 10^(-8), add.es = NULL,
alpha = 0.05)
Arguments
data |
name of the dataset, of class |
y |
quantitative measurement column name. |
id |
subject effect column name. The corresponding column of |
met |
rater effect column name. The corresponding column of |
rep |
replicate effect column name. When there are no replicates the user should use |
method |
name of the method(s) to estimate the TDI and UB. The options are:
|
p |
a value or vector of the proportion(s) for estimation of the TDI, where |
ub |
logical asking whether the UBs should be computed. |
boot.type |
name of the bootstrap approach(es) to be used in the method of Perez-Jaume and Carrasco (2015). There are two
different options when there are replicates: to bootstrap the vector of the within-subject differences ( |
type |
in the method of Perez-Jaume and Carrasco (2015), a quantile is calculated to obtain the estimation of the TDI. This argument is an integer
between 1 and 9 selecting one of the nine quantile algorithms (to be passed to |
R |
in the method of Perez-Jaume and Carrasco (2015), bootstrap is used for the estimation of the UB.
This argument chooses the number of bootstrap replicates (to be passed to |
dec.p |
number of decimals to display for |
dec.est |
number of decimals to display for the estimates in the method |
choose.model.ch.p |
in the parametric method of Choudhary (2007) two methods can be fit, one with equal residual homoscedasticity
between raters and one with unequal residual homoscedasticity. This argument, if |
var.equal |
logical asking if there is residual homoscedasticity between raters to choose the model in the parametric method of Choudhary (2007).
If |
choose.model.es |
in the method of Escaramis et al. (2010) two methods can be fit, one including the subject–rater interaction
and one that does not. The model with interaction only applies to data with replicates. This argument, if |
int |
logical asking if there is interaction between subjects and methods to choose the model in the method of Escaramis et al. (2010).
The model with interaction only applies to data with replicates. If |
tol |
tolerance to be used in the method of Escaramis et al. (2010). |
add.es |
name of the columns in |
alpha |
significance level for inference on the TDI. |
Details
The methods of Choudhary (2007) and Escaramis et al. (2010) are parametric methods based on linear mixed models
that assume normality of the data and linearity between the response and the effects (subjects, raters and
random errors). The linear mixed models are fitted using the function lme from the nlme package.
The methods of Choudhary (2010) and Perez-Jaume and Carrasco (2015) are non-parametric methods
based on the estimation of quantiles of the absolute value of the differences between raters. Non-parametric
methods are recommended when dealing with skewed data or other non-normally distributed data, such as count data.
In situations of normality, parametric methods are recommended. See References for further details.
Value
An object of class tdi, which is a list with five components:
resultan object of class
data.framewith the TDI estimates and UBs of the methods specified for every proportion.fitted.modelsa list with the fitted models of the parametric methods of Choudhary (2007) and Escaramis et al. (2010).
paramsa list with the values
dec.est,dec.p,ub,methodandalphato be used in the methodprint.tdiand in the methodplot.tdi.data.longan object of class
data.framewith columns y, id, met (and rep if it applies) with the values of the measurement, subject identifiers, rater (and replicate number if it applies) from the original data frame provided.data.widean object of class
data.framewith either:columns id, y_met1, y_met2 (in the case of no replicates) with the measurements of each method.
columns id, y_met1rep1,..., y_met1rep
m, y_met2rep1,..., y_met2repm, with the measurements of each method and each replicate, wheremis the number of replicates.
Numbers 1 and 2 after met correspond to the first and second level of the column met in data, respectively. Numbers 1,...,
mafter rep correspond to the first,...,m-th level of the column rep in data, respectively.
References
Efron, B., & Tibshirani, R. (1993). An Introduction to the Bootstrap; Chapman and Hall. Inc.: New York, NY, USA, 914.
Lin, L. I. K. (2000). Total deviation index for measuring individual agreement with applications in laboratory performance and bioequivalence. Statistics in Medicine, 19(2):255-270.
Choudhary, P. K. (2007). A tolerance interval approach for assessment of agreement with left censored data. Journal of Biopharmaceutical Statistics, 17(4), 583-594.
Escaramis, G., Ascaso, C., & Carrasco, J. L. (2010). The total deviation index estimated by tolerance intervals to evaluate the concordance of measurement devices. BMC Medical Research Methodology, 10, 1-12.
Choudhary, P. K. (2010). A unified approach for nonparametric evaluation of agreement in method comparison studies. The International Journal of Biostatistics, 6(1).
Perez‐Jaume, S., & Carrasco, J. L. (2015). A non‐parametric approach to estimate the total deviation index for non‐normal data. Statistics in Medicine, 34(25), 3318-3335.
See Also
print.tdi, plot.tdi
Examples
# normal data, parametric methods more suitable
set.seed(2025)
n <- 100
mu.ind <- rnorm(n, 0, 7)
epsA1 <- rnorm(n, 0, 3)
epsA2 <- rnorm(n, 0, 3)
epsB1 <- rnorm(n, 0, 3)
epsB2 <- rnorm(n, 0, 3)
y_A1 <- 50 + mu.ind + epsA1 # rater A, replicate 1
y_A2 <- 50 + mu.ind + epsA2 # rater A, replicate 2
y_B1 <- 40 + mu.ind + epsB1 # rater B, replicate 1
y_B2 <- 40 + mu.ind + epsB2 # rater B, replicate 2
ex_data <- data.frame(y = c(y_A1, y_A2, y_B1, y_B2),
rater = factor(rep(c("A", "B"), each = 2*n)),
replicate = factor(rep(rep(1:2, each = n), 2)),
subj = factor(rep(1:n, 4)))
tdi <- TDI(ex_data, y, subj, rater, replicate, p = c(0.8, 0.9),
method = c("Choudhary P", "Escaramis et al.",
"Choudhary NP", "Perez-Jaume and Carrasco"),
boot.type = "cluster", R = 1000)
tdi$result
tdi$fitted.models
tdi$data.long
tdi$data.wide
# non-normal data, non-parametric methods more suitable
tdi.aml <- TDI(AMLad, mrd, id, met, rep, p = c(0.85, 0.95), boot.type = "cluster",
dec.est = 4, R = 1000)
tdi.aml$result
tdi.aml$fitted.models
tdi.aml$data.long
tdi.aml$data.wide
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.