bayessurvreg2: Cluster-specific accelerated failure time model for...

In bayesSurv: Bayesian Survival Regression with Flexible Error and Random Effects Distributions

Cluster-specific accelerated failure time model for multivariate, possibly doubly-interval-censored data. The error distribution is expressed as a penalized univariate normal mixture with high number of components (G-spline). The distribution of the vector of random effects is multivariate normal.

Description

A function to estimate a regression model with possibly clustered (possibly right, left, interval or doubly-interval censored) data. In the case of doubly-interval censoring, different regression models can be specified for the onset and event times.

(Multivariate) random effects, normally distributed and acting as in the linear mixed model, normally distributed, can be included to adjust for clusters.

The error density of the regression model is specified as a mixture of Bayesian G-splines (normal densities with equidistant means and constant variances). This function performs an MCMC sampling from the posterior distribution of unknown quantities.

For details, see Komárek (2006), and Komárek, Lesaffre and Legrand (2007).

We explain first in more detail a model without doubly censoring. Let T_{i,l},\; i=1,\dots, N,\; l=1,\dots, n_i be event times for ith cluster and the units within that cluster The following regression model is assumed:

\log(T_{i,l}) = \beta'x_{i,l} + b_i'z_{i,l} + \varepsilon_{i,l},\quad i=1,\dots, N,\;l=1,\dots, n_i

where \beta is unknown regression parameter vector, x_{i,l} is a vector of covariates. b_i is a (multivariate) cluster-specific random effect vector and z_{i,l} is a vector of covariates for random effects.

The random effect vectors b_i,\;i=1,\dots, N are assumed to be i.i.d. with a (multivariate) normal distribution with the mean \beta_b and a covariance matrix D. Hierarchical centring (see Gelfand, Sahu, Carlin, 1995) is used. I.e. \beta_b expresses the average effect of the covariates included in z_{i,l}. Note that covariates included in z_{i,l} may not be included in the covariate vector x_{i,l}. The covariance matrix D is assigned an inverse Wishart prior distribution in the next level of hierarchy.

The error terms \varepsilon_{i,l},\;i=1,\dots, N, l=1,\dots, n_i are assumed to be i.i.d. with a univariate density g_{\varepsilon}(e). This density is expressed as a mixture of Bayesian G-splines (normal densities with equidistant means and constant variances). We distinguish two, theoretically equivalent, specifications.

Specification 1

\varepsilon \sim \sum_{j=-K}^{K} w_{j} N(\mu_{j},\,\sigma^2)

where \sigma^2 is the unknown basis variance and \mu_{j},\;j=-K,\dots, K is an equidistant grid of knots symmetric around the unknown point \gamma and related to the unknown basis variance through the relationship

\mu_{j} = \gamma + j\delta\sigma,\quad j=-K,\dots,K,

where \delta is fixed constants, e.g. \delta=2/3 (which has a justification of being close to cubic B-splines).

Specification 2

\varepsilon \sim \alpha + \tau\,V

where \alpha is an unknown intercept term and \tau is an unknown scale parameter. V is then standardized error term which is distributed according to the univariate normal mixture, i.e.

V\sim \sum_{j=-K}^{K} w_{j} N(\mu_{j},\,\sigma^2)

where \mu_{j},\;j=-K,\dots, K is an equidistant grid of fixed knots (means), usually symmetric about the fixed point \gamma=0 and \sigma^2 is fixed basis variance. Reasonable values for the numbers of grid points K is K=15 with the distance between the two knots equal to \delta=0.3 and for the basis variance \sigma^2=0.2^2.

Personally, I found Specification 2 performing better. In the paper Komárek, Lesaffre and Legrand (2007) only Specification 2 is described.

The mixture weights w_{j},\;j=-K,\dots, K are not estimated directly. To avoid the constraints 0 < w_{j} < 1 and \sum_{j=-K}^{K}\,w_j = 1 transformed weights a_{j},\;j=-K,\dots, K related to the original weights by the logistic transformation:

a_{j} = \frac{\exp(w_{j})}{\sum_{m}\exp(w_{m})}

are estimated instead.

A Bayesian model is set up for all unknown parameters. For more details I refer to Komárek (2006) and to Komárek, Lesafre, and Legrand (2007).

If there are doubly-censored data the model of the same type as above can be specified for both the onset time and the time-to-event.

Usage

bayessurvreg2(formula, random, formula2, random2,
   data = parent.frame(),
   na.action = na.fail, onlyX = FALSE,
   nsimul = list(niter = 10, nthin = 1, nburn = 0, nwrite = 10),
   prior, prior.beta, prior.b, init = list(iter = 0),
   mcmc.par = list(type.update.a = "slice", k.overrelax.a = 1,
                   k.overrelax.sigma = 1, k.overrelax.scale = 1),
   prior2, prior.beta2, prior.b2, init2,
   mcmc.par2 = list(type.update.a = "slice", k.overrelax.a = 1,
                    k.overrelax.sigma = 1, k.overrelax.scale = 1),
   store = list(a = FALSE, a2 = FALSE, y = FALSE, y2 = FALSE,
                r = FALSE, r2 = FALSE, b = FALSE, b2 = FALSE), 
   dir)

Arguments

formula	model formula for the regression. In the case of doubly-censored data, this is the model formula for the onset time. The left-hand side of the formula must be an object created using Surv. In the formula all covariates appearing both in the vector x_{i,l} and z_{i,l} must be mentioned. Intercept is implicitely included in the model by the estimation of the error distribution. As a consequence -1 in the model formula does not have any effect on the model specification. If random is used then the formula must contain an identification of clusters in the form cluster(id), where id is a name of the variable that determines clusters, e.g. Surv(time, event) gender + cluster(id).
random	formula for the ‘random’ part of the model, i.e. the part that specifies the covariates z_{i,l}. In the case of doubly-censored data, this is the random formula for the onset time. If omitted, no random part is included in the model. E.g. to specify the model with a random intercept, say random= 1. All effects mentioned in random should also be mentioned on the right-hand side of formula. When some random effects are included the random intercept is added by default. It can be removed using e.g. random= -1 + gender.
formula2	model formula for the regression of the time-to-event in the case of doubly-censored data. Ignored otherwise. The same structure as for formula applies here.
random2	specification of the ‘random’ part of the model for time-to-event in the case of doubly-censored data. Ignored otherwise. The same structure as for random applies here.
data	optional data frame in which to interpret the variables occuring in the formula, formula2, random, random2 statements.
na.action	the user is discouraged from changing the default value na.fail.
onlyX	if TRUE no MCMC sampling is performed and only the design matrix (matrices) are returned. This can be useful to set up correctly priors for regression parameters in the presence of factor covariates.
nsimul	a list giving the number of iterations of the MCMC and other parameters of the simulation. niter total number of sampled values after discarding thinned ones, burn-up included; nthin thinning interval; nburn number of sampled values in a burn-up period after discarding thinned values. This value should be smaller than niter. If not, nburn is set to niter - 1. It can be set to zero; nwrite an interval at which information about the number of performed iterations is print on the screen and during the burn-up period an interval with which the sampled values are writen to files;
prior	a list specifying the prior distribution of the G-spline defining the distribution of the error term in the regression model given by formula and random. See prior argument of bayesHistogram function for more detail. In this list also ‘Specification’ as described above is specified. The item prior$neighbor.system can only be equal to uniCAR here.
prior.b	a list defining the way in which the random effects involved in formula and random are to be updated and the specification of priors for parameters related to these random effects. The list is assumed to have the following components. prior.D a string defining the prior distribution for the covariance matrix of random effects D. It can be either “inv.wishart” or “sduniform”. inv.wishart in that case is assumed that the prior distribution of the matrix D is Inverse-Wishart with degrees of freedom equal to \tau and a scale matrix equal to S. When D is a matrix q\times q a prior expectation of D is equal to (\tau - q - 1)^{-1}S if \tau > q + 1. For q - 1 < \tau \leq q + 1 a prior expectation is not finite. Degrees of freedom parameter \tau does not have to be an integer. It has to only satisfy a condition \tau > q - 1. prior.b$df.D gives a prior degrees of freedom parameter \tau and prior.b$scale.D determines the scale matrix D. Inverse-Wishart is also the default choice. sduniform this can be used only when the random effect is univariate (e.g. only random intercept in the model). Then the matrix D is just a scalar and the prior of \sqrt{D} (standard deviation of the univariate random effect) is assumed to be uniform on interval (0, S). The upper limit S is given by prior.b$scale.D. df.D degrees of freedom parameter \tau in the case that the prior of the matrix D is inverse-Wishart. scale.D a lower triangle of the scale matrix S in the case that the prior of the matrix D is inverse-Wishart or the upper limit S of the uniform distribution in the case that \sqrt{D} \sim \mbox{Unif}(0, S).
prior.beta	prior specification for the regression parameters, in the case of doubly-censored data for the regression parameters of the onset time, i.e. it is related to formula and random. Note that the beta vector contains both the fixed effects \beta and the means of the random effects (except the random intercept) \beta_b. This should be a list with the following components: mean.prior a vector specifying a prior mean for each beta parameter in the model. var.prior a vector specifying a prior variance for each beta parameter. It is recommended to run the function bayessurvreg2 first with its argument onlyX set to TRUE to find out how the betas are sorted. They must correspond to a design matrix X taken from formula.
init	an optional list with initial values for the MCMC related to the model given by formula and random. The list can have the following components: iter the number of the iteration to which the initial values correspond, usually zero. beta a vector of initial values for the regression parameters (both the fixed effects and means of the random effects). It must be sorted in the same way as are the columns in the design matrix. Use onlyX=TRUE if you do not know how the columns in the design matrix are created. a a vector of length 2K+1 with the initial values of transformed mixture weights. lambda initial values for the Markov random fields precision parameter. gamma an initial values for the middle knot \gamma. If ‘Specification’ is 2, this value will not be changed by the MCMC and it is recommended (for easier interpretation of the results) to set init$gamma to zero (default behavior). If ‘Specification’ is 1 init$gamma should be approximately equal to the mean value of the residuals. sigma an initial values of the basis standard deviation \sigma. If ‘Specification’ is 2, this value will not be changed by the MCMC and it is recommended to set it approximately equal to the range of standardized data (let say 4 + 4) divided by the number of knots and multiplied by something like 2/3. If ‘Specification’ is 1 this should be approximately equal to the range of the residuals divided by the number of knots (2K+1) and multiplied again by something like 2/3. intercept an initial values of the intercept term \alpha. If ‘Specification’ is 1 this value is not changed by the MCMC and the initial value is always changed to zero. scale an initial value of the scale parameter \tau. If ‘Specification’ is 1 this value is not changed by the MCMC and the initial value is always changed to one. D initial value for the covariance matrix of random effects D. Only its lower triangle must be given in a vector, e.g. c(d[1,1], d[2,1], d[3,1], d[2,2], d[3,2], d[3,3]) for a matrix 3 \times 3. b a vector or matrix of the initial values of random effects b_i,\;i=1,\dots,N for each cluster. The matrix should be of size q\times N, where q is the number of random effects. I.e. each column of the matrix contains the initial values for one cluster. y a vector of length \sum_{i=1}^N\,n_i with initial values of log-event-times. r a vector of length \sum_{i=1}^N\,n_i with initial component labels for each residual. All values must be between -K and K. See argument init of the function bayesHistogram for more details.
mcmc.par	a list specifying how some of the G-spline parameters related to the distribution of the error term from formula are to be updated. See bayesBisurvreg for more details. In contrast to bayesBisurvreg function argument mcmc.par$type.update.a can also be equal to "block" in which case all a coefficients are updated in 1 block using the Metropolis-Hastings algorithm.
prior2	a list specifying the prior distribution of the G-spline defining the distribution of the error term in the regression model given by formula2 and random2. See prior argument of bayesHistogram function for more detail.
prior.b2	prior specification for the parameters related to the random effects from formula2 and random2. This should be a list with the same structure as prior.b.
prior.beta2	prior specification for the regression parameters of time-to-event in the case of doubly censored data (related to formula2 and random2). This should be a list with the same structure as prior.beta.
init2	an optional list with initial values for the MCMC related to the model given by formula2 and random2. The list has the same structure as init.
mcmc.par2	a list specifying how some of the G-spline parameters related to formula2 are to be updated. The list has the same structure as mcmc.par.
store	a list of logical values specifying which chains that are not stored by default are to be stored. The list can have the following components. a if TRUE then all the transformed mixture weights a_{k}, k=-K,\dots,K, related to the G-spline (error distribution) of formula are stored. a2 if TRUE and there are doubly-censored data then all the transformed mixture weights a_{k}, k=-K,\dots,K, related to the G-spline (error distribution) of formula2 are stored. y if TRUE then augmented log-event times for all observations related to the formula are stored. y2 if TRUE then augmented log-event times for all observations related to formula2 are stored. r if TRUE then labels of mixture components for residuals related to formula are stored. r2 if TRUE then labels of mixture components for residuals related to formula2 are stored. b if TRUE then the sampled values of the random effects related to formula and random are stored. b2 if TRUE then the sampled values of the random effects related to formula2 and random2 are stored.
dir	a string that specifies a directory where all sampled values are to be stored.

Value

A list of class bayessurvreg2 containing an information concerning the initial values and prior choices.

Files created

Additionally, the following files with sampled values are stored in a directory specified by dir argument of this function (some of them are created only on request, see store parameter of this function).

Headers are written to all files created by default and to files asked by the user via the argument store. During the burn-in, only every nsimul$nwrite value is written. After the burn-in, all sampled values are written in files created by default and to files asked by the user via the argument store. In the files for which the corresponding store component is FALSE, every nsimul$nwrite value is written during the whole MCMC (this might be useful to restart the MCMC from some specific point).

The following files are created:

iteration.sim

one column labeled iteration with indeces of MCMC iterations to which the stored sampled values correspond.

mixmoment.sim

columns labeled k, Mean.1, D.1.1, where

k = number of mixture components that had probability numerically higher than zero;

Mean.1 = \mbox{E}(\varepsilon_{i,l});

D.1.1 = \mbox{var}(\varepsilon_{i,l});

all related to the distribution of the error term from the model given by formula.

mixmoment_2.sim

in the case of doubly-censored data, the same structure as mixmoment.sim, however related to the model given by formula2.

mweight.sim

sampled mixture weights w_{k} of mixture components that had probabilities numerically higher than zero. Related to the model given by formula.

mweight_2.sim

in the case of doubly-censored data, the same structure as mweight.sim, however related to the model given by formula2.

mmean.sim

indeces k, k \in\{-K, \dots, K\} of mixture components that had probabilities numerically higher than zero. It corresponds to the weights in mweight.sim. Related to the model given by formula.

mmean_2.sim

in the case of doubly-censored data, the same structure as mmean.sim, however related to the model given by formula2.

gspline.sim

characteristics of the sampled G-spline (distribution of \varepsilon_{i,l}) related to the model given by formula. This file together with mixmoment.sim, mweight.sim and mmean.sim can be used to reconstruct the G-spline in each MCMC iteration.

The file has columns labeled gamma1, sigma1, delta1, intercept1, scale1, The meaning of the values in these columns is the following:

gamma1 = the middle knot \gamma If ‘Specification’ is 2, this column usually contains zeros;

sigma1 = basis standard deviation \sigma of the G-spline. This column contains a fixed value if ‘Specification’ is 2;

delta1 = distance delta between the two knots of the G-spline. This column contains a fixed value if ‘Specification’ is 2;

intercept1 = the intercept term \alpha of the G-spline. If ‘Specification’ is 1, this column usually contains zeros;

scale1 = the scale parameter \tau of the G-spline. If ‘Specification’ is 1, this column usually contains ones;

gspline_2.sim

in the case of doubly-censored data, the same structure as gspline.sim, however related to the model given by formula2.

mlogweight.sim

fully created only if store$a = TRUE. The file contains the transformed weights a_{k}, k=-K,\dots,K of all mixture components, i.e. also of components that had numerically zero probabilities. This file is related to the error distribution of the model given by formula.

mlogweight_2.sim

fully created only if store$a2 = TRUE and in the case of doubly-censored data, the same structure as mlogweight.sim, however related to the error distribution of the model given by formula2.

r.sim

fully created only if store$r = TRUE. The file contains the labels of the mixture components into which the residuals are intrinsically assigned. Instead of indeces on the scale \{-K,\dots, K\} values from 1 to (2\,K+1) are stored here. Function vecr2matr can be used to transform it back to indices from -K to K.

r_2.sim

fully created only if store$r2 = TRUE and in the case of doubly-censored data, the same structure as r.sim, however related to the model given by formula2.

lambda.sim

one column labeled lambda. These are the values of the smoothing parameter\lambda (hyperparameters of the prior distribution of the transformed mixture weights a_{k}). This file is related to the model given by formula.

lambda_2.sim

in the case of doubly-censored data, the same structure as lambda.sim, however related to the model given by formula2.

beta.sim

sampled values of the regression parameters, both the fixed effects \beta and means of the random effects \beta_b (except the random intercept which has always the mean equal to zero). This file is related to the model given by formula. The columns are labeled according to the colnames of the design matrix.

beta_2.sim

in the case of doubly-censored data, the same structure as beta.sim, however related to the model given by formula2.

D.sim

sampled values of the covariance matrix D of the random effects. The file has 1 + 0.5\,q\,(q+1) columns (q is the dimension of the random effect vector b_i). The first column labeled det contains the determinant of the sampled matrix, additional columns labeled D.1.1, D.2.1, ..., D.q.1, ... D.q.q contain the lower triangle of the sampled matrix. This file is related to the model specified by formula and random.

D_2.sim

in the case of doubly-censored data, the same structure as D.sim, however related to the model given by formula2 and random2.

b.sim

fully created only if store$b = TRUE. It contains sampled values of random effects for all clusters in the data set. The file has q\times N columns sorted as b_{1,1},\dots,b_{1,q},\dots, b_{N,1},\dots,b_{N,q}. This file is related to the model given by formula and random.

b_2.sim

fully created only if store$b2 = TRUE and in the case of doubly-censored data, the same structure as b.sim, however related to the model given by formula2 and random2.

Y.sim

fully created only if store$y = TRUE. It contains sampled (augmented) log-event times for all observations in the data set.

Y_2.sim

fully created only if store$y2 = TRUE and in the case of doubly-censored data, the same structure as Y.sim, however related to the model given by formula2.

logposter.sim

columns labeled loglik, penalty, and logprw. This file is related to the model given by formula. The columns have the following meaning.

loglik = % - (\sum_{i=1}^N\,n_i)\,\Bigl\{\log(\sqrt{2\pi}) + \log(\sigma) \Bigr\}- 0.5\sum_{i=1}^N\sum_{l=1}^{n_i} \Bigl\{ (\sigma^2\,\tau^2)^{-1}\; (y_{i,l} - x_{i,l}'\beta - z_{i,l}'b_i - \alpha - \tau\mu_{r_{i,l}})^2 \Bigr\}

where y_{i,l} denotes (augmented) (i,l)th true log-event time.

In other words, loglik is equal to the conditional log-density

\sum_{i=1}^N \sum_{l=1}^{n_i}\,\log\Bigl\{p\bigl(y_{i,l}\;\big|\;r_{i,l},\,\beta,\,b_i,\,\mbox{G-spline}\bigr)\Bigr\};

penalty: the penalty term

-\frac{1}{2}\sum_{k}\Bigl(\Delta\, a_k\Bigr)^2

(not multiplied by \lambda);

logprw = -2\,(\sum_i n_i)\,\log\bigl\{\sum_{k}a_{k}\bigr\} + \sum_{k}N_{k}\,a_{k}, where N_{k} is the number of residuals assigned intrinsincally to the kth mixture component.

In other words, logprw is equal to the conditional log-density \sum_{i=1}^N\sum_{l=1}^{n_i} \log\bigl\{p(r_{i,l}\;|\;\mbox{G-spline weights})\bigr\}.

logposter_2.sim

in the case of doubly-censored data, the same structure as logposter.sim, however related to the model given by formula2.

Author(s)

Arnošt Komárek [e-mail]

References

Gelfand, A. E., Sahu, S. K., and Carlin, B. P. (1995). Efficient parametrisations for normal linear mixed models. Biometrika, 82, 479-488.

Komárek, A. (2006). Accelerated Failure Time Models for Multivariate Interval-Censored Data with Flexible Distributional Assumptions. PhD. Thesis, Katholieke Universiteit Leuven, Faculteit Wetenschappen.

Komárek, A., Lesaffre, E., and Legrand, C. (2007). Baseline and treatment effect heterogeneity for survival times between centers using a random effects accelerated failure time model with flexible error distribution. Statistics in Medicine, 26, 5457-5472.

Examples

## See the description of R commands for
## the model with EORTC data,
## analysis described in Komarek, Lesaffre and Legrand (2007).
##
## R commands available in the documentation
## directory of this package
## as ex-eortc.R and
## https://www2.karlin.mff.cuni.cz/ komarek/software/bayesSurv/ex-eortc.pdf
##

bayesSurv documentation built on Sept. 30, 2024, 9:34 a.m.