BEND (version 1.1)

Bayes_BPREM: Bayesian Bivariate Piecewise Random Effects Model (BPREM)

Description

Estimates a Bayesian bivariate piecewise random effects models (BPREM) for longitudinal data with two interrelated outcomes. See Peralta et al. (2022) for more details.

Usage

Bayes_BPREM(
  data,
  id_var,
  time_var,
  y1_var,
  y2_var,
  iters_adapt = 5000,
  iters_burn_in = 1e+05,
  iters_sampling = 50000,
  thin = 15,
  save_full_chains = FALSE,
  save_conv_chains = FALSE,
  verbose = TRUE
)

Value

A list (an object of class BPREM) with elements:

Convergence

Potential scale reduction factor (PSRF) for each parameter (parameter_psrf), Gelman multivariate scale reduction factor (multivariate_psrf), and mean PSRF (mean_psrf) to assess model convergence.

Model_Fit

Deviance (deviance), effective number of parameters (pD), and Deviance information criterion (dic) to assess model fit.

Fitted_Values

Vector giving the fitted value at each timepoint for each individual (same length as long data).

Parameter_Estimates

Data frame with posterior mean and 95% credible intervals for each model parameter.

Run_Time

Total run time for model fitting.

Full_MCMC_Chains

If save_full_chains=TRUE, raw MCMC chains from rjags.

Convergence_MCMC_Chains

If save_conv_chains=TRUE, raw MCMC chains from rjags but only for the parameters monitored for convergence.

Arguments

data

Data frame in long format, where each row describes a measurement occasion for a given individual. It is assumed that each individual has the same number of assigned timepoints (a.k.a., rows). There can be missingness in the outcomes (y1_var and y2_var), but there cannot be missingness in time (time_var).

id_var

Name of column that contains ids for individuals with repeated measures in a longitudinal dataset.

time_var

Name of column that contains the time variable. This column cannot contain any missing values.

y1_var

Name of column that contains the first outcome variable. Missing values should be denoted by NA.

y2_var

Name of column that contains the second outcome variable. Missing values should be denoted by NA.

iters_adapt

(optional) Number of iterations for adaptation of jags model (default = 5000).

iters_burn_in

(optional) Number of iterations for burn-in (default = 100000).

iters_sampling

(optional) Number of iterations for posterior sampling (default = 50000).

thin

(optional) Thinning interval for posterior sampling (default = 15).

save_full_chains

Logical indicating whether the MCMC chains from rjags should be saved (default = FALSE). Note, this should not be used regularly as it will result in an object with a large file size.

save_conv_chains

Logical indicating whether the MCMC chains from rjags should be saved but only for the parameters monitored for convergence (default = FALSE). This would be useful for plotting traceplots for relevant model parameters to evaluate convergence behavior. Note, this should not be used regularly as it will result in an object with a large file size.

verbose

Logical controlling whether progress messages/bars are generated (default = TRUE).

Author

Corissa T. Rohloff, Yadira Peralta

Details

For more information on the model equation and priors implemented in this function, see Peralta et al. (2022).

References

Peralta, Y., Kohli, N., Lock, E. F., & Davison, M. L. (2022). Bayesian modeling of associations in bivariate piecewise linear mixed-effects models. Psychological Methods, 27(1), 44–64. https://doi.org/10.1037/met0000358

Examples

# \donttest{
# load simulated data
data(SimData_BPREM)
# plot observed data
plot_BEND(data = SimData_BPREM,
          id_var = "id",
          time_var = "time",
          y_var = "y1",
          y2_var = "y2")
# fit Bayes_BPREM()
results_bprem <- Bayes_BPREM(data = SimData_BPREM,
                             id_var = "id",
                             time_var = "time",
                             y1_var = "y1",
                             y2_var = "y2")
# result summary
summary(results_bprem)
# plot fitted results
plot_BEND(data = SimData_BPREM,
          id_var = "id",
          time_var = "time",
          y_var = "y1",
          y2_var = "y2",
          results = results_bprem)
# }