Chisquare               package:stats               R Documentation

The (non-central) Chi-Squared Distribution

Description:

     Density, distribution function, quantile function and random
     generation for the chi-squared (chi^2) distribution with 'df'
     degrees of freedom and optional non-centrality parameter 'ncp'.

Usage:

     dchisq(x, df, ncp=0, log = FALSE)
     pchisq(q, df, ncp=0, lower.tail = TRUE, log.p = FALSE)
     qchisq(p, df, ncp=0, lower.tail = TRUE, log.p = FALSE)
     rchisq(n, df, ncp=0)

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.

      df: degrees of freedom (non-negative, but can be non-integer).

     ncp: non-centrality parameter (non-negative).

log, log.p: logical; if TRUE, probabilities p are given as log(p).

lower.tail: logical; if TRUE (default), probabilities are P[X <= x],
          otherwise, P[X > x].

Details:

     The chi-squared distribution with 'df'= n >= 0 degrees of freedom
     has density

        f_n(x) = 1 / (2^(n/2) Gamma(n/2))  x^(n/2-1) e^(-x/2)

     for x > 0.  The mean and variance are n and 2n.

     The non-central chi-squared distribution with 'df'= n degrees of
     freedom and non-centrality parameter 'ncp' = lambda has density

 f(x) = exp(-lambda/2) SUM_{r=0}^infty ((lambda/2)^r / r!) dchisq(x, df + 2r)

     for x >= 0.  For integer n, this is the distribution of the sum of
     squares of n normals each with variance one, lambda being the sum
     of squares of the normal means; further, 
      E(X) = n + lambda, Var(X) = 2(n + 2*lambda), and E((X - E(X))^3)
     = 8(n + 3*lambda).

     Note that the degrees of freedom 'df'= n, can be non-integer, and
     also n = 0 which is relevant for non-centrality lambda > 0, see
     Johnson et al. (1995, chapter~29).

     Note that 'ncp' values larger than about 1e5 may give inaccurate
     results with many warnings for 'pchisq' and 'qchisq'.

Value:

     'dchisq' gives the density, 'pchisq' gives the distribution
     function, 'qchisq' gives the quantile function, and 'rchisq'
     generates random deviates.

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

Source:

     The central cases are computed via the gamma distribution.

     The non-central 'dchisq' and 'rchisq' are computed as a Poisson
     mixture central of chi-squares (Johnson et al, 1995, p.436).

     The non-central 'pchisq' is for 'ncp < 80' computed from the
     Poisson mixture of central chi-squares and for larger 'ncp' based
     on a C translation of

     Ding, C. G. (1992) Algorithm AS275: Computing the non-central
     chi-squared distribution function. _Appl.Statist._, *41* 478-482.

     which computes the lower tail only (so the upper tail suffers from
     cancellation).

     The non-central 'qchisq' is based on inversion of 'pchisq'.

References:

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

     Johnson, N. L., Kotz, S. and Balakrishnan, N. (1995) _Continuous
     Univariate Distributions_, chapters 18 (volume 1) and 29 (volume
     2). Wiley, New York.

See Also:

     A central chi-squared distribution with n degrees of freedom is
     the same as a Gamma distribution with 'shape' a = n/2 and 'scale'
     s = 2.  Hence, see 'dgamma' for the Gamma distribution.

Examples:

     require(graphics)

     dchisq(1, df=1:3)
     pchisq(1, df= 3)
     pchisq(1, df= 3, ncp = 0:4)# includes the above

     x <- 1:10
     ## Chi-squared(df = 2) is a special exponential distribution
     all.equal(dchisq(x, df=2), dexp(x, 1/2))
     all.equal(pchisq(x, df=2), pexp(x, 1/2))

     ## non-central RNG -- df=0 with ncp > 0:  Z0 has point mass at 0!
     Z0 <- rchisq(100, df = 0, ncp = 2.)
     graphics::stem(Z0)

     ## Not run: 
     ## visual testing
     ## do P-P plots for 1000 points at various degrees of freedom
     L <- 1.2; n <- 1000; pp <- ppoints(n)
     op <- par(mfrow = c(3,3), mar= c(3,3,1,1)+.1, mgp= c(1.5,.6,0),
               oma = c(0,0,3,0))
     for(df in 2^(4*rnorm(9))) {
       plot(pp, sort(pchisq(rr <- rchisq(n,df=df, ncp=L), df=df, ncp=L)),
            ylab="pchisq(rchisq(.),.)", pch=".")
       mtext(paste("df = ",formatC(df, digits = 4)), line= -2, adj=0.05)
       abline(0,1,col=2)
     }
     mtext(expression("P-P plots : Noncentral  "*
                      chi^2 *"(n=1000, df=X, ncp= 1.2)"),
           cex = 1.5, font = 2, outer=TRUE)
     par(op)
     ## End(Not run)

     ## "analytical" test
     lam <- seq(0,100, by=.25)
     p00 <- pchisq(0,      df=0, ncp=lam)
     p.0 <- pchisq(1e-300, df=0, ncp=lam)
     stopifnot(all.equal(p00, exp(-lam/2)),
               all.equal(p.0, exp(-lam/2)))

