1% File src/library/stats/man/Multinomal.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2014 R Core Team
4% Distributed under GPL 2 or later
5
6\name{Multinom}
7\alias{Multinomial}
8\alias{rmultinom}
9\alias{dmultinom}
10\title{The Multinomial Distribution}
11\description{
12  Generate multinomially distributed random number vectors and
13  compute multinomial probabilities.
14}
15\usage{
16rmultinom(n, size, prob)
17dmultinom(x, size = NULL, prob, log = FALSE)
18}
19\arguments{
20  \item{x}{vector of length \eqn{K} of integers in \code{0:size}.}
21  %%FUTURE:  matrix of \eqn{K} rows or ...
22  \item{n}{number of random vectors to draw.}
23  \item{size}{integer, say \eqn{N}, specifying the total number
24    of objects that are put into \eqn{K} boxes in the typical multinomial
25    experiment. For \code{dmultinom}, it defaults to \code{sum(x)}.}
26  \item{prob}{numeric non-negative vector of length \eqn{K}, specifying
27    the probability for the \eqn{K} classes; is internally normalized to
28    sum 1. Infinite and missing values are not allowed.}
29  \item{log}{logical; if TRUE, log probabilities are computed.}
30}
31\note{\code{dmultinom} is currently \emph{not vectorized} at all and has
32  no C interface (API); this may be amended in the future.% yes, DO THIS!
33}
34\details{
35  If \code{x} is a \eqn{K}-component vector, \code{dmultinom(x, prob)}
36  is the probability
37  \deqn{P(X_1=x_1,\ldots,X_K=x_k) = C \times \prod_{j=1}^K
38    \pi_j^{x_j}}{P(X[1]=x[1], \dots , X[K]=x[k]) = C * prod(j=1 , \dots, K) p[j]^x[j]}
39  where \eqn{C} is the \sQuote{multinomial coefficient}
40  \eqn{C = N! / (x_1! \cdots x_K!)}{C = N! / (x[1]! * \dots * x[K]!)}
41  and \eqn{N = \sum_{j=1}^K x_j}{N = sum(j=1, \dots, K) x[j]}.
42  \cr
43  By definition, each component \eqn{X_j}{X[j]} is binomially distributed as
44  \code{Bin(size, prob[j])} for \eqn{j = 1, \ldots, K}.
45
46  The \code{rmultinom()} algorithm draws binomials \eqn{X_j}{X[j]} from
47  \eqn{Bin(n_j,P_j)}{Bin(n[j], P[j])} sequentially, where
48  \eqn{n_1 = N}{n[1] = N} (N := \code{size}),
49  \eqn{P_1 = \pi_1}{P[1] = p[1]} (\eqn{\pi}{p} is \code{prob} scaled to sum 1),
50  and for \eqn{j \ge 2}, recursively,
51  \eqn{n_j = N - \sum_{k=1}^{j-1} X_k}{n[j] = N - sum(k=1, \dots, j-1) X[k]}
52  and
53  \eqn{P_j = \pi_j / (1 - \sum_{k=1}^{j-1} \pi_k)}{P[j] = p[j] / (1 - sum(p[1:(j-1)]))}.
54}
55\value{
56  For \code{rmultinom()},
57  an integer \eqn{K \times n}{K x n} matrix where each column is a
58  random vector generated according to the desired multinomial law, and
59  hence summing to \code{size}.  Whereas the \emph{transposed} result
60  would seem more natural at first, the returned matrix is more
61  efficient because of columnwise storage.
62}
63\seealso{
64  \link{Distributions} for standard distributions, including
65  \code{\link{dbinom}} which is a special case conceptually.
66%% but does not return 2-vectors
67}
68\examples{
69rmultinom(10, size = 12, prob = c(0.1,0.2,0.8))
70
71pr <- c(1,3,6,10) # normalization not necessary for generation
72rmultinom(10, 20, prob = pr)
73
74## all possible outcomes of Multinom(N = 3, K = 3)
75X <- t(as.matrix(expand.grid(0:3, 0:3))); X <- X[, colSums(X) <= 3]
76X <- rbind(X, 3:3 - colSums(X)); dimnames(X) <- list(letters[1:3], NULL)
77X
78round(apply(X, 2, function(x) dmultinom(x, prob = c(1,2,5))), 3)
79}
80\keyword{distribution}
81