% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ba.R
\name{ba}
\alias{ba}
\alias{print.ba}
\alias{summary.ba}
\alias{print.summary.ba}
\alias{plot.ba}
\alias{print.ba_matrix}
\alias{summary.ba_matrix}
\alias{print.summary.ba_matrix}
\alias{plot.ba_matrix}
\title{Bland-Altman statistics with confidence intervals}
\usage{
ba(
  group1,
  group2,
  loa_multiplier = 1.96,
  mode = 1L,
  conf_level = 0.95,
  n_threads = getOption("matrixCorr.threads", 1L),
  verbose = FALSE
)

\method{print}{ba}(
  x,
  digits = 3,
  ci_digits = 3,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{summary}{ba}(object, digits = 3, ci_digits = 3, ...)

\method{print}{summary.ba}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{plot}{ba}(
  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,
  ...
)

\method{print}{ba_matrix}(
  x,
  digits = 3,
  ci_digits = 3,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  style = c("pairs", "matrices"),
  ...
)

\method{summary}{ba_matrix}(object, digits = 3, ci_digits = 3, ...)

\method{print}{summary.ba_matrix}(
  x,
  digits = NULL,
  n = NULL,
  topn = NULL,
  max_vars = NULL,
  width = NULL,
  show_ci = NULL,
  ...
)

\method{plot}{ba_matrix}(
  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,
  ...
)
}
\arguments{
\item{group1}{Numeric vector of paired measurements, or a numeric matrix/data
frame with at least two numeric columns when \code{group2} is omitted.}

\item{group2}{Optional numeric vector of paired measurements. If omitted,
\code{group1} must be a numeric matrix or data frame and all unordered numeric
column pairs are analysed.}

\item{loa_multiplier}{Positive scalar; the multiple of the standard deviation used to
define the LoA (default 1.96 for nominal 95\\% agreement). The confidence
intervals always use \eqn{t_{n-1,\,1-\alpha/2}} regardless of this choice.}

\item{mode}{Integer; 1 uses \code{group1 - group2}, 2 uses \code{group2 - group1}.}

\item{conf_level}{Confidence level for CIs (default 0.95).}

\item{n_threads}{Integer \eqn{\geq 1}. Number of OpenMP threads. Defaults to
\code{getOption("matrixCorr.threads", 1L)}.}

\item{verbose}{Logical; if TRUE, prints how many OpenMP threads are used.}

\item{x}{A \code{"ba_matrix"} object.}

\item{digits}{Number of digits for estimates (default 3).}

\item{ci_digits}{Number of digits for CI bounds (default 3).}

\item{n}{Optional row threshold for compact preview output.}

\item{topn}{Optional number of leading/trailing rows to show when truncated.}

\item{max_vars}{Optional maximum number of visible columns; \code{NULL} derives this
from console width.}

\item{width}{Optional display width; defaults to \code{getOption("width")}.}

\item{show_ci}{One of \code{"yes"} or \code{"no"}.}

\item{...}{Passed to \code{ggplot2::theme()} (ggplot path) or \code{plot()}.}

\item{object}{A \code{"ba"} object.}

\item{title}{Plot title.}

\item{subtitle}{Optional subtitle. If NULL, shows n and LoA summary.}

\item{point_alpha}{Point transparency.}

\item{point_size}{Point size.}

\item{line_size}{Line width for mean/LoA.}

\item{shade_ci}{Logical; if TRUE, draw shaded CI bands instead of 6 dashed
lines.}

\item{shade_alpha}{Transparency of CI bands.}

\item{smoother}{One of "none", "loess", "lm" to visualize proportional bias.}

\item{symmetrize_y}{Logical; if TRUE, y-axis centered at mean difference
with symmetric limits.}

\item{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.}

\item{style}{Show the pairwise result as \code{"pairs"} or \code{"matrices"}.}

\item{pairs}{Optional character vector of pair labels to display.}

\item{against}{Optional single method name; if supplied, only contrasts
involving that method are plotted.}

\item{facet_scales}{Either \code{"free_y"} (default) or \code{"fixed"}.}
}
\value{
If \code{group1} and \code{group2} are both supplied, an object of class
\code{"ba"} (list) with elements:
\itemize{
\item \code{means}, \code{diffs}: numeric vectors
\item \code{groups}: data.frame used after NA removal
\item \code{n_obs}: integer, number of complete pairs used.
\item \code{based.on}: compatibility alias for \code{n_obs}.
\item \code{lower.limit}, \code{mean.diffs}, \code{upper.limit}
\item \code{lines}: named numeric vector (lower, mean, upper)
\item \code{CI.lines}: named numeric vector for CIs of those lines
\item \code{loa_multiplier}, \code{critical.diff}
}

If \code{group2} is omitted and \code{group1} is a wide numeric matrix or data frame,
an object of class \code{"ba_matrix"} with pairwise components:
\itemize{
\item \code{bias}: pairwise matrix of Bland-Altman mean differences.
\item \code{sd_loa}: pairwise matrix of SDs of differences.
\item \code{loa_lower}, \code{loa_upper}: pairwise matrices of LoA
endpoints.
\item \code{width}: pairwise matrix of LoA widths.
\item \code{n}: integer pairwise matrix of complete-case counts.
\item \code{mean_ci_low}, \code{mean_ci_high}: pairwise matrices of CI
bounds for the mean difference.
\item \code{loa_lower_ci_low}, \code{loa_lower_ci_high}: pairwise matrices
of CI bounds for the lower LoA.
\item \code{loa_upper_ci_low}, \code{loa_upper_ci_high}: pairwise matrices
of CI bounds for the upper LoA.
\item \code{methods}: character vector of analysed method names.
\item \code{loa_multiplier}, \code{mode}: calculation settings reused for
every pair.
}
}
\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.
If \code{group2} is omitted and \code{group1} is a numeric matrix or data frame with
at least two numeric columns, \code{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.
}
\details{
Given paired measurements \eqn{(x_i, y_i)}, Bland-Altman analysis uses
\eqn{d_i = x_i - y_i} (or \eqn{y_i - x_i} if \code{mode = 2}) and
\eqn{m_i = (x_i + y_i)/2}. The mean difference \eqn{\bar d} estimates bias.
The limits of agreement (LoA) are \eqn{\bar d \pm z \cdot s_d}, where
\eqn{s_d} is the sample standard deviation of \eqn{d_i} and \eqn{z}
(argument \code{loa_multiplier}) is typically 1.96 for nominal 95\% LoA.

When \code{group2} is omitted and \code{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 \code{mode}: with
\code{mode = 1}, upper-triangle entries represent row minus column; with
\code{mode = 2}, upper-triangle entries represent column minus row.

Confidence intervals use Student's \eqn{t} distribution with \eqn{n-1}
degrees of freedom, with
\itemize{
\item Mean-difference CI given by \eqn{\bar d \pm t_{n-1,\,1-\alpha/2}\,
  s_d/\sqrt{n}}; and
\item LoA CI given by \eqn{(\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 \code{NA} in either input are dropped before
calling the C++ backend).

Probability of agreement, available through \code{\link{prob_agree}}, is a
tolerance-based companion to Bland-Altman analysis. Bland-Altman reports bias
and limits of agreement for paired differences. \code{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.
}
\examples{
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)

}
\references{
Bland JM, Altman DG (1986). Statistical methods for assessing agreement
between two methods of clinical measurement. \emph{The Lancet}, 307-310.

Bland JM, Altman DG (1999). Measuring agreement in method comparison studies.
\emph{Statistical Methods in Medical Research}, 8(2), 135-160.
}
\seealso{
\code{\link{print.ba}}, \code{\link{plot.ba}},
\code{\link{ccc}}, \code{\link{prob_agree}}, \code{\link{ccc_rm_ustat}},
\code{\link{ccc_rm_reml}}
}
\author{
Thiago de Paula Oliveira
}
