--- title: "Getting Started with `SteppedPower`" author: - name: Philipp Mildenberger affiliation: Institute of Medical Biostatistics, Epidemiology and Informatics ([IMBEI, Mainz](https://www.unimedizin-mainz.de/imbei/imbei/welcome-page/)) - name: Federico Marini affiliation: Institute of Medical Biostatistics, Epidemiology and Informatics ([IMBEI, Mainz](https://www.unimedizin-mainz.de/imbei/imbei/welcome-page/)) date: "`r Sys.Date()`" output: rmarkdown::html_vignette: toc: true number_sections: true bibliography: references.bib vignette: > %\VignetteIndexEntry{Getting Started with `SteppedPower`} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", fig.width = 7, warning = FALSE ) library(knitr) library(SteppedPower) library(Matrix) library(plotly) assign("knit_print.plotly", function(x, ...) { x <- plotly::partial_bundle(x) NextMethod() }, envir = .GlobalEnv) # A function for captioning and referencing images fig <- local({ i <- 0 ref <- list() list( cap=function(refName, text) { i <<- i + 1 ref[[refName]] <<- i paste("Figure ", i, ": ", text, sep="") }, ref=function(refName) { paste("(Fig.", ref[[refName]],")") }) }) ``` # About `SteppedPower` 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. Other implemented study design types are parallel, parallel with baseline period(s) and crossover designs. Further design types can be easily defined by the user. Currently, normal, binomial, and count (Poisson) outcomes with identity link are implemented (see also the [Binomial and Count Outcomes](Binomial_and_Count_Outcomes.html) vignette). The following random effects can be specified: random cluster intercept, random treatment effect, random subject specific intercept and random time effect. The covariance structure can be compound symmetry or autoregressive. This package is modularised in order to be flexible and easy to use (and hopefully to maintain as well). At the same time, the use of sparse matrix classes of the `matrix` package makes computation of large designs feasible. # Methods and Notation A common approach to model the correlation in longitudinal studies are random effects [@hussey2007design; @li2020mixed]. Such a model has the form $$y_{ijk}= T_{ij} \theta + c_i + \mu_j + e_{ijk}$$ with * $y_{ijk}$ the response in cluster $i$ at time $j$ for individual $k$ * $\mu_j$ the time trend at time $j$ * $T_{ij}$ the treatment status (0 = control, 1 = interventional treatment) * $\theta$ the treatment effect * $c_i$ a random cluster effect for cluster $i$ with $c_i \sim N(0,\tau^2)$ * $e_{ijk}$ a normal random error term with $e_{ijk}\sim N(0,\sigma^2)$ For power calculation, the standard deviation of random effects is assumed to be known. Let's define $\beta:=(\theta,\mu')'$ and $\omega_{ijk}:=c_i+e_{ijk}$. This leads to a compact and more general notation of the above equation: $$\begin{align} y_{ijk}&= X_{ij}\beta + \omega_{ijk}\\ \text{or, in matrix notation:} \qquad \\ y&=X\beta + \omega \end{align}$$ Where $X$ is the corresponding design matrix and $\omega\sim N(0,\Omega)$, where $\Omega$ is a compound-symmetry (syn. exchangeable) variance matrix defined by $\tau$ and $\sigma$. We are thus in a generalized least squares setting, so the variance of $\beta$ is $$ \text{Var}(\hat\beta) = {(X'\Omega^{-1}X)^{-1}}$$ We can then calculate the power of a z-test $$ \text{power} = \Phi\left(\frac{\theta_A-\theta_0}{\sqrt{\text{Var}(\hat \theta)}}- Z_{1-\frac{\alpha}{2}}\right) $$ where $\text{Var}(\hat \theta)$ is the diagonal element of $\text{Var}(\hat\beta)$ that corresponds to $\hat\theta$. There are further extensions implemented in this package with leads to the following extended model formula: $$y_{ijk}= T (\theta_{ij} + d_i) + c_i + \mu_j + t_{ij} + s_{ijk} + e_{ijk}$$ with * $d_i$ a random treatment effect * $c_i$ and $d_i$ jointly distributed with $\left(\begin{smallmatrix} \tau^2 & \rho\tau\eta \\ \rho\tau\eta & \eta^2\end{smallmatrix}\right)$ * $s_{ijk}$ a random subject specific effect * $t_{ij}$ a random time effect ## Covariance Structure Specifications `SteppedPower` is most flexible when covariance structure is defined by the standard deviations of the random effects directly. However, for users more comfortable with correlation-based specifications, the package provides two alternative approaches that convert correlation parameters to random effect variances. ### $\alpha_0$, $\alpha_1$, $\alpha_2$ A different approach to establish a covariance structure is to directly specify cluster cell correlations. Two approaches are considered in this package, with corresponding transformation functions `icc_to_RandEff()` and `alpha012_to_RandEff()`. One version proposed by \cite{Preisser2003integrated} and introduced to the context of stepped wedge designs in [@li2018sample] uses $\boldsymbol{\alpha}:=(\alpha_0, \alpha_1, \alpha_2)$ where $\alpha_0:=\operatorname{corr}({y_{ijk},y_{ijk'}})$ for $ k\neq k'$ defines the within-period correlation; $\alpha_1:=\operatorname{corr}({y_{ijk},y_{ij'k'}})$ for $j\neq j', \, k\neq k'$ defines the inter-period correlation and $\alpha_0:=\operatorname{corr}({y_{ijk},y_{ij'k}})$ for $j\neq j'$ defines the within-individual correlation. One receives an easily interpretable correlation matrix, albeit at the cost of some flexibility. We can translate $\boldsymbol{\alpha}$ into a representation with random effects, given a marginal variance $\sigma^2_{\text{marg}}$. $$ \begin{align*} \tau^2 &:= {\sigma^2_{\text{marg}} \alpha_1} \\ \gamma^2 &:= {\sigma^2_{\text{marg}} (\alpha_0-\alpha_1)} \\ \psi^2 &:= {\sigma^2_{\text{marg}} (\alpha_2-\alpha_1)} \\ \sigma^2_{\text{res}} &:= {\sigma^2_{\text{marg}} (1-\alpha_0 - \alpha_2 + \alpha_1)} \end{align*} $$ Note that $\boldsymbol{\alpha}$ as defined above cannot specify a random treatment effect. ### ICC, CAC and IAC Another version is explained in [@hooper2016sample]. It consists of intracluster correlation (**ICC**), cluster autocorrelation (**CAC**) and - for closed cohort settings - individual autocorrelation (**IAC**). Given a marginal variance, we can transform these into random effect variances with: $$ \begin{align} \tau^2 &:= \sigma^2_{\text{marg}} \cdot \text{ICC} \cdot \text{CAC} \\ \gamma^2 &:= \sigma^2_{\text{marg}} \cdot \text{ICC} \cdot (1 - \text{CAC}) \\ \psi^2 &:= \sigma^2_{\text{marg}} \cdot \text{IAC} \cdot (1 - \text{ICC})\\ \end{align} $$ ICC, CAC, and IAC cannot be directly specified in `glsPower` but can easily be transformed into $\alpha$. The corresponding $\alpha$ values are: $$ \begin{align} \alpha_0 &= \text{ICC} \\ \alpha_1 &= \text{ICC} \times \text{CAC} \\ \alpha_2 &= \text{IAC} \times (1 - \text{ICC}) + \text{ICC} \times \text{CAC} \\ \end{align} $$ Note that ICC, CAC and IAC as defined above cannot specify a random treatment effect. # Key functions ## `glsPower` For most users, the probably most important function is `glsPower`. It calls several auxiliary functions which will be shortly discussed here. `glsPower` is essentially just a flexible wrapper for the function `compute_glsPower`, which does the actual computation. ## `construct_`-functions `construct_DesMat` builds the design matrix which consists of the treatment status, usually built by`construct_trtMat` and the time adjustment, usually built by `construct_timeAdjust`. There is also the option to pass a user defined definition of the treatment status to `construct_DesMat`. If not specified, the number of timepoints is guessed as the fewest number of periods (timepoints) possible with the given design, i.e. two for cross-over designs or the number of waves plus one for stepped wedge designs. `construct_CovMat` builds the covariance matrix (explicitly). It uses `construct_CovBlk` to construct the blocks for each cluster which are then combined to a block diagonal matrix. # Features ## Plotting The `plot.glsPower` method offers up to four visualisations (selectable by `which=`). 1. Influence of cluster-period cells 2. Information content of cluster-period cells, 3. Treatment matrix $T$ 4. Covariance matrix By default, only the first plot is returned. The information content is also plotted if it the object to be plotted contains the corresponding matrix (which is usually the case). It is constructed by exploiting the approximation to a weighted least squares setting. Therefore, the estimator $\hat \beta$ is a linear function of the data $y$ $$\hat\beta = \underbrace{(X'\Omega^{-1}X)^{-1}(X'\Omega^{-1})}_{=:\text{H}}\cdot y$$ with $X$ the design matrix and $\Omega$ the covariance matrix as above. The matrix $H$ gives an impression of the importance of clusters and time periods with regard to the estimated coefficients $\hat\beta$. The first row of $H$ corresponds to the coefficient of the treatment status, i.e. the treatment effect. The `plot.glsPower` method visualises this first row of $H$ as a matrix where rows and columns correspond to clusters and time periods, respectively. ```{r} glsPwr <- glsPower(Cl=c(3,2,3), mu0=0, mu1=1, sigma=1, tau=.5, verbose=2) ``` ```{r, echo=FALSE, fig.height=8, fig.cap=fig$cap("Influence_Plot_1","Treatment allocation plot (top). Influence of cluster-period cells (center) and information content (bottom) of a stepped wedge design with 8 clusters in 3 sequences")} tmpplt <- plot(glsPwr,which=1:3, marginal_plots = FALSE, show_colorbar = FALSE) subplot(tmpplt[[3]],tmpplt[[1]],tmpplt[[2]], titleY=TRUE, nrows=3, margin=c(0,0,.03,.03) ) ``` The information content, as described in [@kasza2019information], looks like this: ```{r, fig.cap=fig$cap("Info_Plot_1","Information content of cluster-period cells of a stepped wedge design with 8 clusters in 3 sequences.")} plot(glsPwr,which=2, show_colorbar=FALSE)$IMplot ``` Furthermore, to give a rough comparison of importance between clusters (or between time periods), the sum of absolute weights per row (or per column) is also shown. >CAVE: The influence plot (above) yields out-of-bag estimates for the influence of observations on $\hat\theta$, but not for $\text{Var}(\hat\theta)$. The information content (below) visualises the relative change in $\text{Var}(\hat\theta)$ when one particular cluster period is omitted. The relationship between the two if analysed in more detail in [@mildenberger2023influence] ## Find Sample Size for given Power When the argument `power` is passed to `glsPower`, the sample size needed is calculated, under the assumption of equally sized clusters and periods. ```{r} glsPower(Cl=c(3,3,3), mu0=0, mu1=.2, sigma=1, tau=0, power=.8) ``` So in this setting, you would need $50$ individuals per period in each cluster to achieve a target power of $80\%$ ## Unequal Cluster Sizes One of the advantages of the explicit approach to calculate power is an increase in flexibility. The user can specifiy different cluster sizes - which can even vary over time using the argument `N`. `N` can be: * a scalar, if all clusters have the same assumed size, which is also constant over time * a vector, if the size differs between clusters but is assumed to be constant over time * a matrix where each row corresponds to either a cluster or a wave of clusters and each column corresponds to a timepoint ```{r} mod4 <- glsPower(Cl=c(1,1,1), mu0=0, mu1=1, N=c(1,3,10), sigma=1, tau=.5, verbose=2) plot(mod4, which=1, show_colorbar=FALSE)[[1]] ``` ```{r, echo=FALSE} rm(mod4) ``` ## Incomplete Stepped Wedge Designs There are two main types of incomplete designs considered in this package; Incomplete designs with unobserved transition periods (on the right) are defined with the `trtDelay` argument. Designs with unobserved *"edge periods"* are defined with the `incomplete` argument. This is described in more detail in the [Incomplete Designs](Incomplete_Designs.html) vignette. ```{r} Incomp1 <- plot(construct_DesMat(Cl=c(1,1,1,1,0), incomplete = 2)) Incomp2 <- plot(construct_DesMat(Cl=c(1,1,1,1,0), trtDelay = c(NA))) plotly::subplot(Incomp1, Incomp2, nrows=1, titleX=TRUE, titleY=TRUE, margin=0.05) ``` ## Autocorrelated random effects In longitudinal studies, it can be sensible to assume that correlation within clusters decreases with increasing time lag. The argument `AR` enables the user to specify a AR-1 correlation. `AR` must be any value between `0` and `1`. The former corresponds to i.i.d. observations, the latter to the usual compound symmetry covariance type. Optionally, you can pass a vector of up to length three to `AR`. Then, the first element applies to the cluster intercept, the second to the treatment effect (i.e. slope) and the third to the subject specific intercept. This is especially useful for open cohort designs (see below). An example of a stepped wedge design with 3 clusters in 3 waves, once with medium autocorrelation (`AR=0.6`) and once with high autocorrelation (`AR=0.95`): ```{r} plt1 <- glsPower(Cl=c(1,1,1), mu0=0, mu1=1, sigma=1, N=1, tau=1, AR=1, verbose=2) |> plot( which=4, show_colorbar = FALSE) plt2 <- glsPower(Cl=c(1,1,1), mu0=0, mu1=1, sigma=1, N=1, tau=1, AR=.6, verbose=2) |> plot( which=4, show_colorbar = FALSE) plotly::subplot(plt1[[1]], plt2[[1]], nrows=1 , titleX=TRUE, titleY= TRUE) ``` ## Adjustment for Secular Trends The most usual method for the modelling of potential secular trends is to take time period as a factor into the analysis model [@hussey2007design; @hemming2015stepped; @hemming2020reflection]. For diagnostic purposes (or for bold users), some other adjustment options are implemented. ```{r} TimeAdj1 <- glsPower(Cl=rep(2,4), mu0=0, mu1=1, sigma=1, tau=0, timeAdjust="linear", verbose=2) TimeAdj2 <- glsPower(Cl=rep(2,4), mu0=0, mu1=1, sigma=1, tau=0, timeAdjust="factor", verbose=2) ``` Design matrix of the first cluster with linear adjustment for secular trend: ```{r, echo=FALSE} knitr::kable(head(TimeAdj1$DesignMatrix$dsnmatrix, 5)) ``` Design matrix of the first cluster with categorical adjustment for secular trend: ```{r, echo=FALSE} knitr::kable(head(TimeAdj2$DesignMatrix$dsnmatrix, 5)) ``` ## Non-Gaussian outcomes `SteppedPower` can also handle binomial and count (Poisson) outcomes, both with an identity link (see the [Binomial and Count Outcomes](Binomial_and_Count_Outcomes.html) vignette). # Use Cases ## Cross-sectional Parallel Group Design This might be a proof of concept rather than an example with practical relevance, but let's try to compare the mean in two groups. For two groups of 10 observations each, the power of a Z-test can be calculated as follows: ```{r} glsPower(Cl=c(10,10), mu0=0,mu1=1.2,sigma=1, tau=0, N=1, dsntype="parallel", timepoints=1)$power ## the same: glsPower(Cl=c(1,1), mu0=0,mu1=1.2, sigma=1, tau=0, N=10, dsntype="parallel", timepoints=1)$power ``` ```{r} pwr::pwr.norm.test(.6,n=20)$power ``` >A quick note on t-tests: It is much more challenging to use `SteppedPower` to reproduce settings in which the variance is assumed to be unknown, most prominently the well known t-test. In this package, you find implemented some (experimental) heuristics for guessing the denominator degrees of freedom, but they yield rather scaled Wald tests than t-tests. The main difference is that the distribution under the alternative is assumed to be symmetric, whereas the t-test assumes a non-central (hence skewed) t-distribution. ## Longitudinal Parallel Design ```{r} glsPower(Cl=c(10,10),timepoints=5,mu0=0,mu1=.25, sigma=.5,tau=.2,dsntype="parallel") ``` ## Stepped Wedge designs with empty sequences (i.e. empty waves) Periods in which no cluster switches to the intervention are specified by inserting zeros into the `Cl` argument, i.e. `Cl=c(4,4,4,0)`. ```{r, warning=FALSE} mod1 <- glsPower(Cl=c(1,1,1,0), mu0=0, mu1=1, sigma=0.4, tau=0, verbose=2) ``` The treatment matrix is then stored under `mod1$DesignMatrix$trtMat`: ```{r, echo=FALSE} knitr::kable(mod1$DesignMatrix$trtMat) ``` ## Closed cohort SWD In a closed cohort the patients are observed over the whole study period. The same correlation structure arises in cross sectional stepped wedge designs if subclusters exist (such as wards within clinics). The argument `psi` denotes the standard deviation of a random subject (or subcluster) specific intercept. The power is calculated on aggregated cluster means: ```{r} Closed1 <- glsPower(mu0=0, mu1=5, Cl=rep(3,3), sigma=5, tau=1, psi=3, N=3, verbose=2) Closed1 ``` With `INDIV_LVL=TRUE`, the calculation is done on the individual level. This yields the same results but is far more computationally expensive and is mainly intended for diagnostic purposes. ```{r} Closed2 <- glsPower(mu0=0, mu1=5, Cl=rep(3,3), sigma=5, tau=1, psi=3, N=3, verbose=2, INDIV_LVL = TRUE) Closed2 plot(Closed2, annotations=FALSE, show_colorbar=FALSE)$WgtPlot ``` ```{r} Closed1$power - Closed2$power ``` ## Open cohort designs The `AR` argument mentioned above specifies the autocorrelation of random effects. It offers a convenient way to model open cohort designs. The third element of `AR` can be seen as the estimated probability that a subject included in period $j$ is also included in period $j+1$, instead of being replaced by a new subject. Expanding on the closed cohort example above, one could assume that subjects have a 75% chance to reappear in the next study period. ```{r} Open1 <- glsPower(mu0=0, mu1=5, Cl=rep(3,3), sigma=5, tau=1, psi=3, AR=c(1,1,.75), N=3) Closed1$power Open1$power ``` So this would result in a power loss of roughly `r round( Closed1$power - Open1$power,3)*100`% compared to a closed cohort design in this case. ### Covariance structure for open cohort designs This proposed covariance structure is then a mixture of exchangeable (on cluster level) and autoregressive (on subject level). Let's have a look at a toy example with three clusters, each consisting of three subjects. The probability that an individual reappears in two consecutive periods is estimated to be 60%. The covariance matrix (on subject level) could be visualised as follows: ```{r, fig.height=6} Open2Indiv <- glsPower(mu0=0, mu1=10, Cl=c(1,1,1,0), sigma=1, tau=5, psi=10, AR=c(1,1,.60), N=3, verbose=2, INDIV_LVL=TRUE) plot(Open2Indiv, which=4, show_colorbar=FALSE)$CMplot ``` Note that you can zoom to get a better look at the structure. The autoregressive structure on the subject level in the small boxes along the main diagonal and the block exchangeable structure on cluster level becomes evident. ## Reproducing common closed formulae There exist some formulae that do not explicitly construct design and covariance matrices, most notably [@kasza2020sample] and [@li2020design]. Both include the one presented in [@hussey2007design] as a special case. These formulae are also implemented in `SteppedPower`. As a showcase, here is an example that is loosely based on the example in [@hussey2007design]: ```{r} trtMat <- construct_DesMat(c(6,6,6,6))$trtMat mu0 <- 0.05 ; mu1 <- 0.032 ; N <- 100 tau <- .025 ; sigma <- sqrt(.041*.959) gamma <- 0.01 ; psi <- .1 ; chi <- .5 ; AR <- .5 ``` ### Closed formula for proportional decay structure `VarClosed_Li` computes the treatment variance for stepped wedge designs with a autoregressive (syn. proportional decay) structure. It can be used to compute a variance for the treatment effect and thus the power for the setting in question: ```{r} tmp <- VarClosed_Li(trtMat, tau=tau, psi=psi, N=N, AR=AR) tTestPwr(mu0-mu1, se=sqrt(tmp), df=Inf) ``` Explicit calculation yields the same: ```{r} a <- SteppedPower::glsPower(Cl=rep(6,4), mu0=mu0, mu1=mu1, AR=AR, sigma=0, tau=tau, N=N, psi=psi, verbose=1, INDIV_LVL = TRUE) a ``` ### Closed formula for open cohort designs Kasza et al. offer an extension to open cohort designs by the use of an attrition or churn rate `chi` [@kasza2020sample]. It can be understood as the estimated probability that a subject included in period $j$ is also included in period $j'$ for $j\ne j'$. Note that this differs from the approach mentioned above, as it results in a mixture of exchangeable covariance matrices. Since it differs from the way `SteppedPower` intents to model open cohort designs, it requires a bit of tinkering to reproduce the results of the closed formula with this package. It can be done with the help of the random time effect (`gamma`). ```{r} tmp <- VarClosed_Kasza(trtMat, sigma=sigma, tau=tau, gamma=gamma, psi=psi, N=N, chi=0) tTestPwr(mu0-mu1, se=sqrt(tmp), df = Inf) glsPower(Cl = rep(6,4), N=N, mu0=mu0, mu1=mu1, verbose=0, sigma=sigma, tau=tau, gamma=gamma, psi=psi) tmp <- VarClosed_Kasza(trtMat, sigma=sigma, tau=tau, gamma=gamma, psi=psi, N=N, chi=1) tTestPwr(mu0-mu1, sqrt(tmp), df = Inf) glsPower(Cl = rep(6,4), N=N, mu0=mu0, mu1=mu1, verbose=0, sigma=sigma, tau=tau, gamma=sqrt(gamma^2+psi^2/N), psi=0) tmp <- VarClosed_Kasza(trtMat, sigma=sigma, tau=tau, gamma=gamma, psi=psi, N=N, chi=chi) tTestPwr(mu0-mu1, sqrt(tmp), df = Inf) glsPower(Cl = rep(6,4), N=N, mu0=mu0, mu1=mu1, verbose=0, sigma=sigma, tau=tau, gamma=sqrt(gamma^2+chi*psi^2/N), psi=sqrt(1-chi)*psi) ``` # Session Info {-} ```{r, echo=FALSE} print(sessionInfo(),locale=FALSE) ``` # References {-} .