tggd_ln {tggd}

The Truncated Generalised Gamma Distribution

Description

Density, distribution function, quantile function and random generation for the Truncated Generalised Gamma Distribution in natural log (ln) space. Specifically, if exp(x) is drawn from a TGGD distribution (in real space), these functions give the distribution of x, using the same parameter values.

Usage

dtggd_ln(x, scale=log(1e14), a=-1, b=1, xmin=log(1e10), log = FALSE)
ptggd_ln(q, scale=log(1e14), a=-1, b=1, xmin=log(1e10), lower.tail = TRUE, log.p = FALSE)
qtggd_ln(p, scale=log(1e14), a=-1, b=1, xmin=log(1e10), lower.tail = TRUE, log.p = FALSE,
res.approx=1e-2)
rtggd_ln(n, scale=log(1e14), a=-1, b=1, xmin=log(1e10), res.approx=1e-2)

Arguments

x, q

Vector of quantiles.

p

Vector of probabilities.

n

Number of observations. If length(n) > 1, the length is taken to be the number required.

scale

Vector of values for scale, which controls the transition regime between the power law slope and the exponential cut-off of the TGGD. This is analogous to the scale parameter for the standard Gamma distribution (see GammaDist).

a

Vector of values for a, which controls the power law slope of the TGGD.

b

Vector of values for b, which controls the exponential cutoff of the TGGD.

xmin

Vector of values for xmin, which controls the lower limit at which to trancate the TGGD.

res.approx

The resolution used to create the inverted CDF required to map probability integrals back onto quantiles.

log, log.p

Logical; if TRUE, probabilities/densities p are returned as log(p).

lower.tail

Logical; if TRUE (default), probabilities are P[X <= x], otherwise, P[X > x].

Details

This distribution function is described in detail in Murray, Robotham and Power 2016.

f(x;a,b,s,m) = \frac{b \exp((x-s)^{(a+1)}) \exp(-\exp(b(x-s)))}{s \Gamma(\frac{a+1}{b},\exp(m-s)^b)}

where, from the argument list above, we use x=x, a=a, b=b, s=scale and m=xmin. \Gamma is the upper incomplete Gamma function as defined by the gsl gamma_inc function, using the same argument ordering, where gamma_inc(a,x)==pgamma(x,a,lower=FALSE)*gamma(x) for a>0. gamma_inc is used because it allows for the computation of upper incomplete integrals in cases where a<=0.

Value

dtggd_ln gives the density, ptggd_ln gives the distribution function, qtggd_ln gives the quantile function, and rtggd_ln generates random deviates.

Invalid arguments will result in return value NaN, with a warning.

The length of the result is determined by n for rtggd_ln, and is the maximum of the lengths of the numerical arguments for the other functions.

The numerical arguments other than n are recycled to the length of the result. Only the first elements of the logical arguments are used.

Note

The intended application of the log-space version of the TGGD is to provide the correct distribution when variates are drawn from a real-space TGGD, but there are priors on their uncertainty which operate in logspace (eg. a lognormal distribution). The likelihood of a given set of parameters is incorrect in such a case if the real-space version is used without an adjustment to the Jacobian.

Author(s)

Aaron Robotham, Steven Murray

References

Murray, Robotham and Power (2016)

See Also

GammaDist regarding the Gamma distribution. RNG about random number generation in R. Distributions for other standard distributions.

Examples

r <- rtggd_ln(100,a=-2)
hist(r)

##Ideally the output below should equal 0, in practice it will be very close:
qtggd_ln(ptggd_ln(r))-r

#These should be the same:
integrate(dtggd_ln,lower=log(1e10),upper=log(1e11),a=-1.5,b=0.7,xmin=log(1e10))
ptggd_ln(log(1e11),a=-1.5,b=0.7,xmin=log(1e10))

#This should be very close to 1 (for a true PDF):
ptggd_ln(log(1e18),a=-1.5,b=0.7,xmin=log(1e10))

#To show the link to the linear and log10 (called log) variants (and the slight
#inaccuracies) these outputs should be a sequence from 0 to 1 (by=0.1):
ptggd_log(log10(qtggd(seq(0,1,by=0.1))))
ptggd_log(qtggd_ln(seq(0,1,by=0.1))/log(10))