help gsample


gsample -- Sampling


gsample [#|varname] [if] [in] [weight] [, options]

options Description ------------------------------------------------------------------------- percent sample size is in percent wor sample without replacement strata(varlist) variables identifying strata cluster(varlist) variables identifying resampling clusters idcluster(newvar) create new cluster ID variable keep keep observations that do not meet if and in generate(newvar) store sampling frequencies in newvar replace overwrite existing variables ------------------------------------------------------------------------- aweights are allowed; see weight.


gsample draws a random sample from the data in memory. Simple random sampling (SRS) is supported, as well as unequal probability sampling (UPS), of which sampling with probabilities proportional to size (PPS) is a special case. Both methods, SRS and UPS/PPS, provide sampling with replacement and sampling without replacement. Furthermore, stratified sampling and cluster sampling is supported.

# specifies the size of the sample. The default for gsample is to replace the data in memory with the sampled observations in random order. Alternatively, gsample may store a new variable containing the sampling frequencies of the observations (see the generate(newvar) option). In the case of sampling without replacement (see the wor option), the sample size must be less than or equal to the number of sampling units in the data. Sampling units are either single observations or clusters identified by the cluster() option. If # is not specified or if #==., the sample size is equal to the observed number of units in the data. For stratified sampling, # units will be selected from each stratum identified by the strata() option. Alternatively, specify varname instead of #, where varname is a variable containing for each stratum a specific sample size. varname is assumed to be constant within strata.

Specifying aweights causes unequal probability sampling (UPS/PPS) to be performed. The sampling probabilities of the observations will be proportional to the specified weights in this case.

gsample is implemented as a wrapper for the mm_sample() function from the moremata package. See help for mm_sample() for methodical details and references. Note that for unequal probability sampling without replacement many different algorithms have been proposed in the literature and there may be better solutions than the method implemented here. In addition, UPS without replacement may fail if the distribution of weights is very uneven (see help for mm_sample() for an explanation of this problem).

If you are serious about sampling, you should first set the random number seed; see help generate.


gsample requires moremata. Type

. ssc describe moremata


percent indicates that # (or varname) specifies the percentage of observations to be sampled. For example,

. gsample 50, percent

draws a 50% sample. For stratified sampling, a #-percent sample is drawn from each stratum, thus maintaining the proportion of each stratum.

wor causes the observations to be sampled without replacement (each observation may only be drawn once). The default is to sample with replacement (observations may be drawn multiple times).

strata(varlist) specifies the variables identifying strata. If strata() is specified, samples are selected within each stratum. The strata variables may be numeric or string.

cluster(varlist) specifies the variables identifying sampling clusters. If cluster() is specified, the sample drawn is a sample of clusters. The cluster variables may be numeric or string.

idcluster(newvar) creates a new variable containing a unique identifier for each sampled cluster. This is particularly useful when sampling with replacement.

keep causes observations that do not meet the optional if and in criteria (and observations that are missing on any of the input variables or have zero weight) to be kept (sampled at 100%). The default is to drop these observations. Alternatively, if generate() is specified, keep changes the stored sampling frequencies of these observations from zero to one.

generate(newvar) causes a variable containing sampling frequencies to be added to the data instead of replacing the data in memory with the sampled observations. Note that the original sort order of the data will be preserved if generate() is specified. newvar will either be zero or one for observations that do not meet the optional if and in criteria (or for observations that are missing on any of the input variables or have zero weight) depending on whether keep is specified or not.

replace permits gsample to overwrite existing variables.


For example,

. gsample

draws a bootstrap sample of size _N (simple random sample with replacement, SRSWR). The data in memory will be replaced by the sampled observations. Alternatively

. gsample, wor

draws a simple random sample without replacement (SRSWOR).


. gsample [aw=size]

draws a unequal probability sample with sampling probabilities proportional to size.


Ben Jann, ETH Zurich,

You may cite this software as follows:

Jann, B. (2006). gsample: Stata module to draw a random sample. Available from

Also see

Online: mm_sample(), sample, bsample, generate, moremata