TDIagree (version 0.2.0)

plot.tdi: Bland-Altman plot

Description

This function creates a Bland-Altman plot from Altman and Bland (1983), which is used to evaluate the agreement among the quantitative measures taken by two raters. The plot displays the mean of the measurements from both raters in the x-axis and the differences between the measures taken by the two raters in the y-axis. It can also display the TDI and UB estimates from the call of the function TDI as well as the limits of agreement (LoA) from Bland and Altman (1986).

Usage

# S3 method for tdi
plot(
  x,
  tdi = FALSE,
  ub = FALSE,
  loa = FALSE,
  method = NULL,
  ub.pc = NULL,
  p = NULL,
  loess = FALSE,
  method.col = NULL,
  loa.col = "#c27d38",
  loess.col = "#cd2c35",
  loess.span = 2/3,
  legend = FALSE,
  inset = c(-0.24, 0),
  main = "Bland-Altman plot",
  xlab = "Mean",
  ylab = "Difference",
  xlim = NULL,
  ylim = NULL,
  ...
)

Value

A Bland-Altman plot of the data in x with a solid black line at differences \(=\) 0, with differences considered as first level \(-\) second level of the variable met in the call of the function TDI.

Arguments

x

input object of class tdi resulting from a call of the function TDI.

tdi

logical indicating whether the \(\pm\)TDI estimate(s) should be added to the plot as solid lines.
The default value is FALSE.

ub

logical indicating whether the \(\pm\)UB estimate(s) should be added to the plot as dashed lines.
The default value is FALSE.

loa

logical indicating whether the LoA should be added to the plot as dotted lines.
The default value is FALSE.

method

name of the method(s) for which the TDI or the UB estimates will be added to the plot. If both tdi and ub are set to FALSE, this argument is ignored. This argument is not case-sensitive and is passed to match.arg.
The default value, NULL, indicates that, for the measures specified, all the methods for which the TDI (and/or UB) has been computed in the call of the function TDI are to be added to the plot.

ub.pc

name of the technique for the estimated UB to be added from the method of Perez-Jaume and Carrasco (2015). Possible values are: p_db, n_db, e_db, b_db, p_cb, n_cb, e_cb and b_cb. The bootstrap approach (differences or cluster) is indicated with "db" and "cb" and the strategy (based on percentiles, the normal distribution, the empirical method or the BC\(_a\)) is indicated with "p", "n", "e" and "b".
The default value, NULL, indicates that the first estimated UB is to be added to the plot.

p

value of the proportion for which the TDI and/or UB (depending on the value of the arguments tdi and ub) are to be added to the plot. If both tdi and ub are set to FALSE, this argument is ignored.
The default value, NULL, indicates that only the first proportion passed to the call of the function TDI is to be considered.

loess

logical indicating whether a smooth curve computed by loess.smooth should be added to the plot as a dotdashed curve.
The default value is FALSE.

method.col

colour palette to be used in the drawing of TDIs and/or UBs. A colour should be indicated for every method asked. It is assumed that the colours are passed in the same order as the methods passed to method. If both tdi and ub are set to FALSE, this argument is ignored.
The default value, NULL, indicates that the following palette should be used: "#f3df6c", "#9c964a", "#f4b5bd" and "#85d4e3" corresponding to the options "Choudhary P", "Escaramis et al.", "Choudhary NP" and "Perez-Jaume and Carrasco" of method, respectively.

loa.col

colour to be used in the drawing of the LoA. If loa is set to FALSE, this argument is ignored.
The default value is "#c27d38".

loess.col

colour to be used in the drawing of the loess smooth curve. If loess is set to FALSE, this argument is ignored.
The default value is "#cd2c35".

loess.span

smoothness parameter for loess.smooth.
The default value is 2/3.

legend

logical indicating whether a legend should be added outside the plot. If all tdi, ub and loa are set to FALSE, this argument is ignored.
The default value is FALSE.

inset

specifies how far the legend is inset from the plot margins (to be passed to inset argument in legend).
The default value is c(-0.25, 0), recommended for 24'' screens with default plot window. For 13'' screens, c(-0.34, 0) is recommended.

main

overall title for the plot (to be passed to main argument in plot).
The default value is "Bland-Altman plot".

xlab

a label for the x-axis (to be passed to xlab argument in plot).
The default value is "Mean".

ylab

a label for the y-axis (to be passed to ylab argument in plot).
The default value is "Difference".

xlim

the x limits of the plot (to be passed to xlim argument in plot).
The default value, NULL, indicates that the range of the mean values should be used.

ylim

the y limits of the plot (to be passed to ylim argument in plot).
The default value, NULL, indicates that the range of the differences values should be used.

...

other graphical parameters (to be passed to plot).

Details

The LoA are computed using the formula \(\bar{d}\pm z_{1-\frac{\alpha}{2}}\cdot \text{sd}(d)\), where \(z_{1-\frac{\alpha}{2}}\) is the \((1-\frac{\alpha}{2})\)-th quantile of the standard normal distribution, \(d\) is the vector containing the differences between the two raters and \(\bar{d}\) represents their mean.

References

Altman, D. G., & Bland, J. M. (1983). Measurement in medicine: the analysis of method comparison studies. Journal of the Royal Statistical Society Series D: The Statistician, 32(3), 307-317.

Bland, J. M., & Altman, D. (1986). Statistical methods for assessing agreement between two methods of clinical measurement. The Lancet, 327(8476), 307-310.

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.

Examples

# normal data

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)
plot(tdi)

# enhance plot
plot(tdi, xlim = c(20, 70), ylim = c(-20, 30), tdi = TRUE, ub = TRUE,
     method = c("es", "pe"), ub.pc = "b_cb", loa = TRUE, loa.col = "red",
     legend = TRUE)


# non-normal data

tdi.aml <- TDI(AMLad, mrd, id, met, rep, p = c(0.85, 0.95), boot.type = "cluster",
               dec.est = 4, R = 1000)
plot(tdi.aml)

# enhance plot
plot(tdi.aml, method = c("choudhary p", "pe"), tdi = TRUE, ub = TRUE, legend = TRUE,
     main = "Bland-Altman plot of the MRD")