cumulants {EQL} | R Documentation |
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.
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, ...)
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. |
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
cumulants
object
and
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.
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.
Thorn Thaler
Reid, N. (1991). Approximations and Asymptotics. Statistical Theory and Modelling, London: Chapman and Hall.
# 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