{smcl}
{* 18aug2004}{...}
{hline}
help for {hi:bootstrap}, {hi:bs}, {hi:bsample}, {hi:bstat}{right:manual:  {hi:[R] bootstrap}     }
{right:dialogs:  {dialog bootstrap}  {dialog bsample}}
{right:{dialog bstatvar:bstat varlist}     }
{right:{dialog bstatusing:bstat using}       }
{hline}

{title:Bootstrap sampling and estimation}

{p 8 18 2}
{cmd:bootstrap}
	{cmd:"}{it:command}{cmd:"}
	{it:exp_list}
	[{cmd:,}
	{cmdab:r:eps:(}{it:#}{cmd:)}
	{cmdab:si:ze:(}{it:#}{cmd:)}
	{cmdab:d:ots}
	{cmdab:sa:ving:(}{it:filename}{cmd:)}
	{cmdab:doub:le}
	{cmdab:ev:ery:(}{it:#}{cmd:)}
	{cmd:replace}
	{cmd:noesample}
	{cmdab:noi:sily}
	{cmdab:tr:ace}
	{cmd:nowarn}
	{it:bsample_options}
	{it:bstat_options}
	]

{p 8 18 2}
{cmd:bs}{space 7}
	{cmd:"}{it:command}{cmd:"}
	{it:exp_list}
	[{cmd:,}
	{cmdab:r:eps:(}{it:#}{cmd:)}
	{cmdab:si:ze:(}{it:#}{cmd:)}
	{cmdab:d:ots}
	{cmdab:sa:ving:(}{it:filename}{cmd:)}
	{cmdab:doub:le}
	{cmdab:ev:ery:(}{it:#}{cmd:)}
	{cmd:replace}
	{cmd:noesample}
	{cmdab:noi:sily}
	{cmdab:tr:ace}
	{cmd:nowarn}
	{it:bsample_options}
	{it:bstat_options}
	]

{p 8 18 2}
{cmd:bstat}{space 4}
	[{it:varlist}]
	[{cmd:using} {it:filename}]
	[{cmd:,}
	{cmd:accel(}{it:vector}{cmd:)}
	{cmdab:s:tat:(}{it:vector}{cmd:)}
	{cmd:n(}{it:#}{cmd:)}
	{it:bstat_options}
	]

{p 8 18 2}
{cmd:bsample}{space 2}
	[{it:exp}]
	[{cmd:if} {it:exp}]
	[{cmd:in} {it:range}]
	[{cmd:,}
	{cmdab:w:eight:(}{it:varname}{cmd:)}
	{it:bsample_options}
	]


{p 4 8 2}
where {it:bsample_options} are

{p 8 8 2}
	{cmdab:cl:uster:(}{it:varlist}{cmd:)}
	{cmdab:id:cluster:(}{it:newvarname}{cmd:)}
	{cmdab:str:ata:(}{it:varlist}{cmd:)}{p_end}

{p 4 8 2}
and {it:bstat_options} are

{p 8 8 2}
	{cmd:bca}
	{cmdab:l:evel:(}{it:#}{cmd:)}
	{cmdab:sep:arate}
	{cmdab:ti:tle:(}{it:text}{cmd:)}
	{cmd:no}{cmd:bc}
	{cmdab:non:ormal}
	{cmdab:nop:ercentile}
	{cmd:notable}


{title:Description}

{p 4 4 2}
{cmd:bootstrap} runs {it:command} bootstrapping the statistics in
{it:exp_list} by resampling from the data in memory.  This is commonly
referred to as the nonparametric bootstrap method.  {cmd:bs} is equivalent
to {cmd:bootstrap}.

{p 4 8 2}
{it:command} defines the statistical command to be executed.  {it:command}
must be bound in double quotes.  Compound double quotes ({cmd:`"} and
{cmd:"'}) are needed if the command itself contains double quotes.  Most
Stata commands and user-written programs can be used with {cmd:bootstrap};
however, if the {cmd:bca} option is supplied, {it:command} must also work with
{help jknife}.

{p 4 8 2}
{it:exp_list} specifies the statistics to be collected from the execution
of {it:command}.  The expressions in {it:exp_list} follow the grammar given
in help {help exp_list}.

{p 4 4 2}
{cmd:bstat} displays bootstrap estimates of standard error and bias, and
calculates confidence intervals using four different methods:  normal
approximation, percentile, bias corrected, and optionally bias corrected
and accelerated.  {cmd:bootstrap} automatically runs {cmd:bstat} after
completing all the bootstrap replications.  If the
{cmd:saving(}{it:filename}{cmd:)} option is supplied to {cmd:bootstrap}, then
{cmd:bstat} can be run on the data in {it:filename} to review the bootstrap
results.  If given the {help using} modifier, {cmd:bstat} will use the data
in {it:filename} to compute the bootstrap statistics while preserving the
data currently in memory; the data in memory is used by default.

{p 4 4 2}
{cmd:bootstrap} and {cmd:bs} can also be used to call {cmd:bstat} to replay
results.

{p 4 4 2}
{cmd:bsample} is a low-level utility for do-it-yourselfers who prefer not
to use {cmd:bootstrap}.  {cmd:bsample} draws a sample with replacement from
the existing data.  By default this bootstrap sample replaces the data in
memory; however, the {cmd:weight()} option provides a way to recover
frequency weights instead.  {it:exp} specifies the size of the sample and
must be less than or equal to {cmd:_N} (within {cmd:strata()}).  If
{it:exp} is not specified, a sample size of {cmd:_N} is drawn (or size
{it:n_c} when the {cmd:cluster()} option is specified where {it:n_c} is the
number of clusters within each stratum).

{p 4 4 2}
Since bootstrapping is a random process, persons interested in
reproducibility of results should set the random-number seed by typing
{cmd:set seed} {it:#} before running {cmd:bootstrap}; see help {help generate}.


{title:Options}

{p 4 8 2}
{cmd:reps(}{it:#}{cmd:)} specifies the number of bootstrap replications
to be performed.  The default is {cmd:50}.

{p 4 8 2}
{cmd:size(}{it:#}{cmd:)} specifies the size of the samples to be drawn.
The default is {cmd:_N}, meaning to draw samples of the same size as the
data.  If {cmd:cluster()} is specified, the default is the number of
clusters in the original dataset.  Unless all the clusters contain the same
number of observations, resulting sample sizes will differ from replication
to replication.  If {cmd:size(}{it:#}{cmd:)} is specified, {it:#} must be
less than or equal to the number of observations or, if clustered, the
number of clusters (within {cmd:strata()}).

{p 4 8 2}
{cmd:dots} requests a dot be placed on the screen at the beginning
of each replication, thus providing entertainment when a large number of
{cmd:reps()} are requested.

{p 4 8 2}
{cmd:saving(}{it:filename}{cmd:)} creates a Stata data file ({cmd:.dta}
file) containing the bootstrap distribution for each user-specified statistic.

{p 4 8 2}
{cmd:double} specifies that the bootstrap results for each replication
are to be stored as {cmd:double}s, meaning 8-byte reals.  By default, they are
stored as {cmd:float}s, meaning 4-byte reals.  See help {help datatypes}.

{p 4 8 2}
{cmd:every(}{it:#}{cmd:)} specifies that results are to be written to
disk every {it:#}th replication.  {cmd:every()} should only be specified in
conjunction with {cmd:saving()} when performing bootstraps that take a very
long time.  This will allow recovery of partial results should your computer
crash; see help {help postfile}.

{p 4 8 2}
{cmd:replace} indicates that the file specified by {cmd:saving()} may
be overwritten.

{phang}
{opt noesample} prevents observations outside {cmd:e(sample)} 
from being dropped before the data is resampled.  This option is mostly useful
when {it:command} is a user written program that uses one or more estimation
commands that identifies the estimation sample in {cmd:e(sample)}, but
{it:command} needs all of the data to run successfully.

{p 4 8 2}
{cmd:noisily} requests that any output from {it:command} be displayed.

{p 4 8 2}
{cmd:trace} causes a trace of the execution of {it:command} to be displayed.

{p 4 8 2}
{cmd:nowarn} suppresses the printing of a warning message when
{it:command} is not an {cmd:eclass} program.

{p 4 8 2}
{cmd:accel(}{it:vector}{cmd:)} allows the user to specify the acceleration of
each statistic in {it:varlist}.  This value is used to construct bias
corrected and accelerated (BCa) confidence intervals.

{p 4 8 2}
{cmd:stat(}{it:vector}{cmd:)} allows the user to specify the observed value
of each statistic in {it:varlist} (i.e., the value of the statistic using
the original dataset).

{p 4 8 2}
{cmd:n(}{it:#}{cmd:)} ({cmd:bstat} only) specifies the number of
observations from which bootstrap samples were taken.  This option only
affects the output header of {cmd:bstat}.

{p 4 8 2}
{cmd:weight(}{it:varname}{cmd:)} ({cmd:bsample} only) specifies an
existing variable to place the bootstrap replicate weights.  {it:varname}
can then be used as an {cmd:fweight} in any Stata command that accepts
{cmd:fweights}.  This can speed up resampling for commands like
{cmd:regress} and {cmd:summarize}.

{p 4 8 2}
{cmd:cluster(}{it:varlist}{cmd:)} specifies the variable(s)
identifying resampling clusters.  If specified, the sample drawn during
each replication is a bootstrap sample of clusters.

{p 4 8 2}
{cmd:idcluster(}{it:newvarname}{cmd:)} creates a new variable
containing a unique identifier for each resampled cluster.

{p 4 8 2}
{cmd:strata(}{it:varlist}{cmd:)} specifies the variable(s) identifying
strata.  If specified, bootstrap samples are selected within each stratum.

{p 4 8 2}
{cmd:bca} requests that {cmd:bootstrap} estimate the acceleration of each
statistic in {it:exp_list}.  This estimate is used to construct BCa
confidence intervals.

{p 4 8 2}
{cmd:level(}{it:#}{cmd:)} specifies the confidence level, in percent,
for confidence intervals.  The default is {cmd:level(95)} or as set by
{cmd:set level}; see help {help level}.

{p 4 8 2}
{cmd:separate} inserts a separator line between the {it:exp_list}
statistics in the table generated by {cmd:bstat}.

{p 4 8 2}
{cmd:title(}{it:text}{cmd:)} specifies a title to be displayed above the
table of bootstrap results; the default title is "Bootstrap statistics".

{p 4 8 2}
Confidence interval options for {cmd:bstat}:

{p 8 12 2}
{cmd:bca} requests displaying the BCa confidence interval(s).

{p 8 12 2}
{cmd:nobc} prevents displaying the bias-corrected confidence interval(s).

{p 8 12 2}
{cmd:nonormal} prevents displaying the confidence interval(s) based on the
normal approximation.

{p 8 12 2}
{cmd:nopercentile} prevents displaying the percentile confidence interval(s).

{p 8 12 2}
{cmd:notable} prevents displaying all confidence intervals.


{title:Examples}

{p 4 8 2}{cmd:. bootstrap "logit for mpg weight" _b _se, reps(100) saving(bsout) replace bca}

{p 4 8 2}{cmd:. bstat b_mpg b_weight using bsout}

{p 4 8 2}{cmd:. bstat b_mpg b_weight using bsout, accel((.07,.09)) }

{p 4 8 2}{cmd:. bootstrap b_mpg b_weight using bsout, accel((.07,.09)) }


{title:Also see}

    Manual:  {hi:[R] bootstrap}

{p 4 13 2}Online:  help for {help jknife},
{help permute},
{help postfile},
{help sample},
{help simulate},
{help statsby}
