norm.ci                 package:boot                 R Documentation

Normal Approximation Confidence Intervals

Description:

     Using the normal approximation to a statistic, calculate
     equi-tailed two-sided  confidence intervals.

Usage:

     norm.ci(boot.out=NULL, conf=0.95, index=1, var.t0=NULL, 
             t0=NULL, t=NULL, L=NULL, h=function(t) t, 
             hdot=function(t) 1, hinv=function(t) t)

Arguments:

boot.out: A bootstrap output object returned from a call to 'boot'.  If
          't0' is missing then 'boot.out' is a required argument.  It
          is also required if both 'var.t0' and 't' are missing. 

    conf: A scalar or vector containing the confidence level(s) of the
          required  interval(s). 

   index: The index of the statistic of interest within the output of a
          call to 'boot.out$statistic'.  It is not used if 'boot.out'
          is missing, in which case 't0' must be supplied. 

  var.t0: The variance of the statistic of interest.  If it is not
          supplied then  'var(t)' is used. 

      t0: The observed value of the statistic of interest.  If it is
          missing then it is taken from 'boot.out' which is required in
          that case. 

       t: Bootstrap replicates of the variable of interest.  These are
          used to estimate  the variance of the statistic of interest
          if 'var.t0' is not supplied.  The default value is
          'boot.out$t[,index]'. 

       L: The empirical influence values for the statistic of interest.
           These are used to calculate 'var.t0' if neither 'var.t0' nor
          'boot.out' are supplied.  If a transformation is supplied
          through 'h' then the influence values must be for the
          untransformed statistic 't0'. 

       h: A function defining a monotonic transformation,  the
          intervals are calculated on the scale of 'h(t)' and the
          inverse function 'hinv' is applied to the  resulting
          intervals.  'h' must be a function of one variable only and
          must be vectorized. The default is the identity function. 

    hdot: A function of one argument returning the derivative of 'h'. 
          It is a required argument if 'h' is supplied and is used for
          approximating the variance of 'h(t0)'.  The default is the
          constant function 1. 

    hinv: A function, like 'h', which returns the inverse of 'h'.  It
          is used to transform the intervals calculated on the scale of
          'h(t)' back to the original scale. The default is the
          identity function.  If 'h' is supplied but 'hinv' is not,
          then the intervals returned will be on the transformed scale. 

Details:

     It is assumed that the statistic of interest has an approximately
     normal distribution with variance 'var.t0' and so a confidence
     interval of length '2*qnorm((1+conf)/2)*sqrt(var.t0)' is found. 
     If 'boot.out' or 't' are supplied then the interval is
     bias-corrected using the bootstrap bias estimate, and so the
     interval would be centred at '2*t0-mean(t)'.  Otherwise the
     interval is centred at 't0'.

Value:

     If 'length(conf)' is 1 then a vector containing the confidence
     level and the endpoints of the interval is returned.  Otherwise,
     the returned value is a  matrix where each row corresponds to a
     different confidence level.

Note:

     This function is primarily designed to be called by 'boot.ci' to
     calculate  the normal approximation after a bootstrap but it can
     also be used without doing any bootstrap calculations as long as
     't0' and 'var.t0' can be supplied. See the examples below.

References:

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

See Also:

     'boot.ci'

Examples:

     #  In Example 5.1 of Davison and Hinkley (1997), normal approximation 
     #  confidence intervals are found for the air-conditioning data.
     air.mean <- mean(aircondit$hours)
     air.n <- nrow(aircondit)
     air.v <- air.mean^2/air.n
     norm.ci(t0=air.mean, var.t0=air.v)
     exp(norm.ci(t0=log(air.mean), var.t0=1/air.n)[2:3])

     # Now a more complicated example - the ratio estimate for the city data.
     ratio <- function(d, w)
          sum(d$x * w)/sum(d$u *w)
     city.v <- var.linear(empinf(data=city, statistic=ratio))
     norm.ci(t0=ratio(city,rep(0.1,10)), var.t0=city.v)

