Computes Bland-Altman mean difference and limits of agreement (LoA)
between two numeric measurement vectors, including t-based confidence
intervals for the mean difference and for each LoA using 'C++' backend.
If group2 is omitted and group1 is a numeric matrix or data frame with
at least two numeric columns, ba() computes all pairwise contrasts across
methods and returns a pairwise Bland-Altman matrix object.
Note: Lin's concordance correlation coefficient (CCC) is a complementary, single-number summary of agreement (precision + accuracy). It is useful for quick screening or reporting an overall CI, but may miss systematic or magnitude-dependent bias; consider reporting CCC alongside Bland-Altman.
ba(
group1,
group2,
loa_multiplier = 1.96,
mode = 1L,
conf_level = 0.95,
n_threads = getOption("matrixCorr.threads", 1L),
verbose = FALSE
)# S3 method for ba
print(
x,
digits = 3,
ci_digits = 3,
n = NULL,
topn = NULL,
max_vars = NULL,
width = NULL,
show_ci = NULL,
...
)
# S3 method for ba
summary(object, digits = 3, ci_digits = 3, ...)
# S3 method for summary.ba
print(
x,
digits = NULL,
n = NULL,
topn = NULL,
max_vars = NULL,
width = NULL,
show_ci = NULL,
...
)
# S3 method for ba
plot(
x,
title = "Bland-Altman Plot",
subtitle = NULL,
point_alpha = 0.7,
point_size = 2.2,
line_size = 0.8,
shade_ci = TRUE,
shade_alpha = 0.08,
smoother = c("none", "loess", "lm"),
symmetrize_y = TRUE,
show_value = TRUE,
...
)
# S3 method for ba_matrix
print(
x,
digits = 3,
ci_digits = 3,
n = NULL,
topn = NULL,
max_vars = NULL,
width = NULL,
show_ci = NULL,
style = c("pairs", "matrices"),
...
)
# S3 method for ba_matrix
summary(object, digits = 3, ci_digits = 3, ...)
# S3 method for summary.ba_matrix
print(
x,
digits = NULL,
n = NULL,
topn = NULL,
max_vars = NULL,
width = NULL,
show_ci = NULL,
...
)
# S3 method for ba_matrix
plot(
x,
pairs = NULL,
against = NULL,
facet_scales = c("free_y", "fixed"),
title = "Bland-Altman (pairwise)",
point_alpha = 0.6,
point_size = 1.8,
line_size = 0.7,
shade_ci = TRUE,
shade_alpha = 0.08,
smoother = c("none", "loess", "lm"),
show_value = TRUE,
...
)
If group1 and group2 are both supplied, an object of class
"ba" (list) with elements:
means, diffs: numeric vectors
groups: data.frame used after NA removal
n_obs: integer, number of complete pairs used.
based.on: compatibility alias for n_obs.
lower.limit, mean.diffs, upper.limit
lines: named numeric vector (lower, mean, upper)
CI.lines: named numeric vector for CIs of those lines
loa_multiplier, critical.diff
If group2 is omitted and group1 is a wide numeric matrix or data frame,
an object of class "ba_matrix" with pairwise components:
bias: pairwise matrix of Bland-Altman mean differences.
sd_loa: pairwise matrix of SDs of differences.
loa_lower, loa_upper: pairwise matrices of LoA
endpoints.
width: pairwise matrix of LoA widths.
n: integer pairwise matrix of complete-case counts.
mean_ci_low, mean_ci_high: pairwise matrices of CI
bounds for the mean difference.
loa_lower_ci_low, loa_lower_ci_high: pairwise matrices
of CI bounds for the lower LoA.
loa_upper_ci_low, loa_upper_ci_high: pairwise matrices
of CI bounds for the upper LoA.
methods: character vector of analysed method names.
loa_multiplier, mode: calculation settings reused for
every pair.
Numeric vector of paired measurements, or a numeric matrix/data
frame with at least two numeric columns when group2 is omitted.
Optional numeric vector of paired measurements. If omitted,
group1 must be a numeric matrix or data frame and all unordered numeric
column pairs are analysed.
Positive scalar; the multiple of the standard deviation used to define the LoA (default 1.96 for nominal 95\ intervals always use \(t_{n-1,\,1-\alpha/2}\) regardless of this choice.
Integer; 1 uses group1 - group2, 2 uses group2 - group1.
Confidence level for CIs (default 0.95).
Integer \(\geq 1\). Number of OpenMP threads. Defaults to
getOption("matrixCorr.threads", 1L).
Logical; if TRUE, prints how many OpenMP threads are used.
A "ba_matrix" object.
Number of digits for estimates (default 3).
Number of digits for CI bounds (default 3).
Optional row threshold for compact preview output.
Optional number of leading/trailing rows to show when truncated.
Optional maximum number of visible columns; NULL derives this
from console width.
Optional display width; defaults to getOption("width").
One of "yes" or "no".
Passed to ggplot2::theme() (ggplot path) or plot().
A "ba" object.
Plot title.
Optional subtitle. If NULL, shows n and LoA summary.
Point transparency.
Point size.
Line width for mean/LoA.
Logical; if TRUE, draw shaded CI bands instead of 6 dashed lines.
Transparency of CI bands.
One of "none", "loess", "lm" to visualize proportional bias.
Logical; if TRUE, y-axis centered at mean difference with symmetric limits.
Logical; included for a consistent plotting interface. Bland-Altman plots do not overlay numeric cell values, so this argument currently has no effect.
Show the pairwise result as "pairs" or "matrices".
Optional character vector of pair labels to display.
Optional single method name; if supplied, only contrasts involving that method are plotted.
Either "free_y" (default) or "fixed".
Thiago de Paula Oliveira
Given paired measurements \((x_i, y_i)\), Bland-Altman analysis uses
\(d_i = x_i - y_i\) (or \(y_i - x_i\) if mode = 2) and
\(m_i = (x_i + y_i)/2\). The mean difference \(\bar d\) estimates bias.
The limits of agreement (LoA) are \(\bar d \pm z \cdot s_d\), where
\(s_d\) is the sample standard deviation of \(d_i\) and \(z\)
(argument loa_multiplier) is typically 1.96 for nominal 95% LoA.
When group2 is omitted and group1 is a wide numeric matrix or data
frame, the same two-method calculation is applied to every unordered column
pair. The returned pairwise matrices follow the requested mode: with
mode = 1, upper-triangle entries represent row minus column; with
mode = 2, upper-triangle entries represent column minus row.
Confidence intervals use Student's \(t\) distribution with \(n-1\) degrees of freedom, with
Mean-difference CI given by \(\bar d \pm t_{n-1,\,1-\alpha/2}\, s_d/\sqrt{n}\); and
LoA CI given by \((\bar d \pm z\, s_d) \;\pm\; t_{n-1,\,1-\alpha/2}\, s_d\,\sqrt{3/n}\).
Assumptions include approximately normal differences and roughly constant
variability across the measurement range; if differences increase with
magnitude, consider a transformation before analysis. Missing values are
removed pairwise (rows with an NA in either input are dropped before
calling the C++ backend).
Probability of agreement, available through prob_agree, is a
tolerance-based companion to Bland-Altman analysis. Bland-Altman reports bias
and limits of agreement for paired differences. prob_agree() instead uses
the sampling distribution of estimated differences to quantify the
probability that two estimated quantities or curves agree within a
user-specified practical tolerance.
Bland JM, Altman DG (1986). Statistical methods for assessing agreement between two methods of clinical measurement. The Lancet, 307-310.
Bland JM, Altman DG (1999). Measuring agreement in method comparison studies. Statistical Methods in Medical Research, 8(2), 135-160.
print.ba, plot.ba,
ccc, prob_agree, ccc_rm_ustat,
ccc_rm_reml
set.seed(1)
x <- rnorm(100, 100, 10)
y <- x + rnorm(100, 0, 8)
fit_ba <- ba(x, y)
print(fit_ba)
estimate(fit_ba)
tidy(fit_ba)
confint(fit_ba)
plot(fit_ba)
# Pairwise Bland-Altman across 3 methods
set.seed(7)
wide3 <- data.frame(
ref = rnorm(80, 100, 8),
m2 = rnorm(80, 101, 8),
m3 = rnorm(80, 99, 9)
)
fit_ba3 <- ba(wide3)
print(fit_ba3)
summary(fit_ba3)
tidy(fit_ba3)
plot(fit_ba3)
Run the code above in your browser using DataLab