swSummary: Summary of Response/Outcome for Stepped Wedge Cluster...

In swCRTdesign: Stepped Wedge Cluster Randomized Trial (SW CRT) Design

Summary of Response/Outcome for Stepped Wedge Cluster Randomized Trial (SW CRT)

Description

swSummary returns the mean, sum, and number of non-missing values for the response/outcome variable of interest for each cluster at each time point from a SW CRT.

Usage

swSummary(response.var, tx.var, time.var, cluster.var, data, 
type="mean", imputeNA=FALSE, digits=16, fcn.Call=FALSE)

Arguments

response.var	numeric(vector): Response (Outcome) variable.
tx.var	numeric(vector): Treatment (Predictor of Interest) variable. Typically, 0=placebo, 1=intervention, and values greater than 1 correspond to other treatment levels.
time.var	integer(vector): Time (points) variable, corresponding to the time points when data were collected during the SW CRT.
cluster.var	integer(vector) or character(vector): Cluster (identification) variable, corresponding to the cluster where an individual is from.
data	An optional data frame containing (at least) the response, treatment (tx), time, and cluster variables.
type	character (scalar): Specify which summary measure is of interest from "mean", "sum", and "n". (Note: The default returns "mean" as the summary measure of response. Note that all summary measures may not be scientifically relevant in every situation.)
imputeNA	logical (scalar): If TRUE, then swSummary attempts to impute the intervention status in $swDsn and $swDsn.unique.clusters for cluster-periods with 0 non-missing observations (see Details). If FALSE, cluster-periods with 0 non-missing observations are assigned NA in $swDsn and $swDsn.unique.clusters. Note that changing imputeNA from FALSE to TRUE may also change the inferred number of unique waves ($n.waves and $swDsn.waves). Default is FALSE.
digits	integer (scalar): Number of places right of the decimal. The default value is 16.
fcn.Call	logical: Only TRUE when calling swSummary from within swPlot. The default is FALSE.

Details

If imputeNA is set to TRUE then any NA in the design matrix is set to 1 (intervention) if the NA follows a 1 in the same cluster; is set to 0 (control) if the NA precedes a 0 in the same cluster; and is otherwise left as NA.

swSummary returns a list containing a matrix of dimension length(unique(data$cluster)) by length( unique(data$time)) that summarizes data$response for specified type. Either the mean, sum, or the number of non-missing data$response values may be requested using type. dimnames of the matrix correspond to the unique values of cluster and time. Note that the stepping pattern in the data may be obtained by specifying the treatment variable name as the response and type = "mean".

Value

numeric (list): swSummary returns a list containing the following

type	One of user-specified options "mean", "sum", or "n".
swDsn	The SW design.
swDsn.unique.clusters	The unique clusters (i.e., rows) SW design.
swDsn.waves	Wave for each cluster.
n.waves	Number of waves. Note that this is usually, but not necessarily, the same as data$n.waves. See example 2.
clusters	Clusters per wave.
n.clusters	Total number of clusters.
time.at.each.wave	Time at each wave.
total.time	Total time points.
response.cluster	numeric (matrix): Response variable summarized according to type for all clusters, with dimension length(data$cluster) by length(unique(data$time)).
response.wave	numeric (matrix): Response variable summarized according to type, for all waves (all clusters of a particular wave are combined), with dimension length( unique(data$cluster)) by length(unique(data$time)).

Author(s)

James P Hughes and Navneet R Hakhu

References

Hussey MA, Hughes JP. Design and analysis of stepped wedge cluster randomized trials. Contemporary Clinical Trials 2007;28:182-191.

Examples

library(swCRTdesign)
# Example 1 
# Generate binary response with 5 clusters, 4 time points
data.Ex1 <- swSim(swDsn(c(2,2,1)),family=binomial(link="identity"), n=120,
                     mu0=0.25, mu1=0.30,time.effect=0, tau=0.05, gamma=.01)

## Example 1 (type="mean", by cluster and by wave)
swSummary.Ex1.mean <- swSummary(response.var, tx.var, time.var, cluster.var, 
data=data.Ex1, type="mean", digits=3)

swSummary.Ex1.mean$response.cluster

swSummary.Ex1.mean$response.wave

# Example 1 (type="sum", by cluster and by wave)
swSummary.Ex1.sum <- swSummary(response.var, tx.var, time.var, cluster.var, 
data=data.Ex1, type="sum")

swSummary.Ex1.sum$response.cluster

swSummary.Ex1.sum$response.wave

## Example 1 (type="n", by cluster and by wave)
swSummary.Ex1.n <- swSummary(response.var, tx.var, time.var, cluster.var, 
data=data.Ex1, type="n")

swSummary.Ex1.n$response.cluster

swSummary.Ex1.n$response.wave

## Example 2
design2 <- swDsn(clusters=c(6,6,6,6)) 
# design2$n.waves says 4 waves
nmat2 = rbind(matrix(rep(c(120,120,120,120,120),6),6,5,byrow=TRUE),
              matrix(rep(c(120,120,120,120,120),3),3,5,byrow=TRUE),
              matrix(rep(c(0,120,120,120,120),3),3,5,byrow=TRUE),
              matrix(rep(c(0,0,120,120,120),6),6,5,byrow=TRUE),
              matrix(rep(c(0,0,0,120,120),6),6,5,byrow=TRUE))
swGenData2 <- swSim( design2,family=binomial(link="logit"), n=nmat2,
                     mu0=log(0.1/0.9), mu1=log(0.9) + log(0.1/0.9),
                     time.effect=0, tau=0.2, time.lab=seq(0,12,3))
swSummary(response.var, tx.var, time.var, cluster.var, swGenData2,
          type="mean", digits=3)
# This summary create 5 waves
#
# The following is equivalent to above
design2b <- swDsn(c(6,3,3,6,6),
                   swBlk=matrix(c(0,1,1,1,1,
                                  0,0,1,1,1,
                                  NA,0,1,1,1,
                                  NA,NA,0,1,1,
                                  NA,NA,NA,0,1),5,5,byrow=TRUE)) 
# design2b$n.waves says 5 waves
swGenData2b <- swSim(design2b,family=binomial(link="logit"), n=120,
                      mu0=log(0.1/0.9), mu1=log(0.9) + log(0.1/0.9),
                      time.effect=0, tau=0.2, time.lab=seq(0,12,3))
swSummary(response.var, tx.var, time.var, cluster.var, swGenData2b,
          type="mean", digits=3)
# This summary create 5 waves          

swCRTdesign documentation built on Sept. 9, 2025, 5:55 p.m.