sample                 package:base                 R Documentation

_R_a_n_d_o_m _S_a_m_p_l_e_s _a_n_d _P_e_r_m_u_t_a_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     'sample' takes a sample of the specified size from the elements of
     'x' using either with or without replacement.

_U_s_a_g_e:

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

     sample.int(n, size, replace = FALSE, prob = NULL)

_A_r_g_u_m_e_n_t_s:

       x: Either a (numeric, complex, character or logical) vector of
          more than one element from which to choose, or a positive
          integer.

       n: a non-negative integer, the number of items to choose from.

    size: positive integer giving the number of items to choose.

 replace: Should sampling be with replacement?

    prob: A vector of probability weights for obtaining the elements of
          the vector being sampled.

_D_e_t_a_i_l_s:

     If 'x' has length 1, is numeric (in the sense of 'is.numeric') and
     'x >= 1', sampling _via_ 'sample' takes place from '1:x'.  _Note_
     that this convenience feature may lead to undesired behaviour when
     'x' is of varying length 'sample(x)'.  See the 'resample()'
     example below.

     By default 'size' is equal to 'length(x)' so that 'sample(x)'
     generates a random permutation of the elements of 'x' (or '1:x').

     The optional 'prob' argument can be used to give a vector of
     weights for obtaining the elements of the vector being sampled.
     They need not sum to one, but they should be nonnegative and not
     all zero.  If 'replace' is true, Walker's alias method (Ripley,
     1987) is used when there are more than 250 reasonably probable
     values: this gives results incompatible with those from R < 2.2.0,
     and there will be a warning the first time this happens in a
     session.

     If 'replace' is false, these probabilities are applied
     sequentially, that is the probability of choosing the next item is
     proportional to the weights amongst the remaining items.  The
     number of nonzero weights must be at least 'size' in this case.

     'sample.int' is a bare interface in which both 'n' and 'size' must
     be supplied as integers.

_V_a_l_u_e:

     For 'sample' a vector of length 'size' with elements drawn from
     either 'x' or from '1:x'.

     For 'sample.int', an integer vector of length 'size' with elements
     from '1:n',

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

     Ripley, B. D. (1987) _Stochastic Simulation_. Wiley.

_S_e_e _A_l_s_o:

     Package 'sampling' for other methods of weighted sampling without
     replacement.

_E_x_a_m_p_l_e_s:

     x <- 1:12
     # a random permutation
     sample(x)
     # bootstrap sampling -- only if length(x) > 1 !
     sample(x,replace=TRUE)

     # 100 Bernoulli trials
     sample(c(0,1), 100, replace = TRUE)

     ## More careful bootstrapping --  Consider this when using sample()
     ## programmatically (i.e., in your function or simulation)!

     # sample()'s surprise -- example
     x <- 1:10
         sample(x[x >  8]) # length 2
         sample(x[x >  9]) # oops -- length 10!
     try(sample(x[x > 10]))# error!

     ## This is safer, but only for sampling without replacement
     resample <- function(x, size, ...)
       if(length(x) <= 1) { if(!missing(size) && size == 0) x[FALSE] else x
       } else sample(x, size, ...)

     resample(x[x >  8])# length 2
     resample(x[x >  9])# length 1
     resample(x[x > 10])# length 0