swPwr: Power of Stepped Wedge Cluster Randomized Trial (SW CRT)
In swCRTdesign: Stepped Wedge Cluster Randomized Trial (SW CRT) Design
swPwr R Documentation
Power of Stepped Wedge Cluster Randomized Trial (SW CRT)
Description
swPwr returns (two-sided) power for the treatment effect(s) from an immediate treatment effect (IT) model or an exposure time indicator (ETI) model (Kenny et al, 2022) for the specified SW CRT design using a linear models weighted least squares (WLS) approach. A cross-sectional or closed cohort sampling scheme can be specified. The response/outcome of interest can be binomial or Gaussian distributed and is assumed to come from a model with random intercepts, random treatment effects, random cluster-specific time effects, and, in the case of closed cohort sampling, an individual random effect. Variance components can be specified using either random effect variances (tau, eta, rho, gamma, and zeta) or icc, cac, iac (see details). If a cross-sectional sampling, random intercepts only model is used (i.e., eta, rho, gamma and zeta are 0 and n is constant over clusters and time), then the power calculation is comparable to the closed-form formula of [Hussey and Hughes, 2007]. See [Voldal et al., 2020] for more guidance. This function is also available as a Shiny app at https://swcrtdesign.shinyapps.io/stepped_wedge_power_calculation/.
Usage
swPwr(design, distn, n, mu0, mu1, H=NULL, sigma, tau=0, eta=0, rho=0, gamma=0, zeta=0,
icc=0, cac=1, iac=0, ar=1, alpha=0.05, retDATA=FALSE, silent=FALSE)
Arguments
design
list: A stepped wedge design object, typically from swDsn, that includes at least the following components: swDsn, swDsn.unique.clusters, clusters, n.clusters, total.time, nTxLev, TxLev. Fractional treatment effects specified in swDsn are used in the calculation.
distn
character: Distribution assumed (gaussian or binomial). Currently, 'Binomial' implies Bernoulli.
n
integer (scalar, vector, or matrix): Number of observations: (scalar) for all clusters and all time points that are not NA in design$swDsn; (vector) for each cluster at all time points that are not NA in design$swDsn; and (matrix) for each cluster at each time point, where rows correspond to clusters and columns correspond to time. n can also be used to specify a design with transition periods (a transition period is a period, typically, immediately after treatment is introduced were no data are collected). Simply define n as a matrix with a sample size of 0 during every transition period. This is equivalent to putting an NA in the corresponding cluster-period in design$swDsn.
mu0
numeric (scalar): Mean outcome in the control group. See also documentation for H, below.
mu1
numeric (scalar or vector): Mean outcome in the treatment group(s). The treatment effect is the difference in means \theta = \mu_1 - \mu_0. If tx.effect.frac is specified in the call to swDsn then the assumed treatment effect at exposure time k is tx.effect.frac[k]*\theta. For an IT model with multiple treatment levels the length of mu1 should be equal to the number of treatment levels. See also documentation for H, below.
H
numeric (vector): If NULL, then swPwr assumes an immediate, constant treatment effect (IT) model. If not NULL, then an exposure time indicator (ETI) model is assumed and H should be a vector as long as the longest exposure time (in a classic stepped wedge design, the longest exposure time is the number of time periods minus one). H specifies the desired linear combination of exposure time treatment effects. For example, in a stepped wedge trial with 5 time periods and four exposure times, H = rep(.25,4) gives the average treatment effect over the four exposure times; H = c(0,0,.5,.5) ignores the first two periods after the intervention is introduced and averages the remaining periods. Typically, the sum of H is 1.0; if not, it is renormalized to sum to 1.0. H can only be specified when there is a single intervention type (i.e. design$swDsn includes only NA,0,1; see cautions in help for swDsn about including NA periods when H is used). mu0 and mu1 give expected values of the linear combination of exposure time treatment effects under the null and alternative hypotheses, respectively. Do not use an ETI model (non-null H) if you specified a fractional treatment effect in swDsn. See the details section for additional notes regarding incomplete designs.
sigma
numeric (scalar): Standard deviation when assuming Gaussian distribution (distn=gaussian). For binomial distribution \sigma^2 is automatically set to \bar{\mu}(1-\bar{\mu}) where \bar{\mu} = (\mu_1 + \mu_0)/2
tau
numeric (scalar): Standard deviation of random intercepts.
eta
numeric (scalar or list): Standard deviation of random treatment effect(s). If there is only one treatment group or if all the treatment groups have identical standard deviations for their random treatment effects, then eta can be specified as a scalar. If there are multiple treatment effects then eta can be specified as a list with two components: eta$eta is a vector of standard deviations of the random treatment effects (must be of length design$nTxLev); eta$corr is the correlation matrix of the random treatment effects (must be square and symmetrical with dimension design$nTxLev). If there are, say, two treatment groups then specifying eta = .005 is equivalent to specifying eta = list(eta=c(.005,.005),corr=matrix(1,2,2)).
rho
numeric (scalar or vector): Correlation between random intercepts and random treatment effects. If there are multiple treatment effects and eta has been specified as a list, then rho should have the same length as eta$eta.
gamma
numeric (scalar): Standard deviation of random time effects.
zeta
numeric (scalar): Standard deviation of individual effects for closed cohort sampling. Default is 0 which implies cross-sectional sampling. Values greater than 0 imply closed cohort sampling.
icc
numeric (scalar): Within-period intra-cluster correlation. Can be used with CAC instead of tau, eta, rho, and gamma; see details.
cac
numeric (scalar): Cluster auto-correlation. Can be used with ICC instead of tau, eta, rho, and gamma; see details.
iac
numeric (scalar): Individual auto-correlation for closed cohort sampling. Can be used with ICC and CAC instead of tau, eta, rho, gamma, and zeta; see details. Default is 0 which implies cross-sectional sampling. Values greater than 0 imply closed cohort sampling.
ar
numeric (scalar): Autocorrelation for exponential decay structure between periods within a cluster as described in Kasza et al (2019a;2019b). Available for cross-sectional sampling only (i.e. zeta=0 and iac=0). Default is ar=1 (no exponential decay). See details.
alpha
numeric (scalar): Two-sided statistical significance level.
retDATA
logical: if TRUE, all stored (input, intermediate, and output) values of swPwr are returned. Default value is FALSE.
silent
logical: if TRUE, hides most warning messages. Default value is FALSE.
Details
If ar=1, we assume the outcome variable of interest can be modeled using random effects
Y_{ijk} = \mu_0 + \beta_j + \theta X_{ij} + a_i + b_{ij} + r_i X_{ij} + c_{ik} + e_{ijk}
where
a_i \sim N(0, \tau^2)
b_{ij} \sim N(0, \gamma^2)
r_i \sim N(0, \eta^2)
Cov(a_i, r_i) = \rho \tau \eta
c_{ik} \sim N(0, \zeta^2)
e_{ijk} \sim N(0, \sigma^2)
for K observations in cluster i=1,\ldots,I and at time j=1,\ldots,J.
An exponentially decaying autocorrelation structure is specified by setting ar<1. The exponential decay only applies to the cluster and cluster*time random effects (Kasza et al., 2019) and is only available for cross-sectional sampling (i.e. zeta = iac = 0). Let Y_i represent the vector of cluster-period means for cluster i. Then the covariance of Y_i is
Var(Y_i) = G*R + T
where * denotes element by element multiplication and G, R and T are J x J matricies with
\begin{array}{rcl}
G & = & \tau^2 + diag(\gamma^2) + diag(\sigma^2 / K) \\
T_{ij} & = & \eta^2 \mbox{ \hspace{.2in} for i=j=J} \\
& = & \rho \tau \eta \mbox{ \hspace{.1in} for i=1...J-1, j=J and i=J, j=1...J-1} \\
& = & 0 \mbox{ \hspace{.24in} elsewhere} \\
R & = & \mbox{a toeplitz matrix with elements equal to } \code{ar}^m \mbox{ where m = 0...J-1 is the distance from the main diagonal}
\end{array}
The two-sided statistical power of treatment effect (\theta = \mu_1 - \mu_0) is
Pwr(\theta) = \Phi( Z - z_{1 - \alpha /2} ) + \Phi( -Z - z_{1 - \alpha /2} )
where
Z = \frac{ |\theta| }{ \sqrt{Var(\hat{\theta}_{WLS})} }
and \Phi is the cumulative distribution function of the standard normal N(0,1) distribution. If H is non-NULL then the \mu are assumed to be equal to H\delta where \delta is a vector of exposure time treatment effects.
The value of zeta defines the samling scheme. When zeta = 0, cross-sectional sampling is assumed; if zeta > 0 then closed cohort sampling is assumed.
When eta (and rho) are 0, instead of using tau, eta, rho, gamma and zeta, the icc, cac and iac can be used to define the variability of the random effects. In this model,
ICC = \frac{\tau^2+\gamma^2}{\tau^2+\gamma^2+\zeta^2+\sigma^2}
CAC = \frac{\tau^2}{\tau^2+\gamma^2}
IAC = \frac{\zeta^2}{\zeta^2+\sigma^2}
Choose one parameterization or the other, do not mix parameterizations.
Incomplete designs (e.g. staircase) can be specified by using the swDsn function with the swBlk argument to specify the incomplete design or by specifying a complete design with swDsn and using the n argument of swPwr to specify a matrix with 0 in the missing cluster-periods. Note that if the second approach is used then H must be either a scalar or a vector as long as the longest lag in the complete design. See the examples below.
Value
numeric (vector): swPwr returns the power of treatment effect(s), where the variance of treatment effect is computed by WLS.
numeric (list): swPwr returns all specified and computed items as objects of a list if retDATA = TRUE.
design
list: The stepped wedge design object as input.
distn
character: Distribution assumed (gaussian or binomial).
n
integer (scalar, vector, or matrix): Number of observations: (scalar) for all clusters and all time points; (vector) for each cluster at all time points; and (matrix) for each cluster at each time point, where rows correspond to clusters and columns correspond to time.
mu0
numeric (scalar): Mean outcome in the control group.
mu1
numeric (scalar): Mean outcome in intervention group(s). Note: treatment effect is difference in means \theta = \mu_1 - \mu_0.
H
numeric (vector): H specifies the desired linear combination of exposure time treatment effects for a ETI model-based estimate.
sigma
numeric (scalar): Standard deviation input. For binomial distribution, sigma = NA
tau
numeric (scalar): Standard deviation of random intercepts.
eta
numeric (scalar): Standard deviation of random treatment effects.
rho
numeric (scalar): Correlation between random intercepts and random treatment effects.
gamma
numeric (scalar): Standard deviation of random time effects.
zeta
numeric (scalar): Standard deviation of individual random effects for closed cohort sampling.
ar
numeric (scalar): Autocorrelation for exponential decay structure between periods within a cluster as described in Kasza et al (2019). Available for cross-sectional sampling only (i.e. zeta=0 and iac=0). See details.
alpha
numeric (scalar): Statistical significance level.
Xmat
numeric (matrix): Design matrix for this SW CRT design.
Wmat
numeric (matrix): Covariance matrix for this SW CRT design.
var
Variance-covariance matrix of treatment effect(s). Can be used to calculate power for constrasts other than control versus treatment
var.theta.WLS
numeric (scalar): Variance(s) of treatment effect(s) using weighted least squares (WLS) for this SW CRT design.
pwrWLS
numeric (scalar): Power of treatment effect (\theta) using weighted least squares (WLS) for this SW CRT design.
Author(s)
James P Hughes, Navneet R Hakhu, and Emily C Voldal
References
Hussey MA, Hughes JP. Design and analysis of stepped wedge cluster randomized trials. Contemporary Clinical Trials 2007;28:182-191.
Kasza J, Hemming K, Hooper R, Matthews JNS, Forbes AB. Impact of non-uniform correlation on sample size and power in multiple-period cluster randomized trials. Statistical Methods in Medical Research 2019a; 28: 703-716.
Kasza J, Taljaard M, Forbes AB. Information content of stepped-wedge designs when treatment effect heterogeneity and/or implementation periods are present. Statistics in Medicine 2019b; 38:4686-4701.
Kenny A, Voldal E, Xia F, Heagerty PJ, Hughes JP. Analysis of stepped wedge cluster randomized trials in the presence of a time-varying treatment effect. Statistics in Medicine, in press, 2022.
Voldal EC, Hakhu NR, Xia F, Heagerty PJ, Hughes JP. swCRTdesign: An R package for stepped wedge trial design and analysis. Computer Methods and Programs in Biomedicine 2020;196:105514.
Examples
# Example 1 (Random Intercepts Only, standard Stepped Wedge (SW) design)
swPwr.Ex1.RIO.std <- swPwr(swDsn(c(6,6,6,6)), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0, rho=0, gamma=0, alpha=0.05, retDATA=FALSE)
swPwr.Ex1.RIO.std
# Example 2 (Random Intercepts Only, extended SW design)
swPwr.Ex1.RIO.extend <- swPwr(swDsn(c(6,6,6,6), extra.trt.time=3), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0, rho=0, gamma=0,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.RIO.extend
# Example 3 (Independent Random Intercepts and Treatment effects, standard SW design)
swPwr.Ex1.IRIS <- swPwr(swDsn(c(6,6,6,6)), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0.0045, rho=0, gamma=0,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.IRIS
# Example 4 (Correlated Random Intercepts and Slopes, standard SW design)
swPwr.Ex1.CRIS <- swPwr(swDsn(c(6,6,6,6)), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0.0045, rho=0.4, gamma=0,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.CRIS
# Example 5 (Random time effect and correlated Random Intercepts and Slopes, standard SW design)
swPwr.Ex1.RTCRIS <- swPwr(swDsn(c(6,6,6,6)), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0.0045, rho=0.4, gamma = 0.1,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.RTCRIS
#Example 6 (Sample size varying by cluster)
sample.size.vector <- c(35219,53535,63785,456132,128670,96673,
51454,156667,127440,68615,56502,17719,
75931,58655,52874,75936)
swPwr.Ex1.vector <- swPwr(swDsn(c(4,3,5,4)), distn="gaussian",
n=sample.size.vector, mu0=2.66, mu1=2.15,
sigma=sqrt(1/2.66), tau=0.31, eta=0.2, rho=0, gamma = 0.15,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.vector
#Example 7 (Sample size varying by cluster and time)
sample.size.matrix <- matrix(c(26, 493, 64, 45, 48, 231, 117, 17, 49, 36, 19, 77, 67, 590,
261, 212, 67, 318, 132, 58, 44, 57, 59, 78, 115, 532, 176, 199, 73, 293, 129, 79, 51,
62, 109, 94, 174, 785, 133, 79, 120, 305, 224, 99, 83, 79, 122, 122, 94, 961, 90, 131, 166,
352, 316, 59, 54, 131, 101, 133),nrow=12,ncol=5, byrow=FALSE)
swPwr.Ex1.matrix <- swPwr(swDsn(c(3,3,3,3)), distn="binomial",
n=sample.size.matrix, mu0=0.08, mu1=0.06, tau=0.017, eta=0.006, rho=-0.5, gamma = 0,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.matrix
#Example 8 (Using ICC and CAC)
swPwr.Ex1.icccac <- swPwr(swDsn(c(6,6,6,6)), distn="gaussian",
n=120, mu0=0.05, mu1=0.035, sigma=0.1, icc=0.02, cac=0.125, alpha=0.05, retDATA=FALSE)
swPwr.Ex1.icccac
# Example 9 (Random time effect, closed cohort sampling)
sample_size = matrix(c(rep(c(20,20,20,20,20,20,20,20,20,20,20,20,20,20),5),
rep(c( 0,20,20,20,20,20,20,20,20,20,20,20,20,20),5),
rep(c( 0, 0,20,20,20,20,20,20,20,20,20,20,20,20),5),
rep(c( 0, 0, 0,20,20,20,20,20,20,20,20,20,20,20),5),
rep(c( 0, 0, 0, 0,20,20,20,20,20,20,20,20,20,20),5)),
25,14,byrow=TRUE)
swPwr.Ex9 <- swPwr(design=swDsn(c(5,5,5,5,5),extra.ctl.time=3,extra.trt.time=5),
distn="gaussian",n=sample_size,mu0=-0.4,mu1=0.4,
sigma=1.0,tau=sqrt(.1316),gamma=sqrt(.1974),eta=0,rho=0,zeta=sqrt(2.5),
silent=TRUE)
swPwr.Ex9
#Example 10 (Periods with no data, multiple treatment levels)
stdy <- swDsn(c(6,6,6,6),swBlk=matrix(c(0,1,2,2,2,2,
NA,0,1,2,2,2,
NA,NA,0,1,2,2,
NA,NA,NA,0,1,2),4,6,byrow=TRUE))
swPwr.Ex10 <-swPwr(stdy, distn="binomial",n=120, mu0=0.05, mu1=c(0.035,0.03),
tau=0.01, eta=0, rho=0, gamma=0, alpha=0.05, retDATA=TRUE, silent=TRUE)
swPwr.Ex10
# EXample 11 Compare to Kasza et al (2019) figure 4, lower left
swPwr(swDsn(c(1,1,1,1,1,1,1)),distn="gaussian",n=50,mu0=0,mu1=0.2,
tau=sqrt(.035),sigma=sqrt(1-.035),ar=.95,alpha=0.05,retDATA=FALSE,silent=TRUE)
# Example 12 Incomplete design
# These all give the same power
design12 = swDsn(c(4,4,4),swBlk=matrix(c(0,1,1,NA,NA,NA,0,1,1,NA,NA,NA,0,1,1),3,5,byrow=TRUE))
swPwr(design12,distn="gaussian",n=10,mu0=0,mu1=.5,H=c(.5,.5),sigma=1,icc=.01,silent=TRUE)
swPwr(design12,distn="gaussian",n=10,mu0=0,mu1=.5,H=1,sigma=1,icc=.01,silent=TRUE)
# H is automatically expanded and normalized
#
design12a = swDsn(c(4,4,4),extra.trt.time=1)
nmat12a=matrix(c(rep(c(10,10,10,0,0),4),rep(c(0,10,10,10,0),4),rep(c(0,0,10,10,10),4)),12,5,
byrow=TRUE)
swPwr(design12a,distn="gaussian",n=nmat12a,mu0=0,mu1=.5,H=1,sigma=1,icc=.01,silent=TRUE) #OK
swPwr(design12a,distn="gaussian",n=nmat12a,mu0=0,mu1=.5,H=c(1,1,0,0),sigma=1,icc=.01,
silent=TRUE) #OK
# The following generates an error; since design12a is a complete design with maximum lag 4,
# H must be a scalar or vector of length 4
# swPwr(design12a,distn="gaussian",n=nmat12a,mu0=0,mu1=.5,H=c(1,1),sigma=1,icc=.01,silent=TRUE)
swCRTdesign documentation built on Sept. 9, 2025, 5:55 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| swPwr | R Documentation |
Power of Stepped Wedge Cluster Randomized Trial (SW CRT)
Description
swPwr returns (two-sided) power for the treatment effect(s) from an immediate treatment effect (IT) model or an exposure time indicator (ETI) model (Kenny et al, 2022) for the specified SW CRT design using a linear models weighted least squares (WLS) approach. A cross-sectional or closed cohort sampling scheme can be specified. The response/outcome of interest can be binomial or Gaussian distributed and is assumed to come from a model with random intercepts, random treatment effects, random cluster-specific time effects, and, in the case of closed cohort sampling, an individual random effect. Variance components can be specified using either random effect variances (tau, eta, rho, gamma, and zeta) or icc, cac, iac (see details). If a cross-sectional sampling, random intercepts only model is used (i.e., eta, rho, gamma and zeta are 0 and n is constant over clusters and time), then the power calculation is comparable to the closed-form formula of [Hussey and Hughes, 2007]. See [Voldal et al., 2020] for more guidance. This function is also available as a Shiny app at https://swcrtdesign.shinyapps.io/stepped_wedge_power_calculation/.
Usage
swPwr(design, distn, n, mu0, mu1, H=NULL, sigma, tau=0, eta=0, rho=0, gamma=0, zeta=0,
icc=0, cac=1, iac=0, ar=1, alpha=0.05, retDATA=FALSE, silent=FALSE)
Arguments
design |
list: A stepped wedge design object, typically from |
distn |
character: Distribution assumed ( |
n |
integer (scalar, vector, or matrix): Number of observations: (scalar) for all clusters and all time points that are not NA in design$swDsn; (vector) for each cluster at all time points that are not NA in design$swDsn; and (matrix) for each cluster at each time point, where rows correspond to clusters and columns correspond to time. |
mu0 |
numeric (scalar): Mean outcome in the control group. See also documentation for H, below. |
mu1 |
numeric (scalar or vector): Mean outcome in the treatment group(s). The treatment effect is the difference in means |
H |
numeric (vector): If NULL, then swPwr assumes an immediate, constant treatment effect (IT) model. If not NULL, then an exposure time indicator (ETI) model is assumed and H should be a vector as long as the longest exposure time (in a classic stepped wedge design, the longest exposure time is the number of time periods minus one). H specifies the desired linear combination of exposure time treatment effects. For example, in a stepped wedge trial with 5 time periods and four exposure times, H = rep(.25,4) gives the average treatment effect over the four exposure times; H = c(0,0,.5,.5) ignores the first two periods after the intervention is introduced and averages the remaining periods. Typically, the sum of H is 1.0; if not, it is renormalized to sum to 1.0. H can only be specified when there is a single intervention type (i.e. design$swDsn includes only NA,0,1; see cautions in help for |
sigma |
numeric (scalar): Standard deviation when assuming Gaussian distribution ( |
tau |
numeric (scalar): Standard deviation of random intercepts. |
eta |
numeric (scalar or list): Standard deviation of random treatment effect(s). If there is only one treatment group or if all the treatment groups have identical standard deviations for their random treatment effects, then eta can be specified as a scalar. If there are multiple treatment effects then eta can be specified as a list with two components: eta$eta is a vector of standard deviations of the random treatment effects (must be of length design$nTxLev); eta$corr is the correlation matrix of the random treatment effects (must be square and symmetrical with dimension design$nTxLev). If there are, say, two treatment groups then specifying eta = .005 is equivalent to specifying eta = list(eta=c(.005,.005),corr=matrix(1,2,2)). |
rho |
numeric (scalar or vector): Correlation between random intercepts and random treatment effects. If there are multiple treatment effects and eta has been specified as a list, then rho should have the same length as eta$eta. |
gamma |
numeric (scalar): Standard deviation of random time effects. |
zeta |
numeric (scalar): Standard deviation of individual effects for closed cohort sampling. Default is 0 which implies cross-sectional sampling. Values greater than 0 imply closed cohort sampling. |
icc |
numeric (scalar): Within-period intra-cluster correlation. Can be used with CAC instead of tau, eta, rho, and gamma; see details. |
cac |
numeric (scalar): Cluster auto-correlation. Can be used with ICC instead of tau, eta, rho, and gamma; see details. |
iac |
numeric (scalar): Individual auto-correlation for closed cohort sampling. Can be used with ICC and CAC instead of tau, eta, rho, gamma, and zeta; see details. Default is 0 which implies cross-sectional sampling. Values greater than 0 imply closed cohort sampling. |
ar |
numeric (scalar): Autocorrelation for exponential decay structure between periods within a cluster as described in Kasza et al (2019a;2019b). Available for cross-sectional sampling only (i.e. zeta=0 and iac=0). Default is ar=1 (no exponential decay). See details. |
alpha |
numeric (scalar): Two-sided statistical significance level. |
retDATA |
logical: if TRUE, all stored (input, intermediate, and output) values of |
silent |
logical: if TRUE, hides most warning messages. Default value is |
Details
If ar=1, we assume the outcome variable of interest can be modeled using random effects
Y_{ijk} = \mu_0 + \beta_j + \theta X_{ij} + a_i + b_{ij} + r_i X_{ij} + c_{ik} + e_{ijk}
where
a_i \sim N(0, \tau^2)
b_{ij} \sim N(0, \gamma^2)
r_i \sim N(0, \eta^2)
Cov(a_i, r_i) = \rho \tau \eta
c_{ik} \sim N(0, \zeta^2)
e_{ijk} \sim N(0, \sigma^2)
for K observations in cluster i=1,\ldots,I and at time j=1,\ldots,J.
An exponentially decaying autocorrelation structure is specified by setting ar<1. The exponential decay only applies to the cluster and cluster*time random effects (Kasza et al., 2019) and is only available for cross-sectional sampling (i.e. zeta = iac = 0). Let Y_i represent the vector of cluster-period means for cluster i. Then the covariance of Y_i is
Var(Y_i) = G*R + T
where * denotes element by element multiplication and G, R and T are J x J matricies with
\begin{array}{rcl}
G & = & \tau^2 + diag(\gamma^2) + diag(\sigma^2 / K) \\
T_{ij} & = & \eta^2 \mbox{ \hspace{.2in} for i=j=J} \\
& = & \rho \tau \eta \mbox{ \hspace{.1in} for i=1...J-1, j=J and i=J, j=1...J-1} \\
& = & 0 \mbox{ \hspace{.24in} elsewhere} \\
R & = & \mbox{a toeplitz matrix with elements equal to } \code{ar}^m \mbox{ where m = 0...J-1 is the distance from the main diagonal}
\end{array}
The two-sided statistical power of treatment effect (\theta = \mu_1 - \mu_0) is
Pwr(\theta) = \Phi( Z - z_{1 - \alpha /2} ) + \Phi( -Z - z_{1 - \alpha /2} )
where
Z = \frac{ |\theta| }{ \sqrt{Var(\hat{\theta}_{WLS})} }
and \Phi is the cumulative distribution function of the standard normal N(0,1) distribution. If H is non-NULL then the \mu are assumed to be equal to H\delta where \delta is a vector of exposure time treatment effects.
The value of zeta defines the samling scheme. When zeta = 0, cross-sectional sampling is assumed; if zeta > 0 then closed cohort sampling is assumed.
When eta (and rho) are 0, instead of using tau, eta, rho, gamma and zeta, the icc, cac and iac can be used to define the variability of the random effects. In this model,
ICC = \frac{\tau^2+\gamma^2}{\tau^2+\gamma^2+\zeta^2+\sigma^2}
CAC = \frac{\tau^2}{\tau^2+\gamma^2}
IAC = \frac{\zeta^2}{\zeta^2+\sigma^2}
Choose one parameterization or the other, do not mix parameterizations.
Incomplete designs (e.g. staircase) can be specified by using the swDsn function with the swBlk argument to specify the incomplete design or by specifying a complete design with swDsn and using the n argument of swPwr to specify a matrix with 0 in the missing cluster-periods. Note that if the second approach is used then H must be either a scalar or a vector as long as the longest lag in the complete design. See the examples below.
Value
numeric (vector): swPwr returns the power of treatment effect(s), where the variance of treatment effect is computed by WLS.
numeric (list): swPwr returns all specified and computed items as objects of a list if retDATA = TRUE.
design |
list: The stepped wedge design object as input. |
distn |
character: Distribution assumed ( |
n |
integer (scalar, vector, or matrix): Number of observations: (scalar) for all clusters and all time points; (vector) for each cluster at all time points; and (matrix) for each cluster at each time point, where rows correspond to clusters and columns correspond to time. |
mu0 |
numeric (scalar): Mean outcome in the control group. |
mu1 |
numeric (scalar): Mean outcome in intervention group(s). Note: treatment effect is difference in means |
H |
numeric (vector): H specifies the desired linear combination of exposure time treatment effects for a ETI model-based estimate. |
sigma |
numeric (scalar): Standard deviation input. For binomial distribution, sigma = NA |
tau |
numeric (scalar): Standard deviation of random intercepts. |
eta |
numeric (scalar): Standard deviation of random treatment effects. |
rho |
numeric (scalar): Correlation between random intercepts and random treatment effects. |
gamma |
numeric (scalar): Standard deviation of random time effects. |
zeta |
numeric (scalar): Standard deviation of individual random effects for closed cohort sampling. |
ar |
numeric (scalar): Autocorrelation for exponential decay structure between periods within a cluster as described in Kasza et al (2019). Available for cross-sectional sampling only (i.e. zeta=0 and iac=0). See details. |
alpha |
numeric (scalar): Statistical significance level. |
Xmat |
numeric (matrix): Design matrix for this SW CRT design. |
Wmat |
numeric (matrix): Covariance matrix for this SW CRT design. |
var |
Variance-covariance matrix of treatment effect(s). Can be used to calculate power for constrasts other than control versus treatment |
var.theta.WLS |
numeric (scalar): Variance(s) of treatment effect(s) using weighted least squares (WLS) for this SW CRT design. |
pwrWLS |
numeric (scalar): Power of treatment effect ( |
Author(s)
James P Hughes, Navneet R Hakhu, and Emily C Voldal
References
Hussey MA, Hughes JP. Design and analysis of stepped wedge cluster randomized trials. Contemporary Clinical Trials 2007;28:182-191.
Kasza J, Hemming K, Hooper R, Matthews JNS, Forbes AB. Impact of non-uniform correlation on sample size and power in multiple-period cluster randomized trials. Statistical Methods in Medical Research 2019a; 28: 703-716.
Kasza J, Taljaard M, Forbes AB. Information content of stepped-wedge designs when treatment effect heterogeneity and/or implementation periods are present. Statistics in Medicine 2019b; 38:4686-4701.
Kenny A, Voldal E, Xia F, Heagerty PJ, Hughes JP. Analysis of stepped wedge cluster randomized trials in the presence of a time-varying treatment effect. Statistics in Medicine, in press, 2022.
Voldal EC, Hakhu NR, Xia F, Heagerty PJ, Hughes JP. swCRTdesign: An R package for stepped wedge trial design and analysis. Computer Methods and Programs in Biomedicine 2020;196:105514.
Examples
# Example 1 (Random Intercepts Only, standard Stepped Wedge (SW) design)
swPwr.Ex1.RIO.std <- swPwr(swDsn(c(6,6,6,6)), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0, rho=0, gamma=0, alpha=0.05, retDATA=FALSE)
swPwr.Ex1.RIO.std
# Example 2 (Random Intercepts Only, extended SW design)
swPwr.Ex1.RIO.extend <- swPwr(swDsn(c(6,6,6,6), extra.trt.time=3), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0, rho=0, gamma=0,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.RIO.extend
# Example 3 (Independent Random Intercepts and Treatment effects, standard SW design)
swPwr.Ex1.IRIS <- swPwr(swDsn(c(6,6,6,6)), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0.0045, rho=0, gamma=0,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.IRIS
# Example 4 (Correlated Random Intercepts and Slopes, standard SW design)
swPwr.Ex1.CRIS <- swPwr(swDsn(c(6,6,6,6)), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0.0045, rho=0.4, gamma=0,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.CRIS
# Example 5 (Random time effect and correlated Random Intercepts and Slopes, standard SW design)
swPwr.Ex1.RTCRIS <- swPwr(swDsn(c(6,6,6,6)), distn="binomial",
n=120, mu0=0.05, mu1=0.035, tau=0.01, eta=0.0045, rho=0.4, gamma = 0.1,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.RTCRIS
#Example 6 (Sample size varying by cluster)
sample.size.vector <- c(35219,53535,63785,456132,128670,96673,
51454,156667,127440,68615,56502,17719,
75931,58655,52874,75936)
swPwr.Ex1.vector <- swPwr(swDsn(c(4,3,5,4)), distn="gaussian",
n=sample.size.vector, mu0=2.66, mu1=2.15,
sigma=sqrt(1/2.66), tau=0.31, eta=0.2, rho=0, gamma = 0.15,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.vector
#Example 7 (Sample size varying by cluster and time)
sample.size.matrix <- matrix(c(26, 493, 64, 45, 48, 231, 117, 17, 49, 36, 19, 77, 67, 590,
261, 212, 67, 318, 132, 58, 44, 57, 59, 78, 115, 532, 176, 199, 73, 293, 129, 79, 51,
62, 109, 94, 174, 785, 133, 79, 120, 305, 224, 99, 83, 79, 122, 122, 94, 961, 90, 131, 166,
352, 316, 59, 54, 131, 101, 133),nrow=12,ncol=5, byrow=FALSE)
swPwr.Ex1.matrix <- swPwr(swDsn(c(3,3,3,3)), distn="binomial",
n=sample.size.matrix, mu0=0.08, mu1=0.06, tau=0.017, eta=0.006, rho=-0.5, gamma = 0,
alpha=0.05, retDATA=FALSE)
swPwr.Ex1.matrix
#Example 8 (Using ICC and CAC)
swPwr.Ex1.icccac <- swPwr(swDsn(c(6,6,6,6)), distn="gaussian",
n=120, mu0=0.05, mu1=0.035, sigma=0.1, icc=0.02, cac=0.125, alpha=0.05, retDATA=FALSE)
swPwr.Ex1.icccac
# Example 9 (Random time effect, closed cohort sampling)
sample_size = matrix(c(rep(c(20,20,20,20,20,20,20,20,20,20,20,20,20,20),5),
rep(c( 0,20,20,20,20,20,20,20,20,20,20,20,20,20),5),
rep(c( 0, 0,20,20,20,20,20,20,20,20,20,20,20,20),5),
rep(c( 0, 0, 0,20,20,20,20,20,20,20,20,20,20,20),5),
rep(c( 0, 0, 0, 0,20,20,20,20,20,20,20,20,20,20),5)),
25,14,byrow=TRUE)
swPwr.Ex9 <- swPwr(design=swDsn(c(5,5,5,5,5),extra.ctl.time=3,extra.trt.time=5),
distn="gaussian",n=sample_size,mu0=-0.4,mu1=0.4,
sigma=1.0,tau=sqrt(.1316),gamma=sqrt(.1974),eta=0,rho=0,zeta=sqrt(2.5),
silent=TRUE)
swPwr.Ex9
#Example 10 (Periods with no data, multiple treatment levels)
stdy <- swDsn(c(6,6,6,6),swBlk=matrix(c(0,1,2,2,2,2,
NA,0,1,2,2,2,
NA,NA,0,1,2,2,
NA,NA,NA,0,1,2),4,6,byrow=TRUE))
swPwr.Ex10 <-swPwr(stdy, distn="binomial",n=120, mu0=0.05, mu1=c(0.035,0.03),
tau=0.01, eta=0, rho=0, gamma=0, alpha=0.05, retDATA=TRUE, silent=TRUE)
swPwr.Ex10
# EXample 11 Compare to Kasza et al (2019) figure 4, lower left
swPwr(swDsn(c(1,1,1,1,1,1,1)),distn="gaussian",n=50,mu0=0,mu1=0.2,
tau=sqrt(.035),sigma=sqrt(1-.035),ar=.95,alpha=0.05,retDATA=FALSE,silent=TRUE)
# Example 12 Incomplete design
# These all give the same power
design12 = swDsn(c(4,4,4),swBlk=matrix(c(0,1,1,NA,NA,NA,0,1,1,NA,NA,NA,0,1,1),3,5,byrow=TRUE))
swPwr(design12,distn="gaussian",n=10,mu0=0,mu1=.5,H=c(.5,.5),sigma=1,icc=.01,silent=TRUE)
swPwr(design12,distn="gaussian",n=10,mu0=0,mu1=.5,H=1,sigma=1,icc=.01,silent=TRUE)
# H is automatically expanded and normalized
#
design12a = swDsn(c(4,4,4),extra.trt.time=1)
nmat12a=matrix(c(rep(c(10,10,10,0,0),4),rep(c(0,10,10,10,0),4),rep(c(0,0,10,10,10),4)),12,5,
byrow=TRUE)
swPwr(design12a,distn="gaussian",n=nmat12a,mu0=0,mu1=.5,H=1,sigma=1,icc=.01,silent=TRUE) #OK
swPwr(design12a,distn="gaussian",n=nmat12a,mu0=0,mu1=.5,H=c(1,1,0,0),sigma=1,icc=.01,
silent=TRUE) #OK
# The following generates an error; since design12a is a complete design with maximum lag 4,
# H must be a scalar or vector of length 4
# swPwr(design12a,distn="gaussian",n=nmat12a,mu0=0,mu1=.5,H=c(1,1),sigma=1,icc=.01,silent=TRUE)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.