| glsPower {SteppedPower} | R Documentation |
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 and covariance matrix, 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 'DesMat' or a matrix indicating the treatment status for each cluster at each timepoint. If supplied, 'timepoints','Cl','trtDelay' are ignored. |
trtDelay |
numeric (possibly vector), 'NA'(s) and/or value(s) between '0' and '1'. 'NA' means that first (second, ... ) period after intervention start is not observed. A value between '0' and '1' specifies the assumed proportion of intervention effect in the first (second ... ) intervention period. |
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 '1's for observed clusterperiods and '0's or 'NA' for unobserved clusterperiods. |
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 'eta' is given as scalar, 'trtMat' is needed as well. |
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'!=0 !* |
rho |
numeric (scalar), correlation of 'tau' and 'eta'. The default is no correlation. |
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 'N' is returned. |
family |
character, distribution family. One of "gaussian", "binomial". Defaults to "gaussian" |
N_range |
numeric, vector specifying the lower and upper bound for 'N', ignored if 'power' is NULL. |
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 'TRUE' for designs with less or equal than 2500 cluster cells, otherwise 'FALSE'. Ignored if 'verbose=0'. |
verbose |
integer, how much information should the function return? See also under 'Value'. |
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)
##
##