adding mcmc_dots and mcmc_dots_by_chain functions

NAMESPACE

@@ -74,6 +74,8 @@ export(mcmc_dens)
 export(mcmc_dens_chains)
 export(mcmc_dens_chains_data)
 export(mcmc_dens_overlay)
+export(mcmc_dots)
+export(mcmc_dots_by_chain)
 export(mcmc_hex)
 export(mcmc_hist)
 export(mcmc_hist_by_chain)

NEWS.md

@@ -1,5 +1,7 @@
 # bayesplot (development version)
 
+* New functions `mcmc_dots` and `mcmc_dots_by_chain` for dot plots of MCMC draws by @behramulukir (#402)
+
 # bayesplot 1.15.0
 
 * Add `shape` argument to `mcmc_scatter` by @behramulukir (#375)

R/mcmc-distributions.R

@@ -12,7 +12,7 @@
 #' @template args-transformations
 #' @template args-facet_args
 #' @template args-density-controls
-#' @param ... Currently ignored.
+#' @param ... For dot plots, optional additional arguments to pass to [ggdist::stat_dots()].
 #' @param alpha Passed to the geom to control the transparency.
 #'
 #' @template return-ggplot
@@ -25,13 +25,19 @@
 #'   \item{`mcmc_dens()`}{
 #'    Kernel density plots of posterior draws with all chains merged.
 #'   }
+#'   \item{`mcmc_dots()`}{
+#'   Dot plots of posterior draws with all chains merged.
+#'   }
 #'   \item{`mcmc_hist_by_chain()`}{
 #'    Histograms of posterior draws with chains separated via faceting.
 #'   }
 #'   \item{`mcmc_dens_overlay()`}{
 #'    Kernel density plots of posterior draws with chains separated but
 #'    overlaid on a single plot.
 #'   }
+#'   \item{`mcmc_dots_by_chain()`}{
+#'   Dot plots of posterior draws with chains separated via faceting.
+#'   }
 #'   \item{`mcmc_violin()`}{
 #'    The density estimate of each chain is plotted as a violin with
 #'    horizontal lines at notable quantiles.
@@ -100,6 +106,33 @@
 #' color_scheme_set("green")
 #' mcmc_violin(x) + panel_bg(color = "gray20", size = 2, fill = "gray30")
 #'
+#'
+#' #################
+#' ### Dot Plots ###
+#' #################
+#'
+#' # dot plots of all parameters
+#' \donttest{
+#' mcmc_dots(x)
+#' }
+#'
+#' # dot plots of some parameters
+#' \donttest{
+#' color_scheme_set("pink")
+#' mcmc_dots(x, pars = c("alpha", "beta[2]"))
+#' }
+#'
+#' # example of using 'transformations' argument to plot log(sigma),
+#' # and and using 'quantiles' to plot number of dots corresponding to quantiles
+#' \donttest{
+#' mcmc_dots(x, transformations = list(sigma = "log"), quantiles = 80)
+#' }
+#'
+#' # separate dot plots by chain
+#' \donttest{
+#' mcmc_dots_by_chain(x, regex_pars = "beta")
+#' }
+#'
 NULL
 
 #' @rdname MCMC-distributions
@@ -362,7 +395,67 @@ mcmc_violin <- function(
   )
 }
 
+#' @rdname MCMC-distributions
+#' @export
+#' @template args-dots
+mcmc_dots <- function(
+    x,
+    pars = character(),
+    regex_pars = character(),
+    transformations = list(),
+    ...,
+    facet_args = list(),
+    binwidth = NA,
+    alpha = 1,
+    quantiles = NA
+) {
+  check_ignored_arguments(..., ok_args = c("dotsize", "layout", "stackratio", "overflow"))
 
+  suggested_package("ggdist")
+
+  .mcmc_dots(
+    x,
+    pars = pars,
+    regex_pars = regex_pars,
+    transformations = transformations,
+    binwidth = binwidth,
+    facet_args = facet_args,
+    alpha = alpha,
+    quantiles = quantiles,
+    ...
+  )
+}
+
+#' @rdname MCMC-distributions
+#' @export
+mcmc_dots_by_chain <- function(
+    x,
+    pars = character(),
+    regex_pars = character(),
+    transformations = list(),
+    ...,
+    facet_args = list(),
+    binwidth = NA,
+    alpha = 1,
+    quantiles = NA
+) {
+  check_ignored_arguments(..., ok_args = c("dotsize", "layout", "stackratio", "overflow"))
+
+  suggested_package("ggdist")
+
+  .mcmc_dots(
+    x,
+    pars = pars,
+    regex_pars = regex_pars,
+    transformations = transformations,
+    binwidth = binwidth,
+    facet_args = facet_args,
+    by_chain = TRUE,
+    alpha = alpha,
+    quantiles = quantiles,
+    ...
+  )
+}
 
 
 # internal -----------------------------------------------------------------
@@ -539,3 +632,64 @@ mcmc_violin <- function(
     yaxis_title(on = n_param == 1 && violin) +
     xaxis_title(on = n_param == 1)
 }
+
+
+.mcmc_dots <- function(
+    x,
+    pars = character(),
+    regex_pars = character(),
+    transformations = list(),
+    facet_args = list(),
+    binwidth = NA,
+    by_chain = FALSE,
+    alpha = 1,
+    quantiles = NA,
+    ...
+) {
+  x <- prepare_mcmc_array(x, pars, regex_pars, transformations)
+
+  if (by_chain && !has_multiple_chains(x)) {
+    STOP_need_multiple_chains()
+  }
+
+  data <- melt_mcmc(x, value.name = "value")
+  n_param <- num_params(data)
+
+  graph <- ggplot(data, aes(x = .data$value)) +
+    ggdist::stat_dots(
+      binwidth = binwidth,
+      quantiles = quantiles,
+      fill = get_color("mid"),
+      color = get_color("mid_highlight"),
+      alpha = alpha,
+      ...
+    )
+
+  facet_args[["scales"]] <- facet_args[["scales"]] %||% "free"
+  if (!by_chain) {
+    if (n_param > 1) {
+      facet_args[["facets"]] <- vars(.data$Parameter)
+      graph <- graph + do.call("facet_wrap", facet_args)
+    }
+  } else {
+    facet_args[["rows"]] <- vars(.data$Chain)
+    if (n_param > 1) {
+      facet_args[["cols"]] <- vars(.data$Parameter)
+    }
+    graph <- graph +
+      do.call("facet_grid", facet_args) +
+      force_axes_in_facets()
+  }
+
+  if (n_param == 1) {
+    graph <- graph + xlab(levels(data$Parameter))
+  }
+
+  graph +
+    dont_expand_y_axis(c(0.005, 0)) +
+    bayesplot_theme_get() +
+    yaxis_text(FALSE) +
+    yaxis_title(FALSE) +
+    yaxis_ticks(FALSE) +
+    xaxis_title(on = n_param == 1)
+}