saddle                 package:boot                 R Documentation

_S_a_d_d_l_e_p_o_i_n_t _A_p_p_r_o_x_i_m_a_t_i_o_n_s _f_o_r _B_o_o_t_s_t_r_a_p _S_t_a_t_i_s_t_i_c_s

_D_e_s_c_r_i_p_t_i_o_n:

     This function calculates a saddlepoint approximation to the
     distribution of a linear combination of *W* at a particular point
     'u', where *W* is a vector of random variables.  The distribution 
     of *W* may be multinomial (default), Poisson or binary.  Other
     distributions are possible also if the  adjusted cumulant
     generating function and its second derivative are given.  
     Conditional saddlepoint approximations to the distribution of one
     linear  combination given the values of other linear combinations
     of *W* can be calculated for *W* having binary or Poisson
     distributions.

_U_s_a_g_e:

     saddle(A=NULL, u=NULL, wdist="m", type="simp", d=NULL, d1=1, 
            init=rep(0.1, d), mu=rep(0.5, n), LR=FALSE, strata=NULL, 
            K.adj=NULL, K2=NULL)

_A_r_g_u_m_e_n_t_s:

       A: A vector or matrix of known coefficients of the linear
          combinations of *W*. It is a required argument unless 'K.adj'
          and 'K2' are supplied, in which case  it is ignored. 

       u: The value at which it is desired to calculate the saddlepoint
          approximation to the distribution of the linear combination
          of *W*. It is a required argument unless 'K.adj' and 'K2' are
          supplied, in which case it is ignored. 

   wdist: The distribution of *W*.  This can be one of '"m"'
          (multinomial), '"p"'  (Poisson), '"b"' (binary) or "o"
          (other).  If K.adj and K2 are given   'wdist' is set to "o". 

    type: The type of saddlepoint approximation.  Possible types are
          '"simp"' for simple saddlepoint and '"cond"' for the
          conditional saddlepoint.  When 'wdist' is '"o"' or '"m"',
          'type' is automatically set to '"simp"', which is the only
          type of saddlepoint currently implemented for those
          distributions. 

       d: This specifies the dimension of the whole statistic.  This
          argument is required only when 'wdist="o"' and defaults to 1
          if not supplied in that case.  For other distributions it is
          set to 'ncol(A)'. 

      d1: When 'type' is '"cond"' this is the dimension of the
          statistic of interest which must be less than 'length(u)'. 
          Then the saddlepoint approximation to the conditional
          distribution of the first 'd1' linear combinations given the
          values of the remaining combinations is found.  Conditional
          distribution function approximations can only be found if the
          value of 'd1' is 1.  

    init: Used if 'wdist' is either '"m"' or '"o"', this gives initial
          values to  'nlmin' which is used to solve the saddlepoint
          equation.   

      mu: The values of the parameters of the distribution of *W* when
          'wdist' is '"m"', '"p"' '"b"'.  'mu' must be of the same
          length as W (i.e. 'nrow(A)'). The default is that all values
          of 'mu' are equal and so the elements of *W* are identically
          distributed. 

      LR: If 'TRUE' then the Lugananni-Rice approximation to the cdf is
          used, otherwise the approximation used is based on
          Barndorff-Nielsen's r*.  

  strata: The strata for stratified data. 

   K.adj: The adjusted cumulant generating function used when 'wdist'
          is '"o"'.   This is a function of a single parameter, 'zeta',
           which calculates  'K(zeta)-u%*%zeta', where 'K(zeta)' is the
          cumulant generating function  of *W*. 

      K2: This is a function of a single parameter 'zeta' which returns
          the  matrix of second derivatives of 'K(zeta)' for use when
          'wdist' is '"o"'.   If 'K.adj' is given then this must be
          given also.  It is called only once with the calculated
          solution to the saddlepoint equation being passed as  the
          argument.  This argument is ignored if 'K.adj' is not
          supplied. 

_D_e_t_a_i_l_s:

     If 'wdist' is '"o"' or '"m"', the saddlepoint equations are solved
     using 'nlmin' to minimize 'K.adj' with respect to its parameter
     'zeta'.  For the Poisson and binary cases, a generalized linear
     model is fitted such  that the parameter  estimates solve the
     saddlepoint equations.  The response variable 'y' for the 'glm'
     must satisfy the equation 't(A)%*%y=u' ('t()' being the transpose 
     function).  Such a vector can be found as a feasible solution to a
     linear programming problem.  This is done by a call to 'simplex'. 
     The covariate matrix for the 'glm' is given by 'A'.

_V_a_l_u_e:

     A list consisting of the following components

     spa: The saddlepoint approximations.  The first value is the
          density approximation and the second value is the
          distribution function approximation. 

zeta.hat: The solution to the saddlepoint equation.  For the
          conditional saddlepoint this is the solution to the
          saddlepoint equation for the numerator. 

zeta2.hat: If 'type' is '"cond"' this is the solution to the
          saddlepoint equation for the  denominator.  This component is
          not returned for any other value of 'type'. 

_R_e_f_e_r_e_n_c_e_s:

     Booth, J.G. and Butler, R.W. (1990) Randomization distributions
     and  saddlepoint approximations in generalized linear models. 
     _Biometrika_, *77*, 787-796.

     Canty, A.J. and Davison, A.C. (1997) Implementation of saddlepoint
      approximations to resampling distributions.   _Computing Science
     and Statistics; Proceedings of the 28th Symposium on the
     Interface_, 248-253.

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

     Jensen, J.L. (1995) _Saddlepoint Approximations_. Oxford
     University Press.

_S_e_e _A_l_s_o:

     'saddle.distn', 'simplex'

_E_x_a_m_p_l_e_s:

     # To evaluate the bootstrap distribution of the mean failure time of 
     # air-conditioning equipment at 80 hours
     saddle(A=aircondit$hours/12, u=80)

     # Alternatively this can be done using a conditional poisson
     saddle(A=cbind(aircondit$hours/12,1), u=c(80,12), wdist="p", type="cond")

     # To use the Lugananni-Rice approximation to this
     saddle(A=cbind(aircondit$hours/12,1), u=c(80,12), wdist="p", type="cond", 
            LR = TRUE)

     # Example 9.16 of Davison and Hinkley (1997) calculates saddlepoint 
     # approximations to the distribution of the ratio statistic for the
     # city data. Since the statistic is not in itself a linear combination
     # of random Variables, its distribution cannot be found directly.  
     # Instead the statistic is expressed as the solution to a linear 
     # estimating equation and hence its distribution can be found.  We
     # get the saddlepoint approximation to the pdf and cdf evaluated at
     # t=1.25 as follows.
     jacobian <- function(dat,t,zeta)
     {
          p <- exp(zeta*(dat$x-t*dat$u))
          abs(sum(dat$u*p)/sum(p))
     }
     city.sp1 <- saddle(A=city$x-1.25*city$u, u=0)
     city.sp1$spa[1] <- jacobian(city, 1.25, city.sp1$zeta.hat) * city.sp1$spa[1]
     city.sp1