| % File src/library/utils/man/combn.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2017 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{combn} |
| \alias{combn} |
| \title{Generate All Combinations of n Elements, Taken m at a Time} |
| \description{ |
| Generate all combinations of the elements of \code{x} taken \code{m} |
| at a time. If \code{x} is a positive integer, returns all |
| combinations of the elements of \code{seq(x)} taken \code{m} at a |
| time. If argument \code{FUN} is not \code{NULL}, applies a function given |
| by the argument to each point. If simplify is FALSE, returns |
| a list; otherwise returns an \code{\link{array}}, typically a |
| \code{\link{matrix}}. \code{...} are passed unchanged to the |
| \code{FUN} function, if specified. |
| } |
| \usage{ |
| combn(x, m, FUN = NULL, simplify = TRUE, \dots) |
| } |
| \arguments{ |
| \item{x}{vector source for combinations, or integer \code{n} for |
| \code{x <- \link{seq_len}(n)}.} |
| \item{m}{number of elements to choose.} |
| \item{FUN}{function to be applied to each combination; default |
| \code{NULL} means the identity, i.e., to return the combination |
| (vector of length \code{m}).} |
| \item{simplify}{logical indicating if the result should be simplified |
| to an \code{\link{array}} (typically a \code{\link{matrix}}); if |
| FALSE, the function returns a \code{\link{list}}. Note that when |
| \code{simplify = TRUE} as by default, the dimension of the result is |
| simply determined from \code{FUN(\var{1st combination})} (for |
| efficiency reasons). This will badly fail if \code{FUN(u)} is not of |
| constant length.} |
| \item{\dots}{optionally, further arguments to \code{FUN}.} |
| } |
| \details{ |
| Factors \code{x} are accepted. |
| } |
| \value{ |
| A \code{\link{list}} or \code{\link{array}}, see the \code{simplify} |
| argument above. In the latter case, the identity |
| \code{dim(combn(n, m)) == c(m, choose(n, m))} holds. |
| } |
| \references{ |
| Nijenhuis, A. and Wilf, H.S. (1978) |
| \emph{Combinatorial Algorithms for Computers and Calculators}; |
| Academic Press, NY. |
| } |
| \author{Scott Chasalow wrote the original in 1994 for S; |
| R package \CRANpkg{combinat} and documentation by Vince Carey |
| \email{stvjc@channing.harvard.edu}; |
| small changes by the R core team, notably to return an array in all |
| cases of \code{simplify = TRUE}, e.g., for \code{combn(5,5)}. |
| } |
| \seealso{ |
| \code{\link{choose}} for fast computation of the \emph{number} of |
| combinations. \code{\link{expand.grid}} for creating a data frame from |
| all combinations of factors or vectors. |
| } |
| \examples{ |
| combn(letters[1:4], 2) |
| (m <- combn(10, 5, min)) # minimum value in each combination |
| mm <- combn(15, 6, function(x) matrix(x, 2, 3)) |
| stopifnot(round(choose(10, 5)) == length(m), is.array(m), # 1-dimensional |
| c(2,3, round(choose(15, 6))) == dim(mm)) |
| |
| ## Different way of encoding points: |
| combn(c(1,1,1,1,2,2,2,3,3,4), 3, tabulate, nbins = 4) |
| |
| ## Compute support points and (scaled) probabilities for a |
| ## Multivariate-Hypergeometric(n = 3, N = c(4,3,2,1)) p.f.: |
| # table.mat(t(combn(c(1,1,1,1,2,2,2,3,3,4), 3, tabulate, nbins = 4))) |
| |
| ## Assuring the identity |
| for(n in 1:7) |
| for(m in 0:n) stopifnot(is.array(cc <- combn(n, m)), |
| dim(cc) == c(m, choose(n, m)), |
| identical(cc, combn(n, m, identity)) || m == 1) |
| } |
| \keyword{utilities} |
| \keyword{iteration} |