combn                 package:utils                 R Documentation

Generate All Combinations of n Elements, Taken m at a Time

Description:

     Generate all combinations of the elements of 'x' taken 'm' at a
     time.  If 'x' is a positive integer, returns all combinations of
     the elements of 'seq(x)' taken 'm' at a time.  If argument 'FUN'
     is not 'NULL', applies a function given by the argument to each
     point.  If simplify is FALSE,  returns a list; otherwise returns
     an 'array', typically a 'matrix'.  '...' are passed unchanged to
     the 'FUN' function, if specified.

Usage:

     combn(x, m, FUN = NULL, simplify = TRUE, ...)

Arguments:

       x: vector source for combinations, or integer 'n' for 'x <-
          seq(n)'.

       m: number of elements to choose.

     FUN: function to be applied to each combination; default 'NULL'
          means the identity, i.e., to return the combination (vector
          of length 'm').

simplify: logical indicating if the result should be simplified to an
          'array' (typically a 'matrix'); if FALSE, the function
          returns a 'list'.  Note that when 'simplify = TRUE' as by
          default, the dimension of the result is simply determined
          from 'FUN(\emph{<1st combination>})', for efficiency reasons.
           This will badly fail if 'FUN(u)' is not of constant length.

     ...: optionally, further arguments to 'FUN'.

Value:

     a 'list' or 'array' (in nondegenerate cases), see the 'simplify'
     argument above.

Author(s):

     Scott Chasalow wrote the original in 1994 for S; R package
     'combinat' and documentation by Vince Carey
     stvjc@channing.harvard.edu; small changes by the R core team,
     notably to return an array in all cases of 'simplify = TRUE',
     e.g., for 'combn(5,5)'.

References:

     Nijenhuis, A. and Wilf, H.S. (1978) _Combinatorial Algorithms for
     Computers and Calculators_; Academic Press, NY.

See Also:

     'choose' for fast computation of the _number_ of combinations.
     '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),
               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)))

