control                 package:boot                 R Documentation

Control Variate Calculations

Description:

     This function will find control variate estimates from a bootstrap
     output object.  It can either find the adjusted bias estimate
     using post-simulation balancing or it can estimate the bias,
     variance, third cumulant and quantiles, using the linear
     approximation as a control variate.

Usage:

     control(boot.out, L = NULL, distn = NULL, index = 1, t0 = NULL, t = NULL, 
             bias.adj = FALSE, alpha = NULL, ...)

Arguments:

boot.out: A bootstrap output object returned from 'boot'.  The
          bootstrap replicates must have been generated using the usual
          nonparametric bootstrap. 

       L: The empirical influence values for the statistic of interest.
           If 'L' is not supplied then 'empinf' is called to calculate
          them from 'boot.out'. 

   distn: If present this must be the output from 'smooth.spline'
          giving the distribution function of the linear approximation.
           This is used only if 'bias.adj' is 'FALSE'.  Normally this
          would be found using a saddlepoint approximation. If it is
          not supplied in that case then it is calculated by
          'saddle.distn'. 

   index: The index of the variable of interest in the output of
          'boot.out$statistic'. 

      t0: The observed value of the statistic of interest on the
          original data set 'boot.out$data'.  This argument is used
          only if 'bias.adj' is 'FALSE'. The input value is ignored if
          't' is not also supplied.  The default value is is
          'boot.out$t0[index]'. 

       t: The bootstrap replicate values of the statistic of interest. 
          This argument is used only if 'bias.adj' is 'FALSE'.  The
          input is ignored if 't0' is not supplied also.  The default
          value is 'boot.out$t[,index]'. 

bias.adj: A logical variable which if 'TRUE' specifies that the
          adjusted bias estimate using post-simulation balance is all
          that is required. If 'bias.adj' is 'FALSE' (default) then the
          linear approximation to the statistic is calculated and used
          as a control variate in estimates of the bias, variance and
          third cumulant as well as quantiles. 

   alpha: The alpha levels for the required quantiles if 'bias.adj' is
          'FALSE'. 

     ...: Any additional arguments that 'boot.out$statistic' requires.
          These are passed unchanged every time 'boot.out$statistic' is
          called.  'boot.out$statistic' is called once if 'bias.adj' is
          'TRUE', otherwise it may be called by 'empinf' for empirical
          influence calculations if 'L' is not supplied. 

Details:

     If 'bias.adj' is 'FALSE' then the linear approximation to the
     statistic is found and evaluated at each bootstrap replicate. Then
     using the equation _T* = Tl*+(T*-Tl*)_, moment estimates can be
     found.  For quantile estimation the distribution of the linear
     approximation to 't' is approximated very accurately by
     saddlepoint methods, this is then combined with the bootstrap
     replicates to approximate the bootstrap distribution of 't' and
     hence to estimate the bootstrap quantiles of 't'.

Value:

     If 'bias.adj' is 'TRUE' then the returned value is the adjusted
     bias estimate.

     If 'bias.adj' is 'FALSE' then the returned value is a list with
     the following components

       L: The empirical influence values used.  These are the input
          values if supplied, and otherwise they are the values
          calculated by 'empinf'. 

      tL: The linear approximations to the bootstrap replicates 't' of
          the statistic of interest. 

    bias: The control estimate of bias using the linear approximation
          to 't' as a control variate. 

     var: The control estimate of variance using the linear
          approximation to 't' as a control variate. 

      k3: The control estimate of the third cumulant using the linear
          approximation to 't' as a control variate. 

quantiles: A matrix with two columns; the first column are the alpha
          levels used for the quantiles and the second column gives the
          corresponding control estimates of the quantiles using the
          linear approximation to 't' as a control variate. 

   distn: An output object from 'smooth.spline' describing the
          saddlepoint approximation to the bootstrap distribution of
          the linear approximation to 't'.  If 'distn' was supplied on
          input then this is the same as the input otherwise it is
          calculated by a call to 'saddle.distn'. 

References:

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

     Davison, A.C., Hinkley, D.V. and Schechtman, E. (1986) Efficient
     bootstrap  simulation. _Biometrika_, *73*, 555-566.

     Efron, B. (1990) More efficient bootstrap computations. _Journal
     of the American Statistical Association_, *55*, 79-89.

See Also:

     'boot', 'empinf', 'k3.linear', 'linear.approx', 'saddle.distn',
     'smooth.spline', 'var.linear'

Examples:

     # Use of control variates for the variance of the air-conditioning data
     mean.fun <- function(d, i)
     {    m <- mean(d$hours[i])
          n <- nrow(d)
          v <- (n-1)*var(d$hours[i])/n^2
          c(m, v)
     }
     data(aircondit)
     air.boot <- boot(aircondit, mean.fun, R = 999)
     control(air.boot, index = 2, bias.adj = TRUE)
     air.cont <- control(air.boot, index = 2)
     # Now let us try the variance on the log scale.
     air.cont1 <- control(air.boot, t0=log(air.boot$t0[2]), t=log(air.boot$t[,2]))

