GammaDist               package:stats               R Documentation

_T_h_e _G_a_m_m_a _D_i_s_t_r_i_b_u_t_i_o_n

_D_e_s_c_r_i_p_t_i_o_n:

     Density, distribution function, quantile function and random
     generation for the Gamma distribution with parameters 'shape' and
     'scale'.

_U_s_a_g_e:

     dgamma(x, shape, rate = 1, scale = 1/rate, log = FALSE)
     pgamma(q, shape, rate = 1, scale = 1/rate, lower.tail = TRUE,
            log.p = FALSE)
     qgamma(p, shape, rate = 1, scale = 1/rate, lower.tail = TRUE,
            log.p = FALSE)
     rgamma(n, shape, rate = 1, scale = 1/rate)

_A_r_g_u_m_e_n_t_s:

    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.

    rate: an alternative way to specify the scale.

shape, scale: shape and scale parameters.  Must be positive, 'scale'
          strictly.

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].

_D_e_t_a_i_l_s:

     If 'scale' is omitted, it assumes the default value of '1'.

     The Gamma distribution with parameters 'shape' = a and 'scale' = s
     has density

               f(x)= 1/(s^a Gamma(a)) x^(a-1) e^-(x/s)

     for x >= 0, a > 0 and s > 0. (Here Gamma(a) is the function
     implemented by R's 'gamma()' and defined in its help.  Note that
     a=0 corresponds to the trivial distribution with all mass at point
     0.)

     The mean and variance are E(X) = a*s and Var(X) = a*s^2.

     The cumulative hazard H(t) = - log(1 - F(t)) is '-pgamma(t, ...,
     lower = FALSE, log = TRUE)'.

     Note that for smallish values of 'shape' (and moderate 'scale') a
     large parts of the mass of the Gamma distribution is on values of
     x so near zero that they will be represented as zero in computer
     arithmetic.  So 'rgamma' can well return values which will be
     represented as zero.  (This will also happen for very large values
     of 'scale' since the actual generation is done for 'scale=1'.)
     Similarly, 'qgamma' has a very hard job for small 'scale', and
     warns of potential unreliability for 'scale < 1e-10'.

_V_a_l_u_e:

     'dgamma' gives the density, 'pgamma' gives the distribution
     function, 'qgamma' gives the quantile function, and 'rgamma'
     generates random deviates.

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

_N_o_t_e:

     The S parametrization is via 'shape' and 'rate': S has no 'scale'
     parameter.

     'pgamma' is closely related to the incomplete gamma function.  As
     defined by Abramowitz and Stegun 6.5.1 (and by 'Numerical
     Recipes') this is

         P(a,x) = 1/Gamma(a) integral_0^x t^(a-1) exp(-t) dt

     P(a, x) is 'pgamma(x, a)'.  Other authors (for example Karl
     Pearson in his 1922 tables) omit the normalizing factor, defining
     the incomplete gamma function as 'pgamma(x, a) * gamma(a)'. A few
     use the 'upper' incomplete gamma function, the integral from x to
     infty which can be computed by 'pgamma(x, a, lower=FALSE) *
     gamma(a)', or its normalized version. See also <URL:
     http://en.wikipedia.org/wiki/Incomplete_gamma_function>.

_S_o_u_r_c_e:

     'dgamma' is computed via the Poisson density, using code
     contributed by Catherine Loader (see 'dbinom').

     'pgamma' uses an unpublished (and not otherwise documented)
     algorithm 'mainly by Morten Welinder'.

     'qgamma' is based on a C translation of

     Best, D. J. and D. E. Roberts (1975). Algorithm AS91. Percentage
     points of the chi-squared distribution. _Applied Statistics_, 
     *24*, 385-388.

     plus a final Newton step to improve the approximation.

     'rgamma' for 'shape >= 1' uses

     Ahrens, J. H. and Dieter, U. (1982). Generating gamma variates by
     a modified rejection technique. _Communications of the ACM_, *25*,
     47-54,

     and for '0 < shape < 1' uses

     Ahrens, J. H. and Dieter, U. (1974). Computer methods for sampling
     from gamma, beta, Poisson and binomial distributions. _Computing_,
     *12*, 223-246.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

     Shea, B. L. (1988) Algorithm AS 239,  Chi-squared and incomplete
     Gamma integral, _Applied Statistics (JRSS C)_ *37*, 466-473.

     Abramowitz, M. and Stegun, I. A. (1972) _Handbook of Mathematical
     Functions._ New York: Dover. Chapter 6: Gamma and Related
     Functions.

_S_e_e _A_l_s_o:

     'gamma' for the gamma function, 'dbeta' for the Beta distribution
     and 'dchisq' for the chi-squared distribution which is a special
     case of the Gamma distribution.

_E_x_a_m_p_l_e_s:

     -log(dgamma(1:4, shape=1))
     p <- (1:9)/10
     pgamma(qgamma(p,shape=2), shape=2)
     1 - 1/exp(qgamma(p, shape=1))

     # even for shape = 0.001 about half the mass is on numbers
     # that cannot be represented accurately (and most of those as zero)
     pgamma(.Machine$double.xmin, 0.001)
     pgamma(5e-324, 0.001)  # on most machines this is the smallest
                            # representable non-zero number
     table(rgamma(1e4, 0.001) == 0)/1e4