glsPower: Compute power via weighted least squares

In PMildenb/SteppedPower: Power Calculation for Stepped Wedge Designs

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 \cdot timepoints) rows and columns. If 'CovMat' is given, 'sigma', 'tau', 'eta', 'rho', 'gamma' and 'psi' as well as 'alpha_0_1_2' must be NULL.
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)

##
##

PMildenb/SteppedPower documentation built on Sept. 20, 2023, 4:57 a.m.