permCheck: Number of possible permutations and checking of permutation schemes

Description

permCheck provides checking of permutation schemes for validity. numPerms calculates the maximum number of permutations possible under the current permutation scheme. getNumObs is a utility function to return the number of observations for a range of R and ordination objects.

Usage

permCheck(object, control = permControl())
## S3 method for class 'permCheck':
summary(object, \dots)
numPerms(object, control = permControl())
getNumObs(object, ...)
## S3 method for class 'default':
getNumObs(object, \dots)
## S3 method for class 'numeric':
getNumObs(object, \dots)
## S3 method for class 'integer':
getNumObs(object, \dots)

Arguments

object

an R object. Specifically, any object handled by scores, data frames, matrices, and numeric and integer vectors. For summary.permCheck an o

control

a list of control values describing properties of the permutation design, as returned by a call to permControl.

...

arguments to other methods.

Value

For permCheck a list containing the maximum number of permutations possible and an object of class "permControl".
For numPerms, the (numeric) number of possible permutations.
For getNumObs, the (numeric) number of observations in object.

Details

permCheck and numPerms are utility functions for working with the new permutation schemes available in permuted.index2.

permCheck is used to check the current permutation schemes against the object to which it will be applied. It calculates the maximum number of possible permutations for the number of observations in object and the permutation scheme described by control. The returned object contains component control, an object of class "permControl" suitably modified if permCheck identifies a problem.

The main problem is requesting more permutations than possible with the number of observations and the permutation design. In such cases, nperm is reduced to equal the number of possible permutations, and complete enumeration of all permutations is turned on (control$complete is set to TRUE).

Alternatively, if the number of possible permutations is low, and less than control$minperm, it is better to enumerate all possible permutations, and as such complete enumeration of all permutations is turned on (control$complete is set to TRUE).

Examples

Run this code

## use example data from ?pyrifos
example(pyrifos)

## Demonstrate the maximum number of permutations for the pyrifos data
## under a series of permutation schemes

## no restrictions - lots of perms
(check1 <- permCheck(pyrifos, control = permControl(type = "free")))
summary(check1)

## no strata but data are series with no mirroring, so 132 permutations
permCheck(pyrifos, control = permControl(type = "series",
                   mirror = FALSE))

## no strata but data are series with mirroring, so 264 permutations
permCheck(pyrifos, control = permControl(type = "series",
                   mirror = TRUE))

## unrestricted within strata
permCheck(pyrifos, control = permControl(strata = ditch,
                   type = "free"))

## time series within strata, no mirroring
permCheck(pyrifos, control = permControl(strata = ditch,
                   type = "series", mirror = FALSE))

## time series within strata, with mirroring
permCheck(pyrifos, control = permControl(strata = ditch,
                   type = "series", mirror = TRUE))

## time series within strata, no mirroring, same permutation within strata
permCheck(pyrifos, control = permControl(strata = ditch,
                   type = "series", constant = TRUE))

## time series within strata, with mirroring, same permutation within strata
permCheck(pyrifos, control = permControl(strata = ditch,
                   type = "series", mirror = TRUE, constant = TRUE))

## permute strata
permCheck(pyrifos, permControl(strata = ditch, type = "strata"))

## this should also also for arbitrary vectors
vec1 <- permCheck(1:100)
vec2 <- permCheck(1:100, permControl())
all.equal(vec1, vec2)
vec3 <- permCheck(1:100, permControl(type = "series"))
all.equal(100, vec3$n)
vec4 <- permCheck(1:100, permControl(type = "series", mirror = TRUE))
all.equal(vec4$n, 200)