randomizeFeature: Randomize or Pseudorandomize Categorical Variables
In contact: Creating Contact and Social Networks

Description Usage Arguments Details Value References Examples

This function randomizes the values in a given column (or set of columns (i.e., c(colname(x)[1], colname(x)[2]))), identified by the "feature" argument in a dataset (x).

randomizeFeature(
  x,
  feature = NULL,
  shuffle = FALSE,
  maintainDistr = TRUE,
  numRandomizations = 1
)

`x`	Data frame containing real-time-location data.
`feature`	Vector of 1 or more column names describing variables in x to be randomized.
`shuffle`	Logical. If TRUE, unique values will be replaced with another, random unique value from the same distribution with 100 certainty. For example if the values in a "dose" column c(0mg,100mg,300mg) were shuffled, one possible outcome would be: x$dose.shuff[which(x$dose == "0mg")] <- 300mg, x$dose.shuff[which(x$dose == "100mg")] <- 0mg, and x$dose.shuff[which(x$dose == "300mg")] <- 100mg. Defaults to FALSE.
`maintainDistr`	Logical. If TRUE, the number of each unique value in the column will be maintained in the function output. Otherwise, the function will draw on the initial distribution to assign randomized values, but the specific number of each unique value may not be maintained. Defaults to TRUE.
`numRandomizations`	Integer. The number of replicate data frames produced in output. Defaults to 1.

Note: the shuffle argument supercedes the maintainDistr argument. Therefore, if shuffle == TRUE, the maintainDistr argument is irrelevant.

Output is x appended with columns described below.

`...shuff`	Randomized value of specified variables.
`randomRep`	Randomization replicate.

Farine, D.R., 2017. A guide to null models for animal social network analysis. Methods in Ecology and Evolution 8:1309-1320. https://doi.org/10.1111/2041-210X.12772.

data(calves)

system.time(randomizedValues<-contact::randomizeFeature(x = calves, 
   feature = c("calftag", "date"), shuffle = TRUE, maintainDistr = TRUE, 
   numRandomizations = 3)) 
   
randomizedFrame<-data.frame(randomizedValues[[1]], stringsAsFactors = TRUE)

head(randomizedFrame) #see that randomized-value columns have been appended.