BC_limits: Limits for Box-Cox Transformed Data

Description

Box Cox transformation of data to normality; reference limits are found using golden section search.

Usage

BC_limits(X, perc=0.95, cover=0.9, censor = 0, winsor=0,
          bottom=-3, top=3, epsilon=0.0001, neff=NA, CI_corrfac=NA,
          printem=FALSE)

Value

A list containing the following components:

bestr: the maximized QQ correlation coefficient.
bestpow: the fitted Box Cox power.
bestxform: the fitted Box Cox transform of the data.
lower: the lower reference limit and CI on the original scale.
upper: the upper reference limit and CI on the original scale.
BClower: the lower reference limits and CI on the transformed scale.
BCupper: the upper reference limits and CI on the transformed scale.
meanof: the mean of the Box-Cox transform.
sdof: the sd of the Box-Cox transform.
intercept: the intercept of the fitted QQ regression.
slope: the slope of the fitted QQ regression.
Pval: the P value of the QQ correlation.

Arguments

X: the numeric data vector to be transformed.
perc: optional (default of 0.95) - the two-sided coverage of the reference range computed.
cover: optional (default of 0.9) - the confidence level of the CI computed for the reference limits.
censor: optional (default of 0) - the number of left-censored readings
winsor: optional (default of 0) - the number winsorised in each tail
bottom: optional (default of -3) - the smallest Box-Cox power to be considered.
top: optional (default of 3) - the largest Box-Cox power to be considered.
epsilon: optional (default of 0.0001) - a tolerance limit for convergence.
neff: optional (default of NA) - effective sample size, computed by the code but can be overridden.
CI_corrfac: optional (default of NA) - correction factor for CIs, computed by code but can be overridden.
printem: optional - if TRUE, routine will print out results as a message.

Author

Douglas M. Hawkins, Jessica J. Kraker krakerjj@uwec.edu

Details

The function fits the Box-Cox transformation by finding the exponent that maximizes the QQ correlation coefficient. Having done so, it

calculates the reference limits and confidence intervals of the transformed data and
then transforms them back to the original scale. The QQ analysis may incorporate censoring or winsorizing if appropriate.

References

Hawkins DM, Esquivel RN (2024). A Quantile-Quantile Toolbox for Reference Intervals. The Journal of Applied Laboratory Medicine, 9:2, 357-370.

Examples

Run this code

# parameters
mul    <- 3.6
sigmal <- 0.75

# replicable randomization
set.seed(1069)
X      <- exp(mul + sigmal*rnorm(120))

# evaluate and review
BC_results <- BC_limits(X, printem=TRUE)
BC_results$bestpow
BC_results$bestr
# original-scale limits
BC_results$lower[1]; BC_results$upper[1]
cat("\nWith 90% [default] confidence, the lower limit is between",
    signif(BC_results$lower[2],5), "and", signif(BC_results$lower[3],5),
    ";\n while the upper limit is between",
    signif(BC_results$upper[2],5),"and",signif(BC_results$upper[3],5),".\n\n")

# adjust to have heavy tails
HT     <- X
HT[c(1,2,3,4)] <- HT[c(1,2,3,4)] * c(0.5, 0.5, 2, 2)

# evaluate and review
BC_HT_results <- BC_limits(HT)
BC_HT_results$lower; BC_HT_results$upper
# winsorized
BC_HT_wins_results <- BC_limits(HT, winsor=3)
BC_HT_wins_results$lower; BC_HT_wins_results$upper

Run the code above in your browser using DataLab