

   SSaaddddlleeppooiinntt AApppprrooxxiimmaattiioonnss ffoorr BBoooottssttrraapp SSttaattiissttiiccss

        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Arrgguummeenntts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Deessccrriippttiioon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.

   DDeettaaiills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Vaalluue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Reeffeerreennccees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Seeee AAllssoo::

        `saddle.distn', `simplex'

   EExxaammppllees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

