envelope                package:boot                R Documentation

Confidence Envelopes for Curves

Description:

     This function calculates overall and pointwise confidence
     envelopes for a  curve based on bootstrap replicates of the curve
     evaluated at a number of fixed points.

Usage:

     envelope(boot.out=NULL, mat=NULL, level=0.95, index=1:ncol(mat))

Arguments:

boot.out: An object of class '"boot"' for which 'boot.out$t' contains
          the replicates of the curve at a number of fixed points. 

     mat: A matrix of bootstrap replicates of the values of the curve
          at a number of fixed points.  This is a required argument if
          'boot.out' is not supplied and is set to 'boot.out$t'
          otherwise. 

   level: The confidence level of the envelopes required.  The default
          is to find 95% confidence envelopes.  It can be a scalar or a
          vector of length 2.   If it is scalar then both the pointwise
          and the overall envelopes are found at that level.  If is a
          vector then the first element gives  the level for the
          pointwise envelope and the second gives the level for the
          overall envelope. 

   index: The numbers of the columns of 'mat' which contain the
          bootstrap replicates. This can be used to ensure that other
          statistics which may have been calculated in the bootstrap
          are not considered as values of the function. 

Details:

     The pointwise envelope is found by simply looking at the quantiles
     of the replicates at each point.  The overall error for that
     envelope is then calculated using equation (4.17) of Davison and
     Hinkley (1997).  A sequence of pointwise envelopes is then found
     until one of them has overall error approximately equal to the
     level required.  If no such envelope can be found then the
     envelope returned will just contain the extreme values of each
     column of 'mat'.

Value:

     A list with the following components :

   point: A matrix with two rows corresponding to the values of the
          upper and lower pointwise confidence envelope at the same
          points as the bootstrap replicates were calculated. 

 overall: A matrix similar to 'point' but containing the envelope which
          controls the overall error. 

    k.pt: The quantiles used for the pointwise envelope. 

  err.pt: A vector with two components, the first gives the pointwise
          error rate for the pointwise envelope, and the second the
          overall error rate for that envelope. 

    k.ov: The quantiles used for the overall envelope. 

  err.ov: A vector with two components, the first gives the pointwise
          error rate for the overall envelope, and the second the
          overall error rate for that envelope. 

 err.nom: A vector of length 2 giving the nominal error rates for the
          pointwise and the overall envelopes. 

References:

     Davison, A.C. and Hinkley, D.V. (1997)  _Bootstrap Methods and
     Their Application_. Cambridge University Press.

See Also:

     'boot', 'boot.ci'

Examples:

     # Testing whether the final series of measurements of the gravity data
     # may come from a normal distribution.  This is done in Examples 4.7 
     # and 4.8 of Davison and Hinkley (1997).
     grav1 <- gravity$g[gravity$series==8]
     grav.z <- (grav1-mean(grav1))/sqrt(var(grav1))
     grav.gen <- function(dat,mle)
          rnorm(length(dat))
     grav.qqboot <- boot(grav.z,sort,R=999,sim="parametric",ran.gen=grav.gen)
     grav.qq <- qqnorm(grav.z,plot=FALSE)
     grav.qq <- lapply(grav.qq,sort)
     plot(grav.qq,ylim=c(-3.5,3.5),ylab="Studentized Order Statistics",
          xlab="Normal Quantiles")
     grav.env <- envelope(grav.qqboot,level=0.9)
     lines(grav.qq$x,grav.env$point[1,],lty=4)
     lines(grav.qq$x,grav.env$point[2,],lty=4)
     lines(grav.qq$x,grav.env$overall[1,],lty=1)
     lines(grav.qq$x,grav.env$overall[2,],lty=1)

