swSim: Simulating individual-level data for specified study design...

Description Usage Arguments Value Author(s) References Examples

Description

swSim returns individual-level data set of a SW CRT study design for the specified number of clusters per wave, fractional treatment effect at each time after crossing over from control, time (standard SW CRT time computed; extending trial beyond standard time needs to be specified by the user), family (and link function), number of individuals per cluster per wave, mean in control arm, mean in treatment arm, time effect, pooled standard deviation for both arms, standard deviation of random intercepts, standard deviation of random treatment effects, correlation between random intercepts and random treatment effects, standard deviation of random time effects, time point label, and option to simulate data with time on treatment lag. Alternatively, for a Gaussian family standard deviations of random effects may be specified using ICC and CAC; see swPwr details.

Usage

1
2
swSim(design, family, log.gaussian = FALSE, n, mu0, mu1, time.effect, sigma, tau, eta,
rho, gamma, icc, cac, time.lab = NULL, retTimeOnTx = FALSE, silent = FALSE)

Arguments

design

list: A stepped wedge design object, typically from swDsn, that includes at least the following components: ## swDsn, clusters, n.clusters, total.time

family

character: Used in typical way. However, only Gaussian, Binomial, and Poisson families accepted. Also, only identity, logit, and log links accepted. Logit link is only available for Binomial family, and log link is only available for Binomial and Poisson. Currently, 'Binomial' implies Bernoulli. ***NOTE: It is the users responsibility to make sure specified parameters (mu0, mu1, time.effect, tau, eta, rho, gamma) are ALL on SAME scale as specified link function; see example.***

log.gaussian

character: When TRUE with a Gaussian family, simulates data whose log follows a Gaussian distribution; all parameters (mu0, mu1, time.effect, variance parameters) refer to the log scale. Default is FALSE.

n

integer (scalar, vector, or matrix): Number of observations: (scalar) for all clusters and all time points; (vector) for each cluster at all time points; and (matrix) for each cluster at each time point, where rows correspond to clusters and columns correspond to time. n can also be used to specify a design with transition periods were no data is collected; see swPwr.

mu0

numeric (scalar): Mean outcome in the control group on the appropriate scale.

mu1

numeric (scalar): Mean outcome in the treatment group on the appropriate scale.

time.effect

integer (scalar or vector): Time effect at each time point on the appropriate scale (added to mean at each time).

sigma

numeric (scalar): Pooled treatment and control arm standard deviation on the appropriate scale. Ignored if family != Gaussian.

tau

numeric (scalar): Standard deviation of random intercepts on the appropriate scale.

eta

numeric (scalar): Standard deviation of random treatment effects on the appropriate scale.

rho

numeric (scalar): Correlation between random intercepts and random treatment effects on the appropriate scale.

gamma

numeric (scalar): Standard deviation of random time effects on the appropriate scale.

icc

numeric (scalar): Within-period intra-cluster correlation on the appropriate scale. Can be used with CAC instead of tau, eta, rho, and gamma when the outcome is Gaussian.

cac

numeric (scalar): Cluster auto-correlation on the appropriate scale. Can be used with ICC instead of tau, eta, rho, and gamma when the outcome is Gaussian.

time.lab

character (vector): Labeling for time points when output is display; choice of labeling does not affect results.

retTimeOnTx

logical: If TRUE, outputs time on treatment variable (timeOnTx.var) in addition to the usual treatment variable (tx.var). To simulate data with a time on treatment lag effect, the fractional treatment effect can be specified through design. The default is FALSE.

silent

logical: if TRUE, hides reminder about order of entries in n when n is not a scalar. Default value is FALSE.

Value

numeric (data frame): Returns the following (individual-level) variables corresponding to the specified SW CRT design:

$response.var

numeric (vector): Response variable based on specified SW CRT design of interest (including family and link function) for each observation in the data frame/set.

$tx.var

numeric (vector): Predictor of interest. (Fractional) treatment effect corresponding to 0=control, 1=treatment, and value between 0 and 1 corresponding to treatment arm with fractional treatment effect (for each observation in the data frame/set).

$timeOnTx.var

numeric (vector): Predictor of interest when interested in time on treatment lag effect. Total time spent on treatment for each observation in the data frame/set, with 0=control, 1=first time period on treatment, 2=second time period on treatment, etc.

$time.var

numeric (vector): Time point id for each observation in the data frame/set.

$cluster.var

numeric (vector): Grouping variable. Cluster id for each observation in the data frame/set.

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
library(swCRTdesign)
# Example 1 [ n = scalar; can be vector (for different n for each cluster,
# n=rep(120,22)) or matrix (different n for each cluster at each time point,
# n=matrix(120,22,5)) ]

# generate SW data (fractional treatment effect)
design <- swDsn(clusters=c(6,6,6,4), tx.effect.frac=c(0.8,0.9,1.0),
extra.time=0, all.ctl.time0=TRUE)
set.seed(5)
swGenData.nScalar <- swSim( design,
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, eta=0,
rho=0, gamma=0, time.lab=seq(0,12,3), retTimeOnTx=FALSE)

# summarize SW data by wave
swSummary(response.var, tx.var, time.var, cluster.var, swGenData.nScalar,
type="mean", digits=3)$response.wave

swSummary(response.var, tx.var, time.var, cluster.var, swGenData.nScalar,
type="mean", digits=3)$swDsn

swCRTdesign documentation built on Oct. 30, 2019, 11:24 a.m.