bayes.2S_seq {BayesPIM}R Documentation

bayes.2S_seq: Bayesian Prevalence-Incidence Mixture Model (sequential processing)

Description

Estimates the Pattern Mixture model of Klausch et al. (2025) using a Bayesian Gibbs sampler. Identical to bayes.2S but uses a for loop over MCMC chains instead of foreach.

Usage

bayes.2S_seq(
  Vobs,
  Z.X = NULL,
  Z.W = NULL,
  r = NULL,
  dist.X = "weibull",
  kappa = 0.5,
  update.kappa = FALSE,
  kappa.prior = NULL,
  ndraws = 1000,
  prop.sd.X = NULL,
  chains = 3,
  thining = 1,
  parallel = TRUE,
  update.till.converge = FALSE,
  maxit = Inf,
  conv.crit = "upper",
  min_effss = chains * 10,
  beta.prior = "norm",
  beta.prior.X = 1,
  sig.prior.X = 1,
  tau.w = 1,
  fix.sigma.X = FALSE,
  prev.run = NULL,
  update.burnin = TRUE,
  ndraws.update = NULL,
  prev = TRUE,
  vanilla = FALSE,
  ndraws.naive = 5000,
  naive.run.prop.sd.X = prop.sd.X,
  par.exp = FALSE,
  collapsed.g = TRUE,
  k.prior = 1,
  fix.k = FALSE
)

Arguments

Vobs

A list of length n of numeric vectors representing screening times. The first element of each vector should always be 0 and the last element Inf in the case of right censoring.

Z.X

A numeric matrix of dimension n \times p_x containing covariates for the AFT incidence model. Missing values are not allowed.

Z.W

A numeric matrix of dimension n \times p_w containing covariates for the probit prevalence model. Missing values are not allowed.

r

A binary vector of length n indicating whether a baseline test was conducted (1 for yes, 0 for no / missing baseline test).

dist.X

Character. Specifies the distribution for the time-to-incidence variable; choices are 'weibull', 'lognormal', or 'loglog' (log-logistic).

kappa

Numeric. The test sensitivity value to be used if update.kappa = FALSE; otherwise, the starting value for estimating \kappa.

update.kappa

Logical. If TRUE, the test sensitivity (\kappa) is updated during the Gibbs sampler.

kappa.prior

A numeric vector of length 2. When specified, a Beta distribution prior is used for \kappa, centered at kappa.prior[1] with standard deviation kappa.prior[2]. If NULL, a uniform prior (Beta(1,1)) is used.

ndraws

Integer. The total number of MCMC draws for the main Gibbs sampler.

prop.sd.X

Numeric. The standard deviation for the proposal (jumping) distribution in the Metropolis sampler used for updating \beta_{xj}. Can be searched for automatically using search.prop.sd.

chains

Integer. The number of MCMC chains to run.

thining

Integer. The thinning interval for the MCMC sampler.

parallel

Logical. If TRUE, parallel processing is enabled for the Gibbs sampler. Each chain is assigned to one core (via the foreach package). Alternatively, use bayes.2S_seq which employs a for loop over the chains.

update.till.converge

Logical. If TRUE, the model is updated iteratively until convergence criteria are met. Convergence is assessed using the Gelman-Rubin diagnostic (R<1.1) and a minimum effective sample size (min_effss) for each parameter, respectively.

maxit

Numeric. The maximum number of MCMC draws allowed before interrupting the update process when update.till.converge is enabled. Default is Inf (i.e., no automatic interruption).

conv.crit

Character. Specifies whether the convergence check uses the point estimate ('point') or the upper bound ('upper') of the Gelman-Rubin diagnostic estimate (\hat{R}).

min_effss

Integer. The minimum effective sample size required for each parameter before convergence is accepted during iterative updating.

beta.prior

Character. Specifies the type of prior for the incidence regression coefficients (\beta_{xj}); options are 'norm' for normal and 't' for student-t.

beta.prior.X

Numeric. The hyperparameter for the prior distribution of the regression coefficients (\beta_{xj}) in the AFT incidence model. For a normal prior, this is the standard deviation; for a student-t prior, it represents the degrees of freedom. The default produces a standard-normal prior.

sig.prior.X

Numeric. The hyperparameter (standard deviation) for a half-normal prior on the scale parameter (\sigma) of the AFT incidence model.

tau.w

Numeric. The hyperparameter (standard deviation) for the normal prior distribution of the regression coefficients (\beta_{wj}) in the probit prevalence model. The default produces a standard-normal prior.

fix.sigma.X

Logical. If TRUE, the scale parameter (\sigma) in the AFT incidence model is fixed at the value provided in sig.prior.X; if FALSE, it is updated.

prev.run

Optional. An object of class BayesPIM containing results from a previous run. When provided, data and prior settings are adopted from the previous run, and the MCMC chain continues from the last draw.

update.burnin

Logical. If TRUE (default) and prev.run is provided, the burn-in period is updated to half of the total draws (sum of previous and current runs); otherwise, the burn-in is maintained as half of the draws from the initial run.

ndraws.update

Integer. The number of MCMC draws for updating a previous run or for convergence updates. If unspecified, ndraws is used.

prev

Logical. If TRUE, prevalence adjustment is applied; if FALSE, prevalence is assumed to be zero.

vanilla

Logical. If TRUE, a vanilla run is performed that assumes no prevalence adjustment and fixes \kappa = 1, equivalent to a standard Bayesian interval-censored survival regression.

ndraws.naive

Integer. The number of MCMC draws for a preliminary vanilla run used to obtain starting values. Increase if initial values lead to issues (e.g., an infinite posterior).

naive.run.prop.sd.X

Numeric. The standard deviation for the proposal distribution used in the vanilla run. Adjust only if the acceptance rate is significantly off target, as indicated by an interruption message.

par.exp

Logical. If TRUE, the parameter expansion technique of Liu & Wiu (1999) with a Haar prior is employed for updating the regression coefficients (\beta_{wj}) in the prevalence model. Experimental: tests suggest that it does not improve convergence or reduce autocorrelation.

collapsed.g

Logical. If TRUE, the latent prevalence class membership update in the Gibbs sampler is integrated (collapsed) over the latent incidence time variable. This setting is recommended to improve convergence.

k.prior

Experimental prior parameter for generalized gamma; currently not used.

fix.k

Experimental fixing of prior parameter for generalized gamma; currently not used.

Details

This function is dentical to bayes.2S with the only difference being that the chains MCMC chains are run in sequence using a for loop instead of parallel processing. This can be useful if operating systems do not support foreach or for simulation studies that parallize replication of experiments using foreach and/or need a worker that does not apply foreach internally.

Value

A list containing the following elements:

par.X.all

An mcmc.list of MCMC samples for the incidence and prevalence model parameters.

par.X.bi

An mcmc.list of MCMC samples for the incidence and prevalence model parameters after burn-in removal.

X

A matrix of posterior draws for the latent event times x_i, with one column per chain.

C

A matrix of posterior draws for prevalence class membership g_i, with one column per chain.

ac.X

A matrix with MCMC draws in rows and chains in columns, where each row indicates whether the Metropolis sampler accepted (1) or rejected (0) a sample.

ac.X.cur

Same as ac.X, but only for the last update.

dat

A data frame containing the last observed interval.

priors

A list of prior specifications for the model parameters, including beta.prior.X (incidence regression coefficients) and sig.prior.X (scale parameter for the AFT model).

runtime

The total runtime of the MCMC sampler.

Additionally, most input arguments are returned as part of the output for reference.

References

T. Klausch, B. I. Lissenberg-Witte, and V. M. Coupe (2024). "A Bayesian prevalence-incidence mixture model for screening outcomes with misclassification.", doi:10.48550/arXiv.2412.16065.

J. S. Liu and Y. N. Wu, “Parameter Expansion for Data Augmentation,” Journal of the American Statistical Association, vol. 94, no. 448, pp. 1264–1274, 1999, doi: 10.2307/2669940.

Examples


library(BayesPIM)

# Generate data according to the Klausch et al. (2025) PIM
set.seed(2025)
dat <- gen.dat(kappa = 0.7, n = 1e3, theta = 0.2,
               p = 1, p.discrete = 1,
               beta.X = c(0.2, 0.2), beta.W = c(0.2, 0.2),
               v.min = 20, v.max = 30, mean.rc = 80,
               sigma.X = 0.2, mu.X = 5, dist.X = "weibull",
               prob.r = 1)

# Initial model fit with fixed test sensitivity kappa (approx. 4-12 minutes runtime)
mod <- bayes.2S_seq(Vobs = dat$Vobs,
                Z.X = dat$Z,
                Z.W = dat$Z,
                r = dat$r,
                kappa = 0.7,
                update.kappa = FALSE,
                ndraws = 1e4,
                chains = 4,
                prop.sd.X = 0.008,
                parallel = TRUE,
                dist.X = "weibull")

# Inspect results
mod$runtime  # Runtime of the Gibbs sampler
plot(trim.mcmc(mod$par.X.all, thining = 10))  # MCMC chains including burn-in, also see ?trim.mcmc
plot(trim.mcmc(mod$par.X.bi, thining = 10))   # MCMC chains excluding burn-in
apply(mod$ac.X, 2, mean)  # Acceptance rates per chain
gelman.diag(mod$par.X.bi)  # Gelman convergence diagnostics

# Model updating
mod_update <- bayes.2S(prev.run = mod)      # Adds ndraws additional MCMC draws
mod_update <- bayes.2S(prev.run = mod, 
                       ndraws.update = 1e3) # Adds ndraws.update additional MCMC draws

# Example with kappa estimated/updated
mod2 <- bayes.2S_seq(Vobs = dat$Vobs,
                 Z.X = dat$Z,
                 Z.W = dat$Z,
                 r = dat$r,
                 kappa = 0.7,
                 update.kappa = TRUE,
                 kappa.prior = c(0.7, 0.1), # Beta prior, mean = 0.7, s.d. = 0.1
                 ndraws = 1e4,
                 chains = 4,
                 prop.sd.X = 0.008,
                 parallel = TRUE,
                 dist.X = "weibull")

# Inspect results
mod2$runtime # runtime of Gibbs sampler
plot( trim.mcmc( mod2$par.X.all, thining = 10) ) # kappa returned as part of the mcmc.list



[Package BayesPIM version 1.0.0 Index]