Package 'BivRegBLS'

Tolerance Intervals and Errors-in-Variables Regressions in Method Comparison Studies (Bridging Studies)

Description

Assess the agreement in method comparison studies by tolerance intervals and (correlated)-errors-in-variables regressions. The results can then be displayed in an (X,Y) plot or (M,D) plot (Bland-Atman plot). The vertical and horizontal Ordinary Least Square regressions (OLSv, OLSh), the Deming Regression (DR), and the (Correlated)-Bivariate Least Square regressions (BLS and CBLS) can be used with unreplicated or replicated data. The measurement error variances and their ratio (lambda) can be estimated by an unbiased estimator with replicated data. If lambda is unknown and not estimatable, there is no unique solution and all the potential solutions can be calculated from OLSv to OLSh in a (X,Y) plot (extreme solutions), or equivalently from a correlation (between the measurement errors in a Bland-Altman plot) -1 to +1 with the CBLS in a (M,D) plot. The BLS and CBLS are the two main regressions. They provide a table of the estimates (estimates, standard error, confidence intervals and pvalues for separate and joint hypotheses), the coordinates of the joint confidence interval (confidence region, or ellipse), and the four following hyperbolic intervals: the Confidence Intervals (CI), the Confidence Bands (CB), the Predictive Intervals (PI), and the Generalized predictive Intervals (GI). The XY.plot and MD.plot are the two main graphical functions to display an (X,Y) plot or (M,D) plot with the desired results. If one can assume no proportional bias, the (M,D) plot may be simplified by calculating horizontal lines intervals with the beta-expectation tolerance interval (type I) or the beta-gamma content tolerance interval (type II).

Details

Package:	BivRegBLS
Type:	Package
Version:	1.1.1
Date:	2019-10-10
License:	AGPL-3

The most important functions are BLS (Bivariate Least Square regression) and CBLS (Correlated Bivariate Least Square regression). The results can then be plotted with respectively the functions XY.plot and MD.plot. Univariate tolerance intervals (bounded by two straight lines in the (M,D) plot) for the differences by two measurement methods can be obtained by the function MD.horiz.lines.

Note

BivRegBLS was developed with a partnership between the University of Glasgow and Sanofi under a Knowledge Exchange award: BGF lead researcher, MB project manager, and big thanks to the whole project team during this fantastic and wonderful journey: Christophe Agut, Armand Berges, Guy Mathieu, Franck Pellissier, Veronique Onado and Delphine Attonaty.

Author(s)

Bernard G FRANCQ <[email protected]>, Marion BERGER <[email protected]>
Maintainer: Bernard G Francq <[email protected]>

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.
Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.
Francq BG. Errors-in-variables regressions to assess equivalence in method comparison studies. Ph.D. Thesis, UCLouvain, Institute of Statistics, Biostatistics and Actuarial science, Louvain-la-Neuve, Belgium, 2013.

Examples

library(BivRegBLS)
data(SBP)
### Descriptive statistics
res=desc.stat(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
raw.plot(data.plot=res,xname="J",yname="S",graph="XY.bar.SEM")
### BLS regression in an (X,Y) plot
res.BLS=BLS(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10,qx=3,qy=3)
XY.plot(BLS.results=res.BLS,xname="J",yname="S",accept.int=10,accept.int.perc=FALSE)
### CBLS regression in an (M,D) plot
res.CBLS=CBLS(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
MD.plot(results=res.CBLS,xname="J",yname="S",
        accept.int=10,accept.int.perc=FALSE,include.int=TRUE,graph.int=c("CI","GI"))
### Univariate tolerance intervals in an (M,D) plot
res.MD.horiz=MD.horiz.lines(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10,pred.level=0.95)
MD.plot(results=res.MD.horiz,xname="J",yname="S",
        accept.int=10,accept.int.perc=FALSE,include.int=TRUE,graph.horiz.int=c("bTI","bgTI"))

---

Back transforms the results if a logarithmic transformation is used

Description

If the data are log-normal, the user can apply a logarithmic transformation. Then, antilog.pred will automatically back-transform (exponentiate) the data and the predictions (hyperbolic intervals) obtained by the BLS, CBLS, MD.horiz.lines, FullCIs.XY or FullCIs.MD functions.

Usage

antilog.pred(results = NULL, base = 10)

Arguments

results	an object of class BLS, CBLS, MD.horiz.lines, CIs.XY or CIs.MD.
base	a character string or a numeric value. Options available are: 10 (default value) or "e".

Details

antilog.pred is automatically called by the argument antilog in the functions XY.plot or MD.plot.

Value

An object of class BLS, CBLS, MD.horiz.lines, CIs.XY or CIs.MD.

Author(s)

Bernard G FRANCQ

See Also

BLS, CBLS, MD.horiz.lines, FullCIs.XY, FullCIs.MD

Examples

library(BivRegBLS)
data(SBP)
SBPlog=SBP
SBPlog[,2:10]=log(SBPlog[,2:10])
res.BLS.log=BLS(data=SBPlog,xcol=c("J1","J2","J3"),ycol=8:10)
res.BLS=antilog.pred(results=res.BLS.log,base="e")

---

Aromatics petroleum data

Description

Aromatics measurements in light and medium petroleum by HPLC and GC MS.

Usage

data(Aromatics)

Format

A data frame with 35 observations on the following 8 variables:

Sample

a factor with the sample type

Type

a factor with the following levels: HD (Heavy Diesel), LD (Light Diesel), LGO (Light Gas Oil), MGO (Medium Gas Oil).

HPLCmono

a numeric vector with the monoaromatics measurements by HPLC.

GCMSmono

a numeric vector with the monoaromatics measurements by GC MS.

HPLCdi

a numeric vector with the diaromatics measurements by HPLC.

GCMSdi

a numeric vector with the diaromatics measurements by GC MS.

HPLCtri

a numeric vector with the triaromatics measurements by HPLC.

GCMStri

a numeric vector with the triaromatics measurements by GC MS.

Source

C-A B Ferrer, B M Celis, A B Velandia, Development of a methodology to determine the aromatic structural distribution in light and medium petroleum fractions by HPLC. Cienc. Tecnol. Futuro, 2006; 3 (2), 149-162.

References

Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.

Examples

data(Aromatics)
str(Aromatics)
head(Aromatics)

---

Bivariate Least Square regression (BLS)

Description

Estimate the (homoscedastic) Bivariate Least Square regression with unreplicated or replicated data (in a (X,Y) plot).

Usage

BLS(data = NULL, xcol = 1, ycol = 2, var.x = NULL, var.y = NULL,
    df.var.x = Inf, df.var.y = Inf, ratio.var = NULL, conf.level = 0.95,
    pred.level = 0.95, npoints = 1000, qx = 1, qy = 1, xpred = NULL)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
var.x	a numeric variable for the variance of the measurement error of device X if known.
var.y	a numeric variable for the variance of the measurement error of device Y if known.
df.var.x	a numeric variable for the degrees of freedom of the variance of the measurement error of device X if known.
df.var.y	a numeric variable for the degrees of freedom of the variance of the measurement error of device Y if known.
ratio.var	a numeric value for λ, the ratio of the measurement error variances (Y over X) if known.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).
pred.level	a numeric value for the predictive level (expressed between 0 and 1).
npoints	an integer (at least 10) for the number of points to smooth the hyperbolic curves.
qx	an integer to predict the mean of qy Y future values from the mean of qx X values (generalized interval).
qy	an integer to predict the mean of qy Y future values from the mean of qx X values (generalized interval).
xpred	a numeric vector for customized predictions at given X values.

Details

The data argument is mandatory. If the data are unreplicated, then the measurement error variances must be given or their ratio (λ). The confidence level is used for the confidence intervals of the parameters (λ_{XY}, β (slope), α (intercept)), the hyperbolic confidence intervals (the prediction of the expectation of Y for a given X) and the hyperbolic confidence bands. The predictive level is used for the hyperbolic predictive intervals (the prediction of a future Y for a given X) and the hyperbolic generalized intervals (the prediction of the mean of qy future Y values from a given (mean of) X).
The results (Xij, Yik, Xi, Yi, nxi, nyi, variances_x, variances_y) are reordered according to the increasing values of Xi (the X mean values).

Value

A BLS class object, a list including the following elements:

Xij	a table with the (replicated) X measurements (replicates are in columns).
Yik	a table with the (replicated) Y measurements (replicates are in columns).
Xi	a vector with the means of the X measurements.
Yi	a vector with the means of the Y measurements.
nxi	a vector with the number of X replicates per sample (patient).
nyi	a vector with the number of Y replicates per sample (patient).
variances_x	a vector with the variances calculated on the X replicates per sample (patient).
variances_y	a vector with the variances calculated on the Y replicates per sample (patient).
Lambda.XY	a table with the value of λXY and its confidence interval.
Ellipse.BLS	a two columns matrix with the coordinates of the joint confidence interval (confidence region, ellipse) for the parameters (β, α).
Estimate.BLS	a table (data frame) with the estimates of the intercept and the slope, standard error, confidence interval and pvalue (null hypothesis: slope = 1, intercept = 0).
Pred.BLS	a data frame with npoints rows (from the minimum to the maximum of the observed X values) and the following columns: the X values where the predictions are calculated (X0), the Y predicted values (Ypred), the lower and upper bounds of the confidence intervals, predictive intervals, generalized intervals and confidence bands.
xpred.BLS	a data frame with the customized predictions and the same columns than Pred.BLS.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.
Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

CBLS, BLS.fit, BLS.ht

Examples

library(BivRegBLS)
data(SBP)
# BLS regression on replicated data
res.BLS1=BLS(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10,qx=3,qy=3,xpred=c(100,120,140,160))
# BLS regression on unreplicated data with measurement error variances previously estimated
res.BLS2=BLS(data=SBP,xcol=c("J1"),ycol="S1",var.x=80,var.y=50,df.var.x=100,df.var.y=100)

---

Fit a Bivariate Least Square regression (BLS): estimates table

Description

Estimate the (homoscedastic) Bivariate Least Square regression with unreplicated or replicated data: provide the estimates table

Usage

BLS.fit(data = NULL, xcol = 1, ycol = 2, var.x = NULL, var.y = NULL,
    ratio.var = NULL, conf.level = 0.95)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
var.x	a numeric variable for the variance of the measurement error of device X if known.
var.y	a numeric variable for the variance of the measurement error of device Y if known.
ratio.var	a numeric value for λ, the ratio of the measurement error variances (Y over X) if known.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).

Details

The data argument is mandatory. If the data are unreplicated, then the measurement error variances must be given or their ratio (λ). The confidence level is used for the confidence intervals of the parameters (β (slope), α (intercept)).

Value

A table with the estimates of the intercept and the slope, standard error, confidence interval and pvalue (null hypothesis: slope = 1, intercept = 0).

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.
Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

BLS, CBLS

Examples

library(BivRegBLS)
data(SBP)
# BLS regression on replicated data
res1=BLS.fit(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# BLS regression on unreplicated data with measurement error variances previously estimated
res2=BLS.fit(data=SBP,xcol="J1",ycol="S1",var.x=80,var.y=50)

---

Bivariate Least Square regression (BLS)

Description

Estimate the heteroscedastic Bivariate Least Square regression with replicated data or variance functions.

Usage

BLS.ht(data = NULL, xcol = NULL, ycol = NULL, var.x.col = NULL, var.y.col = NULL,
       var.x.formula = NULL, var.y.formula = NULL, nxi.col = NULL, nyi.col = NULL,
       df.var.x.col = NULL, df.var.y.col = NULL, conf.level = 0.95, pred.level = 0.95,
       npoints = 1000, qx = 1, qy = 1, xpred = NULL, tol = 1e-05)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
var.x.col	a numeric or character variable to specify the column with the heteroscedastic variances of X.
var.y.col	a numeric or character variable to specify the column with the heteroscedastic variances of Y.
var.x.formula	a character string with a formula related to X that will be interpreted as a variance function, i.e. var.x.formula="exp(2*X+3)".
var.y.formula	a character string with a formula related to Y that will be interpreted as a variance function, i.e. var.y.formula="exp(2*Y+3)".
nxi.col	a numeric or character variable to specify the column with the number of replicates in X on which the variances were calculated.
nyi.col	a numeric or character variable to specify the column with the number of replicates in Y on which the variances were calculated.
df.var.x.col	a numeric or character variable to specify the column with the degrees of freedom of the heteroscedastic variances in X.
df.var.y.col	a numeric or character variable to specify the column with the degrees of freedom of the heteroscedastic variances in Y.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).
pred.level	a numeric value for the predictive level (expressed between 0 and 1).
npoints	an integer (at least 10) for the number of points to smooth the hyperbolic curves.
qx	an integer to predict the mean of qy Y future values from the mean of qx X values (generalized interval).
qy	an integer value to predict the mean of qy Y future values from the mean of qx X values (generalized interval).
xpred	a numeric vector for customized predictions at given X values.
tol	a numeric variable to change the tolerance for the BLS to converge.

Details

The data argument is mandatory. If the data are unreplicated, then the measurement error variances must be given. The confidence level is used for the confidence intervals of the parameters (β, α), the hyperbolic confidence intervals (the prediction of the expectation of Y for a given X) and the hyperbolic confidence bands. The predictive level is used for the hyperbolic predictive intervals (the prediction of a future Y for a given X) and the hyperbolic generalized intervals (the prediction of the mean of qy future Y values from a given (mean of) X).
The results (Xij, Yik, Xi, Yi, nxi, nyi, variances_x, variances_y) are reordered according to the increasing values of Xi (the X mean values).

Value

A BLS.ht class object, a list including the following elements:

Xij	a table with the (replicated) X measurements (replicates are in columns).
Yik	a table with the (replicated) Y measurements (replicates are in columns).
Xi	a vector with the means of the X measurements.
Yi	a vector with the means of the Y measurements.
nxi	a vector with the number of X replicates per sample (patient).
nyi	a vector with the number of Y replicates per sample (patient).
variances_x	a vector with the variances calculated on the X replicates per sample (patient).
variances_y	a vector with the variances calculated on the Y replicates per sample (patient).
Ellipse.BLS.ht	a two columns matrix with the coordinates of the joint confidence interval (confidence region, ellipse) for the parameters (β, α).
Estimate.BLS.ht	a table (data frame) with the estimates of the intercept and the slope, standard error, confidence interval and pvalue (null hypothesis: slope = 1, intercept = 0).
Pred.BLS.ht	a data frame with npoints rows (from the minimum to the maximum of the observed X values) and the following columns: the X values where the predictions are calculated (X0), the Y predicted values (Ypred), the lower and upper bounds of the confidence interval, predictive interval, generalized interval and confidence bands.
xpred.BLS.ht	a data frame with the customized predictions and the same columns than Pred.BLS.ht.

Note

The prediction interval should be interpreted with caution as it is still under development.

Author(s)

Bernard G FRANCQ

References

Francq BG. Errors-in-variables regressions to assess equivalence in method comparison studies. Ph.D. Thesis, Universite Catholique de Louvain, Institute of Statistics, Biostatistics and Actuarial science, Louvain-la-Neuve, Belgium, 2013.

See Also

BLS

Examples

library(BivRegBLS)
data(SBP)
res.BLS.ht=BLS.ht(data=SBP,xcol=c("J1","J2","J3"),ycol=c("S1","S2","S3"))

---

Correlated Bivariate Least Square regression (CBLS)

Description

Estimate the Correlated Bivariate Least Square regression with replicated data (in a (M,D) plot) where M=(X+Y)/2 and D=Y-X.

Usage

CBLS(data = NULL, xcol = 1, ycol = 2, var.x = NULL, var.y = NULL,
     df.var.x = Inf, df.var.y = Inf, ratio.var = NULL, conf.level = 0.95,
     pred.level = 0.95, npoints = 1000, qx = 1, qy = 1, xpred = NULL)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
var.x	a numeric variable for the variance of the measurement error of device X if known.
var.y	a numeric variable for the variance of the measurement error of device Y if known.
df.var.x	a numeric variable for the degrees of freedom of the variance of the measurement error of device X if known.
df.var.y	a numeric variable for the degrees of freedom of the variance of the measurement error of device Y if known.
ratio.var	a numeric value for λ, the ratio of the measurement error variances (Y over X) if known.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).
pred.level	a numeric value for the predictive level (expressed between 0 and 1).
npoints	an integer (at least 10) for the number of points to smooth the hyperbolic curves.
qx	an integer to predict the mean of qy Y future values from the mean of qx X values (generalized interval).
qy	an integer to predict the mean of qy Y future values from the mean of qx X values (generalized interval).
xpred	a numeric vector for customized predictions at given M values.

Details

The data argument is mandatory. If the data are unreplicated, then the measurement error variances must be given or their ratio (λ) in order to calculate the correlation, ρ_{MD}, between the measurement errors of the differences (on the Y-axis) and the measurement errors of the means (on the X-axis). The confidence level is used for the confidence intervals of the parameters (ρ_{MD}, β (slope), α (intercept)), the hyperbolic confidence intervals (the prediction of the expectation of Y for a given X) and the hyperbolic confidence bands. The predictive level is used for the hyperbolic predictive intervals (the prediction of a future Y for a given X) and the hyperbolic generalized intervals (the prediction of the mean of q future Y values for a given X).

Value

A CBLS class object, a list including the following elements:

Xij	a table with the (replicated) X measurements (replicates are in columns).
Yik	a table with the (replicated) Y measurements (replicates are in columns).
Xi	a vector with the means of the X measurements.
Yi	a vector with the means of the Y measurements.
Mi	a vector with the means ((X+Y)/2) measurements.
Di	a vector with the differences (Y-X) measurements.
nxi	a vector with the number of X replicates per sample (patient).
nyi	a vector with the number of Y replicates per sample (patient).
variances_x	a vector with the variances calculated on the X replicates per sample (patient).
variances_y	a vector with the variances calculated on the Y replicates per sample (patient).
Rho.MD	a table with the value of ρMD (the correlation between the measurement errors of the means and the differences) and its confidence interval.
Ellipse.CBLS	a two columns matrix with the coordinates of the joint confidence interval (confidence region, ellipse) for the parameters (β, α).
Estimate.CBLS	a table (data frame) with the estimates of the intercept and the slope, standard error, confidence interval and pvalue (null hypothesis: slope = 0, intercept = 0).
Pred.CBLS	a data frame with npoints rows (from the minimum to the maximum of the observed X values) and the following columns: the X values where the predictions are calculated (X0), the Y predicted values (Ypred), the lower and upper bounds of the confidence interval, predictive interval, generalized interval and confidence bands.
xpred.CBLS	a data frame with the customized predictions and the same columns than Pred.CBLS.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.

See Also

BLS

Examples

library(BivRegBLS)
data(SBP)
# CBLS regression on replicated data
res.CBLS1=CBLS(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10,qx=3,qy=3,xpred=c(100,120,140,160))
# CBLS regression on unreplicated data with measurement error variances previously estimated
res.CBLS2=CBLS(data=SBP,xcol=c("J1"),ycol="S1",var.x=80,var.y=50,df.var.x=100,df.var.y=100)

---

Fit a Correlated Bivariate Least Square regression (CBLS): estimates table

Description

Estimate the Correlated Bivariate Least Square regression with replicated data in a (M,D) plot (Bland-Altman) where M=(X+Y)/2 and D=Y-X, provide the estimates table.

Usage

CBLS.fit(data = NULL, xcol = 1, ycol = 2, var.x = NULL, var.y = NULL,
     ratio.var = NULL, conf.level = 0.95)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
var.x	a numeric variable for the variance of the measurement error of device X if known.
var.y	a numeric variable for the variance of the measurement error of device Y if known.
ratio.var	a numeric value for λ, the ratio of the measurement error variances (Y over X) if known.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).

Details

The data argument is mandatory. If the data are unreplicated, then the measurement error variances must be given or their ratio (λ) in order to calculate the correlation, ρ_{MD}, between the measurement errors of the differences (on the Y-axis) and the measurement errors of the means (on the X-axis). The confidence level is used for the confidence intervals of the parameters (ρ_{MD}, β (slope), α (intercept)).

Value

A table with the estimates of the intercept and the slope, standard error, confidence interval and pvalue (null hypothesis: slope = 0, intercept = 0).

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.

See Also

BLS, CBLS

Examples

library(BivRegBLS)
data(SBP)
# CBLS regression on replicated data
res1=CBLS.fit(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# CBLS regression on unreplicated data with measurement error variances previously estimated
res2=CBLS.fit(data=SBP,xcol=c("J1"),ycol="S1",var.x=80,var.y=50)

---

Descriptive statistics in method comparison studies

Description

Calculate several descriptive statistics in method comparison studies per device (X and Y) and per type of samples.

Usage

desc.stat(data = NULL, xcol = 1, ycol = 2, IDcol = NULL)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
IDcol	a numeric or character variable to specify the column with the different IDs or type of samples.

Details

If IDcol is null (as by default), the descriptive statistics are calculated for X and Y. Otherwise, the descriptive statistics are calculated for X and Y for each type of sample (each ID) (with a maximum of 30 different IDs). This information is also used to differentiate the observations on a raw plot when the function raw.plot is used. In presence of missing values on X or Y and non-replicates, the rows with missing values are removed. In presence of replicates, the rows with missing values are removed if all Xi or all Yi are missing.
The results (Xij, Yik, Xi, Yi, nxi, nyi, variances_x, variances_y) are reordered according to the increasing values of Xi (the X mean values).

Value

A list including the following elements:

Xij	a table with the (replicated) X measurements (replicates are in columns).
Yik	a table with the (replicated) Y measurements (replicates are in columns).
Xi	a vector with the means of the X measurements.
Yi	a vector with the means of the Y measurements.
IDs	a vector with the different IDs.
nxi	a vector with the number of X replicates per sample (patient).
nyi	a vector with the number of Y replicates per sample (patient).
variances_x	a vector with the variances calculated on the X replicates per sample (patient).
variances_y	a vector with the variances calculated on the Y replicates per sample (patient).
Order.Xi	a vector with the order of the means of the X replicates.
statistics	a table with different descriptive statistics per type of sample (rows): the number of sample (patient), the number of replicates in X and Y, the degrees of freedom of the measurement error variances in X and Y, the mean, the sum of squares (Sxx and Syy), the cross-product (Sxy), the variance, minimum, 1st quartile, median, 3rd quartile, maximum for X and Y, and the Pearson correlation coefficient and its square.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.
Francq BG. Errors-in-variables regressions to assess equivalence in method comparison studies. Ph.D. Thesis, Universite Catholique de Louvain, Institute of Statistics, Biostatistics and Actuarial science, Louvain-la-Neuve, Belgium, 2013.

See Also

lambdas, raw.plot

Examples

library(BivRegBLS)
data(Aromatics)
res=desc.stat(data=Aromatics,xcol=3,ycol=4,IDcol=2)

---

Degrees of freedom by Welch-Satterthwaite

Description

Calculate the degrees of freedom from the Welch-Satterthwaite equation for a linear combination of sample variances.

Usage

df.WS(variances = NULL, k = rep(1, length(variances)), dfs = NULL)

Arguments

variances	a numeric vector for the variances.
k	a numeric vector with the multiplicative constants.
dfs	a numeric vector with the degrees of freedom of each variance.

Details

The variances argument is mandatory while other arguments are optional.

Value

A numeric variable with the degrees of freedom of the linear combination of the variances.

Author(s)

Bernard G FRANCQ

References

Satterthwaite FE. An Approximate Distribution of Estimates of Variance Components. Biometrics Bulletin, 1946, 2: 110-114.
Welch BK. The generalization of "student's" problem when several different population variances are involved. Biometrika, 1947, 34: 28-35.

Examples

df.WS(variances=c(10,15,20),k=c(1.5,2,1.3),dfs=c(8,13,11))

---

Deming Regression

Description

Estimate the Deming Regression (DR) with unreplicated or replicated data.

Usage

DR(data = NULL, xcol = 1, ycol = 2, ratio.var = NULL, conf.level = 0.95)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
ratio.var	a numeric value for λ the ratio of the measurement error variances (Y over X) if known. Otherwise, it may be estimated with replicated data.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).

Details

The BLS regression is more general and includes the Deming Regression. The BLS regression provides more results and should, therefore, be used instead of DR.

Value

A list including the following elements:

Ellipse.DR	a two columns matrix with the coordinates of the joint confidence interval (confidence region, ellipse) for the parameters (β, α).
Estimate.DR	a table (data frame) with the estimates of the intercept and the slope, standard error, confidence interval and pvalue (null hypothesis: slope = 1, intercept = 0). The exact confidence interval for the slope is also given.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems 2014; 134:123-139.
Tan CY, Iglewicz B. Measurement-methods comparisons and linear statistical relationship. Technometrics, 1999; 41(3):192-201.

See Also

BLS

Examples

library(BivRegBLS)
data(SBP)
res.DR=DR(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
res.DR$Estimate.DR
data(Aromatics)
res.DR=DR(data=Aromatics,xcol=3,ycol=4,ratio.var=2)

---

Confidence Intervals by CBLS with all potential solutions

Description

Estimate the Correlated-Bivariate-Least Square regression (CBLS) for all potential solutions from ρMD=-1 to ρMD=1, in a (M,D) plot. This function is analogous to FullCIs.XY estimating all the BLS regressions from OLSv to OLSh in a (X,Y) plot.

Usage

FullCIs.MD(data = NULL, xcol = 1, ycol = 2,
           conf.level = 0.95, npoints = 1000, nlambdas = 13)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).
npoints	an integer (at least 10) for the number of points to smooth the hyperbolic curves.
nlambdas	an integer for the number of intermediate CBLS regressions (the two extreme CBLS are calculated by default).

Details

The data argument is mandatory. This function is especially useful for unreplicated data with unknown ρMD (related to λXY, the ratio of the measurement error variances), as it calculates all the potential solutions. The different estimated regression lines are provided with the different confidence intervals.

Value

A CIs.MD class object, a list including the following elements:

Data.means	a table with the X and Y data (means of the replicated data if replicated), their means and differences.
Ellipses.CB	an array of dimension [npoints, 2 (intercept and slope), nlambdas + 2] with the coordinates of all the joint confidence intervals (confidence region, ellipses) from ρMD = -1 to ρMD = 1.
Slopes	a table (nlambdas + 2 rows) with all the slopes estimates and their approximate confidence intervals and pvalue (slope = 0).
Intercepts	a table (nlambdas + 2 rows) with all the intercepts estimates and their approximate confidence intervals and pvalue (intercept = 0).
Joints	a table (nlambdas + 2 rows) with all the pvalues of the joint hypothesis (slope = 0 and intercept = 0).
Hyperbolic.intervals	an array of dimension [npoints, 6 (X values, Y predictions, confidence interval and confidence bands), nlambdas + 2] with the hyperbolic confidence interval and confidence bands.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.

See Also

FullCIs.XY, CBLS

Examples

library(BivRegBLS)
data(Aromatics)
res.full=FullCIs.MD(data=Aromatics,xcol=3,ycol=4)

---

Confidence Intervals from OLSv to OLSh by DR and BLS

Description

Estimate the vertical and horizontal Ordinary least Square regressions, and several 'intermediate' Deming Regression (DR) and Bivariate Least Square (BLS), in a (X,Y) plot. The OLSv assumes no error on the X axis (λ=Infinity), while the OLSh assumes no error on the Y axis (λ=0). These two regressions are therefore 'extreme' regressions, while DR and BLS assume errors on both axes.

Usage

FullCIs.XY(data = NULL, xcol = 1, ycol = 2,
           conf.level = 0.95, npoints = 1000, nlambdas = 13)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).
npoints	an integer (at least 10) for the number of points to smooth the hyperbolic curves.
nlambdas	an integer for the number of intermediate DR and BLS regressions (between the OLSv and OLSh).

Details

The data argument is mandatory. This function is especially useful for unreplicated data with unknown λ (the ratio of the measurement error variances), as it calculates all the potential solutions from OLSv to OLSh. The different estimated regression lines are provided with the different confidence intervals.

Value

A CIs.XY class object, a list including the following elements:

Data.means	a table with the X and Y data (means of the replicated data if replicated).
Ellipses.CB	an array of dimension [npoints, 2 (intercept and slope), nlambdas + 2] with the coordinates of all the joint confidence intervals (confidence region, ellipses) from OLSv to OLSh.
Slopes	a table (nlambdas + 2 rows) with all the slopes estimates from OLSv to OLSh including nlambdas intermediate values, the exact and approximate confidence intervals and pvalue (slope = 1).
Intercepts	a table (nlambdas + 2 rows) with all the intercepts estimates from OLSv to OLSh including nlambdas intermediate values, the approximate confidence intervals and pvalue (intercept = 0).
Joints	a table (nlambdas + 2 rows) with all the pvalues of the joint hypothesis (slope = 1 and intercept = 0) from OLSv to OLSh including intermediate nlambdas values.
Hyperbolic.intervals	an array of dimension [npoints, 6 (X values, Y predictions, confidence interval and confidence bands),nlambdas+2] with the hyperbolic confidence intervals and confidence bands from OLSv to OLSh including nlambdas intermediate values.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

FullCIs.MD, BLS

Examples

library(BivRegBLS)
data(Aromatics)
res.full=FullCIs.XY(data=Aromatics,xcol=3,ycol=4)

---

Plot all the CBLS potential solutions

Description

Display a plot with all the CBLS potential solutions in a (M,D) plot from ρ_{MD} = -1 to ρ_{MD} = 1 (useful for unreplicated data), choose between all the slopes (and their confidence intervals), all the intercepts (and their confidence intervals), all the confidence regions (ellipses), the two extreme confidence intervals (for the expectation of Y) or the two extreme confidence bands.

Usage

GraphFullCIs.MD(FullCIs = NULL, CBLS.estimate = NULL, lambda = NULL,
                xname = "X", yname = "Y", antilog = NULL, graph = "joint.ellipse",
                accept.int = 0, accept.int.perc = FALSE, accept.int.threshold = NULL,
                include.H0 = TRUE, include.int = TRUE)

Arguments

FullCIs	a CIs.MD class object.
CBLS.estimate	a CBLS class object. The CBLS estimates (obtained, for example, with replicated data) will be superimposed on the plot.
lambda	a lambdas class object. The value of λ (ratio of the error measurement variances) will be converted to ρ (correlation between the error measurement) and superimposed on the plot with its confidence interval.
xname	a character string for the name of the X device.
yname	a character string for the name of the Y device.
antilog	a character string or a numeric value. This argument displays the CBLS results on the initial scales on the (M,D) plot if a logarithmic transformation was used prior to the CBLS function. Options available are: 10 or "e".
graph	a character string for the type of graph: "slope" to plot all the slopes, "intercept" to plot all the intercepts,"joint.ellipse" to plot all the joint confidence intervals (ellipses), "CI" to plot the confidence intervals,"CB" to plot the confidence bands, "all" to plot all the plots on different windows.
accept.int	a numeric vector (length equal 1 or 2) for the value of Δ: |Y-X|<Δ to assess whether two devices (X and Y) are equivalent or not. Two values of Δ can be entered to take into account the case where the equivalence threshold changes along the M axis.
accept.int.perc	a logical variable (TRUE or FALSE) whether Δ needs to be interpreted in percentage: Y = X ± Δ %.
accept.int.threshold	a numeric value for the M threshold where the value of Δ changes if two Δ values are used in accept.int.
include.H0	a logical variable (TRUE or FALSE) whether the null hypothesis (slope = 0, intercept = 0) should lie on plot (in the case that the null hypothesis is out from the axes limits).
include.int	a logical variable (TRUE or FALSE) whether the confidence intervals should lie entirely in the plot.

Details

The ellipses are plotted in an (β,α) coordinate system where the acceptance interval is a diamond. The slopes and the intercepts are plotted on the Y-axis with ρ assigned on the X-axis. The confidence intervals and confidence bands are displayed on a (M,D) plot (Bland-Altman plot).

Value

The plot requested by the argument graph.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.
Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

MD.plot, CBLS

Examples

library(BivRegBLS)
data(SBP)
# Estimate all the solutions with the CBLS regression
res.full=FullCIs.MD(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# Estimate the CBLS regression with replicated data
res.CBLS=CBLS(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# Estimate the measurement error variances ratio
res.lambda=lambdas(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# Plot all the results with all the potential solutions
#   and superimpose the CBLS regression estimated with replicated data
GraphFullCIs.MD(FullCIs=res.full,CBLS.estimate=res.CBLS,lambda=res.lambda,
                xname="J",yname="S",graph="all",accept.int=10,accept.int.perc=FALSE,include.H0=TRUE)
data(Aromatics)
# Estimate all the solutions with the CBLS regression
res.full=FullCIs.MD(data=Aromatics,xcol=3,ycol=4)
# Plot all the potential solutions for the confidence regions (ellipses)
GraphFullCIs.MD(FullCIs=res.full,xname="HPLC",yname="GC MS",graph="joint.ellipse")
# Plot all the potential solutions for the confidence intervals and add two acceptance intervals
GraphFullCIs.MD(FullCIs=res.full,xname="HPLC",yname="GC MS",graph="CI",
                accept.int=c(0.1,0.2),accept.int.threshold=15)

---

Plot all the DR and BLS potential solutions

Description

Display a plot with all the DR and BLS potential solutions from OLSv to OLSh (useful for unreplicated data), choose between all the slopes (and their confidence intervals), all the intercepts (and their confidence intervals), all the confidence region (ellipses), the two extreme confidence intervals (for the expectation of Y) or the two extreme confidence bands.

Usage

GraphFullCIs.XY(FullCIs = NULL, BLS.estimate = NULL, lambda = NULL,
                xname = "X", yname = "Y", antilog = NULL, graph = "joint.ellipse",
                accept.int = 0, accept.int.perc = FALSE, accept.int.threshold = NULL,
                include.H0 = TRUE, include.int = TRUE)

Arguments

FullCIs	a CIs.XY class object.
BLS.estimate	a BLS class object. The BLS estimates (obtained, for example, with replicated data) will be superimposed on the plot.
lambda	a lambdas class object. The value of λ_{XY} will be superimposed on the plot with its confidence interval.
xname	a character string for the name of the X device.
yname	a character string for the name of the Y device.
antilog	a character string or a numeric value. This argument displays the BLS results on the initial scales on the (X,Y) plot if a logarithmic transformation was used prior to the BLS function. Options available are: 10 or "e".
graph	a character string for the type of graph: "slope" to plot all the slopes, "intercept" to plot all the intercepts,"joint.ellipse" to plot all the joint confidence intervals (ellipses), "CI" to plot the confidence intervals,"CB" to plot the confidence bands, "all" to plot all the plots on different windows.
accept.int	a numeric vector (length equal 1 or 2) for the value of Δ: Y = X ± Δ to assess whether the two devices (X and Y) are equivalent or not. Two values of Δ can be entered to take into account the case where the equivalence threshold changes along the X axis.
accept.int.perc	a logical variable (TRUE or FALSE) whether Δ needs to be interpreted in percentage: Y = X ± Δ%.
accept.int.threshold	a numeric value for the X threshold where the value of Δ changes if two Δ values are used in accept.int.
include.H0	a logical variable (TRUE or FALSE) whether the null hypothesis (slope = 1, intercept = 0) should lie on plot (in the case that the null hypothesis is out from the axes limits).
include.int	a logical variable (TRUE or FALSE) whether the confidence intervals should lie entirely in the plot.

Details

The ellipses are plotted in an (β,α) coordinate system where the acceptance interval is a diamond. The slopes and the intercepts are plotted on the Y-axis with λ_{XY} assigned on the X-axis. The confidence intervals and confidence bands are displayed on a classical (X,Y) plot.

Value

The plot requested by the argument graph.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

XY.plot, BLS

Examples

library(BivRegBLS)
data(SBP)
# Estimate all the solutions with the DR and BLS regressions
res.full=FullCIs.XY(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# Estimate the BLS regression with replicated data
res.BLS=BLS(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# Estimate the measurement error variances ratio
res.lambda=lambdas(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# Plot all the results with all the potential solutions
#   and superimpose the BLS regression estimated with replicated data
GraphFullCIs.XY(FullCIs=res.full,BLS.estimate=res.BLS,lambda=res.lambda,
                xname="J",yname="S",graph="all",accept.int=10,accept.int.perc=FALSE,include.H0=TRUE)
# Plot all the potential solutions for the confidence intervals and add two acceptance intervals
GraphFullCIs.XY(FullCIs=res.full,xname="J",yname="S",graph="CI",
                accept.int=c(8,12),accept.int.threshold=150,accept.int.perc=FALSE,include.H0=TRUE)
data(Aromatics)
# Estimate all the solutions with the BLS regression
res.full=FullCIs.XY(data=Aromatics,xcol=3,ycol=4)
# Plot all the potential solutions for the confidence regions (ellipses)
GraphFullCIs.XY(FullCIs=res.full,xname="HPLC",yname="GC MS",graph="joint.ellipse")

---

Measurement error variances ratio

Description

Calculate the measurement error variances ratio of two devices (Y over X): λ and λ_{XY}

Usage

lambdas(data = NULL, xcol = NULL, ycol = NULL, conf.level = 0.95)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X columns or a character vector with the column names.
ycol	a numeric vector to specify the Y columns or a character vector with the column names.
conf.level	a numeric value for the confidence level.

Details

The data must be replicated to estimate the measurement error variances. If the number of replicates in X is equal to the number of replicates in Y, then λ and λ_{XY} are equal: λ is the ratio (Y over X) of the measurement error variances, while λ_{XY} is similar but takes also into account the number of replicates per device (nx and ny). Unbiased estimators (which is not the ratio of the two variances) for λ and λ_{XY} are also given.

Value

A lambdas class object, a table with 2 rows (λ and λ_{XY}) and their confidence intervals and pvalues in columns (the null hypothesized value is 1).

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.
Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.

See Also

desc.stat

Examples

library(BivRegBLS)
data(SBP)
lambdas(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)

---

Tolerance intervals in a (M,D) plot

Description

Calculate agreement interval and tolerance intervals (bounded by 2 horizontal lines) for the differences (D=Y-X) in a (M,D) plot (also called Bland-Altman plot).

Usage

MD.horiz.lines(data = NULL, xcol = 1, ycol = 2,
               pred.level = 0.95, TI.conf.level = 0.8)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
pred.level	a numeric value for the predictive level (expressed between 0 and 1) of the tolerance intervals (beta expectation (type I) and beta gamma content (type II)).
TI.conf.level	a numeric value for the confidence level of the beta gamma content tolerance interval (tolerance interval type II).

Details

The data argument is mandatory while other arguments are optional. If the data are replicated, the tolerance intervals predict where a future single difference (Di=Yi-Xi) will lie (and not an average difference). Tolerance intervals are better (than agreement interval) and should be preferred. The tolerance intervals are calculated on the univariate distribution of the differences (Di). These intervals are valid under the assumption that there is no proportional bias. If a pattern is observed, the CBLS function (CBLS regression) must be used (with its predictive intervals).

Value

A MD.horiz.lines class object: a list including the following elements:

data.MD	a table with the means ((X+Y)/2) and differences (Y-X).
Table.Differences	a table with one row and several descriptive statistics: the mean of the differences, the standard deviation of the mean difference (Di=Yi-Xi) and the standard deviation for a single difference (Yik-Xik), the minimum, 1st quartile, median, 3rd quartile, maximum and number of observations.
Intervals.horiz.lines	a table with 3 rows for the agreement interval, the beta expectation tolerance interval and the beta gamma content tolerance interval, with their interpretation (columns).

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.

See Also

CBLS

Examples

library(BivRegBLS)
data(SBP)
res.MD.horiz=MD.horiz.lines(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10,pred.level=0.95)
res.MD.horiz$Intervals.horiz.lines

---

Display the CBLS regression, or univariate tolerance intervals in a (M,D) plot

Description

Display the CBLS regression in a (M,D) plot with or without hyperbolic confidence and/or predictive intervals, and an acceptance interval. Alternatively, univariate tolerance intervals which are bounded by two horizontal lines can be plotted.

Usage

MD.plot(results = NULL, xname = "X", yname = "Y", antilog = NULL,
        accept.int = 0, accept.int.perc = FALSE, accept.int.threshold = NULL,
        include.int = TRUE, graph.int = c("CB", "PI"), graph.horiz.int = c("bTI", "bgTI"),
        col.CBLS = 1, col.CI = 2, col.CB = 3, col.PI = 4, col.GI = 5, col.bTI = 3,
        col.bgTI = 4, lty.CBLS = 1, lty.CI = 1, lty.CB = 1, lty.PI = 1, lty.GI = 1,
        lty.bTI = 1, lty.bgTI = 1, ...)

Arguments

results	a CBLS class object (obtained with the BLS function) or a MD.horiz.lines class object (obtained with the MD.horiz.lines function).
xname	a character string for the name of the X device.
yname	a character string for the name of the Y device.
antilog	a character string or a numeric value. This argument displays the CBLS or MD.horiz.lines results on the initial scales in the (M,D) plot if a logarithmic transformation was used prior to the CBLS or MD.horiz.lines functions. Options available are: 10 or "e".
accept.int	a numeric vector (length equal 1 or 2) for the value of Δ: |Y-X|<Δ to assess whether two devices (X and Y) are equivalent or not. Two values of Δ can be entered to take into account the case where the equivalence threshold changes along the M axis.
accept.int.perc	a logical variable (TRUE or FALSE) whether Δ needs to be interpreted in percentage: Y = X ± Δ%.
accept.int.threshold	a numeric value for the M threshold where the value of Δ changes if two Δ values are used in accept.int.
include.int	a logical variable (TRUE or FALSE) whether the hyperbolic intervals should lie entirely in the plot.
graph.int	a character vector for the hyperbolic curves to be displayed on the graph. Options are: "CI" (Confidence Intervals),"CB" (Confidence Bands),"PI" (Predictive Intervals),"GI" (Generalised Intervals).
graph.horiz.int	if a MD.horiz.lines object is used, a character vector for the univariate tolerance intervals to be displayed on the graph. Options are: "bTI" (beta expectation tolerance interval or tolerance interval type I) and/or "bgTI" (beta gamma content tolerance interval or tolerance interval type II).
col.CBLS	a character string or a numeric variable for the colour of the CBLS regression line.
col.CI	a character string or a numeric variable for the colour of the confidence intervals.
col.CB	a character string or a numeric variable for the colour of the confidence bands.
col.PI	a character string or a numeric variable for the colour of the predictive intervals.
col.GI	a character string or a numeric variable for the colour of the generalized intervals.
col.bTI	a character string or a numeric variable for the colour of the beta expectation tolerance interval.
col.bgTI	a character string or a numeric variable for the colour of the beta gamma content tolerance interval.
lty.CBLS	a numeric variable for the type of line of the CBLS regression line.
lty.CI	a numeric variable for the type of line for the confidence intervals.
lty.CB	a numeric variable for the type of line for the confidence bands.
lty.PI	a numeric variable for the type of line for the predictive intervals.
lty.GI	a numeric variable for the type of line for the generalized intervals.
lty.bTI	a numeric variable for the type of line for the beta expectation tolerance interval.
lty.bgTI	a numeric variable for the type of line for the beta gamma content tolerance interval.
...	the common arguments from 'plot' or 'par' that may be used additionaly, such as xlim, ylim, xlab, ylab.

Details

The results argument is mandatory. The value of Δ (accept.int) is converted to percentage if antilog is used in a (M,D) plot to define 2 asymetric bounds (1- Δ/100, (100/(100-Δ)).

Value

An (M,D) plot in a new window.

Note

The limits of the axes and their labels are set automatically by the function. To compare different plots with fixed limits, use xlim and ylim. To write customized labels, use xlab and ylab.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

XY.plot

Examples

library(BivRegBLS)
data(SBP)
# Estimate the CBLS regression on replicated data
res.CBLS=CBLS(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# Plot the results in a (M,D) plot with an acceptance interval
MD.plot(results=res.CBLS,xname="J",yname="S",accept.int=10,accept.int.perc=FALSE)
MD.plot(results=res.CBLS,xname="J",yname="S",accept.int=10,accept.int.perc=TRUE)
MD.plot(results=res.CBLS,xname="J",yname="S",accept.int=c(10,15),
        accept.int.perc=FALSE,accept.int.threshold=150)

---

Horizontal Ordinary Least Square regression

Description

Fit a linear ordinary least square regression by minimising the residuals in a horizontal direction.

Usage

OLSh(data = NULL, xcol = 1, ycol = 2, conf.level = 0.95)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X columns or a character vector with the column names.
ycol	a numeric vector to specify the Y columns or a character vector with the column names.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).

Details

The data argument is mandatory while other arugments are optional.

Value

A list including the following elements:

Ellipse.OLSh	a two columns matrix with the coordinates of the joint confidence interval (confidence region) for the parameters (β, α).
Estimate.OLSh	a table (data frame) with the estimates of the intercept and the slope, standard error, confidence interval and pvalue (null hypothesis: slope = 1, intercept = 0).

Note

The default value for xcol (ycol) is 1 (2) for the 1st (2nd) column. The confidence region for the OLSh parameters is 'distorted' as it results from the OLSv confidence region (ellipse).

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

OLSv

Examples

res.OLSh=OLSh(matrix(nrow=10,ncol=2,c((1:10)+rnorm(10),1:10)))
res.OLSh$Estimate.OLSh

---

Vertical Ordinary Least Square regression

Description

Fit a linear ordinary least square regression by minimising the residuals in a vertical direction.

Usage

OLSv(data = NULL, xcol = 1, ycol = 2, conf.level = 0.95, pred.level = 0.95,
     npoints = 1000, q = 1, xpred = NULL)

Arguments

data	a data set (data frame or matrix).
xcol	a numeric vector to specify the X column(s) or a character vector with the column names.
ycol	a numeric vector to specify the Y column(s) or a character vector with the column names.
conf.level	a numeric value for the confidence level (expressed between 0 and 1).
pred.level	a numeric value for the predictive level (expressed between 0 and 1).
npoints	an integer (at least 10) for the number of points to smooth the hyperbolic curves.
q	an integer to predict the mean of q future values (generalized interval).
xpred	a numeric vector for customized predictions at given X values.

Details

The data argument is mandatory while other arguments are optional. The confidence level is used for the confidence intervals of the parameters, the hyperbolic confidence intervals (the prediction of the expectation of Y for a given X) and the hyperbolic confidence bands. The predictive level is used for the hyperbolic predictive intervals (the prediction of a future Y for a given X) and the hyperbolic generalized intervals (the prediction of the mean of q future Y values for a given X).

Value

A list including the following elements:

Ellipse.OLSv	a two columns matrix with the coordinates of the joint confidence interval (confidence region, ellipse) for the parameters (β, α).
Estimate.OLSv	a table (data frame) with the estimates of the intercept and the slope, standard error, confidence interval and pvalue (null hypothesis: slope = 1, intercept = 0).
Pred.OLSv	a data frame with npoints rows (from the minimum to the maximum of the observed X values) and the following columns: the X values where the predictions are calculated (X0), the Y predicted values (Ypred), the lower and upper bounds of the confidence intervals, predictive intervals, generalized intervals and confidence bands.
xpred.OLSv	a data frame with the customized predictions and the same columns than Pred.OLSv.

Note

The default value for xcol (ycol) is 1 (2) for the 1st (2nd) column.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

OLSh

Examples

res.OLSv=OLSv(matrix(nrow=10,ncol=2,c(1:10,(1:10)+rnorm(10))))
res.OLSv$Estimate.OLSv

---

Raw plot for descriptive statistics

Description

Display a plot with the raw data in an (X,Y) plot or (M,D) plot with or witout error bars.

Usage

raw.plot(data.plot = NULL, xname = "X", yname = "Y", graph = "XY.means",
         col.ID = NULL, pch.ID = NULL, ...)

Arguments

data.plot	a desc.stat class object (obtained by using the desc.stat function).
xname	a character string for the name of the X device.
yname	a character string for the name of the Y device.
graph	a character string for the kind of graph. Options available are: XY.means, XY.points, XY.bar.range, XY.bar.SEM, XY.bar.SD, MD.means.
col.ID	a numeric or character vector describing the color of the points per ID.
pch.ID	a numeric vector describing the type of points per ID to plot the data.
...	the common arguments from 'plot' or 'par' that may be used additionaly, such as xlim, ylim, xlab, ylab.

Details

The data.plot argument is mandatory. The labels of the X and Y axes are built by default with xname and yname, and with the type of graph. The arguments col.ID and pch.ID are useful if the argument IDcol was used in the function desc.stat. col.ID and pch.ID are recycled if shorter than the number of IDs, i.e. if 3 colors are specified as col.ID=c(1,2,3) while there are 7 IDs, then the colors will be used as c(1,2,3,1,2,3,1).
With the argument graph, the option XY.means plots the mean measures in a (X,Y) plot, XY.points plots all the X (Y) replicated data centered on the means of Y (X), XY.bar.range plots the error bars from the minimum to the maximum (the range) of the replicates, XY.bar.SEM plots the error bars with the standard errors of the means, XY.bar.SD plots the error bars with the standard deviations, MD.means plots the mean measures in a (M,D) plot.

Value

A plot in a new window.

Note

The limits of the axes and the labels are set automatically by the function. To compare different plots with fixed limits, use xlim and ylim. To write customized labels, use xlab and ylab.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems 2014; 134:123-139.

See Also

XY.plot, MD.plot

Examples

library(BivRegBLS)
data(Aromatics)
# Calculate the descriptive statistics
res=desc.stat(data=Aromatics,xcol=3,ycol=4,IDcol="Type")
# Plot the mean or single measures (it is the same for unreplicated data)
raw.plot(data.plot=res,xname="HPLC",yname="GC MS",graph="XY.means")
raw.plot(data.plot=res,xname="HPLC",yname="GC MS",graph="XY.points")
# Plot with customized colours and type of points per type of samples
raw.plot(data.plot=res,xname="HPLC",yname="GC MS",graph="XY.points",pch.ID=c(19,5,8),col.ID=c(1,2))
raw.plot(data.plot=res,xname="HPLC",yname="GC MS",graph="MD.means")
raw.plot(data.plot=res,xname="HPLC",yname="GC MS",graph="MD.means",col.ID=c(1,2,4))
data(SBP)
# Calculate the descriptive statistics
res=desc.stat(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10)
# Different plots to show the measurement uncertainties
raw.plot(data.plot=res,xname="J",yname="S",graph="XY.means")
raw.plot(data.plot=res,xname="J",yname="S",graph="XY.points")
raw.plot(data.plot=res,xname="J",yname="S",graph="XY.bar.range")
raw.plot(data.plot=res,xname="J",yname="S",graph="XY.bar.SD")
raw.plot(data.plot=res,xname="J",yname="S",graph="XY.bar.SEM")
raw.plot(data.plot=res,xname="J",yname="S",graph="MD.means")

---

Systolic blood pressure data

Description

Systolic blood pressure measured by two devices on 85 patients: 3 times with a manual device by 2 operators and 3 times with a semi automatic device.

Usage

data(SBP)

Format

A data frame with 85 observations and 10 variables.

Subject

a numeric vector for the patient IDs.

J1

a numeric vector: the 1st measures obtained by operator J.

J2

a numeric vector: the 2nd measures obtained by operator J.

J3

a numeric vector: the 3rd measures obtained by operator J.

R1

a numeric vector: the 1st measures obtained by operator R.

R2

a numeric vector: the 2nd measures obtained by operator R.

R3

a numeric vector: the 3rd measures obtained by operator R.

S1

a numeric vector: the 1st measures obtained by the semi automatic device.

S2

a numeric vector: the 2nd measures obtained by the semi automatic device.

S3

a numeric vector: the 3rd measures obtained by the semi automatic device.

Source

Bland JM, Altman DG. Measuring agreement in method comparison studies. Statistical Methods in Medical Research, 1999; 8:135-160.

References

Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.
Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.

Examples

data(SBP)
str(SBP)
head(SBP)

---

Display the BLS regression in a (X,Y) plot

Description

Display the BLS regression in a (X,Y) plot with or without hyperbolic confidence and/or predictive intervals, and an acceptance interval.

Usage

XY.plot(BLS.results = NULL, xname = "X", yname = "Y", antilog = NULL,
        accept.int = 0, accept.int.perc = FALSE, accept.int.threshold = NULL,
        graph.int = c("CB", "PI"), include.int = FALSE, col.BLS = 1, col.CI = 2,
        col.CB = 3, col.PI = 4, col.GI = 5, lty.BLS = 1, lty.CI = 1,
        lty.CB = 1, lty.PI = 1, lty.GI = 1, ...)

Arguments

BLS.results	a BLS or BLS.ht class object (obtained with the BLS or BLS.ht functions).
xname	a character string for the name of the X device.
yname	a character string for the name of the Y device.
antilog	a character string or a numeric value. This argument display the BLS results on the initial scales on the (X,Y) plot if a logarithmic transformation was used prior to the BLS function. Options available are: 10 or "e".
accept.int	a numeric vector (length equal 1 or 2) for the value of Δ: Y = X ± Δ to assess whether two devices (X and Y) are equivalent or not. Two values of Δ can be entered to take into account the case where the equivalence threshold changes along the X axis.
accept.int.perc	a logical variable (TRUE or FALSE) whether Δ needs to be interpreted in percentage: Y = X ± Δ %.
accept.int.threshold	a numeric value for the X threshold where the value of Δ changes if two Δ values are used in accept.int.
graph.int	a character vector for the hyperbolic curves to be displayed on the graph. Options are: "CI" (Confidence Intervals),"CB" (Confidence Bands),"PI" (Predictive Intervals),"GI" (Generalised Intervals).
include.int	a logical variable whether the hyperbolic intervals should lie entirely in the plot.
col.BLS	a character string or a numeric variable for the colour of the BLS regression line.
col.CI	a character string or a numeric variable for the colour of the confidence intervals.
col.CB	a character string or a numeric variable for the colour of the confidence bands.
col.PI	a character string or a numeric variable for the colour of the predictive intervals.
col.GI	a character string or a numeric variable for the colour of the generalized intervals.
lty.BLS	a numeric variable for the type of line of the BLS regression line.
lty.CI	a numeric variable for the type of line for the confidence intervals.
lty.CB	a numeric variable for the type of line for the confidence bands.
lty.PI	a numeric variable for the type of line for the predictive intervals.
lty.GI	a numeric variable for the type of line for the generalized intervals.
...	the common arguments from 'plot' or 'par' that may be used additionaly, such as xlim, ylim, xlab, ylab.

Details

The BLS.result argument is mandatory.

Value

An (X,Y) plot in a new window.

Note

The limits of the axes and their labels are set automatically by the function. To compare different plots with fixed limits, use xlim and ylim. To write customized labels, use xlab and ylab.

Author(s)

Bernard G FRANCQ

References

Francq BG, Govaerts BB. How to regress and predict in a Bland-Altman plot? Review and contribution based on tolerance intervals and correlated-errors-in-variables models. Statistics in Medicine, 2016; 35:2328-2358.
Francq BG, Govaerts BB. Measurement methods comparison with errors-in-variables regressions. From horizontal to vertical OLS regression, review and new perspectives. Chemometrics and Intelligent Laboratory Systems, 2014; 134:123-139.
Francq BG, Govaerts BB. Hyperbolic confidence bands of errors-in-variables regression lines applied to method comparison studies. Journal de la Societe Francaise de Statistique 2014; 155(1):23-45.

See Also

MD.plot

Examples

library(BivRegBLS)
data(SBP)
# Estimate the BLS regression on replicated data
res.BLS=BLS(data=SBP,xcol=c("J1","J2","J3"),ycol=8:10,qx=3,qy=3)
# Plot the results in a (X,Y) plot with an acceptance interval
XY.plot(BLS.results=res.BLS,xname="J",yname="S",accept.int=10,accept.int.perc=FALSE)
XY.plot(BLS.results=res.BLS,xname="J",yname="S",accept.int=10,accept.int.perc=TRUE)
XY.plot(BLS.results=res.BLS,xname="J",yname="S",accept.int=c(10,20),
        accept.int.perc=FALSE,accept.int.threshold=150)

---