| Type: | Package |
| Title: | Power Calculation for Stepped Wedge Designs |
| Version: | 0.4.0 |
| Description: | Tools for power and sample size calculation as well as design diagnostics for longitudinal mixed model settings, with a focus on stepped wedge designs. All calculations are oracle estimates i.e. assume random effect variances to be known (or guessed) in advance. The method is introduced in Hussey and Hughes (2007) <doi:10.1016/j.cct.2006.05.007>, extensions are discussed in Li et al. (2020) <doi:10.1177/0962280220932962>. |
| Depends: | R (≥ 3.5.0) |
| Imports: | Matrix, plotly, Rfast, grDevices, stats, utils |
| Suggests: | knitr, rmarkdown, pwr, testthat |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| VignetteBuilder: | knitr |
| Config/roxygen2/version: | 8.0.0 |
| NeedsCompilation: | no |
| Packaged: | 2026-09-21 09:43:51 UTC; rasputin |
| Author: | Philipp Mildenberger
|
| Maintainer: | Philipp Mildenberger <pmildenb@uni-mainz.de> |
| Repository: | CRAN |
| Date/Publication: | 2026-09-21 10:10:08 UTC |
SteppedPower
Description
SteppedPower offers tools for power and sample size calculation as well as design diagnostics for longitudinal mixed model settings, with a focus on stepped wedge designs. All calculations are oracle estimates i.e. assume random effect variances to be known (or guessed) in advance.
Author(s)
Philipp Mildenberger pmildenb@uni-mainz.de
Transform random effects to alpha
Description
Transforms standard deviations of random effects into a
correlation structure specified by \alpha_0, \alpha_1, \alpha_2
as defined in Li et al. (2018).
Usage
RandEff_to_alpha012(sigResid, tau, gamma, psi)
Arguments
sigResid |
Residual standard deviation on individual level |
tau |
standard deviation of random cluster intercept |
gamma |
standard deviation of random time effect |
psi |
standard deviation of random subject specific intercept |
Value
a list containing four named elements (possibly vectors or matrices):
alpha0, alpha1, alpha2 specify a correlation structure. SigMarg
denotes the marginal standard deviation
References
Li, F., Turner, E. L., & Preisser, J. S. (2018).
Sample size determination for GEE analyses of stepped wedge cluster randomized trials.
Biometrics, 74(4), 1450-1458. DOI: 10.1111/biom.12918
See Also
RandEff_to_icc(), icc_to_RandEff() or alpha012_to_RandEff()
Examples
RandEff_to_alpha012(sigResid=sqrt(11), tau=4, gamma=3, psi=2)
## The function is vectorised:
RandEff_to_alpha012(sigResid = matrix(c(0,1,2,3,4,5), 2, 3),
tau = matrix(c(1,1,1,0,0,0), 2, 3),
gamma = matrix(c(0,0,1,0,0,1), 2, 3),
psi = matrix(c(0,1,1,0,0,1), 2, 3))
Transform random effects into ICC, CAC, IAC
Description
This function transforms standard deviations of random effects into intracluster correlation (ICC), cluster autocorrelation (CAC) and individual autocorrelation (IAC). It reproduces the formulae in Hooper et al. (2016).
Usage
RandEff_to_icc(sigResid, tau, gamma = 0, psi = 0)
Arguments
sigResid |
Residual standard deviation on individual level |
tau |
standard deviation of random cluster intercept |
gamma |
standard deviation of random time effect |
psi |
standard deviation of random subject specific intercept |
Details
The formulae used are
\sigma^2_{marg} = \sigma^2_{resid} + \tau^2 + \gamma^2 + \psi^2 \\[1ex]
ICC = \frac{\tau^2 + \gamma^2}{\sigma^2_{marg}} \\[1ex]
CAC = \frac{\tau^2}{\tau^2 + \gamma^2} \\[1ex]
IAC = \frac{\psi^2}{\sigma^2_{resid}+\psi^2}
Value
a list containing four named elements (possibly vectors or matrices):
-
iccintracluster correlation -
caccluster autocorrelation -
iacindividual autocorrelation -
sigResidResidual standard deviation on individual level
References
Hooper, R., Teerenstra, S., de Hoop, E., & Eldridge, S. (2016).
Sample size calculation for stepped wedge and other longitudinal cluster randomised trials.
Statistics in medicine, 35(26), 4718-4728. DOI: 10.1002/sim.7028
See Also
icc_to_RandEff(), RandEff_to_alpha012() or alpha012_to_RandEff()
Closed formula for treatment variance in open cohort settings
Description
From Kasza et al "Sample size and power calculations for open cohort longitudinal cluster rondomized trials" 2020
Usage
VarClosed_Kasza(trtMat, tau, gamma = 0, psi = 0, sigma, N, chi)
Arguments
trtMat |
a matrix trtMat to define treatment allocation, where rows and columns correspond to cluster and timepoints, respectively |
tau |
numeric, standard deviation of random intercepts |
gamma |
numeric, random time effect |
psi |
numeric, random subject specific intercept. |
sigma |
numeric, residual error on subject level. |
N |
numeric, number of individuals per cluster. |
chi |
Attrition factor |
Value
numeric, variance of the estimator for treatment effect
Examples
## test setting, from Hussey&Hughes 2007 ####
trtMat <- construct_DesMat(c(6,6,6,6))$trtMat
tau <- .025 ; sigma <- sqrt(.041*.959) ; N <- 100 ;
gamma <- 0.01 ; psi <- .1 ; chi <- .7
tmp <- VarClosed_Kasza(trtMat, tau=tau, sigma=sigma, gamma=0, psi=0, N=N, chi=0)
tTestPwr((.05-.032), sqrt(tmp), df = Inf)
glsPower(Cl = rep(6,4), N=N, mu0=.05, mu1=.032, verbose=0,
sigma=sigma, gamma=0, tau=tau, psi=0)
tmp <- VarClosed_Kasza(trtMat, tau=tau, sigma=sigma, gamma=gamma, psi=psi, N=N, chi=0)
tTestPwr((.05-.032), sqrt(tmp), df = Inf)
glsPower(Cl = rep(6,4), N=N, mu0=.05, mu1=.032, verbose=0,
sigma=sigma, gamma=gamma, tau=tau, psi=psi)
tmp <- VarClosed_Kasza(trtMat, tau=tau, sigma=sigma, gamma=gamma, psi=psi, N=N, chi=1)
tTestPwr((.05-.032), sqrt(tmp), df = Inf)
glsPower(Cl = rep(6,4), N=N, mu0=.05, mu1=.032, verbose=0,
sigma=sigma, gamma=sqrt(gamma^2+psi^2/N), tau=tau, psi=0)
tmp <- VarClosed_Kasza(trtMat, tau=tau, sigma=sigma, gamma=gamma, psi=psi, N=N, chi=chi)
tTestPwr((.05-.032), sqrt(tmp), df = Inf)
glsPower(Cl = rep(6,4), N=N, mu0=.05, mu1=.032, verbose=0,
sigma=sigma, gamma=sqrt(gamma^2+chi*psi^2/N), tau=tau, psi=sqrt(1-chi)*psi)
Closed formula for treatment variance, with proportional decay
Description
From Li et al "Design and analysis considerations for cohort stepped wedge cluster randomized trials with a decay correlation structure"
Usage
VarClosed_Li(trtMat, tau, psi, N, AR)
Arguments
trtMat |
a matrix trtMat to define treatment allocation, where rows and columns correspond to cluster and timepoints, respectively |
tau |
numeric, standard deviation of random intercepts |
psi |
numeric, random subject specific intercept. |
N |
numeric, number of individuals per cluster. |
AR |
numeric (scalar), It defines the AR(1)-correlation of random effects. |
Value
numeric, variance of the estimator for treatment effect
Examples
## test setting, from Hussey&Hughes 2007 ####
trtMat <- construct_DesMat(c(6,6,6,6))$trtMat
tau <- .025 ; N <- 100 ; psi <- .1 ; AR <- .6
tmp <- VarClosed_Li(trtMat, tau=tau, psi=psi, N=N, AR=AR)
tTestPwr((.05-.032), se=sqrt(tmp), Inf)
glsPower(Cl=rep(6,4), mu0=.05, mu1=.032, AR=AR,
tau=tau, N=N, sigma=0, psi=psi, verbose=0)
Transform alpha to random effects
Description
Transforms a correlation structure specified by \alpha_0, \alpha_1, \alpha_2
as defined in Li et al. (2018) into standard deviations of random effects.
Usage
alpha012_to_RandEff(alpha012, sigResid = NULL, sigMarg = NULL)
Arguments
alpha012 |
A vector or a list of length 3. Each list element must have the same dimension(s). |
sigResid |
Residual standard deviation on individual level. Either residual sd or marginal sd needs to be specified. |
sigMarg |
Marginal standard deviation on individual level. Either residual sd or marginal sd needs to be specified. |
Value
a list containing four named elements (possibly vectors or matrices):
random cluster intercept
tau,random time effect
gamma,random subject intercept
psi,residual standard deviation
sigResid.
References
Li, F., Turner, E. L., & Preisser, J. S. (2018).
Sample size determination for GEE analyses of stepped wedge cluster randomized trials.
Biometrics, 74(4), 1450-1458. DOI: 10.1111/biom.12918
See Also
RandEff_to_icc(), icc_to_RandEff() or RandEff_to_alpha012()
Examples
alpha012_to_RandEff(alpha012=c(.1,.1,.1), sigMarg=1)
alpha012_to_RandEff(alpha012=c(.1,.1,.1), sigResid=.9486833)
## The function is vectorised:
alpha012_to_RandEff(alpha012=list(matrix(c(0,.1,.1,.2), 2, 2),
matrix(c(0,0,.1,.2) , 2, 2),
matrix(c(0,0,.2,.2) , 2, 2)),
sigMarg=1)
Title Formula-based calculation of information content
Description
Title Formula-based calculation of information content
Usage
compute_InfoContent(CovMat = NULL, W = NULL, dsn, sumCl, tp)
Arguments
CovMat |
#' @param CovMat numeric, a positive-semidefinite matrix with
(#Clusters |
W |
numeric, the inverse of a covariance matrix. If CovMat is specified, input for W is ignored |
dsn |
a matrix with (#Clusters |
sumCl |
number of clusters |
tp |
number of time points |
Value
A matrix containing the information content for every cluster-period cell
Compute power via weighted least squares
Description
This function is not intended to be used directly, but rather to be called
by glsPower - the main function of this package.
It expects the design matrix as an input argument DesMat and
construct the covariance matrix (if not given as well). These matrices are
used to calculate the variance of the treatment effect estimator which is
then used to calculate the power to detect the assumed treatment effect.
Usage
compute_glsPower(
DesMat,
EffSize,
sigma,
tau = 0,
eta = NULL,
AR = NULL,
rho = NULL,
gamma = NULL,
psi = NULL,
CovMat = NULL,
dfAdjust = "none",
sig.level = 0.05,
INDIV_LVL = FALSE,
INFO_CONTENT = FALSE,
verbose = 1
)
Arguments
DesMat |
object of class |
EffSize |
raw effect, i.e. difference between mean under control and mean under intervention |
sigma |
numeric, residual error of cluster means if no N given. |
tau |
numeric, standard deviation of random intercepts |
eta |
numeric (scalar or matrix), standard deviation of random slopes.
If |
AR |
numeric, vector containing up to three values, each between 0 and 1.
Defaults to NULL. It defines the AR(1)-correlation of random effects.
The first element corresponds to the cluster intercept, the second to the
treatment effect and the third to subject specific intercept.
If only one element is provided, autocorrelation of all random effects is
assumed to be the same.
Currently not compatible with |
rho |
numeric (scalar), correlation of |
gamma |
numeric (scalar), random time effect |
psi |
numeric (scalar), random subject specific intercept. Leads to a closed cohort setting |
CovMat |
numeric, a positive-semidefinite matrix with
(#Clusters |
dfAdjust |
character, one of the following: "none","between-within", "containment", "residual". |
sig.level |
numeric (scalar), significance level, defaults to 0.05 |
INDIV_LVL |
logical, should the computation be conducted on an individual level? This leads to longer run time and is mainly for diagnostic purposes. |
INFO_CONTENT |
logical, should the information content of cluster cells be
computed? The default is |
verbose |
integer, how much information should the function return?
See also under |
Value
The return depends on the verbose parameter.
If verbose=0, only the power is returned
If verbose=1 (the default), a list containing power and the
parameters of the specific setting is returned.
If requested (by verbose=2) this list also contains relevant matrices.
Construct a Single Block of the Covariance Matrix
Description
Constructs the covariance matrix
for multiple measurements of the same cluster.
This function is usually called by construct_CovMat and is
not designed to be used directly.
Usage
construct_CovBlk(sigma, tau = NULL, eta = NULL, AR = NULL, rho = NULL)
Arguments
sigma |
numeric (vector of length |
tau |
numeric (vector of length |
eta |
numeric (vector of length |
AR |
numeric, vector containing up to three values, each between 0 and 1.
Defaults to NULL. It defines the AR(1)-correlation of random effects.
The first element corresponds to the cluster intercept, the second to the
treatment effect and the third to subject specific intercept.
If only one element is provided, autocorrelation of all random effects is
assumed to be the same.
Currently not compatible with |
rho |
numeric (scalar), correlation of |
Value
a block of a covariance matrix, corresponding to intra-cluster covariance over time for one cluster
Examples
construct_CovBlk(sigma=rep(2,5), tau=rep(1,5))
construct_CovBlk(sigma=rep(2,5),
tau=rep(.5,5), eta=c(0,0,1,1,1),
AR=c(.5, 1))
Construct a Covariance Matrix
Description
constructs a (block diagonal) covariance matrix.
This function calls construct_CovBlk
(or construct_CovSubMat in case of repeated
observations of the same individuals) for each block.
Usage
construct_CovMat(
sumCl = NULL,
timepoints = NULL,
sigma,
tau,
eta = NULL,
AR = NULL,
rho = NULL,
gamma = NULL,
trtMat = NULL,
N = NULL,
CovBlk = NULL,
psi = NULL,
INDIV_LVL = FALSE
)
Arguments
sumCl |
total number of clusters |
timepoints |
numeric (scalar or vector), number of timepoints (periods). If design is swd, timepoints defaults to length(Cl)+1. Defaults to 1 for parallel designs. |
sigma |
numeric, residual error of cluster means if no N given. |
tau |
numeric, standard deviation of random intercepts |
eta |
numeric (scalar or matrix), standard deviation of random slopes.
If |
AR |
numeric, vector containing up to three values, each between 0 and 1.
Defaults to NULL. It defines the AR(1)-correlation of random effects.
The first element corresponds to the cluster intercept, the second to the
treatment effect and the third to subject specific intercept.
If only one element is provided, autocorrelation of all random effects is
assumed to be the same.
Currently not compatible with |
rho |
numeric (scalar), correlation of |
gamma |
numeric (scalar), random time effect |
trtMat |
a matrix of dimension #Cluster x timepoints as produced by
the function |
N |
numeric, number of individuals per cluster. Either a scalar, vector of length #Clusters or a matrix of dimension #Clusters x timepoints. Defaults to 1 if not passed. |
CovBlk |
a matrix of dimension timepoints x timepoints. |
psi |
numeric (scalar), random subject specific intercept. Leads to a closed cohort setting |
INDIV_LVL |
logical, should the computation be conducted on an individual level? This leads to longer run time and is mainly for diagnostic purposes. |
Value
a covariance matrix
Examples
## Two clusters, three timepoints,
## residual standard error sd=3, random slope sd=1.
construct_CovMat(sumCl=2, timepoints=3, sigma=3, tau=1)
##
##
## ... with random slope as AR-1 process
construct_CovMat(sumCl=2, timepoints=3, sigma=3, tau=1, AR=.8)
##
##
## ... with sigma and tau variing over time and between clusters:
construct_CovMat(sumCl=2,timepoints=3,
sigma=matrix(c(1,2,2,1,1,2),nrow=2, byrow=TRUE),
tau=matrix(c(.2,.1,.1,.2,.2,.1),nrow=2, byrow=TRUE),
N=c(3,4))
Construct a Block of the Covariance Matrix
Description
Constructs the covariance matrix for multiple measurements of the same cluster if the same individuals are observed at all time periods. This function is not designed to be used directly.
Usage
construct_CovSubMat(
N,
timepoints,
sigma,
tau,
eta = NULL,
AR = NULL,
rho = NULL,
gamma = NULL,
psi = NULL,
INDIV_LVL = FALSE
)
Arguments
N |
Number of individuals per cluster |
timepoints |
numeric (scalar or vector), number of timepoints (periods). If design is swd, timepoints defaults to length(Cl)+1. Defaults to 1 for parallel designs. |
sigma |
numeric (vector of length |
tau |
numeric (vector of length |
eta |
numeric (vector of length |
AR |
numeric, vector containing up to three values, each between 0 and 1.
Defaults to NULL. It defines the AR(1)-correlation of random effects.
The first element corresponds to the cluster intercept, the second to the
treatment effect and the third to subject specific intercept.
If only one element is provided, autocorrelation of all random effects is
assumed to be the same.
Currently not compatible with |
rho |
numeric (scalar), correlation of |
gamma |
numeric (vector of length |
psi |
numeric (scalar), random subject specific intercept. Leads to a closed cohort setting |
INDIV_LVL |
logical, should the computation be conducted on an individual level? This leads to longer run time and is mainly for diagnostic purposes. |
Value
a block of a covariance matrix with two levels of clustering, corresponding to intra-cluster covariance over time for one cluster
Construct the Design Matrix
Description
Constructs the design matrix with one column for every (fixed)
parameter to be estimated and one row for every cluster for every timepoint.
This function calls construct_trtMat to construct a matrix that indicates
treatment status for each cluster at each timepoint.
This is then transformed into the first
column of the design matrix. construct_DesMat further calls
construct_timeAdjust to get the fixed effect(s) of the timepoints.
Note: Unlike the usual notation, the treatment effect is in the first column (for easier access by higher level functions).
Usage
construct_DesMat(
Cl = NULL,
trtDelay = NULL,
dsntype = "SWD",
timepoints = NULL,
timeAdjust = "factor",
period = NULL,
trtmatrix = NULL,
timeBlk = NULL,
N = NULL,
incomplete = NULL,
INDIV_LVL = FALSE
)
Arguments
Cl |
integer (vector), number of clusters per sequence group (in SWD), or number in control and intervention (in parallel designs) |
trtDelay |
numeric (possibly vector), |
dsntype |
character, defines the type of design. Options are "SWD", "parallel" and "parallel_baseline", defaults to "SWD". |
timepoints |
numeric (scalar or vector), number of timepoints (periods). If design is swd, timepoints defaults to length(Cl)+1. Defaults to 1 for parallel designs. |
timeAdjust |
character, specifies adjustment for time periods. One of the following: "factor", "linear", "none", "periodic". Defaults to "factor". |
period |
numeric (scalar) |
trtmatrix |
an optional user defined matrix to define treatment allocation |
timeBlk |
an optional user defined matrix that defines the time adjustment in one cluster. Is repeated for every cluster. |
N |
numeric, number of individuals per cluster. Either a scalar, vector of length #Clusters or a matrix of dimension #Clusters x timepoints. Defaults to 1 if not passed. |
incomplete |
integer, either a scalar (only for SWD) or a matrix.
A vector defines the number of periods before and after the switch from
control to intervention that are observed. A matrix consists of |
INDIV_LVL |
logical, should the computation be conducted on an individual level? This leads to longer run time and is mainly for diagnostic purposes. |
Value
an object of class DesMat
Examples
construct_DesMat(Cl=c(2,0,1))
construct_DesMat(Cl=c(2,0,1), N=c(1,3,2))
## manually defined time adjustment (same as above)
timeBlock <- matrix(c(1,0,0,0,
1,1,0,0,
1,0,1,0,
1,0,0,1), 4, byrow=TRUE)
construct_DesMat(Cl=c(2,0,1), timeBlk=timeBlock)
Constructs a matrix of NA and 1 for unobserved and observed cluster periods, respectively.
Description
Mostly useful to build incomplete stepped wedge designs
Usage
construct_incompMat(incomplete, dsntype, timepoints, Cl, trtmatrix = NULL)
Arguments
incomplete |
integer, either a scalar (only for SWD) or a matrix.
A vector defines the number of periods before and after the switch from
control to intervention that are observed. A matrix consists of |
dsntype |
character, defines the type of design. Options are "SWD", "parallel" and "parallel_baseline", defaults to "SWD". |
timepoints |
numeric (scalar or vector), number of timepoints (periods). If design is swd, timepoints defaults to length(Cl)+1. Defaults to 1 for parallel designs. |
Cl |
integer (vector), number of clusters per sequence group (in SWD), or number in control and intervention (in parallel designs) |
trtmatrix |
an optional user defined matrix to define treatment allocation |
Value
a matrix
Construct the time period adjustment in the design matrix
Description
Offers several options to adjust for secular trends.
Usage
construct_timeAdjust(
Cl,
timepoints,
timeAdjust = "factor",
period = NULL,
timeBlk = NULL
)
Arguments
Cl |
integer (vector), number of clusters per sequence group (in SWD), or number in control and intervention (in parallel designs) |
timepoints |
numeric (scalar or vector), number of timepoints (periods). If design is swd, timepoints defaults to length(Cl)+1. Defaults to 1 for parallel designs. |
timeAdjust |
character, specifies adjustment for time periods. One of the following: "factor", "linear", "none", "periodic". Defaults to "factor". |
period |
numeric (scalar) |
timeBlk |
an optional user defined matrix that defines the time adjustment in one cluster. Is repeated for every cluster. |
Value
a matrix with one row for every cluster at every timepoint and number of columns depending of adjustment type.
Construct Treatment Matrix
Description
Constructs a matrix of #cluster rows and #timepoint columns, indicating
treatment status in each cluster at each timepoint.
Usage
construct_trtMat(Cl, trtDelay, dsntype, timepoints = NULL)
Arguments
Cl |
integer (vector), number of clusters per sequence group (in SWD), or number in control and intervention (in parallel designs) |
trtDelay |
numeric (possibly vector), |
dsntype |
character, defines the type of design. Options are "SWD", "parallel" and "parallel_baseline", defaults to "SWD". |
timepoints |
numeric (scalar or vector), number of timepoints (periods). If design is swd, timepoints defaults to length(Cl)+1. Defaults to 1 for parallel designs. |
Value
a matrix trtMat, where rows and columns correspond to cluster and timepoints, respectively
Examples
construct_trtMat(Cl=c(1,2,1), trtDelay=c(.2,.8), dsntype="SWD")
Compute power via weighted least squares
Description
This is the main function of the SteppedPower package.
It calls the constructor functions for the design matrix
construct_DesMat and
covariance matrix construct_CovMat,
and then calculates the variance of the
intervention effect estimator. The latter is then used
to compute the power of a Wald test of a (given) intervention effect.
Usage
glsPower(
Cl = NULL,
timepoints = NULL,
DesMat = NULL,
trtDelay = NULL,
incomplete = NULL,
timeAdjust = "factor",
period = NULL,
dsntype = "SWD",
mu0,
mu1,
marginal_mu = FALSE,
sigma = NULL,
tau = NULL,
eta = NULL,
AR = NULL,
rho = NULL,
gamma = NULL,
psi = NULL,
alpha_0_1_2 = NULL,
CovMat = NULL,
N = NULL,
power = NULL,
family = "gaussian",
N_range = c(1, 1000),
sig.level = 0.05,
dfAdjust = "none",
INDIV_LVL = FALSE,
INFO_CONTENT = NULL,
verbose = 1
)
Arguments
Cl |
integer (vector), number of clusters per sequence group (in SWD), or number in control and intervention (in parallel designs) |
timepoints |
numeric (scalar or vector), number of timepoints (periods). If design is swd, timepoints defaults to length(Cl)+1. Defaults to 1 for parallel designs. |
DesMat |
Either an object of class |
trtDelay |
numeric (possibly vector), |
incomplete |
integer, either a scalar (only for SWD) or a matrix.
A vector defines the number of periods before and after the switch from
control to intervention that are observed. A matrix consists of |
timeAdjust |
character, specifies adjustment for time periods. One of the following: "factor", "linear", "none", "periodic". Defaults to "factor". |
period |
numeric (scalar) |
dsntype |
character, defines the type of design. Options are "SWD", "parallel" and "parallel_baseline", defaults to "SWD". |
mu0 |
numeric (scalar), mean under control |
mu1 |
numeric (scalar), mean under treatment |
marginal_mu |
logical. Only relevant for non-gaussian outcome. Indicates whether mu0 and mu1 are to be interpreted as marginal prevalence under control and under treatment, respectively, or whether they denote the prevalence conditional on random effects being 0 (It defaults to the latter). (experimental!) |
sigma |
numeric, residual error of cluster means if no N given. |
tau |
numeric, standard deviation of random intercepts |
eta |
numeric (scalar or matrix), standard deviation of random slopes.
If |
AR |
numeric, vector containing up to three values, each between 0 and 1.
Defaults to NULL. It defines the AR(1)-correlation of random effects.
The first element corresponds to the cluster intercept, the second to the
treatment effect and the third to subject specific intercept.
If only one element is provided, autocorrelation of all random effects is
assumed to be the same.
Currently not compatible with |
rho |
numeric (scalar), correlation of |
gamma |
numeric (scalar), random time effect |
psi |
numeric (scalar), random subject specific intercept. Leads to a closed cohort setting |
alpha_0_1_2 |
numeric vector or list of length 2 or 3, that consists of alpha_0, alpha_1 and alpha_2. Can be used instead of random effects to define the correlation structure, following Li et al. (2018). When omitting alpha_2, this describes a cross-sectional design, where alpha_0 and alpha_1 define the intracluster correlation and cluster autocorrelation, respectively - as defined by Hooper et al. (2016). |
CovMat |
numeric, a positive-semidefinite matrix with
(#Clusters |
N |
numeric, number of individuals per cluster. Either a scalar, vector of length #Clusters or a matrix of dimension #Clusters x timepoints. Defaults to 1 if not passed. |
power |
numeric, a specified target power.
If supplied, the minimal |
family |
character, distribution family. One of "gaussian", "binomial". Defaults to "gaussian" |
N_range |
numeric, vector specifying the lower and upper bound for |
sig.level |
numeric (scalar), significance level, defaults to 0.05 |
dfAdjust |
character, one of the following: "none","between-within", "containment", "residual". |
INDIV_LVL |
logical, should the computation be conducted on an individual level? This leads to longer run time and is mainly for diagnostic purposes. |
INFO_CONTENT |
logical, should the information content of cluster cells be
computed? The default is |
verbose |
integer, how much information should the function return?
See also under |
Details
Let \theta:= \mu_1-\mu_0 the treatment effect under investigation.
The variance of the treatment effect estimator \hat\theta can then be
estimated via weighted least squares (see also vignette 'Getting Started').
Value
The return depends on the verbose parameter.
If verbose=0, only the power is returned
If verbose=1 (the default), a list containing power, projection matrix and the
parameters of the specific setting is returned.
If explicitly requested (by verbose=2) this list also contains
the DesMat-object and the covariance matrix.
If INFO_CONTENT= TRUE, the returned list contains a named list with four elements:
Cells is explicit computation of the information content in each cell;
Cluster is the information content of entire clusters;
time is thie information content of entire time periods and
Closed is a formula-based computation the information content in each cell,
Examples
## See also vignette for more examples
##
##
## stepped wedge design with 5 Clusters in 5 sequences,
## residual standard deviation 2,
## cluster effect sd = 0.33, and 10 individuals per cluster.
## Further, let the mean under the null and alternative hypothesis 0 and 1,
## respectively.
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33, N=10)
##
##
## ... with auto-regressive cluster effect `AR=0.7`.
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33, AR=0.7, N=10)
##
##
## ... with varying cluster size
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33, N=c(12,8,10,9,14))
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33,
N=matrix(c(12,8,10,9,14,
11,8,10,9,13,
11,7,11,8,12,
10,7,10,8,11,
9,7, 9,7,11,
9,6, 8,7,11),5,6))
##
##
## ... with random treatment effect (with standard deviation 0.2),
## which is correlated with the cluster effect with `rho`=0.25.
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33, eta=.2, rho=.25, N=10)
##
##
## ... with missing observations (a.k.a. incomplete stepped wedge design)
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33, N=10, incomplete=3)
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33, N=10,
incomplete=matrix(c(1,1,1,0,0,
1,1,1,1,0,
1,1,1,1,1,
1,1,1,1,1,
0,1,1,1,1,
0,0,1,1,1),5,6))
## -> the same.
##
## ... with two levels of clustering. This arises if the patients are
## observed over the whole study period
## (often referred to as closed cohort design) or if subclusters exist
## (such as wards within clinics). For
mod_aggr <- glsPower(mu0=0, mu1=1, Cl=rep(1,5),
sigma=2, tau=0.33, psi=.25,
N=10, incomplete=3, verbose=2)
mod_indiv <- glsPower(mu0=0, mu1=1, Cl=rep(1,5),
sigma=2, tau=0.33, psi=.25,
N=10, incomplete=3, verbose=2, INDIV_LVL=TRUE)
mod_aggr
mod_indiv
## Compare covariance matrices of first cluster
mod_aggr$CovarianceMatrix[1:6,1:6] ; mod_indiv$CovarianceMatrix[1:60,1:60]
##
##
## stepped wedge design with 5 Clusters in 5 sequences, residual sd = 2,
## cluster effect sd = 0.33. How many Individuals are needed to achieve a
## power of 80% ?
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33, power=.8)
##
## ... How many are needed if we have a closed cohort design with a random
## individuum effect of .7?
glsPower(mu0=0, mu1=1, Cl=rep(1,5), sigma=2, tau=0.33, psi=.7, power=.8)
##
##
## longitudinal parallel design, with 5 time periods, 3 clusters in treatment
## and control arm each.
glsPower(mu0=0, mu1=1, Cl=c(3,3), sigma=2, tau=0.33, N=10,
dsntype="parallel", timepoints=5)
##
##
##
## ... with one baseline period and four parallel periods
glsPower(mu0=0, mu1=1, Cl=c(3,3), sigma=2, tau=0.33, N=10,
dsntype="parallel_baseline", timepoints=c(1,4))
##
##
##
## cross-over design with two timepoints before and two after the switch
glsPower(mu0=0, mu1=1, Cl=c(3,3), sigma=2, tau=0.33, N=10,
dsntype="crossover", timepoints=c(2,2))
##
##
##
## stepped wedge design with 32 Individuals in 8 sequences, binomial outcome,
## 50% incidence under control, 25% incidence under interventional treatment.
## cluster effect sd = 0.5 (ICC of 1/3 under control),
## every individual is its own cluster.
## ... with incidences defined conditional on cluster effect=0
glsPower(mu0=0.5, mu1=0.25, Cl=rep(4,8), tau=0.5, N=1,
family="binomial")
##
##
## ... with marginally defined proportions
glsPower(mu0=0.5, mu1=0.25, Cl=rep(4,8), tau=0.5, N=1,
family="binomial", marginal_mu=TRUE)
##
##
Transform ICC, CAC, IAC into random effects
Description
This function transforms a covariance structure specified by
intracluster correlation (ICC), cluster autocorrelation (CAC)
and individual autocorrelation (IAC) as in Hooper et al. (2016)
into the random effects notation. The latter specification type
is used by the workhorse function of this package, glsPower().
Usage
icc_to_RandEff(icc, cac = 1, iac = 0, sigMarg = NULL, sigResid = NULL)
Arguments
icc |
intracluster correlation |
cac |
cluster autocorrelation |
iac |
individual autocorrelation |
sigMarg |
Marginal standard deviation |
sigResid |
Residual standard deviation on individual level |
Details
The formulae used are
\sigma^2_{resid} = \sigma^2_{marg} (1-ICC) (1-IAC) \\[1ex]
\tau^2 = \sigma^2_{marg} \cdot ICC \cdot CAC \\[1ex]
\gamma^2 = \sigma^2_{marg} \cdot ICC \cdot (1-CAC) \\[1ex]
\psi^2 = \sigma^2_{marg} \cdot IAC \cdot (1-ICC)
Note that this does not allow to define the standard deviation of
a random treatment effect eta, but you can manually define it in the call to
glsPower(), see examples.
The CAC is sometimes interpreted in two different ways. Two-period decay
(the more common interpretation) allows correlation within the same period to
differ form those across periods. Discrete time decay (much less common interpretation),
on the other hand, assumes a consistent rate of correlation decay over time.
The former introduces an additional random term (i.e. an cluster-period specific
random intercept, with standard deviation \gamma), whereas the latter simply defines a fixed autocorrelation structure
that dictates how correlations diminish over time. Therefore, if CAC is specified,
is is interpreted as two-period decay and a (non-zero) value for gamma is returned. To define discrete time decay, please use
the AR option in the main function glsPower() instead.
Value
a list containing five named elements (possibly vectors or matrices):
random cluster intercept
tau,random time effect
gamma,random subject intercept
psi,residual standard deviation
sigResidandmarginal standard deviation
sigMarg.
References
Hooper, R., Teerenstra, S., de Hoop, E., & Eldridge, S. (2016).
Sample size calculation for stepped wedge and other longitudinal cluster randomised trials.
Statistics in medicine, 35(26), 4718-4728. DOI: 10.1002/sim.7028
See Also
RandEff_to_icc(), RandEff_to_alpha012() or alpha012_to_RandEff()
Examples
## The function can be applied to vectors
tmp <- icc_to_RandEff(icc=c(0.01,0.005,0.001),
cac=1,
iac=.001,
sigMarg=sqrt(.5*(1-.5)) )
tmp
## This can then be inserted into `glsPower()` to calculate power for a
## specific setting (albeit not as vectors)
## Possibly with an additional random treatment effect `eta`.
glsPower(Cl=rep(2,4),
N = 15,
mu0=.5, mu1=.3,
sigma = tmp$sigResid[1],
tau = tmp$tau[1],
gamma = tmp$gamma[1],
psi = tmp$psi[1],
eta = 0.03 )
plot.DesMat
Description
plot.DesMat
Usage
## S3 method for class 'DesMat'
plot(x, show_colorbar = FALSE, INDIV_LVL = FALSE, ...)
Arguments
x |
An object of class |
show_colorbar |
logical, should the colorbar be shown? |
INDIV_LVL |
logical, should the computation be conducted on an individual level? This leads to longer run time and is mainly for diagnostic purposes. |
... |
Arguments to be passed to methods |
Value
a plotly html widget, displaying the treatment status
Examples
x <- construct_DesMat(Cl=c(2,2,2,0,2,2,2),.5)
plot an object of class glsPower
Description
Up to four plots (selectable by which) that visualise:
the contribution of each cluster-period cell to the treatment effect estimator,
the information content of each cluster-period cell,
the treatment status for each cluster for each time point and
the covariance matrix. By default, only the first two plots are returned.
Usage
## S3 method for class 'glsPower'
plot(
x,
which = NULL,
show_colorbar = NULL,
annotations = NULL,
annotation_size = NULL,
marginal_plots = TRUE,
...
)
Arguments
x |
object of class glsPower |
which |
Specify a subset of the numbers |
show_colorbar |
logical, should the colorbars be shown? |
annotations |
logical, should the cell contributions be annotated in the Plot? |
annotation_size |
font size of annotation in influence plots |
marginal_plots |
should the influence of whole periods, clusters also be plotted? |
... |
Arguments to be passed to methods |
Value
a list of plotly html widgets
plot cell contributions (weights) of a gls object
Description
plot cell contributions (weights) of a gls object
Usage
plot_CellWeights(
x,
annotations = NULL,
annotation_size = NULL,
show_colorbar = TRUE,
marginal_plots = TRUE
)
Arguments
x |
object of class glsPower |
annotations |
logical, should the cell contributions be annotated in the Plot? |
annotation_size |
font size of annotation in influence plots |
show_colorbar |
logical, should the colorbars be shown? |
marginal_plots |
should the influence of whole periods, clusters also be plotted? |
Value
a plotly html widget
Visualise a Covariance Matrix
Description
Currently not exported.
Usage
plot_CovMat(CovMat, show_colorbar = FALSE)
Arguments
CovMat |
A covariance matrix (possibly in sparse matrix notation) |
show_colorbar |
logical, should the colorbar be shown? |
Value
a plotly object
plot the information content of a gls object
Description
plot the information content of a gls object
Usage
plot_InfoContent(
IC,
annotations = NULL,
annotation_size = NULL,
show_colorbar = TRUE,
marginal_plots = TRUE
)
Arguments
IC |
a matrix with information content for each cluster at each time period |
annotations |
logical, should the cell contributions be annotated in the Plot? |
annotation_size |
font size of annotation in influence plots |
show_colorbar |
logical, should the colorbars be shown? |
marginal_plots |
should the influence of whole periods, clusters also be plotted? |
Value
a plotly object
print.DesMat
Description
print.DesMat
Usage
## S3 method for class 'DesMat'
print(x, ...)
Arguments
x |
An object of class 'DesMat |
... |
Arguments to be passed to methods |
Value
Messages with information about the design.
Print an object of class glsPower
Description
Print an object of class glsPower
Usage
## S3 method for class 'glsPower'
print(x, ...)
Arguments
x |
object of class glsPower |
... |
Arguments to be passed to methods |
Value
Messages, containing information about (at least) power and significance level
Compute Power of a Wald Test
Description
Computes the power of a scaled Wald test given a standard error, an effect size, the degrees of freedom of the t-distribution and a significance level. Computes the exact power, see second example
Usage
tTestPwr(d, se, df, sig.level = 0.05)
Arguments
d |
numeric, raw effect |
se |
numeric, standard error |
df |
numeric, degrees of freedom of the t-distribution |
sig.level |
numeric, significance level, defaults to 0.05 |
Value
a scalar
Examples
tTestPwr(4,1,10) ; tTestPwr(4,1,30) ; tTestPwr(4,1,Inf)