dpgrowmm: Bayesian semiparametric growth curve models with employment...

In growcurves: Bayesian Semi and Nonparametric Growth Curve Models that Additionally Include Multiple Membership Random Effects

Description

Employs a Dirichlet Process (DP) prior on the set of by-subject random effect parameters under repeated waves of measurements to allow the number of random effect parameters specified per subject, q, to be equal to the number of measurement waves, T. Random effects are grouped by subject and all q parameters receive the DP prior. An additional set of random effects are included that utilize a different grouping factor; e.g. treatment(s) exposure or dosage. These additional random effects are mapped back to subjects through a multiple membership weight matrix.

Usage

dpgrowmm(y, subject, trt, time, n.random, n.fix_degree, formula, random.only,
  data, Omega, group, subj.aff, W.subj.aff, multi, n.iter, n.burn, n.thin,
  strength.mm, shape.dp, rate.dp, plot.out, option)

Arguments

y	A univariate continuous response, specified as an N x 1 matrix or vector, where N captures the number of subject-time cases (repeated subject measures). Data may reflect unequal number of measures per subject. Missing occasions are left out as no NA values are allowed.
subject	The objects on which repeated measures are conducted that serves as the random effects grouping factor. Input as an N x 1 matrix or vector of subject-measure cases in either integer or character format; e.g. (1,1,1,2,2,3,3,3,...,n,n,n), where n is the total number of subjects.
trt	An integer or character matrix/vector of length N (number of cases) indicating treatment group assignments for each case. May also be input as length P vector, where P is the number of unique subjects, indicating subject group assignment. Multiple treatment groups are allowed and if the vector is entered as numeric, e.g. (0,1,2,3,..), the lowest numbered group is taken as baseline (captured by global fixed effects). If entered in character format, the first treatment entry is taken as baseline. If the are no treatment (vs. control) groups, then this vector may be excluded (set to NULL).
time	A univariate vector of length N, capturing the time points associated to each by-subject measure. Mav leave blank if only one time point (no repeated measures).
n.random	The desired number of time-indexed subject random effect terms, q. Since a DP prior is used on subject effects, may be set equal to the number of measurement waves, T. The y, trt, time vectors will together be used to create both fixed and random effect design matrices. The random effects matrix will be of the the form, (1, time, ... , time^(n.random - 1)) (grouped, by subject). This formulation is a growth curve model that allows assessment of by-treatment effects and by-client growth curves.
n.fix_degree	The desired polynomial order in time to use for generating time-based fix effects. The fixed effects matrix will be constructed as, (time, ..., time^(n.fix_degree), trt_1,time*trt_1, ... ,time^(n.fix_degree)*trt_l, trt_L,..., time^(n.fix_degree)*trt_L). This formulation is a growth curve model that allows assessment of by-treatment effects and by-client growth curves. If is.null(n.fix_degree) | n.fix_degree == 0 & is.null(trt) time-by-treatment fixed effects and growth curves are not generated.
formula	Nuisance fixed and random effects may be entered in formula with the following format, y ~ x_1 + x_2*x_3 | z_1*z_2 as an object of class formula. The bar, |, separates fixed and random effects. If it is only desired to enter either fixed or random effects, but not both then the | may be omitted. Note: the nuisance random effects are assumed to be grouped by subject. The fixed and random effects values may change with each repeated measure; however, within subject growth curves will keep constant z and x values between measurement waves. It is possible to bypass the growth curve construction by leaving y, trt, time, n.random, n.fix_degree blank and entering only formula, instead. The model output plots, will, however exclude growth curves in that event. If a formula is input (which requires response, y) then the separate entry of y may be omitted. If the parameter y is input, it will be over-written by that from formula.
random.only	A Boolean variable indicating whether the input formula contains random (for fixed) effects in the case that only one set are entered. If excluded and formula is entered without a |, random.only defaults to FALSE.
data	a data.frame containing the variables with names as specified in formula, including the response, y.
Omega	An S x S numerical matrix object to encode the CAR adjacency matrix for random effects mapped through multiple membership, where S is the number of effects mapped to subjects through the multiple membership construction. This input applies only to option = "mmcar".
group	A numeric or character vector of length S, providing group identifiers for each of S multiple membership effects (e.g. (1,1,1,2,2,...). If excluded, it is assumed there is a single group.
subj.aff	A n.aff x 1 vector subset of subject composed with unique subject identifiers that are linked to the multiple membership effects; e.g. one or more treatment cohorts. If all subjects are to receive the mapping of multiple membership effects, subj.aff may be left blank.
W.subj.aff	An n.aff x S numeric matrix that maps a set of random effects to affected subjects, where P.aff is the length of the unique subjects to whom the multiple membership random effects applies. It is assumed that the row order is the same as the order of subj.aff (or unique(subject) if subj.aff is not input). If W.subj.aff is a multiple membership weight matrix, then the rows will sum to 1. The form and therefore, interpretation of output is dependent on form of input; for example, the rows of W.subj.aff may include indicators for whether each of S treatment dosages are linked to a given subject.
multi	A boolean scalar input that when set to TRUE indicates the each of the S MM effects is multivariate. Leave blank if univariate multiple membership effects are desired. It is assumed that the associated design matrix is equal to the number of time-indexed random effects. For example, the time-indexed (non-nuisance) random effects design matrix, Z = (1,time,time^n.random-1) is also used to compose an inner product with each row of the N x n.random MM product, W * U, where W is case-expanded MM design matrix and U is the S x n.random set of multivariate MM effects.
n.iter	Total number of MCMC iterations.
n.burn	Number of MCMC iterations to discard. dpgrow will return (n.iter - n.burn) posterior samples.
n.thin	Gap between successive sampling iterations to save.
strength.mm	Sets both the shape and rate parameter for a tau_{gamma} ~ G(strength.mm,strength.mm) prior on the precision parameter of either a CAR (gamma ~ CAR(tau_gamma)) or independent (gamma ~ N(0,tau^(-1)I_S) prior on the set of S multiple membership effects.
shape.dp	Shape parameter under a c ~ G(shape.dp, 1) prior on the concentration parameter of the DP (prior on the set of random effects parameters, b_1, ..., b_n ~ DP(c,G_0) where n is the total number of subjects.
rate.dp	Rate parameter under a c ~ G(shape.dp, rate.dp) prior on the concentration parameter of the DP.
plot.out	A boolean variable indicating whether user wants to return plots with output results. Defaults to TRUE.
option	Modeling option, of which there are three: 1. mmcar places a CAR prior on the set of multiple membership effects; 2. mmi places the usual independent Gaussian priors on the set of multiple membership effects. 3. mmigrp employs a set of independent Gaussian priors, but with a common mean parameter for each sub-group of multiple membership effects sharing a common group identifier. (e.g. treatment groups that disjointly divide therapy sessions from Savitsky and Paddock (2011))

Value

S3 dpgrowmm object, for which many methods are available to return and view results. Generic functions applied to an object, res of class dpgrow, includes:

summary(res)	returns call, the function call made to dpgrowmm and summary.results, which contains a list of objects that include 95% credible intervals for each set of sampled parameters, specified as (2.5%, mean, 97.5%, including fixed and random effects. Also contains model fit statistics, including DIC (and associated Dbar, Dhat, pD, pV), as well as the log pseudo marginal likelihood (LPML), a leave-one-out fit statistic. Note that DIC is constructed as DIC3 (see Celeaux et. al. 2006), where the conditional likehihood evaluated at the posterior mode is replaced by the marginal predictive density. Lastly, the random and fixed effects design matrices, X, Z, are returned that include both the user input nuisance covariates appended to the time and treatment-based covariates constructed by dpgrowmm.
print(summary(res))	prints contents of summary to console.
plot(res)	returns results plots, including the set of subject random effects values and credible intervals, a sample of by-subject growth curves, mean growth curves split by each treatment and control, as well as selected trace plots for number of clusters and for precision parameters for the likehilood and random effects. Lastly, a trace plot for the deviance statistic is also included.
samples(res)	contains (n.iter - n.burn) posterior sampling iterations for every model parameter, including fixed and random effects.
resid(res)	contains the model residuals.

Note

The intended focus for this package are data where both number of subjects and number of repeated measures are limited. A DP prior is placed on the by-subject random effects to borrow strength across subjects for each estimation of each subject's growth curve. The imposition of the DP prior also allows the resulting posterior distributions over the subject random effects to be non-Gaussian. The dpgrow function is very similar to dpgrowmm; only the latter includes a separate set of random effects not grouped by subject (e.g. for treatment dosages allocated to subjects) mapped back to subject-time cases through a multiple membership design matrix. The dpgrowmult function generalizes dpgrowmm by allowing more than one multiple membership effects term. See Savitsky and Paddock (2011) for detailed model constructions.

Author(s)

Terrance Savitsky [e-mail] Susan Paddock [e-mail]

References

S. M. Paddock and T. D. Savitsky (2012) Bayesian Hierarchical Semiparametric Modeling of Longitudinal Post-treatment Outcomes from Open-enrollment Therapy Groups, submitted to: JRSS Series A (Statistics in Society).

T. D. Savitsky and S. M. Paddock (2012) Visual Sufficient Statistics for Repeated Measures data with growcurves for R, submitted to: Journal of Statistical Software.

See Also

dpgrow, dpgrowmult

Examples

## Not run: 
## extract simulated dataset
library(growcurves)
data(datsim)
## attach(datsim)
## Model with DP on clients effects, but now INCLUDE session random effects
## in a multiple membership construction communicated with the N x S matrix, W.subj.aff.
## Returns object, res.mm, of class "dpgrowmm".
shape.dp	= 3
strength.mm	= 0.001
res.mm	= dpgrowmm(y = datsim$y, subject = datsim$subject, 
		trt = datsim$trt, time = datsim$time, 
		n.random = datsim$n.random, 
		n.fix_degree = 2, Omega = datsim$Omega, 
		group = datsim$group, 
		subj.aff = datsim$subj.aff,
		W.subj.aff = datsim$W.subj.aff, 
		n.iter = 10000, n.burn = 2000, n.thin = 10,
		shape.dp = shape.dp, rate.dp = rate.dp, 
		strength.mm = strength.mm, option = "mmcar")
plot.results		= plot(res.mm) ## ggplot2 plot objects,
summary.results	= summary(res.mm) ## credible intervals and fit statistics
samples.posterior	= samples(res.mm) ## posterior sampled values

## End(Not run)

growcurves documentation built on May 2, 2019, 7:03 a.m.