| % File src/library/stats/man/Multinomal.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2014 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{Multinom} |
| \alias{Multinomial} |
| \alias{rmultinom} |
| \alias{dmultinom} |
| \title{The Multinomial Distribution} |
| \description{ |
| Generate multinomially distributed random number vectors and |
| compute multinomial probabilities. |
| } |
| \usage{ |
| rmultinom(n, size, prob) |
| dmultinom(x, size = NULL, prob, log = FALSE) |
| } |
| \arguments{ |
| \item{x}{vector of length \eqn{K} of integers in \code{0:size}.} |
| %%FUTURE: matrix of \eqn{K} rows or ... |
| \item{n}{number of random vectors to draw.} |
| \item{size}{integer, say \eqn{N}, specifying the total number |
| of objects that are put into \eqn{K} boxes in the typical multinomial |
| experiment. For \code{dmultinom}, it defaults to \code{sum(x)}.} |
| \item{prob}{numeric non-negative vector of length \eqn{K}, specifying |
| the probability for the \eqn{K} classes; is internally normalized to |
| sum 1. Infinite and missing values are not allowed.} |
| \item{log}{logical; if TRUE, log probabilities are computed.} |
| } |
| \note{\code{dmultinom} is currently \emph{not vectorized} at all and has |
| no C interface (API); this may be amended in the future.% yes, DO THIS! |
| } |
| \details{ |
| If \code{x} is a \eqn{K}-component vector, \code{dmultinom(x, prob)} |
| is the probability |
| \deqn{P(X_1=x_1,\ldots,X_K=x_k) = C \times \prod_{j=1}^K |
| \pi_j^{x_j}}{P(X[1]=x[1], \dots , X[K]=x[k]) = C * prod(j=1 , \dots, K) p[j]^x[j]} |
| where \eqn{C} is the \sQuote{multinomial coefficient} |
| \eqn{C = N! / (x_1! \cdots x_K!)}{C = N! / (x[1]! * \dots * x[K]!)} |
| and \eqn{N = \sum_{j=1}^K x_j}{N = sum(j=1, \dots, K) x[j]}. |
| \cr |
| By definition, each component \eqn{X_j}{X[j]} is binomially distributed as |
| \code{Bin(size, prob[j])} for \eqn{j = 1, \ldots, K}. |
| |
| The \code{rmultinom()} algorithm draws binomials \eqn{X_j}{X[j]} from |
| \eqn{Bin(n_j,P_j)}{Bin(n[j], P[j])} sequentially, where |
| \eqn{n_1 = N}{n[1] = N} (N := \code{size}), |
| \eqn{P_1 = \pi_1}{P[1] = p[1]} (\eqn{\pi}{p} is \code{prob} scaled to sum 1), |
| and for \eqn{j \ge 2}, recursively, |
| \eqn{n_j = N - \sum_{k=1}^{j-1} X_k}{n[j] = N - sum(k=1, \dots, j-1) X[k]} |
| and |
| \eqn{P_j = \pi_j / (1 - \sum_{k=1}^{j-1} \pi_k)}{P[j] = p[j] / (1 - sum(p[1:(j-1)]))}. |
| } |
| \value{ |
| For \code{rmultinom()}, |
| an integer \eqn{K \times n}{K x n} matrix where each column is a |
| random vector generated according to the desired multinomial law, and |
| hence summing to \code{size}. Whereas the \emph{transposed} result |
| would seem more natural at first, the returned matrix is more |
| efficient because of columnwise storage. |
| } |
| \seealso{ |
| \link{Distributions} for standard distributions, including |
| \code{\link{dbinom}} which is a special case conceptually. |
| %% but does not return 2-vectors |
| } |
| \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) |
| } |
| \keyword{distribution} |