Package {buzzMed}

Internal Prior Table Printer

Description

Formats and displays the current parameter specifications in a clean, readable table within the R console.

Usage

.print_parms_table(parms)

Arguments

Value

No return value; called for side effects (printing to console).

Build JAGS Model String (Binary M & Binary Y)

Description

This internal function generates a JAGS model string using logistic regression (logit link) for both the mediator and outcome equations. It incorporates spike-and-slab variable selection on all mediation pathways.

Usage

build_ebmed_model_mcat_ycat(P, K, parms)

Arguments

Details

Constructs the JAGS model specification for a Bayesian mediation model where both mediators and the outcome are binary (0/1).

The model structure for dual-binary data:

• Mediator Models: M_k \sim Bernoulli(p_{m_k}), where logit(p_{m_k}) is a linear combination of predictors X.

• Outcome Model: Y \sim Bernoulli(p_y), where logit(p_y) is a linear combination of direct effects (X) and indirect effects (binary M).

• Variable Selection: Bernoulli hyperpriors (a.pip.hyperprior and b.pip.hyperprior) govern the inclusion of each path.

Value

A character string containing the full JAGS model specification.

See Also

buzzEBMcatMcatY, define_init_values

Build JAGS Model String (Binary M & Continuous Y)

Description

This internal function generates a JAGS model string using logistic regression (logit link) for the binary mediators and a Gaussian likelihood for the continuous outcome. It incorporates spike-and-slab variable selection on all mediation pathways.

Usage

build_ebmed_model_mcat_ycont(P, K, parms)

Arguments

Details

Constructs the JAGS model specification for a Bayesian mediation model where mediators are binary (0/1) and the outcome is continuous.

The model structure for binary mediators:

• Mediator Models: M_k \sim Bernoulli(p_{m_k}), where logit(p_{m_k}) is a linear combination of predictors X.

• Outcome Model: Y \sim Normal(\mu_y, \tau_y), where \mu_y includes both direct effects from X and indirect effects from binary M.

• Precision: Note that m.prec is not used in this formulation as the mediators are binary.

Value

A character string containing the full JAGS model specification.

See Also

buzzEBMcatMcontY, define_init_values

Build JAGS Model String (Continuous M & Binary Y)

Description

This internal function generates a JAGS model string that uses Gaussian likelihoods for the mediators and a logistic regression (logit link) for the binary outcome. It incorporates spike-and-slab variable selection on all mediation pathways.

Usage

build_ebmed_model_mcont_ycat(P, K, parms)

Arguments

Details

Constructs the JAGS model specification for a Bayesian mediation model where mediators are continuous and the outcome is binary (0/1).

The model uses a mixed-likelihood approach:

• Mediator Models: M_k \sim Normal(\mu_{M_k}, \tau_{M_k}). Variable selection is applied to the a-paths from X.

• Outcome Model: Y \sim Bernoulli(p_y), where logit(p_y) is a linear combination of predictors and mediators.

• Precision: Note that y.prec is not used in this formulation as the outcome is binary.

Value

A character string containing the full JAGS model specification.

See Also

buzzEBMcontMcatY, define_init_values

Build JAGS Model String (Continuous M & Continuous Y)

Description

This internal function dynamically generates a JAGS model string based on the number of predictors (P), mediators (K), and the prior distributions defined in the parms object. It handles the multivariate a-paths and b-paths using inprod (inner product) for efficiency in JAGS.

Usage

build_ebmed_model_mcont_ycont(P, K, parms)

Arguments

Details

Constructs the JAGS model specification for a Bayesian mediation model where both mediators and outcome are continuous, incorporating spike-and-slab variable selection.

The model structure follows a standard mediation framework:

• Mediator Models: Each mediator M_k is modeled as a linear combination of predictors X.

• Outcome Model: Y is modeled as a linear combination of predictors X (direct effects) and mediators M (indirect effects).

• Variable Selection: Uses Bernoulli-distributed indicators (a.pip and b.pip) to implement spike-and-slab priors on the mediation pathways.

Joint inclusion for a specific mediator pathway is calculated internally as ind.joint <- a.pip * b.pip.

Value

A character string containing the full JAGS model specification.

See Also

prepare_ebmed_data, define_init_values, buzzEBMcontMcontY

Fit Bayesian Mediation Model (Binary M & Binary Y)

Description

This function implements variable selection for mediators when dealing with binary data. It utilizes a latent probit link formulation to model the probabilities of the binary responses within the JAGS framework. It automates data preparation, JAGS model construction, and MCMC sampling.

Usage

buzzEBMcatMcatY(
  model,
  dataset,
  my_prior = NULL,
  advanced = NULL,
  a.coef.mean = NULL,
  a.coef.prec = NULL,
  b.coef.mean = NULL,
  b.coef.prec = NULL,
  a.pip.hyperalpha = NULL,
  a.pip.hyperbeta = NULL,
  b.pip.hyperalpha = NULL,
  b.pip.hyperbeta = NULL,
  direct.coef.mean = NULL,
  direct.coef.precision = NULL,
  direct.coef.init = NULL,
  a.pip.hyperprior.init = NULL,
  b.pip.hyperprior.init = NULL,
  n_chains = NULL,
  n_adapt = NULL,
  n_burnin = NULL,
  n_iter = NULL,
  thin = NULL
)

Arguments

Details

Fits a Bayesian mediation model specifically designed for cases where both the mediators (M) and the outcome variable (Y) are binary (0/1).

Since both M and Y are binary, residual precisions are not estimated (they are fixed to 1 in the latent probit space). This function identifies X, M, Y via .parse_buzz_syntax and routes the data through an internal pipeline including prepare_ebmed_data and build_ebmed_model_mcat_ycat.

Value

An object of class mcmc.list containing posterior samples.

Note

This function is strictly for binary data. For variables with more than two levels, please convert them into dummy variables or ensure they are binary before running.

References

Shi, D., Shi, D., and Fairchild, A. J. (2023) "Variable Selection for Mediators under a Bayesian Mediation Model" <doi:10.1080/10705511.2022.2164285>

Examples

# Binary case: Both M and Y are Binary
set.seed(101)
n <- 100
toy_data <- data.frame(
   X = rbinom(n, 1, 0.5),
   M1 = rbinom(n, 1, 0.3),
   M2 = rbinom(n, 1, 0.7),
   Y = rbinom(n, 1, 0.5)
)

# Fit the model
results <- buzzEBMcatMcatY(
   model    = "Y ~ M1 + M2 | X",
   dataset  = toy_data,
   n_burnin = 200,
   n_iter   = 1000
)

summary(results)

Fit Bayesian Mediation Model (Binary M & Continuous Y)

Description

This function implements variable selection for mediators in a mixed data framework. It utilizes latent variable formulations for the binary mediators and a Gaussian likelihood for the continuous outcome. It automates data preparation, JAGS model construction, and MCMC sampling.

Usage

buzzEBMcatMcontY(
  model,
  dataset,
  my_prior = NULL,
  advanced = NULL,
  y.prec.shape = NULL,
  y.prec.rate = NULL,
  a.coef.mean = NULL,
  a.coef.prec = NULL,
  b.coef.mean = NULL,
  b.coef.prec = NULL,
  a.pip.hyperalpha = NULL,
  a.pip.hyperbeta = NULL,
  b.pip.hyperalpha = NULL,
  b.pip.hyperbeta = NULL,
  direct.coef.mean = NULL,
  direct.coef.precision = NULL,
  y.prec.init = NULL,
  direct.coef.init = NULL,
  a.pip.hyperprior.init = NULL,
  b.pip.hyperprior.init = NULL,
  n_chains = NULL,
  n_adapt = NULL,
  n_burnin = NULL,
  n_iter = NULL,
  thin = NULL
)

Arguments

Details

Fits a Bayesian mediation model specifically designed for cases where the mediators (M) are binary (0/1) and the outcome variable (Y) is continuous.

This function is a specific "worker" function. It identifies X, M, Y via .parse_buzz_syntax. While Y is modeled with residual precision parameters, the mediators M are binary and thus their residual precisions are fixed to 1 within the latent variable framework.

Value

An object of class mcmc.list containing posterior samples.

References

Shi, D., Shi, D., and Fairchild, A. J. (2023) "Variable Selection for Mediators under a Bayesian Mediation Model" <doi:10.1080/10705511.2022.2164285>

Examples

# Mixed case: Binary M, Continuous Y
set.seed(789)
n <- 100
toy_data <- data.frame(
   X = rnorm(n),
   M1 = rbinom(n, 1, 0.4),
   M2 = rbinom(n, 1, 0.6),
   Y = rnorm(n)
)

# Fit the model
results <- buzzEBMcatMcontY(
   model    = "Y ~ M1 + M2 | X",
   dataset  = toy_data,
   n_burnin = 200,
   n_iter   = 1000
)

summary(results)

Fit Bayesian Mediation Model (Continuous M & Binary Y)

Description

This function implements variable selection for mediators in a mixed data framework. It assumes a Gaussian likelihood for the mediators and a latent probit link for the binary outcome. It automates data preparation, JAGS model construction, and MCMC sampling.

Usage

buzzEBMcontMcatY(
  model,
  dataset,
  my_prior = NULL,
  advanced = NULL,
  m.prec.shape = NULL,
  m.prec.rate = NULL,
  a.coef.mean = NULL,
  a.coef.prec = NULL,
  b.coef.mean = NULL,
  b.coef.prec = NULL,
  a.pip.hyperalpha = NULL,
  a.pip.hyperbeta = NULL,
  b.pip.hyperalpha = NULL,
  b.pip.hyperbeta = NULL,
  direct.coef.mean = NULL,
  direct.coef.precision = NULL,
  m.prec.init = NULL,
  direct.coef.init = NULL,
  a.pip.hyperprior.init = NULL,
  b.pip.hyperprior.init = NULL,
  n_chains = NULL,
  n_adapt = NULL,
  n_burnin = NULL,
  n_iter = NULL,
  thin = NULL
)

Arguments

Details

Fits a Bayesian mediation model specifically designed for cases where the mediators (M) are continuous and the outcome variable (Y) is binary (0/1).

This function is a specific "worker" function. It identifies X, M, Y via .parse_buzz_syntax. While M is modeled with residual precision parameters, Y is binary and thus its residual precision is fixed to 1 within the latent variable framework.

Value

An object of class mcmc.list containing posterior samples.

References

Shi, D., Shi, D., and Fairchild, A. J. (2023) "Variable Selection for Mediators under a Bayesian Mediation Model" <doi:10.1080/10705511.2022.2164285>

Examples

# Mixed case: Continuous M, Binary Y
set.seed(456)
n <- 100
toy_data <- data.frame(
   X = rnorm(n),
   M1 = rnorm(n),
   M2 = rnorm(n),
   Y = rbinom(n, 1, 0.5)
)

# Fit the model
results <- buzzEBMcontMcatY(
   model    = "Y ~ M1 + M2 | X",
   dataset  = toy_data,
   n_burnin = 200,
   n_iter   = 1000
)

summary(results)

Fit Bayesian Mediation Model (Continuous M & Continuous Y)

Description

This function implements variable selection for mediators in a fully continuous framework. It automates data preparation, JAGS model construction using Gaussian likelihoods, and MCMC sampling.

Usage

buzzEBMcontMcontY(
  model,
  dataset,
  my_prior = NULL,
  advanced = NULL,
  m.prec.shape = NULL,
  m.prec.rate = NULL,
  y.prec.shape = NULL,
  y.prec.rate = NULL,
  a.coef.mean = NULL,
  a.coef.prec = NULL,
  b.coef.mean = NULL,
  b.coef.prec = NULL,
  a.pip.hyperalpha = NULL,
  a.pip.hyperbeta = NULL,
  b.pip.hyperalpha = NULL,
  b.pip.hyperbeta = NULL,
  direct.coef.mean = NULL,
  direct.coef.precision = NULL,
  m.prec.init = NULL,
  y.prec.init = NULL,
  direct.coef.init = NULL,
  a.pip.hyperprior.init = NULL,
  b.pip.hyperprior.init = NULL,
  n_chains = NULL,
  n_adapt = NULL,
  n_burnin = NULL,
  n_iter = NULL,
  thin = NULL
)

Arguments

Details

Fits a Bayesian mediation model specifically designed for cases where both the mediators (M) and the outcome variable (Y) are continuous.

This function is a specific "worker" function. It identifies X, M, Y via .parse_buzz_syntax and performs Bayesian estimation assuming: M \sim Normal(\dots) and Y \sim Normal(\dots).

Value

An object of class mcmc.list containing posterior samples.

References

Shi, D., Shi, D., and Fairchild, A. J. (2023) "Variable Selection for Mediators under a Bayesian Mediation Model" <doi:10.1080/10705511.2022.2164285>

Examples

# 1. Create a continuous synthetic dataset
set.seed(123)
n <- 100
toy_data <- data.frame(
   X = rnorm(n),
   M1 = rnorm(n),
   M2 = rnorm(n),
   Y = rnorm(n)
)

# 2. Fit the model using lavaan-style syntax
# We define Y as the outcome, with M1, M2, and X as predictors
results <- buzzEBMcontMcontY(
   model    = "Y ~ M1 + M2 | X",
   dataset  = toy_data,
   n_burnin = 500,
   n_iter   = 2000
)

# 3. Check results
summary(results)

Define Initial Values for Bayesian Mediation Model

Description

This internal function constructs the starting values for both the parameters (coefficients and precisions) and the latent variables (inclusion indicators). It handles the conditional inclusion of precision parameters based on whether the mediators and outcome are continuous.

Usage

define_init_values(
  P,
  K,
  M_cont,
  Y_cont,
  m.prec.init,
  y.prec.init,
  direct.coef.init,
  a.pip.hyperprior.init,
  b.pip.hyperprior.init
)

Arguments

Details

Generates a named list of initial values for MCMC chains, specifically tailored for the Bayesian mediation model with variable selection.

The function uses the null-coalescing operator %||% to apply system defaults when NULL values are passed from the main wrapper functions.

Value

A named list of initial values compatible with JAGS:

m.prec

Numeric vector of length K (if M_cont = TRUE).

a.coef

Numeric matrix of dimension K x P, initialized to 0.

a.pip

Binary vector of length K, initialized to 0.

b.coef

Numeric vector of length K, initialized to 0.

b.pip

Binary vector of length K, initialized to 0.

y.prec

Numeric scalar (if Y_cont = TRUE).

direct.coef

Numeric vector of length P, initialized to direct.coef.init.

a.pip.hyperprior

Numeric scalar.

b.pip.hyperprior

Numeric scalar.

Extract and Rename Mediation Results from JAGS Output

Description

Parses the summary statistics from a coda MCMC output object and extracts rows corresponding to ind.joint, a.pip.hyperprior, and b.pip.hyperprior.

Usage

extract_results(output, M)

Arguments

Value

A named numeric matrix.

Create Parameter Mapping from Individual Arguments

Description

This internal worker function compiles individual numeric prior arguments into the standard parameters data frame used for JAGS model construction.

Usage

make_parms_from_argument(
  a.coef.mean = NULL,
  a.coef.prec = NULL,
  b.coef.mean = NULL,
  b.coef.prec = NULL,
  m.prec.shape = NULL,
  m.prec.rate = NULL,
  y.prec.shape = NULL,
  y.prec.rate = NULL,
  a.pip.hyperalpha = NULL,
  a.pip.hyperbeta = NULL,
  b.pip.hyperalpha = NULL,
  b.pip.hyperbeta = NULL,
  direct.coef.mean = NULL,
  direct.coef.precision = NULL
)

Arguments

Details

This function is called by make_parms_main when a user provides individual named arguments. It performs several key tasks:

• Partial Override Handling: If only one parameter of a pair is provided (e.g., shape but not rate), it uses the system default for the missing value and issues a warning.

• Coercion: Ensures all inputs are treated as numeric.

• Validation: Checks values against distribution-specific range rules (e.g., ensuring Gamma shapes are positive).

Value

A data.frame containing columns: priors, distribution, arguments, and template.

See Also

make_parms_main

Create Parameter Mapping from Data Frame

Description

This internal worker function validates and merges a user-supplied prior specification data frame with the system defaults.

Usage

make_parms_from_df(my_prior)

Arguments

Details

This function is called by make_parms_main when a user provides a custom prior data frame (Method 2) or completes the interactive wizard. It enforces the following logic:

• Structural Validation: Ensures the input is a data frame with all three required columns.

• Prior Filtering: Any unrecognized priors (those not present in system defaults) are dropped with a warning.

• Missing Priors: Any required priors missing from the user's data frame are filled using system defaults, and a warning is issued.

• Immutable Templates: The template column is always sourced from .make_default_parms and cannot be overridden, ensuring the JAGS model structure remains valid.

• Argument Validation: Arguments are split, coerced to numeric (except for a.coef and b.coef hyperprior references), and checked against distribution-specific range rules.

Value

A validated data.frame with columns: priors, distribution, arguments, and template.

See Also

make_parms_main, run_parms_wizard

Internal Router for Parameter Dataframe Construction

Description

This function is the central hub for resolving prior specifications. It determines which method of parameter construction to use based on user input, enforcing a strict hierarchy to handle overlapping arguments.

Usage

make_parms_main(
  m.prec.shape = NULL,
  m.prec.rate = NULL,
  y.prec.shape = NULL,
  y.prec.rate = NULL,
  a.coef.mean = NULL,
  a.coef.prec = NULL,
  b.coef.mean = NULL,
  b.coef.prec = NULL,
  a.pip.hyperalpha = NULL,
  a.pip.hyperbeta = NULL,
  b.pip.hyperalpha = NULL,
  b.pip.hyperbeta = NULL,
  direct.coef.mean = NULL,
  direct.coef.precision = NULL,
  my_prior = NULL,
  advanced = NULL
)

Arguments

Details

The function evaluates inputs in the following **Priority Order**:

1. Skip to Named Arguments (Trigger: advanced = FALSE)

   • Bypasses my_prior and the wizard entirely.

   • If named arguments are provided, calls make_parms_from_argument.

   • If no named arguments are provided, falls back to system defaults.

   • Note: my_prior is ignored with a message.

2. Interactive Wizard (Trigger: advanced = "interactive")

   • Calls run_parms_wizard.

   • If the user completes the wizard, the result is passed to make_parms_from_df.

   • If the user cancels, it falls back to system defaults.

   • Note: All other arguments are ignored with a message.

3. Use my_prior Directly (Trigger: advanced = "myprior")

   • Requires my_prior to be non-NULL; errors otherwise.

   • Passes my_prior directly to make_parms_from_df.

   • Note: Named arguments are ignored with a message.

4. Standard Routing (Trigger: advanced = NULL)

   • User Dataframe: if my_prior is not NULL, validates and passes it to make_parms_from_df. Named arguments are ignored with a message.

   • Named Arguments: if any Method 1 argument is not NULL, compiles them and calls make_parms_from_argument.

   • System Defaults: silent fallback if nothing else is provided.

Value

A validated data.frame of parameters (priors, distribution, arguments) ready for model use.

Prepare Data for buzzMed Model

Description

This internal helper extracts the predictor(s), mediators, and outcome from the dataset, handles matrix conversions for the predictors, and creates a named list of mediators (m1, m2, ... mk) to match the indexing used in the generated JAGS model strings.

Usage

prepare_ebmed_data(dataset, X, M, Y, M_cont, Y_cont)

Arguments

Details

Converts a user-supplied data frame into the specific list format required by the Bayesian mediation JAGS models.

Predictors are converted to a matrix to allow for multivariate X (e.g., when including covariates). Mediators are split into individual list elements to simplify the JAGS for loops.

Value

A list containing:

N

Integer. The number of observations (rows).

X

Numeric matrix of predictors.

y

Numeric vector (or binary 0/1 vector) of the outcome.

m1, m2, ...

Individual numeric vectors for each mediator.

Execute JAGS MCMC Sampling for Exploratory Bayesian Mediation Models

Description

A worker function that handles the technical execution of the MCMC chains. It dynamically determines which parameters to monitor based on the distributional assumptions (continuous vs. binary) of the mediators and outcome.

Usage

run_ebmed_jags(
  modelstring,
  bdata,
  init,
  M_cont,
  Y_cont,
  n_chains,
  n_adapt,
  n_burnin,
  n_iter,
  thin
)

Arguments

Details

This internal function interfaces with the rjags package to initialize the model, perform burn-in, and collect posterior samples.

The function follows the standard JAGS workflow:

1. Initialization: Calls jags.model with adaptation.

2. Burn-in: Discards initial samples using update.

3. Sampling: Collects final posteriors via coda.samples.

Parameters monitored by default include coefficients (a, b, direct.coef), inclusion probabilities (pip), and joint inclusion indicators (ind.joint).

Value

A coda::mcmc.list object containing the posterior samples for the monitored parameters.

Interactive Prior Specification Wizard

Description

This function allows users to customize priors without needing to manually construct complex data frames. It displays current defaults, allows selection of specific parameters to change, and provides a menu of available JAGS distributions (e.g., Normal, Gamma, Beta).

Usage

run_parms_wizard(verbose = TRUE)

Arguments

Details

Launches an interactive console-based interface to guide users through viewing and modifying Bayesian prior distributions for mediation models.

The wizard handles two main types of customization:

• Distribution Selection: Choose from supported JAGS distributions.

• Argument Specification: Set numeric values for hyperparameters (e.g., shape, rate, mean, precision).

For coefficients like a and b, the wizard will note if they reference hyperpriors (back-references). It is generally recommended to modify the shape of the hyperprior rather than the coefficient's distribution directly to maintain the hierarchical structure.

Value

A data.frame with columns priors, distribution, and arguments. This dataframe is formatted to be passed directly to the my_prior argument in related fitting functions.

Note

This function requires an interactive R session. It will return invisible(NULL) if the user cancels the process.

Examples

# Create toy data
toy_data <- data.frame(
   X = rbinom(100, 1, 0.5),
   M = rbinom(100, 1, 0.3),
   Y = rbinom(100, 1, 0.5)
)

custom_priors <- NULL

if (interactive()){
# Launch the wizard
custom_priors <- run_parms_wizard()
}

# Use the resulting object in a model
fit <- buzzEBMcatMcatY(model = "Y ~ M | X",
                     dataset = toy_data,
                     my_prior = custom_priors)