R: Utility functions for unrestricted and restricted...

shuffle-utils {permute} | R Documentation

## 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

[Package permute version 0.9-4 Index]