equivalence (version 0.8.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, ...)

Value

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

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

Author

Andrew Robinson

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])