Merge pull request #179 from stan-dev/rank-histogram

Rank histogram

Author: jgabry

DESCRIPTION

@@ -29,6 +29,7 @@ Imports:
     utils,
     rlang (>= 0.3.0),
     ggridges,
+    tibble,
     hexbin
 Suggests: 
     gridExtra (>= 2.2.1),

NAMESPACE

@@ -70,6 +70,8 @@ export(mcmc_nuts_treedepth)
 export(mcmc_pairs)
 export(mcmc_parcoord)
 export(mcmc_parcoord_data)
+export(mcmc_rank_hist)
+export(mcmc_rank_overlay)
 export(mcmc_recover_hist)
 export(mcmc_recover_intervals)
 export(mcmc_recover_scatter)
@@ -78,6 +80,7 @@ export(mcmc_rhat_data)
 export(mcmc_rhat_hist)
 export(mcmc_scatter)
 export(mcmc_trace)
+export(mcmc_trace_data)
 export(mcmc_trace_highlight)
 export(mcmc_violin)
 export(neff_ratio)

NEWS.md

@@ -6,6 +6,23 @@
 
 <!-- Items for next release go here* -->
 
+* Two new plots have been added for inspecting the distribution of ranks.
+  Rank-normalized histograms were introduced by the Stan team's [new paper on 
+  MCMC diagnostics](https://arxiv.org/abs/1903.08008). (#178, #179)
+
+  `mcmc_rank_hist()`: A traditional traceplot (`mcmc_trace()`) visualizes how
+  sampled values the MCMC chains mix over the course of sampling. A
+  rank-normalized histogram (`mcmc_rank_hist()`) visualizes how the *ranks* of
+  values from the chains mix together. An ideal plot would show the ranks mixing
+  or overlapping in a uniform distribution. 
+  
+  `mcmc_rank_overlay()`: Instead of drawing each chain's histogram in a separate
+  panel, this plot draws the top edge of the chains' histograms in a single
+  panel.
+  
+* Added `mcmc_trace_data()`, which returns the data used for plotting the trace
+  plots and rank histograms. (Advances #97)
+
 * [ColorBrewer](http://colorbrewer2.org) palettes are now available as color
   schemes via
   [`color_scheme_set()`](https://mc-stan.org/bayesplot/reference/bayesplot-colors.html).
@@ -49,6 +66,12 @@
 * The examples in
   [`?ppc_loo_pit_overlay()`](https://mc-stan.org/bayesplot/reference/PPC-loo.html)
   now work as expected. (#166, #167)
+  
+* Added `"viridisD"` as an alternative name for `"viridis"` to the supported 
+  colors.
+
+* Added `"viridisE"` (the [cividis](https://github.com/marcosci/cividis) 
+  version of viridis) to the supported colors. 
 
 * `ppc_bars()` and `ppc_bars_grouped()` now allow negative integers as input.
   (#172, @jeffpollock9)

R/bayesplot-colors.R

@@ -45,7 +45,7 @@
 #'  * `"teal"`
 #'  * `"yellow"`
 #'  * [`"viridis"`](https://CRAN.R-project.org/package=viridis), `"viridisA"`,
-#'    `"viridisB"`, `"viridisC"`
+#'    `"viridisB"`, `"viridisC"`, `"viridisD"`, `"viridisE"`
 #'  * `"mix-x-y"`, replacing `x` and `y` with any two of
 #'      the scheme names listed above (e.g. "mix-teal-pink", "mix-blue-red",
 #'      etc.). The order of `x` and `y` matters, i.e., the color schemes
@@ -395,7 +395,12 @@ master_color_list <- list(
   viridisB =
     list("#FCFFA4FF", "#FCA50AFF", "#DD513AFF", "#932667FF", "#420A68FF", "#000004FF"),
   viridisC =
-    list("#F0F921FF", "#FCA636FF", "#E16462FF", "#B12A90FF", "#6A00A8FF", "#0D0887FF")
+    list("#F0F921FF", "#FCA636FF", "#E16462FF", "#B12A90FF", "#6A00A8FF", "#0D0887FF"),
+  # popular form of viridis is viridis option D
+  viridisD =
+    list("#FDE725FF", "#7AD151FF", "#22A884FF", "#2A788EFF", "#414487FF", "#440154FF"),
+  viridisE =
+    list("#FFEA46FF", "#CBBA69FF", "#958F78FF", "#666970FF", "#31446BFF", "#00204DFF")
 )
 
 # instantiate aesthetics --------------------------------------------------

R/bayesplot-package.R

@@ -5,7 +5,7 @@
 #' @aliases bayesplot
 #'
 #' @import ggplot2 stats rlang
-#' @importFrom dplyr %>%
+#' @importFrom dplyr %>% summarise group_by select
 #'
 #' @description
 #' \if{html}{

R/helpers-gg.R

@@ -64,12 +64,26 @@ dont_expand_axes <- function() {
 }
 force_axes_in_facets <- function() {
   thm <- bayesplot_theme_get()
-  annotate("segment",
-           x = c(-Inf, -Inf), xend = c(Inf,-Inf),
-           y = c(-Inf,-Inf), yend = c(-Inf, Inf),
-           color = thm$axis.line$colour %||% "black",
-           size = thm$axis.line$size %||% 0.5)
+  annotate(
+    "segment",
+    x = c(-Inf, -Inf), xend = c(Inf,-Inf),
+    y = c(-Inf,-Inf), yend = c(-Inf, Inf),
+    color = thm$axis.line$colour %||% thm$line$colour %||% "black",
+    size = thm$axis.line$size %||% thm$line$size %||% 0.5
+  )
 }
+
+force_x_axis_in_facets <- function() {
+  thm <- bayesplot_theme_get()
+  annotate(
+    "segment",
+    x = -Inf, xend = Inf,
+    y = -Inf, yend = -Inf,
+    color = thm$axis.line$colour %||% thm$line$colour %||% "black",
+    size = thm$axis.line$size %||% thm$line$size %||% 0.5
+  )
+}
+
 no_legend_spacing <- function() {
   theme(legend.spacing.y = unit(0, "cm"))
 }

R/helpers-ppc.R

@@ -151,7 +151,7 @@ validate_x <- function(x = NULL, y, unique_x = FALSE) {
 melt_yrep <- function(yrep) {
   out <- yrep %>%
     reshape2::melt(varnames = c("rep_id", "y_id")) %>%
-    dplyr::as_data_frame()
+    tibble::as_tibble()
   id <- create_yrep_ids(out$rep_id)
   out$rep_label <- factor(id, levels = unique(id))
   out[c("y_id", "rep_id", "rep_label", "value")]
@@ -178,7 +178,7 @@ melt_and_stack <- function(y, yrep) {
   # Add a level in the labels for the observed y values
   levels(molten_yrep$rep_label) <- c(levels(molten_yrep$rep_label), y_text)
 
-  ydat <- dplyr::data_frame(
+  ydat <- tibble::tibble(
     rep_label = factor(y_text, levels = levels(molten_yrep$rep_label)),
     rep_id = NA_integer_,
     y_id = seq_along(y),

R/mcmc-diagnostics.R

@@ -379,7 +379,7 @@ diagnostic_data_frame <- function(x) {
   stopifnot(!anyDuplicated(names(x)))
   diagnostic <- class(x)[1]
 
-  d <- dplyr::data_frame(
+  d <- tibble::tibble(
     diagnostic = diagnostic,
     parameter = factor(seq_along(x), labels = names(x)),
     value = as.numeric(x),