Multinomial              package:stats              R Documentation

The Multinomial Distribution

Description:

     Generate multinomially distributed random number vectors and
     compute multinomial "density" probabilities.

Usage:

     rmultinom(n, size, prob)
     dmultinom(x, size = NULL, prob, log = FALSE)

Arguments:

       x: vector of length K of integers in '0:size'.

       n: number of random vectors to draw.

    size: integer, say N, specifying the total number of objects that
          are put into K boxes in the typical multinomial experiment.
          For 'dmultinom', it defaults to 'sum(x)'.

    prob: numeric non-negative vector of length K, specifying the
          probability for the K classes; is internally normalized to
          sum 1.

     log: logical; if TRUE, log probabilities are computed.

Details:

     If 'x' is a $K$-component vector, 'dmultinom(x, prob)' is the
     probability

      P(X[1]=x[1],...,X[K]=x[k]) = C * prod(j=1,..,K) p[j]^x[j]

     where C is the "multinomial coefficient" C = N! / (x[1]! * ... *
     x[K]!) and N = sum(j=1,..,K) x[j]. 
      By definition, each component X[j] is binomially distributed as
     'Bin(size, prob[j])' for j = 1,...,K.

     The 'rmultinom()' algorithm draws binomials from Bin(n[j], P[j])
     sequentially, where n[1] = N (N := 'size'), P[1] = p[1] (p is
     'prob' scaled to sum 1), and for j >= 2, recursively n[j]= N -
     sum(k=1, .., j-1) n[k] and P[j]= p[j] / (1 - sum(p[1:(j-1)])).

Value:

     For 'rmultinom()', an integer 'K x n' matrix where each column is
     a random vector generated according to the desired multinomial
     law, and hence summing to 'size'.  Whereas the _transposed_ result
     would seem more natural at first, the returned matrix is more
     efficient because of columnwise storage.

Note:

     'dmultinom' is currently _not vectorized_ at all and has no C
     interface (API); this may be amended in the future.

See Also:

     'rbinom' which is a special case conceptually.

Examples:

     rmultinom(10, size = 12, prob=c(0.1,0.2,0.8))

     pr <- c(1,3,6,10) # normalization not necessary for generation
     rmultinom(10, 20, prob = pr)

     ## all possible outcomes of Multinom(N = 3, K = 3)
     X <- t(as.matrix(expand.grid(0:3, 0:3))); X <- X[, colSums(X) <= 3]
     X <- rbind(X, 3:3 - colSums(X)); dimnames(X) <- list(letters[1:3], NULL)
     X
     round(apply(X, 2, function(x) dmultinom(x, prob = c(1,2,5))), 3)

