Descriptive plots for the assessment of agreement — descriptive.plots • TDIagree

This function implements some basic descriptive plots that can be analysed in the context of agreement. The plots implemented are:

a scatter plot of all the possible paired-measurements of one rater against the other
a boxplot of the measurements per rater and, if it applies, replicate
a histogram of the measurements per rater and, if it applies, replicate
a normal quantile-quantile plot of the measurements per rater and, if it applies, replicate
a histogram of the paired-differences
a normal quantile-quantile plot of the paired-differences

Usage

descriptive.plots(data, y, id, met, rep = NA,
                  plots = c("scatterplot", "boxplot",
                            "histogram.y", "qqplot.y",
                            "histogram.d", "qqplot.d"),
                  rater.col = c("#cc6e5c", "#06402b"), d.col = "lavender",
                  line.col = "red", density.col = "red",
                  scatterplot.xlab = NULL, scatterplot.ylab = NULL,
                  histogram.y.main = NULL, histogram.y.xlab = NULL,
                  qqplot.y.main = NULL,
                  histogram.d.density = TRUE, histogram.d.bw = "nrd0", ...)

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.
plots: name of the descriptive plots to display. The options are: "scatterplot" (a scatter plot of all the possible paired-measurements of one rater against the other), "boxplot" (a boxplot of the measurements per rater and, if it applies, replicate), "histogram.y" (a histogram of the measurements per rater and, if it applies, replicate), "qqplot.y" (a QQ plot of the measurements per rater and, if it applies, replicate), "histogram.d" (a histogram of the paired-differences) and "qqplot.d" (a QQ plot of the paired-differences). This argument is not case-sensitive and is passed to match.arg.
The default value is c("scatterplot", "boxplot", "histogram.y", "qqplot.y", "histogram.d", "qqplot.d"), so all plots are executed by default.
rater.col: colour palette to be used in the plots involving the measurements separated per rater. If neither "boxplot" nor "histogram.y" are selected in plots, this argument is ignored.
The default value is c("#cc6e5c", "#06402b") for the first and second level, respectively, of the variable met in data.
d.col: colour to be used in the histogram involving the paired-differences. If "histogram.d" is not selected in plots, this argument is ignored.
The default value is "lavender".
line.col: colour to be used in the theoretical line added to the scatterplot or the normal quantile-quantile plots. If none of "scatterplot", "qqplot.y", or "qqplot.d" are selected in plots, this argument is ignored.
The default value is "red".
density.col: colour to be used in the density curve added to the histogram involving the paired differences. If "histogram.d" is not selected in plots or histogram.d.density is FALSE, this argument is ignored.
The default value is "red".
scatterplot.xlab: a label to use for the x-axis in the scatterplot. If "scatterplot" is not selected in plots, this argument is ignored.
The default value, NULL, indicates that the label "y" from "1st level of met column" should be used.
scatterplot.ylab: a label to use for the y-axis in the scatterplot. If "scatterplot" is not selected in plots, this argument is ignored.
The default value, NULL, indicates that the label "y" from "2nd level of met column" should be used.
histogram.y.main: overall title for the histograms of the measurements (to be passed to main argument in hist). Notice that all histograms (one per rater and, if it applies, replicate) will have the same title. If "histogram.y" is not selected in plots, this argument is ignored.
The default value, NULL, indicates that the label "\(j\)-th level of met column" should be used in the case of no replicates, where \(j \in\) {1,2}, and the label "\(i\)-th level of rep column" from "\(j\)-th level of met column" should be used in the case of replicates, where \(i \in\) {1,..., number of replicates} and \(j \in\) {1,2}.
histogram.y.xlab: a label to use for the x-axis in the histograms of the measurements (to be passed to xlab argument in hist). Notice that all histograms (one per rater and, if it applies, replicate) will have the same label. If "histogram.y" is not selected in plots, this argument is ignored.
The default value, NULL, indicates that the label "y" should be used.
qqplot.y.main: overall title for the normal quantile-quantile plots of the measurements (to be passed to main argument in qqplot). Notice that all QQ plots (one per rater and, if it applies, replicate) will have the same title. If "qqplot.y" is not selected in plots, this argument is ignored.
The default value, NULL, indicates that the label "\(j\)-th level of met column" should be used in the case of no replicates, where \(j \in\) {1,2}, and the label "\(i\)-th level of rep column" from "\(j\)-th level of met column" should be used in the case of replicates, where \(i \in\) {1,..., number of replicates} and \(j \in\) {1,2}.
histogram.d.density: logical indicating whether the density should be added as a solid curve to the histogram of the paired-differences. If "histogram.d" is not selected in plots, this argument is ignored.
The default value is TRUE.
histogram.d.bw: the smoothing bandwidth to be used in the density curve added to the histogram involving the paired differences (to be passed to bw argument in density). If "histogram.d" is not selected in plots or histogram.d.density is FALSE, this argument is ignored.
The default value is "nrd0".
...: other graphical parameters (to be passed to each plot). To be used calling only one plot for optimal performance.

Value

The desired plots are shown one after the other.

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

descriptive.plots(ex_data, y, subj, rater, replicate, plots = "scatterplot")
descriptive.plots(ex_data, y, subj, rater, replicate, plots = "boxplot",
                  rater.col = c("blue", "red"),
                  names = rep(c("1st rep.", "2nd rep."), 2),
                  xlab = "", main = "Boxplots per rater and replicate")
legend("topright", legend = c("A", "B"), fill = c("blue", "red"))

# non-normal data

# involving the measurements: call par(mfcol = c(4, 2), las = 1)
# for optimal performance
descriptive.plots(AMLad, mrd, id, met, rep, plots = "histogram.y",
                  ylim = c(0, 120), xlim = c(0, 100),
                  breaks = seq(from = 0, to = 100, by = 2.5))
descriptive.plots(AMLad, mrd, id, met, rep, plots = "qqplot.y",
                  ylim = c(0, 8), xlim = c(-3, 3))

# involving the paired-differences: call par(mfrow = c(1, 2), las = 1)
# for optimal performance
descriptive.plots(AMLad, mrd, id, met, rep, plots = "histogram.d",
                  line.col = "darkred", density.col = "darkred",
                  histogram.d.bw = 2,
                  ylim = c(0, 0.15), breaks = seq(-20, 100, 5),
                  xlab = "Paired-differences", main = "")
descriptive.plots(AMLad, mrd, id, met, rep, plots = "qqplot.d",
                  ylim = c(-2, 8), xlim = c(-4, 4), main = "")