Title:	Bayesian Analysis for Multivariate Categorical Outcomes
Version:	0.1.0
Description:	Provides Bayesian methods for comparing groups on multiple binary outcomes. Includes basic tests using multivariate Bernoulli distributions, subgroup analysis via generalized linear models, and multilevel models for clustered data. For statistical underpinnings, see Kavelaars, Mulder, and Kaptein (2020) <doi:10.1177/0962280220922256>, Kavelaars, Mulder, and Kaptein (2024) <doi:10.1080/00273171.2024.2337340>, and Kavelaars, Mulder, and Kaptein (2023) <doi:10.1186/s12874-023-02034-z>. An interactive shiny app to perform sample size computations is available.
License:	GPL (≥ 3)
Encoding:	UTF-8
LazyData:	TRUE
LazyDataCompression:	xz
RoxygenNote:	7.3.3
Imports:	abind, coda, MCMCpack, msm, pgdraw, tcltk, Rdpack, stats
Suggests:	knitr, rmarkdown, testthat, RefManageR
Config/testthat/edition:	3
VignetteBuilder:	knitr
RdMacros:	Rdpack
URL:	https://github.com/XynthiaKavelaars/bmco, https://xynthia-kavelaars.shinyapps.io/bmco-pwr/
BugReports:	https://github.com/XynthiaKavelaars/bmco/issues
Depends:	R (≥ 3.5)
NeedsCompilation:	no
Packaged:	2026-03-05 14:51:38 UTC; xk1
Author:	Xynthia Kavelaars [aut, cre], Joris Mulder [ths], Maurits Kaptein [ths], Dutch Research Council [fnd] (Grant no. 406.18.505)
Maintainer:	Xynthia Kavelaars <xynthia.kavelaars@ou.nl>
Repository:	CRAN
Date/Publication:	2026-03-10 11:30:07 UTC

bmco: Bayesian Analysis for Multivariate Categorical Outcomes

Description

Provides Bayesian methods for comparing groups on multiple binary outcomes, including basic tests, regression adjustment, and multilevel models.

Main functions

• bmvb: Bayesian test using multivariate Bernoulli

• bglm: Subgroup analysis using Bayesian logistic regression analysis

• bglmm: Multilevel data using Bayesian multilevel logistic regression analysis

Author(s)

Maintainer: Xynthia Kavelaars xynthia.kavelaars@ou.nl (ORCID)

Other contributors:

• Joris Mulder (ORCID) [thesis advisor]

• Maurits Kaptein (ORCID) [thesis advisor]

• Dutch Research Council (Grant no. 406.18.505) [funder]

References

Kavelaars X, Mulder J, Kaptein M (2020). “Decision-making with multiple correlated binary outcomes in clinical trials.” Statistical Methods in Medical Research, 29(11), 3265–3277. doi:10.1177/0962280220922256.

Kavelaars X, Mulder J, Kaptein M (2024). “Bayesian Multivariate Logistic Regression for Superiority and Inferiority Decision-Making under Observable Treatment Heterogeneity.” Multivariate Behavioral Research, 59(4), 859–882. doi:10.1080/00273171.2024.2337340.

Kavelaars X, Mulder J, Kaptein M (2023). “Bayesian multilevel multivariate logistic regression for superiority decision-making under observable treatment heterogeneity.” BMC Medical Research Methodology, 23(1). doi:10.1186/s12874-023-02034-z.

See Also

Useful links:

• https://github.com/XynthiaKavelaars/bmco

• https://xynthia-kavelaars.shinyapps.io/bmco-pwr/

• Report bugs at https://github.com/XynthiaKavelaars/bmco/issues

Bayesian Generalized Linear Model

Description

Perform a Bayesian test for differences between two (sub)groups on multiple binary outcomes using multinomial logistic regression as described in Kavelaars et al. (2024).

Usage

bglm(
  data,
  grp,
  grp_a,
  grp_b,
  x_var,
  y_vars,
  x_method = c("Empirical", "Analytical", "Value"),
  x_def = c(-Inf, Inf),
  test = c("right_sided", "left_sided"),
  rule = c("All", "Any", "Comp"),
  w = NULL,
  b_mu0 = NULL,
  b_sigma0 = NULL,
  n_burn = 10000,
  n_it = 20000,
  n_thin = 1,
  n_chain = 2,
  start = c(0.5, 1),
  return_diagnostics = TRUE,
  return_diagnostic_plots = FALSE,
  return_samples = FALSE
)

Arguments

Value

An object of class bglm, a list containing:

estimates

A list with posterior means and standard deviations of group probabilities (mean_a, mean_b, sd_a, sd_b), as well as posterior means (b) and standard deviations (b_sd) of the regression coefficients.

sample_sizes

A list with group sample sizes (n_a, n_b).

delta

A list with posterior mean differences (mean_delta), posterior standard errors (se_delta), posterior probability of the hypothesis (pop), and, if rule = "Comp", the weighted difference (w_delta).

info

A list with prior specifications, test settings, group labels, covariate handling method, and subpopulation definition.

diags

If diagnostics are requested, a list with MCMC diagnostic results for the regression coefficients.

samples

If return_samples = TRUE, a list containing posterior draws of theta_a, theta_b, delta, and regression coefficients.

References

Kavelaars X, Mulder J, Kaptein M (2024). “Bayesian Multivariate Logistic Regression for Superiority and Inferiority Decision-Making under Observable Treatment Heterogeneity.” Multivariate Behavioral Research, 59(4), 859–882. doi:10.1080/00273171.2024.2337340.

Examples

# Example with simulated data
# Generate data
set.seed(123)
n <- 100

data <- data.frame(
 group = rep(c("A", "B"), each = n/2),
 x = rnorm(n),
 stringsAsFactors = FALSE
)

p1 <- p2 <- rep(NA, n)

for (i in 1:n) {
 grpB <- ifelse(data$group[i] == "B", 1, 0)

 p1[i] <- plogis(-0.50 + 0.75 * grpB + 0.10 * data$x[i] + 0.20 * grpB * data$x[i])
 p2[i] <- plogis(-0.50 + 0.80 * grpB + 0.05 * data$x[i] + 0.15 * grpB * data$x[i])

 data$y1[i] <- rbinom(1, 1, p1[i])
 data$y2[i] <- rbinom(1, 1, p2[i])
}

# Analyze
result <- bglm(
 data = data,
 grp = "group",
 grp_a = "A",
 grp_b = "B",
 x_var = "x",
 y_vars = c("y1", "y2"),
 x_method = "Empirical",
 x_def = c(-Inf, Inf),
 test = "right_sided",
 rule = "All",
 n_burn = 100, # Too low for proper MCMC sampling
 n_it = 500 # Too low for proper MCMC sampling
)

print(result)

Simulated Single-Level Clinical Trial Data

Description

A simulated dataset representing a two-arm clinical trial with 200 subjects, one continuous covariate, and two binary outcomes. It serves as the underlying data for bglm_fit and can be used to illustrate bglm.

Usage

bglm_data

Format

A data frame with 200 rows and 4 columns:

group

Character. Treatment arm: "placebo" (n = 100) or "drug" (n = 100).

age

Numeric. Continuous covariate drawn from N(50,\,10^2).

y1

Integer (0/1). First binary outcome.

y2

Integer (0/1). Second binary outcome.

Details

Data were generated with set.seed(2024) using logistic models:

P(y_1 = 1) = \text{logit}^{-1}(-0.50 + 0.75\,\text{drug} + 0.10\,\text{age}/10)

P(y_2 = 1) = \text{logit}^{-1}(-0.50 + 0.80\,\text{drug} + 0.05\,\text{age}/10)

where drug is 1 for the drug arm and 0 for placebo. See data-raw/generate_examples.R for the full script.

See Also

bglm, bglm_fit, bglmm_data

Examples

head(bglm_data)
table(bglm_data$group, bglm_data$y1)

Pre-computed bglm Example Fit

Description

A fitted bglm object estimated on bglm_data. Used in package examples and tests so that print, summary, and plot examples run in well under 5 seconds without re-running the MCMC sampler.

Usage

bglm_fit

Format

An object of class bglm as returned by bglm. See the Value section of bglm for a full description of the list components. Key settings: n_burn = 10000, n_it = 20000, n_chain = 2, return_diagnostics = TRUE, return_samples = TRUE.

Details

Generated with set.seed(2024). See data-raw/generate_examples.R for the full reproducible script.

See Also

bglm, bglm_data, bglmm_fit

Examples

print(bglm_fit)
summary(bglm_fit)

Bayesian Generalized Linear Mixed Model

Description

Perform a Bayesian test for differences between two (sub)groups on multiple binary outcomes using multilevel multinomial logistic regression, as described in Kavelaars et al. (2023).

Usage

bglmm(
  data,
  grp,
  grp_a = NULL,
  grp_b = NULL,
  id_var,
  x_var,
  y_vars,
  x_method = c("Empirical", "Analytical", "Value"),
  x_def = c(-Inf, Inf),
  test = c("right_sided", "left_sided"),
  rule = c("All", "Any", "Comp"),
  w = NULL,
  n_burn = 10000,
  n_it = 50000,
  start = c(0.5, 1),
  fixed = NULL,
  random = NULL,
  b_mu0 = NULL,
  b_sigma0 = NULL,
  g_mu0 = NULL,
  g_sigma0 = NULL,
  nu0 = NULL,
  tau0 = NULL,
  n_chain = 2,
  return_thinned = TRUE,
  n_thin = 10,
  return_diagnostics = TRUE,
  return_diagnostic_plots = FALSE,
  return_samples = FALSE
)

Arguments

Value

An object of class bglmm, a list containing:

estimates

A list with posterior means and standard deviations of group probabilities (mean_a, mean_b, sd_a, sd_b). If estimated, posterior means and standard deviations of fixed effects (b, b_sd) and random effects and variance components (g, g_sd, tau, tau_sd) are included.

sample_sizes

A list with group sample sizes (n_a, n_b) and the number of clusters (J).

delta

A list with posterior mean differences (mean_delta), posterior standard errors (se_delta), posterior probability of the hypothesis (pop), and, if rule = "Comp", the weighted difference (w_delta).

info

A list with prior specifications, model structure (fixed and random effects), test settings, group labels, covariate handling method, and subpopulation definition.

diags

If diagnostics are requested, a list with MCMC diagnostic results for fixed effects, random effects, and variance components.

samples

If return_samples = TRUE, a list containing posterior draws of group probabilities, differences, fixed effects, random effects, and variance components (if applicable).

References

Kavelaars X, Mulder J, Kaptein M (2023). “Bayesian multilevel multivariate logistic regression for superiority decision-making under observable treatment heterogeneity.” BMC Medical Research Methodology, 23(1). doi:10.1186/s12874-023-02034-z.

Examples

# Example with simulated data
# Generate data
set.seed(123)
J <- 20 # No. clusters
nJ <- 15 # Sample size per cluster

# Generate random intercepts
uj_1 <- rnorm(J)
uj_2 <- rnorm(J)
data <- data.frame(
 id = factor(rep(1:J, each = nJ)),
 group = rep(rep(c("A", "B"), each = J/2), each = nJ),
 x = rnorm(J * nJ),
 stringsAsFactors = FALSE
)

p1 <- p2 <- rep(NA, J * nJ)

for (i in 1:(J * nJ)) {
 j <- as.numeric(data$id[i])
 grpB <- ifelse(data$group[i] == "B", 1, 0)

 p1[i] <- plogis(-0.50 + 0.75 * grpB + 0.10 * data$x[i] + 0.20 * grpB * data$x[i] + uj_1[j])
 p2[i] <- plogis(-0.50 + 0.80 * grpB + 0.05 * data$x[i] + 0.15 * grpB * data$x[i] + uj_2[j])

 data$y1[i] <- rbinom(1, 1, p1[i])
 data$y2[i] <- rbinom(1, 1, p2[i])
}

# Analyze
result <- bglmm(
 data = data,
 grp = "group",
 grp_a = "A",
 grp_b = "B",
 id_var = "id",
 x_var = "x",
 y_vars = c("y1", "y2"),
 x_method = "Empirical",
 x_def = c(-Inf, Inf),
 fixed = c("group", "x", "group_x"),
 random = c("Intercept"), # Random intercept model
 test = "right_sided",
 rule = "All",
 n_burn = 100, # Too low for proper MCMC sampling
 n_it = 500 # Too low for proper MCMC sampling
 )

print(result) # Warnings due to low number of MCMC iterations (n_burn and n_it)

Simulated Multilevel Clinical Trial Data

Description

A simulated dataset representing a two-arm clinical trial with 300 subjects nested within 20 clusters (e.g., hospitals), one continuous covariate, and two binary outcomes. It serves as the underlying data for bglmm_fit and can be used to illustrate bglmm.

Usage

bglmm_data

Format

A data frame with 300 rows and 5 columns:

id

Factor with 20 levels (1–20). Cluster identifier (e.g., hospital). Each cluster contains 15 subjects.

group

Character. Treatment arm: "placebo" (clusters 1–10) or "drug" (clusters 11–20).

age

Numeric. Continuous covariate drawn from N(50,\,10^2).

y1

Integer (0/1). First binary outcome.

y2

Integer (0/1). Second binary outcome.

Details

Data were generated with set.seed(2024) using logistic models with cluster-specific random intercepts u_{j1},\,u_{j2} \sim N(0,\,0.25):

P(y_1 = 1) = \text{logit}^{-1}(-0.50 + 0.75\,\text{drug} + 0.10\,\text{age}/10 + u_{j1})

P(y_2 = 1) = \text{logit}^{-1}(-0.50 + 0.80\,\text{drug} + 0.05\,\text{age}/10 + u_{j2})

where drug is 1 for the drug arm and 0 for placebo. See data-raw/generate_examples.R for the full script.

See Also

bglmm, bglmm_fit, bglm_data

Examples

head(bglmm_data)
table(bglmm_data$group, bglmm_data$id)

Pre-computed bglmm Example Fit

Description

A fitted bglmm object estimated on bglmm_data. Used in package examples and tests so that print, summary, and plot examples run in well under 5 seconds without re-running the MCMC sampler.

Usage

bglmm_fit

Format

An object of class bglmm as returned by bglmm. See the Value section of bglmm for a full description of the list components. Key settings: n_burn = 10000, n_it = 50000, n_thin = 10, n_chain = 2, return_diagnostics = TRUE, return_samples = TRUE.

Details

Generated with set.seed(2024). See data-raw/generate_examples.R for the full reproducible script.

See Also

bglmm, bglmm_data, bglm_fit

Examples

print(bglmm_fit)
summary(bglmm_fit)

Bayesian Multivariate Bernoulli Test

Description

Perform a Bayesian test for differences between two groups on multiple binary outcomes using a Multivariate Bernoulli distribution, as described in Kavelaars et al. (2020).

Usage

bmvb(
  data,
  grp,
  grp_a,
  grp_b,
  y_vars,
  test = c("right_sided", "left_sided"),
  rule = c("All", "Any", "Comp"),
  w = NULL,
  prior_a = 0.5,
  prior_b = 0.5,
  n_it = 10000,
  return_samples = FALSE
)

Arguments

Value

An object of class bmvb, a list containing:

estimates

A list with posterior means (mean_a, mean_b) and standard deviations (sd_a, sd_b) of the category probabilities for both groups.

sample_sizes

A list with group sample sizes (n_a, n_b).

delta

A list with posterior mean differences (mean_delta), posterior standard errors (se_delta), posterior probability of the hypothesis (pop), and, if rule = "Comp", the weighted difference (w_delta).

info

A list with test specifications, including the decision rule, test direction, group labels, and weights (if applicable).

samples

If return_samples = TRUE, a list containing posterior draws of theta_a, theta_b, and delta.

References

Kavelaars X, Mulder J, Kaptein M (2020). “Decision-making with multiple correlated binary outcomes in clinical trials.” Statistical Methods in Medical Research, 29(11), 3265–3277. doi:10.1177/0962280220922256.

Examples

# Example with simulated data
# Generate data
set.seed(123)
data <- data.frame(
treatment = rep(c("control", "drug"), each = 50),
 outcome1 = rbinom(100, 1, 0.5),
 outcome2 = rbinom(100, 1, 0.5)
)

# Analyze
result <- bmvb(
 data = data,
 grp = "treatment",
 grp_a = "control",
 grp_b = "drug",
 y_vars = c("outcome1", "outcome2"),
 n_it = 10000
)

print(result)

Check and Validate Input Parameters

Description

Comprehensive input validation for bmvb, bglm, and bglmm functions. Performs all necessary checks and returns cleaned/validated parameters.

Usage

check_input(
  data,
  grp,
  grp_a,
  grp_b,
  y_vars,
  test,
  rule,
  w,
  analysis = c("bmvb", "bglm", "bglmm"),
  prior_a = NULL,
  prior_b = NULL,
  b_mu0 = NULL,
  b_sigma0 = NULL,
  g_mu0 = NULL,
  g_sigma0 = NULL,
  nu0 = NULL,
  tau0 = NULL,
  fixed = NULL,
  random = NULL,
  x_var = NULL,
  x_method = NULL,
  x_def = NULL,
  id_var = NULL,
  n_burn = NULL,
  n_it,
  n_thin = 1
)

Arguments

Value

List with validated parameters and cleaned data subsets:

y_a

Matrix of outcomes for group A (with missing data removed)

y_b

Matrix of outcomes for group B (with missing data removed)

w

Weights (generated if NULL and rule = "Comp")

grp_a

Validated group A value

grp_b

Validated group B value

J

Number of clusters (bglmm only)

Compute Pairwise Correlation

Description

Compute pairwise correlation from joint response probabilities. Based on Dai, Ding, & Wahba (2013). Multivariate Bernoulli distribution.

Usage

compute_rho(phi)

Arguments

Value

Scalar. Correlation between outcome variables.

Compute Credible Intervals

Description

Compute Credible Intervals

Usage

credible_interval(samples, prob = 0.95)

Diagnose MCMC Chains

Description

Perform diagnostic checks on MCMC chains including convergence assessment and optional trace plots.

Usage

diagnose_mcmc(chains, param_names = NULL)

Arguments

Value

A list with diagnostic information:

convergence

Multivariate potential scale reduction factor (Gelman-Rubin statistic)

n_eff

Effective sample sizes for each parameter

rhat

Univariate potential scale reduction factors for each parameter

summary

Posterior summary of MCMC chains

Estimate Parameters for Multilevel Model

Description

Estimate regression coefficients using multiple chains of Polya-Gamma Gibbs sampling for multilevel data.

Usage

estimate_parameters_ml(
  X,
  Y,
  fixed,
  random,
  n_burn,
  n_it,
  start,
  b_mu0 = NULL,
  b_sigma0 = NULL,
  g_mu0 = NULL,
  g_sigma0 = NULL,
  nu0 = NULL,
  tau0 = NULL,
  n_chain = 2,
  return_thinned = FALSE,
  n_thin = 1
)

Arguments

Value

A named list with:

Pars

List of parameter draws from each chain

Estimate Parameters using Polya-Gamma Method

Description

Wrapper function for MCMC procedure to estimate regression coefficients using Polya-Gamma Gibbs sampling.

Usage

estimate_parameters_pg(X, Y, n_burn, n_it, start, b_mu0, b_sigma0, n_chain)

Arguments

Value

A list of length n_chain, being a list of length n_it with P x Q matrices with estimated regression coefficients

Estimate Theta via Analytical Integration

Description

Estimate success probabilities by integrating over a range of covariate values.

Usage

estimate_theta_analytical(
  est_pars,
  X,
  grp,
  range_x,
  grp_var,
  population_var,
  fixed = NULL,
  random = NULL
)

Arguments

Value

List of nIt vectors of length K with multivariate probabilities. Currently supported for K=2 only.

Estimate Theta via Empirical Marginalization

Description

Estimate success probabilities via empirical marginalization over covariate values.

Usage

estimate_theta_empirical(est_pars, X)

Arguments

Value

List of nIt vectors of length K containing bivariate probabilities. Currently supported for K=2 only.

Estimate Theta with Multivariate Bernoulli Distribution

Description

Estimate success probabilities with a Multivariate Bernoulli distribution (reference approach).

Usage

estimate_theta_mvb(Y, prior_alpha = 0.5, n_it = 10000)

Arguments

Value

nIt x K matrix with bivariate Bernoulli probabilities. Currently supported for K=2 only.

Extract MCMC Chains from Model

Description

Extract MCMC chains from a fitted bglm or bglmm model for custom plotting or analysis.

Usage

extract_chains(model, component = "fixed")

Arguments

Value

An mcmc.list object containing the MCMC chains.

Integrand for Analytical Marginalization

Description

Integrand function for integration over a range of a covariate in numerical marginalization. Works for both GLM and GLMM.

Usage

integrand(
  x,
  est_rc,
  mu_x,
  sigma_x,
  range_x,
  grp,
  grp_var,
  population_var,
  q,
  fixed = NULL,
  random = NULL
)

Arguments

Value

Scalar. Joint response probability for response category q.

Transform Bivariate Binomial to Multinomial Response

Description

Transform bivariate binomial response data to multinomial response format.

Usage

multivariate2multinomial(y_bv)

Arguments

Value

n x 4 matrix with multinomial responses, ordered as 11, 10, 01, 00.

Transform Phi to Weighted Treatment Difference

Description

Transform joint response probabilities to weighted treatment difference. Currently supported for Q=4/K=2 only.

Usage

phi2delta_w(phi_a, phi_b, weights)

Arguments

Value

Scalar. Weighted treatment difference.

Transform Phi to Theta

Description

Transform joint response probabilities to bivariate success probabilities. Currently supported for K=2/Q=4 only.

Usage

phi2theta(phi)

Arguments

Value

Numeric vector of bivariate success probabilities.

Plot Method for bglm Objects

Description

Plot Method for bglm Objects

Usage

## S3 method for class 'bglm'
plot(x, type = "all", parameters = NULL, ...)

Arguments

Value

Invisibly returns NULL (plots are displayed).

Examples

# Uses the pre-computed example object shipped with the package.
# Plot trace plots for the fixed-effect regression coefficients:
plot(bglm_fit, type = "trace")

Plot Method for bglmm Objects

Description

Plot Method for bglmm Objects

Usage

## S3 method for class 'bglmm'
plot(x, type = "all", which = "fixed", parameters = NULL, ...)

Arguments

Value

Invisibly returns NULL (plots are displayed).

Examples

# Uses the pre-computed example object shipped with the package.
# Trace plots for the fixed-effect regression coefficients:
plot(bglmm_fit, type = "trace", which = "fixed")

# Trace plots for the random-effect variance components:
plot(bglmm_fit, type = "trace", which = "variance")

Plot Specific MCMC Diagnostic

Description

Generate a specific type of diagnostic plot for MCMC chains.

Usage

plot_mcmc(chains, type = "trace", parameters = NULL, main = NULL, ...)

Arguments

Value

Invisibly returns NULL.

Print Method for bglm Objects

Description

Print Method for bglm Objects

Usage

## S3 method for class 'bglm'
print(x, digits = 3, ...)

Arguments

Value

Invisibly returns the input object.

See Also

summary.bglm

Examples

# Uses the pre-computed example object shipped with the package:
print(bglm_fit)

Print Method for bglmm Objects

Description

Print Method for bglmm Objects

Usage

## S3 method for class 'bglmm'
print(x, digits = 3, ...)

Arguments

Value

Invisibly returns the input object.

See Also

summary.bglmm

Examples

# Uses the pre-computed example object shipped with the package:
print(bglmm_fit)

Print Method for bmvb Objects

Description

Print Method for bmvb Objects

Usage

## S3 method for class 'bmvb'
print(x, digits = 3, ...)

Arguments

Value

Invisibly returns the input object.

See Also

summary.bmvb

Examples

set.seed(2024)
trial_data <- data.frame(
  treatment = rep(c("placebo", "drug"), each = 50),
  y1 = rbinom(100, 1, rep(c(0.40, 0.60), each = 50)),
  y2 = rbinom(100, 1, rep(c(0.50, 0.70), each = 50))
)
fit <- bmvb(
  data = trial_data, grp = "treatment",
  grp_a = "placebo", grp_b = "drug",
  y_vars = c("y1", "y2"), n_it = 1000
)
print(fit)

Print Method for mcmc_diagnostics Objects

Description

Print Method for mcmc_diagnostics Objects

Usage

## S3 method for class 'mcmc_diagnostics'
print(x, ...)

Arguments

Value

Invisibly returns the input object.

Print Method for summary.bglm Objects

Description

Print Method for summary.bglm Objects

Usage

## S3 method for class 'summary.bglm'
print(x, digits = 3, ...)

Arguments

Value

Invisibly returns x.

See Also

summary.bglm, print.bglm

Examples

# Uses the pre-computed example object shipped with the package:
print(summary(bglm_fit))

Print Method for summary.bglmm Objects

Description

Print Method for summary.bglmm Objects

Usage

## S3 method for class 'summary.bglmm'
print(x, digits = 3, ...)

Arguments

Value

Invisibly returns x.

See Also

summary.bglmm, print.bglmm

Examples

# Uses the pre-computed example object shipped with the package:
print(summary(bglmm_fit))

Print Method for summary.bmvb Objects

Description

Print Method for summary.bmvb Objects

Usage

## S3 method for class 'summary.bmvb'
print(x, digits = 3, ...)

Arguments

Value

Invisibly returns x.

See Also

summary.bmvb, print.bmvb

Examples

set.seed(2024)
trial_data <- data.frame(
  treatment = rep(c("placebo", "drug"), each = 50),
  y1 = rbinom(100, 1, rep(c(0.40, 0.60), each = 50)),
  y2 = rbinom(100, 1, rep(c(0.50, 0.70), each = 50))
)
fit <- bmvb(
  data = trial_data, grp = "treatment",
  grp_a = "placebo", grp_b = "drug",
  y_vars = c("y1", "y2"), n_it = 1000,
  return_samples = TRUE
)
print(summary(fit))

Round to Chosen Interval

Description

Function to round number up or down to a chosen interval. Adapted from: https://stackoverflow.com/a/32508105

Usage

round_choose(x, round_to, dir = 1)

Arguments

Value

Scalar. Rounded number.

Sample Beta Coefficients for Multilevel Model

Description

Sample regression coefficients via Polya-Gamma multinomial logistic regression for multilevel data (single chain).

Usage

sample_beta_ml(
  X,
  Y,
  fixed,
  random,
  n_burn,
  n_it,
  start,
  b_mu0 = NULL,
  b_sigma0 = NULL,
  g_mu0 = NULL,
  g_sigma0 = NULL,
  nu0 = NULL,
  tau0 = NULL,
  return_thinned = FALSE,
  n_thin = 1
)

Arguments

Value

A named list with:

b_draw_pg

List of length n_it/n_thin with fixed regression coefficients (if fixed effects present)

g_draw_pg

List of length n_it/n_thin with random regression coefficients (if random effects present)

gj_draw_pg

List of length n_it/n_thin with cluster-specific random effects (if return_thinned = TRUE)

tau_draw_pg

List of length n_it/n_thin with covariance matrices of random effects

Sample Beta Coefficients using Polya-Gamma Method

Description

Sample regression coefficients via Polya-Gamma multinomial logistic regression for a single chain.

Usage

sample_beta_pg(X, Y, n_burn, n_it, start, b_mu0, b_sigma0, verbose = FALSE)

Arguments

Value

b_draw_pg: List of length n_it with P x Q matrices with estimated regression coefficients

Sample Population Subsets

Description

Extract subsets of covariate data for treatment groups based on specified method.

Usage

sample_population(
  X,
  population_var = NULL,
  grp_var,
  method,
  value = NULL,
  range = NULL,
  fixed = NULL,
  random = NULL
)

Arguments

Value

A list with:

x_a

Design matrix with covariate data for group A

x_b

Design matrix with covariate data for group B

Summary Method for bglm Objects

Description

Provides a comprehensive summary of a bglm analysis, including the regression coefficient table, prior specification, MCMC diagnostics (effective sample sizes and \hat{R} per parameter), and, when the model was fitted with return_samples = TRUE, credible intervals.

Usage

## S3 method for class 'bglm'
summary(object, prob = 0.95, ...)

Arguments

Value

An object of class summary.bglm, a list containing:

estimates

Posterior means and SDs of group probabilities and regression coefficients.

sample_sizes

Group sample sizes.

delta

Posterior mean differences, SEs, and posterior probability.

info

Prior specification, test settings, and marginalization details.

credible_intervals

If posterior samples are available: credible interval matrices for theta_a, theta_b, and delta.

effective_n

If posterior samples are available: effective sample sizes for theta_a, theta_b, and delta.

mcmc_diags

MCMC diagnostics for the regression coefficients (effective sample sizes and \hat{R}).

See Also

bglm, print.bglm

Examples

# Uses the pre-computed example object shipped with the package:
summary(bglm_fit)

Summary Method for bglmm Objects

Description

Provides a comprehensive summary of a bglmm analysis, including fixed and random effect tables, variance component estimates, multilevel structure, and MCMC convergence diagnostics.

Usage

## S3 method for class 'bglmm'
summary(object, prob = 0.95, ...)

Arguments

Value

An object of class summary.bglmm, a list containing:

estimates

Posterior means and SDs of group probabilities, fixed effects, random effects, and variance components.

sample_sizes

Group sample sizes and number of clusters.

delta

Posterior mean differences, SEs, and posterior probability.

info

Prior specification, model structure, test settings, and marginalization details.

credible_intervals

If posterior samples are available: credible interval matrices for theta_a, theta_b, and delta.

effective_n

If posterior samples are available: effective sample sizes for theta_a, theta_b, and delta.

mcmc_diags

MCMC convergence diagnostics (ESS, \hat{R}, MPSRF) for fixed effects, random effects, and variance components.

See Also

bglmm, print.bglmm

Examples

# Uses the pre-computed example object shipped with the package:
summary(bglmm_fit)

Summary Method for bmvb Objects

Description

Provides a comprehensive summary of a bmvb analysis. When the model was fitted with return_samples = TRUE, credible intervals and effective sample sizes are included.

Usage

## S3 method for class 'bmvb'
summary(object, prob = 0.95, ...)

Arguments

Value

An object of class summary.bmvb, a list containing all fields of object plus:

credible_intervals

If posterior samples are available: a list with prob and credible interval matrices for theta_a, theta_b, and delta.

effective_n

If posterior samples are available: a list with effective sample sizes for theta_a, theta_b, and delta.

See Also

bmvb, print.bmvb

Examples

set.seed(2024)
trial_data <- data.frame(
  treatment = rep(c("placebo", "drug"), each = 50),
  y1 = rbinom(100, 1, rep(c(0.40, 0.60), each = 50)),
  y2 = rbinom(100, 1, rep(c(0.50, 0.70), each = 50))
)
fit <- bmvb(
  data = trial_data, grp = "treatment",
  grp_a = "placebo", grp_b = "drug",
  y_vars = c("y1", "y2"), n_it = 1000,
  return_samples = TRUE
)
summary(fit)

Transform Theta to Weighted Treatment Difference

Description

Transform bivariate success probabilities to weighted treatment difference. Currently supported for K=2 only.

Usage

theta2delta_w(theta_a, theta_b, weights)

Arguments

Value

Scalar. Weighted treatment difference.

Transform Theta to Phi

Description

Transform bivariate success probabilities to joint response probabilities. Currently supported for K=2/Q=4 only.

Usage

theta2phi(theta, rho)

Arguments

Value

Numeric vector of 4 joint response probabilities, summing to 1 and ordered as 11, 10, 01, 00.

Transform Regression Coefficients to Success Probabilities

Description

Compute theta (success probabilities) from regression coefficients via various methods.

Usage

transform2theta(
  beta_draw_pg,
  X,
  Y = NULL,
  grp_var,
  population_var,
  measurement_level,
  method,
  range,
  value
)

Arguments

Value

A list with:

m_theta_a

List of n_it vectors of length K with multivariate probabilities for group A

m_theta_b

List of n_it vectors of length K with multivariate probabilities for group B

Transform Regression Coefficients to Theta for Multilevel Model

Description

Compute theta (success probabilities) from regression coefficients for multilevel data via various methods.

Usage

transform2theta_lr_ml(
  est_pars,
  X,
  measurement_levels,
  population_var,
  grp_var,
  grp_lvl,
  method = c("Empirical", "Analytical", "Value"),
  range = NULL,
  value = NULL,
  fixed,
  random
)

Arguments

Value

A list with:

m_theta_a

List of n_it vectors with multivariate probabilities for group A

m_theta_b

List of n_it vectors with multivariate probabilities for group B