# Cumulants Class For Saddlepoint Approximations 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. ```r 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. ## 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. ## Returns `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. ## References Reid, N. (1991). Approximations and Asymptotics. **Statistical Theory and Modelling**, London: Chapman and Hall. ## Author(s) Thorn Thaler ## See Also `edgeworth`, `saddlepoint` ## Examples ```r # 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 ```

cumulants function