swPlot: Plot of Mean Response/Outcome for Stepped Wedge Cluster...
In swCRTdesign: Stepped Wedge Cluster Randomized Trial (SW CRT) Design

swPlot

R Documentation

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

Description

swPlot returns plot of the mean response versus time based on waves and/or clusters from a SW CRT.

Usage

swPlot(response.var, tx.var, time.var, cluster.var, data, imputeNA = FALSE, 
choose.mfrow=NULL, by.wave=TRUE, combined.plot=TRUE, choose.xlab="Time", choose.main=NULL,
choose.pch=NULL, choose.cex=1, choose.tx.col=NULL, choose.tx.lty = c(2,1),
choose.ncol=2, xlim=NULL, ylim=NULL, choose.tx.pos="topright", choose.legend.pos="right")

Arguments

`response.var`	numeric(vector): Response (Outcome) variable.
`tx.var`	numeric(vector): Treatment (Predictor of Interest) variable. Typically, 0=control, 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 observation is from.
`data`	An optional data frame containing (at least) the response, treatment (tx), time, and cluster variables.
`imputeNA`	logical (scalar): If TRUE, then swPlot (via a call to swSummary) attempts to impute the intervention status for cluster-periods with 0 non-missing observations (see Details). If FALSE, cluster-periods with 0 non-missing observations are assigned NA. Note that changing imputeNA from FALSE to TRUE may also change the inferred number of unique waves. Default is FALSE.
`choose.mfrow`	numeric (vector): Choose `mfrow` for plot. If `NULL`, `mfrow` is automatically assigned based on the plot created. The default is `NULL`.
`by.wave`	logical: If `TRUE`, plot mean response according to each wave. If `FALSE`, plot mean response according to each cluster. The default is `TRUE`.
`combined.plot`	logical: If `TRUE`, plot mean response on same plot (what is plotted depends on `by.wave`). If `FALSE`, plot mean response on separate plots for each wave (what is plotted depends on `by.wave`). The default is `TRUE`.
`choose.xlab`	Choose `xlab` for plot. The default is "Time".
`choose.main`	Choose `main` for plot. If `NULL`, `main` is chosen for the user; which is highly recommended. The default is `NULL`.
`choose.pch`	Choose `pch` for plot. If `NULL`, `pch` are chosen for the user; which is highly recommended. The default is `NULL`.
`choose.cex`	Choose `cex` for `choose.pch`. Standard `cex` option in `points()` applies. The default is `1`.
`choose.tx.col`	Choose colors for different treatment options. Vector of two colors, corresponding to control and treatment groups, respectively. If `NULL`, colors are chosen for the unique treatment options in the data supplied. The default is `NULL`.
`choose.tx.lty`	Choose line types for different treatment options. Vector of two numbers for `lty`, corresponding to control and treatment groups, respectively. The default is `c(2,1)`.
`choose.ncol`	Choose number of columns for non-treatment legend. Standard `ncol` option in `legend()` applies. The default is `2`.
`xlim`, `ylim`	Vectors of length 2 giving x and y axis limits on plot. If NULL, minimum and maximum of summary time and response variables are used, respectively.
`choose.tx.pos`	Choose where to place treatment colors "legend". Standard `legend()` positions apply. The default is "topright"; if this covers points, it should be changed.
`choose.legend.pos`	Choose where to place the non-treatment legend. Standard `legend()` positions apply. The default is "right"; if this covers points, it should be changed. If "mouseclick", user specifies location with mouse/trackpad by clicking on the plot that appears. Specify `NULL` to remove legend. When by.wave=FALSE, no legend is plotted

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.

Returns a plot of the mean response versus time with a combination of by wave (TRUE / FALSE) and combined plot (TRUE / FALSE) from a SW CRT. See discussion of number of waves in help file for swSummary.

Author(s)

James P Hughes, Navneet R Hakhu, and Emily C Voldal

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 (Mean Response vs Time, by.wave=TRUE, combined.plot=TRUE)
swPlot(response.var, tx.var, time.var, cluster.var, data.Ex1, by.wave=TRUE,
combined.plot=TRUE, choose.tx.pos="bottomright", choose.legend.pos="bottom")

# Example 2 (Mean Response vs Time, by.wave=TRUE, combined.plot=FALSE)
swPlot(response.var, tx.var, time.var, cluster.var, data.Ex1, by.wave=TRUE,
combined.plot=FALSE, choose.tx.pos="bottomright", choose.legend.pos="bottom")

# Example 3 (Mean Response vs Time, by.wave=FALSE, combined.plot=TRUE)
swPlot(response.var, tx.var, time.var, cluster.var, data.Ex1, by.wave=FALSE,
combined.plot=TRUE, ylim=c(0,0.6), choose.tx.pos="bottomright", choose.legend.pos="topleft")

# Example 4 (Mean Response vs Time, by.wave=FALSE, combined.plot=FALSE)
swPlot(response.var, tx.var, time.var, cluster.var, data.Ex1, by.wave=FALSE,
combined.plot=FALSE, choose.tx.pos="bottomright", choose.legend.pos="bottom")

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