comboGroups Iterator

  • Returns an iterator for iterating over partitions of a vector into groups.

  • Supports random access via the [[ method.

  • GMP support allows for exploration of cases where the number of comboGroups is large.

  • Use the next methods to obtain results in lexicographical order.

comboGroupsIter(v, numGroups = NULL, grpSizes = NULL,
                retType = "matrix", Parallel = FALSE,
                nThreads = NULL)

Arguments

v

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).

numGroups

An Integer. The number of groups that the vector will be partitioned into. The default is NULL. If provided and grpSize is NULL, it must divide the length of v (if v is a vector) or v (if v is a scalar).

grpSizes

A vector of whole numbers representing the size of each group. The default is NULL. If provided, the sum of the elements must total the length of v (if v is a vector) or v (if v is a scalar).

retType

A string, "3Darray" or "matrix", that determines the shape of the output. The default is "matrix". Note, "3Darray" can only be used when the size of each group is uniform. When the size of each group varies, the return output will always be a matrix.

Parallel

Logical value indicating whether results should be generated in parallel using \(n - 1\) threads, where \(n\) is the maximum number of threads. The default is FALSE. 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.

nThreads

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

Value

  • If nextIter is called, a named vector is returned if retType = "matrix". If retType = "3Darray", a named matrix is returned.

  • Otherwise a named matrix is returned when retType = "matrix" and a named 3D array is returned when retType = "3Darray".

Details

Once you initialize a new iterator, the following methods are available:

nextIter

Retrieve the next lexicographical result

nextNIter

Pass an integer n to retrieve the next n lexicographical results

nextRemaining

Retrieve all remaining lexicographical results

currIter

Returns the current iteration

startOver

Resets the iterator

sourceVector

View the source vector

summary

Returns a list of summary information about the iterator

front

Retrieve the first lexicographical result

back

Retrieve the last lexicographical result

[[

Random access method. Pass a single value or a vector of valid indices. If a single value is passed, the internal index of the iterator will be updated, however if a vector is passed the internal state will not change. GMP support allows for flexible indexing.

Note

  • If nThreads is utilized, it will only take effect if the number of elements requested is greater than some threshold (determined internally). E.g: 

    serial   <- comboGroupsIter(50, 10)
multi    <- comboGroupsIter(50, 10, nThreads = 4)
fetch1e6 <- multi@nextNIter(1e6)  ## much faster than serial@nextNIter(1e6)
fetch1e3 <- multi@nextNIter(1e3)  ## only one thread used... same as serial@nextNIter(1e3)library(microbenchmark)
microbenchmark(multi@nextNIter(1e6), serial@nextNIter(1e6), times = 20)
microbenchmark(multi@nextNIter(1e3), serial@nextNIter(1e3), times = 20)

  • The maximum number of comboGroups that can be generated at one time is \(2^{31} - 1\).

See also

comboGroups

Author

Joseph Wood

Examples

a = comboGroupsIter(12, 3)
a@nextIter()
#> Grp1 Grp1 Grp1 Grp1 Grp2 Grp2 Grp2 Grp2 Grp3 Grp3 Grp3 Grp3 
#>    1    2    3    4    5    6    7    8    9   10   11   12 
a@nextNIter(3)
#>      Grp1 Grp1 Grp1 Grp1 Grp2 Grp2 Grp2 Grp2 Grp3 Grp3 Grp3 Grp3
#> [1,]    1    2    3    4    5    6    7    9    8   10   11   12
#> [2,]    1    2    3    4    5    6    7   10    8    9   11   12
#> [3,]    1    2    3    4    5    6    7   11    8    9   10   12
a@front()
#> Grp1 Grp1 Grp1 Grp1 Grp2 Grp2 Grp2 Grp2 Grp3 Grp3 Grp3 Grp3 
#>    1    2    3    4    5    6    7    8    9   10   11   12 
all_remaining = a@nextRemaining()
dim(all_remaining)
#> [1] 5774   12
a@summary()
#> $description
#> [1] "Partition of v of length 12 into 3 uniform groups"
#> 
#> $currentIndex
#> [1] 5776
#> 
#> $totalResults
#> [1] 5775
#> 
#> $totalRemaining
#> [1] -1
#> 
a@back()
#> Grp1 Grp1 Grp1 Grp1 Grp2 Grp2 Grp2 Grp2 Grp3 Grp3 Grp3 Grp3 
#>    1   10   11   12    2    7    8    9    3    4    5    6 
a[[5]]
#> Grp1 Grp1 Grp1 Grp1 Grp2 Grp2 Grp2 Grp2 Grp3 Grp3 Grp3 Grp3 
#>    1    2    3    4    5    6    7   12    8    9   10   11 
a@summary()
#> $description
#> [1] "Partition of v of length 12 into 3 uniform groups"
#> 
#> $currentIndex
#> [1] 5
#> 
#> $totalResults
#> [1] 5775
#> 
#> $totalRemaining
#> [1] 5770
#> 
a[[c(1, 17, 3)]]
#>      Grp1 Grp1 Grp1 Grp1 Grp2 Grp2 Grp2 Grp2 Grp3 Grp3 Grp3 Grp3
#> [1,]    1    2    3    4    5    6    7    8    9   10   11   12
#> [2,]    1    2    3    4    5    7    8   10    6    9   11   12
#> [3,]    1    2    3    4    5    6    7   10    8    9   11   12
a@summary()
#> $description
#> [1] "Partition of v of length 12 into 3 uniform groups"
#> 
#> $currentIndex
#> [1] 5
#> 
#> $totalResults
#> [1] 5775
#> 
#> $totalRemaining
#> [1] 5770
#>