Merge pull request #188 from stan-dev/feature-tidyselect

Feature tidyselect

Author: jgabry

DESCRIPTION

@@ -6,7 +6,7 @@ Date: 2018-08-01
 Authors@R: c(person("Jonah", "Gabry", role = c("aut", "cre"), email = "[email protected]"),
              person("Tristan", "Mahr", role = "aut"),
              person("Paul-Christian", "Bürkner", role = "ctb"),
-             person("Martin", "Modrák", role = "ctb"), 
+             person("Martin", "Modrák", role = "ctb"),
              person("Malcolm", "Barrett", role = "ctb"))
 Maintainer: Jonah Gabry <[email protected]>
 Description: Plotting functions for posterior analysis, posterior predictive checks,
@@ -25,10 +25,12 @@ Imports:
     dplyr (>= 0.8.0),
     ggplot2 (>= 2.2.1),
     ggridges,
+    glue,
     reshape2,
     rlang (>= 0.3.0),
     stats,
     tibble,
+    tidyselect,
     utils
 Suggests: 
     gridExtra (>= 2.2.1),

NAMESPACE

@@ -89,6 +89,8 @@ export(overlay_function)
 export(pairs_condition)
 export(pairs_style_np)
 export(panel_bg)
+export(param_glue)
+export(param_range)
 export(parcoord_style_np)
 export(plot_bg)
 export(pp_check)
@@ -132,6 +134,7 @@ export(rhat)
 export(scatter_style_np)
 export(theme_default)
 export(trace_style_np)
+export(vars)
 export(vline_0)
 export(vline_at)
 export(xaxis_text)
@@ -158,6 +161,7 @@ importFrom(dplyr,select)
 importFrom(dplyr,summarise)
 importFrom(dplyr,top_n)
 importFrom(dplyr,ungroup)
+importFrom(dplyr,vars)
 importFrom(ggplot2,"%+replace%")
 importFrom(ggridges,geom_density_ridges)
 importFrom(ggridges,geom_density_ridges2)

NEWS.md

@@ -6,6 +6,9 @@
 
 <!-- Items for next release go here* -->
 
+* The `pars` argument of all MCMC plotting functions now supports tidy variable selection.
+  See `help("tidy-params", package="bayesplot")` for details and examples. (#161, #183, #188)
+
 * Two new plots have been added for inspecting the distribution of ranks.
   Rank histograms were introduced by the Stan team's [new paper on 
   MCMC diagnostics](https://arxiv.org/abs/1903.08008). (#178, #179)
@@ -41,21 +44,21 @@
   curves. The default `"equal area"` constrains the heights so that the curves 
   have the same area. As a result, a narrow interval will appear as a spike 
   of density, while a wide, uncertain interval is spread thin over the _x_ axis.
-  Alternatively `"equal height"` will set the maximum height on each curve to 
-  the same value. This works well when the intervals are about the same width. 
-  Otherwise, that wide, uncertain interval will dominate the visual space 
-  compared to a narrow, less uncertain interval. A compromise between the two is 
-  `"scaled height"` which scales the curves from `"equal height"` using 
+  Alternatively `"equal height"` will set the maximum height on each curve to
+  the same value. This works well when the intervals are about the same width.
+  Otherwise, that wide, uncertain interval will dominate the visual space
+  compared to a narrow, less uncertain interval. A compromise between the two is
+  `"scaled height"` which scales the curves from `"equal height"` using
   `height * sqrt(height)`. (#163, #169)
-  
-* `mcmc_areas()` correctly plots density curves where the point estimate 
-  does not include the highest point of the density curve. 
+
+* `mcmc_areas()` correctly plots density curves where the point estimate
+  does not include the highest point of the density curve.
   (#168, #169, @jtimonen)
-  
-* `mcmc_areas_ridges()` draws the vertical line at *x* = 0 over the curves so 
+
+* `mcmc_areas_ridges()` draws the vertical line at *x* = 0 over the curves so
   that it is always visible.
 
-* `mcmc_intervals()` and `mcmc_areas()` raise a warning if `prob_outer` is ever 
+* `mcmc_intervals()` and `mcmc_areas()` raise a warning if `prob_outer` is ever
   less than `prob`. It sorts these two values into the correct order. (#138)
 
 * MCMC parameter names are now *always* converted to factors prior to
@@ -148,7 +151,7 @@
 
 * Added `mcmc_intervals_data()` and `mcmc_areas_data()` that return data
   plotted by `mcmc_intervals()` and `mcmc_areas()`. (Advances #97)
-  
+
 * New `ppc_data()` function returns the data plotted by many of the PPC plotting
   functions. (Advances #97)
 
@@ -165,29 +168,29 @@
 
 (GitHub issue/PR numbers in parentheses)
 
-* New plotting function `mcmc_parcoord()` for parallel coordinates plots of 
+* New plotting function `mcmc_parcoord()` for parallel coordinates plots of
   MCMC draws (optionally including HMC/NUTS diagnostic information). (#108)
-  
+
 * `mcmc_scatter` gains an `np` argument for specifying NUTS parameters, which
   allows highlighting divergences in the plot. (#112)
-  
-* New functions with names ending with suffix `_data` don't make the plots, 
-  they just return the data prepared for plotting (more of these to come in 
+
+* New functions with names ending with suffix `_data` don't make the plots,
+  they just return the data prepared for plotting (more of these to come in
   future releases):
     - `ppc_intervals_data()` (#101)
     - `ppc_ribbon_data()` (#101)
     - `mcmc_parcoord_data()` (#108)
     - `mcmc_rhat_data()` (#110)
     - `mcmc_neff_data()` (#110)
-    
-* `ppc_stat_grouped()`, `ppc_stat_freqpoly_grouped()` gain a `facet_args` 
-  argument for controlling **ggplot2** faceting (many of the `mcmc_` functions 
+
+* `ppc_stat_grouped()`, `ppc_stat_freqpoly_grouped()` gain a `facet_args`
+  argument for controlling **ggplot2** faceting (many of the `mcmc_` functions
   already have this).
-  
-* The `divergences` argument to `mcmc_trace()` has been deprecated in favor 
-  of `np` (NUTS parameters) to match the other functions that have an `np` 
+
+* The `divergences` argument to `mcmc_trace()` has been deprecated in favor
+  of `np` (NUTS parameters) to match the other functions that have an `np`
   argument.
-  
+
 * Fixed an issue where duplicated rhat values would break `mcmc_rhat()` (#105).
 
 
@@ -316,5 +319,5 @@ Initial CRAN release
 
 
 
-[ggridges]: https://CRAN.R-project.org/package=ggridges 
+[ggridges]: https://CRAN.R-project.org/package=ggridges
             "ggridges package"

R/helpers-mcmc.R

@@ -1,9 +1,10 @@
-# Prepare 3-D array for MCMC plots
-#
-# @param x,pars,regex_pars,transformations Users's arguments to one of the
-#   mcmc_* functions.
-# @return A 3-D (Iterations x Chains x Parameters) array.
-#
+#' Prepare 3-D array for MCMC plots
+#'
+#' @noRd
+#' @param x,pars,regex_pars,transformations Users's arguments to one of the
+#'   mcmc_* functions.
+#' @return A 3-D (Iterations x Chains x Parameters) array.
+#'
 prepare_mcmc_array <- function(x,
                                pars = character(),
                                regex_pars = character(),
@@ -29,12 +30,14 @@ prepare_mcmc_array <- function(x,
     abort("NAs not allowed in 'x'.")
   }
 
-  parnames <- parameter_names(x)
-  pars <- select_parameters(
-    explicit = pars,
-    patterns = regex_pars,
-    complete = parnames
-  )
+  if (rlang::is_quosures(pars)) {
+    pars <- tidyselect_parameters(complete_pars = parameter_names(x),
+                                  pars_list = pars)
+  } else {
+    pars <- select_parameters(complete_pars = parameter_names(x),
+                              explicit = pars,
+                              patterns = regex_pars)
+  }
 
   # possibly recycle transformations (apply same to all pars)
   if (is.function(transformations) ||
@@ -61,12 +64,63 @@ prepare_mcmc_array <- function(x,
 }
 
 
-# Melt a 3-D array or matrix of MCMC draws
-#
-# @param x An mcmc_array (from prepare_mcmc_array).
-# @param varnames,value.name,... Passed to reshape2::melt (array method).
-# @return A molten data frame.
-#
+#' Explicit and/or regex parameter selection
+#'
+#' @noRd
+#' @param explicit Character vector of selected parameter names.
+#' @param patterns Character vector of regular expressions.
+#' @param complete_pars Character vector of all possible parameter names.
+#' @return Character vector of combined explicit and matched (via regex)
+#'   parameter names, unless an error is thrown.
+#'
+select_parameters <-
+  function(explicit = character(),
+           patterns = character(),
+           complete_pars = character()) {
+
+    stopifnot(is.character(explicit),
+              is.character(patterns),
+              is.character(complete_pars))
+
+    if (!length(explicit) && !length(patterns)) {
+      return(complete_pars)
+    }
+
+    if (length(explicit)) {
+      if (!all(explicit %in% complete_pars)) {
+        not_found <- which(!explicit %in% complete_pars)
+        abort(paste(
+          "Some 'pars' don't match parameter names:",
+          paste(explicit[not_found], collapse = ", "),
+          call. = FALSE
+        ))
+      }
+    }
+
+    if (!length(patterns)) {
+      return(unique(explicit))
+    } else {
+      regex_pars <-
+        unlist(lapply(seq_along(patterns), function(j) {
+          grep(patterns[j], complete_pars, value = TRUE)
+        }))
+
+      if (!length(regex_pars)) {
+        abort("No matches for 'regex_pars'.")
+      }
+    }
+
+    unique(c(explicit, regex_pars))
+  }
+
+
+#' Melt a 3-D array or matrix of MCMC draws
+#'
+#' @noRd
+#' @param x An mcmc_array (from prepare_mcmc_array).
+#' @param varnames,value.name,... Passed to reshape2::melt (array method).
+#' @return A molten data frame.
+#'
 melt_mcmc <- function(x, ...) UseMethod("melt_mcmc")
 melt_mcmc.mcmc_array <- function(x,
                                  varnames =
@@ -103,9 +157,11 @@ melt_mcmc.matrix <- function(x,
   long
 }
 
-# Set dimnames of 3-D array
-# @param x 3-D array
-# @param parnames Character vector of parameter names
+#' Set dimnames of 3-D array
+#' @noRd
+#' @param x 3-D array
+#' @param parnames Character vector of parameter names
+#' @return x with a modified dimnames.
 set_mcmc_dimnames <- function(x, parnames) {
   stopifnot(is_3d_array(x))
   dimnames(x) <- list(
@@ -116,11 +172,12 @@ set_mcmc_dimnames <- function(x, parnames) {
   structure(x, class = c(class(x), "mcmc_array"))
 }
 
-# Convert 3-D array to matrix with chains merged
-#
-# @param x A 3-D array (iter x chain x param)
-# @return A matrix with one column per parameter
-#
+#' Convert 3-D array to matrix with chains merged
+#'
+#' @noRd
+#' @param x A 3-D array (iter x chain x param)
+#' @return A matrix with one column per parameter
+#'
 merge_chains <- function(x) {
   xdim <- dim(x)
   mat <- array(x, dim = c(prod(xdim[1:2]), xdim[3]))
@@ -129,10 +186,11 @@ merge_chains <- function(x) {
 }
 
 
-# Check if an object is a data.frame with a chain index column
-#
-# @param x object to check
-# @return TRUE or FALSE
+#' Check if an object is a data.frame with a chain index column
+#'
+#' @noRd
+#' @param x object to check
+#' @return TRUE or FALSE
 is_df_with_chain <- function(x) {
   is.data.frame(x) && any(tolower(colnames(x)) %in% "chain")
 }
@@ -167,11 +225,11 @@ df_with_chain2array <- function(x) {
 }
 
 
-# Check if an object is a list (but not a data.frame) that contains
-# all 2-D objects
-#
-# @param x object to check
-# @return TRUE or FALSE
+#' Check if an object is a list (but not a data.frame) that contains
+#' all 2-D objects
+#' @noRd
+#' @param x object to check
+#' @return TRUE or FALSE
 is_chain_list <- function(x) {
   check1 <- !is.data.frame(x) && is.list(x)
   dims <- try(sapply(x, function(chain) length(dim(chain))), silent=TRUE)
@@ -316,13 +374,14 @@ validate_transformations <-
   }
 
 
-# Apply transformations to matrix or 3-D array of parameter draws
-#
-# @param x A matrix or 3-D array of draws
-# @param transformation User's 'transformations' argument to one of the mcmc_*
-#   functions.
-# @return x, with tranformations having been applied to some parameters.
-#
+#' Apply transformations to matrix or 3-D array of parameter draws
+#'
+#' @noRd
+#' @param x A matrix or 3-D array of draws
+#' @param transformation User's 'transformations' argument to one of the mcmc_*
+#'   functions.
+#' @return x, with tranformations having been applied to some parameters.
+#'
 apply_transformations <- function(x, transformations = list(), ...) {
   UseMethod("apply_transformations")
 }
@@ -395,4 +454,3 @@ num_iters.data.frame <- function(x, ...) {
 
   n
 }
-