R: Main function of the package

cure_rate_MC3 {bayesCureRateModel}

R Documentation

Main function of the package

Description

Runs a Metropolis Coupled MCMC (MC^3) sampler in order to estimate the joint posterior distribution of the model.

Usage

cure_rate_MC3(y, X, Censoring_status, nChains = 12, mcmc_cycles = 15000, 
	alpha = NULL,nCores = 1, sweep = 5, mu_g = 1, s2_g = 1, 
	a_l = 2.1, b_l = 1.1, mu_b = rep(0, dim(X)[2]), 
	Sigma = 100 * diag(dim(X)[2]), g_prop_sd = 0.045, 
	lambda_prop_scale = 0.03, b_prop_sd = rep(0.022, dim(X)[2]), 
	initialValues = NULL, plot = TRUE, adjust_scales = FALSE, 
	verbose = FALSE, tau_mala = 1.5e-05, mala = 0.15, 
	promotion_time = list(distribution = "weibull", 
	prior_parameters = matrix(rep(c(2.1, 1.1), 2), byrow = TRUE, 2, 2), 
	prop_scale = c(0.1, 0.2)), single_MH_in_f = 0.2)

Arguments

`y`	Observed data, that is, a vector of length `n` with positive entries.
`X`	Design matrix with `k > 1` columns. Should contain a column of 1's if the model has a constant term. Should be a matrix with dimension `n\times k`.
`Censoring_status`	A vector `\boldsymbol\delta = (\delta_1,\ldots,\delta_n)` of binary variables corresponding to censoring indicators. The `i`-th observation is treated as a time-to-event if `\delta_i = 1` or as a censoring time otherwise (`\delta_i = 0`).
`nChains`	Positive integer corresponding to the number of heated chains in the MC`^3` scheme.
`mcmc_cycles`	Length of the generated MCMC sample. Default value: 15000. Note that each MCMC cycle consists of `sweep` (see below) usual MCMC iterations.
`alpha`	A decreasing sequence in `[1,0)` of `nChains` temperatures (or heat values). The first value should always be equal to 1, which corresponds to the target posterior distribution (that is, the first chain).
`nCores`	The number of cores used for parallel processing. In case where `nCores` > 1, the `nChains` will be processed in parallel using `nCores` cores. This may speed up significantly the run-time of the algorithm in Linux or macOS, but it is not suggested in Windows.
`sweep`	The number of usual MCMC iterations per MCMC cycle. Default value: 10.
`mu_g`	Parameter `a_{\gamma}` of the prior distribution of `\gamma`.
`s2_g`	Parameter `b_{\gamma}` of the prior distribution of `\gamma`.
`a_l`	Shape parameter `a_{\lambda}` of the Inverse Gamma prior distribution of `\lambda`.
`b_l`	Scale parameter `b_{\lambda}` of the Inverse Gamma prior distribution of `\lambda`.
`mu_b`	Mean (`\boldsymbol\mu`) of the multivariate normal prior distribution of regression coefficients. Should be a vector whose length is equal to `k`, i.e. the number of columns of the design matrix `X`. Default value: rep(0, k).
`Sigma`	Covariance matrix of the multivariate normal prior distribution of regression coefficients.
`g_prop_sd`	The scale of the proposal distribution for single-site updates of the `\gamma` parameter.
`lambda_prop_scale`	The scale of the proposal distribution for single-site updates of the `\lambda` parameter.
`b_prop_sd`	The scale of the proposal distribution for the update of the `\beta` parameter (regression coefficients).
`initialValues`	A list of initial values for each parameter (optional).
`plot`	Plot MCMC sample on the run. Default: TRUE.
`adjust_scales`	Boolean. If TRUE the MCMC sampler runs an initial phase of a small number of iterations in order to tune the scale of the proposal distributions in the Metropolis-Hastings steps.
`verbose`	Print progress on the terminal if TRUE.
`tau_mala`	Scale of the Metropolis adjusted Langevin diffussion proposal distribution.
`mala`	A number between `[0,1]` indicating the proportion of times the sampler attempts a MALA proposal. Thus, the probability of attempting a typical Metropolis-Hastings move is equal to 1 - `mala`.
`promotion_time`	A list with details indicating the parametric family of distribution describing the promotion time and corresponding prior distributions. See 'details'.
`single_MH_in_f`	The probability for attempting a series of single site updates in the typical Metropolis-Hastings move. Otherwise, with probability 1 - `single_MH_in_f` a Metropolis-Hastings move will attempt to update all continuous parameters simultaneously. It only makes sense when `mala < 1`.

Details

It is advised to scale all continuous explanatory variables in the design matrix, so their sample mean and standard deviations are equal to 0 and 1, respectively. The promotion_time argument should be a list containing the following entries

distribution: Character string specifying the family of distributions \{F(\cdot;\boldsymbol\alpha);\boldsymbol\alpha\in\mathcal A\} describing the promotion time.
prior_parameters: Values of hyper-parameters in the prior distribution of the parameters \boldsymbol\alpha.
prop_scale: The scale of the proposal distributions for each parameter in \boldsymbol\alpha.
dirichlet_concentration_parameter: Relevant only in the case of the 'gamma_mixture'. Positive scalar (typically, set to 1) determining the (common) concentration parameter of the Dirichlet prior distribution of mixing proportions.

The distribution entry should be one of the following: 'exponential', 'weibull', 'gamma', 'logLogistic', 'gompertz', 'lomax', 'dagum', 'gamma_mixture'.

The joint prior distribution of \boldsymbol\alpha = (\alpha_1,\ldots,\alpha_d) factorizes into products of inverse Gamma distributions for all (positive) parameters of F. Moreover, in the case of 'gamma_mixture', the joint prior also consists of another term to the Dirichlet prior distribution on the mixing proportions.

The prop_scale argument should be a vector with length equal to the length of vector d (number of elements in \boldsymbol\alpha), containing (positive) numbers which correspond to the scale of the proposal distribution. Note that these scale parameters are used only as initial values in case where adjust_scales = TRUE.

Value

An object of class bayesCureModel, i.e. a list with the following entries

`mcmc_sample`	Object of class `mcmc` (see the coda package), containing the generated MCMC sample for the target chain. The column names correspond to `g_mcmc` Sampled values for parameter `\gamma` `lambda_mcmc` Sampled values for parameter `\lambda` `alpha1_mcmc`... Sampled values for parameter `\alpha_1`... of the promotion time distribution `F(\cdot;\alpha_1,\ldots,\alpha_d)`. The subsequent `d-1` columns contain the sampled values for all remaining parameters, `\alpha_2,...,\ldots,\alpha_d`, where `d` depens on the family used in `promotion_time`. `b0_mcmc` Sampled values for the constant term of the regression (present only in the case where the design matrix `X` contains a column of 1s). `b1_mcmc`... Sampled values for the regression coefficient for the first explanatory variable, and similar for all subsequent columns.
`complete_log_likelihood`	The complete log-likelihood for the target chain.
`all_cll_values`	The complete log-likelihood for all chains
`latent_status_censored`	A data frame with the simulated binary latent status for each censored item.
`swap_accept_rate`	the acceptance rate of proposed swappings between adjacent MCMC chains.
`input_data_and_model_prior`	the input data and specification of the prior parameters.
`log_posterior`	the logarithm of the posterior distribution, up to a normalizing constant.
`map_estimate`	The Maximum A Posterior estimate of parameters
`BIC`	Bayesian Information Criterion.
`AIC`	Akaike Information Criterion.

Note

The core function is cure_rate_mcmc.

Author(s)

Panagiotis Papastamoulis

References

Papastamoulis and Milienos (2023). Bayesian inference and cure rate modeling for event history data. arXiv:2310.06926

Examples

# simulate toy data just for cran-check purposes        
	set.seed(10)
        n = 4
        stat = rbinom(n, size = 1, prob = 0.5)
        x <- cbind(1, matrix(rnorm(2*n), n, 2))
        y <- rexp(n)
	fit1 <- cure_rate_MC3(y = y, X = x, Censoring_status = stat, 
		promotion_time = list(distribution = 'weibull'),
		nChains = 2, nCores = 1, 
		mcmc_cycles = 3, sweep = 2)

[Package bayesCureRateModel version 1.1 Index]