.-
help for ^resample^                                [STB-37: ip18; STB-52: ip18.1]
.-

Random re-sampling of existing variables
----------------------------------------

   ^resample^ varlist [^if^ exp] [^in^ range] [^, n^ames^(^namelist^)^ ^r^etain]

   ^resample ?^


Description
-----------

^resample^ generates random samples with replacement from each variable in var-
list, by choosing randomly among from its values in the observations where the
[if] [in] expression is true. By default, each resample is stored in a variable
with the same name as the parent variable, but with an underscore added as a
suffix. (If necessary, the case of the name is changed to distinguish the orig-
inal variable and its random resample.)  If a variable with the same name as
the resample already exists, it is replaced; otherwise, a new variable is cre-
ated.  This naming convention precludes the use of abbreviated variable names.

Resampling is performed in case-wise fashion, so that if varlist contains more
than one variable, the resampled variables contain values from the same random
subset of observations.  Missing values are assigned to the resample when the
[if] [in] expression evaluates to false, unless the ^retain^ option is given. The
sorted order of the data is preserved in any case.

Unlike @bsample@, resample draws samples with replacement only from selected var-
iables and/or cases.  The re-sampled values are inserted in the data set as new
variables, rather than replacing the original variables. Consequently, the com-
mand `resample _all' should be avoided; instead use `resample ^A^-^Z^' where ^A^ and
^Z^ are the first and last original variables in the current ordering.

If you are serious about drawing random samples, you must first set the random
number seed; see help @generate@.

The second syntax above provides a brief reminder of the first.


Options
-------

^names(^namelist^)^ provides a list of names for the variables created by resampl-
    ing the varlist variables.  Any name not so supplied is created using the
    rule described above.

^retain^ restricts the overwriting of resampled variables to cases specified by
    the [if] [in] expression.  By default, all cases are overwritten.


Examples
--------

 . ^resample xvar^
   (Fills xvar_ with a random sample of the values of xvar)

 . ^resample xvar in 21/l^
   (Fills xvar_[21] .. xvar_[_N] with a random sample drawn from xvar[21] ..
   xvar[_N]; xvar_[1] .. xvar_[20] are assigned missing values)

 . ^resample xvar in 1/20, retain^
   (Fills xvar_[1] .. xvar_[20] with a new random sample drawn from xvar[1] ..
   xvar[20]; xvar_[21] .. xvar_[_N] are unchanged by this command)

 . ^resample abc abcdefg_, n(ABC)^
   (Resample the variables abc and abcdefg_, storing the resample of abc in ABC
   and the resample of abcdefg_ in ABCDEFG_)

 . ^resample abc abcdefg_, n(ABC)^
   (Replace the contents of ABC and ABCDEFG_ with a fresh resample)

 . ^resample time1 if height != .^
 . ^resample time2 if height != .^
   (Fill time1_ and time2_ with values of time1 and time2 obtained by choosing
   independent random samples of the subset of observations where height is not
   missing; time1_ and time2_ are missing wherever height is)

 . ^resample time1 time2 if height != .^
   (Fill time1_ and time2_ with values of time1 and time2 obtained by choosing
   a single bivariate random sample of observations where height is not miss-
   ing; time1_ and time2_ are missing wherever height is)

 . ^set obs 1000^             /* (assume that, previously, _N = 25) */
 . ^resample x1 x2 in 1/25^
   (Fill x1_ and x2_ with a bivariate random sample of values of x1 and x2 from
   observations 1 - 25, thus avoiding the missing values of x1 and x2 that were
   created when _N was increased to 1000)


Author
------
   John R. Gleason, Syracuse University, Syracuse NY, USA
   (loesljrg@@accucom.net)    [This is Version 1.1.3 (26Sep1999).]


Also see
--------

 Manual:  ^[R] bstrap^
On-line:  help for @bsample@, @bstrap@, @generate@