| Title: | Reference Interval Estimation using Real-World Data |
|---|---|
| Description: | Indirect method for the estimation of reference intervals (RIs) using Real-World Data ('RWD') and methods for comparing and verifying RIs. Estimates RIs by applying advanced statistical methods to routine diagnostic test measurements, which include both pathological and non-pathological samples, to model the distribution of non-pathological samples. This distribution is then used to derive reference intervals and support RI verification, i.e., deciding if a specific RI is suitable for the local population. The package also provides functions for printing and plotting algorithm results. See ?refineR for a detailed description of features. Version 1.0 of the algorithm is described in 'Ammer et al. (2021)' <doi:10.1038/s41598-021-95301-2>. Additional guidance is in 'Ammer et al. (2023)' <doi:10.1093/jalm/jfac101>. The verification method is described in 'Beck et al. (2025)' <doi:10.1515/cclm-2025-0728>. |
| Authors: | Matthias Beck [aut, cre] (ORCID: <https://orcid.org/0009-0008-7678-4581>), Tatjana Ammer [aut] (ORCID: <https://orcid.org/0000-0003-2809-0266>), Christopher M Rank [aut], Andre Schuetzenmeister [aut] (ORCID: <https://orcid.org/0000-0002-2964-5502>) |
| Maintainer: | Matthias Beck <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 2.0.0 |
| Built: | 2026-06-04 08:28:30 UTC |
| Source: | https://github.com/cran/refineR |
This package includes the implementation of the refineR algorithm (Ammer et al., 2021) which is an indirect method for the estimation of
reference intervals using Real-World Data (RWD). It takes routine measurements of diagnostic tests, containing pathological and non-pathological samples
as input and uses sophisticated statistical methods to derive a model describing the distribution of the non-pathological samples.
This distribution can then be used to derive reference intervals. Version 2.0.0 added functions to check whether a reference interval is valid for the population from which the RWD originates.
Main function of this package is findRI that takes an input data set and tries to find a model that best explains the non-pathological distribution.
Furthermore, the package offers functions for printing print.RWDRI and plotting plot.RWDRI the results of the algorithm operating on S3-objects of class 'RWDRI'.
Verification is performed with the verifyRI function.
| Package: | refineR |
| Type: | Package |
| Version: | 2.0.0 |
| Date: | 2025-11-05 |
| License: | GPL (>=3) |
| LazyLoad: | yes |
Matthias Beck [email protected], Tatjana Ammer [email protected], Christopher M Rank [email protected], Andre Schuetzenmeister [email protected]
Ammer, T., Schuetzenmeister, A., Prokosch, H.U., Rauh, M., Rank, C.M., Zierk, J. (2021). refineR: A Novel Algorithm for Reference Interval Estimation from Real-World Data. Sci Rep 11, 16023. doi:10.1038/s41598-021-95301-2 Ammer, T., Schützenmeister, A., Rank, C. M., Doyle, K. (2023). Estimation of Reference Intervals from Routine Data Using the refineR Algorithm-A Practical Guide. (2023). J Appl Lab Med 8 (1), 84-91. doi:10.1093/jalm/jfac101 Beck, M., Dufey, F., Ammer, T., Schützenmeister, A., Zierk, J., Rank, C.M., Rauh, M. (2025). VeRUS: verification of reference intervals based on the uncertainty of sampling. Clin Chem Lab Med. doi:10.1515/cclm-2025-0728.
It is possible to use automatically determined grid lines (x=NULL, y=NULL) or specifying the number
of cells x = 3, y = 4 as done by grid. Additionally, x- and y-locations of grid-lines can be specified,
e.g. x = 1:10, y = seq(0,10,2).
addGrid(x = NULL, y = NULL, col = "lightgray", lwd = 1L, lty = 3L)addGrid(x = NULL, y = NULL, col = "lightgray", lwd = 1L, lty = 3L)
x |
(integer, numeric) single integer specifies number of cells, numeric vector specifies vertical grid-lines |
y |
(integer, numeric) single integer specifies number of cells, numeric vector specifies horizontal grid-lines |
col |
(character) color of grid-lines |
lwd |
(integer) line width of grid-lines |
lty |
(integer) line type of grid-lines |
Andre Schuetzenmeister [email protected]
This function aligns vectors by padding with spaces to the right
alignVec(x, digits = 3)alignVec(x, digits = 3)
x |
(numeric or character) vector of values to be aligned |
digits |
(integer) number of digits to be displayed for numeric values |
(character) vector of aligned values
Christopher Rank [email protected]
Function takes the name of a color and converts it into the rgb space. Parameter "alpha" allows to specify the transparency within (0,1), 0 meaning completey transparent and 1 meaning completey opaque. If an RGB-code is provided and alpha != 1, the RGB-code of the transparency adapted color will be returned.
as.rgb(col = "black", alpha = 1)as.rgb(col = "black", alpha = 1)
col |
(character) name of the color to be converted/transformed into RGB-space (code). Only those colors can be used which are part of the set returned by function colors(). Defaults to "black". |
alpha |
(numeric) value specifying the transparency to be used, 0 = completely transparent, 1 = opaque. |
RGB-code
Andre Schuetzenmeister [email protected]
## Not run: # convert character string representing a color to RGB-code using alpha-channel of .25 (75\ as.rgb("red", alpha = .25) # same thing now using the RGB-code of red (alpha=1, i.e. as.rgb("red")) as.rgb("#FF0000FF", alpha = .25) ## End(Not run)## Not run: # convert character string representing a color to RGB-code using alpha-channel of .25 (75\ as.rgb("red", alpha = .25) # same thing now using the RGB-code of red (alpha=1, i.e. as.rgb("red")) as.rgb("#FF0000FF", alpha = .25) ## End(Not run)
Estimate density of distribution employing the R package "ash" using R-wrapper function.
ashDensity(x, ab, nbin, m, kopt = c(2, 1), normToAB = FALSE)ashDensity(x, ab, nbin, m, kopt = c(2, 1), normToAB = FALSE)
x |
(numeric) vector of data points |
ab |
(numeric) vector of lower and higher truncation limit of density estimation |
nbin |
(integer) specifying the number of bins used for density estimation |
m |
(integer) specifying the width of the smoothing kernel(s) used for density estimation |
kopt |
(integer) vector specifying the smoothing kernel |
normToAB |
(logical) specifying if the density is normed to the interval ab or to all data points in x |
(list) with density estimation (x values, y values, m and ab).
Christopher Rank [email protected], Tatjana Ammer [email protected]
One-parameter Box-Cox transformation.
BoxCox(x, lambda)BoxCox(x, lambda)
x |
(numeric) data to be transformed |
lambda |
(numeric) Box-Cox transformation parameter |
(numeric) vector with Box-Cox transformation of x
Andre Schuetzenmeister [email protected]
Calculate costs for a specific combinations of lambda, muVec and sigmaVec.
calculateCostHist( lambda, muVec, sigmaVec, HistData, alpha = 0.01, alphaMcb = 0.1, pNormLookup )calculateCostHist( lambda, muVec, sigmaVec, HistData, alpha = 0.01, alphaMcb = 0.1, pNormLookup )
lambda |
(numeric) transformation parameter for inverse Box-Cox transformation |
muVec |
(numeric) vector of mean values of non-pathological Gaussian distribution in transformed space |
sigmaVec |
(numeric) vector of sd values of non-pathological Gaussian distribution in transformed space |
HistData |
(list) with histogram data generated by function |
alpha |
(numeric) specifying the confidence region used for selection of histgram bins in cost calculation |
alphaMcb |
(numeric) specifying the confidence level defining the maximal allowed counts below asymmetric confidence region |
pNormLookup |
(list) with lookup table for pnormApprox function |
(numeric) vector with (lambda, mu, sigma, P, cost).
Tatjana Ammer [email protected]
Function to calculate the RI from a set of parameters
cdfTruncatedBoxCox(mu, sigma, lambda, shift, RIperc)cdfTruncatedBoxCox(mu, sigma, lambda, shift, RIperc)
mu |
(numeric) mean of the distribution |
sigma |
(numeric) standard deviation of the distribution |
lambda |
(numeric) Box-Cox transformation parameter |
shift |
(numeric) shift of the distribution |
RIperc |
(numeric) vector of percentiles for which the reference interval should be calculated |
(numeric) vector of reference interval values for the given percentiles
Matthias Beck [email protected], Christopher Rank [email protected], Tatjana Ammer [email protected]
Freeman, R. Modarres / Statistics & Probability Letters 76 (2006) P 767
This function checks if the arguments in param are valid
checkInvalidArgs(param, validArgs, marginType, verbose)checkInvalidArgs(param, validArgs, marginType, verbose)
param |
(list) providing non-default parameters for the calculation of the margins |
validArgs |
(character) vector of valid arguments for the calculation of the margins |
marginType |
(character) specifying calculation of the margins: using "VeRUS", or Equivalence Limits ("EL") |
verbose |
(logical) specifying if additional warning messages are printed |
warning message if invalid arguments are found
Matthias Beck [email protected]
Method to summarize the UMS of RIdata and RIcand and checks of the UMs overlap
createVerificationTab(RIperc, marginsRIdata, marginsRIcand)createVerificationTab(RIperc, marginsRIdata, marginsRIcand)
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default c(0.025, 0.975)) |
marginsRIdata |
(data.frame) Margins for the data-derived reference intervals |
marginsRIcand |
(data.frame) Margins for the candidate reference intervals |
(list) containing whether the point estimate and margin overlap tests passed, and the verification table
Matthias Beck [email protected]
The function estimates the start search regions for mu and sigma for each lambda. Further it determines an appropriate region around the main peak 'ab' that is used for all lambdas.
defineSearchRegions(x, lambdaVec, roundingBase, abEst = NULL)defineSearchRegions(x, lambdaVec, roundingBase, abEst = NULL)
x |
(numeric) values specifying data points comprising pathological and non-pathological values |
lambdaVec |
(numeric) transformation parameter for inverse Box-Cox transformation |
roundingBase |
(numeric) describing the rounding base of the dataset |
abEst |
(numeric) vector with already estimated abSearchReg and abHist for second definition of search regions |
(list) with (abEst, search region for mu and sigma)
Tatjana Ammer [email protected]
Helper function to find region around the main peak of a distribution
estimateAB(x)estimateAB(x)
x |
(numeric) vector of data points |
(list) with two numeric vectors with lower and upper bound of region around the main peak used for 1) defining the search regions and 2) estimating the histogram with overlapping bins
Tatjana Ammer [email protected]
The function uses a combination of the area under the curve between valleys and the peak height to detect the main peak.
findMainPeak(x, ab, mStart, withHeight = FALSE, prevPeak = NULL)findMainPeak(x, ab, mStart, withHeight = FALSE, prevPeak = NULL)
x |
(numeric) vector of data points |
ab |
(numeric) vector specifying the lower and higher truncation limit of density estimation |
mStart |
(integer) specifying the width of the smoothing kernel(s) used for density estimation |
withHeight |
(logical) specifying if only the area under the curve (FALSE) or a combination of AUC and peak height (TRUE) should be used to detect the main peak |
prevPeak |
(numeric) specifying the modEst of the previously estimated peak |
(list) with the two numeric values peakInd, modEst, and a density list
Tatjana Ammer [email protected]
Find the index of the peaks and valleys of the density estimation.
findPeaksAndValleys(Dens)findPeaksAndValleys(Dens)
Dens |
(list) with density estimation (x values, y values) |
(list) specifying the index of the peaks and valleys of the density estimation.
Tatjana Ammer [email protected]
The function estimates the optimal parameters lambda, mu and sigma for a raw data set containing pathological and non-pathological values. The optimization is carried out via a multi-level grid search to minimize the cost function (negative log-likelihood with regularization) and to find a model that fits the distribution of the physiological values and thus separates pathological from non-pathological values.
findRI( Data = NULL, model = c("BoxCox", "modBoxCoxFast", "modBoxCox"), NBootstrap = 0, seed = 123, ... )findRI( Data = NULL, model = c("BoxCox", "modBoxCoxFast", "modBoxCox"), NBootstrap = 0, seed = 123, ... )
Data |
(numeric) values specifying data points comprising pathological and non-pathological values |
model |
(character) specifying the applied model (can be either "BoxCox" (default), "modBoxCoxFast" or "modBoxCox"), option "modBoxCoxFast" and "modBoxCox" first runs the original optimization using the Box-Cox transformation, afterwards the modified Box-Cox transformation is utilized and an optimal shift is identified ('fast': only 1 iteration is carried out to find a shift) |
NBootstrap |
(integer) specifying the number of bootstrap repetitions |
seed |
(integer) specifying the seed used for bootstrapping |
... |
additional arguments to be passed to the method |
(object) of class "RWDRI" with parameters optimized
Tatjana Ammer [email protected]
# first example resRI <- findRI(Data = testcase1) print(resRI) plot(resRI, showPathol = FALSE) # second example resRI <- findRI(Data = testcase2) print(resRI, RIperc = c(0.025, 0.5, 0.975)) plot(resRI, showPathol = FALSE) # third example, with bootstrapping resRI <- findRI(Data = testcase3, NBootstrap = 30, seed = 123) print(resRI) getRI(resRI, RIperc = c(0.025, 0.5, 0.975), CIprop = 0.95, pointEst ="fullDataEst") getRI(resRI, RIperc = c(0.025, 0.5, 0.975), CIprop = 0.95, pointEst ="medianBS") plot(resRI) # forth example, without values and pathological distribution in plot function resRI <- findRI(Data = testcase4) print(resRI) plot(resRI, showValue = FALSE, showPathol =FALSE) # fifth example, with bootstrapping resRI <- findRI(Data = testcase5, NBootstrap = 30) plot(resRI, RIperc = c(0.025, 0.5, 0.975), showPathol = FALSE, showCI = TRUE)# first example resRI <- findRI(Data = testcase1) print(resRI) plot(resRI, showPathol = FALSE) # second example resRI <- findRI(Data = testcase2) print(resRI, RIperc = c(0.025, 0.5, 0.975)) plot(resRI, showPathol = FALSE) # third example, with bootstrapping resRI <- findRI(Data = testcase3, NBootstrap = 30, seed = 123) print(resRI) getRI(resRI, RIperc = c(0.025, 0.5, 0.975), CIprop = 0.95, pointEst ="fullDataEst") getRI(resRI, RIperc = c(0.025, 0.5, 0.975), CIprop = 0.95, pointEst ="medianBS") plot(resRI) # forth example, without values and pathological distribution in plot function resRI <- findRI(Data = testcase4) print(resRI) plot(resRI, showValue = FALSE, showPathol =FALSE) # fifth example, with bootstrapping resRI <- findRI(Data = testcase5, NBootstrap = 30) plot(resRI, RIperc = c(0.025, 0.5, 0.975), showPathol = FALSE, showCI = TRUE)
Estimate rounding base of the input data.
findRoundingBase(x)findRoundingBase(x)
x |
(numeric) vector of data points |
(numeric) with estimated rounding base (e.g. 0.001 when rounded to 3 digits)
Christopher Rank [email protected], Tatjana Ammer [email protected]
Generate list with histogram data.
generateHistData(x, ab, roundingBase)generateHistData(x, ab, roundingBase)
x |
(numeric) vector of data points |
ab |
(numeric) vector of lower and higher limit embedding appropriate region with the main peak |
roundingBase |
(numeric) describing the rounding base of the dataset |
(list) with histogram data used in the calculation of cost.
Tatjana Ammer [email protected]
Calculate equivalence limits
getEquivalenceLimits( RI, RIperc = c(0.025, 0.975), CIprop = 0.9, pCVA.exp = 0.5, with.bias = FALSE, n = NULL )getEquivalenceLimits( RI, RIperc = c(0.025, 0.975), CIprop = 0.9, pCVA.exp = 0.5, with.bias = FALSE, n = NULL )
RI |
(numeric) vector of length 2 representing the lower and upper limits of the reference interval |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default c(0.025, 0.975)) |
CIprop |
(numeric) specifying the width of the confidence interval used to determine Equivalence Limits (default 0.9) |
pCVA.exp |
(numeric) value greater than 0 representing the exponent for the calculation of pCV.A |
with.bias |
(logical) value indicating whether to consider bias according to Haekel 2015 |
n |
(numeric) value representing the sample size for consideration of bias |
(data.frame) containing the calculated equivalence limits
Matthias Beck [email protected]
Method to calculate reference intervals (percentiles) for objects of class 'RWDRI'
getRI( x, RIperc = c(0.025, 0.975), CIprop = 0.95, pointEst = c("fullDataEst", "medianBS"), Scale = c("original", "transformed", "zScore"), UMprop = 0.9, ... )getRI( x, RIperc = c(0.025, 0.975), CIprop = 0.95, pointEst = c("fullDataEst", "medianBS"), Scale = c("original", "transformed", "zScore"), UMprop = 0.9, ... )
x |
(object) of class 'RWDRI' |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval |
CIprop |
(numeric) value specifying the central region for estimation of confidence intervals |
pointEst |
(character) specifying the point estimate determination: (1) using the full dataset ("fullDataEst"), (2) calculating the median model from all bootstrap samples ("medianBS"), (2) works only if NBootstrap > 0 |
Scale |
(character) specifying if percentiles are calculated on the original scale ("or") or the transformed scale ("tr") or the z-Score scale ("z") |
UMprop |
(numeric) value specifying the central region for estimation of uncertainty margins |
... |
calcUCMargins argument (logical) disabling the calculation of uncertainty margins when set to FALSE, n argument (integer) specifying the theoretical sample size used for uncertainty margin calculation default (n = 120), asymmetryCorr argument (logical) disabling the asymmetry correction when set to FALSE |
(data.frame) with columns for percentile, point estimate, bootstrap-based confidence intervals and uncertainty margins.
Christopher Rank [email protected], Tatjana Ammer [email protected], Matthias Beck [email protected]
Helper function to get the reference interval from a RWDRI object. For internal use only.
getRIfromRWDRI(RWDRI, RIperc, pointEst)getRIfromRWDRI(RWDRI, RIperc, pointEst)
RWDRI |
(RWDRI) The RWDRI object containing the reference interval information. |
RIperc |
(numeric) The percentiles to interpolate. |
pointEst |
(character) The point estimate to use ("fullDataEst" or "medianBS"). |
(list) A list containing the interpolated reference interval and percentiles.
Calculate uncertainty margins for a reference interval using the asymptotic method
getRIMargins( RI, RIperc = c(0.025, 0.975), UMprop = 0.9, lambda = 0, shift = 0, asymmetryCorr = FALSE, n = 120, verbose = TRUE )getRIMargins( RI, RIperc = c(0.025, 0.975), UMprop = 0.9, lambda = 0, shift = 0, asymmetryCorr = FALSE, n = 120, verbose = TRUE )
RI |
(numeric) vector of length >= 2 representing the lower and upper limits of the reference interval. |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default |
UMprop |
(numeric) value between 0 and 1 representing the confidence level for the uncertainty margins. |
lambda |
(numeric) value representing the power parameter for the Box-Cox transformation. |
shift |
(numeric) value representing the shift parameter for the Box-Cox transformation. |
asymmetryCorr |
(logical) value if the asymmetry correction shall be applied for extremely skewed distributions |
n |
(numeric) value representing the sample size for which the sampling uncertainty shall be taken into account |
verbose |
(logical) specifying if additional warning messages are printed |
(data.frame) containing the calculated uncertainty margins for the reference interval.
Christopher Rank [email protected]
## Not run: getRIMargins(RI = c(12, 65), lambda = 0, shift = 0) getRIMargins(RI = c(12, 65), lambda = 1, shift = 0) the following examples should return NAs with and without asymmetry correction # Next examples should return NAs getRIMargins(RI = c(78.6, 116.7), lambda = 0.30673426, shift = 120.898) getRIMargins(RI = c(78.6, 116.7), lambda = 0.30673426, shift = 120.898, asymmetryCorr = FALSE) ## End(Not run)## Not run: getRIMargins(RI = c(12, 65), lambda = 0, shift = 0) getRIMargins(RI = c(12, 65), lambda = 1, shift = 0) the following examples should return NAs with and without asymmetry correction # Next examples should return NAs getRIMargins(RI = c(78.6, 116.7), lambda = 0.30673426, shift = 120.898) getRIMargins(RI = c(78.6, 116.7), lambda = 0.30673426, shift = 120.898, asymmetryCorr = FALSE) ## End(Not run)
Calculate similarity of two reference intervals
getRISimilarity( RIdata, RIcand, RIperc = c(0.025, 0.975), pointEst = c("fullDataEst", "medianBS"), UMprop = 0.9, Overlap = c("OverlapMargins", "OverlapPointEst"), printResults = TRUE, verbose = TRUE, ... )getRISimilarity( RIdata, RIcand, RIperc = c(0.025, 0.975), pointEst = c("fullDataEst", "medianBS"), UMprop = 0.9, Overlap = c("OverlapMargins", "OverlapPointEst"), printResults = TRUE, verbose = TRUE, ... )
RIdata |
specifying the RI of the local population: (1) (object) of class |
RIcand |
specifying the RI that needs to be verified: (1) (object) of class |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default c(0.025, 0.975)) |
pointEst |
(character) specifying the point estimate determination: (1) using the full dataset ("fullDataEst"), (2) calculating the median model from the bootstrap samples ("medianBS"), (2) works only if NBootstrap > 0 |
UMprop |
(numeric) specifying the confidence level for the uncertainty margins |
Overlap |
(character) specifying the overlap criteria for the verification process. Options are: (1) uncertainty margins overlap "OverlapMargins" and (2) point estimates must be within the uncertainty margins "OverlapPointEst" |
printResults |
(logical) specifying if the results are printed to the console |
verbose |
(logical) specifying if additional warning messages are printed |
... |
arguments to overwrite the default values of the Uncertainty Margin calculation |
(data.frame) containing the similarity of the two reference intervals
Matthias Beck [email protected]
## Not run: example <- list(Mu = 3.41, Sigma = 0.504, Shift = 1, Lambda = 0.06, Method = "manual", roundingBase = NA) class(example) <- "RWDRI" test <- getRISimilarity(example, c(4, 55.5)) getRISimilarity(c(4, 55.5), c(6, 58)) getRISimilarity(c(4, 55.5), c(6, 58), UMprop = 0.95) ## End(Not run)## Not run: example <- list(Mu = 3.41, Sigma = 0.504, Shift = 1, Lambda = 0.06, Method = "manual", roundingBase = NA) class(example) <- "RWDRI" test <- getRISimilarity(example, c(4, 55.5)) getRISimilarity(c(4, 55.5), c(6, 58)) getRISimilarity(c(4, 55.5), c(6, 58), UMprop = 0.95) ## End(Not run)
The function helps to define the search region for P (fraction of non-pathological samples).
getSumForPArea( pLimitMin, pLimitMax, countsPred, HistData, lambda, mu, sigma, pCorr )getSumForPArea( pLimitMin, pLimitMax, countsPred, HistData, lambda, mu, sigma, pCorr )
pLimitMin |
(numeric) vector specifying the lower limits for the regions next to the peak |
pLimitMax |
(numeric) vector specifying the upper limits for the regions next to the peak |
countsPred |
(numeric) vector with the predicted counts |
HistData |
(list) with histogram data generated by function |
lambda |
(numeric) transformation parameter for inverse Box-Cox transformation |
mu |
(numeric) parameter of the mean of non-pathological distribution |
sigma |
(numeric) parameter of the standard deviation of non-pathological distribution |
pCorr |
(numeric) correcting the cumulative probability of the truncated non-pathological distribution |
(list) with two numeric vectors specifying the amount of observed and estimated data points surrounding the peak
Tatjana Ammer [email protected]
This function adapts the list of test arguments based on the margin type and additional test parameters
getVerificationArgs( RIdata, RIcand, RIperc, pointEst = c("fullDataEst", "medianBS"), verbose = TRUE )getVerificationArgs( RIdata, RIcand, RIperc, pointEst = c("fullDataEst", "medianBS"), verbose = TRUE )
RIdata |
specifying the RI of the local population: (1) (object) of class RWDRI or (2) (numeric) representation of reference limits |
RIcand |
specifying the RI that needs to be verified: (1) (object) of class RWDRI or (2) (numeric) representation of reference limits |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default c(0.025, 0.975)) |
pointEst |
(character) specifying the point estimate determination: (1) using the full dataset ("fullDataEst"), (2) calculating the median model from the bootstrap samples ("medianBS"), (2) works only if NBootstrap > 0 |
verbose |
(logical) specifying if additional warning messages are printed |
(list) containing a list with the "RI", "Lambda", "Shift" parameter for RIdata and RIcand each
Matthias Beck [email protected]
Inverse of the one-parameter Box-Cox transformation.
invBoxCox(x, lambda)invBoxCox(x, lambda)
x |
(numeric) data to be transformed |
lambda |
(numeric) Box-Cox transformation parameter |
(numeric) vector with inverse Box-Cox transformation of x
Andre Schuetzenmeister [email protected]
Helper function for grid search for mu and sigma.
optimizeGrid(currentBestParam, paramUnique, iter, sigmLimit = TRUE)optimizeGrid(currentBestParam, paramUnique, iter, sigmLimit = TRUE)
currentBestParam |
(numeric) value specifying the current best value for this parameter |
paramUnique |
(numeric) vector of possible values for this parameter |
iter |
(integer) indicating the number of iteration, as in the first iteration the search region is larger than in the following iterations |
sigmLimit |
(logical) specifiying if parameter is sigma and thus minimum is 0 |
(vector) specifying the new search region fo the parameter to be optimized
Tatjana Ammer [email protected]
Function to approximate the sampling uncertainty of quantiles using the asymptotic method
perc_ci_asymptotic(mu, sigma, n, prob, conf.level)perc_ci_asymptotic(mu, sigma, n, prob, conf.level)
mu |
(numeric) mean of the distribution |
sigma |
(numeric) standard deviation of the distribution |
n |
(numeric) integer value indicating the sample size |
prob |
(numeric) quantile value(s) for which to calculate the confidence interval(s) |
conf.level |
(numeric) confidence level for the interval(s) |
(matrix) of confidence interval(s) of quantiles of the normal distribution
Florian Dufey [email protected]
Serfling RJ. Approximation theorems of mathematical statistics. NY: John Wiley & Sons; 1980:121 p.
## Not run: perc_ci_asymptotic(mu = 0, sigma = 1, n = 120, prob = c(0.025, 0.975), conf.level = 0.9) ## End(Not run)## Not run: perc_ci_asymptotic(mu = 0, sigma = 1, n = 120, prob = c(0.025, 0.975), conf.level = 0.9) ## End(Not run)
Standard plot method for objects of class 'RWDRI'
## S3 method for class 'RWDRI' plot( x, Scale = c("original", "transformed", "zScore"), RIperc = c(0.025, 0.975), Nhist = 60, showMargin = TRUE, showPathol = FALSE, scalePathol = TRUE, showBSModels = FALSE, showValue = TRUE, uncertaintyRegion = c("bootstrapCI", "uncertaintyMargin"), CIprop = 0.95, UMprop = 0.9, pointEst = c("fullDataEst", "medianBS"), colScheme = c("green", "blue"), xlim = NULL, ylim = NULL, xlab = NULL, ylab = NULL, title = NULL, ... )## S3 method for class 'RWDRI' plot( x, Scale = c("original", "transformed", "zScore"), RIperc = c(0.025, 0.975), Nhist = 60, showMargin = TRUE, showPathol = FALSE, scalePathol = TRUE, showBSModels = FALSE, showValue = TRUE, uncertaintyRegion = c("bootstrapCI", "uncertaintyMargin"), CIprop = 0.95, UMprop = 0.9, pointEst = c("fullDataEst", "medianBS"), colScheme = c("green", "blue"), xlim = NULL, ylim = NULL, xlab = NULL, ylab = NULL, title = NULL, ... )
x |
(object) of class 'RWDRI' |
Scale |
(character) specifying if percentiles are shown on the original scale ("or") or the transformed scale ("tr") or the z-Score scale ("z") |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default c(0.025, 0.975)) |
Nhist |
(integer) number of bins in the histogram (derived automatically if not set) |
showMargin |
(logical) specifying if the specified margins, i.e. confidence intervals or uncertainty margins, shall be shown |
showPathol |
(logical) specifying if the estimated pathological distribution shall be shown |
scalePathol |
(logical) specifying if the estimated pathological distribution shall be weighted with the ration of pathol/non-pathol |
showBSModels |
(logical) specifying if the estimated bootstrapping models shall be shown |
showValue |
(logical) specifying if the exact value of the estimated reference intervals shall be shown above the plot |
uncertaintyRegion |
(character) specifying the type of the uncertainty region around point estimates |
CIprop |
(numeric) value specifying the central region for estimation of confidence intervals |
UMprop |
(numeric) value specifying the central region for estimation of uncertainty margins |
pointEst |
(character) specifying the point estimate determination: (1) using the full dataset ("fullDataEst"), (2) calculating the median model from the bootstrap samples ("medianBS"), (2) works only if NBootstrap > 0 |
colScheme |
(character) specifying color scheme of the non-pathological distribution and reference interval; choices are "green" and "blue" |
xlim |
(numeric) vector specifying the limits in x-direction |
ylim |
(numeric) vector specifying the limits in y-direction |
xlab |
(character) specifying the x-axis label |
ylab |
(character) specifying the y-axis label |
title |
(character) specifying plot title |
... |
additional arguments passed forward to other functions |
The applied plot limits in x-direction (xlim) are returned.
Christopher Rank [email protected], Tatjana Ammer [email protected]
Plot method for RI verification
plotRIVerification( mar1, mar2, marginOverlap, Scale = c("original", "transformed", "splitXAxis"), lambda = 0, xlab = NULL, title = NULL, ... )plotRIVerification( mar1, mar2, marginOverlap, Scale = c("original", "transformed", "splitXAxis"), lambda = 0, xlab = NULL, title = NULL, ... )
mar1 |
(data.frame) with output of function getRIMargins() |
mar2 |
(data.frame) with output of function getRIMargins() |
marginOverlap |
(character) vector length of mar1; specifying if and how the margins overlap; options are: "PEOverlap", "MarsOverlap", "noOverlap" |
Scale |
(character) specifying if percentiles are shown on the original scale ("original") or the transformed scale ("transformed") or a split view of the x-axis ("splitXAxis") |
lambda |
(numeric) specifying the power parameter (skewness) of the assumed distribution |
xlab |
(character) specifying the x-axis label |
title |
(character) specifying plot title |
... |
(additional arguments) candLabel (character) specifying the label for the candidate RI; dataLabel (character) specifying the label for the data-derived RI |
(NULL) Instead, a plot is generated.
Christopher Rank [email protected]
Approximate calculation of CDF of normal distribution.
pnormApprox(q, pNormVal, mean = 0, oneOverSd = 1, oneOverH = 10)pnormApprox(q, pNormVal, mean = 0, oneOverSd = 1, oneOverH = 10)
q |
(numeric) vector of quantiles of data points |
pNormVal |
(numeric) vector of lookup table for pNorm |
mean |
(numeric) vector of mean values |
oneOverSd |
(numeric) reciprocal vector of sd values |
oneOverH |
(numeric) defining the precision of the approximation |
(numeric) vector of approximate CDFs of normal distribution.
Christopher Rank [email protected]
Standard print method for objects of class 'RWDRI'
## S3 method for class 'RWDRI' print( x, RIperc = c(0.025, 0.975), uncertaintyRegion = c("bootstrapCI", "uncertaintyMargin"), CIprop = 0.95, UMprop = 0.9, pointEst = c("fullDataEst", "medianBS"), ... )## S3 method for class 'RWDRI' print( x, RIperc = c(0.025, 0.975), uncertaintyRegion = c("bootstrapCI", "uncertaintyMargin"), CIprop = 0.95, UMprop = 0.9, pointEst = c("fullDataEst", "medianBS"), ... )
x |
(object) of class 'RWDRI' |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval |
uncertaintyRegion |
(character) specifying the type of the uncertainty region around point estimates |
CIprop |
(numeric) value specifying the central region for estimation of confidence intervals |
UMprop |
(numeric) value specifying the central region for estimation of uncertainty margins |
pointEst |
(character) specifying the point estimate determination: (1) using the full dataset ("fullDataEst"), (2) calculating the median model from all bootstrap samples ("medianBS"), (2) works only if NBootstrap > 0 |
... |
additional arguments passed forward to other functions. |
No return value. Instead, a summary is printed.
Christopher Rank [email protected]
## Not run: x <- refineR::findRI(refineR::testcase1) print(x, uncertaintyRegion = "bootstrapCI") print(x, uncertaintyRegion = "uncertaintyMargin") ## End(Not run)## Not run: x <- refineR::findRI(refineR::testcase1) print(x, uncertaintyRegion = "bootstrapCI") print(x, uncertaintyRegion = "uncertaintyMargin") ## End(Not run)
This function prints a table showing the fractions of data points that are below, within, and above specified reference intervals. The function handles both lower and upper limits, or just one of them, based on the input.
printDataFractionWithinOutsideRI(tab, RIperc, data)printDataFractionWithinOutsideRI(tab, RIperc, data)
tab |
(dataframe) must contain columns |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default c(0.025, 0.975)) |
data |
(numeric) vector of unknown length, possibly containing NAs |
(NULL) Prints the verification table to the console
Matthias Beck [email protected]
This function prints a formatted similarity table showing reference intervals and maximum sample sizes.
printSimilarityTable(SimilarityTab, RIperc)printSimilarityTable(SimilarityTab, RIperc)
SimilarityTab |
(data.frame) containing the similarity table. Must include:
|
RIperc |
(numeric) value specifying the percentiles, which define the reference interval |
(NULL) Prints the similarity table to the console.
Helper function to print Table Header
printTableHeader(headers, col_widths)printTableHeader(headers, col_widths)
headers |
(character) vector of column headers |
col_widths |
(numeric) vector of column widths |
(NULL) Prints the header to the console.
Matthias Beck [email protected]
Helper function to print Table Rows
printTableRows(rows, col_widths)printTableRows(rows, col_widths)
rows |
(list) of lists containing row data. |
col_widths |
(numeric) vector of column widths. |
(NULL) Prints the rows to the console.
Matthias Beck [email protected]
This function prints a formatted verification table for reference intervals
printVerificationTable(verificationTab, RIperc)printVerificationTable(verificationTab, RIperc)
verificationTab |
(data.frame) containing the verification table. Must include the following columns:
|
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default c(0.025, 0.975)) |
None. Prints the verification table to the console.
## Not run: df <- data.frame( Percentile = c(0.025, 0.975), RICandPointEst = c(12, 65), RICandMarginLow = c(10.9013, 60.2780), RICandMarginHigh = c(13.86800, 72.64152), RIDataPointEst = c(13, 69), RIDataMarginLow = c(11.60130, 63.77848), RIDataMarginHigh = c(14.39861, 74.22152), OverlapPointEst = c(TRUE, TRUE), OverlapMargins = c(TRUE, TRUE) ) RIperc <- c(0.025, 0.975) printVerificationTable(df, RIperc) ## End(Not run)## Not run: df <- data.frame( Percentile = c(0.025, 0.975), RICandPointEst = c(12, 65), RICandMarginLow = c(10.9013, 60.2780), RICandMarginHigh = c(13.86800, 72.64152), RIDataPointEst = c(13, 69), RIDataMarginLow = c(11.60130, 63.77848), RIDataMarginHigh = c(14.39861, 74.22152), OverlapPointEst = c(TRUE, TRUE), OverlapMargins = c(TRUE, TRUE) ) RIperc <- c(0.025, 0.975) printVerificationTable(df, RIperc) ## End(Not run)
This dataset consists of N = 10,000 simulated measurements with 80\ Ground Truth for reference intervals (2.5\
testcase1testcase1
Numeric vector with data points.
This dataset consists of N = 50,000 simulated measurements with 60\ Ground Truth for reference intervals (2.5\
testcase2testcase2
Numeric vector with data points.
This dataset consists of N = 75,000 simulated measurements with 96\ Ground Truth for reference intervals (2.5\
testcase3testcase3
Numeric vector with data points.
This dataset consists of N = 100,000 simulated measurements with 90\ Ground Truth for reference intervals (2.5\
testcase4testcase4
Numeric vector with data points.
This dataset consists of N = 250,000 simulated measurements with 80\ Ground Truth for reference intervals (2.5\
testcase5testcase5
Numeric vector with data points.
Helper function to find optimal parameters lambda, mu and sigma.
testParam( lambdaVec, bestParam, Data, HistData, startValues, NIter, alpha = 0.01, alphaMcb = 0.1 )testParam( lambdaVec, bestParam, Data, HistData, startValues, NIter, alpha = 0.01, alphaMcb = 0.1 )
lambdaVec |
(numeric) transformation parameter for inverse Box-Cox transformation |
bestParam |
(numeric) vector containing best guess for lambda, mu, sigma, P, cost |
Data |
(numeric) values specifying percentiles or data points comprising pathological and non-pathological values |
HistData |
(list) with histogram data |
startValues |
(list) with start search regions for mu and sigma |
NIter |
(integer) specifying the number of iterations for optimized grid-search |
alpha |
(numeric) specifying the confidence region used for selection of histogram bins in cost calculation |
alphaMcb |
(numeric) specifying the confidence level defining the maximal allowed counts below the asymmetric confidence region |
(numeric) vector with best parameters for lambda, mu, sigma, P, cost.
Tatjana Ammer [email protected]
This function verifies the reference intervals based on the provided data.
verifyRI( RIdata, RIcand, RIperc = c(0.025, 0.975), UMprop = 0.9, pointEst = c("fullDataEst", "medianBS"), printResults = TRUE, generatePlot = TRUE, Scale = c("original", "transformed", "splitXAxis"), xlab = NULL, title = NULL, verbose = TRUE, ... )verifyRI( RIdata, RIcand, RIperc = c(0.025, 0.975), UMprop = 0.9, pointEst = c("fullDataEst", "medianBS"), printResults = TRUE, generatePlot = TRUE, Scale = c("original", "transformed", "splitXAxis"), xlab = NULL, title = NULL, verbose = TRUE, ... )
RIdata |
specifying the RI of the local population: (1) (object) of class |
RIcand |
specifying the RI that needs to be verified: (1) (object) of class |
RIperc |
(numeric) value specifying the percentiles, which define the reference interval (default c(0.025, 0.975)) |
UMprop |
(numeric) specifying the width of the confidence interval approximated by the uncertainty margins (default 0.9) |
pointEst |
(character) specifying the point estimate determination: (1) using the full dataset ("fullDataEst"), (2) calculating the median model from the bootstrap samples ("medianBS"), (2) works only if NBootstrap > 0 |
printResults |
(logical) if TRUE, results are printed in the console. |
generatePlot |
(logical) if TRUE, a plot is generated. |
Scale |
(character) specifying the scale of the plot: (1) "original", (2) "transformed", (3) "splitXAxis" |
xlab |
(character) optional x-axis label for the plot |
title |
(character) optional title for the plot |
verbose |
(logical) specifying if additional warning messages are printed |
... |
(list) specifying non-default parameters for the calculation of the margins |
(list) containing the verification results
Matthias Beck [email protected]
## Not run: # standard usecase: # comparison of the RI estimated from the local population with a numeric candidate # RI from, e.g., literature RIdata <- findRI(testcase1) RIcand <- c(10, 20) verifyRI(RIdata, RIcand, RIperc = c(0.025, 0.975)) # Test if two refineR models are equivalent with stricter criteria, i.e., larger n model1 <- list(Mu = 20, Sigma = 11, Shift = 8, Lambda = 1, Method = "manual", roundingBase = NA) model2 <- list(Mu = 3.41, Sigma = 0.504, Shift = 1, Lambda = 0.06, Method = "manual", roundingBase = NA) class(model1) <- class(model2) <- "RWDRI" verifyRI(RIdata = model1, RIcand = model2, UMprop = 0.95, n = 1e4) # verify two numeric RIs verifyRI(RIdata = c(2.4, 28), RIcand = c(3.1, 29.75)) ## End(Not run)## Not run: # standard usecase: # comparison of the RI estimated from the local population with a numeric candidate # RI from, e.g., literature RIdata <- findRI(testcase1) RIcand <- c(10, 20) verifyRI(RIdata, RIcand, RIperc = c(0.025, 0.975)) # Test if two refineR models are equivalent with stricter criteria, i.e., larger n model1 <- list(Mu = 20, Sigma = 11, Shift = 8, Lambda = 1, Method = "manual", roundingBase = NA) model2 <- list(Mu = 3.41, Sigma = 0.504, Shift = 1, Lambda = 0.06, Method = "manual", roundingBase = NA) class(model1) <- class(model2) <- "RWDRI" verifyRI(RIdata = model1, RIcand = model2, UMprop = 0.95, n = 1e4) # verify two numeric RIs verifyRI(RIdata = c(2.4, 28), RIcand = c(3.1, 29.75)) ## End(Not run)