R: Markov Chain Monte Carlo (MCMC) for time-varying parameter...

shrinkDSM {shrinkDSM}

R Documentation

Markov Chain Monte Carlo (MCMC) for time-varying parameter survival models with shrinkage

Description

shrinkDSM samples from the joint posterior distribution of the parameters of a time-varying parameter survival model with shrinkage and returns the MCMC draws. See also shrinkTVP to see more examples of how to modify the prior setup of the time-varying component of the model.

Usage

shrinkDSM(
  formula,
  data,
  mod_type = "double",
  delta,
  S,
  group,
  subset,
  niter = 10000,
  nburn = round(niter/2),
  nthin = 1,
  learn_a_xi = TRUE,
  learn_a_tau = TRUE,
  a_xi = 0.1,
  a_tau = 0.1,
  learn_c_xi = TRUE,
  learn_c_tau = TRUE,
  c_xi = 0.1,
  c_tau = 0.1,
  a_eq_c_xi = FALSE,
  a_eq_c_tau = FALSE,
  learn_kappa2_B = TRUE,
  learn_lambda2_B = TRUE,
  kappa2_B = 20,
  lambda2_B = 20,
  hyperprior_param,
  sv_param,
  MH_tuning,
  phi_param,
  display_progress = TRUE
)

Arguments

`formula`	an object of class "formula": a symbolic representation of the model, as in the function `lm`. For details, see `formula`.
`data`	optional data frame containing the response variable and the covariates. If not found in `data`, the variables are taken from `environment(formula)`, typically the environment from which `shrinkDSM` is called. No `NA`s are allowed in the response variable and the covariates.
`mod_type`	character string that reads either `"triple"`, `"double"` or `"ridge"`. Determines whether the triple gamma, double gamma or ridge prior are used for `theta_sr` and `beta_mean`. The default is "double".
`delta`	The status indicator of the last period, 0 = censored or 1 = event observed.
`S`	integer vector of time points that start a new interval. Parameters are fixed within an interval and vary across intervals.
`group`	optional grouping indicator for latent factor.
`subset`	optional vector specifying a subset of observations to be used in the fitting process.
`niter`	positive integer, indicating the number of MCMC iterations to perform, including the burn-in. Has to be larger than or equal to `nburn` + 2. The default value is 10000.
`nburn`	non-negative integer, indicating the number of iterations discarded as burn-in. Has to be smaller than or equal to `niter` - 2. The default value is `round(niter / 2)`.
`nthin`	positive integer, indicating the degree of thinning to be performed. Every `nthin` draw is kept and returned. The default value is 1, implying that every draw is kept.
`learn_a_xi`	logical value indicating whether to learn a_xi, the spike parameter of the state variances. The default value is `TRUE`.
`learn_a_tau`	logical value indicating whether to learn a_tau, the spike parameter of the mean of the initial values of the states. The default value is `TRUE`.
`a_xi`	positive, real number, indicating the (fixed) value for a_xi. Ignored if `learn_a_xi` is `TRUE` or `mod_type` is set to `"ridge"`. The default value is 0.1.
`a_tau`	positive, real number, indicating the (fixed) value for a_tau. Ignored if `learn_a_tau` is `TRUE` or `mod_type` is set to `"ridge"`. The default value is 0.1.
`learn_c_xi`	logical value indicating whether to learn c_xi, the tail parameter of the state variances. Ignored if `mod_type` is not set to `"triple"` or `a_eq_c_xi` is set to `TRUE`. The default value is `TRUE`.
`learn_c_tau`	logical value indicating whether to learn c_tau, the tail parameter of the mean of the initial values of the states. Ignored if `mod_type` is not set to `"triple"` or `a_eq_c_tau` is set to `TRUE`. The default value is `TRUE`.
`c_xi`	positive, real number, indicating the (fixed) value for c_xi. Ignored if `learn_c_xi` is `TRUE`, `mod_type` is not set to `"triple"` or `a_eq_c_xi` is set to `TRUE`. The default value is 0.1.
`c_tau`	positive, real number, indicating the (fixed) value for c_tau. Ignored if `learn_c_xi` is `TRUE`, `mod_type` is not set to `"triple"` or `a_eq_c_tau` is set to `TRUE`. The default value is 0.1.
`a_eq_c_xi`	logical value indicating whether to force `a_xi` and `c_xi` to be equal. If set to `TRUE`, `beta_a_xi` and `alpha_a_xi` are used as the hyperparameters and `beta_c_xi` and `alpha_c_xi` are ignored. Ignored if `mod_type` is not set to `"triple"`. The default value is `FALSE`.
`a_eq_c_tau`	logical value indicating whether to force `a_tau` and `c_tau` to be equal. If set to `TRUE`, `beta_a_tau` and `alpha_a_tau` are used as the hyperparameters and `beta_c_tau` and `alpha_c_tau` are ignored. Ignored if `mod_type` is not set to `"triple"`. The default value is `FALSE`.
`learn_kappa2_B`	logical value indicating whether to learn kappa2_B, the global level of shrinkage for the state variances. The default value is `TRUE`.
`learn_lambda2_B`	logical value indicating whether to learn the lambda2_B parameter, the global level of shrinkage for the mean of the initial values of the states. The default value is `TRUE`.
`kappa2_B`	positive, real number. Initial value of kappa2_B. The default value is 20.
`lambda2_B`	positive, real number. Initial value of lambda2_B. The default value is
`hyperprior_param`	optional named list containing hyperparameter values. Not all have to be supplied, with those missing being replaced by the default values. Any list elements that are misnamed will be ignored and a warning will be thrown. All hyperparameter values have to be positive, real numbers. The following hyperparameters can be supplied: `e1`: The default value is 0.001. `e2`: The default value is 0.001. `d1`: The default value is 0.001. `d2`: The default value is 0.001. `beta_a_xi`: The default value is 10. `beta_a_tau`: The default value is 10. `alpha_a_xi`: The default value is 5. `alpha_a_tau`: The default value is 5.
`sv_param`	optional named list containing hyperparameter values for the stochastic volatility parameters. Not all have to be supplied, with those missing being replaced by the default values. Any list elements that are misnamed will be ignored and a warning will be thrown. Ignored if `group` is missing. The following elements can be supplied: `Bsigma_sv`: positive, real number. The default value is 1. `a0_sv`: positive, real number. The default value is 5. `b0_sv`: positive, real number. The default value is 1.5.
`MH_tuning`	optional named list containing values used to tune the MH steps for `a_xi` and `a_tau`. Not all have to be supplied, with those missing being replaced by the default values. Any list elements that are misnamed will be ignored and a warning will be thrown. The arguments for `a_xi`(`a_tau`) are only used if `learn_a_xi`(`learn_a_tau`) is set to `TRUE`. Arguments ending in "adaptive" are logical values indicating whether or not to make the MH step for the respective parameter adaptive. Arguments ending in "tuning_par" serve two different purposes. If the respective MH step is not set to be adaptive, it acts as the standard deviation of the proposal distribution. If the respective MH step is set to be adaptive, it acts as the initial standard deviation. Arguments ending in "target_rate" define the acceptance rate the algorithm aims to achieve. Arguments ending in "max_adapt" set the maximum value by which the logarithm of the standard deviation of the proposal distribution is adjusted. Finally, arguments ending in "batch_size" set the batch size after which the standard deviation of the proposal distribution is adjusted. The following elements can be supplied: `a_xi_adaptive`: logical value. The default is `TRUE`. `a_xi_tuning_par`: positive, real number. The default value is 1. `a_xi_target_rate`: positive, real number, between 0 and 1. The default value is 0.44. `a_xi_max_adapt`: positive, real number. The default value is 0.01. `a_xi_batch_size`: positive integer. The default value is 50. `a_tau_adaptive`: logical value. The default is `TRUE`. `a_tau_tuning_par`: positive, real number. The default value is 1. `a_tau_target_rate`: positive, real number, between 0 and 1. The default value is 0.44. `a_tau_max_adapt`: positive, real number. The default value is 0.01. `a_tau_batch_size`: positive integer. The default value is 50.
`phi_param`	optional named list containing hyperparameter values for the grouped factor and values to tune the MH steps for `a_phi` and `c_phi`. Not all have to be supplied, with those missing being replaced by the default values. Any list elements that are misnamed will be ignored and a warning will be thrown. Ignored if `group` is missing. The following elements can be supplied: `mod_type_phi` character string that reads either `"triple"`, `"double"` or `"ridge"`. Determines whether the triple gamma, double gamma or ridge prior are used for `phi`. The default is "double". `learn_a_phi`: logical value. The default is `TRUE`. `a_phi`: positive, real number. The default value is 0.1. `learn_c_phi`: logical value. The default is `TRUE`. `c_phi`: positive, real number. The default value is 0.1, `a_phi_eq_c_phi`: logical value. The default is `FALSE`. `learn_lambda2_B_phi`: logical value. The default is `TRUE`. `lambda2_B_phi`: positive, real number. The default value is 20. `e1_phi`: positive, real number. The default value is 0.001. `e2_phi`: positive, real number. The default value is 0.001. `beta_a_phi`: positive, real number. The default value is 10. `alpha_a_phi`: positive, real number. The default value is 5. `beta_c_phi`: positive, real number. The default value is 10. `alpha_c_phi`: positive, real number. The default value is 5. `a_phi_adaptive`: logical value. The default is `TRUE`. `a_phi_tuning_par`: positive, real number. The default value is 1. `a_phi_target_rate`: positive, real number, between 0 and 1. The default value is 0.44. `a_phi_max_adapt`: positive, real number. The default value is 0.01. `a_phi_batch_size`: positive integer. The default value is 50. `c_phi_adaptive`: logical value. The default is `TRUE`. `c_phi_tuning_par`: positive, real number. The default value is 1. `c_phi_target_rate`: positive, real number, between 0 and 1. The default value is 0.44. `c_phi_max_adapt`: positive, real number. The default value is 0.01. `c_phi_batch_size`: positive integer. The default value is 50.
`display_progress`	logical value indicating whether the progress bar and other informative output should be displayed. The default value is `TRUE`.

Value

The value returned is a list object of class shrinkDSM containing

`beta`	`list` object containing an `mcmc.dsm.tvp` object for the parameter draws from the posterior distribution of the centered states, one for each covariate. In the case that there is only one covariate, this becomes just a single `mcmc.dsm.tvp` object.
`beta_mean`	`mcmc` object containing the parameter draws from the posterior distribution of beta_mean.
`theta_sr`	`mcmc` object containing the parameter draws from the posterior distribution of the square root of theta.
`tau2`	`mcmc` object containing the parameter draws from the posterior distribution of tau2.
`xi2`	`mcmc` object containing the parameter draws from the posterior distribution of xi2.
`lambda2`	(optional) `mcmc` object containing the parameter draws from the posterior distribution of lambda2. Not returned if `mod_type` is not `"triple"`.
`kappa2`	(optional) `mcmc` object containing the parameter draws from the posterior distribution of kappa2. Not returned if `mod_type` is not `"triple"`.
`a_xi`	(optional) `mcmc` object containing the parameter draws from the posterior distribution of a_xi. Not returned if `learn_a_xi` is `FALSE` or `mod_type` is `"ridge"`.
`a_tau`	(optional) `mcmc` object containing the parameter draws from the posterior distribution of a_tau. Not returned if `learn_a_tau` is `FALSE` or `mod_type` is `"ridge"`.
`c_xi`	(optional) `mcmc` object containing the parameter draws from the posterior distribution of c_xi. Not returned if `learn_c_xi` is `FALSE` or `mod_type` is not `"triple"`.
`c_tau`	(optional) `mcmc` object containing the parameter draws from the posterior distribution of c_tau. Not returned if `learn_c_tau` is `FALSE` or `mod_type` is not `"triple"`.
`lambda2_B`	(optional) `mcmc` object containing the parameter draws from the posterior distribution of lambda2_B. Not returned if `learn_lambda2_B` is `FALSE` or `mod_type` is `"ridge"`.
`kappa2_B`	(optional) `mcmc` object containing the parameter draws from the posterior distribution of kappa2_B. Not returned if `learn_kappa2_B` is `FALSE` or `mod_type` is `"ridge"`.
`MH_diag`	(optional) named list containing statistics for assessing MH performance. Not returned if no MH steps are required or none of them are specified to be adaptive.
`priorvals`	`list` object containing hyperparameter values of the prior distributions, as specified by the user.
`model`	`list` object containing the model matrix, model response and formula used.
`summaries`	`list` object containing a collection of summary statistics of the posterior draws.

To display the output, use plot and summary. The summary method displays the specified prior values stored in priorvals and the posterior summaries stored in summaries, while the plot method calls coda's plot.mcmc or the plot.mcmc.dsm.tvp method. Furthermore, all functions that can be applied to coda::mcmc objects (e.g. coda::acfplot) can be applied to all output elements that are coda compatible.

Author(s)

Daniel Winkler daniel.winkler@wu.ac.at

Peter Knaus peter.knaus@wu.ac.at

Examples


set.seed(123)
data("gastric")

# Create intervals for piecewise exponential model
intervals <- divisionpoints(gastric$time, gastric$status, 2)

# Estimate baseline model
mod <- shrinkDSM(time ~ radiation, gastric,
                 delta = gastric$status, S = intervals)

# Estimate model with different prior setup
mod2 <- shrinkDSM(time ~ radiation, gastric,
                 delta = gastric$status, S = intervals,
                 mod_type = "triple")

# Change some of the hyperparameters
mod3 <- shrinkDSM(time ~ radiation, gastric,
                 delta = gastric$status, S = intervals,
                 mod_type = "triple",
                 hyperprior_param = list(beta_a_xi = 5,
                                         alpha_a_xi = 10))

[Package shrinkDSM version 0.2.0 Index]