valytics (version 0.3.0)

ba_analysis: Bland-Altman Analysis for Method Comparison

Description

Performs Bland-Altman analysis to assess agreement between two measurement methods. Calculates bias (mean difference), limits of agreement, and confidence intervals following the approach of Bland & Altman (1986, 1999).

Usage

ba_analysis(
  x,
  y = NULL,
  data = NULL,
  conf_level = 0.95,
  type = c("absolute", "percent"),
  na_action = c("omit", "fail")
)

Value

An object of class c("ba_analysis", "valytics_comparison", "valytics_result"), which is a list containing:

input

List with original data and metadata:

• x, y: Numeric vectors (after NA handling)

• n: Number of paired observations

• n_excluded: Number of pairs excluded due to NAs

• var_names: Named character vector with variable names

results

List with statistical results:

• differences: Numeric vector of differences (y - x or percent)

• averages: Numeric vector of means ((x + y) / 2)

• bias: Mean difference (point estimate)

• bias_se: Standard error of the bias

• bias_ci: Named numeric vector with lower and upper CI for bias

• sd_diff: Standard deviation of differences

• loa_lower: Lower limit of agreement (bias - 1.96 * SD)

• loa_upper: Upper limit of agreement (bias + 1.96 * SD)

• loa_lower_ci: Named numeric vector with CI for lower LoA

• loa_upper_ci: Named numeric vector with CI for upper LoA

settings

List with analysis settings:

• conf_level: Confidence level used

• type: Type of difference calculation

• multiplier: Multiplier for LoA (default: 1.96 for 95\

call

The matched function call.

Arguments

x

Numeric vector of measurements from method 1 (reference method), or a formula of the form method1 ~ method2.

y

Numeric vector of measurements from method 2 (test method). Ignored if x is a formula.

data

Optional data frame containing the variables specified in x and y (or in the formula).

conf_level

Confidence level for intervals (default: 0.95).

type

Type of difference calculation: "absolute" (default) for y - x, or "percent" for 100 * (y - x) / mean.

na_action

How to handle missing values: "omit" (default) removes pairs with any NA, "fail" stops with an error.

Assumptions

The standard Bland-Altman analysis assumes:

• Differences are approximately normally distributed

• No proportional bias (constant bias across the measurement range)

• No repeated measurements per subject

Details

The Bland-Altman method assesses agreement between two quantitative measurements by analyzing the differences against the averages. The key outputs are:

• Bias: The mean difference between methods, indicating systematic difference. A bias significantly different from zero suggests one method consistently measures higher or lower than the other.

• Limits of Agreement (LoA): The interval within which 95\ differences are expected to lie (bias +/- 1.96 x SD). These define the range of disagreement between methods.

• Confidence Intervals: CIs for bias and LoA quantify the uncertainty in these estimates due to sampling variability.

The confidence intervals for limits of agreement are calculated using the exact method from Bland & Altman (1999), which accounts for the uncertainty in both the mean and standard deviation.

References

Bland JM, Altman DG (1986). Statistical methods for assessing agreement between two methods of clinical measurement. Lancet, 1(8476):307-310. tools:::Rd_expr_doi("10.1016/S0140-6736(86)90837-8")

Bland JM, Altman DG (1999). Measuring agreement in method comparison studies. Statistical Methods in Medical Research, 8(2):135-160. tools:::Rd_expr_doi("10.1177/096228029900800204")

See Also

plot.ba_analysis() for visualization, summary.ba_analysis() for detailed summary

Examples

# Simulated method comparison data
set.seed(42)
method_a <- rnorm(50, mean = 100, sd = 15)
method_b <- method_a + rnorm(50, mean = 2, sd = 5)  # Method B has +2 bias

# Basic analysis
ba <- ba_analysis(method_a, method_b)
ba

# Using formula interface with data frame
df <- data.frame(reference = method_a, test = method_b)
ba <- ba_analysis(reference ~ test, data = df)

# Percentage differences
ba_pct <- ba_analysis(method_a, method_b, type = "percent")