JMbayes2: jm – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

JMbayes2

jm

Joint Models for Longitudinal and Time-to-Event Data

Description

Fits multivariate joint models for longitudinal and time-to-event data.

Usage

jm(Surv_object, Mixed_objects, time_var, functional_forms = NULL,
  data_Surv = NULL, id_var = NULL, priors = NULL, control = NULL, ...)

value(x)
slope(x, eps = 0.001, direction = "both")
area(x)

vexpit(x)
Dexpit(x)

vexp(x)
Dexp(x)

vlog(x)
vlog2(x)
vlog10(x)

vsqrt(x)

tv(x, knots = NULL, ord = 2L)

Arguments

`Surv_object`	an object: of class 'coxph' fitted by function `coxph()` from package survival, or of class 'survreg' fitted by function `survreg()` from package survival.
`Mixed_objects`	a `list` of objects or a single object. Objects may be: of class 'lme' fitted by function `lme()` from package nlme, or of class 'MixMod' fitted by function `mixed_model()` from package GLMMadaptive.
`time_var`	a `character` string indicating the time variable in the mixed-effects model(s).
`functional_forms`	a `list` of formulas. Each formula corresponds to one longitudinal outcome and specifies the association structure between that outcome and the survival submodel as well as any interaction terms between the components of the longitudinal outcome and the survival submodel. See Examples.
`data_Surv`	the `data.frame` used to fit the Cox/AFT survival submodel.
`id_var`	a `character` string indicating the id variable in the survival submodel.
`priors`	a named `list` of user-specified prior parameters: `mean_betas_HC` the prior mean vector of the normal prior for the regression coefficients of the covariates of the longitudinal model(s), which were hierarchically centered. `Tau_betas_HC` the prior precision matrix of the normal prior for the regression coefficients of the longitudinal model(s), which were hierarchically centered. `mean_betas_nHC` a `list` of the prior mean vector(s) of the normal prior(s) for the regression coefficients of the covariates of the longitudinal model(s), which were not hierarchically centered. `Tau_betas_nHC` a `list` of the prior precision matrix(ces) of the normal prior(s) for the regression coefficients of the longitudinal model(s), which were not Hierarchically Centered. `mean_bs_gammas` the prior mean vector of the normal prior for the B-splines coefficients used to approximate the baseline hazard. `Tau_bs_gammas` the prior precision matrix of the normal prior for the B-splines coefficients used to approximate the baseline hazard. `A_tau_bs_gammas` the prior shape parameter of the gamma prior for the precision parameter of the penalty term for the B-splines coefficients for the baseline hazard. `B_tau_bs_gammas` the prior rate parameter of the gamma prior for the precision parameter of the penalty term for the B-splines coefficients for the baseline hazard. `rank_Tau_bs_gammas` the prior rank parameter for the precision matrix of the normal prior for the B-splines coefficients used to approximate the baseline hazard. `mean_gammas` the prior mean vector of the normal prior for the regression coefficients of baseline covariates. `Tau_gammas` the prior precision matrix of the normal prior for the regression coefficients of baseline covariates. `penalty_gammas` a character string with value 'none', 'ridge', or 'horseshoe' indicating whether the coefficients of the baseline covariates included in the survival submodel should not be shrunk, shrank using ridge prior, or shrank using horseshoe prior, respectively. `A_lambda_gammas` the prior shape parameter of the gamma prior for the precision parameter of the local penalty term for the baseline regression coefficients. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `B_lambda_gammas` the prior rate parameter of the gamma prior for the precision parameter of the local penalty term for the baseline regression coefficients. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `A_tau_gammas` the prior shape parameter of the gamma prior for the precision parameter of the global penalty term for the baseline regression coefficients. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `B_tau_gammas` the prior rate parameter of the gamma prior for the precision parameter of the global penalty term for the baseline regression coefficients. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `A_nu_gammas` the prior shape parameter of the gamma prior for the variance hyperparameter for the precision parameter of the local penalty term for the baseline regression coefficients. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `B_nu_gammas` the prior rate parameter of the gamma prior for the variance hyperparameter for the precision parameter of the local penalty term for the baseline regression coefficients. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `A_xi_gammas` the prior shape parameter of the gamma prior for the variance hyperparameter for the precision parameter of the global penalty term for the baseline regression coefficients. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `B_xi_gammas` the prior rate parameter of the gamma prior for the variance hyperparameter for the precision parameter of the global penalty term for the baseline regression coefficients. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `mean_alphas` the prior mean vector of the normal prior for the association parameter(s). `Tau_alphas` the prior mean vector of the normal prior for the association parameter(s). `penalty_alphas` a character string with value 'none', 'ridge', 'horseshoe' indicating whether the coefficients association parameters should not be shrunk, shrank using ridge prior, or shrank using horseshoe prior, respectively. `A_lambda_alphas` the prior shape parameter of the gamma prior for the precision parameter of the local penalty term for the association parameters. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `B_lambda_alphas` the prior rate parameter of the gamma prior for the precision parameter of the local penalty term for the association parameters. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `A_tau_alphas` the prior shape parameter of the gamma prior for the precision parameter of the global penalty term for the association parameters. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `B_tau_alphas` the prior rate parameter of the gamma prior for the precision parameter of the global penalty term for the association parameters. Only relevant when `penalty_gammas = 'ridge'` or `penalty_gammas = 'horseshoe'`. `A_nu_alphas` the prior shape parameter of the gamma prior for the variance hyperparameter for the precision parameter of the local penalty term for the association parameters. Only relevant when `penalty_gammas = 'ridge'`, or `penalty_gammas = 'horseshoe'`. `B_nu_alphas` the prior rate parameter of the gamma prior for the variance hyperparameter for the precision parameter of the local penalty term for the association parameters. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `A_xi_alphas` the prior shape parameter of the gamma prior for the variance hyperparameter for the precision parameter of the global penalty term for the association parameters. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `B_xi_alphas` the prior rate parameter of the gamma prior for the variance hyperparameter for the precision parameter of the global penalty term for the association parameters. Only relevant when `penalty_gammas = 'ridge'` or when `penalty_gammas = 'horseshoe'`. `gamma_prior_D_sds` logical; if `TRUE`, a gamma prior will be used for the standard deviations of the D matrix (variance-covariance matrix of the random effects). Defaults to `TRUE` `D_sds_df` the prior degrees of freedom parameter for the half-t prior for the standard deviations of the D matrix (variance-covariance matrix of the random effects). `D_sds_sigma` the prior sigma parameter vector for the half-t prior for the standard deviations of the D matrix (variance-covariance matrix of the random effects). `D_sds_shape` the prior shape parameter for the gamma prior for the standard deviations of the D matrix (variance-covariance matrix of the random effects). `D_sds_mean` the prior mean parameter vector for the gamma prior for the standard deviations of the D matrix (variance-covariance matrix of the random effects). `D_L_etaLKJ` the prior eta parameter for the LKJ prior for the correlation matrix of the random effects. `sigmas_df` the prior degrees of freedom parameter for the half-t prior for the error term(s). `sigmas_sigma` the prior sigma parameter for the half-t prior for the error term(s).
`control`	a list of control values with components: `GK_k` the number of quadrature points for the Gauss Kronrod rule; options 15 and 7. `Bsplines_degree` the degree of the splines in each basis; default quadratic splines. `base_hazard_segments` the number of segments to split the follow-up period. Defaults to 10. `diff` the order of the difference used in the penalty matrix for the B-splines for h_0. Defaults to 2. `n_chains` an integer specifying the number of chains for the MCMC. Defaults to 3. `n_burnin` an integer specifying the number of burn-in iterations. Defaults to 500. `n_iter` an integer specifying the number of total iterations per chain. Defaults to 3500. `seed` the seed used in the sampling procedures. Defaults to 123. `MALA` a `logical`; if TRUE, the MALA algorithm is used when updating the elements of the Cholesky factor of the D matrix. Defaults to `FALSE`. `save_random_effects` a `logical`; if TRUE, the full MCMC results of the random effects will be saved and returned with the `jm` object. Defaults to `FALSE`. `cores` an integer specifying the number of cores to use. Defaults to the available cores minus one.
`x`	a numeric input variable.
`knots`	a numeric vector of knots.
`ord`	an integer denoting the order of the spline.
`eps`	numeric scalar denoting the step-size for the finite difference approximation.
`direction`	character string for the direction of the numerical derivative, options are `"both"`, and `"backward"`.
`...`	arguments passed to `control`.

Details

The mathematical details regarding the definition of the multivariate joint model, and the capabilities of the package can be found in the vignette in the doc directory.

Value

A list of class jm with components:

`mcmc`	a `list` of the MCMC samples for each parameter.
`acc_rates`	a `list` of the acceptance rates for each parameter.
`logLik`	a `matrix` of dimensions [`((n_iter - n_burnin)/n_thin)n_thin`, number of individuals], with element [i, j] being the conditional log-Likelihood value of the i^{th}* iteration for the j^{th} individual.
`mlogLik`	a `matrix` of dimensions [`((n_iter - n_burnin)/n_thin)n_thin`, number of individuals], with element [i, j] being the marginal log-Likelihood value of the i^{th}* iteration for the j^{th} individual.
`running_time`	an object of class `proc_time` with the time used to run `jm`.
`statistics`	a `list` with posterior estimates of the parameters (means, medians, standard deviations, standard errors, effective sample sizes, tail probabilities, upper and lower bounds of credible intervals, etc.).
`fit_stats`	a `list` of lists with fit statistics (DIC, pD, LPML, CPO, WAIC) for both conditional and marginal formulations.
`model_data`	a `list` of data used to fit the model.
`model_info`	a `list` of components of the fit useful to other functions.
`initial_values`	a `list` with the initial values of the parameters.
`control`	a copy of the `control` values used to fit the model.
`priors`	a copy of the `priors` used to fit the model.
`call`	the matched call.

Author(s)

Dimitris Rizopoulos d.rizopoulos@erasmusmc.nl

Examples

################################################################################

##############################################
# Univariate joint model for serum bilirubin #
# 1 continuous outcome                       #
##############################################

# [1] Fit the mixed model using lme().
fm1 <- lme(fixed = log(serBilir) ~ year * sex + I(year^2) +
           age + prothrombin, random =  ~ year | id, data = pbc2)

# [2] Fit a Cox model, specifying the baseline covariates to be included in the
# joint model.
fCox1 <- coxph(Surv(years, status2) ~ drug + age, data = pbc2.id)

# [3] The basic joint model is fitted using a call to jm() i.e.,
joint_model_fit_1 <- jm(fCox1, fm1, time_var = "year",
        n_chains = 1L, n_iter = 11000L, n_burnin = 1000L)
summary(joint_model_fit_1)
traceplot(joint_model_fit_1)

################################################################################

##########################################################################
# Multivariate joint model for serum bilirubin, hepatomegaly and ascites #
# 1 continuous outcome, 2 categorical outcomes                           #
##########################################################################

# [1] Fit the mixed-effects models using lme() for continuous
# outcomes and mixed_model() for categorical outcomes.
fm1 <- lme(fixed = log(serBilir) ~ year * sex,
           random = ~ year | id, data = pbc2)

fm2 <- mixed_model(hepatomegaly ~ sex + age + year, data = pbc2,
                   random = ~ year | id, family = binomial())

fm3 <- mixed_model(ascites ~ year + age, data = pbc2,
                   random = ~ year | id, family = binomial())

# [2] Save all the fitted mixed-effects models in a list.
Mixed <- list(fm1, fm2, fm3)

# [3] Fit a Cox model, specifying the baseline covariates to be included in the
# joint model.
fCox1 <- coxph(Surv(years, status2) ~ drug + age, data = pbc2.id)

# [4] The joint model is fitted using a call to jm() i.e.,
joint_model_fit_2 <- jm(fCox1, Mixed, time_var = "year",
      n_chains = 1L, n_iter = 11000L, n_burnin = 1000L)
summary(joint_model_fit_2)
traceplot(joint_model_fit_2)

################################################################################

######################
# Slope & Area Terms #
######################

# We extend model 'joint_model_fit_2' by including the value and slope term for
# bilirubin, the area term for hepatomegaly (in the log-odds scale), and the
# value and area term for spiders (in the log-odds scale).
# To include these terms into the model, we specify the 'functional_forms'
# argument. This should be a list of right side formulas. Each component of the
# list should have as name the name of the corresponding outcome variable. In
# the right side formula we specify the functional form of the association using
# functions 'value()', 'slope()' and 'area()'.
# Notes: (1) For terms not specified in the 'functional_forms' list, the default
# value functional form is used.

# [1] Fit the mixed-effects models using lme() for continuous outcomes
# and mixed_model() for categorical outcomes.
fm1 <- lme(fixed = log(serBilir) ~ year * sex, random = ~ year | id, data = pbc2)

fm2 <- mixed_model(hepatomegaly ~ sex + age + year, data = pbc2,
                   random = ~ year | id, family = binomial())

fm3 <- mixed_model(ascites ~ year + age, data = pbc2,
                   random = ~ year | id, family = binomial())

# [2] Save all the fitted mixed-effects models in a list.
Mixed <- list(fm1, fm2, fm3)

# [3] Fit a Cox model, specifying the baseline covariates to be included in the
# joint model.
fCox1 <- coxph(Surv(years, status2) ~ drug + age, data = pbc2.id)

# [4] Specify the list of formulas to be passed to the functional_forms argument
# of jm().
fForms <- list("log(serBilir)" = ~ value(log(serBilir)) + slope(log(serBilir)),
               "hepatomegaly" = ~ area(hepatomegaly),
               "ascites" = ~ value(ascites) + area(ascites))

# [5] The joint model is fitted using a call to jm() and passing the list
# to the functional_forms argument.
joint_model_fit_2 <- jm(fCox1, Mixed, time_var = "year",
                        functional_forms = fForms, n_chains = 1L,
                        n_iter = 11000L, n_burnin = 1000L)
summary(joint_model_fit_2)

JMbayes2

Extended Joint Models for Longitudinal and Time-to-Event Data

v0.1-5

GPL (>= 3)

Authors

Dimitris Rizopoulos [aut, cre] (<https://orcid.org/0000-0001-9397-0900>), Grigorios Papageorgiou [aut], Pedro Miranda Afonso [aut]

Initial release

2021-03-09

jm

Description

Usage

Arguments

Details

Value

Author(s)

See Also

Examples

JMbayes2

We don't support your browser anymore