swSummary {swCRTdesign}

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", 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): 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.)

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

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.

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