Extract Posterior Mean Coefficients from rjMCMC Results

Description

This function extracts the posterior means of the intercept, exposure parameters, and binary parameters from the results of an rjMCMC model.

Usage

## S3 method for class 'rjMCMC'
coef(object, ...)

Arguments

Value

A numeric vector containing the posterior mean of the intercept, exposure, and binary parameters.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)


results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
coef(results)

Credible Intervals for rjMCMC Results

Description

This function calculates the posterior mean and credible intervals for parameters from the rjMCMC results, including both intercept/exposure parameters and binary parameters. The credible intervals are computed based on the specified confidence level.

Usage

credint(results, level = 0.95)

Arguments

Value

A data frame with estimates, lower, and upper bounds of the credible intervals.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)


results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
credint(results)

Fitted values from Reversible Jump MCMC (rjMCMC) Model Results

Description

This function generates posterior fitted values from an rjMCMC model based on the provided data. It combines the fixed effects, spline terms, and binary parameters.

Usage

## S3 method for class 'rjMCMC'
fitted(object, newdata = NULL, ...)

Arguments

Value

A matrix of fitted values.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
           outcome = "Y", factor_var = "trt")

newdata = data.frame(Z_1 = 1, Z_2 = 1, Z_3 = 1, Z_4 = 1, Z_5 = 1,
                   trt = 1, X_1 = seq(0,1,by=0.01))
fitted(results)
fitted(results,newdata)

Fitted exposure effect values from Reversible Jump MCMC (rjMCMC) Model Results

Description

This function generates posterior fitted exposure effects from an rjMCMC model based on the provided data. It combines the fixed effects, spline terms, and binary parameters.

Usage

fittedExposureEff(results, newdata = NULL)

Arguments

Value

A matrix of fitted values.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)
results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
newdata = data.frame(Z_1 = 1, Z_2 = 1, Z_3 = 1, Z_4 = 1, Z_5 = 1,
                   trt = 1, X_1 = seq(0,1,by=0.01))
fittedExposureEff(results)
fittedExposureEff(results,newdata)

Get Effective Subspace

Description

This function identifies the "effective subspace" where exposure is effective based on posterior inference results from the FK-BMA model. It analyzes interaction terms between exposure and covariates, allowing for both binary and continuous variables.

Usage

getEffectiveSubspace(results, newdata = NULL, alpha = 0.05, pip_cutoff = 0.1)

Arguments

Details

• The function computes the posterior exposure effect for each observation in the dataset using the fittedExposureEff function and evaluates its quantiles at the specified alpha level.

• Binary variables with high posterior inclusion probabilities (PIP) are used to define subgroups, and the corresponding effective subspaces for a continuous variable are identified by checking where the exposure effect quantiles are strictly positive.

• If the number of binary variables is <= 3 and there is exactly one continuous variable, the function describes the effective subspace in terms of disjoint intervals.

• For more complex cases, a warning is issued suggesting alternative methods such as Bayesian regression trees for interpretation.

Value

A list with the following components:

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
getEffectiveSubspace(results)

Compute Posterior Inclusion Probabilities (PIPs) for rjMCMC Results

Description

This function returns the posterior inclusion probabilities (PIPs) for all variables, including the intercept and exposure, based on the results from an rjMCMC model.

Usage

pip(results)

Arguments

Value

A numeric vector with the PIPs for the intercept, exposure, and other variables.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
pip(results)

Plotting function for rjMCMC results

Description

This function generates plots for model results from rjMCMC based on specified sample type, effect type, and plot type. The function is flexible for various combinations of sample_type, effect_type, and plot_type, as outlined below.

Usage

## S3 method for class 'rjMCMC'
plot(
  x,
  ...,
  variables = NULL,
  sample_type = "fitted",
  effect_type = "exposure_effect",
  plot_type = "cred",
  level = 0.95,
  aux_vars = list(),
  facet_by = NULL,
  pip_cutoff = 0.1
)

Arguments

Details

• Sample and Plot Compatibility:

  • For sample_type = "estimand", only plot_type = "hist" or "trace" is allowed, as these are designed to visualize the posterior distribution or MCMC trajectory of individual parameters. Parameters like intercept, trt, and sigma are agnostic to effect_type as they do not interact with exposure.

  • plot_type = "cred" is designed for use with sample_type = "fitted" or "predictive" and shows credible intervals for the outcome (y-axis) across biomarker values (x-axis) by covariate pattern. effect_type controls whether the exposure effect or main effect is displayed.

• Effect Types:

  • outcome plots either the fitted or predictive values without exposure interaction, allowing for exposure (trt) values to be specified.

  • exposure_effect plots the interaction of the exposure effect across different covariate patterns.

Value

A ggplot2 object or a grid of plots.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
plot(results, sample_type = "fitted", effect_type = "exposure_effect", plot_type = "cred")
plot(results, sample_type = "estimand", plot_type = "hist")

Generate Histogram and Trace Plots for MCMC Samples

Description

This internal function creates histogram or trace plots for MCMC samples from an rjMCMC model, displaying the posterior distributions or sampling trajectories of specified variables.

Usage

plotHistTrace(
  results,
  variables = NULL,
  sample_type = "fitted",
  effect_type = "exposure_effect",
  plot_type = "cred",
  aux_vars = list(),
  facet_by = NULL
)

Arguments

Details

• Sample and Plot Compatibility:

  • For sample_type = "estimand", only plot_type = "hist" or "trace" is compatible, as it represents the posterior distribution or MCMC trajectory of individual parameters.

  • For sample_type = "fitted" or "predictive", this function plots either the main effect (no interaction with exposure) or exposure effect for an individual using auxiliary variable values.

• Effect Types:

  • For sample_type = "fitted" or "predictive", "outcome" generates plots without exposure interaction, and "exposure_effect" plots the interaction effect with exposure.

Value

A ggplot2 object displaying histograms or trace plots of the MCMC samples.

Note

This is an internal function not intended for direct use by package users.

Predict from Reversible Jump MCMC (rjMCMC) Model Results

Description

This function generates posterior predictions from an rjMCMC model based on the provided data. It combines the fixed effects, spline terms, and binary parameters, and includes residual variance in the predictions.

Usage

## S3 method for class 'rjMCMC'
predict(object, newdata = NULL, ...)

Arguments

Value

A matrix of predicted values.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
           outcome = "Y", factor_var = "trt")
predict(results)

Predict Exposure Effect

Description

This function predicts the exposure effect for new data based the Reversible Jump MCMC (rjMCMC) results.

Usage

predictExposureEff(results, newdata = NULL)

Arguments

Details

The function:

• Checks if the required columns in results$candinter are present in newdata.

• Computes the fitted posterior exposure effect based on main exposure effects, spline interactions, and binary interactions.

• Adds noise to the fitted posterior using the residual variance results$sigma_sq to generate predictive posterior samples.

Spline interactions are handled by interpolating the spline coefficients for the values in newdata.

Value

A matrix of predictive posterior samples for the exposure effect, where each row corresponds to a posterior sample and each column corresponds to an observation in newdata.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
newdata = data.frame(Z_1 = 1, Z_2 = 1, Z_3 = 1, Z_4 = 1, Z_5 = 1,
                   trt = 1, X_1 = seq(0,1,by=0.01))
predictExposureEff(results)
predictExposureEff(results,newdata)

Print a summary of results from from Reversible Jump MCMC (rjMCMC)

Description

This function provides a detailed summary of the results from the rjMCMC procedure, including model information, parameter estimates, posterior inclusion probabilities, convergence diagnostics, and plots for spline terms. The function also prints the model formula with fbs() notation for spline terms, indicating the use of free-knot B-splines.

Usage

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

Arguments

Details

The function produces detailed summaries similar to those from brms, including diagnostics, estimates, posterior inclusion probabilities, and spline effects. The spline terms are wrapped in fbs() notation, indicating the use of free-knot B-splines in the model. If the sampler did not converge, a warning is issued. The function also allows the user to view diagnostic plots for fitted exposure effects.

Value

Prints the following summary information:

Model Formula

The model formula with spline terms wrapped in fbs(), indicating free-knot B-splines, and interaction terms appropriately formatted.

Convergence Diagnostics

Reports any convergence issues based on Geweke diagnostics.

MCMC Sampler Arguments

Displays MCMC sampler arguments, including the number of posterior samples, burn-in, thinning, and chains.

Parameter Estimates

Posterior mean, standard error, 95% credible intervals, effective sample size (ESS), Gelman-Rubin statistic (Rhat), and posterior inclusion probabilities (PIP) for binary parameters, exposure intercept, and exposure effect.

Gaussian Family Parameters

Posterior summary for the residual standard error (sigma).

Posterior Inclusion Probabilities for Splines

Prints the posterior inclusion probabilities for spline terms.

Plots for Fitted Exposure Effects

Plots the mean and 95% credible intervals for each spline term vs fitted exposure effects.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)


results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
           outcome = "Y", factor_var = "trt")
print(results)

Calculate and Print Rhat Diagnostics for rjMCMC Results

Description

This function calculates the Rhat diagnostic for convergence based on the posterior samples of individual exposure effects, intercept, and main exposure effect from an rjMCMC model. It prints the median, minimum, and maximum Rhat values for the exposure effects, as well as the Rhat for the intercept and exposure effect.

Usage

rhats(results)

Arguments

Details

This function calculates R-hat statistics to assess MCMC convergence for both exposure effects and model parameters. Diagnostic plots are generated to visually inspect the chains across iterations.

Value

A list containing:

Rhat_trt_eff_posterior

Vector of R-hat values for each individual's exposure effect.

Rhat_inter

R-hat value for the intercept parameter.

Rhat_factor_var

R-hat value for the main effect of exposure.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
rhats(results)

Run Reversible Jump MCMC (rjMCMC) Procedure

Description

This function performs a Reversible Jump MCMC (rjMCMC) procedure to generate the posterior distribution, using Bayesian model averaging and free-knot B-splines.

Usage

rjMCMC(
  data,
  candsplinevars,
  candbinaryvars,
  candinter,
  outcome,
  factor_var,
  mcmc_specs = NULL,
  prior_params = NULL
)

Arguments

Value

An rjMCMC object with the following components:

accept_var

Matrix indicating the acceptance of variable inclusion/removal for each iteration.

accept_add_knot

Matrix indicating acceptance of knot addition for each spline term across iterations.

accept_remove_knot

Matrix indicating acceptance of knot removal for each spline term across iterations.

accept_move_knot

Matrix indicating acceptance of knot movement for each spline term across iterations.

splines_fitted

List of matrices, one per spline interaction term, containing fitted spline values across iterations.

binary_param

Matrix containing posterior samples of binary variable parameters.

inter_trt_param

Matrix containing posterior samples of the treatment intercept and main effect.

sigma_sq

Matrix of posterior samples for the residual variance (sigma squared).

vars_prop

Matrix indicating the inclusion of variables across iterations (1 for included, 0 for excluded).

vars_prop_summ

Posterior inclusion probabilities for all candidate variables (spline and binary).

k

Matrix indicating the number of knots for each spline term across iterations.

trt_eff_posterior

Matrix of posterior treatment effect estimates, including spline effects.

data_fit

The original dataset passed to the function.

candsplineinter

A character vector indicating the spline interaction terms.

candsplinevars

A character vector of candidate spline variables.

candbinaryvars

A character vector of candidate binary variables.

candinter

A character vector of interaction terms with treatment (can include splines and binary variables).

mcmc_specs

The MCMC specifications used in the procedure.

prior_params

The prior parameters used in the procedure.

References

Maleyeff, L., Golchi, S., Moodie, E. E. M., & Hudson, M. (2024) "An adaptive enrichment design using Bayesian model averaging for selection and threshold-identification of predictive variables" doi:10.1093/biomtc/ujae141

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")

A synthetic dataset with continuous and binary covariates and a binary treatment variable (trt).

Description

This dataset was generated using the formula: Y = 2 * Z_1 + 2 * X_1 + 2 * Z_1 * trt + \cos(X_1 \cdot 2 \pi) * trt + \epsilon, where \epsilon \sim N(0, 0.5).

Usage

data(simulated_data)

Format

A data frame with 1000 rows and 8 variables:

X_1

A continuous variable sampled from U(0, 1).

Z_1

A binary variable sampled from Bernoulli(0.35).

Z_2

A binary variable sampled from Bernoulli(0.5).

Z_3

A binary variable sampled from Bernoulli(0.65).

Z_4

A binary variable sampled from Bernoulli(0.2).

Z_5

A binary variable sampled from Bernoulli(0.35).

trt

A binary treatment variable sampled from Bernoulli(0.5).

Y

The outcome variable calculated using the formula above.

Examples

data(simulated_data)
head(simulated_data)

Summarize Results from Reversible Jump MCMC (rjMCMC)

Description

This function provides a detailed summary of the results from the rjMCMC procedure, including model information, parameter estimates, posterior inclusion probabilities, convergence diagnostics, and plots for spline terms. The function also prints the model formula with fbs() notation for spline terms, indicating the use of free-knot B-splines.

Usage

## S3 method for class 'rjMCMC'
summary(object, digits = 3, level = 0.95, pip_cutoff = 0.1, ...)

Arguments

Details

The function produces detailed summaries similar to those from brms, including diagnostics, estimates, posterior inclusion probabilities, and spline effects. The spline terms are wrapped in fbs() notation, indicating the use of free-knot B-splines in the model. If the sampler did not converge, a warning is issued. The function also allows the user to view diagnostic plots for fitted exposure effects.

Value

Prints the following summary information:

Model Formula

The model formula with spline terms wrapped in fbs(), indicating free-knot B-splines, and interaction terms appropriately formatted.

Convergence Diagnostics

Reports any convergence issues based on Geweke diagnostics.

MCMC Sampler Arguments

Displays MCMC sampler arguments, including the number of posterior samples, burn-in, thinning, and chains.

Parameter Estimates

Posterior mean, standard error, 95% credible intervals, effective sample size (ESS), Gelman-Rubin statistic (Rhat), and posterior inclusion probabilities (PIP) for binary parameters, exposure intercept, and exposure effect.

Gaussian Family Parameters

Posterior summary for the residual standard error (sigma).

Posterior Inclusion Probabilities for Splines

Prints the posterior inclusion probabilities for spline terms.

Plots for Fitted Exposure Effects

Plots the mean and 95% credible intervals for each spline term vs fitted exposure effects.

Examples

# Example dataset
data("simulated_data")

candsplinevars <- c("X_1")
candbinaryvars <- paste0("Z_", 1:5)
candinter <- c(candsplinevars, candbinaryvars)

results <- rjMCMC(simulated_data, candsplinevars, candbinaryvars, candinter,
                  outcome = "Y", factor_var = "trt")
summary(results)