shuffle-utils: Utility functions for unrestricted and restricted...

In permute: Functions for Generating Restricted Permutations of Data

Utility functions for unrestricted and restricted permutations

Description

Unrestricted and restricted permutations for time series, line transects, spatial grids and blocking factors.

Usage

shuffleFree(x, size)

shuffleSeries(x, mirror = FALSE, start = NULL, flip = NULL)

shuffleGrid(nrow, ncol, mirror = FALSE, start.row = NULL,
            start.col = NULL, flip = NULL)

shuffleStrata(strata, type, mirror = FALSE, start = NULL, flip = NULL,
              nrow, ncol, start.row = NULL, start.col = NULL)

Arguments

x	vector of indices to permute.
size	number of random permutations required
mirror	logical; should mirroring of sequences be allowed?
start	integer; the starting point for time series permutations. If missing, a random starting point is determined.
flip	logical, length 1 (shuffleSeries) or length 2 (shuffleGrid); force mirroring of permutation. This will always return the reverse of the computed permutation. For shuffleGrid, the first element pertains to flipping rows, the second to flipping columns of the grid.
nrow, ncol	numeric; the number of rows and columns in the grid.
start.row, start.col	numeric; the starting row and column for the shifted grid permutation. If non supplied, a random starting row and column will be selected.
strata	factor; the blocks to permute.
type	character; the type of permutation used to shuffle the strata. One of "free", "grid" or "series".

Details

These are developer-level functions for generating permuted indexes from one of several restricted and unrestricted designs.

shuffleFree is a wrapper to code underlying sample, but without the extra over head of sanity checks. It is defined as sample.int(x, size, replace = FALSE). You must arrange for the correct values to be supplied, where x is a vector of indices to sample from, and size is the number of indices to sample. Sampling is done without replacement and without regard to prior probabilities. Argument size is allowed so that one can draw a single observation at random from the indices x. In general use, size would be set equal to length{x}.

Value

A integer vector of permuted indices.

Author(s)

Gavin Simpson

See Also

check, a utility function for checking permutation scheme described by how. shuffle as a user-oriented wrapper to these functions.

Examples

set.seed(3)

## draw 1 value at random from the set 1:10
shuffleFree(1:10, 1)

## permute the series 1:10
x <- 1:10
shuffleSeries(x)                ## with random starting point
shuffleSeries(x, start = 5L)    ## known starting point
shuffleSeries(x, flip = TRUE)   ## random start, forced mirror
shuffleSeries(x, mirror = TRUE) ## random start, possibly mirror

## permute a grid of size 3x3
shuffleGrid(3, 3)                      ## random starting row/col
shuffleGrid(3, 3, start.row = 2,
            start.col = 3)             ## with known row/col
shuffleGrid(3, 3, flip = rep(TRUE, 2)) ## random start, forced mirror

permute documentation built on March 18, 2022, 7:36 p.m.