numPerms: Number of possible permutations for a given object

In gavinsimpson/permute: Functions for Generating Restricted Permutations of Data

Description

numPerms calculates the maximum number of permutations possible under the current permutation scheme.

Usage

numPerms(object, control = how())

Arguments

object	any object handled by nobs.
control	a list of control values describing properties of the permutation design, as returned by a call to how.

Details

Function numPerms returns the number of permutations for the passed object and the selected permutation scheme. object can be one of a data frame, matrix, an object for which a scores method exists, or a numeric or integer vector. In the case of a numeric or integer vector, a vector of length 1 can be used and it will be expanded to a vector of length object (i.e., 1:object) before computing the number of permutations. As such, object can be the number of observations not just the object containing the observations.

Value

The (numeric) number of possible permutations of observations in object.

Note

In general, mirroring "series" or "grid" designs doubles or quadruples, respectively, the number of permutations without mirroring (within levels of strata if present). This is not true in two special cases:

1. In "grid" designs where the number of columns is equal to 2, and

2. In "series" designs where the number of observations in a series is equal to 2.

For example, with 2 observations there are 2 permutations for "series" designs:

1. 1-2, and

2. 2-1.

If these two permutations were mirrored, we would have:

1. 2-1, and

2. 1-2.

It is immediately clear that this is the same set of permutations without mirroring (if one reorders the rows). A similar situation arises in "grid" designs where the number of columns per grid is equal to 2. Note that the number of rows per grid is not an issue here.

Author(s)

Gavin Simpson

See Also

shuffle and how. Additional nobs methods are provide, see nobs-methods.

Examples

## permutation design --- see ?how
ctrl <- how() ## defaults to freely exchangeable

## vector input
v <- 1:10
(obs <- nobs(v))
numPerms(v, control = ctrl)

## integer input
len <- length(v)
(obs <- nobs(len))
numPerms(len, control = ctrl)

## new design, objects are a time series
ctrl <- how(within = Within(type = "series"))
numPerms(v, control = ctrl)
## number of permutations possible drastically reduced...
## ...turn on mirroring
ctrl <- how(within = Within(type = "series", mirror = TRUE))
numPerms(v, control = ctrl)

## Try blocking --- 2 groups of 5
bl <- numPerms(v, control = how(blocks = gl(2,5)))
bl

## should be same as
pl <- numPerms(v, control = how(plots = Plots(strata = gl(2,5))))
pl
stopifnot(all.equal(bl, pl))

gavinsimpson/permute documentation built on Jan. 31, 2022, 12:05 p.m.