Update package documentation.

Easybgm shim.

Author: MaartenMarsman

R/bgm.R

@@ -392,8 +392,6 @@ bgm = function(
   }
   if(hasArg(save)) {
     warning("The argument save is deprecated. Everything is saved in the function output.")
-  } else {
-    save = TRUE
   }
   if(hasArg(threshold_alpha) || hasArg(threshold_beta)) {
     if(!hasArg(main_alpha))
@@ -607,14 +605,34 @@ bgm = function(
     hmc_num_leapfrogs = hmc_num_leapfrogs,
     nuts_max_depth = nuts_max_depth,
     learn_mass_matrix = learn_mass_matrix,
-    num_chains = chains, save = save
+    num_chains = chains
   )
 
   if (update_method == "nuts") {
     nuts_diag = summarize_nuts_diagnostics(out, nuts_max_depth = nuts_max_depth)
     output$nuts_diag = nuts_diag
   }
 
+  # -------------------------------------------------------------------
+  # TODO: REMOVE after easybgm >= 0.2.2 is on CRAN
+  # Compatibility shim for easybgm <= 0.2.1
+  # -------------------------------------------------------------------
+  if ("easybgm" %in% loadedNamespaces()) {
+    ebgm_version <- utils::packageVersion("easybgm")
+    if (ebgm_version <= "0.2.1") {
+      warning("bgms is running in compatibility mode for easybgm (<= 0.2.1). ",
+              "This will be removed once easybgm is updated on CRAN.")
+
+      # Add legacy variables to output
+      output$arguments$save <- TRUE
+      if (edge_selection) {
+        output$indicator <- extract_indicators(output)
+      }
+      output$interactions <- extract_pairwise_interactions(output)
+      output$thresholds   <- extract_category_thresholds(output)
+    }
+  }
+
   userInterrupt = any(vapply(out, FUN = `[[`, FUN.VALUE = logical(1L), "userInterrupt"))
   if (userInterrupt)
     warning("Stopped sampling after user interrupt, results are likely uninterpretable.")

R/bgms-package.R

@@ -2,58 +2,55 @@
 #'
 #' @description
 #' The \code{R} package \strong{bgms} provides tools for Bayesian analysis of
-#' the ordinal Markov random field, a graphical model describing a network of
-#' binary and/or ordinal variables \insertCite{MarsmanVandenBerghHaslbeck_2024}{bgms}.
-#' A pseudolikelihood is used to approximate the likelihood of the graphical
-#' model, and Markov chain Monte Carlo methods are used to simulate from the
-#' corresponding pseudoposterior distribution of the graphical model parameters.
+#' the ordinal Markov random field (MRF), a graphical model describing networks
+#' of binary and/or ordinal variables \insertCite{MarsmanVandenBerghHaslbeck_2024}{bgms}.
+#' The likelihood is approximated via a pseudolikelihood, and Markov chain Monte
+#' Carlo (MCMC) methods are used to sample from the corresponding pseudoposterior
+#' distribution of model parameters.
 #'
-#' The \strong{bgm} function can be used for a one-sample design and the
-#' \strong{bgmCompare} function can be used for a two-independent-samples design
-#' \insertCite{MarsmanWaldorpSekulovskiHaslbeck_2024}{bgms}. Both functions can
-#' model the selection of effects. In one-sample designs, the \strong{bgm}
-#' function models the presence or absence of edges between pairs of variables
-#' in the network. The estimated posterior inclusion probability indicates how
-#' plausible it is that a network with an edge between the two corresponding
-#' variables produced the observed data, and can be converted into a Bayes
-#' factor test for conditional independence.
+#' The main entry points are:
+#' \itemize{
+#'   \item \strong{bgm}: estimation in a one-sample design.
+#'   \item \strong{bgmCompare}: estimation and group comparison in an
+#'         independent-sample design.
+#' }
+#'
+#' Both functions support Bayesian effect selection with spike-and-slab priors.
+#' \itemize{
+#'   \item In one-sample designs, \code{bgm} models the presence or absence of
+#'   edges between variables. Posterior inclusion probabilities quantify the
+#'   plausibility of each edge and can be converted into Bayes factors for
+#'   conditional independence tests.
 #'
-#' In two-independent-samples designs, the \strong{bgmCompare} function models
-#' the selection of group differences in edge weights and possibly category
-#' thresholds. The estimated posterior inclusion probability indicates how
-#' plausible it is that graphical models with a difference in the corresponding
-#' edge weight or category threshold generated the data at hand, and can be
-#' converted to a Bayes factor test for parameter equivalence.
+#'   \item \code{bgm} can also model communities (clusters) of variables. The
+#'   posterior distribution of the number of clusters provides evidence for or
+#'   against clustering \insertCite{SekulovskiEtAl_2025}{bgms}.
 #'
-#' The \strong{bgms} package offers several tools for analyzing the structure of
-#' the MRF:
+#'   \item In independent-sample designs, \code{bgmCompare} estimates group
+#'   differences in edge weights and category thresholds. Posterior inclusion
+#'   probabilities quantify the evidence for differences and can be converted
+#'   into Bayes factors for parameter equivalence tests
+#'   \insertCite{MarsmanWaldorpSekulovskiHaslbeck_2024}{bgms}.
+#' }
 #'
+#' @section Tools:
+#' The package also provides:
 #' \enumerate{
-#'  \item Simulate response data from the MRF using the Gibbs sampler.
-#'  \itemize{
-#'    \item Simulate \code{\link{mrfSampler}}.
-#'  }
-#
-#'  \item Estimate the posterior distribution of the MRF's parameters and
-#'  possibly its network structure in one-sample designs.
-#'  \itemize{
-#'  \item Bayesian estimation or Bayesian edge selection with \code{\link{bgm}}.
-#'  }
-#'
-#'  \item Estimate the posterior distribution of the MRF's parameters in a
-#'  two-independent-sample design, and possibly perform selection on group
-#'  differences in MRF parameters.
-#'  \itemize{
-#'  \item Bayesian estimation or Bayesian difference selection with \code{\link{bgmCompare}}.
-#'  }
+#'   \item Simulation of response data from MRFs with a Gibbs sampler
+#'         (\code{\link{mrfSampler}}).
+#'   \item Posterior estimation and edge selection in one-sample designs
+#'         (\code{\link{bgm}}).
+#'   \item Posterior estimation and group-difference selection in
+#'         independent-sample designs (\code{\link{bgmCompare}}).
 #' }
 #'
 #' @section Vignettes:
 #' For tutorials and worked examples, see:
 #' \itemize{
-#'   \item \code{vignette("intro", package = "bgms")} for a getting started guide.
-#'   \item \code{vignette("comparison", package = "bgms")} for model comparison.
-#'   \item \code{vignette("diagnostics", package = "bgms")} for diagnostics and spike-and-slab summaries.
+#'   \item \code{vignette("intro", package = "bgms")} — Getting started.
+#'   \item \code{vignette("comparison", package = "bgms")} — Model comparison.
+#'   \item \code{vignette("diagnostics", package = "bgms")} — Diagnostics and
+#'         spike-and-slab summaries.
 #' }
 #'
 #' @docType package

R/output_utils.R

@@ -4,7 +4,7 @@ prepare_output_bgm = function(
     na_action, na_impute, edge_selection, edge_prior, inclusion_probability,
     beta_bernoulli_alpha, beta_bernoulli_beta, dirichlet_alpha, lambda,
     variable_type, update_method, target_accept, hmc_num_leapfrogs,
-    nuts_max_depth, learn_mass_matrix, num_chains, save
+    nuts_max_depth, learn_mass_matrix, num_chains
 ) {
   arguments = list(
     prepared_data = x,
@@ -34,8 +34,7 @@ prepare_output_bgm = function(
     num_chains = num_chains,
     num_categories = num_categories,
     data_columnnames = data_columnnames,
-    no_variables = ncol(x), #backwards compatibility easybgm
-    save = save #backwards compatibility easybgm
+    no_variables = ncol(x) #backwards compatibility easybgm
   )
 
   num_variables = ncol(x)