equivalence (version 0.7.2)

equivalence.xyplot: Constructs graphical regression-based tests of equivalence inside a lattice coplot

Description

Implements regression-based tests of equivalence within lattice graphics.

Usage

equivalence.xyplot(formula, alpha, b0.ii, b1.ii,
add.smooth=FALSE, b0.absolute=FALSE, ...)

Arguments

formula

a formula describing the form of conditioning plot. See the manual entry for xyplot for more details.

alpha

the size of the test

b0.ii

the half-length of the region of similarity for the intercept, can be relative or absolute (see below).

b1.ii

the half-length of the region of similarity for the slope.

add.smooth

adds a loess smooth to the graph.

b0.absolute

is b0.ii in absolute or relative units?

...

extra arguments passed on to xyplot

Value

Run for its side effect of producing a lattice plot object.

Warning

The accuracy of the output of this function is contingent on the usual regression assumptions, which are not checked here. Caveat emptor! Consider using equiv.boot() for a bootstrap-based solution. Transforming either variable will probably complicate the analysis considerably.

Acknowledgements

Feedback from Mohammad Al-Ahmadi has been very useful for this function.

Details

The graphic created by this function was proposed by Robinson et al. (2005) as a visual summary of the regression-based TOST. At first glance the graph will look messy; interpretation eases with practice. The following points should be noted.

• LS line:A black, solid line of best fit is added.
• Mean:A grey vertical bar indicates the mean of x and the TOST confidence interval for the intercept.
• b0 R.S.:A shaded polygon is the region of similarity of the intercept, to test the model bias.
• Test b0:If the grey vertical bar is within the shaded polygon then reject the null hypothesis of dissimilarity. This is a test of bias.
• ...1 -If the region is too low then the predictions are too low.
• ...2 -If the region is too high then the predictions are too high.
• ...3 -If the region is too narrow then the predictions are too variable.
• b1 C.I.:A black vertical bar undermeath the grey bar represents a confidence interval for the slope of the line of best fit.
• b1 R.S.:Two black dashed lines are added representing the region of similarity.
• Test b1:If the black bar is within the angle described by the dashed black lines then the slope of the observed/predicted regression is significantly similar to 1. This is a test of proportionality.
• ...1 -If the bar is too high then the slope is too high; the model over-predicts the higher observations and under-predicts the lower observations.
• ...2 -If the bar is too low then the slope is too low; the model underpredicts the higher observations and overpredicts the lower observations (analogous to regression to the mean).
• ...3 -If the bar is too narrow then the predictions are too variable.

The implementation in Robinson et al. (2005) required shifting so that the predictor has 0 mean. This hack has been removed here so that the basic graph object is a plot of the two variables being compared.

References

Robinson, A.P., R.A. Duursma, and J.D. Marshall. 2005. A regression-based equivalence test for model validation: shifting the burden of proof. Tree Physiology 25, 903-913.

See Also

tost.stat, xyplot, equiv.boot

Examples

data(pref.4PG)
equivalence.xyplot(pref.4PG$stemvolinc ~ pref.4PG$volinc4PG,
                   alpha=0.05, b0.ii=0.25, b1.ii=0.25, add.smooth=TRUE, 
                   xlab=expression(paste("4PG decadal volume growth (", m^3,
                       ha^-1, decade^-1, ")", sep="")), 
                   ylab=expression(paste("Measured decadal volume growth (",
                       m^3, ha^-1, decade^-1, ")", sep="")))

data(pref.LAI)
equivalence.xyplot(pref.LAI$lai.pa ~ pref.LAI$lai.bl,
                   alpha=0.05, b0.ii=0.25, b1.ii=0.25,
                   xlab=expression(paste("LAI Beer-Lambert (", m^2, m^-2, ")",
                       sep="")), 
                   ylab=expression(paste("LAI Ceptometer (", m^2, m^-2, ")",
                       sep=""))) 


data(ufc)
ufc.ht <- ufc[!is.na(ufc$Height),]
equivalence.xyplot(ufc.ht$Height.m ~ ufc.ht$Height.m.p,
                   alpha=0.05, b0.ii=0.1, b1.ii=0.2,
                   xlab="Predicted height (m)",
                   ylab="Measured height (m)")

equivalence.xyplot(ufc.ht$Height.m ~ ufc.ht$Height.m.p | ufc.ht$Species,
                   alpha=0.05, b0.ii=0.1, b1.ii=0.2,
                   xlab="Predicted height (m)",
                   ylab="Measured height (m)",
                   subset=ufc.ht$Species %in%
                        levels(ufc.ht$Species)[table(ufc.ht$Species)>5])