help permute dialog: permute
-------------------------------------------------------------------------------
Title
[R] permute -- Monte Carlo permutation tests
Syntax
Compute permutation test
permute permvar exp_list [, options] : command
Report saved results
permute [varlist] [using filename] [, display_options]
options description
-------------------------------------------------------------------------
Main
reps(#) perform # random permutations, default is
reps(100)
left|right compute one-sided p-values; default is two-sided
Options
strata(varlist) permute within strata
saving(filename, ...) save results to filename; save statistics in
double precision; save results to filename
every # replications
Reporting
level(#) set confidence level; default is level(95)
noheader suppress table header
nolegend suppress table legend
verbose display full table legend
nodrop do not drop observations
nodots suppress replication dots
noisily display any output from command
trace trace command
title(text) use text as title for permutation results
Advanced
eps(#) numerical tolerance; seldom used
nowarn do not warn when e(sample) is not set
force do not check for weights or svy commands; seldom
used
reject(exp) identify invalid results
seed(#) set random-number seed to #
-------------------------------------------------------------------------
weights are not allowed in command.
display_options description
-------------------------------------------------------------------------
left|right compute one-sided p-values; default is two-sided
level(#) set confidence level; default is level(95)
noheader suppress table header
nolegend suppress table legend
verbose display full table legend
title(text) use text as title for permutation results
eps(#) numerical tolerance; seldom used
-------------------------------------------------------------------------
Menu
Statistics > Resampling > Permutation tests
Description
permute estimates p-values for permutation tests on the basis of Monte
Carlo simulations. Typing
. permute permvar exp_list, reps(#): command
randomly permutes the values in permvar # times, each time executing
command and collecting the associated values from the expressions in
exp_list.
These p-value estimates can be one-sided: Pr(T* < T) or Pr(T* > T). The
default is two-sided: Pr(|T*| > |T|). Here T* denotes the value of the
statistic from a randomly permuted dataset, and T denotes the statistic,
as computed on the original data.
permvar identifies the variable whose observed values will be randomly
permuted.
command defines the statistical command to be executed. Most Stata
commands and user-written programs can be used with permute, as long as
they follow standard Stata syntax. The by prefix may not be part of
command.
exp_list specifies the statistics to be retrieved after the execution of
command.
permute may be used for replaying results, but this feature is
appropriate only when a dataset generated by permute is currently in
memory or is identified by the using option. The variables specified in
varlist in this context must be present in the respective dataset.
Options
+------+
----+ Main +-------------------------------------------------------------
reps(#) specifies the number of random permutations to perform. The
default is 100.
left or right requests that one-sided p-values be computed. If left is
specified, an estimate of Pr(T* < T) is produced, where T* is the
test statistic and T is its observed value. If right is specified,
an estimate of Pr(T* > T) is produced. By default, two-sided
p-values are computed; i.e., Pr(|T*| > |T|) is estimated.
+---------+
----+ Options +----------------------------------------------------------
strata(varlist) specifies that the permutations be performed within each
stratum defined by the values of varlist.
saving(filename [, suboptions]) creates a Stata data file (.dta file)
consisting of (for each statistic in exp_list) a variable containing
the replicates.
See prefix_saving_option for details about suboptions.
+-----------+
----+ Reporting +--------------------------------------------------------
level(#) specifies the confidence level, as a percentage, for confidence
intervals. The default is level(95) or as set by set level.
noheader suppresses display of the table header. This option implies
nolegend.
nolegend suppresses display of the table legend. The table legend
identifies the rows of the table with the expressions they represent.
verbose requests that the full table legend be displayed. By default,
coefficients and standard errors are not displayed.
nodrop prevents permute from dropping observations outside the if and in
qualifiers. nodrop will also cause permute to ignore the contents of
e(sample) if it exists as a result of running command. By default,
permute temporarily drops out-of-sample observations.
nodots suppresses display of the replication dots. By default, one dot
character is displayed for each successful replication. A red 'x' is
displayed if command returns an error or if one of the values in
exp_list is missing.
noisily requests that any output from command be displayed. This option
implies the nodots option.
trace causes a trace of the execution of command to be displayed. This
option implies the noisily option.
title(text) specifies a title to be displayed above the table of results;
the default title is Monte Carlo permutation results.
+----------+
----+ Advanced +---------------------------------------------------------
eps(#) specifies the numerical tolerance for testing |T*| > |T|, T* < T,
or T* > T. These are considered true if, respectively, |T*| > |T| -
#, T* < T + #, or T* > T - #. The default is 1e-7. You will not
have to specify eps() under normal circumstances.
nowarn suppresses the printing of a warning message when command does not
set e(sample).
force suppresses the restriction that command may not specify weights or
be a svy command. permute is not suited for weighted estimation, thus
permute should not be used with weights or svy. permute reports an
error when it encounters weights or svy in command if the force
option is not specified. This is a seldom used option, so use it
only if you know what you are doing!
reject(exp) identifies an expression that indicates when results should
be rejected. When exp is true, the resulting values are reset to
missing values.
seed(#) sets the random-number seed. Specifying this option is
equivalent to typing the following command prior to calling permute:
. set seed #
Examples
---------------------------------------------------------------------------
Setup
. webuse permutexmpl
Test whether a drug treatment increases the development of cells relative
to a placebo
. permute y sum=r(sum), saving(permdish) right nodrop nowarn:
summarize y if treatment
Replay results, requesting 80% confidence intervals
. permute using permdish, level(80)
---------------------------------------------------------------------------
Setup
. webuse permute2
Use the Wilcoxon rank-sum test to determine if two independent samples
are from populations with the same distribution
. permute y z=r(z), reps(10000) nowarn nodots: ranksum y, by(group)
---------------------------------------------------------------------------
Saved results
permute saves the following in r():
Scalars
r(N) sample size
r(N_reps) number of requested replications
r(level) confidence level
r(k_exp) number of standard expressions
r(k_eexp) number of _b/_se expressions
Macros
r(cmd) permute
r(command) command following colon
r(permvar) permutation variable
r(title) title in output
r(exp#) #th expression
r(left) left or empty
r(right) right or empty
r(seed) initial random-number seed
r(event) T <= T(obs), T >= T(obs), or |T| <= |T(obs)|
Matrices
r(b) observed statistics
r(c) count when r(event) is true
r(reps) number of nonmissing results
r(p) observed proportions
r(se) standard errors of observed proportions
r(ci) confidence intervals of observed proportions
Also see
Manual: [R] permute
Help: [R] bootstrap, [R] jackknife, [R] simulate
