ba: Bland-Altman statistics with confidence intervals

In matrixCorr: Collection of Correlation and Association Estimators

Bland-Altman statistics with confidence intervals

Description

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.

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.

Usage

ba(
  group1,
  group2,
  loa_multiplier = 1.96,
  mode = 1L,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE
)

## S3 method for class 'ba'
print(
  x,
  digits = 3,
  ci_digits = 3,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

## S3 method for class 'ba'
summary(object, digits = 3, ci_digits = 3, ...)

## S3 method for class 'summary.ba'
print(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

## S3 method for class '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,
  ...
)

Arguments

group1, group2	Numeric vectors of equal length.
loa_multiplier	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.
mode	Integer; 1 uses group1 - group2, 2 uses group2 - group1.
conf_level	Confidence level for CIs (default 0.95).
n_threads	Integer \geq 1. Number of OpenMP threads. Defaults to getOption("matrixCorr.threads", 1L).
verbose	Logical; if TRUE, prints how many OpenMP threads are used.
x	A "ba" object.
digits	Number of digits for estimates (default 3).
ci_digits	Number of digits for CI bounds (default 3).
n	Optional row threshold for compact preview output.
topn	Optional number of leading/trailing rows to show when truncated.
max_vars	Optional maximum number of visible columns; NULL derives this from console width.
width	Optional display width; defaults to getOption("width").
show_ci	One of "yes" or "no".
...	Passed to ggplot2::theme() (ggplot path) or plot().
object	A "ba" object.
title	Plot title.
subtitle	Optional subtitle. If NULL, shows n and LoA summary.
point_alpha	Point transparency.
point_size	Point size.
line_size	Line width for mean/LoA.
shade_ci	Logical; if TRUE, draw shaded CI bands instead of 6 dashed lines.
shade_alpha	Transparency of CI bands.
smoother	One of "none", "loess", "lm" to visualize proportional bias.
symmetrize_y	Logical; if TRUE, y-axis centered at mean difference with symmetric limits.
show_value	Logical; included for a consistent plotting interface. Bland-Altman plots do not overlay numeric cell values, so this argument currently has no effect.

Details

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.

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

Value

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

Author(s)

Thiago de Paula Oliveira

References

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.

See Also

print.ba, plot.ba, ccc,ccc_rm_ustat, ccc_rm_reml

Examples

set.seed(1)
x <- rnorm(100, 100, 10)
y <- x + rnorm(100, 0, 8)
fit_ba <- ba(x, y)
print(fit_ba)
plot(fit_ba)

matrixCorr documentation built on April 18, 2026, 5:06 p.m.