**[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
__r__**eps(***#***)** perform *#* random permutations; default is
**reps(100)**
__le__**ft**|__ri__**ght** compute one-sided p-values; default is two-sided

Options
__str__**ata(***varlist***)** permute within strata
__sa__**ving(***filename***, ...)** save results to *filename*; save statistics in
double precision; save results to *filename*
every *#* replications

Reporting
__l__**evel(***#***)** set confidence level; default is **level(95)**
__noh__**eader** suppress table header
__nol__**egend** suppress table legend
__v__**erbose** display full table legend
**nodrop** do not drop observations
**nodots** suppress replication dots
**dots(***#***)** display dots every *#* replications
__noi__**sily** display any output from *command*
__tr__**ace** trace *command*
__ti__**tle(***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
-------------------------------------------------------------------------
__le__**ft**|__ri__**ght** compute one-sided p-values; default is two-sided
__l__**evel(***#***)** set confidence level; default is **level(95)**
__noh__**eader** suppress table header
__nol__**egend** suppress table legend
__v__**erbose** display full table legend
__ti__**tle(***text***)** use *text* as title for 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 collected from 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; that is, 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 the
**nolegend** option.

**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.

**dots(***#***)** displays dots every *#* replications. **dots(0)** is a synonym for
**nodots**.

**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
permutation 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)**

---------------------------------------------------------------------------
Setup
**. webuse lbw**

Use logistic regression to test for an association between smoking and
low birthweight
**. permute smoke x2=e(chi2), reps(10000) nodots: logit low smoke**

---------------------------------------------------------------------------

__Stored results__

**permute** stores 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(rngstate)** random-number state used
**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