simEd (version 2.0.0)

sample: Random Samples

Description

sample takes a sample of the specified size from the elements of x, either with or without replacement, and with capability to use independent streams and antithetic variates in the draws.

Usage

sample(
  x,
  size,
  replace = FALSE,
  prob = NULL,
  stream = NULL,
  antithetic = FALSE
)

Arguments

x

Either a vector of one or more elements from which to choose, or a positive integer

size

A non-negative integer giving the number of items to choose

replace

If FALSE (default), sampling is without replacement; otherwise, sample is with replacement

prob

A vector of probability weights for obtaining the elements of the vector being sampled

stream

If NULL (default), directly calls base::sample and returns its result; otherwise, an integer in 1:100 indicates the rstream stream used to generate the sample

antithetic

If FALSE (default), uses \(u\) = uniform(0,1) variate(s)generated via rstream::rstream.sample to generate the sample; otherwise, uses \(1 - u\). (NB: ignored if stream is NULL.)

Value

If x is a single positive integer, sample returns a vector drawn from the integers 1:x. Otherwise, sample returns a vector, list, or data frame consistent with typeof(x).

Details

If stream is NULL, sampling is done by direct call to base::sample (refer to its documentation for details). In this case, a value of TRUE for antithetic is ignored.

The remainder of details below presume that stream has a positive integer value, corresponding to use of the vunif variate generator for generating the random sample.

If x has length 1 and is numeric, sampling takes place from 1:x only if x is a positive integer; otherwise, sampling takes place using the single value of x provided (either a floating-point value or a non-positive integer). Otherwise x can be a valid R vector, list, or data frame from which to sample.

The default for size is the number of items inferred from x, so that sample(x, stream = \(m\)) generates a random permutation of the elements of x (or 1:x) using random number stream \(m\).

It is allowed to ask for size = 0 samples (and only then is a zero-length x permitted), in which case base::sample is invoked to return the correct (empty) data type.

The optional prob argument can be used to give a vector of probabilities for obtaining the elements of the vector being sampled. Unlike base::sample, the weights here must sum to one. If replace is false, these probabilities are applied successively; that is the probability of choosing the next item is proportional to the weights among the remaining items. The number of nonzero probabilities must be at least size in this case.

See Also

base::sample, vunif

Examples

# NOT RUN {
 set.seed(8675309)

 # use base::sample (since stream is NULL) to generate a permutation of 1:5
 sample(5)

 # use vunif(1, stream = 1) to generate a permutation of 1:5
 sample(5, stream = 1)

 # generate a (boring) sample of identical values drawn using the single value 867.5309
 sample(867.5309, size = 10, replace = TRUE, stream = 1)

 # use vunif(1, stream = 1) to generate a size-10 sample drawn from 7:9
 sample(7:9, size = 10, replace = TRUE, stream = 1)

 # use vunif(1, stream = 1) to generate a size-10 sample drawn from c('x','y','z')
 sample(c('x','y','z'), size = 10, replace = TRUE, stream = 1)

 # use vunif(1, stream = 1) to generate a size-5 sample drawn from a list
 mylist <- list()
 mylist$a <- 1:5
 mylist$b <- 2:6
 mylist$c <- 3:7
 sample(mylist, size = 5, replace = TRUE, stream = 1)

 # use vunif(1, stream = 1) to generate a size-5 sample drawn from a data frame
 mydf <- data.frame(a = 1:6, b = c(1:3, 1:3))
 sample(mydf, size = 5, replace = TRUE, stream = 1)

# }