*! version 0.91
help swpermute ({})

Title

swpermute -- Monte Carlo permutation tests for stepped wedge
trial designs

Syntax

swpermute
exp
,
cluster(varname)
period(varname)
intervention(varname)
[options]
: command

Main
* cluster(varname) variable defining the clusters

* period(varname) variable defining the periods of the
trial

* intervention(varname) variable defining the intervention
conditions. This
must be a binary variable

reps(#) perform # random permutations; default is reps(1000)

left|right compute one-sided p-values; default is two-sided

Options
strata(varlist) permute within strata

null(numlist) null hypothesis values to be tested. Only available
for continuous outcomes and cluster-period level outcomes. The default is 0

outcome(varname) variable defining the outcome in the analysis.
This must be specified for null values other than 0

saving(filename, ...) save
estimated effects of each permutation to filename; save estimates in double
precision; save estimates to filename every # permutations

Within-period
withinperiod run command within each level of the variable
defined in period() and combine using a weighted average

weightperiod:(swpermute##weightperiod:weightperiod) the weight
given to each period if a within-period analysis has been selected. The default
is weightperiod(N) which weights periods by the number of clusters in each
intervention condition

Reporting
nodots suppress permutation dots

level(#) set confidence level; default is level(95)

Advanced
seed(#) set random-number seed to #

*these options are required.

weightperiod

none equal weight is given to all periods

N periods are weighted by the number of clusters in the control and intervention conditions in that period: (1/s_0j + 1/s_1j)^-1 where s_0j is the number of clusters in the control condition in period j and s_1j is the number in the intervention condition in period j. This is the default

variance exp periods are weighted by the inverse of the statistic
exp calculated by the command. Usually exp will be a variance

Menu

This command can be executed from a dialog box. To add swpermute to your menu
type these commands:

. window menu append submenu "stUser" "&Cluster RCTs"

. window menu append item "Cluster RCTs" "Permute for stepped wedge trials (&swpermute)" "db swpermute"

. window menu refresh

To permanently install this command menu, place the above code into your profile.do file.
Further information on how to do this and how to find your profile.do file see
profilew, profilem, or profileu for window, mac, or unix respectively.

Description

swpermute estimates p-values for permutation tests using data from stepped-wedge
cluster-randomised trial designs. The command can also be used for parallel cluster-randomised
trial designs.

In a stepped-wedge trial, clusters are assigned to sequences consisting of a number
of periods receiving a control condition, followed by the remaining periods receiving the
intervention condition. The variable defining the clusters is given in cluster(),
the variable defining the periods is given in period(), and the variable defining
the intervention is given in intervention().

In this context, a permutation means assigning clusters to a different sequence, selected from the sequences observed in the trial.

The command uses Monte-Carlo permutations meaning that a number of permutations
are selected at random, rather than using all possible arrangements of clusters
to sequences. For more information about permutation tests, see the Stata help
file for permute.

The syntax for swpermute is similar to permute. Typing

swpermute exp,
cluster(varname)
period(varname)
intervention(varname):
command

randomly permutes clusters between the sequences that are present in the data.
A specified number of permutations are completed as defined by reps(#) (the
default is 500). For each permutation, command is executed and the value given
by the expression exp is collected. These values are compared to the value of
exp given by the original data to calculate a p-value as

p = c/n

where n is the number of permutations and c is the number of permutations that
resulted in exp the same as or more extreme than the value of exp given
by the original data.

command defines the statistical command to be executed. Most Stata commands
and user-written programs can be used with swpermute.

exp specifies the expression to be collected from the execution of
command (see return and the command help file for more details).
Unlike the permute command, you should not give this expression a name and
do not need to enclose the expression in brackets.

If withinperiod is specified, the command is run within each level of
the variable defined in period(). This results in a value of exp for
each level. A weighted average of these values is calculated using the weights
specified in weightperiod(). If variance is specified you must provide
an expression in the weightperiod() option giving the variance expression
to extract from command.

For continuous and cluster-period level outcomes, null() may be specified to test
null values other than 0. This is useful to construct of confidence intervals. For
each value given in null(), the value is subtracted from outcomes given in the variable defined in outcome() if the variable defined in intervention() is equal to 1. The permutations then proceeds as before. The seed is reset for each null value to ensure the same set of permutations are selected so that there is consistency between the p-value and confidence interval.

Options

Main

cluster(varname) specifies a numeric variable the gives the clusters. All
observations within each cluster() must have the same value of intervention()
in each period(). Observations with cluster() missing will be excluded from the analysis.

period(varname) specifies a numeric variable the gives the periods. Observations with period() missing will be excluded from the analysis.

intervention(varname) specifies a binary variable that gives the intervention
assignment, where 0 and 1 represent the control and intervention conditions, respectively. All observations within each value of cluster() must have the same value of intervention() in each period(). If all values of intervention() are missing for a cluster() in a period(), this is assumed to be part of the sequence, for
example as a washout period, and the missing value will be permuted. Otherwise, observations with intervention() missing will be excluded from the analysis.

reps(#) specifies the number of permutations to perform. The default is 500.

left or right requests that one-sided p-values be computed.
If left is specified, the p-value reported is the proportion of permutations
where exp gives a value less than the value given by the original data. If
right is specified, the p-value reported is the proportion of permutations
where exp gives a value greater than the value given by the original data. The default, when neither left nor right is specified, is to calculate two-sided p-values, that is the proportion of permutations where exp gives a value further from 0 than the value given by the original data.

Options

strata(varlist) specifies that the permutations be performed within each
stratum defined by the values of varlist. This option should be used if randomisation of clusters was stratified.

saving(filename[, suboptions]) creates a Stata file (.dta file) consisting
of a row for each permutation run for each value in null(). The dataset will contain
three variables; one containing the null value, one containing the value of exp
in the observed data for that null value, and one for values of exp for each
permutation.

See prefix_saving_option for details about suboptions.

null(numlist) specifies a list of null hypothesis values. For each value
specified, a set of permutations will be run and a p-value will be calculated after
subtracting the null value from outcomes assigned to intervention()==1. For each value in numlist the random seed is reset to the value specified in seed() or the value when the command was called. This option is only available for continuous outcomes (including cluster-period level outcomes). The null values are assumed to be on the same scale as the outcome (e.g. risks differences if the outcomes are cluster-period risks). For cluster-period level outcomes, ratios such as
risk ratios, or odds ratios should be given on the log scale. The default is
null(0). When values other than the default are specified the option
outcome(varname) is required.

outcome(varname) specifies the outcome variable from which the null value
will be subtracted. The outcome variable is assumed to be on the same scale as
the null values. Required if option null() is given with a value other
than 0.

Within period analysis

withinperiod requests command be run within each level of period().
A weighted mean of the exp values from each level of period() is then
calculated using the weights given in weightperiod(). This option allows what
is known as a "vertical analysis" in stepped-wedge trial literature.

weightperiod(swpermute##weightperiod:weightperiod) specifies which weights
to use when calculating the weighted mean of the exp values from a within-period
analysis. The default is weightperiod(N) which weights periods by the
number of clusters in each condition during that period. Other options are none,
or variance.

Reporting

nodots suppresses display of the permutation dots. By default, one
dot character is displayed for each successful permutation. A red 'x'
is displayed if command returns an error or if the statistic in
exp is missing for a permutation.

level(#) specifies the confidence level, as a percentage, for confidence
intervals. The default is level(95).

Advanced

seed(#) sets the random-number seed. Specifying this option is
equivalent to typing :

. set seed #

prior to calling swpermute.

Examples

Setup

. webuse tbconfirmed, clear

Run permutation test on the results of a mixed-effect model

. swpermute _b[arm], intervention(arm) period(study_month) cluster(lab) reps(100): melogit confirmed arm i.study_month || lab :

Setup

. webuse tbconfirmed, clear

Calculate the risk of the outcome in each cluster-period

. collapse (sum) cases=confirmed (count) N=confirmed, by(lab study_month arm)

. gen risk = cases / N

Run a within period analysis on cluster-period level outcomes to calculate a risk difference

. swpermute r(mu_2) - r(mu_1), intervention(arm) period(study_month) cluster(lab) withinperiod weightperiod(variance r(se)^2) reps(100): ttest risk, by(arm)

Test different null values to generate a confidence interval

. swpermute r(mu_2) - r(mu_1), outcome(risk) null(0.05 0.15) intervention(arm) period(study_month) cluster(lab) withinperiod weightperiod(variance r(se)^2) reps(100): ttest risk, by(arm)

Stored results

swpermute stores the following in r():

Scalars

r(N_cluster) number of clusters being permuted

r(N_strata) number of strata if strata option is specified

r(obs_value) value of exp observed in the original data

r(N_reps) number of permutations

Matrices

r(design) a matrix of 0 and 1 values showing the design of the SWT

r(obs_period) value of exp observed in the original data within each value of period if a within period analysis is specified

r(p) p-values with their confidence intervals for each null value

References

Thompson JA & Davey C, Fielding K, Hargreaves JR, Hayes RJ. Robust analysis of stepped wedge trials using cluster-level summaries within periods. Statistics in Medicine, 2018(37) 2487-2500. doi: 10.1002/sim.7668

Ji X, Fink G, Robyn PJ, Small SS. Randomization inference for stepped-wedge cluster-randomised trials: An application to community-based health insurance. Annals of Applied Statistics. 2011(11) 1-20

Wang, R., and De Gruttola, V. The use of permutation tests for the analysis of parallel and stepped-wedge cluster-randomized trials. Statistics in Medicine, 2017(36) 2831–2843. doi: 10.1002/sim.7329

Authors

Jennifer Thompson
London School of Hygiene and Tropical Medicine
London, UK
jennifer.thompson@lshtm.ac.uk