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 

kappa2f 
the variance function. If 
rho3f , rho4f 
the 3rd and the 4th standardized cumulant function,
respectively. If 
domain 
an object of type 
... 
additional parameters to be passed to the cumulant
functions, respectively function 
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
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.
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 
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 
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) (xmu)/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