expand documentation

Author: tjmahr

R/tidy-params.R

@@ -1,29 +1,60 @@
 #' Tidy parameter selection
 #'
+#' Parameter selection in the style of **dplyr** and other tidyverse packages.
+#'
 #' @name tidy-params
 #'
-#' @description As of version `1.7.0`, **bayesplot** allows the `pars` argument
-#'   for [MCMC plots][bayesplot::MCMC-overview] to be used for so-called 'tidy'
-#'   variable selection (in the style of the **dplyr** package).
-#'   The [`vars()`][dplyr::vars] function is re-exported from **dplyr**
-#'   for this purpose. See the **Examples** section, below.
-#'
-#'   When using `pars` for tidy parameter selection, the `regex_pars` argument
-#'   is ignored because **bayesplot** supports using
-#'   [tidyselect helper functions][tidyselect::select_helpers]
-#'   (`starts_with()`, `contains()`, `num_range()`, etc.) for the same purpose.
-#'   **bayesplot** also exports some additional helper functions
-#'   to help with parameter selection:
+#' @details
+#' As of version `1.7.0`, **bayesplot** allows the `pars` argument for [MCMC
+#' plots][bayesplot::MCMC-overview] to use "tidy" variable selection (in the
+#' style of the **dplyr** package). The [`vars()`][dplyr::vars] function is
+#' re-exported from **dplyr** for this purpose.
+#'
+#' Features of tidy selection includes direct selection (`vars(alpha, sigma)`),
+#' everything-but selection (`vars(-alpha)`), ranged selection
+#' (``vars(`beta[1]`:`beta[3]`)``), support for selection functions
+#' (`vars(starts_with("beta"))`), and combinations of these features. See the
+#' **Examples** section, below.
+#'
+#' When using `pars` for tidy parameter selection, the `regex_pars` argument is
+#' ignored because **bayesplot** supports using [tidyselect helper
+#' functions][tidyselect::select_helpers] (`starts_with()`, `contains()`,
+#' `num_range()`, etc.) for the same purpose. **bayesplot** also exports some
+#' additional helper functions to help with parameter selection:
+#'
 #'   * `param_range()`: like [`num_range()`][tidyselect::num_range] but used
 #'     when parameter indexes are in brackets (e.g. `beta[2]`).
+#'
 #'   * `param_glue()`: for more complicated parameter names with multiple
 #'     indexes (including variable names) inside the brackets
 #'     (e.g., `beta[(Intercept) age_group:3]`).
 #'
 #'   These functions can be used inside of `vars()`, `dplyr::select()`,
 #'   and similar functions, just like the
 #'   [tidyselect helper functions][tidyselect::select_helpers].
-#'   See the **Examples** section.
+#'
+#' @section Extra Advice:
+#'
+#'   Parameter names in `vars()` are not quoted. When the names contain special
+#'   characters like brackets, they should be wrapped in backticks, as in
+#'   ``vars(`beta[1]`)``.
+#'
+#'   To exclude a range of variables, wrap the sequence in parentheses and then
+#'   negate it. For example, (``vars(-(`beta[1]`:`beta[3]`))``) would exclude
+#'   `beta[1]`, `beta[2]`, and `beta[3]`.
+#'
+#'   `vars()` is a helper function. It holds onto the names and expressions used
+#'   to select columns. When selecting variables inside a **bayesplot**
+#'   function, use `vars(...)`: `mcmc_hist(data, pars = vars(alpha))`. When
+#'   using `select()` to prepare a dataframe for a **bayesplot** function, do
+#'   not use `vars()`: `data %>% select(alpha) %>% mcmc_hist()`.
+#'
+#'   Internally, tidy selection works by converting names and expressions
+#'   into position numbers. As a result, integers will select parameters;
+#'   `vars(1, 3)` selects the first and third ones. We do not endorse this
+#'   approach because positions might change as variables are added and
+#'   removed from models. To select a parameter that happens to be called `1`,
+#'   use backticks to escape it ``vars(`1`)``.
 #'
 #' @seealso [glue::glue()]
 #'
@@ -81,7 +112,6 @@
 #'     mcmc_intervals()
 #' }
 #'}
-#'
 NULL
 
 # re-export vars for tidy parameter selection
@@ -128,36 +158,29 @@ param_range <- function(prefix, range, vars = NULL) {
 #'
 #'   would select parameters with names
 #'   `"beta_age[3]"`, `"beta_income[3]"`, `"beta_age[8]"`, `"beta_income[8]"`.
-#'   See the **Examples** section below for demonstrations.
 #'
 #' @examples
 #' \dontrun{
 #' ###################################
 #' ## More examples of param_glue() ##
 #' ###################################
 #' library(dplyr)
-#' posterior <-
-#'  structure(list(
-#'    b_Intercept = rnorm(1000),
-#'    sd_condition__Intercept = rexp(1000),
-#'    sigma = rexp(1000),
-#'    `r_condition[A,Intercept]` = rnorm(1000),
-#'    `r_condition[B,Intercept]` = rnorm(1000),
-#'    `r_condition[C,Intercept]` = rnorm(1000),
-#'    `r_condition[A,Slope]` = rnorm(1000),
-#'    `r_condition[B,Slope]` = rnorm(1000)
-#'   ),
-#'   class = c("tbl_df", "tbl", "data.frame"),
-#'   row.names = c(NA, -1000L)
-#'   )
-#' str(posterior)
+#' posterior <- tibble(
+#'   b_Intercept = rnorm(1000),
+#'   sd_condition__Intercept = rexp(1000),
+#'   sigma = rexp(1000),
+#'   `r_condition[A,Intercept]` = rnorm(1000),
+#'   `r_condition[B,Intercept]` = rnorm(1000),
+#'   `r_condition[C,Intercept]` = rnorm(1000),
+#'   `r_condition[A,Slope]` = rnorm(1000),
+#'   `r_condition[B,Slope]` = rnorm(1000)
+#' )
+#' posterior
 #'
 #' # using one expression in braces
 #' posterior %>%
 #'   select(
-#'     param_glue(
-#'       "r_condition[{level},Intercept]",
-#'       level = c("A", "B"))
+#'     param_glue("r_condition[{level},Intercept]", level = c("A", "B"))
 #'   ) %>%
 #'   mcmc_hist()
 #'
@@ -171,7 +194,6 @@ param_range <- function(prefix, range, vars = NULL) {
 #'    ) %>%
 #'    mcmc_hist()
 #'}
-#'
 param_glue <- function(pattern, ..., vars = NULL) {
   if (!is.null(vars) && !is.character(vars)) {
     abort("'vars' must be NULL or a character vector.")
@@ -191,17 +213,19 @@ param_glue <- function(pattern, ..., vars = NULL) {
 #' `pars` argument is a quosure.
 #'
 #' @noRd
-#' @md
 #' @param complete_pars A character vector of *all* parameter names.
 #' @param pars_list A list of columns generated by `vars()`.
 #' @return Character vector of selected parameter names.
-#'
 tidyselect_parameters <- function(complete_pars, pars_list) {
+  # We use the list of helpers so that we don't have to keep track of any
+  # changes to tidyselect. We use `env_bury()`` so that the definitions of
+  # selection helpers are available. This pattern is taken from the example code
+  # in `vars_select_helpers`.
   helpers <- tidyselect::vars_select_helpers
   pars_list <- lapply(pars_list, rlang::env_bury, !!! helpers)
   selected <- tidyselect::vars_select(.vars = complete_pars, !!! pars_list)
   if (!length(selected)) {
     abort("No parameters were found matching those names.")
   }
-  return(unname(selected))
+  unname(selected)
 }