cumulants {EQL}

Cumulants Class For Saddlepoint Approximations

Description

A cumulants object contains all the cumulant functions that are needed to calculate the saddlepoint approximation.

The predefined functions

• gammaCumulants,

• gaussianCumulants and

• inverseGaussianCumulants

compute the cumulant functions for the normal, gamma and inverse gaussian distribution, respectively.

Usage

cumulants(saddlef, cgf = NULL, kappa2f = NULL, rho3f = NULL,
          rho4f = NULL, cgf.deriv = NULL,
          domain = interval(-Inf, Inf), ...)

gammaCumulants(shape, scale)
gaussianCumulants(mu, sigma2)
inverseGaussianCumulants(lambda, nu)

## S3 method for class 'cumulants'
check(object, ...)

Arguments

saddlef

the saddlepoint function. Corresponds to the inverse of the first derivative of the cumulant generating function (cgf).

cgf, cgf.deriv

cgf is the cumulant generating function. If NULL (the default), it will be derived from cgf.deriv (the generic derivative function of the cgf).

kappa2f

the variance function. If NULL (the default), it will be derived from the function cgf.deriv.

rho3f, rho4f

the 3rd and the 4th standardized cumulant function, respectively. If NULL (the default), the functions will be derived from cgf.deriv if supplied. If neither the cumulants nor cgf.deriv are supplied, a warning will be displayed and a flag is set in the output. In this case, saddlepoint approximations cannot make use of the correction term (see saddlepoint for further details).

domain

an object of type interval giving the domain of the random variable. Will be needed to calculate the normalizing factor. See interval for further information.

...

additional parameters to be passed to the cumulant functions, respectively function check. See section ‘Details’ for further information.

shape, scale

shape and scale parameter for the gamma distribution.

mu, sigma2

mean and variance parameter for the normal distribution.

lambda, nu

parameters for the inverse Gaussian distribution.

object

an object to be tested whether or not it meets the formal requirements.

Details

Basically, there are two ways to specify the cumulant functions using cumulants. The first one is to specify each of the following functions seperately:

• cgf

• kappa2f

• rho3f

• rho4f

Since the functions may (and probably will) depend on some additional parameters, it is necessary to include these parameters in the respective argument lists. Thus, these additional parameters must be passed to cumulants as named parameters as well. To be more specific, if one of the above functions has an extra parameter z, say, the particular value of z must be passed to the function cumulants as well (see the example). In any case, the first argument of the cumulant functions must be the value at which the particular function will be evaluated.

The other way to specify the cumulant functions is to specify the generic derivative of the cgf cgf.deriv. Its first argument must be the order of the derivative and its second the value at which it should be evaluated, followed by supplementary arguments. cgf.deriv must be capable to return the cgf itself, which corresponds to the zeroth derivative.

The function cumulants performs a basic check to test if all needed additional parameters are supplied and displays a warning if there are extra arguments in the cumulant functions, which are not specified.

The generic function check for the class cumulants tests if

• an object has the same fields as an cumulants object and

• the cumulant functions are properly vectorized, i.e. if they return a vector whenever the argument is a vector.

Value

cumulants returns an object of class cumulants containing the following components:

K

the cumulant function.

mu.inv

the saddlepoint function.

kappa2

the variance function.

rho3, rho4

the 3rd and the 4th standardized cumulant functions.

domain

an interval giving the domain of the random variable.

extra.params

extra parameter passed to cumulants, typically parameters of the underlying distribution.

type

character string equating either to “explicit” or “implicit” indicating whether the cumulant functions were passed explicitly or were derived from the generic derivative of the cgf.

missing

logical. If TRUE, the 3rd and/or the 4th cumulant function were not defined.

gammaCumulants, gaussianCumulants and inverseGaussianCumulants return a cumulants object representing the cumulant functions of the particular distribution.

Note

If it happens that one of the cumulant functions f, say, does not need any extra arguments while the others do, one have to define these extra arguments for f nonetheless. The reason is that cumulants passes any additional arguments to all defined cumulant functions and it would end up in an error, if a function is not capable of dealing with additional arguments.

Hence, it is good practice to define all cumulant functions for the same set of arguments, needed or not. An alternative is to add ... to the argument list in order to absorb any additional arguments.

The functions must be capable of handling vector input properly.

Supplementary arguments must not be named similar to the arguments of cumulants (especially any abbreviation must be avoided), for the argument matching may match an argument (thought to be an extra argument for one of the cumulant function) to an argument of cumulants. The same problem may arise, if additional cumulant function parameters are not named.

Author(s)

Thorn Thaler

References

Reid, N. (1991). Approximations and Asymptotics. Statistical Theory and Modelling, London: Chapman and Hall.

See Also

edgeworth, saddlepoint

Examples

# Define cumulant functions for the normal distribution

saddlef <- function(x, mu, sigma2) (x-mu)/sigma2
cgf <- function(x, mu, sigma2) mu*x+sigma2*x^2/2

## Not run: 

# cgf, saddlef, kappa2, rho3 and rho4 must have the same argument lists! 
# Functions are _not_ properly vectorized!
kappa2 <- function(x, sigma2) sigma2 
rho3 <- function(x) 0                 
rho4 <- function(x) 0

cc <- cumulants(saddlef, cgf, kappa2, rho3, rho4, mu=0, sigma2=1)

check(cc) # FALSE


## End(Not run)

kappa2 <- function(x, mu, sigma2)
    rep(sigma2, length(x)) 
rho3 <- function(x, mu, sigma2)   # or function(x, ...)
    rep(0, length(x))        
rho4 <- function(x, mu, sigma2)   # or function(x, ...)
    rep(0, length(x))        

cc <- cumulants(saddlef, cgf, kappa2, rho3, rho4, mu=0, sigma2=1)

cc$K(1:2)       # 0.5 2
cc$kappa2(1:2)  # 1 1
cc$mu.inv(1:2)  # 1 2
cc$rho3(1:2)    # 0 0
cc$rho4(1:2)    # 0 0

check(cc) # TRUE

# The same using the generic derivative of the cgf

K.deriv <- function(n, x, mu, sigma2) {
  if (n <= 2) {
    switch(n + 1,
           return(mu * x + sigma2 * x ^ 2 / 2), # n == 0
           return(mu + sigma2 * x),             # n == 1
           return(rep(sigma2, length(x))))      # n == 2
  } else {
    return(rep(0, length(x)))                   # n >= 3
  }
}

cc <- cumulants(saddlef, cgf.deriv=K.deriv, mu=0, sigma2=1)

cc$K(1:2)       # 0.5 2
cc$kappa2(1:2)  # 1 1
cc$mu.inv(1:2)  # 1 2
cc$rho3(1:2)    # 0 0
cc$rho4(1:2)    # 0 0

check(cc) # TRUE

# The same using a predefined function
cc <- gaussianCumulants(0, 1)

cc$K(1:2)       # 0.5 2
cc$kappa2(1:2)  # 1 1
cc$mu.inv(1:2)  # 1 2
cc$rho3(1:2)    # 0 0
cc$rho4(1:2)    # 0 0

check(cc) # TRUE