combinatoricsSample: Sample Combinations and Permutations

comboSampleR Documentation

Sample Combinations and Permutations


  • Generate a specific (lexicographically) or random sample of combinations/permutations.

  • Produce results in parallel using the Parallel or nThreads arguments.

  • GMP support allows for exploration of combinations/permutations of vectors with many elements.


comboSample(v, m = NULL, repetition = FALSE, freqs = NULL, n = NULL,
            sampleVec = NULL, seed = NULL, FUN = NULL, Parallel = FALSE,
            nThreads = NULL, namedSample = FALSE, FUN.VALUE = NULL)

permuteSample(v, m = NULL, repetition = FALSE, freqs = NULL, n = NULL,
              sampleVec = NULL, seed = NULL, FUN = NULL, Parallel = FALSE,
              nThreads = NULL, namedSample = FALSE, FUN.VALUE = NULL)



Source vector. If v is a positive integer, it will be converted to the sequence 1:v. If v is a negative integer, it will be converted to the sequence v:-1. All atomic types are supported (See is.atomic).


Number of elements to choose. If repetition = TRUE or freqs is utilized, m can exceed the length of v. If m = NULL, the length will default to length(v) or sum(freqs).


Logical value indicating whether combinations/permutations should be with or without repetition. The default is FALSE.


A vector of frequencies used for producing all combinations/permutations of a multiset of v. Each element of freqs represents how many times each element of the source vector, v, is repeated. It is analogous to the times argument in rep. The default value is NULL.


Number of combinations/permutations to return. The default is NULL.


A vector of indices representing the lexicographical combination/permutations to return. Accepts whole numbers as well as vectors of class bigz as well as vectors of characters


Random seed initialization. The default is NULL. N.B. If the gmp library is needed, this parameter must be set in order to have reproducible results (E.g set.seed() has no effect in these cases).


Function to be applied to each combination/permutation. The default is NULL.


Logical value indicating whether combinations/permutations should be generated in parallel. The default is FALSE. If TRUE and nThreads = NULL, the number of threads used is equal to the minimum of one minus the number of threads available on your system and the number of results requested (e.g. if user has 16 threads and only needs 5 results, 5 threads will be used (i.e. min(16 - 1, 5) = 5)). If nThreads is not NULL, it will be given preference (e.g. if user has 8 threads with Parallel = TRUE and nThreads = 4, only 4 threads will be spawned). If your system is single-threaded, the arguments Parallel and nThreads are ignored.


Specific number of threads to be used. The default is NULL. See Parallel.


Logical flag. If TRUE, rownames corresponding to the lexicographical combination/permutation, will be added to the returned matrix. The default is FALSE.


A template for the return value from FUN. See 'Details' of vapply for more information.


These algorithms rely on efficiently generating the n^{th} lexicographical combination/permutation. This is the process of unranking.


  • In general, a matrix with m or m + 1 columns, depending on the value of keepResults

  • If FUN is utilized and FUN.VALUE = NULL, a list is returned

  • When both FUN and FUN.VALUE are not NULL, the return is modeled after the return of vapply. See the 'Value' section of vapply.


  • Parallel and nThreads will be ignored in the following cases:

    • If the class of the vector passed is character (N.B. Rcpp::CharacterMatrix is not thread safe). Alternatively, you can generate an indexing matrix in parallel.

    • If FUN is utilized.

  • n and sampleVec cannot both be NULL.

  • Factor vectors are accepted. Class and level attributes are preserved except when FUN is used.


Joseph Wood


Lexicographical order

See Also

comboRank, permuteRank


## generate 10 random combinations
comboSample(30, 8, TRUE, n = 5, seed = 10)

## using sampleVec to generate specific permutations
permuteSample(15, 10, freqs = c(1,2,2,1,2,2,1,2,1,2,2,1,2,1,1),
              sampleVec = c(1, 10^2, 10^5, 10^8, 10^11))

all.equal(comboSample(10, 5,
            sampleVec = 1:comboCount(10, 5)),
         comboGeneral(10, 5))

## Examples with enormous number of total permutations
num = permuteCount(10000, 20)
## [1] 265.7268

first = gmp::urand.bigz(n = 1, size = 265, seed = 123)
mySamp =, lapply(0:10, function(x) gmp::add.bigz(first, x)))

## [1] "bigz"

## using permuteSample
pSamp = permuteSample(10000, 20, sampleVec = mySamp)

## using permuteGeneral
pGeneral = permuteGeneral(10000, 20,
                          lower = first,
                          upper = gmp::add.bigz(first, 10))

identical(pSamp, pGeneral)
## [1] TRUE

## Using nThreads
permPar = permuteSample(10000, 50, n = 8, seed = 10, nThreads = 2)

## Using FUN
permuteSample(10000, 50, n = 4, seed = 10, FUN = sd)

## Not run: 
## Using Parallel
permuteSample(10000, 50, n = 80, seed = 10, Parallel = TRUE)

## End(Not run)

RcppAlgos documentation built on Oct. 3, 2023, 1:07 a.m.