| Version: | 0.1.3 |
| Date: | 2026-07-16 |
| Title: | Bayesian Understanding for Mediator Selection Framework |
| Description: | A collection of quantitative tools for selecting mediating effects within exploratory Bayesian mediation models. The package accommodates both continuous and dichotomous outcomes, including the dependent variables and the mediators for identifying and analyzing mediation pathways. |
| License: | GPL (≥ 3) |
| Depends: | R (≥ 4.0.0) |
| SystemRequirements: | JAGS (>= 4.0.0) |
| Imports: | coda, methods, rjags, stats, utils |
| Suggests: | knitr, rmarkdown, spelling, testthat (≥ 3.0.0) |
| LazyData: | true |
| ByteCompile: | true |
| VignetteBuilder: | knitr |
| URL: | https://github.com/olfactorybulb/buzzMed |
| BugReports: | https://github.com/olfactorybulb/buzzMed/issues |
| Encoding: | UTF-8 |
| Language: | en-US |
| RoxygenNote: | 7.3.3 |
| NeedsCompilation: | no |
| Packaged: | 2026-07-16 19:04:53 UTC; jesshsing |
| Author: | Dingjing Shi [aut, cre], Tansu Celikel [aut], Chih-Chia Hsing [aut], Dexin Shi [aut] |
| Maintainer: | Dingjing Shi <dshi32@gatech.edu> |
| Repository: | CRAN |
| Date/Publication: | 2026-07-16 20:00:02 UTC |
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
parms |
A |
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
P |
Integer. The number of predictors/covariates. |
K |
Integer. The number of mediators. |
parms |
A |
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}), wherelogit(p_{m_k})is a linear combination of predictorsX. -
Outcome Model:
Y \sim Bernoulli(p_y), wherelogit(p_y)is a linear combination of direct effects (X) and indirect effects (binaryM). -
Variable Selection: Bernoulli hyperpriors (
a.pip.hyperpriorandb.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
P |
Integer. The number of predictors/covariates. |
K |
Integer. The number of mediators. |
parms |
A |
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}), wherelogit(p_{m_k})is a linear combination of predictorsX. -
Outcome Model:
Y \sim Normal(\mu_y, \tau_y), where\mu_yincludes both direct effects fromXand indirect effects from binaryM. -
Precision: Note that
m.precis 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
P |
Integer. The number of predictors/covariates. |
K |
Integer. The number of mediators. |
parms |
A |
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 thea-paths fromX. -
Outcome Model:
Y \sim Bernoulli(p_y), wherelogit(p_y)is a linear combination of predictors and mediators. -
Precision: Note that
y.precis 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
P |
Integer. The number of predictors/covariates. |
K |
Integer. The number of mediators. |
parms |
A |
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_kis modeled as a linear combination of predictorsX. -
Outcome Model:
Yis modeled as a linear combination of predictorsX(direct effects) and mediatorsM(indirect effects). -
Variable Selection: Uses Bernoulli-distributed indicators (
a.pipandb.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
Select binary mediators using the GT-exploratory Bayesian mediation model with dichotomous dependent variables.
Description
This function selects time-invariant binary mediators using the generalized two-stage exploratory Bayesian mediation model with dichotomous dependent variables.
Usage
buzzEBMcatMcatY(
model,
dataset,
my_prior = NULL,
advanced = 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
model |
A character string specifying the mediation model to be
fitted. The model should be specified using the syntax
|
dataset |
A |
my_prior |
Optional |
advanced |
Character. Use |
a.pip.hyperalpha |
Numeric scalar or vector. Alpha hyperparameter of
the Beta prior distribution for the |
a.pip.hyperbeta |
Numeric scalar or vector. Beta hyperparameter of
the Beta prior distribution for the |
b.pip.hyperalpha |
Numeric scalar or vector. Alpha hyperparameter of
the Beta prior distribution for the |
b.pip.hyperbeta |
Numeric scalar or vector. Beta hyperparameter of
the Beta prior distribution for the |
direct.coef.mean |
Numeric scalar or vector. Mean parameter of the
Normal prior distribution for the direct effects ( |
direct.coef.precision |
Numeric scalar or vector. Precision parameter
of the Normal prior distribution for the direct effects ( |
direct.coef.init |
Numeric or |
a.pip.hyperprior.init |
Numeric or |
b.pip.hyperprior.init |
Numeric or |
n_chains |
Integer. Number of MCMC chains. |
n_adapt |
Integer. Number of adaptation iterations. |
n_burnin |
Integer. Number of burn-in iterations. |
n_iter |
Integer. Number of post-burn-in iterations. |
thin |
Integer. Thinning interval. |
Details
Fits a generalized two-stage exploratory Bayesian mediation model, specifically
designed for cases where both the mediators (M) and the outcome
variable (Y) are binary (0/1).
Value
A matrix of posterior summary statistics for the monitored parameters.
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 ~ X | M1 + M2",
dataset = toy_data,
n_burnin = 200,
n_iter = 1000
)
summary(results)
Select binary mediators using the GT-exploratory Bayesian mediation model with continuous dependent variables.
Description
This function selects time-invariant binary mediators using the generalized two-stage exploratory Bayesian mediation model with continuous dependent variables.
Usage
buzzEBMcatMcontY(
model,
dataset,
my_prior = NULL,
advanced = 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,
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
model |
A character string specifying the mediation model to be
fitted. The model should be specified using the syntax
|
dataset |
A |
my_prior |
Optional |
advanced |
Character. Use |
y.prec.shape |
Numeric scalar. Shape hyperparameter of the Gamma prior distribution for the outcome residual precision. The default value is 1. |
y.prec.rate |
Numeric scalar. Rate hyperparameter of the Gamma prior distribution for the outcome residual precision. The default value is 0.001. |
a.pip.hyperalpha |
Numeric scalar or vector. Alpha hyperparameter of
the Beta prior distribution for the |
a.pip.hyperbeta |
Numeric scalar or vector. Beta hyperparameter of
the Beta prior distribution for the |
b.pip.hyperalpha |
Numeric scalar or vector. Alpha hyperparameter of
the Beta prior distribution for the |
b.pip.hyperbeta |
Numeric scalar or vector. Beta hyperparameter of
the Beta prior distribution for the |
direct.coef.mean |
Numeric scalar or vector. Mean parameter of the
Normal prior distribution for the direct effects ( |
direct.coef.precision |
Numeric scalar or vector. Precision parameter
of the Normal prior distribution for the direct effects ( |
y.prec.init |
Numeric or |
direct.coef.init |
Numeric or |
a.pip.hyperprior.init |
Numeric or |
b.pip.hyperprior.init |
Numeric or |
n_chains |
Integer. Number of MCMC chains. |
n_adapt |
Integer. Number of adaptation iterations. |
n_burnin |
Integer. Number of burn-in iterations. |
n_iter |
Integer. Number of post-burn-in iterations. |
thin |
Integer. Thinning interval. |
Details
Fits a generalized two-stage exploratory Bayesian mediation model,
specifically designed for cases where the mediators (M) are
binary (0/1) and the outcome variable (Y) is continuous.
Value
A matrix of posterior summary statistics for the monitored parameters.
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 ~ X | M1 + M2",
dataset = toy_data,
n_burnin = 200,
n_iter = 1000
)
summary(results)
Select continuous mediators using the GT-exploratory Bayesian mediation model with dichotomous dependent variables.
Description
This function selects time-invariant continuous mediators using the generalized two-stage exploratory Bayesian mediation model with dichotomous dependent variables.
Usage
buzzEBMcontMcatY(
model,
dataset,
my_prior = NULL,
advanced = NULL,
m.prec.shape = NULL,
m.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,
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
model |
A character string specifying the mediation model to be
fitted. The model should be specified using the syntax
|
dataset |
A |
my_prior |
Optional |
advanced |
Character. Use |
m.prec.shape |
Numeric scalar or vector of length equal to the number of mediators. Shape hyperparameter of the Gamma prior distribution for the mediator residual precisions. The default value is 1. |
m.prec.rate |
Numeric scalar or vector of length equal to the number of mediators. Rate hyperparameter of the Gamma prior distribution for the mediator residual precisions. The default value is 0.001. |
a.pip.hyperalpha |
Numeric scalar or vector. Alpha hyperparameter of
the Beta prior distribution for the |
a.pip.hyperbeta |
Numeric scalar or vector. Beta hyperparameter of
the Beta prior distribution for the |
b.pip.hyperalpha |
Numeric scalar or vector. Alpha hyperparameter of
the Beta prior distribution for the |
b.pip.hyperbeta |
Numeric scalar or vector. Beta hyperparameter of
the Beta prior distribution for the |
direct.coef.mean |
Numeric scalar or vector. Mean parameter of the
Normal prior distribution for the direct effects ( |
direct.coef.precision |
Numeric scalar or vector. Precision parameter
of the Normal prior distribution for the direct effects ( |
m.prec.init |
Numeric or |
direct.coef.init |
Numeric or |
a.pip.hyperprior.init |
Numeric or |
b.pip.hyperprior.init |
Numeric or |
n_chains |
Integer. Number of MCMC chains. |
n_adapt |
Integer. Number of adaptation iterations. |
n_burnin |
Integer. Number of burn-in iterations. |
n_iter |
Integer. Number of post-burn-in iterations. |
thin |
Integer. Thinning interval. |
Details
Fits a generalized two-stage exploratory Bayesian mediation model,
specifically designed for cases where the mediators (M) are continuous
and the outcome variable (Y) is binary (0/1).
Value
A matrix of posterior summary statistics for the monitored parameters.
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 ~ X | M1 + M2",
dataset = toy_data,
n_burnin = 200,
n_iter = 1000
)
summary(results)
Select continuous mediators using the GT-exploratory Bayesian mediation model with continuous dependent variables.
Description
This function selects time-invariant continuous mediators using the generalized two-stage exploratory Bayesian mediation model with continuous dependent variables.
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.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
model |
A character string specifying the mediation model to be
fitted. The model should be specified using the syntax
|
dataset |
A |
my_prior |
Optional |
advanced |
Character. Use |
m.prec.shape |
Numeric scalar or vector of length equal to the number of mediators. Shape hyperparameter of the Gamma prior distribution for the mediator residual precisions. The default value is 1. |
m.prec.rate |
Numeric scalar or vector of length equal to the number of mediators. Rate hyperparameter of the Gamma prior distribution for the mediator residual precisions. The default value is 0.001. |
y.prec.shape |
Numeric scalar. Shape hyperparameter of the Gamma prior distribution for the outcome residual precision. The default value is 1. |
y.prec.rate |
Numeric scalar. Rate hyperparameter of the Gamma prior distribution for the outcome residual precision. The default value is 0.001. |
a.pip.hyperalpha |
Numeric scalar or vector. Alpha hyperparameter of
the Beta prior distribution for the |
a.pip.hyperbeta |
Numeric scalar or vector. Beta hyperparameter of
the Beta prior distribution for the |
b.pip.hyperalpha |
Numeric scalar or vector. Alpha hyperparameter of
the Beta prior distribution for the |
b.pip.hyperbeta |
Numeric scalar or vector. Beta hyperparameter of
the Beta prior distribution for the |
direct.coef.mean |
Numeric scalar or vector. Mean parameter of the
Normal prior distribution for the direct effects ( |
direct.coef.precision |
Numeric scalar or vector. Precision parameter
of the Normal prior distribution for the direct effects ( |
m.prec.init |
Numeric or |
y.prec.init |
Numeric or |
direct.coef.init |
Numeric or |
a.pip.hyperprior.init |
Numeric or |
b.pip.hyperprior.init |
Numeric or |
n_chains |
Integer. Number of MCMC chains. |
n_adapt |
Integer. Number of adaptation iterations. |
n_burnin |
Integer. Number of burn-in iterations. |
n_iter |
Integer. Number of post-burn-in iterations. |
thin |
Integer. Thinning interval. |
Details
Fits a generalized two-stage exploratory Bayesian mediation model, specifically
designed for cases where both the mediators (M) and the outcome variable
(Y) are continuous.
Value
A matrix of posterior summary statistics for the monitored parameters.
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 ~ X | M1 + M2",
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
P |
Integer. Number of predictors ( |
K |
Integer. Number of mediators ( |
M_cont |
Logical. If |
Y_cont |
Logical. If |
m.prec.init, y.prec.init |
Numeric or |
direct.coef.init |
Numeric or |
a.pip.hyperprior.init, b.pip.hyperprior.init |
Numeric or |
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.precNumeric vector of length
K(ifM_cont = TRUE).a.coefNumeric matrix of dimension
K x P, initialized to 0.a.pipBinary vector of length
K, initialized to 0.b.coefNumeric vector of length
K, initialized to 0.b.pipBinary vector of length
K, initialized to 0.y.precNumeric scalar (if
Y_cont = TRUE).direct.coefNumeric vector of length
P, initialized todirect.coef.init.a.pip.hyperpriorNumeric scalar.
b.pip.hyperpriorNumeric 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
output |
An |
M |
Character vector of mediator variable names. |
Value
A named numeric matrix.
Modified framing dataset with some dichotomization
Description
A modified version of the framing dataset from the
mediation package, originally based on the study by
Brader, Valentino, and Suhay (2008). The candidate mediators have been
dichotomized relative to the original framing dataset. The dataset
contains 265 observations and 10 variables.
Usage
framing2
Format
A data frame with 265 observations and 10 variables:
- tone
From the original
framingdataset. First treatment; whether the news story is framed positively or negatively.- eth
From the original
framingdataset. Second treatment; whether the news story features a Latino or European immigrant.- treat
From the original
framingdataset. Product of the two treatment variables. In the original study the authors only find this cell to be significant.- negemo2
Recoded from the
emovariable in the originalframingdataset. Binary variable of subjects' negative feelings during the experiment. A value of 1 indicates an original score of 3–7, corresponding to stronger negative emotions, whereas a value of 0 indicates an original score of 8–12.- p_harm2
Recoded from the
p_harmvariable in the originalframingdataset. Binary variable of subjects' perceived harm caused by increased immigration. A value of 1 indicates an original score of 6–8, whereas a value of 0 indicates a score of 2–5.- att2
Recoded from the
immigrvariable in the originalframingdataset. Binary variable measuring subjects' attitudes toward increased immigration. A value of 1 indicates an original score of 3 or 4, corresponding to more negative attitudes toward increased immigration. A value of 0 indicates an original score of 1 or 2.- anx2
Recoded from the
anxvariable in the originalframingdataset. Binary variable measuring subjects' anxiety about increased immigration. A value of 1 indicates respondents who reported being “very anxious” or “somewhat anxious” about increased immigration. A value of 0 indicates respondents who reported being “a little anxious” or “not anxious at all”.- english2
Recoded from the
englishvariable in the originalframingdataset. Binary variable measuring support for making English the official language of the United States. A value of 1 indicates respondents who selected “Favor” or “Strongly Favor”. A value of 0 indicates respondents who selected “Oppose” or “Strongly Oppose”.- congmsg
From the original
cong_mesgvariable in theframingdataset. Whether subjects requested sending an anti-immigration message to Congress on their behalf.- info
From the original
anti_infovariable in theframingdataset. Whether subjects wanted to receive information from anti-immigration organizations.
Source
Adapted from the framing dataset in the mediation package.
References
Brader, T., Valentino, N. A., & Suhay, E. (2008). What Triggers Public Opposition to Immigration? Anxiety, Group Cues, and Immigration Threat. American Journal of Political Science, 52(4), 959–978.
Select time-varying mediators using the longitudinal Bayesian mediation selection model
Description
This function selects time-varying mediators using the longitudinal Bayesian mediation selection model.
Usage
longBMed(model = NULL, data, n.burnin = 3000, n.iter = 6000, thin = 1)
Arguments
model |
Specifies how variables are assigned to the outcome(Y),
predictor(s)(X), and candidate mediator(s) (M).
The format depends on the type of Named list or data frame: A character string of the form
3-D array: A character string of the form |
data |
One of:
|
n.burnin |
Integer. Number of burn-in iterations. Default |
n.iter |
Integer. Number of posterior samples after burn-in.
Default |
thin |
Integer. Thinning interval. Default |
Details
The model supports one or more predictor variables (X), one or more
candidate mediators (M), and exactly one outcome variable (Y). Data may be
supplied as an N \times T \times K numeric array, a named list
of N \times T matrices, or a data frame in long format.
For a named list or long-format data frame, the model can be specified using
variable names, such as "Y ~ X1 + X2 | M1 + M2".
For a 3-D array, the model can be specified using integer slice indices,
such as "21 ~ 1 | 2:20", where the left side specifies the outcome,
the expression before | specifies the predictor(s), and the
expression after | specifies the mediator(s).
Value
A matrix of posterior summary statistics from
summary(output)$statistics, including posterior means, standard
deviations, and standard errors for ind.joint and ind.p.
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
a.coef.mean, a.coef.prec |
Numeric. Mean and precision for the
|
b.coef.mean, b.coef.prec |
Numeric. Mean and precision for the
|
m.prec.shape, m.prec.rate |
Numeric. Shape and rate for the mediator
residual precision ( |
y.prec.shape, y.prec.rate |
Numeric. Shape and rate for the outcome
residual precision ( |
a.pip.hyperalpha, a.pip.hyperbeta |
Numeric. Alpha and beta parameters
for the |
b.pip.hyperalpha, b.pip.hyperbeta |
Numeric. Alpha and beta parameters
for the |
direct.coef.mean, direct.coef.precision |
Numeric. Mean and precision
for the direct effect ( |
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
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
my_prior |
A |
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
templatecolumn is always sourced from.make_default_parmsand cannot be overridden, ensuring the JAGS model structure remains valid. -
Argument Validation: Arguments are split, coerced to numeric (except for
a.coefandb.coefhyperprior 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.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
m.prec.shape, m.prec.rate, y.prec.shape, y.prec.rate, a.pip.hyperalpha, a.pip.hyperbeta, b.pip.hyperalpha, b.pip.hyperbeta, direct.coef.mean, direct.coef.precision |
Numeric. Individual prior parameters (Method 1). |
my_prior |
A data frame or list provided by the user (Method 2). Lists are automatically coerced to data frames. |
advanced |
Controls routing override behavior. Acceptable values:
|
Details
The function evaluates inputs in the following **Priority Order**:
-
Skip to Named Arguments (Trigger:
advanced = FALSE)Bypasses
my_priorand 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_prioris ignored with a message.
-
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.
-
Use my_prior Directly (Trigger:
advanced = "myprior")Requires
my_priorto be non-NULL; errors otherwise.Passes
my_priordirectly tomake_parms_from_df.-
Note: Named arguments are ignored with a message.
-
Standard Routing (Trigger:
advanced = NULL)-
User Dataframe: if
my_prioris not NULL, validates and passes it tomake_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
dataset |
A |
X |
Character vector naming the predictor variable(s). |
M |
Character vector naming mediator variables. |
Y |
Character string naming the outcome variable. |
M_cont |
Logical. Should |
Y_cont |
Logical. Should |
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:
NInteger. The number of observations (rows).
XNumeric matrix of predictors.
yNumeric 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
modelstring |
Character string containing the generated JAGS model code. |
bdata |
Named list of data (N, X, y, m1, m2...) for JAGS. |
init |
Named list of starting values for the parameters. |
Y_cont, M_cont |
Logical flags indicating the nature of the variables.
These determine whether residual precisions ( |
n_chains, n_adapt, n_burnin, n_iter, thin |
Integer. MCMC tuning
parameters. If |
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:
-
Initialization: Calls
jags.modelwith adaptation. -
Burn-in: Discards initial samples using
update. -
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 probabilistic distributions (e.g., Normal, Gamma, Beta).
Usage
run_parms_wizard(verbose = TRUE)
Arguments
verbose |
Logical. If |
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 probabilistic 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)
Rate of action potential (i.e. firing rate) across neurons and repetitions.
Description
The average rate of action potentials over the observation period (i.e. 2500 ms) is provided per neuron (N:20) across repetitions (n: 300), yielding a single average firing rate value for each neuron.
Usage
data(singlespikes)
Format
A data frame with 300 observations and 21 variables:
- x
Predictor variable. External Current.
- m1
Candidate mediator 1. Average action potential of neuron 1.
- m2
Candidate mediator 2. Average action potential of neuron 2.
- m3
Candidate mediator 3. Average action potential of neuron 3.
- m4
Candidate mediator 4. Average action potential of neuron 4.
- m5
Candidate mediator 5. Average action potential of neuron 5.
- m6
Candidate mediator 6. Average action potential of neuron 6.
- m7
Candidate mediator 7. Average action potential of neuron 7.
- m8
Candidate mediator 8. Average action potential of neuron 8.
- m9
Candidate mediator 9. Average action potential of neuron 9.
- m10
Candidate mediator 10. Average action potential of neuron 10.
- m11
Candidate mediator 11. Average action potential of neuron 11.
- m12
Candidate mediator 12. Average action potential of neuron 12.
- m13
Candidate mediator 13. Average action potential of neuron 13.
- m14
Candidate mediator 14. Average action potential of neuron 14.
- m15
Candidate mediator 15. Average action potential of neuron 15.
- m16
Candidate mediator 16. Average action potential of neuron 16.
- m17
Candidate mediator 17. Average action potential of neuron 17.
- m18
Candidate mediator 18. Average action potential of neuron 18.
- m19
Candidate mediator 19. Average action potential of neuron 19.
- y
Outcome variable. Average action potential of neuron 20.
Details
The dataset contains one predictor, nineteen candidate mediators, and one outcome variable.
Source
Time-averaged neural spiking data included with the buzzMed package.
A subset in time of longitudinal spike train data.
Description
For each neuron across all repetitions, the time series that describe whether or not a neuron generated action potential is provided. This is a subset of the full data matrix where the temporal index starts at 1002 ms and continues until 1026 ms.
Usage
data(sublongspikes)
Format
A numeric array with dimensions 300 × 25 × 21:
- Dimension 1 (N)
300 observations.
- Dimension 2 (T)
25 repeated measurements (time points).
- Dimension 3 (Variables)
21 variables consisting of one predictor (X), 19 candidate mediators (M), and one outcome (Y).
Details
The third dimension stores the variables in the following order:
Slice 1: Predictor (X)
Slices 2–20: Candidate mediators (M)
Slice 21: Outcome (Y)
Source
Longitudinal spiking train data included with the buzzMed package.