

saddle(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 par-
     ticular point `u', where W is a vector of random vari-
     ables.  The distribution of W may be multinomial
     (default), Poisson or binary.  Other distributions are
     possible also if the adjusted cumulant generating func-
     tion 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=F, 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 argu-
          ment 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 saddle-
          point currently implemented for those distribu-
          tions.

       d: This specifies the dimension of the whole statis-
          tic.  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 dis-
          tribution 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 dis-
          tributed.

      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 cumu-
          lant 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 dis-
     tributions and saddlepoint approximations in general-
     ized 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 Meth-
     ods 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
     data(aircondit)
     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=T)

     # 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))
     }
     data(city)
     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

