From a883cd83b1bd7d88f5dcf9f4cbc42cde62d6505e Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 16 May 2019 00:20:21 -0400 Subject: [PATCH 1/8] run roxygen2md and start fixing by hand --- DESCRIPTION | 1 + R/available-module-functions.R | 8 +- R/bayesplot-colors.R | 7 +- R/bayesplot-extractors.R | 30 ++-- R/bayesplot-ggplot-themes.R | 54 +++--- R/bayesplot-helpers.R | 163 ++++++++---------- R/bayesplot-package.R | 48 +++--- R/bayesplot_grid.R | 22 +-- R/example-data.R | 40 ++--- R/helpers-gg.R | 2 +- R/helpers-ppc.R | 36 ++-- R/helpers-shared.R | 4 +- R/helpers-testthat.R | 9 +- R/mcmc-combo.R | 34 ++-- R/mcmc-diagnostics-nuts.R | 124 ++++++-------- R/mcmc-diagnostics.R | 66 ++++---- R/mcmc-distributions.R | 20 +-- R/mcmc-intervals.R | 45 +++-- R/mcmc-overview.R | 95 +++++------ R/mcmc-parcoord.R | 60 ++++--- R/mcmc-recover.R | 38 ++--- R/mcmc-scatterplots.R | 252 ++++++++++++++-------------- R/mcmc-traces.R | 42 ++--- R/pp_check.R | 40 +++-- R/ppc-discrete.R | 93 +++++----- R/ppc-distributions.R | 74 ++++---- R/ppc-errors.R | 62 +++---- R/ppc-intervals.R | 40 ++--- R/ppc-loo.R | 82 ++++----- R/ppc-overview.R | 32 ++-- R/ppc-scatterplots.R | 22 +-- R/ppc-test-statistics.R | 30 ++-- man-roxygen/args-by_chain.R | 2 +- man-roxygen/args-dens.R | 2 +- man-roxygen/args-density-controls.R | 4 +- man-roxygen/args-facet_args.R | 4 +- man-roxygen/args-group.R | 4 +- man-roxygen/args-hist-freq.R | 6 +- man-roxygen/args-hist.R | 6 +- man-roxygen/args-mcmc-x.R | 6 +- man-roxygen/args-pars.R | 4 +- man-roxygen/args-prob-prob_outer.R | 2 +- man-roxygen/args-regex_pars.R | 6 +- man-roxygen/args-transformations.R | 23 ++- man-roxygen/args-y-yrep.R | 11 +- man-roxygen/details-binomial.R | 2 +- man-roxygen/reference-bda.R | 2 +- man-roxygen/reference-betancourt.R | 4 +- man-roxygen/reference-loo.R | 4 +- man-roxygen/reference-nuts.R | 4 +- man-roxygen/reference-stan-manual.R | 5 +- man-roxygen/reference-vis-paper.R | 10 +- man-roxygen/return-ggplot-or-data.R | 6 +- man-roxygen/return-ggplot.R | 3 +- man-roxygen/seealso-colors.R | 2 +- man-roxygen/seealso-helpers.R | 2 +- man-roxygen/seealso-theme.R | 4 +- 57 files changed, 865 insertions(+), 938 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index b5b2de4c6..d74895793 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -46,3 +46,4 @@ Suggests: RoxygenNote: 6.1.1 VignetteBuilder: knitr Encoding: UTF-8 +Roxygen: list(markdown = TRUE) diff --git a/R/available-module-functions.R b/R/available-module-functions.R index 7acb42e1c..64fa32023 100644 --- a/R/available-module-functions.R +++ b/R/available-module-functions.R @@ -1,12 +1,12 @@ #' Get or view the names of available plotting functions #' #' @export -#' @param pattern,fixed,invert Passed to \code{\link[base]{grep}}. +#' @param pattern,fixed,invert Passed to [base::grep()]. #' @return A possibly empty character vector of function names with several -#' additional attributes (for use by a custom print method). If \code{pattern} +#' additional attributes (for use by a custom print method). If `pattern` #' is missing then the returned object contains the names of all available -#' plotting functions in the \link{MCMC} or \link{PPC} module, depending on -#' which function is called. If \code{pattern} is specified then a subset of +#' plotting functions in the [MCMC] or [PPC] module, depending on +#' which function is called. If `pattern` is specified then a subset of #' function names is returned. #' #' @examples diff --git a/R/bayesplot-colors.R b/R/bayesplot-colors.R index 250a17fed..bba823e99 100644 --- a/R/bayesplot-colors.R +++ b/R/bayesplot-colors.R @@ -5,7 +5,6 @@ #' of available scheme names. The **Custom color schemes** section describes how #' to specify a custom scheme. #' -#' @md #' @name bayesplot-colors #' @param scheme For `color_scheme_set()`, either a string naming one of the #' available color schemes or a character vector of _exactly six_ colors @@ -289,9 +288,9 @@ mixed_scheme <- function(scheme1, scheme2) { scheme } -#' Check if object returned by color_scheme_get() is a mixed scheme +#' Check if object returned by `color_scheme_get()` is a mixed scheme #' @noRd -#' @param x object returned by color_scheme_get() +#' @param x object returned by `color_scheme_get()` #' @return T/F is_mixed_scheme <- function(x) { stopifnot(is.list(x)) @@ -300,7 +299,7 @@ is_mixed_scheme <- function(x) { #' Access a subset of the current scheme colors #' @noRd -#' @param level A character vector of level names scheme_level_names(). +#' @param level A character vector of level names in `scheme_level_names()`. #' The abbreviations "l", "lh", "m", "mh", "d", and "dh" can also be used #' instead of the full names. #' @return A character vector of color values. diff --git a/R/bayesplot-extractors.R b/R/bayesplot-extractors.R index eefe0095e..ae93db992 100644 --- a/R/bayesplot-extractors.R +++ b/R/bayesplot-extractors.R @@ -2,36 +2,34 @@ #' #' Generics and methods for extracting quantities needed for plotting from #' various types of model objects. Currently methods are only provided for -#' stanfit (\pkg{rstan}) and stanreg (\pkg{rstanarm}) objects, but adding new +#' stanfit (**rstan**) and stanreg (**stanreg**) objects, but adding new #' methods should be relatively straightforward. #' #' @name bayesplot-extractors #' @param object The object to use. #' @param ... Arguments passed to individual methods. #' @param pars An optional character vector of parameter names. For -#' \code{nuts_params} these will be NUTS sampler parameter names rather than -#' model parameters. If \code{pars} is omitted all parameters are included. +#' `nuts_params()` these will be NUTS sampler parameter names rather than +#' model parameters. If `pars` is omitted all parameters are included. #' #' @return #' \describe{ -#' \item{\code{log_posterior}}{ -#' \code{log_posterior} methods return a molten data frame (see -#' \code{\link[reshape2]{melt}}). The data frame should have columns -#' \code{"Iteration"} (integer), \code{"Chain"} (integer), and \code{"Value"} -#' (numeric). See \strong{Examples}, below. +#' \item{`log_posterior()`}{ +#' `log_posterior()` methods return a molten data frame (see [reshape2::melt()]). +#' The data frame should have columns `"Iteration"` (integer), `"Chain"` +#' (integer), and `"Value"` (numeric). See **Examples**, below. #' } -#' \item{\code{nuts_params}}{ -#' \code{nuts_params} methods return a molten data frame (see -#' \code{\link[reshape2]{melt}}). The data frame should have columns -#' \code{"Parameter"} (factor), \code{"Iteration"} (integer), \code{"Chain"} -#' (integer), and \code{"Value"} (numeric). See \strong{Examples}, below. +#' \item{`nuts_params()`}{ +#' `nuts_params()` methods return a molten data frame (see [reshape2::melt()]). +#' The data frame should have columns `"Parameter"` (factor), `"Iteration"` +#' (integer), `"Chain"` (integer), and `"Value"` (numeric). See **Examples**, below. #' } -#' \item{\code{rhat}, \code{neff_ratio}}{ +#' \item{`rhat()`, `neff_ratio()`}{ #' Methods return (named) vectors. #' } #' } #' -#' @seealso \code{\link{MCMC-nuts}}, \code{\link{MCMC-diagnostics}} +#' @seealso [MCMC-nuts], [MCMC-diagnostics] #' #' @examples #' \dontrun{ @@ -80,7 +78,7 @@ neff_ratio <- function(object, ...) { #' @rdname bayesplot-extractors #' @export #' @method log_posterior stanfit -#' @param inc_warmup A logical scalar (defaulting to \code{FALSE}) indicating +#' @param inc_warmup A logical scalar (defaulting to `FALSE`) indicating #' whether to include warmup draws, if applicable. #' log_posterior.stanfit <- function(object, inc_warmup = FALSE, ...) { diff --git a/R/bayesplot-ggplot-themes.R b/R/bayesplot-ggplot-themes.R index 532954db7..7dd5fa448 100644 --- a/R/bayesplot-ggplot-themes.R +++ b/R/bayesplot-ggplot-themes.R @@ -1,19 +1,17 @@ #' Default bayesplot plotting theme #' -#' The \code{\link{theme_default}} function returns the default ggplot -#' \link{theme} used by the \pkg{bayesplot} plotting functions. See -#' \code{\link{bayesplot_theme_set}} for details on setting and updating the -#' plotting theme. +#' The [theme_default()] function returns the default ggplot +#' [theme][ggplot2::theme] used by the **bayesplot** plotting functions. See +#' [bayesplot_theme_set()] for details on setting and updating the plotting theme. #' #' @export #' @param base_size,base_family Base font size and family (passed to -#' \code{\link[ggplot2]{theme_bw}}). It is possible to set -#' \code{"bayesplot.base_size"} and \code{"bayesplot.base_family"} via -#' \code{\link{options}} to change the defaults, which are \code{12} and -#' \code{"serif"}, respectively. -#' @return A ggplot \link[ggplot2]{theme} object. +#' [ggplot2::theme_bw()]). It is possible to set `"bayesplot.base_size"` and +#' `"bayesplot.base_family"` via [options()] to change the defaults, which are +#' `12` and `"serif"`, respectively. +#' @return A ggplot [theme][ggplot2::theme] object. #' -#' @seealso \code{\link{bayesplot_theme_set}} to change the ggplot theme. +#' @seealso [bayesplot_theme_set()] to change the ggplot theme. #' @template seealso-colors #' @template seealso-helpers #' @@ -64,34 +62,32 @@ theme_default <- #' Get, set, and modify the active bayesplot theme #' -#' @description These functions are the \pkg{bayesplot} equivalent to -#' \pkg{ggplot2}'s \code{\link[ggplot2]{theme_set}} and friends. They set, -#' get, and update the active theme but only apply them to \code{bayesplots}. -#' The current/active theme is automatically applied to every \code{bayesplot} -#' you draw. +#' @description These functions are the **bayesplot** equivalent to +#' **ggplot2**'s [ggplot2::theme_set()] and friends. They set, get, and update +#' the active theme but only apply them to `bayesplots`. The current/active +#' theme is automatically applied to every `bayesplot` you draw. #' -#' Use \code{bayesplot_theme_get} to get the current \pkg{bayesplot} theme, -#' and \code{bayesplot_theme_set} to change it. \code{bayesplot_theme_update} -#' and \code{bayesplot_theme_replace} are shorthands for changing individual -#' elements. +#' Use `bayesplot_theme_get()` to get the current **bayesplot** theme, and +#' `bayesplot_theme_set()` to change it. `bayesplot_theme_update()` and +#' `bayesplot_theme_replace()` are shorthands for changing individual elements. #' -#' @details \code{bayesplot_theme_set} and friends only apply to -#' \code{bayesplots}. However, \code{ggplot2::theme_set} can also be used to -#' change the \pkg{bayesplot} theme. Currently, setting a theme with -#' \code{ggplot2::theme_set} (other than the \pkg{ggplot2} default -#' \code{\link[ggplot2]{theme_grey}}) will override the \pkg{bayesplot} theme. +#' @details `bayesplot_theme_set()` and friends only apply to +#' `bayesplots`. However, [ggplot2::theme_set()] can also be used to +#' change the **bayesplot** theme. Currently, setting a theme with +#' `ggplot2::theme_set()` (other than the **ggplot2** default +#' [ggplot2::theme_grey()]) will override the **bayesplot** theme. #' #' @export #' @param new The new theme (list of theme elements) to use. This is analogous -#' to the \code{new} argument to \code{\link[ggplot2]{theme_set}}. +#' to the `new` argument to [ggplot2::theme_set()]. #' @param ... A named list of theme settings. #' -#' @return \code{bayesplot_theme_get} returns the current theme. The other three -#' functions (set, update, replace) invisibly return the \emph{previous} theme +#' @return `bayesplot_theme_get()` returns the current theme. The other three +#' functions (set, update, replace) invisibly return the *previous* theme #' so it can be saved and easily restored later. This is the same behavior as -#' the \pkg{ggplot2} versions of these functions. +#' the **ggplot2** versions of these functions. #' -#' @seealso \code{\link{theme_default}} for the default \pkg{bayesplot} theme. +#' @seealso [theme_default()] for the default **bayesplot** theme. #' @template seealso-helpers #' @template seealso-colors #' diff --git a/R/bayesplot-helpers.R b/R/bayesplot-helpers.R index b535aa739..0f7896d56 100644 --- a/R/bayesplot-helpers.R +++ b/R/bayesplot-helpers.R @@ -1,111 +1,97 @@ #' Convenience functions for adding or changing plot details #' #' Convenience functions for adding to (and changing details of) ggplot objects -#' (many of the objects returned by \pkg{bayesplot} functions). See the -#' \strong{Examples} section, below. +#' (many of the objects returned by **bayesplot** functions). See the +#' **Examples** section, below. #' #' @name bayesplot-helpers #' -#' @param ... For the various \code{vline_}, \code{hline_}, and \code{abline_} -#' functions, \code{...} is passed to \code{\link[ggplot2]{geom_vline}}, -#' \code{\link[ggplot2]{geom_hline}}, and \code{\link[ggplot2]{geom_abline}}, +#' @param ... For the various `vline_`, `hline_`, and `abline_` +#' functions, `...` is passed to [ggplot2::geom_vline()], +#' [ggplot2::geom_hline()], and [ggplot2::geom_abline()], #' respectively, to control the appearance of the line(s). #' -#' For functions ending in \code{_bg}, \code{...} is passed to -#' \code{\link[ggplot2]{element_rect}}. +#' For functions ending in `_bg`, `...` is passed to +#' [ggplot2::element_rect()]. #' -#' For functions ending in \code{_text} or \code{_title}, \code{...} is passed -#' to \code{\link[ggplot2]{element_text}}. +#' For functions ending in `_text` or `_title`, `...` is passed +#' to [ggplot2::element_text()]. #' -#' For \code{xaxis_ticks} and \code{yaxis_ticks}, \code{...} is passed to -#' \code{\link[ggplot2]{element_line}}. +#' For `xaxis_ticks` and `yaxis_ticks`, `...` is passed to +#' [ggplot2::element_line()]. #' -#' For \code{overlay_function}, \code{...} is passed to -#' \code{\link[ggplot2]{stat_function}}. +#' For `overlay_function`, `...` is passed to +#' [ggplot2::stat_function()]. #' #' @return -#' A \pkg{ggplot2} layer or \code{\link[ggplot2]{theme}} object that can be +#' A **ggplot2** layer or [ggplot2::theme()] object that can be #' added to existing ggplot objects, like those created by many of the -#' \pkg{bayesplot} plotting functions. See the \strong{Details} section. +#' **bayesplot** plotting functions. See the **Details** section. #' #' @details #' \subsection{Add vertical, horizontal, and diagonal lines to plots}{ -#' \itemize{ -#' \item \code{vline_at} and \code{hline_at} return an object created by either -#' \code{geom_vline} or \code{geom_hline} that can be added to a ggplot object -#' to draw a vertical or horizontal line (at one or several values). If -#' \code{fun} is missing then the lines are drawn at the values in \code{v}. If -#' \code{fun} is specified then the lines are drawn at the values returned by -#' \code{fun(v)}. -#' -#' \item \code{vline_0} and \code{hline_0} are wrappers for \code{vline_at} and -#' \code{hline_at} with \code{v = 0} and \code{fun} missing. -#' -#' \item \code{abline_01} is a wrapper for \code{geom_abline} with the intercept -#' set to 0 and the slope set to 1. -#' -#' \item \code{lbub} returns a \emph{function} that takes a single argument -#' \code{x} and returns the lower and upper bounds (\code{lb}, \code{ub}) of the -#' \code{100*p}\% central interval of \code{x}, as well as the median (if -#' \code{med} is \code{TRUE}). -#' } +#' * `vline_at()` and `hline_at()` return an object created by either +#' [ggplot2::geom_vline()] or [ggplot::geom_hline()] that can be added to a +#' ggplot object to draw a vertical or horizontal line (at one or several +#' values). If `fun` is missing then the lines are drawn at the values in `v`. +#' If `fun` is specified then the lines are drawn at the values returned by `fun(v)`. +#' +#' * `vline_0()` and `hline_0()` are wrappers for `vline_at()` and `hline_at()` +#' with `v = 0` and `fun` missing. +#' +#' * `abline_01()` is a wrapper for [ggplot2::geom_abline()] with the intercept +#' set to `0` and the slope set to `1`. +#' +#' * `lbub()` returns a _function_ that takes a single argument `x` and returns +#' the lower and upper bounds (`lb`, `ub`) of the `100*p`\% central interval +#' of `x`, as well as the median (if `med=TRUE`). #' } #' \subsection{Control appearance of facet strips}{ -#' \itemize{ -#' \item \code{facet_text} and \code{facet_bg} return ggplot2 theme objects that -#' can be added to an existing plot (ggplot object) to format the text and the -#' background for the facet strips. -#' } +#' * `facet_text()` and `facet_bg()` return ggplot2 theme objects that +#' can be added to an existing plot (ggplot object) to format the text and the +#' background for the facet strips. #' } #' \subsection{Move legend, remove legend, or style the legend text}{ -#' \itemize{ -#' \item \code{legend_move} and \code{legend_none} return a ggplot2 theme object -#' that can be added to an existing plot (ggplot object) in order to change the -#' position of the legend (\code{legend_move}) or remove the legend -#' (\code{legend_none}). \code{legend_text} works much like \code{facet_text}, -#' except it controls the legend text. -#' } +#' * `legend_move()` and `legend_none()` return a ggplot2 theme object +#' that can be added to an existing plot (ggplot object) in order to change the +#' position of the legend (`legend_move()`) or remove the legend +#' (`legend_none()`). `legend_text()` works much like `facet_text()`, +#' except it controls the legend text. #' } #' \subsection{Control appearance of \eqn{x}-axis and \eqn{y}-axis features}{ -#' \itemize{ -#' \item \code{xaxis_title} and \code{yaxis_title} return a ggplot2 theme object -#' that can be added to an existing plot (ggplot object) in order to toggle or -#' format the titles displayed on the \code{x} or \code{y} axis. (To change -#' the titles themselves use \code{\link[ggplot2]{labs}}.) -#' -#' \item \code{xaxis_text} and \code{yaxis_text} return a ggplot2 theme object -#' that can be added to an existing plot (ggplot object) in order to toggle or -#' format the text displayed on the \code{x} or \code{y} axis (e.g. tick -#' labels). -#' -#' \item \code{xaxis_ticks} and \code{yaxis_ticks} return a ggplot2 theme object -#' that can be added to an existing plot (ggplot object) to change the -#' appearance of the axis tick marks. -#' } +#' * `xaxis_title()` and `yaxis_title()` return a ggplot2 theme object +#' that can be added to an existing plot (ggplot object) in order to toggle or +#' format the titles displayed on the `x` or `y` axis. (To change +#' the titles themselves use [ggplot2::labs()].) +#' +#' * `xaxis_text()` and `yaxis_text()` return a ggplot2 theme object +#' that can be added to an existing plot (ggplot object) in order to toggle or +#' format the text displayed on the `x` or `y` axis (e.g. tick +#' labels). +#' +#' * `xaxis_ticks()` and `yaxis_ticks()` return a ggplot2 theme object +#' that can be added to an existing plot (ggplot object) to change the +#' appearance of the axis tick marks. #' } #' \subsection{Customize plot background}{ -#' \itemize{ -#' \item \code{plot_bg} returns a ggplot2 theme object that can be added to an -#' existing plot (ggplot object) to format the background of the \emph{entire} plot. -#' \item \code{panel_bg} returns a ggplot2 theme object that can be added to an +#' * `plot_bg()` returns a ggplot2 theme object that can be added to an +#' existing plot (ggplot object) to format the background of the *entire* plot. +#' * `panel_bg()` returns a ggplot2 theme object that can be added to an #' existing plot (ggplot object) to format the background of the just the #' plotting area. -#' \item \code{grid_lines} returns a ggplot2 theme object that can be added to +#' * `grid_lines()` returns a ggplot2 theme object that can be added to #' an existing plot (ggplot object) to add grid lines to the plot background. #' } -#' } #' \subsection{Superimpose a function on an existing plot}{ -#' \itemize{ -#' \item \code{overlay_function} is a simple wrapper for -#' \code{\link[ggplot2]{stat_function}} but with the \code{inherit.aes} argument -#' fixed to \code{FALSE}. Fixing \code{inherit.aes=FALSE} will avoid potential -#' errors due to the \code{\link[ggplot2]{aes}}thetic mapping used by certain -#' \pkg{bayesplot} plotting functions). -#' } +#' * `overlay_function()` is a simple wrapper for +#' [ggplot2::stat_function()] but with the `inherit.aes` argument +#' fixed to `FALSE`. Fixing `inherit.aes=FALSE` will avoid potential +#' errors due to the [ggplot2::aes()]thetic mapping used by certain +#' **bayesplot** plotting functions. #' } #' -#' @seealso \code{\link{theme_default}} for the default ggplot theme used by -#' \pkg{bayesplot}. +#' @seealso [theme_default()] for the default ggplot theme used by +#' **bayesplot**. #' #' @examples #' color_scheme_set("gray") @@ -247,11 +233,11 @@ NULL #' @export #' @param v Either a numeric vector specifying the value(s) at which to #' draw the vertical or horizontal line(s), or an object of any type to use as -#' the first argument to \code{fun}. +#' the first argument to `fun`. #' @param fun A function, or the name of a function, that returns a numeric #' vector. #' @param na.rm A logical scalar passed to the appropriate geom (e.g. -#' \code{\link[ggplot2]{geom_vline}}). The default is \code{TRUE}. +#' [ggplot2::geom_vline()]). The default is `TRUE`. #' vline_at <- function(v, fun, ..., na.rm = TRUE) { geom_vline(xintercept = calc_v(v, fun), @@ -298,7 +284,7 @@ abline_01 <- function(..., na.rm = TRUE) { # intervals --------------------------------------------------------------- #' @rdname bayesplot-helpers #' @export -#' @param p The probability mass (in [0,1]) to include in the interval. +#' @param p The probability mass (in `[0,1]``) to include in the interval. #' @param med Should the median also be included in addition to the lower #' and upper bounds of the interval? #' @@ -331,9 +317,9 @@ calc_intervals <- function(x, p, med = TRUE, ...) { #' @export #' @param position The position of the legend. Either a numeric vector (of #' length 2) giving the relative coordinates (between 0 and 1) for the legend, -#' or a string among \code{"right"}, \code{"left"}, \code{"top"}, -#' \code{"bottom"}. Using \code{position = "none"} is also allowed and is -#' equivalent to using \code{legend_none()}. +#' or a string among `"right"`, `"left"`, `"top"`, +#' `"bottom"`. Using `position = "none"` is also allowed and is +#' equivalent to using `legend_none()`. #' legend_move <- function(position = "right") { theme(legend.position = position) @@ -402,12 +388,11 @@ yaxis_ticks <- function(on = TRUE, ...) { # facet stuff ------------------------------------------------------------- #' @rdname bayesplot-helpers #' @export -#' @param on For functions modifying ggplot \link[ggplot2]{theme} elements, set -#' \code{on=FALSE} to set the element to \code{\link[ggplot2]{element_blank}}. -#' For example, facet text can be removed by adding -#' \code{facet_text(on=FALSE)}, or simply \code{facet_text(FALSE)} to a ggplot -#' object. If \code{on=TRUE} (the default), then \code{...} can be used to -#' customize the appearance of the theme element. +#' @param on For functions modifying ggplot [theme][ggplot2::theme] elements, +#' set `on=FALSE` to set the element to [ggplot2::element_blank()]. For +#' example, facet text can be removed by adding `facet_text(on=FALSE)`, or +#' simply `facet_text(FALSE)` to a ggplot object. If `on=TRUE` (the default), +#' then `...` can be used to customize the appearance of the theme element. #' facet_text <- function(on = TRUE, ...) { theme(strip.text = if (on) @@ -445,7 +430,7 @@ plot_bg <- function(on = TRUE, ...) { #' @rdname bayesplot-helpers #' @export -#' @param color,size Passed to \code{\link[ggplot2]{element_line}}. +#' @param color,size Passed to [ggplot2::element_line()]. #' grid_lines <- function(color = "gray50", size = 0.2) { theme( diff --git a/R/bayesplot-package.R b/R/bayesplot-package.R index d3f905dfc..e500fb192 100644 --- a/R/bayesplot-package.R +++ b/R/bayesplot-package.R @@ -10,19 +10,19 @@ #' @description #' \if{html}{ #' \figure{stanlogo.png}{options: width="50px" alt="mc-stan.org"} -#' \emph{Stan Development Team} #' } +#' *Stan Development Team* #' -#' The \pkg{bayesplot} package provides a variety of \pkg{ggplot2}-based +#' The **bayesplot** package provides a variety of **ggplot2**-based #' plotting functions for use after fitting Bayesian models (typically, though #' not exclusively, via Markov chain Monte Carlo). The package is designed not #' only to provide convenient functionality for users, but also a common set of #' functions that can be easily used by developers working on a variety of #' packages for Bayesian modeling, particularly (but not necessarily) packages -#' powered by \pkg{\link[rstan]{rstan}}. Examples of packages that will soon (or -#' already are) using \pkg{bayesplot} are \pkg{rstan} itself, as well as the -#' \pkg{rstan}-dependent \pkg{rstanarm} and \pkg{brms} packages for applied -#' regression modeling. +#' powered by [rstan][rstan::rstan-package]. Examples of packages that will soon +#' (or already are) using **bayesplot** are **rstan** itself, as well as the +#' **rstan**-dependent **rstanarm** and **brms** packages for applied regression +#' modeling. #' #' @section Plotting functionality: #' \if{html}{ @@ -31,37 +31,29 @@ #' \figure{bayesplot3.png}{options: width="30\%" alt="ppc_dens_overlay"} #' } #' -#' The plotting functions in \pkg{bayesplot} are organized into several modules: -#' \itemize{ -#' \item \strong{\link[=MCMC-overview]{MCMC}}: Visualizations of Markov chain -#' Monte Carlo (MCMC) simulations generated by \emph{any} MCMC algorithm +#' The plotting functions in **bayesplot** are organized into several modules: +#' * [__MCMC__][MCMC-overview]: Visualizations of Markov chain +#' Monte Carlo (MCMC) simulations generated by *any* MCMC algorithm #' as well as diagnostics. There are also additional functions specifically -#' for use with models fit using the \link[=NUTS]{No-U-Turn Sampler (NUTS)}. -#' \item \strong{\link[=PPC-overview]{PPC}}: Graphical posterior predictive checks (PPCs). -#' } +#' for use with models fit using the [No-U-Turn Sampler (NUTS)][NUTS]. +#' * [__PPC__][PPC-overview]: Graphical posterior predictive checks (PPCs). +#' #' In future releases modules will be added specifically for #' forecasting/out-of-sample prediction and other inference-related tasks. #' #' @section Resources: -#' \itemize{ -#' \item{\strong{Bug reports and feature requests}:}{ -#' If you would like to request a new feature or if you have noticed a bug that -#' needs to be fixed please let us know at the \pkg{bayesplot} issue tracker on -#' GitHub: -#' -#' \url{https://github.com/stan-dev/bayesplot/issues/}. -#' } -#' \item{\strong{General questions and help}:}{ -#' To ask a question about \pkg{bayesplot} on the Stan Forums -#' forum please visit: -#' -#' \url{https://discourse.mc-stan.org}. -#' } +#' * __Bug reports and feature requests__: If you would like to request a new +#' feature or if you have noticed a bug that needs to be fixed please let us +#' know at the **bayesplot** issue tracker at +#' +#' * __General questions and help__: +#' To ask a question about **bayesplot** on the Stan Forums forum please visit +#' . #' } #' #' @template seealso-theme #' @template seealso-colors -#' @seealso \code{\link[ggplot2]{ggsave}} in \pkg{ggplot2} for saving plots. +#' @seealso [ggplot2::ggsave()] for saving plots. #' #' @template reference-vis-paper #' diff --git a/R/bayesplot_grid.R b/R/bayesplot_grid.R index cd22a0581..161ad870d 100644 --- a/R/bayesplot_grid.R +++ b/R/bayesplot_grid.R @@ -1,30 +1,30 @@ #' Arrange plots in a grid #' -#' The \code{bayesplot_grid} function makes it simple to juxtapose plots using +#' The `bayesplot_grid` function makes it simple to juxtapose plots using #' common \eqn{x} and/or \eqn{y} axes. #' #' @export #' @param ... One or more ggplot objects. #' @param plots A list of ggplot objects. Can be used as an alternative to -#' specifying plot objects via \code{...}. +#' specifying plot objects via `...`. #' @param grid_args An optional named list of arguments to pass to -#' \code{\link[gridExtra]{arrangeGrob}} (\code{nrow}, \code{ncol}, -#' \code{widths}, etc.). +#' [gridExtra::arrangeGrob()] (`nrow`, `ncol`, +#' `widths`, etc.). #' @param titles,subtitles Optional character vectors of plot titles and -#' subtitles. If specified, \code{titles} and \code{subtitles} must must have +#' subtitles. If specified, `titles` and `subtitles` must must have #' length equal to the number of plots specified. #' @param xlim,ylim Optionally, numeric vectors of length 2 specifying lower and #' upper limits for the axes that will be shared across all plots. #' @param legends If any of the plots have legends should they be displayed? -#' Defaults to \code{TRUE}. -#' @param save_gg_objects If \code{TRUE}, the default, then the ggplot objects -#' specified in \code{...} or via the \code{plots} argument are saved in a -#' list in the \code{"bayesplots"} component of the returned object. -#' Setting this to \code{FALSE} will make the returned object smaller but +#' Defaults to `TRUE`. +#' @param save_gg_objects If `TRUE`, the default, then the ggplot objects +#' specified in `...` or via the `plots` argument are saved in a +#' list in the `"bayesplots"` component of the returned object. +#' Setting this to `FALSE` will make the returned object smaller but #' these individual plot objects will not be available. #' #' @return An object of class "bayesplot_grid" (essentially a gtable object from -#' \code{\link[gridExtra]{arrangeGrob}}), which has a \code{plot} method. +#' [gridExtra::arrangeGrob()]), which has a `plot` method. #' #' @examples #' y <- example_y_data() diff --git a/R/example-data.R b/R/example-data.R index 4ba53be51..0187ab212 100644 --- a/R/example-data.R +++ b/R/example-data.R @@ -6,43 +6,43 @@ #' @name example-data #' @keywords internal #' -#' @return See \strong{Details}. +#' @return See **Details**. #' #' @details #' Each of these functions returns an object containing data, parameter draws, or #' predictions corresponding to a basic linear regression model with data -#' \code{y} (outcome vector) and \code{X} (predictor matrix), and parameters -#' \code{alpha} (intercept), \code{beta} (coefficient vector), and \code{sigma} +#' `y` (outcome vector) and `X` (predictor matrix), and parameters +#' `alpha` (intercept), `beta` (coefficient vector), and `sigma` #' (error sd). #' #' \describe{ -#' \item{\code{example_mcmc_draws}}{ -#' If \code{chains > 1}, a \code{250} (iterations) by \code{chains} by -#' \code{params} array or, if \code{chains = 1}, a \code{250} by \code{params} +#' \item{`example_mcmc_draws()`}{ +#' If `chains > 1`, a `250` (iterations) by `chains` by +#' `params` array or, if `chains = 1`, a `250` by `params` #' matrix of MCMC draws from the posterior distribution of the parameters in -#' the linear regression model described above. If \code{params = 1} then only -#' the draws for \code{alpha} are included in the returned object. If -#' \code{params >= 2} then draws for \code{sigma} are also included. And if -#' \code{params} is between \code{3} and the maximum of \code{6} then draws -#' for regression coefficients \code{beta[k]} (\code{k} in \code{1:(params-2)}) +#' the linear regression model described above. If `params = 1` then only +#' the draws for `alpha` are included in the returned object. If +#' `params >= 2` then draws for `sigma` are also included. And if +#' `params` is between `3` and the maximum of `6` then draws +#' for regression coefficients `beta[k]` (`k` in `1:(params-2)`) #' are also included. #' } -#' \item{\code{example_y_data}}{ -#' A numeric vector with \code{434} observations of the outcome variable in the +#' \item{`example_y_data()`}{ +#' A numeric vector with `434` observations of the outcome variable in the #' linear regression model. #' } -#' \item{\code{example_x_data}}{ -#' A numeric vector with \code{434} observations of one of the predictor +#' \item{`example_x_data()`}{ +#' A numeric vector with `434` observations of one of the predictor #' variables in the linear regression model. #' } -#' \item{\code{example_group_data}}{ -#' A factor variable with \code{434} observations of a grouping variable with +#' \item{`example_group_data()`}{ +#' A factor variable with `434` observations of a grouping variable with #' two levels. #' } -#' \item{\code{example_yrep_draws}}{ -#' A \code{500} (draws) by \code{434} (data points) matrix of draws from the +#' \item{`example_yrep_draws()`}{ +#' A `500` (draws) by `434` (data points) matrix of draws from the #' posterior predictive distribution. Each row represents a full dataset drawn -#' from the posterior predictive distribution of the outcome \code{y} after +#' from the posterior predictive distribution of the outcome `y` after #' fitting the linear regression model mentioned above. #' } #' } diff --git a/R/helpers-gg.R b/R/helpers-gg.R index 84711280f..7254b880a 100644 --- a/R/helpers-gg.R +++ b/R/helpers-gg.R @@ -25,7 +25,7 @@ geom_ignore <- function(...) { #' #' The "area ridges" are for use in `mcmc_areas()`. The scale of 1 and the #' identity statistic prevent the ridges from overlapping. -#' `geom_density_ridges2` draws closed polygons. +#' `geom_density_ridges2()` draws closed polygons. #' #' @importFrom ggridges geom_density_ridges geom_density_ridges2 #' @noRd diff --git a/R/helpers-ppc.R b/R/helpers-ppc.R index dd19c53e0..063dba97e 100644 --- a/R/helpers-ppc.R +++ b/R/helpers-ppc.R @@ -10,10 +10,10 @@ is_vector_or_1Darray <- function(x) { #' Validate y #' -#' Checks that y is numeric, doesn't have any NAs, and is either a vector, 1-D -#' array, or univariate time series object of class \code{ts}. +#' Checks that `y` is numeric, doesn't have any NAs, and is either a vector, 1-D +#' array, or univariate time series object of class `ts`. #' -#' @param y The y object from the user. +#' @param y The `y` object from the user. #' @return Either throws an error or returns a numeric vector. #' @noRd validate_y <- function(y) { @@ -36,10 +36,10 @@ validate_y <- function(y) { #' Validate yrep #' -#' Checks that yrep is a numeric matrix, doesn't have any NAs, and has the -#' correct number of columns (equal to the length of y). +#' Checks that `yrep` is a numeric matrix, doesn't have any NAs, and has the +#' correct number of columns (equal to the length of `y`). #' -#' @param yrep,y The user's yrep object and the y object returned by validate_y. +#' @param yrep,y The user's `yrep` object and the `y` object returned by `validate_y()`. #' @return Either throws an error or returns a numeric matrix. #' @noRd validate_yrep <- function(yrep, y) { @@ -67,11 +67,11 @@ validate_yrep <- function(yrep, y) { #' Validate group #' -#' Checks that grouping variable has same length as y and is either a vector or +#' Checks that grouping variable has same length as `y` and is either a vector or #' factor variable. #' -#' @param group,y The user's group object and the y object returned by validate_y. -#' @return Either throws an error or returns \code{group} (coerced to a factor). +#' @param group,y The user's `group` object and the `y` object returned by `validate_y()`. +#' @return Either throws an error or returns `group` (coerced to a factor). #' @noRd validate_group <- function(group, y) { stopifnot(is.vector(group) || is.factor(group)) @@ -101,8 +101,9 @@ validate_group <- function(group, y) { #' Checks that x is a numeric vector, doesn't have any NAs, and has the #' same length as y. #' -#' @param x,y The user's x vector and the y object returned by validate_y. -#' @param unique_x T/F indicating whether to require all unique values in x. +#' @param x,y The user's `x` vector and the `y` object returned by `validate_y()`. +#' @param unique_x `TRUE` or `FALSE` indicating whether to require all unique +#' values in `x`. #' @return Either throws an error or returns a numeric vector. #' @noRd validate_x <- function(x = NULL, y, unique_x = FALSE) { @@ -147,7 +148,6 @@ validate_x <- function(x = NULL, y, unique_x = FALSE) { #' number of simulations included in `yrep`. #' 1. `value`: the simulation values. #' @noRd -#' @md melt_yrep <- function(yrep) { out <- yrep %>% reshape2::melt(varnames = c("rep_id", "y_id")) %>% @@ -169,7 +169,6 @@ melt_yrep <- function(yrep) { #' 1. `is_y_label`: factor with levels `italic(y)` for observations and #' `italic(y)[rep]` for simulations. #' @noRd -#' @md melt_and_stack <- function(y, yrep) { y_text <- as.character(y_label()) yrep_text <- as.character(yrep_label()) @@ -198,12 +197,13 @@ melt_and_stack <- function(y, yrep) { #' Prepare data for use in PPCs by group #' -#' @param y,yrep,group Validated y, yrep, and group objects. -#' @param stat Either NULL or a string naming a function. -#' @return If \code{stat} is NULL, a molten data frame grouped by group and -#' variable. If \code{stat} specifies a function then a summary table created -#' by dplyr::summarise. +#' @param y,yrep,group Validated `y`, `yrep`, and `group` objects. +#' @param stat Either `NULL` or a string naming a function. +#' @return If `stat` is `NULL`, a molten data frame grouped by group and +#' variable. If `stat` specifies a function then a summary table created +#' by `dplyr::summarise()`. #' @noRd +#' #' @examples #' y <- example_y_data() #' yrep <- example_yrep_draws() diff --git a/R/helpers-shared.R b/R/helpers-shared.R index 1d676fc35..9bcd425bc 100644 --- a/R/helpers-shared.R +++ b/R/helpers-shared.R @@ -1,9 +1,9 @@ -#' Check for suggested package (requireNamespace) and throw error if necessary +#' Check for suggested package with `requireNamespace` and throw error if necessary #' #' @noRd #' @param pkg Package name as a string. #' @param min_version Optionally, a minimum version number as a string. -#' @return TRUE, invisibly, if no error is thrown. +#' @return `TRUE`, invisibly, if no error is thrown. #' suggested_package <- function(pkg, min_version = NULL) { stopifnot(length(pkg) == 1, is.character(pkg)) diff --git a/R/helpers-testthat.R b/R/helpers-testthat.R index 2d6890330..08914b6d2 100644 --- a/R/helpers-testthat.R +++ b/R/helpers-testthat.R @@ -7,10 +7,11 @@ expect_mcmc_array <- function(x) testthat::expect_true(is_mcmc_array(x)) expect_bayesplot_grid <- function(x) testthat::expect_true(is_bayesplot_grid(x)) -# Insert fake divergences for testing purposes -# -# @param np Data frame returned by nuts_params -# @return 'np' with every other iter marked as a divergence +#' Insert fake divergences for testing purposes +#' +#' @noRd +#' @param np Data frame returned by `nuts_params()` +#' @return `np` with every other iter marked as a divergence ensure_divergences <- function(np) { divs <- rep_len(c(0,1), length.out = sum(np$Parameter=="divergent__")) np$Value[np$Parameter=="divergent__"] <- divs diff --git a/R/mcmc-combo.R b/R/mcmc-combo.R index 96b8c7762..dc8901388 100644 --- a/R/mcmc-combo.R +++ b/R/mcmc-combo.R @@ -4,28 +4,28 @@ #' @family MCMC #' #' @template args-mcmc-x -#' @param ... Arguments passed to the plotting functions named in \code{combo}. +#' @param ... Arguments passed to the plotting functions named in `combo`. #' @param combo A character vector with at least two elements. Each element of -#' \code{combo} corresponds to a column in the resulting graphic and should be -#' the name of one of the available \link{MCMC} functions (omitting the -#' \code{mcmc_} prefix). -#' @param widths A numeric vector the same length as \code{combo} specifying +#' `combo` corresponds to a column in the resulting graphic and should be the +#' name of one of the available [MCMC][MCMC-overview] functions (omitting the +#' `mcmc_` prefix). +#' @param widths A numeric vector the same length as `combo` specifying #' relative column widths. For example, if the plot has two columns, then -#' \code{widths = c(2, 1)} will allocate more space for the first column by a -#' factor of 2 (as would \code{widths = c(.3, .15)}, etc.). The default, -#' \code{NULL}, allocates the same horizontal space for each column. -#' @param gg_theme Unlike most of the other \pkg{bayesplot} functions, -#' \code{mcmc_combo} returns a gtable object rather than a ggplot object, and +#' `widths = c(2, 1)` will allocate more space for the first column by a +#' factor of 2 (as would `widths = c(.3, .15)`, etc.). The default, +#' `NULL`, allocates the same horizontal space for each column. +#' @param gg_theme Unlike most of the other **bayesplot**functions, +#' `mcmc_combo` returns a gtable object rather than a ggplot object, and #' so theme objects can't be added directly to the returned plot object. The -#' \code{gg_theme} argument helps get around this problem by accepting a -#' \pkg{ggplot2} \link[ggplot2]{theme} object that is added to each of the -#' plots \emph{before} combining them into the gtable object that is returned. -#' This can be a theme object created by a call to \code{ggplot2::theme} or -#' one of the \pkg{bayesplot} convenience functions, e.g. -#' \code{\link{legend_none}} (see the \strong{Examples} section, below). +#' `gg_theme` argument helps get around this problem by accepting a +#' **ggplot2** [theme][ggplot2::theme] object that is added to each of the +#' plots *before* combining them into the gtable object that is returned. +#' This can be a theme object created by a call to [ggplot2::theme()] or +#' one of the **bayesplot**convenience functions, e.g. +#' [legend_none()] (see the **Examples** section, below). #' #' @return A gtable object (the result of calling -#' \code{\link[gridExtra]{arrangeGrob}}) with \code{length(combo)} columns and +#' [gridExtra::arrangeGrob()]) with `length(combo)` columns and #' a row for each parameter. #' #' @examples diff --git a/R/mcmc-diagnostics-nuts.R b/R/mcmc-diagnostics-nuts.R index 694a3ac5b..df7ce9a25 100644 --- a/R/mcmc-diagnostics-nuts.R +++ b/R/mcmc-diagnostics-nuts.R @@ -1,89 +1,75 @@ #' Diagnostic plots for the No-U-Turn-Sampler (NUTS) #' #' Diagnostic plots for the No-U-Turn-Sampler (NUTS), the default MCMC algorithm -#' used by Stan. See the \strong{Plot Descriptions} section, below. +#' used by [Stan](https://mc-stan.org). See the **Plot Descriptions** section, below. #' #' @name MCMC-nuts #' @aliases NUTS #' @family MCMC #' #' @param x A molten data frame of NUTS sampler parameters, either created by -#' \code{\link{nuts_params}} or in the same form as the object returned by -#' \code{\link{nuts_params}}. +#' [nuts_params()] or in the same form as the object returned by +#' [nuts_params()]. #' @param lp A molten data frame of draws of the log-posterior or, more #' commonly, of a quantity equal to the log-posterior up to a constant. -#' \code{lp} should either be created via \code{\link{log_posterior}} or be an +#' `lp` should either be created via [log_posterior()] or be an #' object with the same form as the object returned by -#' \code{\link{log_posterior}}. +#' [log_posterior()]. #' @param chain A positive integer for selecting a particular chain. The default -#' (\code{NULL}) is to merge the chains before plotting. If \code{chain = k} -#' then the plot for chain \code{k} is overlaid (in a darker shade but with -#' transparency) on top of the plot for all chains. The \code{chain} argument -#' is not used by \code{mcmc_nuts_energy}. +#' (`NULL`) is to merge the chains before plotting. If `chain = k` +#' then the plot for chain `k` is overlaid (in a darker shade but with +#' transparency) on top of the plot for all chains. The `chain` argument +#' is not used by `mcmc_nuts_energy()`. #' @param ... Currently ignored. #' #' @return A gtable object (the result of calling -#' \code{\link[gridExtra]{arrangeGrob}}) created from several ggplot objects, -#' except for \code{mcmc_nuts_energy}, which returns a ggplot object. +#' [gridExtra::arrangeGrob()]) created from several ggplot objects, +#' except for `mcmc_nuts_energy()`, which returns a ggplot object. #' #' @section Quick Definitions: #' For more details see Stan Development Team (2016) and Betancourt (2017). -#' \itemize{ -#' \item \code{accept_stat__}: the average acceptance probabilities of all +#' * `accept_stat__`: the average acceptance probabilities of all #' possible samples in the proposed tree. -#' \item \code{divergent__}: the number of leapfrog transitions with diverging +#' * `divergent__`: the number of leapfrog transitions with diverging #' error. Because NUTS terminates at the first divergence this will be either #' 0 or 1 for each iteration. -#' \item \code{stepsize__}: the step size used by NUTS in its Hamiltonian +#' * `stepsize__`: the step size used by NUTS in its Hamiltonian #' simulation. -#' \item \code{treedepth__}: the depth of tree used by NUTS, which is the log +#' * `treedepth__`: the depth of tree used by NUTS, which is the log #' (base 2) of the number of leapfrog steps taken during the Hamiltonian #' simulation. -#' \item \code{energy__}: the value of the Hamiltonian (up to an additive +#' * `energy__`: the value of the Hamiltonian (up to an additive #' constant) at each iteration. -#' } #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{mcmc_nuts_acceptance}}{ +#' \item{`mcmc_nuts_acceptance()`}{ #' Three plots: -#' \itemize{ -#' \item Histogram of \code{accept_stat__} with vertical lines indicating the -#' mean (solid line) and median (dashed line). -#' \item Histogram of \code{lp__} with vertical -#' lines indicating the mean (solid line) and median (dashed line). -#' \item Scatterplot of \code{accept_stat__} vs \code{lp__}. -#' } +#' * Histogram of `accept_stat__` with vertical lines indicating the +#' mean (solid line) and median (dashed line). +#' * Histogram of `lp__` with vertical +#' lines indicating the mean (solid line) and median (dashed line). +#' * Scatterplot of `accept_stat__` vs `lp__`. #' } -#' \item{\code{mcmc_nuts_divergence}}{ +#' \item{`mcmc_nuts_divergence()`}{ #' Two plots: -#' \itemize{ -#' \item Violin plots of \code{lp__|divergent__=1} and -#' \code{lp__|divergent__=0}. -#' \item Violin plots of \code{accept_stat__|divergent__=1} and -#' \code{accept_stat__|divergent__=0}. -#' } +#' * Violin plots of `lp__|divergent__=1` and `lp__|divergent__=0`. +#' * Violin plots of `accept_stat__|divergent__=1` and `accept_stat__|divergent__=0`. #' } -#' \item{\code{mcmc_nuts_stepsize}}{ +#' \item{`mcmc_nuts_stepsize()`}{ #' Two plots: -#' \itemize{ -#' \item Violin plots of \code{lp__} by chain ordered by -#' \code{stepsize__} value. -#' \item Violin plots of \code{accept_stat__} by chain ordered by -#' \code{stepsize__} value. -#' } +#' * Violin plots of `lp__` by chain ordered by `stepsize__` value. +#' * Violin plots of `accept_stat__` by chain ordered by `stepsize__` value. #' } -#' \item{\code{mcmc_nuts_treedepth}}{ +#' \item{`mcmc_nuts_treedepth()`}{ #' Three plots: -#' \itemize{ -#' \item Violin plots of \code{lp__} by value of \code{treedepth__}. -#' \item Violin plots of \code{accept_stat__} by value of \code{treedepth__}. -#' \item Histogram of \code{treedepth__}. -#' } +#' * Violin plots of `lp__` by value of `treedepth__`. +#' * Violin plots of `accept_stat__` by value of `treedepth__`. +#' * Histogram of `treedepth__`. #' } -#' \item{\code{mcmc_nuts_energy}}{ -#' Overlaid histograms showing \code{energy__} vs the change in -#' \code{energy__}. See Betancourt (2016) for details. +#' \item{`mcmc_nuts_energy()`}{ +#' Overlaid histograms showing `energy__` vs the change in +#' `energy__`. See Betancourt (2016) for details. #' } #' } #' @@ -92,22 +78,18 @@ #' @template reference-stan-manual #' #' @seealso -#' \itemize{ -#' \item The \emph{Visual MCMC Diagnostics} vignette. -#' \item Several other plotting functions in the \pkg{bayesplot} package -#' are not NUTS-specific but take optional extra arguments if the model was fit -#' using NUTS: -#' \itemize{ -#' \item \code{\link{mcmc_trace}}: show divergences as tick marks below the -#' trace plot. -#' \item \code{\link{mcmc_parcoord}}: change the color/size/transparency of -#' lines correspondending to divergences. -#' \item \code{\link{mcmc_scatter}}: change the color/size/shape of points -#' corresponding to divergences. -#' \item \code{\link{mcmc_pairs}}: change the color/size/shape of points -#' corresponding divergences and/or max treedepth saturation. -#' } -#' } +#' * The [Visual MCMC Diagnostics](https://mc-stan.org/bayesplot/articles/visual-mcmc-diagnostics.html) +#' vignette. +#' * Several other plotting functions are not NUTS-specific but take optional +#' extra arguments if the model was fit using NUTS: +#' * [mcmc_trace()]: show divergences as tick marks below the +#' trace plot. +#' * [mcmc_parcoord()]: change the color/size/transparency of lines +#' correspondending to divergences. +#' * [mcmc_scatter()]: change the color/size/shape of points +#' corresponding to divergences. +#' * [mcmc_pairs()]: change the color/size/shape of points +#' corresponding divergences and/or max treedepth saturation. #' #' @examples #' \dontrun{ @@ -139,8 +121,8 @@ NULL #' @rdname MCMC-nuts #' @export -#' @param binwidth An optional value passed to -#' \code{\link[ggplot2]{geom_histogram}} to override the default binwidth. +#' @param binwidth An optional value passed to [ggplot2::geom_histogram()] to +#' override the default binwidth. #' mcmc_nuts_acceptance <- function(x, @@ -433,10 +415,10 @@ mcmc_nuts_treedepth <- function(x, lp, chain = NULL, ...) { #' @rdname MCMC-nuts #' @export -#' @param alpha For \code{mcmc_nuts_energy} only, the transparency (alpha) level -#' in [0,1] used for the overlaid histogram. -#' @param merge_chains For \code{mcmc_nuts_energy} only, should all chains be -#' merged or displayed separately? The default is \code{FALSE}, i.e., to show +#' @param alpha For `mcmc_nuts_energy()` only, the transparency (alpha) level +#' in `[0,1]` used for the overlaid histogram. +#' @param merge_chains For `mcmc_nuts_energy()` only, should all chains be +#' merged or displayed separately? The default is `FALSE`, i.e., to show #' the chains separately. #' mcmc_nuts_energy <- diff --git a/R/mcmc-diagnostics.R b/R/mcmc-diagnostics.R index 8f4c8d945..d2ffac1e7 100644 --- a/R/mcmc-diagnostics.R +++ b/R/mcmc-diagnostics.R @@ -1,64 +1,60 @@ #' General MCMC diagnostics #' #' Plots of Rhat statistics, ratios of effective sample size to total sample -#' size, and autocorrelation of MCMC draws. See the \strong{Plot Descriptions} +#' size, and autocorrelation of MCMC draws. See the **Plot Descriptions** #' section, below, for details. For models fit using the No-U-Turn-Sampler, see -#' also \link{MCMC-nuts} for additional MCMC diagnostic plots. +#' also [MCMC-nuts] for additional MCMC diagnostic plots. #' #' @name MCMC-diagnostics #' @family MCMC #' #' @template args-hist -#' @param size An optional value to override \code{\link[ggplot2]{geom_point}}'s -#' default size (for \code{mcmc_rhat}, \code{mcmc_neff}) or -#' \code{\link[ggplot2]{geom_line}}'s default size (for \code{mcmc_acf}). +#' @param size An optional value to override [ggplot2::geom_point()]'s +#' default size (for `mcmc_rhat()`, `mcmc_neff()`) or +#' [ggplot2::geom_line()]'s default size (for `mcmc_acf()`). #' @param ... Currently ignored. #' #' @template return-ggplot-or-data #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{mcmc_rhat, mcmc_rhat_hist}}{ +#' \item{`mcmc_rhat()`, `mcmc_rhat_hist()`}{ #' Rhat values as either points or a histogram. Values are colored using #' different shades (lighter is better). The chosen thresholds are somewhat #' arbitrary, but can be useful guidelines in practice. -#' \itemize{ -#' \item \emph{light}: below 1.05 (good) -#' \item \emph{mid}: between 1.05 and 1.1 (ok) -#' \item \emph{dark}: above 1.1 (too high) -#' } +#' * _light_: below 1.05 (good) +#' * _mid_: between 1.05 and 1.1 (ok) +#' * _dark_: above 1.1 (too high) #' } -#' \item{\code{mcmc_neff, mcmc_neff_hist}}{ +#' \item{`mcmc_neff()`, `mcmc_neff_hist()`}{ #' Ratios of effective sample size to total sample size as either points or a #' histogram. Values are colored using different shades (lighter is better). The #' chosen thresholds are somewhat arbitrary, but can be useful guidelines in #' practice. -#' \itemize{ -#' \item \emph{light}: between 0.5 and 1 (high) -#' \item \emph{mid}: between 0.1 and 0.5 (good) -#' \item \emph{dark}: below 0.1 (low) +#' * _light_: between 0.5 and 1 (high) +#' * _mid_: between 0.1 and 0.5 (good) +#' * _dark_: below 0.1 (low) #' } #' } -#' \item{\code{mcmc_acf}}{ -#' Grid of autocorrelation plots by chain and parameter. The \code{lags} +#' \item{`mcmc_acf()`, `mcmc_acf_bar()`}{ +#' Grid of autocorrelation plots by chain and parameter. The `lags` #' argument gives the maximum number of lags at which to calculate the -#' autocorrelation function. \code{mcmc_acf} is a line plot whereas -#' \code{mcmc_acf_bar} is a barplot. +#' autocorrelation function. `mcmc_acf()` is a line plot whereas +#' `mcmc_acf_bar()` is a barplot. #' } #'} #' #' @template reference-stan-manual #' @references #' Gelman, A. and Rubin, D. B. (1992). Inference from iterative -#' simulation using multiple sequences. \emph{Statistical Science}. 7(4), +#' simulation using multiple sequences. *Statistical Science*. 7(4), #' 457--472. #' #' @seealso -#' \itemize{ -#' \item The \emph{Visual MCMC Diagnostics} vignette. -#' \item \link{MCMC-nuts} for additional MCMC diagnostic plots for models fit +#' * The [Visual MCMC Diagnostics](https://mc-stan.org/bayesplot/articles/visual-mcmc-diagnostics.html) +#' vignette. +#' * [MCMC-nuts] for additional MCMC diagnostic plots for models fit #' using the No-U-Turn-Sampler. -#' } #' #' @examples #' # autocorrelation @@ -128,7 +124,7 @@ NULL #' @rdname MCMC-diagnostics #' @export -#' @param rhat A vector of \code{\link[=rhat]{Rhat}} estimates. +#' @param rhat A vector of R-hat estimates. #' mcmc_rhat <- function(rhat, ..., size = NULL) { check_ignored_arguments(...) @@ -213,8 +209,8 @@ mcmc_rhat_data <- function(rhat, ...) { #' @rdname MCMC-diagnostics #' @export -#' @param ratio A vector of \emph{ratios} of effective sample size estimates to -#' total sample size. See \code{\link{neff_ratio}}. +#' @param ratio A vector of *ratios* of effective sample size estimates to +#' total sample size. See [neff_ratio()]. #' mcmc_neff <- function(ratio, ..., size = NULL) { check_ignored_arguments(...) @@ -355,11 +351,11 @@ mcmc_acf_bar <- #' Convert numeric vector of diagnostic values to a factor #' -#' @param x A numeric vector +#' @param x A numeric vector. #' @param breaks A numeric vector of length two. The resulting factor variable -#' will have three levels ('low', 'ok', and 'high') corresponding to (x <= -#' breaks[1], breaks[1] < x <= breaks[2], x > breaks[2]). -#' @return A factor the same length as x with three levels. +#' will have three levels ('low', 'ok', and 'high') corresponding to ( +#' `x <= breaks[1]`, `breaks[1] < x <= breaks[2]`, `x > breaks[2]`). +#' @return A factor the same length as `x` with three levels. #' @noRd diagnostic_factor <- function(x, breaks, ...) { UseMethod("diagnostic_factor") @@ -412,7 +408,7 @@ diagnostic_points <- function(size = NULL) { } -# Functions wrapping around scale_color_manual and scale_fill_manual, used to +# Functions wrapping around scale_color_manual() and scale_fill_manual(), used to # color the intervals by rhat value scale_color_diagnostic <- function(diagnostic = c("rhat", "neff")) { d <- match.arg(diagnostic) @@ -505,8 +501,8 @@ drop_NAs_and_warn <- function(x) { x[!is_NA] } -# autocorr plot (either bar or line) -# @param size passed to geom_line if style="line" +# Autocorrelation plot (either bar or line) +# @param size passed to geom_line() if style="line" .mcmc_acf <- function(x, pars = character(), diff --git a/R/mcmc-distributions.R b/R/mcmc-distributions.R index f59d7ae2d..bb3899f8a 100644 --- a/R/mcmc-distributions.R +++ b/R/mcmc-distributions.R @@ -1,7 +1,7 @@ #' Histograms and kernel density plots of MCMC draws #' #' Various types of histograms and kernel density plots of MCMC draws. See the -#' \strong{Plot Descriptions} section, below, for details. +#' **Plot Descriptions** section, below, for details. #' #' @name MCMC-distributions #' @family MCMC @@ -17,27 +17,27 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{mcmc_hist}}{ +#' \item{`mcmc_hist()`}{ #' Histograms of posterior draws with all chains merged. #' } -#' \item{\code{mcmc_dens}}{ +#' \item{`mcmc_dens()`}{ #' Kernel density plots of posterior draws with all chains merged. #' } -#' \item{\code{mcmc_hist_by_chain}}{ +#' \item{`mcmc_hist_by_chain()`}{ #' Histograms of posterior draws with chains separated via faceting. #' } -#' \item{\code{mcmc_dens_overlay}}{ +#' \item{`mcmc_dens_overlay()`}{ #' Kernel density plots of posterior draws with chains separated but #' overlaid on a single plot. #' } -#' \item{\code{mcmc_violin}}{ +#' \item{`mcmc_violin()`}{ #' The density estimate of each chain is plotted as a violin with #' horizontal lines at notable quantiles. #' } -#' \item{\code{mcmc_dens_chains}}{ +#' \item{`mcmc_dens_chains()`}{ #' Ridgeline kernel density plots of posterior draws with chains separated -#' but overlaid on a single plot. In \code{mcmc_dens_overlay} parameters -#' appear in separate facets; in \code{mcmc_dens_chains} they appear in the +#' but overlaid on a single plot. In `mcmc_dens_overlay()` parameters +#' appear in separate facets; in `mcmc_dens_chains()` they appear in the #' same panel and can overlap vertically. #' } #' } @@ -202,7 +202,7 @@ mcmc_dens_overlay <- function(x, #' @rdname MCMC-distributions #' @template args-density-controls -#' @param color_chains option for whether to separately color chains. +#' @param color_chains Option for whether to separately color chains. #' @export mcmc_dens_chains <- function(x, pars = character(), regex_pars = character(), transformations = list(), diff --git a/R/mcmc-intervals.R b/R/mcmc-intervals.R index 7fe7a960f..23f5dfc2b 100644 --- a/R/mcmc-intervals.R +++ b/R/mcmc-intervals.R @@ -1,7 +1,7 @@ #' Plot interval estimates from MCMC draws #' #' Plot central (quantile-based) posterior interval estimates from MCMC draws. -#' See the \strong{Plot Descriptions} section, below, for details. +#' See the **Plot Descriptions** section, below, for details. #' #' @name MCMC-intervals #' @family MCMC @@ -12,41 +12,40 @@ #' @template args-transformations #' @param ... Currently unused. #' @param prob The probability mass to include in the inner interval (for -#' \code{mcmc_intervals}) or in the shaded region (for \code{mcmc_areas}). The -#' default is \code{0.5} (50\% interval) and \code{1} for -#' \code{mcmc_areas_ridges}. +#' `mcmc_intervals()`) or in the shaded region (for `mcmc_areas()`). The +#' default is `0.5` (50\% interval) and `1` for +#' `mcmc_areas_ridges`. #' @param prob_outer The probability mass to include in the outer interval. The -#' default is \code{0.9} for \code{mcmc_intervals} (90\% interval) and -#' \code{1} for \code{mcmc_areas} and for \code{mcmc_areas_ridges}. -#' @param area_method How to constrain the areas in \code{mcmc_areas}. The -#' default is \code{"equal area"}, setting the density curves to have the same -#' area. With \code{"equal height"}, the curves are scaled so that the highest -#' points across the curves are the same height. The method \code{"scaled -#' height"} tries a compromise between to the two: the heights from -#' \code{"equal height"} are scaled using \code{height*sqrt(height)} -#' @param point_est The point estimate to show. Either \code{"median"} (the -#' default), \code{"mean"}, or \code{"none"}. -#' @param rhat An optional numeric vector of \eqn{\hat{R}}{Rhat} estimates, with -#' one element per parameter included in \code{x}. If \code{rhat} is provided, -#' the intervals/areas and point estimates in the resulting plot are colored -#' based on \eqn{\hat{R}}{Rhat} value. See \code{\link{rhat}} for methods for -#' extracting \eqn{\hat{R}}{Rhat} estimates. +#' default is `0.9` for `mcmc_intervals()` (90\% interval) and +#' `1` for `mcmc_areas()` and for `mcmc_areas_ridges()`. +#' @param area_method How to constrain the areas in `mcmc_areas()`. The +#' default is `"equal area"`, setting the density curves to have the same +#' area. With `"equal height"`, the curves are scaled so that the highest +#' points across the curves are the same height. The method `"scaled +#' height"` tries a compromise between to the two: the heights from +#' `"equal height"` are scaled using `height*sqrt(height)` +#' @param point_est The point estimate to show. Either `"median"` (the +#' default), `"mean"`, or `"none"`. +#' @param rhat An optional numeric vector of R-hat estimates, with one element +#' per parameter included in `x`. If `rhat` is provided, the intervals/areas +#' and point estimates in the resulting plot are colored based on R-hat value. +#' See [rhat()] for methods for extracting R-hat estimates. #' @template args-density-controls #' #' @template return-ggplot-or-data #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{mcmc_intervals}}{ +#' \item{`mcmc_intervals()`}{ #' Plots of uncertainty intervals computed from posterior draws with all #' chains merged. #' } -#' \item{\code{mcmc_areas}}{ +#' \item{`mcmc_areas()`}{ #' Density plots computed from posterior draws with all chains merged, #' with uncertainty intervals shown as shaded areas under the curves. #' } -#' \item{\code{mcmc_areas_ridges}}{ -#' Density plot, as in \code{mcmc_areas}, but drawn with overlapping +#' \item{`mcmc_areas_ridges()`}{ +#' Density plot, as in `mcmc_areas()`, but drawn with overlapping #' ridgelines. This plot provides a compact display of (hierarchically) #' related distributions. #' } diff --git a/R/mcmc-overview.R b/R/mcmc-overview.R index dfff1f411..3b4d1bd6d 100644 --- a/R/mcmc-overview.R +++ b/R/mcmc-overview.R @@ -5,71 +5,52 @@ #' @family MCMC #' #' @description -#' The \pkg{bayesplot} MCMC module provides various plotting functions for +#' The **bayesplot** MCMC module provides various plotting functions for #' creating graphical displays of Markov chain Monte Carlo (MCMC) simulations. -#' The \strong{MCMC plotting functions} section, below, provides links to the +#' The **MCMC plotting functions** section, below, provides links to the #' documentation for various categories of MCMC plots. Currently the MCMC #' plotting functions accept posterior draws provided in one of the following #' formats: -#' \itemize{ -#' \item \strong{3-D array}: An \code{\link{array}} with dimensions -#' \code{[Iteration, Chain, Parameter]} in that order. -#' \item \strong{list}: A \code{list} of matrices, where each matrix -#' corresponds to a Markov chain. All of the matrices should have the same -#' number of iterations (rows) and parameters (columns), and parameters should -#' have the same names and be in the same order. -#' \item \strong{matrix (2-D array)}: A \code{\link{matrix}} with one column -#' per parameter. If using matrix there should only be a single Markov chain or -#' all chains should already be merged (stacked). -#' \item \strong{data frame}: There are two types of \link[=data.frame]{data -#' frames} allowed. Either a data frame with one column per parameter (if only -#' a single chain or all chains have already been merged), or a data frame with -#' one column per parameter plus an additional column \code{"Chain"} that -#' contains the chain number (an integer) corresponding to each row in -#' the data frame. -#' } -#' \strong{Note}: typically the user should \emph{not} include warmup iterations -#' in the object passed to \pkg{bayesplot} plotting functions, although for +#' * __3-D array__: An array with dimensions `[Iteration, Chain, Parameter]` +#' in that order. +#' * __list__: A list of matrices, where each matrix corresponds to a Markov +#' chain. All of the matrices should have the same number of iterations (rows) +#' and parameters (columns), and parameters should have the same names and be +#' in the same order. +#' * __matrix (2-D array)__: A matrix with one column per parameter. If using +#' matrix there should only be a single Markov chain or all chains should +#' already be merged (stacked). +#' * __data frame__: There are two types of [data frames][base::data.frame] +#' allowed. Either a data frame with one column per parameter (if only a single +#' chain or all chains have already been merged), or a data frame with one +#' column per parameter plus an additional column `"Chain"` that contains the +#' chain number (an integer) corresponding to each row in the data frame. +#' __Note__: typically the user should *not* include warmup iterations +#' in the object passed to **bayesplot** plotting functions, although for #' certain plots (e.g. trace plots) it can occasionally be useful to include the #' warmup iterations for diagnostic purposes. #' #' @section MCMC plotting functions: -#' -#' \describe{ -#' \item{\strong{\link[=MCMC-distributions]{Posterior distributions}}}{ -#' Histograms and kernel density plots of parameter draws, optionally -#' showing each Markov chain separately. -#' } -#' \item{\strong{\link[=MCMC-intervals]{Uncertainty intervals}}}{ -#' Uncertainty intervals computed from parameter draws. -#' } -#' \item{\strong{\link[=MCMC-traces]{Trace plots}}}{ -#' Times series of parameter draws, optionally including with HMC/NUTS -#' diagnostic information. -#' } -#' \item{\strong{\link[=MCMC-scatterplots]{Scatterplots}}}{ -#' Scatterplots, heatmaps, and pairs plots of parameter draws, optionally -#' including with HMC/NUTS diagnostic information. -#' } -#' \item{\strong{\link[=MCMC-parcoord]{Parallel coordinates plots}}}{ -#' Parallel coordinates plot of MCMC draws (one dimension per parameter), -#' optionally including with HMC/NUTS diagnostic information. -#' } -#' \item{\strong{\link[=MCMC-combos]{Combinations}}}{ -#' Combination plots (e.g. trace plot + histogram). -#' } -#' \item{\strong{\link[=MCMC-diagnostics]{General MCMC diagnostics}}}{ -#' MCMC diagnostic plots including Rhat, effective sample size, -#' autocorrelation. -#' } -#' \item{\strong{\link[=MCMC-nuts]{NUTS diagnostics}}}{ -#' Special diagnostic plots for the No-U-Turn Sampler. -#' } -#' \item{\strong{\link[=MCMC-recover]{Comparisons to "true" values}}}{ -#' Plots comparing MCMC estimates to "true" parameter values (e.g., -#' values used to simulate data). -#' } -#' } +#' * [__Posterior distributions__][MCMC-distributions]: +#' Histograms and kernel density plots of parameter draws, optionally +#' showing each Markov chain separately. +#' * [__Uncertainty intervals__][MCMC-intervals]: Uncertainty intervals computed +#' from parameter draws. +#' * [__Trace plots__][MCMC-traces]: Times series of parameter draws, optionally +#' including with HMC/NUTS diagnostic information. +#' * [__Scatterplots__][MCMC-scatterplots]: Scatterplots, heatmaps, and pairs +#' plots of parameter draws, optionally including with HMC/NUTS diagnostic +#' information. +#' * [__Parallel coordinates plots__][MCMC-parcoord]: Parallel coordinates plot +#' of MCMC draws (one dimension per parameter), optionally including with +#' HMC/NUTS diagnostic information. +#' * [__Combos__][MCMC-combos]: Combination plots (e.g. trace plot + histogram). +#' * [__General MCMC diagnostics__][MCMC-diagnostics]: MCMC diagnostic plots +#' including R-hat, effective sample size, autocorrelation. +#' [__NUTS diagnostics__][MCMC-nuts]: Special diagnostic plots for +#' the No-U-Turn Sampler. +#' * [__Comparisons to "true" values__][MCMC-recover]: Plots comparing MCMC +#' estimates to "true" parameter values (e.g., values used to simulate data). #' #' @template reference-vis-paper #' diff --git a/R/mcmc-parcoord.R b/R/mcmc-parcoord.R index 7109cc360..34309ed4e 100644 --- a/R/mcmc-parcoord.R +++ b/R/mcmc-parcoord.R @@ -1,8 +1,8 @@ #' Parallel coordinates plot of MCMC draws #' -#' Parallel coordinates plot of MCMC draws (one dimension per parameter). See -#' the \strong{Plot Descriptions} section below for details, and see -#' \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)} +#' Parallel coordinates plot of MCMC draws (one dimension per parameter). +#' See the **Plot Descriptions** section below for details, +#' and see [Gabry et al. (2019)](https://github.com/jgabry/bayes-vis-paper) #' for more background and a real example. #' #' @name MCMC-parcoord @@ -13,15 +13,15 @@ #' @template args-regex_pars #' @template args-transformations #' @param ... Currently ignored. -#' @param size,alpha Arguments passed on to \code{\link[ggplot2]{geom_line}}. -#' @param np For models fit using \code{\link{NUTS}} (more generally, -#' any \href{https://en.wikipedia.org/wiki/Symplectic_integrator}{symplectic -#' integrator}), an optional data frame providing NUTS -#' diagnostic information. The data frame should be the object returned by -#' \code{\link{nuts_params}} or one with the same structure. -#' @param np_style A call to the \code{parcoord_style_np} helper function to +#' @param size,alpha Arguments passed on to [ggplot2::geom_line()]. +#' @param np For models fit using [NUTS] (more generally, +#' any [symplectic integrator](https://en.wikipedia.org/wiki/Symplectic_integrator)), +#' an optional data frame providing NUTS diagnostic information. The data +#' frame should be the object returned by [nuts_params()] or one with the same +#' structure. +#' @param np_style A call to the `parcoord_style_np()` helper function to #' specify arguments controlling the appearance of superimposed lines -#' representing NUTS diagnostics (in this case divergences) if the \code{np} +#' representing NUTS diagnostics (in this case divergences) if the `np` #' argument is specified. #' #' @template return-ggplot-or-data @@ -29,32 +29,31 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{mcmc_parcoord}}{ -#' (\href{https://en.wikipedia.org/wiki/Parallel_coordinates}{Parallel -#' coordinates plot}) of MCMC draws. There is one dimension per parameter -#' along the horizontal axis and each set of connected line segments -#' represents a single MCMC draw (i.e., a vector of length equal to the -#' number of parameters). +#' \item{`mcmc_parcoord()`}{ +#' [Parallel coordinates plot](https://en.wikipedia.org/wiki/Parallel_coordinates) +#' of MCMC draws. There is one dimension per parameter along the horizontal +#' axis and each set of connected line segments represents a single MCMC draw +#' (i.e., a vector of length equal to the number of parameters). #' #' The parallel coordinates plot is most useful if the optional HMC/NUTS -#' diagnostic information is provided via the \code{np} argument. In that +#' diagnostic information is provided via the `np` argument. In that #' case divergences are highlighted in the plot. The appearance of the -#' divergences can be customized using the \code{np_style} argument and the -#' \code{parcoord_style_np} helper function. This version of the plot is the +#' divergences can be customized using the `np_style` argument and the +#' `parcoord_style_np` helper function. This version of the plot is the #' same as the parallel coordinates plot described in Gabry et al. (2019). #' #' When the plotted model parameters are on very different scales the -#' \code{transformations} argument can be useful. For example, to standardize -#' all variables before plotting you could use function \code{(x - -#' mean(x))/sd(x)} when specifying the \code{transformations} argument to -#' \code{mcmc_parcoord}. See the \strong{Examples} section for how to do this. +#' `transformations` argument can be useful. For example, to standardize +#' all variables before plotting you could use function `(x - mean(x))/sd(x)` +#' when specifying the `transformations` argument to +#' `mcmc_parcoord`. See the **Examples** section for how to do this. #' } #' } #' #' @template reference-vis-paper #' @references Hartikainen, A. (2017, Aug 23). Concentration of divergences -#' [Msg 21]. Message posted to The Stan Forums: -#' \url{https://discourse.mc-stan.org/t/concentration-of-divergences/1590/21}. +#' (Msg 21). Message posted to The Stan Forums: +#' . #' #' @examples #' color_scheme_set("pink") @@ -203,11 +202,10 @@ mcmc_parcoord_data <- #' @rdname MCMC-parcoord #' @export #' @param div_color,div_size,div_alpha Optional arguments to the -#' \code{parcoord_style_np} helper function that are eventually passed to -#' \code{\link[ggplot2]{geom_line}} if the \code{np} argument is also -#' specified. They control the color, size, and transparency specifications -#' for showing divergences in the plot. The default values are displayed in -#' the \strong{Usage} section above. +#' `parcoord_style_np()` helper function that are eventually passed to +#' [ggplot2::geom_line()] if the `np` argument is also specified. They control +#' the color, size, and transparency specifications for showing divergences in +#' the plot. The default values are displayed in the **Usage** section above. parcoord_style_np <- function(div_color = "red", div_size = 0.2, diff --git a/R/mcmc-recover.R b/R/mcmc-recover.R index 40687f802..9c9cf3e20 100644 --- a/R/mcmc-recover.R +++ b/R/mcmc-recover.R @@ -4,7 +4,7 @@ #' model to real data it is useful to simulate data according to the model using #' known (fixed) parameter values and to check that these "true" parameter #' values are (approximately) recovered by fitting the model to the simulated -#' data. See the \strong{Plot Descriptions} section, below, for details on the +#' data. See the **Plot Descriptions** section, below, for details on the #' available plots. #' #' @name MCMC-recover @@ -12,41 +12,41 @@ #' #' @template args-mcmc-x #' @template args-facet_args -#' @param true A numeric vector of "true" values of the parameters in \code{x}. -#' There should be one value in \code{true} for each parameter included in -#' \code{x} and the order of the parameters in \code{true} should be the same -#' as the order of the parameters in \code{x}. +#' @param true A numeric vector of "true" values of the parameters in `x`. +#' There should be one value in `true` for each parameter included in +#' `x` and the order of the parameters in `true` should be the same +#' as the order of the parameters in `x`. #' @param batch Optionally, a vector-like object (numeric, character, integer, -#' factor) used to split the parameters into batches. If \code{batch} is -#' specified, it must have the same length as \code{true} and be in the same -#' order as \code{true}. Parameters in the same batch will be grouped together -#' in the same facet in the plot (see the \strong{Examples} section, below). +#' factor) used to split the parameters into batches. If `batch` is +#' specified, it must have the same length as `true` and be in the same +#' order as `true`. Parameters in the same batch will be grouped together +#' in the same facet in the plot (see the **Examples** section, below). #' The default is to group all parameters together into a single batch. #' Changing the default is most useful when parameters are on very different -#' scales, in which case \code{batch} can be used to group them into batches -#' within which it makes sense to use the same \eqn{y}-axis. +#' scales, in which case `batch` can be used to group them into batches +#' within which it makes sense to use the same y-axis. #' @param ... Currently unused. #' @param prob The probability mass to include in the inner interval. The -#' default is \code{0.5} (50\% interval). +#' default is `0.5` (50\% interval). #' @param prob_outer The probability mass to include in the outer interval. The -#' default is \code{0.9} (90\% interval). -#' @param point_est The point estimate to show. Either \code{"median"} (the -#' default), \code{"mean"}, or \code{"none"}. -#' @param size,alpha Passed to \code{\link[ggplot2]{geom_point}} to control the +#' default is `0.9` (90\% interval). +#' @param point_est The point estimate to show. Either `"median"` (the +#' default), `"mean"`, or `"none"`. +#' @param size,alpha Passed to [ggplot2::geom_point()] to control the #' appearance of plotted points. #' #' @template return-ggplot #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{mcmc_recover_intervals}}{ +#' \item{`mcmc_recover_intervals()`}{ #' Central intervals and point estimates computed from MCMC draws, with #' "true" values plotted using a different shape. #' } -#' \item{\code{mcmc_recover_scatter}}{ +#' \item{`mcmc_recover_scatter()`}{ #' Scatterplot of posterior means (or medians) against "true" values. #' } -#' \item{\code{mcmc_recover_hist}}{ +#' \item{`mcmc_recover_hist()`}{ #' Histograms of the draws for each parameter with the "true" value overlaid #' as a vertical line. #' } diff --git a/R/mcmc-scatterplots.R b/R/mcmc-scatterplots.R index 9608b2d29..81461e548 100644 --- a/R/mcmc-scatterplots.R +++ b/R/mcmc-scatterplots.R @@ -1,59 +1,58 @@ #' Scatterplots of MCMC draws #' #' Scatterplots, hexagonal heatmaps, and pairs plots from MCMC draws. See the -#' \strong{Plot Descriptions} section, below, for details. +#' **Plot Descriptions** section, below, for details. #' #' @name MCMC-scatterplots #' @family MCMC #' #' @template args-mcmc-x #' @param pars An optional character vector of parameter names. For -#' \code{mcmc_scatter} and \code{mcmc_hex} only two parameters can be -#' selected. To plot more than two parameters use \code{mcmc_pairs}. +#' `mcmc_scatter()` and `mcmc_hex()` only two parameters can be +#' selected. To plot more than two parameters use `mcmc_pairs()`. #' @template args-regex_pars #' @template args-transformations #' @param ... Currently ignored. -#' @param size,alpha For \code{mcmc_scatter}, passed to -#' \code{\link[ggplot2]{geom_point}} to control the appearance of the points. -#' @param binwidth For \code{mcmc_hex}, an optional numeric vector of -#' \emph{length two} passed to \code{\link[ggplot2]{geom_hex}} to override the +#' @param size,alpha For `mcmc_scatter()`, passed to +#' [ggplot2::geom_point()] to control the appearance of the points. +#' @param binwidth For `mcmc_hex()`, an optional numeric vector of +#' *length two* passed to [ggplot2::geom_hex()] to override the #' default binwidth in both the vertical and horizontal directions. #' #' @param np Optionally, a data frame of NUTS sampler parameters, either created -#' by \code{\link{nuts_params}} or in the same form as the object returned by -#' \code{\link{nuts_params}}. The colors, shapes, and sizes of the -#' superimposed points can be customized using the \code{np_style} argument. -#' @param np_style If \code{np} is specified, \code{np_style} can be a call to -#' the \code{scatter_style_np} helper function (for \code{mcmc_scatter}) or -#' the \code{pairs_style_np} helper function (for \code{mcmc_pars}) to specify +#' by [nuts_params()] or in the same form as the object returned by +#' [nuts_params()]. The colors, shapes, and sizes of the +#' superimposed points can be customized using the `np_style` argument. +#' @param np_style If `np` is specified, `np_style` can be a call to +#' the `scatter_style_np()` helper function (for `mcmc_scatter()`) or +#' the `pairs_style_np()` helper function (for `mcmc_pairs()`) to specify #' arguments controlling the appearance of superimposed points representing -#' NUTS diagnostic information. (Note: for \code{pairs_style_np} the -#' \code{size} arguments are interpreted as scaling factors). +#' NUTS diagnostic information. (Note: for `pairs_style_np()` the +#' `size` arguments are interpreted as scaling factors). #' -#' @return \code{mcmc_scatter} and \code{mcmc_hex} return a ggplot object that -#' can be further customized using the \pkg{ggplot2} package. +#' @return `mcmc_scatter()` and `mcmc_hex()` return a ggplot object that +#' can be further customized using the **ggplot2** package. #' -#' \code{mcmc_pairs} returns many ggplot objects organized into a grid via -#' \code{\link{bayesplot_grid}}. +#' `mcmc_pairs()` returns many ggplot objects organized into a grid via +#' [bayesplot_grid()]. #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{mcmc_scatter}}{ +#' \item{`mcmc_scatter()`}{ #' Bivariate scatterplot of posterior draws. If using a very large number of -#' posterior draws then \code{mcmc_hex} may be preferable to avoid -#' overplotting. For models fit using \code{\link{NUTS}} the \code{np}, -#' and \code{np_style} arguments can be used to add additional information in +#' posterior draws then `mcmc_hex()` may be preferable to avoid +#' overplotting. For models fit using [NUTS] the `np`, +#' and `np_style` arguments can be used to add additional information in #' the plot (in this case the approximate location of divergences). -#' For an example of why the scatter plot with divergences is a useful -#' diagnostic tool see \href{https://github.com/jgabry/bayes-vis-paper}{Gabry -#' et al. (2019)}. +#' For more on why the scatter plot with divergences is a useful +#' diagnostic tool see [Gabry et al. (2019)](https://github.com/jgabry/bayes-vis-paper). #' } -#' \item{\code{mcmc_hex}}{ +#' \item{`mcmc_hex()`}{ #' Hexagonal heatmap of 2-D bin counts. This plot is useful in cases where -#' the posterior sample size is large enough that \code{mcmc_scatter} suffers +#' the posterior sample size is large enough that `mcmc_scatter()` suffers #' from overplotting. #' } -#' \item{\code{mcmc_pairs}}{ +#' \item{`mcmc_pairs()`}{ #' A square plot matrix with univariate marginal distributions along the #' diagonal (as histograms or kernel density plots) and bivariate #' distributions off the diagonal (as scatterplots or hex heatmaps). @@ -61,20 +60,20 @@ #' For the off-diagonal plots, the default is to split the chains so that #' (roughly) half are displayed above the diagonal and half are below (all #' chains are always merged together for the plots along the diagonal). Other -#' possibilities are available by setting the \code{condition} argument. +#' possibilities are available by setting the `condition` argument. #' #' Additionally, extra diagnostic information for models fit using -#' \code{\link{NUTS}} can be added to the pairs plot using the \code{lp}, -#' \code{np}, and \code{np_style} arguments. If \code{np} is specified (and -#' \code{condition} is \emph{not} \code{"divergent__"}), then points (red, by +#' [NUTS] can be added to the pairs plot using the `lp`, +#' `np`, and `np_style` arguments. If `np` is specified (and +#' `condition` is *not* `"divergent__"`), then points (red, by #' default) will be superimposed onto the off-diagonal plots indicating which #' (if any) iterations encountered a divergent transition. Also, if both -#' \code{np} and \code{max_treedepth} are specified then points (yellow, by +#' `np` and `max_treedepth` are specified then points (yellow, by #' default) will be superimposed to indicate a transition that hit the #' maximum treedepth rather than terminated its evolution normally. The -#' \code{np_style} argument can be used with the \code{pairs_style_np} +#' `np_style` argument can be used with the `pairs_style_np()` #' convenience function to change the appearance of these overlaid points. -#' See the \strong{Examples} section. +#' See the **Examples** section. #' } #' } #' @@ -173,45 +172,45 @@ mcmc_hex <- function(x, #' @rdname MCMC-scatterplots #' @export -#' @param condition For \code{mcmc_pairs}, a call to the \code{pairs_condition} +#' @param condition For `mcmc_pairs()`, a call to the `pairs_condition()` #' helper function, which is used to specify a criterion for determining which #' chains (or iterations) are shown in the plots above the diagonal and which #' are shown in the plots below the diagonal. The histograms (or density #' plots) along the diagonal are always made using all chains and iterations, #' but the scatterplots (or hex plots) above and below the diagonal show -#' different combinations of chains/iterations depending on \code{condition}. -#' The default is a call to \code{pairs_condition} with none of its arguments +#' different combinations of chains/iterations depending on `condition`. +#' The default is a call to `pairs_condition()` with none of its arguments #' specified. In this case half of the chains (or roughly half if there are an #' odd number) will be used in the plots above the diagonal and the rest in -#' the plots below the diagonal. The \code{chains}, \code{draws}, and -#' \code{nuts} arguments to \code{pairs_condition}, which are documented +#' the plots below the diagonal. The `chains`, `draws`, and +#' `nuts` arguments to `pairs_condition()`, which are documented #' below, can be used to change this default. #' -#' @param lp For \code{mcmc_pairs}, a molten data frame of draws of the +#' @param lp For `mcmc_pairs()`, a molten data frame of draws of the #' log-posterior or, more commonly, of a quantity equal to the log-posterior -#' up to a constant. \code{lp} should either be created via -#' \code{\link{log_posterior}} or be an object with the same form as the -#' object returned by \code{\link{log_posterior}}. -#' @param max_treedepth For \code{mcmc_pairs}, an integer representing the +#' up to a constant. `lp` should either be created via +#' [log_posterior()] or be an object with the same form as the +#' object returned by [log_posterior()]. +#' @param max_treedepth For `mcmc_pairs()`, an integer representing the #' maximum treedepth allowed when fitting the model (if fit using NUTS). This #' is only needed for detecting which transitions (if any) hit the maximum #' treedepth. -#' @param diag_fun,off_diag_fun For \code{mcmc_pairs}, the plotting function to +#' @param diag_fun,off_diag_fun For `mcmc_pairs()`, the plotting function to #' use for the plots along the diagonal and for the off-diagonal plots, -#' respectively. Currently \code{diag_fun} can be \code{"hist"} for histogram -#' or \code{"dens"} for density, and \code{off_diag_fun} can be -#' \code{"scatter"} for scatterplot or \code{"hex"} for a hexagonal heatmap. -#' @param diag_args,off_diag_args For \code{mcmc_pairs}, optional named lists of -#' arguments to pass to the functions implied by the \code{diag_fun} and -#' \code{off_diag_fun} arguments, respectively. For example, if -#' \code{off_diag_fun} is \code{"scatter"} then \code{off_diag_args} could -#' include optional arguments to \code{mcmc_scatter} like \code{size} and -#' \code{alpha}. -#' @param grid_args,save_gg_objects For \code{mcmc_pairs}, arguments to pass to -#' \code{\link{bayesplot_grid}}. For example, since \code{mcmc_pairs} returns -#' more than a single ggplot object, using \code{\link{ggtitle}} afterwards +#' respectively. Currently `diag_fun` can be `"hist"` for histogram +#' or `"dens"` for density, and `off_diag_fun` can be +#' `"scatter"` for scatterplot or `"hex"` for a hexagonal heatmap. +#' @param diag_args,off_diag_args For `mcmc_pairs()`, optional named lists of +#' arguments to pass to the functions implied by the `diag_fun` and +#' `off_diag_fun` arguments, respectively. For example, if +#' `off_diag_fun` is `"scatter"` then `off_diag_args` could +#' include optional arguments to `mcmc_scatter()` like `size` and +#' `alpha`. +#' @param grid_args,save_gg_objects For `mcmc_pairs()`, arguments to pass to +#' [bayesplot_grid()]. For example, since `mcmc_pairs()` returns +#' more than a single ggplot object, using [ggtitle()] afterwards #' will not work. But you you can still add a title to the plot using -#' \code{grid_args = list(top="My title")}. +#' `grid_args = list(top="My title")`. #' #' @examples #' \donttest{ @@ -438,10 +437,10 @@ mcmc_pairs <- function(x, #' @rdname MCMC-scatterplots #' @export #' @param div_color,div_shape,div_size,div_alpha,td_color,td_shape,td_size,td_alpha -#' Optional arguments to the \code{scatter_style_np} or \code{pairs_style_np} +#' Optional arguments to the `scatter_style_np()` or `pairs_style_np()` #' helper functions that are eventually passed to -#' \code{\link[ggplot2]{geom_point}}.The default values are displayed in the -#' \strong{Usage} section above. +#' [ggplot2::geom_point()].The default values are displayed in the +#' **Usage** section above. scatter_style_np <- function(div_color = "red", div_shape = 16, @@ -495,41 +494,41 @@ pairs_style_np <- #' @rdname MCMC-scatterplots #' @export -#' @param chains,draws,nuts Optional arguments to the \code{pairs_condition} -#' helper function, which is used to specify the \code{condition} argument for -#' \code{mcmc_pairs}. +#' @param chains,draws,nuts Optional arguments to the `pairs_condition()` +#' helper function, which is used to specify the `condition` argument for +#' `mcmc_pairs()`. #' \itemize{ -#' \item The \code{chains} argument can be used to select some subset of the -#' chains. If \code{chains} is an integer vector then the behavior is the same +#' \item The `chains` argument can be used to select some subset of the +#' chains. If `chains` is an integer vector then the behavior is the same #' as the default (half the chains above the diagonal and half below) except -#' using only the specified subset of chains. Alternatively, \code{chains} can +#' using only the specified subset of chains. Alternatively, `chains` can #' be a list of two integer vectors with the first specifying the chains to be #' shown in the plots above the diagonal and the second for below the #' diagonal. -#' \item The \code{draws} argument to \code{pairs_condition} can be used to +#' \item The `draws` argument to `pairs_condition()` can be used to #' directly specify which realizations are plotted above and below the -#' diagonal. \code{draws} can be a single proportion, which is interpreted as +#' diagonal. `draws` can be a single proportion, which is interpreted as #' the proportion of realizations (among all chains) to plot in the lower #' panel starting with the first realization in each chain, with the #' complement (from the end of each chain) plotted in the upper panel. -#' Alternatively \code{draws} can be a logical vector with length equal to the +#' Alternatively `draws` can be a logical vector with length equal to the #' product of the number of iterations and the number of chains, in which case -#' realizations corresponding to \code{FALSE} and \code{TRUE} will be plotted +#' realizations corresponding to `FALSE` and `TRUE` will be plotted #' in the lower and upper panels, respectively. -#' \item For models fit using NUTS, the \code{nuts} argument to -#' \code{pairs_condition} can be used. It takes a (possibly abbreviated) -#' string to select among \code{"accept_stat__"}, \code{"stepsize__"}, -#' \code{"treedepth__"}, \code{"n_leapfrog__"}, \code{"divergent__"}, -#' \code{"energy__"}, and \code{"lp__"}. These are the sampler parameters -#' associated with \code{\link{NUTS}} (and \code{"lp__"} is the log-posterior +#' \item For models fit using NUTS, the `nuts` argument to +#' `pairs_condition()` can be used. It takes a (possibly abbreviated) +#' string to select among `"accept_stat__"`, `"stepsize__"`, +#' `"treedepth__"`, `"n_leapfrog__"`, `"divergent__"`, +#' `"energy__"`, and `"lp__"`. These are the sampler parameters +#' associated with [NUTS()] (and `"lp__"` is the log-posterior #' up to an additive constant). In this case, plots below the diagonal will #' contain realizations that are below the median of the indicated variable -#' (or are zero in the case of \code{"divergent__"}), and plots above the +#' (or are zero in the case of `"divergent__"`), and plots above the #' diagonal will contain realizations that are greater than or equal to the #' median of the indicated variable (or are one in the case of -#' \code{"divergent__"}). If \code{"lp__"} is used then the \code{lp} -#' argument to \code{mcmc_pairs} must also be specified. For the other NUTS -#' parameters the \code{np} argument to \code{mcmc_pairs} must also be +#' `"divergent__"`). If `"lp__"` is used then the `lp` +#' argument to `mcmc_pairs` must also be specified. For the other NUTS +#' parameters the `np` argument to `mcmc_pairs()` must also be #' specified. #' } #' @@ -728,59 +727,62 @@ pairs_condition <- function(chains = NULL, draws = NULL, nuts = NULL) { # internal for mcmc_pairs ------------------------------------------------- -# Get plotting functions from user-specified diag_fun, off_diag_fun arguments -# -# @param x User specified diag_fun or off_diag_fun argument to mcmc_pairs +#' Get plotting functions from user-specified `diag_fun`, `off_diag_fun` arguments +#' @noRd +#' @param x User specified `diag_fun` or `off_diag_fun` argument to `mcmc_pairs()` pairs_plotfun <- function(x) { fun <- paste0("mcmc_", x) utils::getFromNamespace(fun, "bayesplot") } -# Unstack molten data frame -# -# @param df A data frame (from nuts_params(), log_posterior(), etc) -# @param .form Same as 'form' arg to utils::unstack +#' Unstack molten data frame +#' +#' @noRd +#' @param df A data frame (from `nuts_params()`, `log_posterior()`, etc) +#' @param .form Same as 'form' arg to `utils::unstack()` unstack_to_matrix <- function(df, .form) { x <- utils::unstack(df, form = .form) as.matrix(x) } -# Check if off-diagonal plot is above or below the diagonal -# -# @param j integer (index) -# @param n Number of parameters (number of plots = n^2) -# @return TRUE if below the diagonal FALSE if above the diagonal +#' Check if off-diagonal plot is above or below the diagonal +#' +#' @noRd +#' @param j integer (index) +#' @param n Number of parameters (number of plots = `n^2`) +#' @return `TRUE` if below the diagonal, `FALSE` if above the diagonal is_lower_tri <- function(j, n) { idx <- array_idx_j(j, n) lower_tri <- lower_tri_idx(n) row_match_found(idx, lower_tri) } -# Get array indices of the jth element in the plot matrix -# -# @param j integer (index) -# @param n number of parameters (number of plots = n^2) -# @return rwo vector (1-row matrix) containing the array indices of the jth -# element in the plot matrix +#' Get array indices of the jth element in the plot matrix +#' +#' @noRd +#' @param j integer (index) +#' @param n number of parameters (number of plots = n^2) +#' @return rwo vector (1-row matrix) containing the array indices of the jth +#' element in the plot matrix array_idx_j <- function(j, n) { jj <- matrix(seq_len(n^2), nrow = n, byrow = TRUE)[j] arrayInd(jj, .dim = c(n, n)) } -# Get indices of lower triangular elements of a square matrix -# -# @param n number of rows (columns) in the square matrix +#' Get indices of lower triangular elements of a square matrix +#' @noRd +#' @param n number of rows (columns) in the square matrix lower_tri_idx <- function(n) { a <- rev(abs(sequence(seq.int(n - 1)) - n) + 1) b <- rep.int(seq.int(n - 1), rev(seq.int(n - 1))) cbind(row = a, col = b) } -# Find which (if any) row in y is a match for x -# -# @param x a row vector (i.e., a matrix with 1 row) -# @param y a matrix -# @return either a row number in y or NA if no match +#' Find which (if any) row in y is a match for x +#' @noRd +#' @param x a row vector (i.e., a matrix with 1 row) +#' @param y a matrix +#' @return either a row number in `y` or `NA` if no match row_match_found <- function(x, y) { stopifnot(is.matrix(x), is.matrix(y), nrow(x) == 1) x <- as.data.frame(x) @@ -793,8 +795,9 @@ row_match_found <- function(x, y) { } -# Drop any constant or duplicate variables -# @param x 3-D array +#' Drop any constant or duplicate variables +#' @noRd +#' @param x 3-D array drop_constants_and_duplicates <- function(x) { x2 <- drop_consts(x) x2 <- drop_dupes(x2) @@ -824,13 +827,13 @@ drop_dupes <- function(x) { x[, , !dupes, drop = FALSE] } -# Handle user's specified condition -# -# @param x 3-D mcmc array -# @param condition Object returned by pairs_condition -# @param np,lp User-specified arguments to mcmc_pairs -# @return A named list containing 'x' (x, possibly modified) and 'mark' (logical -# or interger vector for eventually splitting x) +#' Handle user's specified `condition` +#' @noRd +#' @param x 3-D mcmc array. +#' @param condition Object returned by `pairs_condition()`. +#' @param np,lp User-specified arguments to `mcmc_pairs()`. +#' @return A named list containing `"x"` (`x`, possibly modified) and `"mark"` +#' (logical or interger vector for eventually splitting `x`). handle_condition <- function(x, condition=NULL, np=NULL, lp=NULL) { n_iter <- num_iters(x) n_chain <- num_chains(x) @@ -894,12 +897,13 @@ handle_condition <- function(x, condition=NULL, np=NULL, lp=NULL) { } -# Apply scale_color_manual and scale_size_manual if plotting divergences and -# hitting max_treedepth -# -# @param graph ggplot object -# @param np_args list of style arguments returned by pairs_style_np() -# @return graph, updated +#' Apply scale_color_manual and scale_size_manual if plotting divergences and +#' hitting max_treedepth +#' +#' @noRd +#' @param graph ggplot object +#' @param np_args list of style arguments returned by `pairs_style_np()` +#' @return `graph`, updated format_nuts_points <- function(graph, np_args) { graph + scale_color_manual( diff --git a/R/mcmc-traces.R b/R/mcmc-traces.R index cc3f24ab1..ae6bcc199 100644 --- a/R/mcmc-traces.R +++ b/R/mcmc-traces.R @@ -13,45 +13,45 @@ #' @template args-facet_args #' @param ... Currently ignored. #' @param size An optional value to override the default line size -#' (\code{mcmc_trace}) or the default point size -#' (\code{mcmc_trace_highlight}). -#' @param alpha For \code{mcmc_trace_highlight}, passed to -#' \code{\link[ggplot2]{geom_point}} to control the transparency of the points +#' (`mcmc_trace`) or the default point size +#' (`mcmc_trace_highlight`). +#' @param alpha For `mcmc_trace_highlight`, passed to +#' [ggplot2::geom_point()] to control the transparency of the points #' for the chains not highlighted. #' @param n_warmup An integer; the number of warmup iterations included in -#' \code{x}. The default is \code{n_warmup = 0}, i.e. to assume no warmup -#' iterations are included. If \code{n_warmup > 0} then the background for -#' iterations \code{1:n_warmup} is shaded gray. +#' `x`. The default is `n_warmup = 0`, i.e. to assume no warmup +#' iterations are included. If `n_warmup > 0` then the background for +#' iterations `1:n_warmup` is shaded gray. #' @param iter1 An integer; the iteration number of the first included draw #' (default 0). This can be used to make it more obvious that the warmup #' iterations have been discarded from the traceplot. It cannot be specified -#' if \code{n_warmup} is also set to a positive value. +#' if `n_warmup` is also set to a positive value. #' @param window An integer vector of length two specifying the limits of a #' range of iterations to display. -#' @param np For models fit using \code{\link{NUTS}} (more generally, any +#' @param np For models fit using [NUTS()] (more generally, any #' \href{https://en.wikipedia.org/wiki/Symplectic_integrator}{symplectic #' integrator}), an optional data frame providing NUTS diagnostic #' information. The data frame should be the object returned by -#' \code{\link{nuts_params}} or one with the same structure. If \code{np} is +#' [nuts_params()] or one with the same structure. If `np` is #' specified then tick marks are added to the bottom of the trace plot #' indicating within which iterations there was a divergence (if there were any). #' See the end of the \strong{Examples} section, below. -#' @param np_style A call to the \code{trace_style_np} helper function to +#' @param np_style A call to the `trace_style_np` helper function to #' specify arguments controlling the appearance of tick marks representing -#' divergences (if the \code{np} argument is specified). -#' @param divergences Deprecated. Use the \code{np} argument instead. +#' divergences (if the `np` argument is specified). +#' @param divergences Deprecated. Use the `np` argument instead. #' #' @template return-ggplot #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{mcmc_trace}}{ -#' Standard trace plots of MCMC draws. For models fit using \code{\link{NUTS}}, -#' the \code{np} argument can be used to also show divergences on the trace plot. +#' \item{`mcmc_trace`}{ +#' Standard trace plots of MCMC draws. For models fit using [NUTS()], +#' the `np` argument can be used to also show divergences on the trace plot. #' } -#' \item{\code{mcmc_trace_highlight}}{ +#' \item{`mcmc_trace_highlight`}{ #' Traces are plotted using points rather than lines and the opacity of all -#' chains but one (specified by the \code{highlight} argument) is reduced. +#' chains but one (specified by the `highlight` argument) is reduced. #' } #' } #' @@ -192,7 +192,7 @@ mcmc_trace <- #' @rdname MCMC-traces #' @export -#' @param highlight For \code{mcmc_trace_highlight}, an integer specifying one +#' @param highlight For `mcmc_trace_highlight`, an integer specifying one #' of the chains that will be more visible than the others in the plot. mcmc_trace_highlight <- function(x, @@ -227,8 +227,8 @@ mcmc_trace_highlight <- #' @rdname MCMC-traces #' @export #' @param div_color,div_size,div_alpha Optional arguments to the -#' \code{trace_style_np} helper function that are eventually passed to -#' \code{\link[ggplot2]{geom_rug}} if the \code{np} argument is also +#' `trace_style_np` helper function that are eventually passed to +#' [ggplot2::geom_rug()] if the `np` argument is also #' specified. They control the color, size, and transparency specifications #' for showing divergences in the plot. The default values are displayed in #' the \strong{Usage} section above. diff --git a/R/pp_check.R b/R/pp_check.R index 5d129cae5..558e47314 100644 --- a/R/pp_check.R +++ b/R/pp_check.R @@ -2,30 +2,29 @@ #' #' S3 generic with simple default method. The intent is to provide a generic so #' authors of other \R packages who wish to provide interfaces to the functions -#' in \pkg{bayesplot} will be encouraged to include \code{pp_check} methods in +#' in **bayesplot** will be encouraged to include `pp_check()` methods in #' their package, preserving the same naming conventions for posterior #' predictive checking across many \R packages for Bayesian inference. This is -#' for the convenience of both users and developers. See the \strong{Details} -#' and \strong{Examples} sections, below, and the package vignettes for examples -#' of defining \code{pp_check} methods. +#' for the convenience of both users and developers. See the **Details** +#' and **Examples** sections, below, and the package vignettes for examples +#' of defining `pp_check()` methods. #' #' @export #' @param object Typically a fitted model object. The default method, however, -#' takes \code{object} to be a \code{y} (outcome) vector. +#' takes `object` to be a `y` (outcome) vector. #' @param ... For the generic, arguments passed to individual methods. For the -#' default method, these are additional arguments to pass to \code{fun}. -#' @return The exact form of the value returned by \code{pp_check} may vary by -#' the class of \code{object}, but for consistency we encourage authors of -#' methods to return the ggplot object created by one of \pkg{bayesplot}'s -#' plotting functions. The default method returns the object returned by -#' \code{fun}. +#' default method, these are additional arguments to pass to `fun`. +#' @return The exact form of the value returned by `pp_check()` may vary by +#' the class of `object`, but for consistency we encourage authors of +#' methods to return the ggplot object created by one of **bayesplot**'s +#' plotting functions. The default method returns the object returned by `fun`. #' -#' @details A package that creates fitted model objects of class \code{"foo"} -#' can include a method \code{pp_check.foo} that prepares the appropriate -#' inputs (\code{y}, \code{yrep}, etc.) for the \pkg{bayesplot} functions. The -#' \code{pp_check.foo} method may, for example, let the user choose between -#' various plots, calling the functions from \pkg{bayesplot} internally as -#' needed. See \strong{Examples}, below, and the package vignettes. +#' @details A package that creates fitted model objects of class `"foo"` +#' can include a method `pp_check.foo()` that prepares the appropriate +#' inputs (`y`, `yrep`, etc.) for the **bayesplot** functions. The +#' `pp_check.foo()` method may, for example, let the user choose between +#' various plots, calling the functions from **bayesplot** internally as +#' needed. See **Examples**, below, and the package vignettes. #' #' @examples #' # default method @@ -55,11 +54,10 @@ pp_check <- function(object, ...) { #' @rdname pp_check #' @export -#' @param yrep For the default method, a \code{yrep} matrix passed to -#' \code{fun}. +#' @param yrep For the default method, a `yrep` matrix passed to `fun`. #' @param fun For the default method, the plotting function to call. Can be any -#' of the \link[=PPC]{PPC functions}. The \code{"ppc_"} prefix can optionally -#' be dropped if \code{fun} is specified as a string. +#' of the \link[=PPC]{PPC functions}. The `"ppc_"` prefix can optionally +#' be dropped if `fun` is specified as a string. #' pp_check.default <- function(object, yrep, fun, ...) { if (is.character(fun) && substr(fun, 1, 4) != "ppc_") diff --git a/R/ppc-discrete.R b/R/ppc-discrete.R index c8e749683..2815ff573 100644 --- a/R/ppc-discrete.R +++ b/R/ppc-discrete.R @@ -1,67 +1,65 @@ #' PPCs for discrete outcomes #' -#' Many of the \link{PPC} functions in \pkg{bayesplot} can +#' Many of the [PPC][PPC-overview] functions in **bayesplot** can #' be used with discrete data. The small subset of these functions that can -#' \emph{only} be used if \code{y} and \code{yrep} are discrete are documented +#' *only* be used if `y` and `yrep` are discrete are documented #' on this page. Currently these include rootograms for count outcomes and bar #' plots for ordinal, categorical, and multinomial outcomes. See the -#' \strong{Plot Descriptions} section below. +#' **Plot Descriptions** section below. #' #' @name PPC-discrete #' @family PPCs #' #' @template args-y-yrep #' @param ... Currently unused. -#' @param prob A value between 0 and 1 indicating the desired probability mass -#' to include in the \code{yrep} intervals. Set \code{prob=0} to -#' remove the intervals. For \code{ppc_rootogram} these are intervals -#' of the \emph{square roots} of the expected counts. -#' @param width For \code{ppc_bars} and \code{ppc_bars_grouped}, -#' passed to \code{\link[ggplot2]{geom_bar}} to control the bar width. -#' @param size,fatten For \code{ppc_bars} and \code{ppc_bars_grouped}, -#' \code{size} and \code{fatten} are passed to -#' \code{\link[ggplot2]{geom_pointrange}} to control the appearance of the -#' \code{yrep} points and intervals. For \code{ppc_rootogram} \code{size} is -#' passed to \code{\link[ggplot2]{geom_line}}. -#' @param freq For \code{ppc_bars} and \code{ppc_bars_grouped}, if \code{TRUE} -#' (the default) the y-axis will display counts. Setting \code{freq=FALSE} -#' will put proportions on the y-axis. +#' @param prob A value between `0` and `1` indicating the desired probability +#' mass to include in the `yrep` intervals. Set `prob=0` to remove the +#' intervals. For `ppc_rootogram()` these are intervals of the *square roots* +#' of the expected counts. +#' @param width For `ppc_bars()` and `ppc_bars_grouped()`, passed to +#' [ggplot2::geom_bar()] to control the bar width. +#' @param size,fatten For `ppc_bars()` and `ppc_bars_grouped()`, `size` and +#' `fatten` are passed to [ggplot2::geom_pointrange()] to control the +#' appearance of the `yrep` points and intervals. For `ppc_rootogram()` `size` +#' is passed to [ggplot2::geom_line()]. +#' @param freq For `ppc_bars()` and `ppc_bars_grouped()`, if `TRUE` (the +#' default) the y-axis will display counts. Setting `freq=FALSE` will put +#' proportions on the y-axis. #' #' #' @template return-ggplot #' -#' @details For all of these plots \code{y} and \code{yrep} must be -#' integers, although they need not be integers in the strict sense -#' of \R's \code{\link{integer}} type. For rootogram plots \code{y} -#' and \code{yrep} must also be non-negative. +#' @details For all of these plots `y` and `yrep` must be integers, although +#' they need not be integers in the strict sense of \R's +#' [integer][base::integer] type. For rootogram plots `y` and `yrep` must also +#' be non-negative. #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{ppc_bars}}{ -#' Bar plot of \code{y} with \code{yrep} medians and uncertainty intervals +#' \item{`ppc_bars()`}{ +#' Bar plot of `y` with `yrep` medians and uncertainty intervals #' superimposed on the bars. #' } -#' \item{\code{ppc_bars_grouped}}{ -#' Same as \code{ppc_bars} but a separate plot (facet) is generated for each +#' \item{`ppc_bars_grouped()`}{ +#' Same as `ppc_bars()` but a separate plot (facet) is generated for each #' level of a grouping variable. #' } -#' \item{\code{ppc_rootogram}}{ +#' \item{`ppc_rootogram()`}{ #' Rootograms allow for diagnosing problems in count data models such as -#' overdispersion or excess zeros. They consist of a histogram of \code{y} -#' with the expected counts based on \code{yrep} overlaid as a line along with -#' uncertainty intervals. The y-axis represents the square roots of the counts -#' to approximately adjust for scale differences and thus ease comparison -#' between observed and expected counts. Using the \code{style} argument, the -#' histogram style can be adjusted to focus on different aspects of the data: -#' \itemize{ -#' \item \emph{Standing}: basic histogram of observed counts with curve +#' overdispersion or excess zeros. They consist of a histogram of `y` with the +#' expected counts based on `yrep` overlaid as a line along with uncertainty +#' intervals. The y-axis represents the square roots of the counts to +#' approximately adjust for scale differences and thus ease comparison between +#' observed and expected counts. Using the `style` argument, the histogram +#' style can be adjusted to focus on different aspects of the data: +#' * _Standing_: basic histogram of observed counts with curve #' showing expected counts. -#' \item \emph{Hanging}: observed counts counts hanging from the curve +#' * _Hanging_: observed counts counts hanging from the curve #' representing expected counts. -#' \item \emph{Suspended}: histogram of the differences between expected and +#' * _Suspended_: histogram of the differences between expected and #' observed counts. -#' } -#' \strong{All of these are plotted on the square root scale}. See Kleiber and +#' +#' **All of these are plotted on the square root scale**. See Kleiber and #' Zeileis (2016) for advice on interpreting rootograms and selecting among #' the different styles. #' } @@ -137,8 +135,8 @@ ppc_bars <- #' @rdname PPC-discrete #' @export #' @template args-group -#' @param facet_args An optional list of arguments (other than \code{facets}) -#' passed to \code{\link[ggplot2]{facet_wrap}} to control faceting. +#' @param facet_args An optional list of arguments (other than `facets`) +#' passed to [ggplot2::facet_wrap()] to control faceting. ppc_bars_grouped <- function(y, yrep, @@ -180,15 +178,16 @@ ppc_bars_grouped <- #' @rdname PPC-discrete #' @export -#' @param style For \code{ppc_rootogram}, a string specifying the rootogram -#' style. The options are \code{"standing"}, \code{"hanging"}, and -#' \code{"suspended"}. See the \strong{Plot Descriptions} section, below, for +#' @param style For `ppc_rootogram`, a string specifying the rootogram +#' style. The options are `"standing"`, `"hanging"`, and +#' `"suspended"`. See the **Plot Descriptions** section, below, for #' details on the different styles. #' #' @references -#' Kleiber, C. and Zeileis, A. (2016). Visualizing count data regressions using -#' rootograms. \emph{The American Statistician}. 70(3): 296--303. -#' \url{https://arxiv.org/abs/1605.01311}. +#' Kleiber, C. and Zeileis, A. (2016). +#' Visualizing count data regressions using rootograms. +#' *The American Statistician*. 70(3): 296--303. +#' . #' #' @examples #' # rootograms for counts @@ -313,7 +312,7 @@ ppc_bars_yrep_data <- function(y, yrep, probs, freq = TRUE, group = NULL) { was_null_group <- FALSE } - # FIXME: double check and make sure that levels with zero counts are still plotted + # FIXME: make sure that levels with zero counts are still plotted yrep_data <- ppc_group_data(y, yrep, group = group, stat = NULL) %>% dplyr::filter(.data$variable != "y") %>% ungroup() %>% diff --git a/R/ppc-distributions.R b/R/ppc-distributions.R index f298d13d3..8235570cd 100644 --- a/R/ppc-distributions.R +++ b/R/ppc-distributions.R @@ -1,7 +1,7 @@ #' PPC distributions #' -#' Compare the empirical distribution of the data \code{y} to the distributions -#' of simulated/replicated data \code{yrep} from the posterior predictive +#' Compare the empirical distribution of the data `y` to the distributions +#' of simulated/replicated data `yrep` from the posterior predictive #' distribution. See the \strong{Plot Descriptions} section, below, #' for details. #' @@ -13,7 +13,7 @@ #' @template args-hist-freq #' @template args-dens #' @param size,alpha Passed to the appropriate geom to control the appearance of -#' the \code{yrep} distributions. +#' the `yrep` distributions. #' @param ... Currently unused. #' #' @template details-binomial @@ -21,30 +21,30 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{ppc_hist, ppc_freqpoly, ppc_dens, ppc_boxplot}}{ +#' \item{`ppc_hist, ppc_freqpoly, ppc_dens, ppc_boxplot`}{ #' A separate histogram, shaded frequency polygon, smoothed kernel density -#' estimate, or box and whiskers plot is displayed for \code{y} and each -#' dataset (row) in \code{yrep}. For these plots \code{yrep} should therefore +#' estimate, or box and whiskers plot is displayed for `y` and each +#' dataset (row) in `yrep`. For these plots `yrep` should therefore #' contain only a small number of rows. See the \strong{Examples} section. #' } -#' \item{\code{ppc_freqpoly_grouped}}{ +#' \item{`ppc_freqpoly_grouped`}{ #' A separate frequency polygon is plotted for each level of a grouping -#' variable for \code{y} and each dataset (row) in \code{yrep}. For this plot -#' \code{yrep} should therefore contain only a small number of rows. See the +#' variable for `y` and each dataset (row) in `yrep`. For this plot +#' `yrep` should therefore contain only a small number of rows. See the #' \strong{Examples} section. #' } -#' \item{\code{ppc_dens_overlay, ppc_ecdf_overlay}}{ +#' \item{`ppc_dens_overlay, ppc_ecdf_overlay`}{ #' Kernel density or empirical CDF estimates of each dataset (row) in -#' \code{yrep} are overlaid, with the distribution of \code{y} itself on top -#' (and in a darker shade). When using \code{ppc_ecdf_overlay} with discrete -#' data, set the \code{discrete} argument to \code{TRUE} for better results. -#' For an example of \code{ppc_dens_overlay} also see Gabry et al. (2019). +#' `yrep` are overlaid, with the distribution of `y` itself on top +#' (and in a darker shade). When using `ppc_ecdf_overlay` with discrete +#' data, set the `discrete` argument to `TRUE` for better results. +#' For an example of `ppc_dens_overlay` also see Gabry et al. (2019). #' } -#' \item{\code{ppc_violin_grouped}}{ -#' The density estimate of \code{yrep} within each level of a grouping +#' \item{`ppc_violin_grouped`}{ +#' The density estimate of `yrep` within each level of a grouping #' variable is plotted as a violin with horizontal lines at notable -#' quantiles. \code{y} is overlaid on the plot either as a violin, points, or -#' both, depending on the \code{y_draw} argument. +#' quantiles. `y` is overlaid on the plot either as a violin, points, or +#' both, depending on the `y_draw` argument. #' } #' } #' @@ -150,8 +150,8 @@ ppc_hist <- function(y, yrep, ..., binwidth = NULL, breaks = NULL, #' @rdname PPC-distributions #' @export -#' @param notch A logical scalar passed to \code{\link[ggplot2]{geom_boxplot}}. -#' Unlike for \code{geom_boxplot}, the default is \code{notch=TRUE}. +#' @param notch A logical scalar passed to [ggplot2::geom_boxplot()]. +#' Unlike for `geom_boxplot`, the default is `notch=TRUE`. #' ppc_boxplot <- function(y, yrep, ..., notch = TRUE, size = 0.5, alpha = 1) { check_ignored_arguments(...) @@ -321,11 +321,11 @@ ppc_dens_overlay <- function(y, yrep, ..., #' @export #' @rdname PPC-distributions -#' @param discrete For \code{ppc_ecdf_overlay}, should the data be treated as -#' discrete? The default is \code{FALSE}, in which case \code{geom="line"} is -#' passed to \code{\link[ggplot2]{stat_ecdf}}. If \code{discrete} is set to -#' \code{TRUE} then \code{geom="step"} is used. -#' @param pad A logical scalar passed to \code{\link[ggplot2]{stat_ecdf}}. +#' @param discrete For `ppc_ecdf_overlay`, should the data be treated as +#' discrete? The default is `FALSE`, in which case `geom="line"` is +#' passed to [ggplot2::stat_ecdf()]. If `discrete` is set to +#' `TRUE` then `geom="step"` is used. +#' @param pad A logical scalar passed to [ggplot2::stat_ecdf()]. ppc_ecdf_overlay <- function(y, yrep, @@ -371,18 +371,18 @@ ppc_ecdf_overlay <- #' @export #' @rdname PPC-distributions -#' @param probs A numeric vector passed to \code{\link[ggplot2]{geom_violin}}'s -#' \code{draw_quantiles} argument to specify at which quantiles to draw -#' horizontal lines. Set to \code{NULL} to remove the lines. -#' @param y_draw For \code{ppc_violin_grouped}, a string specifying how to draw -#' \code{y}: \code{"violin"} (default), \code{"points"} (jittered points), or -#' \code{"both"}. -#' @param y_jitter,y_size,y_alpha For \code{ppc_violin_grouped}, if -#' \code{y_draw} is \code{"points"} or \code{"both"} then \code{y_size}, -#' \code{y_alpha}, and \code{y_jitter} are passed to to the \code{size}, -#' \code{alpha}, and \code{width} arguments of -#' \code{\link[ggplot2]{geom_jitter}} to control the appearance of \code{y} -#' points. The default of \code{y_jitter=NULL} will let \pkg{ggplot2} +#' @param probs A numeric vector passed to [ggplot2::geom_violin()]'s +#' `draw_quantiles` argument to specify at which quantiles to draw +#' horizontal lines. Set to `NULL` to remove the lines. +#' @param y_draw For `ppc_violin_grouped`, a string specifying how to draw +#' `y`: `"violin"` (default), `"points"` (jittered points), or +#' `"both"`. +#' @param y_jitter,y_size,y_alpha For `ppc_violin_grouped`, if +#' `y_draw` is `"points"` or `"both"` then `y_size`, +#' `y_alpha`, and `y_jitter` are passed to to the `size`, +#' `alpha`, and `width` arguments of +#' [ggplot2::geom_jitter()] to control the appearance of `y` +#' points. The default of `y_jitter=NULL` will let \pkg{ggplot2} #' determine the amount of jitter. #' ppc_violin_grouped <- function(y, yrep, group, ..., probs = c(0.1, 0.5, 0.9), diff --git a/R/ppc-errors.R b/R/ppc-errors.R index cc225e862..2ca02a4aa 100644 --- a/R/ppc-errors.R +++ b/R/ppc-errors.R @@ -1,6 +1,6 @@ #' PPC errors #' -#' Various plots of predictive errors \code{y} - \code{yrep}. See the +#' Various plots of predictive errors `y` - `yrep`. See the #' \strong{Details} and \strong{Plot Descriptions} sections, below. #' #' @name PPC-errors @@ -9,57 +9,57 @@ #' @template args-y-yrep #' @param ... Currently unused. #' @param size,alpha For scatterplots, arguments passed to -#' \code{\link[ggplot2]{geom_point}} to control the appearance of the +#' [ggplot2::geom_point()] to control the appearance of the #' points. For the binned error plot, arguments controlling the size of #' the outline and opacity of the shaded region indicating the 2-SE bounds. #' #' @details -#' All of these functions (aside from the \code{*_scatter_avg} functions) -#' compute and plot predictive errors for each row of the matrix \code{yrep}, so -#' it is usually a good idea for \code{yrep} to contain only a small number of +#' All of these functions (aside from the `*_scatter_avg` functions) +#' compute and plot predictive errors for each row of the matrix `yrep`, so +#' it is usually a good idea for `yrep` to contain only a small number of #' draws (rows). See \strong{Examples}, below. #' -#' For binomial and Bernoulli data the \code{ppc_error_binned} function can be +#' For binomial and Bernoulli data the `ppc_error_binned` function can be #' used to generate binned error plots. Bernoulli data can be input as a vector -#' of 0s and 1s, whereas for binomial data \code{y} and \code{yrep} should +#' of 0s and 1s, whereas for binomial data `y` and `yrep` should #' contain "success" proportions (not counts). See the \strong{Examples} #' section, below. #' #' @section Plot descriptions: #' \describe{ -#' \item{\code{ppc_error_hist}}{ +#' \item{`ppc_error_hist`}{ #' A separate histogram is plotted for the predictive errors computed from -#' \code{y} and each dataset (row) in \code{yrep}. For this plot \code{yrep} +#' `y` and each dataset (row) in `yrep`. For this plot `yrep` #' should have only a small number of rows. #' } -#' \item{\code{ppc_error_hist_grouped}}{ -#' Like \code{ppc_error_hist}, except errors are computed within levels of a +#' \item{`ppc_error_hist_grouped`}{ +#' Like `ppc_error_hist`, except errors are computed within levels of a #' grouping variable. The number of histograms is therefore equal to the -#' product of the number of rows in \code{yrep} and the number of groups -#' (unique values of \code{group}). +#' product of the number of rows in `yrep` and the number of groups +#' (unique values of `group`). #' } -#' \item{\code{ppc_error_scatter}}{ -#' A separate scatterplot is displayed for \code{y} vs. the predictive errors -#' computed from \code{y} and each dataset (row) in \code{yrep}. For this -#' plot \code{yrep} should have only a small number of rows. +#' \item{`ppc_error_scatter`}{ +#' A separate scatterplot is displayed for `y` vs. the predictive errors +#' computed from `y` and each dataset (row) in `yrep`. For this +#' plot `yrep` should have only a small number of rows. #' } -#' \item{\code{ppc_error_scatter_avg}}{ -#' A single scatterplot of \code{y} vs. the average of the errors computed -#' from \code{y} and each dataset (row) in \code{yrep}. For each individual -#' data point \code{y[n]} the average error is the average of the -#' errors for \code{y[n]} computed over the the draws from the posterior +#' \item{`ppc_error_scatter_avg`}{ +#' A single scatterplot of `y` vs. the average of the errors computed +#' from `y` and each dataset (row) in `yrep`. For each individual +#' data point `y[n]` the average error is the average of the +#' errors for `y[n]` computed over the the draws from the posterior #' predictive distribution. #' } -#' \item{\code{ppc_error_scatter_avg_vs_x}}{ -#' Same as \code{ppc_error_scatter_avg}, except the average is plotted on the -#' \eqn{y}-axis and a a predictor variable \code{x} is plotted on the +#' \item{`ppc_error_scatter_avg_vs_x`}{ +#' Same as `ppc_error_scatter_avg`, except the average is plotted on the +#' \eqn{y}-axis and a a predictor variable `x` is plotted on the #' \eqn{x}-axis. #' } -#' \item{\code{ppc_error_binned}}{ +#' \item{`ppc_error_binned`}{ #' Intended for use with binomial data. A separate binned error plot (similar -#' to \code{arm::binnedplot}) is generated for each dataset (row) in -#' \code{yrep}. For this plot \code{y} and \code{yrep} should contain -#' proportions rather than counts, and \code{yrep} should have only a small +#' to `arm::binnedplot`) is generated for each dataset (row) in +#' `yrep`. For this plot `y` and `yrep` should contain +#' proportions rather than counts, and `yrep` should have only a small #' number of rows. #' } #' } @@ -282,7 +282,7 @@ ppc_error_scatter_avg <- #' @rdname PPC-errors #' @export -#' @param x A numeric vector the same length as \code{y} to use as the x-axis +#' @param x A numeric vector the same length as `y` to use as the x-axis #' variable. #' ppc_error_scatter_avg_vs_x <- @@ -311,7 +311,7 @@ ppc_error_scatter_avg_vs_x <- #' @rdname PPC-errors #' @export -#' @param bins For \code{ppc_error_binned}, the number of bins to use (approximately). +#' @param bins For `ppc_error_binned`, the number of bins to use (approximately). ppc_error_binned <- function(y, yrep, ..., bins = NULL, size = 1, alpha = 0.25) { check_ignored_arguments(...) diff --git a/R/ppc-intervals.R b/R/ppc-intervals.R index 2a50440c2..20db9c2c6 100644 --- a/R/ppc-intervals.R +++ b/R/ppc-intervals.R @@ -1,6 +1,6 @@ #' PPC intervals #' -#' Medians and central interval estimates of \code{yrep} with \code{y} overlaid. +#' Medians and central interval estimates of `yrep` with `y` overlaid. #' See the \strong{Plot Descriptions} section, below. #' #' @name PPC-intervals @@ -8,15 +8,15 @@ #' #' @template args-y-yrep #' @template args-prob-prob_outer -#' @param x A numeric vector the same length as \code{y} to use as the x-axis -#' variable. For example, \code{x} could be a predictor variable from a -#' regression model, a time variable for time-series models, etc. If \code{x} -#' is missing or NULL, then \code{1:length(y)} is used for the x-axis. +#' @param x A numeric vector the same length as `y` to use as the x-axis +#' variable. For example, `x` could be a predictor variable from a +#' regression model, a time variable for time-series models, etc. If `x` +#' is missing or NULL, then `1:length(y)` is used for the x-axis. #' @param ... Currently unused. #' @param alpha,size,fatten Arguments passed to geoms. For ribbon plots -#' \code{alpha} and \code{size} are passed to -#' \code{\link[ggplot2]{geom_ribbon}}. For interval plots \code{size} and -#' \code{fatten} are passed to \code{\link[ggplot2]{geom_pointrange}}. +#' `alpha` and `size` are passed to +#' [ggplot2::geom_ribbon()]. For interval plots `size` and +#' `fatten` are passed to [ggplot2::geom_pointrange()]. #' #' @template return-ggplot-or-data #' @@ -25,21 +25,21 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{ppc_intervals, ppc_ribbon}}{ -#' \code{100*prob}\% central intervals for \code{yrep} at each \code{x} -#' value. \code{ppc_intervals} plots intervals as vertical bars with points -#' indicating \code{yrep} medians and darker points indicating observed -#' \code{y} values. \code{ppc_ribbon} plots a ribbon of connected intervals -#' with a line through the median of \code{yrep} and a darker line connecting -#' observed \code{y} values. In both cases an optional \code{x} variable can +#' \item{`ppc_intervals, ppc_ribbon`}{ +#' `100*prob`\% central intervals for `yrep` at each `x` +#' value. `ppc_intervals` plots intervals as vertical bars with points +#' indicating `yrep` medians and darker points indicating observed +#' `y` values. `ppc_ribbon` plots a ribbon of connected intervals +#' with a line through the median of `yrep` and a darker line connecting +#' observed `y` values. In both cases an optional `x` variable can #' also be specified for the x-axis variable. #' #' Depending on the number of observations and the variability in the -#' predictions at different values of \code{x}, one or the other of these +#' predictions at different values of `x`, one or the other of these #' plots may be easier to read than the other. #' } -#' \item{\code{ppc_intervals_grouped, ppc_ribbon_grouped}}{ -#' Same as \code{ppc_intervals} and \code{ppc_ribbon}, respectively, but a +#' \item{`ppc_intervals_grouped, ppc_ribbon_grouped`}{ +#' Same as `ppc_intervals` and `ppc_ribbon`, respectively, but a #' separate plot (facet) is generated for each level of a grouping variable. #' } #' } @@ -134,8 +134,8 @@ ppc_intervals <- function(y, yrep, x = NULL, ..., prob = 0.5, prob_outer = 0.9, #' @rdname PPC-intervals #' @export #' @template args-group -#' @param facet_args An optional list of arguments (other than \code{facets}) -#' passed to \code{\link[ggplot2]{facet_wrap}} to control faceting. +#' @param facet_args An optional list of arguments (other than `facets`) +#' passed to [ggplot2::facet_wrap()] to control faceting. #' ppc_intervals_grouped <- function(y, yrep, diff --git a/R/ppc-loo.R b/R/ppc-loo.R index 18ab09b1b..afbfe7741 100644 --- a/R/ppc-loo.R +++ b/R/ppc-loo.R @@ -9,22 +9,22 @@ #' @template args-y-yrep #' @param ... Currently unused. #' @param lw A matrix of (smoothed) log weights with the same dimensions as -#' \code{yrep}. See \code{\link[loo]{psis}} and the associated \code{weights} +#' `yrep`. See [loo::psis()] and the associated `weights` #' method and the \strong{Examples} section, below. #' @param alpha,size,fatten Arguments passed to code geoms to control plot -#' aesthetics. For \code{ppc_loo_pit_qq} and \code{ppc_loo_pit_overlay}, -#' \code{size} and \code{alpha} are passed to -#' \code{\link[ggplot2]{geom_point}} and \code{\link[ggplot2]{geom_density}}, -#' respectively. For \code{ppc_loo_intervals}, \code{size} and \code{fatten} -#' are passed to \code{\link[ggplot2]{geom_pointrange}}. For -#' \code{ppc_loo_ribbon}, \code{alpha} and \code{size} are passed to -#' \code{\link[ggplot2]{geom_ribbon}}. +#' aesthetics. For `ppc_loo_pit_qq` and `ppc_loo_pit_overlay`, +#' `size` and `alpha` are passed to +#' [ggplot2::geom_point()] and [ggplot2::geom_density()], +#' respectively. For `ppc_loo_intervals`, `size` and `fatten` +#' are passed to [ggplot2::geom_pointrange()]. For +#' `ppc_loo_ribbon`, `alpha` and `size` are passed to +#' [ggplot2::geom_ribbon()]. #' #' @template return-ggplot #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{ppc_loo_pit_overlay, ppc_loo_pit_qq}}{ +#' \item{`ppc_loo_pit_overlay, ppc_loo_pit_qq`}{ #' The calibration of marginal predictions can be assessed using probability #' integral transformation (PIT) checks. LOO improves the check by avoiding the #' double use of data. See the section on marginal predictive checks in Gelman @@ -32,25 +32,25 @@ #' example of using \pkg{bayesplot} for these checks. #' #' The LOO PIT values are asymptotically uniform (for continuous data) if the -#' model is calibrated. The \code{ppc_loo_pit_overlay} function creates a plot +#' model is calibrated. The `ppc_loo_pit_overlay` function creates a plot #' comparing the density of the LOO PITs (thick line) to the density estimates #' of many simulated data sets from the standard uniform distribution (thin #' lines). See Gabry et al. (2019) for an example of interpreting the shape of #' the miscalibration that can be observed in these plots. #' -#' The \code{ppc_loo_pit_qq} function provides an alternative visualization of +#' The `ppc_loo_pit_qq` function provides an alternative visualization of #' the miscalibration with a quantile-quantile (Q-Q) plot comparing the LOO #' PITs to the standard uniform distribution. Comparing to the uniform is not #' good for extreme probabilities close to 0 and 1, so it can sometimes be -#' useful to set the \code{compare} argument to \code{"normal"}, which will +#' useful to set the `compare` argument to `"normal"`, which will #' produce a Q-Q plot comparing standardized PIT values to the standard normal #' distribution that can help see the (mis)calibration better for the extreme #' values. However, in most cases we have found that the overlaid density plot -#' (\code{ppc_loo_pit_overlay}) function will provided a clearer picture of +#' (`ppc_loo_pit_overlay`) function will provided a clearer picture of #' calibration problems that the Q-Q plot. #' } -#' \item{\code{ppc_loo_intervals, ppc_loo_ribbon}}{ -#' Similar to \code{\link{ppc_intervals}} and \code{\link{ppc_ribbon}} but the +#' \item{`ppc_loo_intervals, ppc_loo_ribbon`}{ +#' Similar to [ppc_intervals()] and [ppc_ribbon()] but the #' intervals are for the LOO predictive distribution. #' } #' } @@ -102,22 +102,22 @@ NULL #' @rdname PPC-loo #' @export -#' @param pit For \code{ppc_loo_pit_overlay} and \code{ppc_loo_pit_qq}, +#' @param pit For `ppc_loo_pit_overlay` and `ppc_loo_pit_qq`, #' optionally a vector of precomputed PIT values that can be specified instead -#' of \code{y}, \code{yrep}, and \code{lw} (these are all ignored if -#' \code{pit} is specified). If not specified the PIT values are computed +#' of `y`, `yrep`, and `lw` (these are all ignored if +#' `pit` is specified). If not specified the PIT values are computed #' internally before plotting. -#' @param samples For \code{ppc_loo_pit_overlay}, the number of data sets (each -#' the same size as \code{y}) to simulate from the standard uniform +#' @param samples For `ppc_loo_pit_overlay`, the number of data sets (each +#' the same size as `y`) to simulate from the standard uniform #' distribution. The default is 100. The density estimate of each dataset is #' plotted as a thin line in the plot, with the density estimate of the LOO #' PITs overlaid as a thicker dark line. -#' @param compare For \code{ppc_loo_pit_qq}, a string that can be either -#' \code{"uniform"} or \code{"normal"}. If \code{"uniform"} (the default) the +#' @param compare For `ppc_loo_pit_qq`, a string that can be either +#' `"uniform"` or `"normal"`. If `"uniform"` (the default) the #' Q-Q plot compares computed PIT values to the standard uniform distribution. -#' If \code{compare="normal"}, the Q-Q plot compares standardized PIT values +#' If `compare="normal"`, the Q-Q plot compares standardized PIT values #' to the standard normal distribution. -#' @param trim Passed to \code{\link[ggplot2]{stat_density}}. +#' @param trim Passed to [ggplot2::stat_density()]. #' @template args-density-controls ppc_loo_pit_overlay <- function(y, yrep, lw, pit, samples = 100, ..., size = 0.25, alpha = 0.7, trim = FALSE, @@ -259,30 +259,30 @@ ppc_loo_pit <- #' @rdname PPC-loo #' @export #' @template args-prob-prob_outer -#' @param psis_object If using \pkg{loo} version \code{2.0.0} or greater, an -#' object returned by the \code{psis} function (or by the \code{loo} function -#' with argument \code{save_psis} set to \code{TRUE}). -#' @param intervals For \code{ppc_loo_intervals} and \code{ppc_loo_ribbon}, +#' @param psis_object If using \pkg{loo} version `2.0.0` or greater, an +#' object returned by the `psis` function (or by the `loo` function +#' with argument `save_psis` set to `TRUE`). +#' @param intervals For `ppc_loo_intervals` and `ppc_loo_ribbon`, #' optionally a matrix of precomputed LOO predictive intervals -#' that can be specified instead of \code{yrep} and \code{lw} (these are both -#' ignored if \code{intervals} is specified). If not specified the intervals -#' are computed internally before plotting. If specified, \code{intervals} +#' that can be specified instead of `yrep` and `lw` (these are both +#' ignored if `intervals` is specified). If not specified the intervals +#' are computed internally before plotting. If specified, `intervals` #' must be a matrix with number of rows equal to the number of data points and #' five columns in the following order: lower outer interval, lower inner #' interval, median (50\%), upper inner interval and upper outer interval #' (column names are ignored). -#' @param order For \code{ppc_loo_intervals}, a string indicating how to arrange -#' the plotted intervals. The default (\code{"index"}) is to plot them in the -#' order of the observations. The alternative (\code{"median"}) arranges them +#' @param order For `ppc_loo_intervals`, a string indicating how to arrange +#' the plotted intervals. The default (`"index"`) is to plot them in the +#' order of the observations. The alternative (`"median"`) arranges them #' by median value from smallest (left) to largest (right). -#' @param subset For \code{ppc_loo_intervals} and \code{ppc_loo_ribbon}, an -#' optional integer vector indicating which observations in \code{y} (and -#' \code{yrep}) to include. Dropping observations from \code{y} and -#' \code{yrep} manually before passing them to the plotting function will not +#' @param subset For `ppc_loo_intervals` and `ppc_loo_ribbon`, an +#' optional integer vector indicating which observations in `y` (and +#' `yrep`) to include. Dropping observations from `y` and +#' `yrep` manually before passing them to the plotting function will not #' work because the dimensions will not match up with the dimensions of -#' \code{psis_object}, but if all of \code{y} and \code{yrep} are passed along -#' with \code{subset} then \pkg{bayesplot} can do the subsetting internally -#' for \code{y}, \code{yrep} \emph{and} \code{psis_object}. +#' `psis_object`, but if all of `y` and `yrep` are passed along +#' with `subset` then \pkg{bayesplot} can do the subsetting internally +#' for `y`, `yrep` *and* `psis_object`. #' See the \strong{Examples} section for a demonstration. #' ppc_loo_intervals <- diff --git a/R/ppc-overview.R b/R/ppc-overview.R index 2084c8bfc..18c918207 100644 --- a/R/ppc-overview.R +++ b/R/ppc-overview.R @@ -19,7 +19,7 @@ #' #' \subsection{Posterior predictive distribution}{ #' To generate the data used for posterior predictive checks we simulate from -#' the \emph{posterior predictive distribution}. The posterior predictive +#' the *posterior predictive distribution*. The posterior predictive #' distribution is the distribution of the outcome variable implied by a model #' after using the observed data \eqn{y} (a vector of outcome values), and #' typically predictors \eqn{X}, to update our beliefs about the unknown @@ -37,7 +37,7 @@ #' the same values of the predictors \eqn{X} that we used when fitting the model #' or new observations of those predictors. When we use the same values of #' \eqn{X} we denote the resulting simulations by \eqn{y^{rep}}{yrep} as they -#' can be thought of as \emph{replications} of the outcome \eqn{y} rather than +#' can be thought of as *replications* of the outcome \eqn{y} rather than #' predictions for future observations. This corresponds to the notation from #' Gelman et. al. (2013) and is the notation used throughout the documentation #' for this package. @@ -58,32 +58,32 @@ #' \describe{ #' \item{\strong{\link[=PPC-distributions]{Distributions}}}{ #' Histograms, kernel density estimates, boxplots, and other plots comparing -#' the empirical distribution of the observed data \code{y} to the -#' distributions of individual replicated datasets (rows) in \code{yrep}. +#' the empirical distribution of the observed data `y` to the +#' distributions of individual replicated datasets (rows) in `yrep`. #' } #' \item{\strong{\link[=PPC-test-statistics]{Test statistics}}}{ #' The distribution of a test statistic, or a pair of test statistics, over -#' the replicated datasets (rows) in \code{yrep} compared to value of the -#' statistic(s) computed from \code{y}. +#' the replicated datasets (rows) in `yrep` compared to value of the +#' statistic(s) computed from `y`. #' } #' \item{\strong{\link[=PPC-intervals]{Intervals}}}{ -#' Interval estimates of \code{yrep} with \code{y} overlaid. The x-axis +#' Interval estimates of `yrep` with `y` overlaid. The x-axis #' variable can be optionally specified by the user (e.g. to plot against #' against a predictor variable or over time). #' } #' \item{\strong{\link[=PPC-errors]{Predictive errors}}}{ -#' Plots of predictive errors (\code{y - yrep}) computed from \code{y} and -#' replicated datasets (rows) in \code{yrep}. For binomial models binned +#' Plots of predictive errors (`y - yrep`) computed from `y` and +#' replicated datasets (rows) in `yrep`. For binomial models binned #' error plots are also available. #' } #' \item{\strong{\link[=PPC-scatterplots]{Scatterplots}}}{ -#' Scatterplots (and similar visualizations) of the observed data \code{y} -#' vs. individual replicated datasets (rows) in \code{yrep}, or vs. the +#' Scatterplots (and similar visualizations) of the observed data `y` +#' vs. individual replicated datasets (rows) in `yrep`, or vs. the #' average value of the distributions of each data point (columns) in -#' \code{yrep}. +#' `yrep`. #' } #' \item{\strong{\link[=PPC-discrete]{Plots for discrete outcomes}}}{ -#' PPC functions that can only be used if \code{y} and \code{yrep} are +#' PPC functions that can only be used if `y` and `yrep` are #' discrete. For example, rootograms for count outcomes and bar #' plots for ordinal, categorical, and multinomial outcomes. #' } @@ -96,11 +96,11 @@ #' @section Providing an interface for posterior predictive checking from another package: #' #' In addition to the various plotting functions, the \pkg{bayesplot} package -#' provides the S3 generic \code{\link{pp_check}}. Authors of \R packages for -#' Bayesian inference are encouraged to define \code{pp_check} methods for the +#' provides the S3 generic [pp_check()]. Authors of \R packages for +#' Bayesian inference are encouraged to define `pp_check` methods for the #' fitted model objects created by their packages. See the package vignettes for #' more details and a simple example, and see the \pkg{rstanarm} and \pkg{brms} -#' packages for full examples of \code{pp_check} methods. +#' packages for full examples of `pp_check` methods. #' #' @template reference-vis-paper #' @templateVar bdaRef (Ch. 6) diff --git a/R/ppc-scatterplots.R b/R/ppc-scatterplots.R index f6c7faa91..45e321073 100644 --- a/R/ppc-scatterplots.R +++ b/R/ppc-scatterplots.R @@ -1,7 +1,7 @@ #' PPC scatterplots #' -#' Scatterplots of the observed data \code{y} vs. simulated/replicated data -#' \code{yrep} from the posterior predictive distribution. See the \strong{Plot +#' Scatterplots of the observed data `y` vs. simulated/replicated data +#' `yrep` from the posterior predictive distribution. See the \strong{Plot #' Descriptions} and \strong{Details} sections, below. #' #' @name PPC-scatterplots @@ -9,7 +9,7 @@ #' #' @template args-y-yrep #' @param ... Currently unused. -#' @param size,alpha Arguments passed to \code{\link[ggplot2]{geom_point}} to +#' @param size,alpha Arguments passed to [ggplot2::geom_point()] to #' control the appearance of the points. #' #' @template details-binomial @@ -20,18 +20,18 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{ppc_scatter}}{ -#' For each dataset (row) in \code{yrep} a scatterplot is generated showing -#' \code{y} against that row of \code{yrep}. For this plot \code{yrep} should +#' \item{`ppc_scatter`}{ +#' For each dataset (row) in `yrep` a scatterplot is generated showing +#' `y` against that row of `yrep`. For this plot `yrep` should #' only contain a small number of rows. #' } -#' \item{\code{ppc_scatter_avg}}{ -#' A scatterplot of \code{y} against the average values of \code{yrep}, i.e., -#' the points \code{(mean(yrep[, n]), y[n])}, where each \code{yrep[, n]} is +#' \item{`ppc_scatter_avg`}{ +#' A scatterplot of `y` against the average values of `yrep`, i.e., +#' the points `(mean(yrep[, n]), y[n])`, where each `yrep[, n]` is #' a vector of length equal to the number of posterior draws. #' } -#' \item{\code{ppc_scatter_avg_grouped}}{ -#' The same as \code{ppc_scatter_avg}, but a separate plot is generated for +#' \item{`ppc_scatter_avg_grouped`}{ +#' The same as `ppc_scatter_avg`, but a separate plot is generated for #' each level of a grouping variable. #' } #' } diff --git a/R/ppc-test-statistics.R b/R/ppc-test-statistics.R index a036f62de..3d319efd3 100644 --- a/R/ppc-test-statistics.R +++ b/R/ppc-test-statistics.R @@ -1,8 +1,8 @@ #' PPC test statistics #' -#' The distribution of a test statistic \code{T(yrep)}, or a pair of test -#' statistics, over the simulated datasets in \code{yrep}, compared to the -#' observed value \code{T(y)} computed from the data \code{y}. See the +#' The distribution of a test statistic `T(yrep)`, or a pair of test +#' statistics, over the simulated datasets in `yrep`, compared to the +#' observed value `T(y)` computed from the data `y`. See the #' \strong{Plot Descriptions} and \strong{Details} sections, below, as #' well as \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)}. #' @@ -12,7 +12,7 @@ #' @template args-y-yrep #' @template args-facet_args #' @param stat A single function or a string naming a function, except for -#' \code{ppc_stat_2d} which requires a vector of exactly two functions or +#' `ppc_stat_2d` which requires a vector of exactly two functions or #' function names. In all cases the function(s) should take a vector input and #' return a scalar test statistic. If specified as a string (or strings) then #' the legend will display function names. If specified as a function (or @@ -28,23 +28,23 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{\code{ppc_stat}}{ +#' \item{`ppc_stat`}{ #' A histogram of the distribution of a test statistic computed by applying -#' \code{stat} to each dataset (row) in \code{yrep}. The value of the -#' statistic in the observed data, \code{stat(y)}, is overlaid as a vertical -#' line. More details on \code{ppc_stat} can be found in Gabry et al. +#' `stat` to each dataset (row) in `yrep`. The value of the +#' statistic in the observed data, `stat(y)`, is overlaid as a vertical +#' line. More details on `ppc_stat` can be found in Gabry et al. #' (2019). #' } -#' \item{\code{ppc_stat_grouped,ppc_stat_freqpoly_grouped}}{ -#' The same as \code{ppc_stat}, but a separate plot is generated for each +#' \item{`ppc_stat_grouped,ppc_stat_freqpoly_grouped`}{ +#' The same as `ppc_stat`, but a separate plot is generated for each #' level of a grouping variable. In the case of -#' \code{ppc_stat_freqpoly_grouped} the plots are frequency polygons rather -#' than histograms. More details on \code{ppc_stat_grouped} can be found in +#' `ppc_stat_freqpoly_grouped` the plots are frequency polygons rather +#' than histograms. More details on `ppc_stat_grouped` can be found in #' Gabry et al. (2019). #' } -#' \item{\code{ppc_stat_2d}}{ +#' \item{`ppc_stat_2d`}{ #' A scatterplot showing the joint distribution of two test statistics -#' computed over the datasets (rows) in \code{yrep}. The value of the +#' computed over the datasets (rows) in `yrep`. The value of the #' statistics in the observed data is overlaid as large point. #' } #' } @@ -245,7 +245,7 @@ ppc_stat_freqpoly_grouped <- #' @rdname PPC-test-statistics #' @export -#' @param size,alpha Arguments passed to \code{\link[ggplot2]{geom_point}} to +#' @param size,alpha Arguments passed to [ggplot2::geom_point()] to #' control the appearance of scatterplot points. ppc_stat_2d <- function(y, yrep, stat = c("mean", "sd"), ..., size = 2.5, alpha = 0.7) { diff --git a/man-roxygen/args-by_chain.R b/man-roxygen/args-by_chain.R index 76a57a266..10b49249b 100644 --- a/man-roxygen/args-by_chain.R +++ b/man-roxygen/args-by_chain.R @@ -1,2 +1,2 @@ #' @param by_chain A logical value indicating whether to plot each chain -#' separately (\code{TRUE}) or merge the chains (\code{FALSE}, the default). +#' separately (`TRUE`) or merge the chains (`FALSE`, the default). diff --git a/man-roxygen/args-dens.R b/man-roxygen/args-dens.R index 46239469a..ff893e11e 100644 --- a/man-roxygen/args-dens.R +++ b/man-roxygen/args-dens.R @@ -1 +1 @@ -#' @param trim A logical scalar passed to \code{\link[ggplot2]{geom_density}}. +#' @param trim A logical scalar passed to [ggplot2::geom_density()]. diff --git a/man-roxygen/args-density-controls.R b/man-roxygen/args-density-controls.R index e377c3ea8..e49d8610d 100644 --- a/man-roxygen/args-density-controls.R +++ b/man-roxygen/args-density-controls.R @@ -1,3 +1,3 @@ #' @param bw,adjust,kernel,n_dens Optional arguments passed to -#' \code{\link[stats]{density}} to override default kernel density estimation -#' parameters. \code{n_dens} defaults to 1024. +#' [stats::density()] to override default kernel density estimation +#' parameters. `n_dens` defaults to `1024`. diff --git a/man-roxygen/args-facet_args.R b/man-roxygen/args-facet_args.R index 6e6b46d2e..566739cde 100644 --- a/man-roxygen/args-facet_args.R +++ b/man-roxygen/args-facet_args.R @@ -1,3 +1,3 @@ -#' @param facet_args A named list of arguments (other than \code{facets}) passed -#' to \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} +#' @param facet_args A named list of arguments (other than `facets`) passed +#' to [ggplot2::facet_wrap()] or [ggplot2::facet_grid()] #' to control faceting. diff --git a/man-roxygen/args-group.R b/man-roxygen/args-group.R index 76fed7c4f..ad7fcf1ce 100644 --- a/man-roxygen/args-group.R +++ b/man-roxygen/args-group.R @@ -1,3 +1,3 @@ #' @param group A grouping variable (a vector or factor) the same length as -#' \code{y}. Each value in \code{group} is interpreted as the group level -#' pertaining to the corresponding value of \code{y}. +#' `y`. Each value in `group` is interpreted as the group level +#' pertaining to the corresponding value of `y`. diff --git a/man-roxygen/args-hist-freq.R b/man-roxygen/args-hist-freq.R index df566a9c7..9d232bd65 100644 --- a/man-roxygen/args-hist-freq.R +++ b/man-roxygen/args-hist-freq.R @@ -1,5 +1,5 @@ -#' @param freq For histograms, \code{freq=TRUE} (the default) puts count on the -#' y-axis. Setting \code{freq=FALSE} puts density on the y-axis. (For many +#' @param freq For histograms, `freq=TRUE` (the default) puts count on the +#' y-axis. Setting `freq=FALSE` puts density on the y-axis. (For many #' plots the y-axis text is off by default. To view the count or density -#' labels on the y-axis see the \code{\link{yaxis_text}} convenience +#' labels on the y-axis see the [yaxis_text()] convenience #' function.) diff --git a/man-roxygen/args-hist.R b/man-roxygen/args-hist.R index 031cd1876..a0b6358f2 100644 --- a/man-roxygen/args-hist.R +++ b/man-roxygen/args-hist.R @@ -1,6 +1,6 @@ -#' @param binwidth Passed to \code{\link[ggplot2]{geom_histogram}} to override +#' @param binwidth Passed to [ggplot2::geom_histogram()] to override #' the default binwidth. #' -#' @param breaks Passed to \code{\link[ggplot2]{geom_histogram}} as an -#' alternative to \code{binwidth}. +#' @param breaks Passed to [ggplot2::geom_histogram()] as an +#' alternative to `binwidth`. #' diff --git a/man-roxygen/args-mcmc-x.R b/man-roxygen/args-mcmc-x.R index 2b63aa4c9..47fe849ec 100644 --- a/man-roxygen/args-mcmc-x.R +++ b/man-roxygen/args-mcmc-x.R @@ -1,5 +1,5 @@ #' @param x A 3-D array, matrix, list of matrices, or data frame of MCMC draws. -#' The \link{MCMC-overview} page provides details on how to specify each these +#' The [MCMC-overview] page provides details on how to specify each these #' allowed inputs. It is also possible to use an object with an -#' \code{as.array} method that returns the same kind of 3-D array described on -#' the \link{MCMC-overview} page. +#' `as.array` method that returns the same kind of 3-D array described on +#' the [MCMC-overview] page. diff --git a/man-roxygen/args-pars.R b/man-roxygen/args-pars.R index fdbea7069..bea544f21 100644 --- a/man-roxygen/args-pars.R +++ b/man-roxygen/args-pars.R @@ -1,3 +1,3 @@ #' @param pars An optional character vector of parameter names. If neither -#' \code{pars} nor \code{regex_pars} is specified then the default is to use -#' \emph{all} parameters. +#' `pars` nor `regex_pars` is specified then the default is to use +#' **all** parameters. diff --git a/man-roxygen/args-prob-prob_outer.R b/man-roxygen/args-prob-prob_outer.R index bcde0734e..44186780a 100644 --- a/man-roxygen/args-prob-prob_outer.R +++ b/man-roxygen/args-prob-prob_outer.R @@ -1,3 +1,3 @@ #' @param prob,prob_outer Values between 0 and 1 indicating the desired #' probability mass to include in the inner and outer intervals. The defaults -#' are \code{prob=0.5} and \code{prob_outer=0.9}. +#' are `prob=0.5` and `prob_outer=0.9`. diff --git a/man-roxygen/args-regex_pars.R b/man-roxygen/args-regex_pars.R index 2e4ebd650..09f6120bd 100644 --- a/man-roxygen/args-regex_pars.R +++ b/man-roxygen/args-regex_pars.R @@ -1,3 +1,3 @@ -#' @param regex_pars An optional \link[=grep]{regular expression} to use for -#' parameter selection. Can be specified instead of \code{pars} or in addition -#' to \code{pars}. +#' @param regex_pars An optional [regular expression][base::grep] to use for +#' parameter selection. Can be specified instead of `pars` or in addition +#' to `pars`. diff --git a/man-roxygen/args-transformations.R b/man-roxygen/args-transformations.R index 170d8ed92..94262f944 100644 --- a/man-roxygen/args-transformations.R +++ b/man-roxygen/args-transformations.R @@ -1,21 +1,20 @@ #' @param transformations Optionally, transformations to apply to parameters -#' before plotting. If \code{transformations} is a function or a single string +#' before plotting. If `transformations` is a function or a single string #' naming a function then that function will be used to transform all #' parameters. To apply transformations to particular parameters, the -#' \code{transformations} argument can be a named list with length equal to +#' `transformations` argument can be a named list with length equal to #' the number of parameters to be transformed. Currently only univariate #' transformations of scalar parameters can be specified (multivariate #' transformations will be implemented in a future release). If -#' \code{transformations} is a list, the name of each list element should be a +#' `transformations` is a list, the name of each list element should be a #' parameter name and the content of each list element should be a function -#' (or any item to match as a function via \code{\link{match.fun}}, e.g. a +#' (or any item to match as a function via [match.fun()], e.g. a #' string naming a function). If a function is specified by its name as a -#' string (e.g. \code{"log"}), then it can be used to construct a new -#' parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). -#' If a function itself is specified (e.g. \code{log} or \code{function(x) -#' log(x)}) then \code{"t"} is used in the new parameter label to indicate -#' that the parameter is transformed (e.g. \code{"t(sigma)"}). +#' string (e.g. `"log"`), then it can be used to construct a new +#' parameter label for the appropriate parameter (e.g. `"log(sigma)"`). +#' If a function itself is specified (e.g. `log` or `function(x) +#' log(x)`) then `"t"` is used in the new parameter label to indicate +#' that the parameter is transformed (e.g. `"t(sigma)"`). #' -#' Note: due to partial argument matching \code{transformations} can be -#' abbreviated for convenience in interactive use (e.g., \code{transform}, -#' \code{trans}, etc.). +#' Note: due to partial argument matching `transformations` can be +#' abbreviated for convenience in interactive use (e.g., `transform`). diff --git a/man-roxygen/args-y-yrep.R b/man-roxygen/args-y-yrep.R index 96ac721c9..5c3a7ba53 100644 --- a/man-roxygen/args-y-yrep.R +++ b/man-roxygen/args-y-yrep.R @@ -1,8 +1,7 @@ -#' @param y A vector of observations. See \strong{Details}. +#' @param y A vector of observations. See **Details**. #' @param yrep An \eqn{S} by \eqn{N} matrix of draws from the posterior #' predictive distribution, where \eqn{S} is the size of the posterior sample -#' (or subset of the posterior sample used to generate \code{yrep}) and -#' \eqn{N} is the number of observations (the length of \code{y}). The columns -#' of \code{yrep} should be in the same order as the data points in \code{y} -#' for the plots to make sense. See \strong{Details} for additional -#' instructions. +#' (or subset of the posterior sample used to generate `yrep`) and \eqn{N} is +#' the number of observations (the length of `y`). The columns of `yrep` +#' should be in the same order as the data points in `y` for the plots to make +#' sense. See **Details** for additional instructions. diff --git a/man-roxygen/details-binomial.R b/man-roxygen/details-binomial.R index ebe394c8c..d49000e20 100644 --- a/man-roxygen/details-binomial.R +++ b/man-roxygen/details-binomial.R @@ -1,3 +1,3 @@ #' @details For Binomial data, the plots will typically be most useful if -#' \code{y} and \code{yrep} contain the "success" proportions (not discrete +#' `y` and `yrep` contain the "success" proportions (not discrete #' "success" or "failure" counts). diff --git a/man-roxygen/reference-bda.R b/man-roxygen/reference-bda.R index 6ef1cf8d1..21945bfeb 100644 --- a/man-roxygen/reference-bda.R +++ b/man-roxygen/reference-bda.R @@ -1,3 +1,3 @@ #' @references Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, -#' A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC +#' A., and Rubin, D. B. (2013). *Bayesian Data Analysis.* Chapman & Hall/CRC #' Press, London, third edition. <%= bdaRef %> diff --git a/man-roxygen/reference-betancourt.R b/man-roxygen/reference-betancourt.R index c12de9261..5716a0ff9 100644 --- a/man-roxygen/reference-betancourt.R +++ b/man-roxygen/reference-betancourt.R @@ -1,8 +1,8 @@ #' @references #' Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo. -#' \url{https://arxiv.org/abs/1701.02434} +#' #' #' Betancourt, M. and Girolami, M. (2013). Hamiltonian Monte Carlo for -#' hierarchical models. \url{https://arxiv.org/abs/1312.0906} +#' hierarchical models. #' diff --git a/man-roxygen/reference-loo.R b/man-roxygen/reference-loo.R index 2cac1cceb..d26497d6b 100644 --- a/man-roxygen/reference-loo.R +++ b/man-roxygen/reference-loo.R @@ -1,5 +1,5 @@ #' @references Vehtari, A., Gelman, A., and Gabry, J. (2017). Practical #' Bayesian model evaluation using leave-one-out cross-validation and WAIC. -#' \emph{Statistics and Computing}. 27(5), 1413--1432. +#' *Statistics and Computing*. 27(5), 1413--1432. #' doi:10.1007/s11222-016-9696-4. arXiv preprint: -#' \url{https://arxiv.org/abs/1507.04544/} +#' diff --git a/man-roxygen/reference-nuts.R b/man-roxygen/reference-nuts.R index e772a96a3..b09285fd7 100644 --- a/man-roxygen/reference-nuts.R +++ b/man-roxygen/reference-nuts.R @@ -1,3 +1,3 @@ #' @references Hoffman, M. D. and Gelman, A. (2014). The No-U-Turn Sampler: -#' adaptively setting path lengths in Hamiltonian Monte Carlo. \emph{Journal -#' of Machine Learning Research}. 15:1593--1623. +#' adaptively setting path lengths in Hamiltonian Monte Carlo. +#' *Journal of Machine Learning Research*. 15:1593--1623. diff --git a/man-roxygen/reference-stan-manual.R b/man-roxygen/reference-stan-manual.R index e760f0676..c01d5015b 100644 --- a/man-roxygen/reference-stan-manual.R +++ b/man-roxygen/reference-stan-manual.R @@ -1,2 +1,3 @@ -#' @references Stan Development Team. \emph{Stan Modeling Language Users -#' Guide and Reference Manual.} \url{https://mc-stan.org/users/documentation/} +#' @references Stan Development Team. +#' *Stan Modeling Language Users Guide and Reference Manual.* +#' diff --git a/man-roxygen/reference-vis-paper.R b/man-roxygen/reference-vis-paper.R index a63adfbfa..25598b502 100644 --- a/man-roxygen/reference-vis-paper.R +++ b/man-roxygen/reference-vis-paper.R @@ -1,6 +1,6 @@ #' @references Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and -#' Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. -#' Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, -#' (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, -#' \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, -#' \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +#' Gelman, A. (2019), Visualization in Bayesian workflow. +#' *J. R. Stat. Soc. A*, 182: 389-402. doi:10.1111/rssa.12378. +#' ([journal version](https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378), +#' [arXiv preprint](https://arxiv.org/abs/1709.01449), +#' [code on GitHub](https://github.com/jgabry/bayes-vis-paper)) diff --git a/man-roxygen/return-ggplot-or-data.R b/man-roxygen/return-ggplot-or-data.R index 29428007e..486ddd547 100644 --- a/man-roxygen/return-ggplot-or-data.R +++ b/man-roxygen/return-ggplot-or-data.R @@ -1,3 +1,3 @@ -#' @return A ggplot object that can be further customized using the -#' \pkg{ggplot2} package. The \code{_data} functions return the data that -#' would have been drawn by the plotting function. +#' @return A ggplot object that can be further customized using the **ggplot2** +#' package. The functions with suffix `_data` return the data that would have +#' been drawn by the plotting function. diff --git a/man-roxygen/return-ggplot.R b/man-roxygen/return-ggplot.R index 9f6c221d0..c71191e45 100644 --- a/man-roxygen/return-ggplot.R +++ b/man-roxygen/return-ggplot.R @@ -1,2 +1 @@ -#' @return A ggplot object that can be further customized using the -#' \pkg{ggplot2} package. +#' @return A ggplot object that can be further customized using the **ggplot2** package. diff --git a/man-roxygen/seealso-colors.R b/man-roxygen/seealso-colors.R index 010240352..0fe6de047 100644 --- a/man-roxygen/seealso-colors.R +++ b/man-roxygen/seealso-colors.R @@ -1,2 +1,2 @@ -#' @seealso \code{\link{bayesplot-colors}} to set or view the color scheme used +#' @seealso [bayesplot-colors] to set or view the color scheme used #' for plotting. diff --git a/man-roxygen/seealso-helpers.R b/man-roxygen/seealso-helpers.R index 294321e06..a53a6e7f0 100644 --- a/man-roxygen/seealso-helpers.R +++ b/man-roxygen/seealso-helpers.R @@ -1,3 +1,3 @@ -#' @seealso \link{bayesplot-helpers} for a variety of convenience functions, +#' @seealso [bayesplot-helpers] for a variety of convenience functions, #' many of which provide shortcuts for tweaking theme elements after creating #' a plot. diff --git a/man-roxygen/seealso-theme.R b/man-roxygen/seealso-theme.R index f69434c37..d26f263bf 100644 --- a/man-roxygen/seealso-theme.R +++ b/man-roxygen/seealso-theme.R @@ -1,2 +1,2 @@ -#' @seealso \code{\link{theme_default}} for the default ggplot theme used by -#' \pkg{bayesplot} and \code{\link{bayesplot_theme_set}} to change it. +#' @seealso [theme_default()] for the default ggplot theme used by +#' **bayesplot** and [bayesplot_theme_set()] to change it. From 25b33f923e0b5875c59166bfd3784bab95437929 Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 16 May 2019 00:31:05 -0400 Subject: [PATCH 2/8] use git grep and sed to do find and replace --- R/example-data.R | 2 +- R/mcmc-traces.R | 4 ++-- R/ppc-distributions.R | 8 ++++---- R/ppc-errors.R | 6 +++--- R/ppc-intervals.R | 2 +- R/ppc-loo.R | 10 +++++----- R/ppc-overview.R | 10 +++++----- R/ppc-scatterplots.R | 2 +- R/ppc-test-statistics.R | 2 +- 9 files changed, 23 insertions(+), 23 deletions(-) diff --git a/R/example-data.R b/R/example-data.R index 0187ab212..afca502c2 100644 --- a/R/example-data.R +++ b/R/example-data.R @@ -1,7 +1,7 @@ #' Example draws to use in demonstrations and tests #' #' These functions return various objects containing data used in the examples -#' throughout the \pkg{bayesplot} package documentation. +#' throughout the **bayesplot** package documentation. #' #' @name example-data #' @keywords internal diff --git a/R/mcmc-traces.R b/R/mcmc-traces.R index ae6bcc199..422f3336b 100644 --- a/R/mcmc-traces.R +++ b/R/mcmc-traces.R @@ -1,6 +1,6 @@ #' Trace plot (time series plot) of MCMC draws #' -#' Trace plot (or traceplot) of MCMC draws. See the \strong{Plot Descriptions} +#' Trace plot (or traceplot) of MCMC draws. See the **Plot Descriptions** #' section, below, for details. #' #' @name MCMC-traces @@ -35,7 +35,7 @@ #' [nuts_params()] or one with the same structure. If `np` is #' specified then tick marks are added to the bottom of the trace plot #' indicating within which iterations there was a divergence (if there were any). -#' See the end of the \strong{Examples} section, below. +#' See the end of the **Examples** section, below. #' @param np_style A call to the `trace_style_np` helper function to #' specify arguments controlling the appearance of tick marks representing #' divergences (if the `np` argument is specified). diff --git a/R/ppc-distributions.R b/R/ppc-distributions.R index 8235570cd..e5c077108 100644 --- a/R/ppc-distributions.R +++ b/R/ppc-distributions.R @@ -2,7 +2,7 @@ #' #' Compare the empirical distribution of the data `y` to the distributions #' of simulated/replicated data `yrep` from the posterior predictive -#' distribution. See the \strong{Plot Descriptions} section, below, +#' distribution. See the **Plot Descriptions** section, below, #' for details. #' #' @name PPC-distributions @@ -25,13 +25,13 @@ #' A separate histogram, shaded frequency polygon, smoothed kernel density #' estimate, or box and whiskers plot is displayed for `y` and each #' dataset (row) in `yrep`. For these plots `yrep` should therefore -#' contain only a small number of rows. See the \strong{Examples} section. +#' contain only a small number of rows. See the **Examples** section. #' } #' \item{`ppc_freqpoly_grouped`}{ #' A separate frequency polygon is plotted for each level of a grouping #' variable for `y` and each dataset (row) in `yrep`. For this plot #' `yrep` should therefore contain only a small number of rows. See the -#' \strong{Examples} section. +#' **Examples** section. #' } #' \item{`ppc_dens_overlay, ppc_ecdf_overlay`}{ #' Kernel density or empirical CDF estimates of each dataset (row) in @@ -382,7 +382,7 @@ ppc_ecdf_overlay <- #' `y_alpha`, and `y_jitter` are passed to to the `size`, #' `alpha`, and `width` arguments of #' [ggplot2::geom_jitter()] to control the appearance of `y` -#' points. The default of `y_jitter=NULL` will let \pkg{ggplot2} +#' points. The default of `y_jitter=NULL` will let **ggplot2** #' determine the amount of jitter. #' ppc_violin_grouped <- function(y, yrep, group, ..., probs = c(0.1, 0.5, 0.9), diff --git a/R/ppc-errors.R b/R/ppc-errors.R index 2ca02a4aa..ecb9275ea 100644 --- a/R/ppc-errors.R +++ b/R/ppc-errors.R @@ -1,7 +1,7 @@ #' PPC errors #' #' Various plots of predictive errors `y` - `yrep`. See the -#' \strong{Details} and \strong{Plot Descriptions} sections, below. +#' **Details** and **Plot Descriptions** sections, below. #' #' @name PPC-errors #' @family PPCs @@ -17,12 +17,12 @@ #' All of these functions (aside from the `*_scatter_avg` functions) #' compute and plot predictive errors for each row of the matrix `yrep`, so #' it is usually a good idea for `yrep` to contain only a small number of -#' draws (rows). See \strong{Examples}, below. +#' draws (rows). See **Examples**, below. #' #' For binomial and Bernoulli data the `ppc_error_binned` function can be #' used to generate binned error plots. Bernoulli data can be input as a vector #' of 0s and 1s, whereas for binomial data `y` and `yrep` should -#' contain "success" proportions (not counts). See the \strong{Examples} +#' contain "success" proportions (not counts). See the **Examples** #' section, below. #' #' @section Plot descriptions: diff --git a/R/ppc-intervals.R b/R/ppc-intervals.R index 20db9c2c6..21c10c605 100644 --- a/R/ppc-intervals.R +++ b/R/ppc-intervals.R @@ -1,7 +1,7 @@ #' PPC intervals #' #' Medians and central interval estimates of `yrep` with `y` overlaid. -#' See the \strong{Plot Descriptions} section, below. +#' See the **Plot Descriptions** section, below. #' #' @name PPC-intervals #' @family PPCs diff --git a/R/ppc-loo.R b/R/ppc-loo.R index afbfe7741..58b1925d5 100644 --- a/R/ppc-loo.R +++ b/R/ppc-loo.R @@ -1,6 +1,6 @@ #' LOO predictive checks #' -#' Leave-One-Out (LOO) predictive checks. See the \strong{Plot Descriptions} +#' Leave-One-Out (LOO) predictive checks. See the **Plot Descriptions** #' section, below, and \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et #' al. (2019)} for details. #' @@ -10,7 +10,7 @@ #' @param ... Currently unused. #' @param lw A matrix of (smoothed) log weights with the same dimensions as #' `yrep`. See [loo::psis()] and the associated `weights` -#' method and the \strong{Examples} section, below. +#' method and the **Examples** section, below. #' @param alpha,size,fatten Arguments passed to code geoms to control plot #' aesthetics. For `ppc_loo_pit_qq` and `ppc_loo_pit_overlay`, #' `size` and `alpha` are passed to @@ -29,7 +29,7 @@ #' integral transformation (PIT) checks. LOO improves the check by avoiding the #' double use of data. See the section on marginal predictive checks in Gelman #' et al. (2013, p. 152--153) and section 5 of Gabry et al. (2019) for an -#' example of using \pkg{bayesplot} for these checks. +#' example of using **bayesplot** for these checks. #' #' The LOO PIT values are asymptotically uniform (for continuous data) if the #' model is calibrated. The `ppc_loo_pit_overlay` function creates a plot @@ -281,9 +281,9 @@ ppc_loo_pit <- #' `yrep` manually before passing them to the plotting function will not #' work because the dimensions will not match up with the dimensions of #' `psis_object`, but if all of `y` and `yrep` are passed along -#' with `subset` then \pkg{bayesplot} can do the subsetting internally +#' with `subset` then **bayesplot** can do the subsetting internally #' for `y`, `yrep` *and* `psis_object`. -#' See the \strong{Examples} section for a demonstration. +#' See the **Examples** section for a demonstration. #' ppc_loo_intervals <- function(y, diff --git a/R/ppc-overview.R b/R/ppc-overview.R index 18c918207..99502f63f 100644 --- a/R/ppc-overview.R +++ b/R/ppc-overview.R @@ -5,12 +5,12 @@ #' @family PPCs #' #' @description -#' The \pkg{bayesplot} PPC module provides various plotting functions for +#' The **bayesplot** PPC module provides various plotting functions for #' creating graphical displays comparing observed data to simulated data from #' the posterior predictive distribution. See below for a brief discussion of #' the ideas behind posterior predictive checking, a description of the #' structure of this package, and tips on providing an interface to -#' \pkg{bayesplot} from another package. +#' **bayesplot** from another package. #' #' @details #' The idea behind posterior predictive checking is simple: if a model is a good @@ -44,7 +44,7 @@ #' } #' \subsection{Graphical posterior predictive checking}{ #' Using the datasets \eqn{y^{rep}}{yrep} drawn from the posterior predictive -#' distribution, the functions in the \pkg{bayesplot} package produce various +#' distribution, the functions in the **bayesplot** package produce various #' graphical displays comparing the observed data \eqn{y} to the replications. #' For a more thorough discussion of posterior predictive checking see #' Chapter 6 of Gelman et. al. (2013). @@ -95,11 +95,11 @@ #' #' @section Providing an interface for posterior predictive checking from another package: #' -#' In addition to the various plotting functions, the \pkg{bayesplot} package +#' In addition to the various plotting functions, the **bayesplot** package #' provides the S3 generic [pp_check()]. Authors of \R packages for #' Bayesian inference are encouraged to define `pp_check` methods for the #' fitted model objects created by their packages. See the package vignettes for -#' more details and a simple example, and see the \pkg{rstanarm} and \pkg{brms} +#' more details and a simple example, and see the **rstanarm** and \pkg{brms} #' packages for full examples of `pp_check` methods. #' #' @template reference-vis-paper diff --git a/R/ppc-scatterplots.R b/R/ppc-scatterplots.R index 45e321073..a8a9a3112 100644 --- a/R/ppc-scatterplots.R +++ b/R/ppc-scatterplots.R @@ -2,7 +2,7 @@ #' #' Scatterplots of the observed data `y` vs. simulated/replicated data #' `yrep` from the posterior predictive distribution. See the \strong{Plot -#' Descriptions} and \strong{Details} sections, below. +#' Descriptions} and **Details** sections, below. #' #' @name PPC-scatterplots #' @family PPCs diff --git a/R/ppc-test-statistics.R b/R/ppc-test-statistics.R index 3d319efd3..ca0217ebd 100644 --- a/R/ppc-test-statistics.R +++ b/R/ppc-test-statistics.R @@ -3,7 +3,7 @@ #' The distribution of a test statistic `T(yrep)`, or a pair of test #' statistics, over the simulated datasets in `yrep`, compared to the #' observed value `T(y)` computed from the data `y`. See the -#' \strong{Plot Descriptions} and \strong{Details} sections, below, as +#' **Plot Descriptions** and **Details** sections, below, as #' well as \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)}. #' #' @name PPC-test-statistics From 946fe1fafdab48803520f51ae10c9d878e4204e3 Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 16 May 2019 00:53:24 -0400 Subject: [PATCH 3/8] almost finish editing by hand --- R/ppc-distributions.R | 33 ++++++++--------- R/ppc-errors.R | 42 ++++++++++----------- R/ppc-intervals.R | 19 +++++----- R/ppc-loo.R | 81 ++++++++++++++++++++--------------------- R/ppc-overview.R | 71 +++++++++++++++--------------------- R/ppc-scatterplots.R | 22 +++++------ R/ppc-test-statistics.R | 37 +++++++++---------- 7 files changed, 141 insertions(+), 164 deletions(-) diff --git a/R/ppc-distributions.R b/R/ppc-distributions.R index e5c077108..031969bf1 100644 --- a/R/ppc-distributions.R +++ b/R/ppc-distributions.R @@ -21,26 +21,26 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{`ppc_hist, ppc_freqpoly, ppc_dens, ppc_boxplot`}{ +#' \item{`ppc_hist(), ppc_freqpoly(), ppc_dens(), ppc_boxplot()`}{ #' A separate histogram, shaded frequency polygon, smoothed kernel density #' estimate, or box and whiskers plot is displayed for `y` and each #' dataset (row) in `yrep`. For these plots `yrep` should therefore #' contain only a small number of rows. See the **Examples** section. #' } -#' \item{`ppc_freqpoly_grouped`}{ +#' \item{`ppc_freqpoly_grouped()`}{ #' A separate frequency polygon is plotted for each level of a grouping #' variable for `y` and each dataset (row) in `yrep`. For this plot #' `yrep` should therefore contain only a small number of rows. See the #' **Examples** section. #' } -#' \item{`ppc_dens_overlay, ppc_ecdf_overlay`}{ +#' \item{`ppc_dens_overlay(), ppc_ecdf_overlay()`}{ #' Kernel density or empirical CDF estimates of each dataset (row) in #' `yrep` are overlaid, with the distribution of `y` itself on top -#' (and in a darker shade). When using `ppc_ecdf_overlay` with discrete +#' (and in a darker shade). When using `ppc_ecdf_overlay()` with discrete #' data, set the `discrete` argument to `TRUE` for better results. -#' For an example of `ppc_dens_overlay` also see Gabry et al. (2019). +#' For an example of `ppc_dens_overlay()` also see Gabry et al. (2019). #' } -#' \item{`ppc_violin_grouped`}{ +#' \item{`ppc_violin_grouped()`}{ #' The density estimate of `yrep` within each level of a grouping #' variable is plotted as a violin with horizontal lines at notable #' quantiles. `y` is overlaid on the plot either as a violin, points, or @@ -151,7 +151,7 @@ ppc_hist <- function(y, yrep, ..., binwidth = NULL, breaks = NULL, #' @rdname PPC-distributions #' @export #' @param notch A logical scalar passed to [ggplot2::geom_boxplot()]. -#' Unlike for `geom_boxplot`, the default is `notch=TRUE`. +#' Unlike for `geom_boxplot()`, the default is `notch=TRUE`. #' ppc_boxplot <- function(y, yrep, ..., notch = TRUE, size = 0.5, alpha = 1) { check_ignored_arguments(...) @@ -321,7 +321,7 @@ ppc_dens_overlay <- function(y, yrep, ..., #' @export #' @rdname PPC-distributions -#' @param discrete For `ppc_ecdf_overlay`, should the data be treated as +#' @param discrete For `ppc_ecdf_overlay()`, should the data be treated as #' discrete? The default is `FALSE`, in which case `geom="line"` is #' passed to [ggplot2::stat_ecdf()]. If `discrete` is set to #' `TRUE` then `geom="step"` is used. @@ -374,16 +374,13 @@ ppc_ecdf_overlay <- #' @param probs A numeric vector passed to [ggplot2::geom_violin()]'s #' `draw_quantiles` argument to specify at which quantiles to draw #' horizontal lines. Set to `NULL` to remove the lines. -#' @param y_draw For `ppc_violin_grouped`, a string specifying how to draw -#' `y`: `"violin"` (default), `"points"` (jittered points), or -#' `"both"`. -#' @param y_jitter,y_size,y_alpha For `ppc_violin_grouped`, if -#' `y_draw` is `"points"` or `"both"` then `y_size`, -#' `y_alpha`, and `y_jitter` are passed to to the `size`, -#' `alpha`, and `width` arguments of -#' [ggplot2::geom_jitter()] to control the appearance of `y` -#' points. The default of `y_jitter=NULL` will let **ggplot2** -#' determine the amount of jitter. +#' @param y_draw For `ppc_violin_grouped()`, a string specifying how to draw +#' `y`: `"violin"` (default), `"points"` (jittered points), or `"both"`. +#' @param y_jitter,y_size,y_alpha For `ppc_violin_grouped()`, if `y_draw` is +#' `"points"` or `"both"` then `y_size`, `y_alpha`, and `y_jitter` are passed +#' to to the `size`, `alpha`, and `width` arguments of [ggplot2::geom_jitter()] +#' to control the appearance of `y` points. The default of `y_jitter=NULL` +#' will let **ggplot2** determine the amount of jitter. #' ppc_violin_grouped <- function(y, yrep, group, ..., probs = c(0.1, 0.5, 0.9), size = 1, alpha = 1, diff --git a/R/ppc-errors.R b/R/ppc-errors.R index ecb9275ea..3f84d9b4e 100644 --- a/R/ppc-errors.R +++ b/R/ppc-errors.R @@ -1,6 +1,6 @@ #' PPC errors #' -#' Various plots of predictive errors `y` - `yrep`. See the +#' Various plots of predictive errors `y - yrep`. See the #' **Details** and **Plot Descriptions** sections, below. #' #' @name PPC-errors @@ -9,9 +9,9 @@ #' @template args-y-yrep #' @param ... Currently unused. #' @param size,alpha For scatterplots, arguments passed to -#' [ggplot2::geom_point()] to control the appearance of the -#' points. For the binned error plot, arguments controlling the size of -#' the outline and opacity of the shaded region indicating the 2-SE bounds. +#' [ggplot2::geom_point()] to control the appearance of the points. For the +#' binned error plot, arguments controlling the size of the outline and +#' opacity of the shaded region indicating the 2-SE bounds. #' #' @details #' All of these functions (aside from the `*_scatter_avg` functions) @@ -19,48 +19,46 @@ #' it is usually a good idea for `yrep` to contain only a small number of #' draws (rows). See **Examples**, below. #' -#' For binomial and Bernoulli data the `ppc_error_binned` function can be -#' used to generate binned error plots. Bernoulli data can be input as a vector -#' of 0s and 1s, whereas for binomial data `y` and `yrep` should -#' contain "success" proportions (not counts). See the **Examples** -#' section, below. +#' For binomial and Bernoulli data the `ppc_error_binned()` function can be used +#' to generate binned error plots. Bernoulli data can be input as a vector of 0s +#' and 1s, whereas for binomial data `y` and `yrep` should contain "success" +#' proportions (not counts). See the **Examples** section, below. #' #' @section Plot descriptions: #' \describe{ -#' \item{`ppc_error_hist`}{ +#' \item{`ppc_error_hist()`}{ #' A separate histogram is plotted for the predictive errors computed from #' `y` and each dataset (row) in `yrep`. For this plot `yrep` #' should have only a small number of rows. #' } -#' \item{`ppc_error_hist_grouped`}{ -#' Like `ppc_error_hist`, except errors are computed within levels of a +#' \item{`ppc_error_hist_grouped()`}{ +#' Like `ppc_error_hist()`, except errors are computed within levels of a #' grouping variable. The number of histograms is therefore equal to the #' product of the number of rows in `yrep` and the number of groups #' (unique values of `group`). #' } -#' \item{`ppc_error_scatter`}{ +#' \item{`ppc_error_scatter()`}{ #' A separate scatterplot is displayed for `y` vs. the predictive errors #' computed from `y` and each dataset (row) in `yrep`. For this #' plot `yrep` should have only a small number of rows. #' } -#' \item{`ppc_error_scatter_avg`}{ +#' \item{`ppc_error_scatter_avg()`}{ #' A single scatterplot of `y` vs. the average of the errors computed #' from `y` and each dataset (row) in `yrep`. For each individual #' data point `y[n]` the average error is the average of the #' errors for `y[n]` computed over the the draws from the posterior #' predictive distribution. #' } -#' \item{`ppc_error_scatter_avg_vs_x`}{ -#' Same as `ppc_error_scatter_avg`, except the average is plotted on the +#' \item{`ppc_error_scatter_avg_vs_x()`}{ +#' Same as `ppc_error_scatter_avg()`, except the average is plotted on the #' \eqn{y}-axis and a a predictor variable `x` is plotted on the #' \eqn{x}-axis. #' } -#' \item{`ppc_error_binned`}{ +#' \item{`ppc_error_binned()`}{ #' Intended for use with binomial data. A separate binned error plot (similar -#' to `arm::binnedplot`) is generated for each dataset (row) in -#' `yrep`. For this plot `y` and `yrep` should contain -#' proportions rather than counts, and `yrep` should have only a small -#' number of rows. +#' to `arm::binnedplot()`) is generated for each dataset (row) in `yrep`. For +#' this plot `y` and `yrep` should contain proportions rather than counts, +#' and `yrep` should have only a small number of rows. #' } #' } #' @@ -311,7 +309,7 @@ ppc_error_scatter_avg_vs_x <- #' @rdname PPC-errors #' @export -#' @param bins For `ppc_error_binned`, the number of bins to use (approximately). +#' @param bins For `ppc_error_binned()`, the number of bins to use (approximately). ppc_error_binned <- function(y, yrep, ..., bins = NULL, size = 1, alpha = 0.25) { check_ignored_arguments(...) diff --git a/R/ppc-intervals.R b/R/ppc-intervals.R index 21c10c605..1f0ab9aa7 100644 --- a/R/ppc-intervals.R +++ b/R/ppc-intervals.R @@ -11,12 +11,11 @@ #' @param x A numeric vector the same length as `y` to use as the x-axis #' variable. For example, `x` could be a predictor variable from a #' regression model, a time variable for time-series models, etc. If `x` -#' is missing or NULL, then `1:length(y)` is used for the x-axis. +#' is missing or `NULL`, then `1:length(y)` is used for the x-axis. #' @param ... Currently unused. -#' @param alpha,size,fatten Arguments passed to geoms. For ribbon plots -#' `alpha` and `size` are passed to -#' [ggplot2::geom_ribbon()]. For interval plots `size` and -#' `fatten` are passed to [ggplot2::geom_pointrange()]. +#' @param alpha,size,fatten Arguments passed to geoms. For ribbon plots `alpha` +#' and `size` are passed to [ggplot2::geom_ribbon()]. For interval plots +#' `size` and `fatten` are passed to [ggplot2::geom_pointrange()]. #' #' @template return-ggplot-or-data #' @@ -25,11 +24,11 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{`ppc_intervals, ppc_ribbon`}{ +#' \item{`ppc_intervals(), ppc_ribbon()`}{ #' `100*prob`\% central intervals for `yrep` at each `x` -#' value. `ppc_intervals` plots intervals as vertical bars with points +#' value. `ppc_intervals()` plots intervals as vertical bars with points #' indicating `yrep` medians and darker points indicating observed -#' `y` values. `ppc_ribbon` plots a ribbon of connected intervals +#' `y` values. `ppc_ribbon()` plots a ribbon of connected intervals #' with a line through the median of `yrep` and a darker line connecting #' observed `y` values. In both cases an optional `x` variable can #' also be specified for the x-axis variable. @@ -38,8 +37,8 @@ #' predictions at different values of `x`, one or the other of these #' plots may be easier to read than the other. #' } -#' \item{`ppc_intervals_grouped, ppc_ribbon_grouped`}{ -#' Same as `ppc_intervals` and `ppc_ribbon`, respectively, but a +#' \item{`ppc_intervals_grouped(), ppc_ribbon_grouped()`}{ +#' Same as `ppc_intervals()` and `ppc_ribbon()`, respectively, but a #' separate plot (facet) is generated for each level of a grouping variable. #' } #' } diff --git a/R/ppc-loo.R b/R/ppc-loo.R index 58b1925d5..26ac1bee1 100644 --- a/R/ppc-loo.R +++ b/R/ppc-loo.R @@ -1,30 +1,29 @@ #' LOO predictive checks #' -#' Leave-One-Out (LOO) predictive checks. See the **Plot Descriptions** -#' section, below, and \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et -#' al. (2019)} for details. +#' Leave-One-Out (LOO) predictive checks. See the **Plot Descriptions** section, +#' below, and [Gabry et al. (2019)](https://github.com/jgabry/bayes-vis-paper) +#' for details. #' #' @name PPC-loo #' @family PPCs #' @template args-y-yrep #' @param ... Currently unused. #' @param lw A matrix of (smoothed) log weights with the same dimensions as -#' `yrep`. See [loo::psis()] and the associated `weights` -#' method and the **Examples** section, below. +#' `yrep`. See [loo::psis()] and the associated `weights()` method as well as +#' the **Examples** section, below. #' @param alpha,size,fatten Arguments passed to code geoms to control plot -#' aesthetics. For `ppc_loo_pit_qq` and `ppc_loo_pit_overlay`, -#' `size` and `alpha` are passed to -#' [ggplot2::geom_point()] and [ggplot2::geom_density()], -#' respectively. For `ppc_loo_intervals`, `size` and `fatten` -#' are passed to [ggplot2::geom_pointrange()]. For -#' `ppc_loo_ribbon`, `alpha` and `size` are passed to +#' aesthetics. For `ppc_loo_pit_qq()` and `ppc_loo_pit_overlay()`, `size` and +#' `alpha` are passed to [ggplot2::geom_point()] and +#' [ggplot2::geom_density()], respectively. For `ppc_loo_intervals()`, `size` +#' and `fatten` are passed to [ggplot2::geom_pointrange()]. For +#' `ppc_loo_ribbon()`, `alpha` and `size` are passed to #' [ggplot2::geom_ribbon()]. #' #' @template return-ggplot #' #' @section Plot Descriptions: #' \describe{ -#' \item{`ppc_loo_pit_overlay, ppc_loo_pit_qq`}{ +#' \item{`ppc_loo_pit_overlay()`, `ppc_loo_pit_qq()`}{ #' The calibration of marginal predictions can be assessed using probability #' integral transformation (PIT) checks. LOO improves the check by avoiding the #' double use of data. See the section on marginal predictive checks in Gelman @@ -32,13 +31,13 @@ #' example of using **bayesplot** for these checks. #' #' The LOO PIT values are asymptotically uniform (for continuous data) if the -#' model is calibrated. The `ppc_loo_pit_overlay` function creates a plot +#' model is calibrated. The `ppc_loo_pit_overlay()` function creates a plot #' comparing the density of the LOO PITs (thick line) to the density estimates #' of many simulated data sets from the standard uniform distribution (thin #' lines). See Gabry et al. (2019) for an example of interpreting the shape of #' the miscalibration that can be observed in these plots. #' -#' The `ppc_loo_pit_qq` function provides an alternative visualization of +#' The `ppc_loo_pit_qq()` function provides an alternative visualization of #' the miscalibration with a quantile-quantile (Q-Q) plot comparing the LOO #' PITs to the standard uniform distribution. Comparing to the uniform is not #' good for extreme probabilities close to 0 and 1, so it can sometimes be @@ -46,12 +45,12 @@ #' produce a Q-Q plot comparing standardized PIT values to the standard normal #' distribution that can help see the (mis)calibration better for the extreme #' values. However, in most cases we have found that the overlaid density plot -#' (`ppc_loo_pit_overlay`) function will provided a clearer picture of +#' (`ppc_loo_pit_overlay()`) function will provided a clearer picture of #' calibration problems that the Q-Q plot. #' } -#' \item{`ppc_loo_intervals, ppc_loo_ribbon`}{ -#' Similar to [ppc_intervals()] and [ppc_ribbon()] but the -#' intervals are for the LOO predictive distribution. +#' \item{`ppc_loo_intervals()`, `ppc_loo_ribbon()`}{ +#' Similar to [ppc_intervals()] and [ppc_ribbon()] but the intervals are for +#' the LOO predictive distribution. #' } #' } #' @@ -102,21 +101,20 @@ NULL #' @rdname PPC-loo #' @export -#' @param pit For `ppc_loo_pit_overlay` and `ppc_loo_pit_qq`, -#' optionally a vector of precomputed PIT values that can be specified instead -#' of `y`, `yrep`, and `lw` (these are all ignored if -#' `pit` is specified). If not specified the PIT values are computed -#' internally before plotting. -#' @param samples For `ppc_loo_pit_overlay`, the number of data sets (each +#' @param pit For `ppc_loo_pit_overlay()` and `ppc_loo_pit_qq()`, optionally a +#' vector of precomputed PIT values that can be specified instead of `y`, +#' `yrep`, and `lw` (these are all ignored if `pit` is specified). If not +#' specified the PIT values are computed internally before plotting. +#' @param samples For `ppc_loo_pit_overlay()`, the number of data sets (each #' the same size as `y`) to simulate from the standard uniform #' distribution. The default is 100. The density estimate of each dataset is #' plotted as a thin line in the plot, with the density estimate of the LOO #' PITs overlaid as a thicker dark line. -#' @param compare For `ppc_loo_pit_qq`, a string that can be either -#' `"uniform"` or `"normal"`. If `"uniform"` (the default) the -#' Q-Q plot compares computed PIT values to the standard uniform distribution. -#' If `compare="normal"`, the Q-Q plot compares standardized PIT values -#' to the standard normal distribution. +#' @param compare For `ppc_loo_pit_qq()`, a string that can be either +#' `"uniform"` or `"normal"`. If `"uniform"` (the default) the Q-Q plot +#' compares computed PIT values to the standard uniform distribution. If +#' `compare="normal"`, the Q-Q plot compares standardized PIT values to the +#' standard normal distribution. #' @param trim Passed to [ggplot2::stat_density()]. #' @template args-density-controls ppc_loo_pit_overlay <- function(y, yrep, lw, pit, samples = 100, ..., @@ -259,10 +257,10 @@ ppc_loo_pit <- #' @rdname PPC-loo #' @export #' @template args-prob-prob_outer -#' @param psis_object If using \pkg{loo} version `2.0.0` or greater, an -#' object returned by the `psis` function (or by the `loo` function +#' @param psis_object If using **loo** version `2.0.0` or greater, an +#' object returned by the `psis()` function (or by the `loo()` function #' with argument `save_psis` set to `TRUE`). -#' @param intervals For `ppc_loo_intervals` and `ppc_loo_ribbon`, +#' @param intervals For `ppc_loo_intervals()` and `ppc_loo_ribbon()`, #' optionally a matrix of precomputed LOO predictive intervals #' that can be specified instead of `yrep` and `lw` (these are both #' ignored if `intervals` is specified). If not specified the intervals @@ -271,19 +269,18 @@ ppc_loo_pit <- #' five columns in the following order: lower outer interval, lower inner #' interval, median (50\%), upper inner interval and upper outer interval #' (column names are ignored). -#' @param order For `ppc_loo_intervals`, a string indicating how to arrange +#' @param order For `ppc_loo_intervals()`, a string indicating how to arrange #' the plotted intervals. The default (`"index"`) is to plot them in the #' order of the observations. The alternative (`"median"`) arranges them #' by median value from smallest (left) to largest (right). -#' @param subset For `ppc_loo_intervals` and `ppc_loo_ribbon`, an -#' optional integer vector indicating which observations in `y` (and -#' `yrep`) to include. Dropping observations from `y` and -#' `yrep` manually before passing them to the plotting function will not -#' work because the dimensions will not match up with the dimensions of -#' `psis_object`, but if all of `y` and `yrep` are passed along -#' with `subset` then **bayesplot** can do the subsetting internally -#' for `y`, `yrep` *and* `psis_object`. -#' See the **Examples** section for a demonstration. +#' @param subset For `ppc_loo_intervals()` and `ppc_loo_ribbon()`, an optional +#' integer vector indicating which observations in `y` (and `yrep`) to +#' include. Dropping observations from `y` and `yrep` manually before passing +#' them to the plotting function will not work because the dimensions will not +#' match up with the dimensions of `psis_object`, but if all of `y` and `yrep` +#' are passed along with `subset` then **bayesplot** can do the subsetting +#' internally for `y`, `yrep` *and* `psis_object`. See the **Examples** +#' section for a demonstration. #' ppc_loo_intervals <- function(y, diff --git a/R/ppc-overview.R b/R/ppc-overview.R index 99502f63f..b9895eddb 100644 --- a/R/ppc-overview.R +++ b/R/ppc-overview.R @@ -24,8 +24,9 @@ #' after using the observed data \eqn{y} (a vector of outcome values), and #' typically predictors \eqn{X}, to update our beliefs about the unknown #' parameters \eqn{\theta} in the model. For each draw of the parameters -#' \eqn{\theta} from the posterior distribution \eqn{p(\theta \,|\, y, -#' X)}{p(\theta | y, X)} we generate an entire vector of outcomes. The result is +#' \eqn{\theta} from the posterior distribution +#' \eqn{p(\theta \,|\, y, X)}{p(\theta | y, X)} +#' we generate an entire vector of outcomes. The result is #' an \eqn{S \times N}{S x N} matrix of simulations, where \eqn{S} is the the #' size of the posterior sample (number of draws from the posterior #' distribution) and \eqn{N} is the number of data points in \eqn{y}. That is, @@ -54,53 +55,39 @@ #' #' The plotting functions for posterior predictive checking in this package are #' organized into several categories, each with its own documentation: -#' -#' \describe{ -#' \item{\strong{\link[=PPC-distributions]{Distributions}}}{ -#' Histograms, kernel density estimates, boxplots, and other plots comparing -#' the empirical distribution of the observed data `y` to the -#' distributions of individual replicated datasets (rows) in `yrep`. -#' } -#' \item{\strong{\link[=PPC-test-statistics]{Test statistics}}}{ -#' The distribution of a test statistic, or a pair of test statistics, over -#' the replicated datasets (rows) in `yrep` compared to value of the -#' statistic(s) computed from `y`. -#' } -#' \item{\strong{\link[=PPC-intervals]{Intervals}}}{ -#' Interval estimates of `yrep` with `y` overlaid. The x-axis -#' variable can be optionally specified by the user (e.g. to plot against -#' against a predictor variable or over time). -#' } -#' \item{\strong{\link[=PPC-errors]{Predictive errors}}}{ -#' Plots of predictive errors (`y - yrep`) computed from `y` and -#' replicated datasets (rows) in `yrep`. For binomial models binned -#' error plots are also available. -#' } -#' \item{\strong{\link[=PPC-scatterplots]{Scatterplots}}}{ -#' Scatterplots (and similar visualizations) of the observed data `y` -#' vs. individual replicated datasets (rows) in `yrep`, or vs. the -#' average value of the distributions of each data point (columns) in -#' `yrep`. -#' } -#' \item{\strong{\link[=PPC-discrete]{Plots for discrete outcomes}}}{ -#' PPC functions that can only be used if `y` and `yrep` are -#' discrete. For example, rootograms for count outcomes and bar -#' plots for ordinal, categorical, and multinomial outcomes. -#' } -#' \item{\strong{\link[=PPC-loo]{LOO predictive checks}}}{ -#' PPC functions for predictive checks based on (approximate) leave-one-out -#' (LOO) cross-validation. -#' } +#' * [__Distributions__][PPC-distributions]: Histograms, kernel density +#' estimates, boxplots, and other plots comparing the empirical distribution +#' of the observed data `y` to the distributions of individual replicated +#' datasets (rows) in `yrep`. +#' * [__Statistics__][PPC-test-statistics]: The distribution of a statistic, or a +#' pair of statistics, over the replicated datasets (rows) in `yrep` compared +#' to value of the statistic(s) computed from `y`. +#' * [__Intervals__][PPC-intervals]: Interval estimates of `yrep` with `y` +#' overlaid. The x-axis variable can be optionally specified by the user +#' (e.g. to plot against against a predictor variable or over time). +#' * [__Predictive errors__][PPC-errors]: Plots of predictive errors +#' (`y - yrep`) computed from `y` and replicated datasets (rows) in `yrep`. +#' For binomial models binned error plots are also available. +#' * [__Scatterplots__][PPC-scatterplots]: Scatterplots (and similar +#' visualizations) of the observed data `y` vs. individual replicated datasets +#' (rows) in `yrep`, or vs. the average value of the distributions of each data +#' point (columns) in `yrep`. +#' * [__Plots for discrete outcomes__][PPC-discrete]: PPC functions that can +#' only be used if `y` and `yrep` are discrete. For example, rootograms for +#' count outcomes and bar plots for ordinal, categorical, and +#' multinomial outcomes. +#' * [__LOO predictive checks__][PPC-loo]: PPC functions for predictive checks +#' based on (approximate) leave-one-out (LOO) cross-validation. #' } #' #' @section Providing an interface for posterior predictive checking from another package: #' #' In addition to the various plotting functions, the **bayesplot** package #' provides the S3 generic [pp_check()]. Authors of \R packages for -#' Bayesian inference are encouraged to define `pp_check` methods for the +#' Bayesian inference are encouraged to define `pp_check()` methods for the #' fitted model objects created by their packages. See the package vignettes for -#' more details and a simple example, and see the **rstanarm** and \pkg{brms} -#' packages for full examples of `pp_check` methods. +#' more details and a simple example, and see the **rstanarm** and **brms** +#' packages for full examples of `pp_check()` methods. #' #' @template reference-vis-paper #' @templateVar bdaRef (Ch. 6) diff --git a/R/ppc-scatterplots.R b/R/ppc-scatterplots.R index a8a9a3112..277dfaf83 100644 --- a/R/ppc-scatterplots.R +++ b/R/ppc-scatterplots.R @@ -1,16 +1,16 @@ #' PPC scatterplots #' #' Scatterplots of the observed data `y` vs. simulated/replicated data -#' `yrep` from the posterior predictive distribution. See the \strong{Plot -#' Descriptions} and **Details** sections, below. +#' `yrep` from the posterior predictive distribution. See the +#' **Plot Descriptions** and **Details** sections, below. #' #' @name PPC-scatterplots #' @family PPCs #' #' @template args-y-yrep #' @param ... Currently unused. -#' @param size,alpha Arguments passed to [ggplot2::geom_point()] to -#' control the appearance of the points. +#' @param size,alpha Arguments passed to [ggplot2::geom_point()] to control the +#' appearance of the points. #' #' @template details-binomial #' @template return-ggplot @@ -20,18 +20,18 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{`ppc_scatter`}{ -#' For each dataset (row) in `yrep` a scatterplot is generated showing -#' `y` against that row of `yrep`. For this plot `yrep` should -#' only contain a small number of rows. +#' \item{`ppc_scatter()`}{ +#' For each dataset (row) in `yrep` a scatterplot is generated showing `y` +#' against that row of `yrep`. For this plot `yrep` should only contain a +#' small number of rows. #' } -#' \item{`ppc_scatter_avg`}{ +#' \item{`ppc_scatter_avg()`}{ #' A scatterplot of `y` against the average values of `yrep`, i.e., #' the points `(mean(yrep[, n]), y[n])`, where each `yrep[, n]` is #' a vector of length equal to the number of posterior draws. #' } -#' \item{`ppc_scatter_avg_grouped`}{ -#' The same as `ppc_scatter_avg`, but a separate plot is generated for +#' \item{`ppc_scatter_avg_grouped()`}{ +#' The same as `ppc_scatter_avg()`, but a separate plot is generated for #' each level of a grouping variable. #' } #' } diff --git a/R/ppc-test-statistics.R b/R/ppc-test-statistics.R index ca0217ebd..5377bc186 100644 --- a/R/ppc-test-statistics.R +++ b/R/ppc-test-statistics.R @@ -1,10 +1,10 @@ #' PPC test statistics #' -#' The distribution of a test statistic `T(yrep)`, or a pair of test +#' The distribution of a (test) statistic `T(yrep)`, or a pair of (test) #' statistics, over the simulated datasets in `yrep`, compared to the #' observed value `T(y)` computed from the data `y`. See the #' **Plot Descriptions** and **Details** sections, below, as -#' well as \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)}. +#' well as [Gabry et al. (2019)](https://github.com/jgabry/bayes-vis-paper). #' #' @name PPC-test-statistics #' @family PPCs @@ -12,9 +12,9 @@ #' @template args-y-yrep #' @template args-facet_args #' @param stat A single function or a string naming a function, except for -#' `ppc_stat_2d` which requires a vector of exactly two functions or +#' `ppc_stat_2d()` which requires a vector of exactly two functions or #' function names. In all cases the function(s) should take a vector input and -#' return a scalar test statistic. If specified as a string (or strings) then +#' return a scalar statistic. If specified as a string (or strings) then #' the legend will display function names. If specified as a function (or #' functions) then generic naming is used in the legend. #' @param ... Currently unused. @@ -28,21 +28,20 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{`ppc_stat`}{ +#' \item{`ppc_stat()`}{ #' A histogram of the distribution of a test statistic computed by applying -#' `stat` to each dataset (row) in `yrep`. The value of the -#' statistic in the observed data, `stat(y)`, is overlaid as a vertical -#' line. More details on `ppc_stat` can be found in Gabry et al. -#' (2019). +#' `stat` to each dataset (row) in `yrep`. The value of the statistic in the +#' observed data, `stat(y)`, is overlaid as a vertical line. More details on +#' `ppc_stat()` can be found in Gabry et al. (2019). #' } -#' \item{`ppc_stat_grouped,ppc_stat_freqpoly_grouped`}{ -#' The same as `ppc_stat`, but a separate plot is generated for each +#' \item{`ppc_stat_grouped()`,`ppc_stat_freqpoly_grouped()`}{ +#' The same as `ppc_stat()`, but a separate plot is generated for each #' level of a grouping variable. In the case of -#' `ppc_stat_freqpoly_grouped` the plots are frequency polygons rather -#' than histograms. More details on `ppc_stat_grouped` can be found in +#' `ppc_stat_freqpoly_grouped()` the plots are frequency polygons rather +#' than histograms. More details on `ppc_stat_grouped()` can be found in #' Gabry et al. (2019). #' } -#' \item{`ppc_stat_2d`}{ +#' \item{`ppc_stat_2d()`}{ #' A scatterplot showing the joint distribution of two test statistics #' computed over the datasets (rows) in `yrep`. The value of the #' statistics in the observed data is overlaid as large point. @@ -245,8 +244,8 @@ ppc_stat_freqpoly_grouped <- #' @rdname PPC-test-statistics #' @export -#' @param size,alpha Arguments passed to [ggplot2::geom_point()] to -#' control the appearance of scatterplot points. +#' @param size,alpha Arguments passed to [ggplot2::geom_point()] to control the +#' appearance of scatterplot points. ppc_stat_2d <- function(y, yrep, stat = c("mean", "sd"), ..., size = 2.5, alpha = 0.7) { check_ignored_arguments(...) @@ -316,9 +315,9 @@ ppc_stat_2d <- function(y, yrep, stat = c("mean", "sd"), ..., #' Make legend title for ppc_stat,ppc_stat_grouped,ppc_stat_freqpoly_grouped #' -#' @param stat The user's 'stat' argument. -#' @param stat_txt deparse(substitute()) applied to users 'stat' argument -#' @return Either throws an error or returns a legend title (possibly NULL) +#' @param stat The user's `stat` argument. +#' @param stat_txt `deparse(substitute())` applied to users `stat` argument. +#' @return Either throws an error or returns a legend title (possibly `NULL`). #' @noRd stat_legend_title <- function(stat, stat_txt) { stopifnot(is.character(stat) || is.function(stat)) From fdcf6a237d466c3bbea00b68ff492fc03d2dca03 Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 16 May 2019 01:27:24 -0400 Subject: [PATCH 4/8] fix some warnings/errors Pretty much closes #191 --- R/bayesplot-colors.R | 1 - R/bayesplot-helpers.R | 43 +++--- R/bayesplot-package.R | 1 - R/bayesplot_grid.R | 4 +- R/mcmc-diagnostics-nuts.R | 4 + R/mcmc-diagnostics.R | 37 +++--- R/mcmc-traces.R | 63 +++++---- R/ppc-overview.R | 8 +- man/MCMC-combos.Rd | 18 +-- man/MCMC-diagnostics.Rd | 78 +++++------ man/MCMC-distributions.Rd | 109 ++++++++------- man/MCMC-intervals.Rd | 98 +++++++------- man/MCMC-nuts.Rd | 167 +++++++++++------------ man/MCMC-overview.Rd | 101 ++++++-------- man/MCMC-parcoord.Rd | 128 +++++++++--------- man/MCMC-recover.Rd | 35 +++-- man/MCMC-scatterplots.Rd | 257 ++++++++++++++++++------------------ man/MCMC-traces.Rd | 105 +++++++-------- man/PPC-discrete.Rd | 107 ++++++++------- man/PPC-distributions.Rd | 124 +++++++++-------- man/PPC-errors.Rd | 110 ++++++++------- man/PPC-intervals.Rd | 64 +++++---- man/PPC-loo.Rd | 165 +++++++++++------------ man/PPC-overview.Rd | 103 +++++++-------- man/PPC-scatterplots.Rd | 56 ++++---- man/PPC-test-statistics.Rd | 85 ++++++------ man/available_ppc.Rd | 12 +- man/bayesplot-colors.Rd | 4 +- man/bayesplot-extractors.Rd | 28 ++-- man/bayesplot-helpers.Rd | 123 +++++++++-------- man/bayesplot-package.Rd | 67 +++++----- man/bayesplot_grid.Rd | 6 +- man/bayesplot_theme_get.Rd | 48 ++++--- man/example-data.Rd | 50 +++---- man/pp_check.Rd | 26 ++-- man/theme_default.Rd | 26 ++-- 36 files changed, 1193 insertions(+), 1268 deletions(-) diff --git a/R/bayesplot-colors.R b/R/bayesplot-colors.R index bba823e99..e18dd010e 100644 --- a/R/bayesplot-colors.R +++ b/R/bayesplot-colors.R @@ -142,7 +142,6 @@ color_scheme_set <- function(scheme = "blue") { } #' @rdname bayesplot-colors -#' @md #' @export #' @param i For `color_scheme_get()`, an optional subset of the integers from `1` #' (lightest) to `6` (darkest) indicating which of the colors in the diff --git a/R/bayesplot-helpers.R b/R/bayesplot-helpers.R index 0f7896d56..0d0bfa8e1 100644 --- a/R/bayesplot-helpers.R +++ b/R/bayesplot-helpers.R @@ -46,18 +46,22 @@ #' the lower and upper bounds (`lb`, `ub`) of the `100*p`\% central interval #' of `x`, as well as the median (if `med=TRUE`). #' } +#' #' \subsection{Control appearance of facet strips}{ -#' * `facet_text()` and `facet_bg()` return ggplot2 theme objects that -#' can be added to an existing plot (ggplot object) to format the text and the -#' background for the facet strips. +#' * `facet_text()` returns ggplot2 theme objects that can be added to an +#' existing plot (ggplot object) to format the text in facet strips. +#' +#' * `facet_bg()` can be added to a plot to change the background of the facet strips. #' } +#' #' \subsection{Move legend, remove legend, or style the legend text}{ -#' * `legend_move()` and `legend_none()` return a ggplot2 theme object -#' that can be added to an existing plot (ggplot object) in order to change the -#' position of the legend (`legend_move()`) or remove the legend -#' (`legend_none()`). `legend_text()` works much like `facet_text()`, -#' except it controls the legend text. +#' * `legend_move()` and `legend_none()` return a ggplot2 theme object that can +#' be added to an existing plot (ggplot object) in order to change the +#' position of the legend or remove it. +#' +#' * `legend_text()` works much like `facet_text()` but for the legend. #' } +#' #' \subsection{Control appearance of \eqn{x}-axis and \eqn{y}-axis features}{ #' * `xaxis_title()` and `yaxis_title()` return a ggplot2 theme object #' that can be added to an existing plot (ggplot object) in order to toggle or @@ -73,21 +77,24 @@ #' that can be added to an existing plot (ggplot object) to change the #' appearance of the axis tick marks. #' } +#' #' \subsection{Customize plot background}{ #' * `plot_bg()` returns a ggplot2 theme object that can be added to an -#' existing plot (ggplot object) to format the background of the *entire* plot. +#' existing plot (ggplot object) to format the background of the *entire* plot. +#' #' * `panel_bg()` returns a ggplot2 theme object that can be added to an -#' existing plot (ggplot object) to format the background of the just the -#' plotting area. +#' existing plot (ggplot object) to format the background of the just the +#' plotting area. +#' #' * `grid_lines()` returns a ggplot2 theme object that can be added to -#' an existing plot (ggplot object) to add grid lines to the plot background. +#' an existing plot (ggplot object) to add grid lines to the plot background. #' } +#' #' \subsection{Superimpose a function on an existing plot}{ -#' * `overlay_function()` is a simple wrapper for -#' [ggplot2::stat_function()] but with the `inherit.aes` argument -#' fixed to `FALSE`. Fixing `inherit.aes=FALSE` will avoid potential -#' errors due to the [ggplot2::aes()]thetic mapping used by certain -#' **bayesplot** plotting functions. +#' * `overlay_function()` is a simple wrapper for [ggplot2::stat_function()] but +#' with the `inherit.aes` argument fixed to `FALSE`. Fixing `inherit.aes=FALSE` +#' will avoid potential errors due to the [ggplot2::aes()]thetic mapping used by +#' certain **bayesplot** plotting functions. #' } #' #' @seealso [theme_default()] for the default ggplot theme used by @@ -284,7 +291,7 @@ abline_01 <- function(..., na.rm = TRUE) { # intervals --------------------------------------------------------------- #' @rdname bayesplot-helpers #' @export -#' @param p The probability mass (in `[0,1]``) to include in the interval. +#' @param p The probability mass (in `[0,1]`) to include in the interval. #' @param med Should the median also be included in addition to the lower #' and upper bounds of the interval? #' diff --git a/R/bayesplot-package.R b/R/bayesplot-package.R index e500fb192..33eba1f5a 100644 --- a/R/bayesplot-package.R +++ b/R/bayesplot-package.R @@ -49,7 +49,6 @@ #' * __General questions and help__: #' To ask a question about **bayesplot** on the Stan Forums forum please visit #' . -#' } #' #' @template seealso-theme #' @template seealso-colors diff --git a/R/bayesplot_grid.R b/R/bayesplot_grid.R index 161ad870d..eb0841bed 100644 --- a/R/bayesplot_grid.R +++ b/R/bayesplot_grid.R @@ -23,8 +23,8 @@ #' Setting this to `FALSE` will make the returned object smaller but #' these individual plot objects will not be available. #' -#' @return An object of class "bayesplot_grid" (essentially a gtable object from -#' [gridExtra::arrangeGrob()]), which has a `plot` method. +#' @return An object of class `"bayesplot_grid"` (essentially a gtable object +#' from [gridExtra::arrangeGrob()]), which has a `plot` method. #' #' @examples #' y <- example_y_data() diff --git a/R/mcmc-diagnostics-nuts.R b/R/mcmc-diagnostics-nuts.R index df7ce9a25..8023a2385 100644 --- a/R/mcmc-diagnostics-nuts.R +++ b/R/mcmc-diagnostics-nuts.R @@ -51,22 +51,26 @@ #' lines indicating the mean (solid line) and median (dashed line). #' * Scatterplot of `accept_stat__` vs `lp__`. #' } +#' #' \item{`mcmc_nuts_divergence()`}{ #' Two plots: #' * Violin plots of `lp__|divergent__=1` and `lp__|divergent__=0`. #' * Violin plots of `accept_stat__|divergent__=1` and `accept_stat__|divergent__=0`. #' } +#' #' \item{`mcmc_nuts_stepsize()`}{ #' Two plots: #' * Violin plots of `lp__` by chain ordered by `stepsize__` value. #' * Violin plots of `accept_stat__` by chain ordered by `stepsize__` value. #' } +#' #' \item{`mcmc_nuts_treedepth()`}{ #' Three plots: #' * Violin plots of `lp__` by value of `treedepth__`. #' * Violin plots of `accept_stat__` by value of `treedepth__`. #' * Histogram of `treedepth__`. #' } +#' #' \item{`mcmc_nuts_energy()`}{ #' Overlaid histograms showing `energy__` vs the change in #' `energy__`. See Betancourt (2016) for details. diff --git a/R/mcmc-diagnostics.R b/R/mcmc-diagnostics.R index d2ffac1e7..4006391b4 100644 --- a/R/mcmc-diagnostics.R +++ b/R/mcmc-diagnostics.R @@ -19,28 +19,29 @@ #' @section Plot Descriptions: #' \describe{ #' \item{`mcmc_rhat()`, `mcmc_rhat_hist()`}{ -#' Rhat values as either points or a histogram. Values are colored using -#' different shades (lighter is better). The chosen thresholds are somewhat -#' arbitrary, but can be useful guidelines in practice. -#' * _light_: below 1.05 (good) -#' * _mid_: between 1.05 and 1.1 (ok) -#' * _dark_: above 1.1 (too high) +#' Rhat values as either points or a histogram. Values are colored using +#' different shades (lighter is better). The chosen thresholds are somewhat +#' arbitrary, but can be useful guidelines in practice. +#' * _light_: below 1.05 (good) +#' * _mid_: between 1.05 and 1.1 (ok) +#' * _dark_: above 1.1 (too high) #' } +#' #' \item{`mcmc_neff()`, `mcmc_neff_hist()`}{ -#' Ratios of effective sample size to total sample size as either points or a -#' histogram. Values are colored using different shades (lighter is better). The -#' chosen thresholds are somewhat arbitrary, but can be useful guidelines in -#' practice. -#' * _light_: between 0.5 and 1 (high) -#' * _mid_: between 0.1 and 0.5 (good) -#' * _dark_: below 0.1 (low) -#' } +#' Ratios of effective sample size to total sample size as either points or a +#' histogram. Values are colored using different shades (lighter is better). +#' The chosen thresholds are somewhat arbitrary, but can be useful guidelines +#' in practice. +#' * _light_: between 0.5 and 1 (high) +#' * _mid_: between 0.1 and 0.5 (good) +#' * _dark_: below 0.1 (low) #' } +#' #' \item{`mcmc_acf()`, `mcmc_acf_bar()`}{ -#' Grid of autocorrelation plots by chain and parameter. The `lags` -#' argument gives the maximum number of lags at which to calculate the -#' autocorrelation function. `mcmc_acf()` is a line plot whereas -#' `mcmc_acf_bar()` is a barplot. +#' Grid of autocorrelation plots by chain and parameter. The `lags` argument +#' gives the maximum number of lags at which to calculate the autocorrelation +#' function. `mcmc_acf()` is a line plot whereas `mcmc_acf_bar()` is a +#' barplot. #' } #'} #' diff --git a/R/mcmc-traces.R b/R/mcmc-traces.R index 422f3336b..eafce7e4e 100644 --- a/R/mcmc-traces.R +++ b/R/mcmc-traces.R @@ -13,9 +13,9 @@ #' @template args-facet_args #' @param ... Currently ignored. #' @param size An optional value to override the default line size -#' (`mcmc_trace`) or the default point size -#' (`mcmc_trace_highlight`). -#' @param alpha For `mcmc_trace_highlight`, passed to +#' (`mcmc_trace()`) or the default point size +#' (`mcmc_trace_highlight()`). +#' @param alpha For `mcmc_trace_highlight()`, passed to #' [ggplot2::geom_point()] to control the transparency of the points #' for the chains not highlighted. #' @param n_warmup An integer; the number of warmup iterations included in @@ -23,20 +23,19 @@ #' iterations are included. If `n_warmup > 0` then the background for #' iterations `1:n_warmup` is shaded gray. #' @param iter1 An integer; the iteration number of the first included draw -#' (default 0). This can be used to make it more obvious that the warmup +#' (default is `0`). This can be used to make it more obvious that the warmup #' iterations have been discarded from the traceplot. It cannot be specified #' if `n_warmup` is also set to a positive value. #' @param window An integer vector of length two specifying the limits of a #' range of iterations to display. -#' @param np For models fit using [NUTS()] (more generally, any -#' \href{https://en.wikipedia.org/wiki/Symplectic_integrator}{symplectic -#' integrator}), an optional data frame providing NUTS diagnostic -#' information. The data frame should be the object returned by -#' [nuts_params()] or one with the same structure. If `np` is -#' specified then tick marks are added to the bottom of the trace plot -#' indicating within which iterations there was a divergence (if there were any). -#' See the end of the **Examples** section, below. -#' @param np_style A call to the `trace_style_np` helper function to +#' @param np For models fit using [NUTS] (more generally, any +#' (https://en.wikipedia.org/wiki/Symplectic_integrator)[symplectic integrator]), +#' an optional data frame providing NUTS diagnostic information. The data +#' frame should be the object returned by [nuts_params()] or one with the same +#' structure. If `np` is specified then tick marks are added to the bottom of +#' the trace plot indicating within which iterations there was a divergence +#' (if there were any). See the end of the **Examples** section, below. +#' @param np_style A call to the `trace_style_np()` helper function to #' specify arguments controlling the appearance of tick marks representing #' divergences (if the `np` argument is specified). #' @param divergences Deprecated. Use the `np` argument instead. @@ -45,11 +44,11 @@ #' #' @section Plot Descriptions: #' \describe{ -#' \item{`mcmc_trace`}{ -#' Standard trace plots of MCMC draws. For models fit using [NUTS()], +#' \item{`mcmc_trace()`}{ +#' Standard trace plots of MCMC draws. For models fit using [NUTS], #' the `np` argument can be used to also show divergences on the trace plot. #' } -#' \item{`mcmc_trace_highlight`}{ +#' \item{`mcmc_trace_highlight()`}{ #' Traces are plotted using points rather than lines and the opacity of all #' chains but one (specified by the `highlight` argument) is reduced. #' } @@ -192,7 +191,7 @@ mcmc_trace <- #' @rdname MCMC-traces #' @export -#' @param highlight For `mcmc_trace_highlight`, an integer specifying one +#' @param highlight For `mcmc_trace_highlight()`, an integer specifying one #' of the chains that will be more visible than the others in the plot. mcmc_trace_highlight <- function(x, @@ -227,11 +226,10 @@ mcmc_trace_highlight <- #' @rdname MCMC-traces #' @export #' @param div_color,div_size,div_alpha Optional arguments to the -#' `trace_style_np` helper function that are eventually passed to -#' [ggplot2::geom_rug()] if the `np` argument is also -#' specified. They control the color, size, and transparency specifications -#' for showing divergences in the plot. The default values are displayed in -#' the \strong{Usage} section above. +#' `trace_style_np()` helper function that are eventually passed to +#' [ggplot2::geom_rug()] if the `np` argument is also specified. They control +#' the color, size, and transparency specifications for showing divergences in +#' the plot. The default values are displayed in the **Usage** section above. trace_style_np <- function(div_color = "red", div_size = 0.25, @@ -391,16 +389,17 @@ chain_colors <- function(n) { } -# Add divergences to trace plot using geom_rug -# -# @param np User's 'np' argument, if specified. -# @param np_style User's 'np_style' argument, if specified. -# @param n_iter Number of iterations in the trace plot (to check against number -# of iterations provided in 'np'). -# @param n_chain Number of chains in the trace plot (to check against number -# of chains provided in 'np'). -# @return Object returned by geom_rug. -# +#' Add divergences to trace plot using geom_rug +#' +#' @noRd +#' @param np User's `np` argument, if specified. +#' @param np_style User's `np_style` argument, if specified. +#' @param n_iter Number of iterations in the trace plot (to check against number +#' of iterations provided in `np`). +#' @param n_chain Number of chains in the trace plot (to check against number +#' of chains provided in `np`). +#' @return Object returned by `ggplot2::geom_rug()`. +#' #' @importFrom dplyr summarise group_by select divergence_rug <- function(np, np_style, n_iter, n_chain) { if (is.data.frame(np)) { diff --git a/R/ppc-overview.R b/R/ppc-overview.R index b9895eddb..eb0bf5cdb 100644 --- a/R/ppc-overview.R +++ b/R/ppc-overview.R @@ -51,10 +51,9 @@ #' Chapter 6 of Gelman et. al. (2013). #' } #' -#' @section PPC plotting functions: -#' -#' The plotting functions for posterior predictive checking in this package are -#' organized into several categories, each with its own documentation: +#' @section PPC plotting functions: The plotting functions for posterior +#' predictive checking in this package are organized into several categories, +#' each with its own documentation: #' * [__Distributions__][PPC-distributions]: Histograms, kernel density #' estimates, boxplots, and other plots comparing the empirical distribution #' of the observed data `y` to the distributions of individual replicated @@ -78,7 +77,6 @@ #' multinomial outcomes. #' * [__LOO predictive checks__][PPC-loo]: PPC functions for predictive checks #' based on (approximate) leave-one-out (LOO) cross-validation. -#' } #' #' @section Providing an interface for posterior predictive checking from another package: #' diff --git a/man/MCMC-combos.Rd b/man/MCMC-combos.Rd index 677fbe65c..4992e0ee9 100644 --- a/man/MCMC-combos.Rd +++ b/man/MCMC-combos.Rd @@ -16,8 +16,8 @@ allowed inputs. It is also possible to use an object with an the \link{MCMC-overview} page.} \item{combo}{A character vector with at least two elements. Each element of -\code{combo} corresponds to a column in the resulting graphic and should be -the name of one of the available \link{MCMC} functions (omitting the +\code{combo} corresponds to a column in the resulting graphic and should be the +name of one of the available \link[=MCMC-overview]{MCMC} functions (omitting the \code{mcmc_} prefix).} \item{widths}{A numeric vector the same length as \code{combo} specifying @@ -26,22 +26,22 @@ relative column widths. For example, if the plot has two columns, then factor of 2 (as would \code{widths = c(.3, .15)}, etc.). The default, \code{NULL}, allocates the same horizontal space for each column.} -\item{gg_theme}{Unlike most of the other \pkg{bayesplot} functions, +\item{gg_theme}{Unlike most of the other \strong{bayesplot}functions, \code{mcmc_combo} returns a gtable object rather than a ggplot object, and so theme objects can't be added directly to the returned plot object. The \code{gg_theme} argument helps get around this problem by accepting a -\pkg{ggplot2} \link[ggplot2]{theme} object that is added to each of the +\strong{ggplot2} \link[ggplot2:theme]{theme} object that is added to each of the plots \emph{before} combining them into the gtable object that is returned. -This can be a theme object created by a call to \code{ggplot2::theme} or -one of the \pkg{bayesplot} convenience functions, e.g. -\code{\link{legend_none}} (see the \strong{Examples} section, below).} +This can be a theme object created by a call to \code{\link[ggplot2:theme]{ggplot2::theme()}} or +one of the \strong{bayesplot}convenience functions, e.g. +\code{\link[=legend_none]{legend_none()}} (see the \strong{Examples} section, below).} \item{...}{Arguments passed to the plotting functions named in \code{combo}.} } \value{ A gtable object (the result of calling - \code{\link[gridExtra]{arrangeGrob}}) with \code{length(combo)} columns and - a row for each parameter. +\code{\link[gridExtra:arrangeGrob]{gridExtra::arrangeGrob()}}) with \code{length(combo)} columns and +a row for each parameter. } \description{ Combination plots diff --git a/man/MCMC-diagnostics.Rd b/man/MCMC-diagnostics.Rd index 96cedfd8a..9e86483cf 100644 --- a/man/MCMC-diagnostics.Rd +++ b/man/MCMC-diagnostics.Rd @@ -31,22 +31,22 @@ mcmc_acf_bar(x, pars = character(), regex_pars = character(), facet_args = list(), ..., lags = 20) } \arguments{ -\item{rhat}{A vector of \code{\link[=rhat]{Rhat}} estimates.} +\item{rhat}{A vector of R-hat estimates.} \item{...}{Currently ignored.} -\item{size}{An optional value to override \code{\link[ggplot2]{geom_point}}'s -default size (for \code{mcmc_rhat}, \code{mcmc_neff}) or -\code{\link[ggplot2]{geom_line}}'s default size (for \code{mcmc_acf}).} +\item{size}{An optional value to override \code{\link[ggplot2:geom_point]{ggplot2::geom_point()}}'s +default size (for \code{mcmc_rhat()}, \code{mcmc_neff()}) or +\code{\link[ggplot2:geom_line]{ggplot2::geom_line()}}'s default size (for \code{mcmc_acf()}).} -\item{binwidth}{Passed to \code{\link[ggplot2]{geom_histogram}} to override +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override the default binwidth.} -\item{breaks}{Passed to \code{\link[ggplot2]{geom_histogram}} as an +\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an alternative to \code{binwidth}.} \item{ratio}{A vector of \emph{ratios} of effective sample size estimates to -total sample size. See \code{\link{neff_ratio}}.} +total sample size. See \code{\link[=neff_ratio]{neff_ratio()}}.} \item{x}{A 3-D array, matrix, list of matrices, or data frame of MCMC draws. The \link{MCMC-overview} page provides details on how to specify each these @@ -56,22 +56,22 @@ the \link{MCMC-overview} page.} \item{pars}{An optional character vector of parameter names. If neither \code{pars} nor \code{regex_pars} is specified then the default is to use -\emph{all} parameters.} +\strong{all} parameters.} -\item{regex_pars}{An optional \link[=grep]{regular expression} to use for +\item{regex_pars}{An optional \link[base:grep]{regular expression} to use for parameter selection. Can be specified instead of \code{pars} or in addition to \code{pars}.} \item{facet_args}{A named list of arguments (other than \code{facets}) passed -to \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} +to \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}} or \code{\link[ggplot2:facet_grid]{ggplot2::facet_grid()}} to control faceting.} \item{lags}{The number of lags to show in the autocorrelation plot.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. The \code{_data} functions return the data that - would have been drawn by the plotting function. +A ggplot object that can be further customized using the \strong{ggplot2} +package. The functions with suffix \code{_data} return the data that would have +been drawn by the plotting function. } \description{ Plots of Rhat statistics, ratios of effective sample size to total sample @@ -82,32 +82,34 @@ also \link{MCMC-nuts} for additional MCMC diagnostic plots. \section{Plot Descriptions}{ \describe{ -\item{\code{mcmc_rhat, mcmc_rhat_hist}}{ +\item{\code{mcmc_rhat()}, \code{mcmc_rhat_hist()}}{ Rhat values as either points or a histogram. Values are colored using different shades (lighter is better). The chosen thresholds are somewhat arbitrary, but can be useful guidelines in practice. - \itemize{ - \item \emph{light}: below 1.05 (good) - \item \emph{mid}: between 1.05 and 1.1 (ok) - \item \emph{dark}: above 1.1 (too high) - } +\itemize{ +\item \emph{light}: below 1.05 (good) +\item \emph{mid}: between 1.05 and 1.1 (ok) +\item \emph{dark}: above 1.1 (too high) +} } -\item{\code{mcmc_neff, mcmc_neff_hist}}{ + +\item{\code{mcmc_neff()}, \code{mcmc_neff_hist()}}{ Ratios of effective sample size to total sample size as either points or a -histogram. Values are colored using different shades (lighter is better). The -chosen thresholds are somewhat arbitrary, but can be useful guidelines in -practice. - \itemize{ - \item \emph{light}: between 0.5 and 1 (high) - \item \emph{mid}: between 0.1 and 0.5 (good) - \item \emph{dark}: below 0.1 (low) - } +histogram. Values are colored using different shades (lighter is better). +The chosen thresholds are somewhat arbitrary, but can be useful guidelines +in practice. +\itemize{ +\item \emph{light}: between 0.5 and 1 (high) +\item \emph{mid}: between 0.1 and 0.5 (good) +\item \emph{dark}: below 0.1 (low) +} } -\item{\code{mcmc_acf}}{ -Grid of autocorrelation plots by chain and parameter. The \code{lags} -argument gives the maximum number of lags at which to calculate the -autocorrelation function. \code{mcmc_acf} is a line plot whereas -\code{mcmc_acf_bar} is a barplot. + +\item{\code{mcmc_acf()}, \code{mcmc_acf_bar()}}{ +Grid of autocorrelation plots by chain and parameter. The \code{lags} argument +gives the maximum number of lags at which to calculate the autocorrelation +function. \code{mcmc_acf()} is a line plot whereas \code{mcmc_acf_bar()} is a +barplot. } } } @@ -175,8 +177,9 @@ mcmc_acf(as.array(fit2), pars = c("wt", "cyl"), lags = 10) } \references{ -Stan Development Team. \emph{Stan Modeling Language Users -Guide and Reference Manual.} \url{https://mc-stan.org/users/documentation/} +Stan Development Team. +\emph{Stan Modeling Language Users Guide and Reference Manual.} +\url{https://mc-stan.org/users/documentation/} Gelman, A. and Rubin, D. B. (1992). Inference from iterative simulation using multiple sequences. \emph{Statistical Science}. 7(4), @@ -184,9 +187,10 @@ simulation using multiple sequences. \emph{Statistical Science}. 7(4), } \seealso{ \itemize{ -\item The \emph{Visual MCMC Diagnostics} vignette. +\item The \href{https://mc-stan.org/bayesplot/articles/visual-mcmc-diagnostics.html}{Visual MCMC Diagnostics} +vignette. \item \link{MCMC-nuts} for additional MCMC diagnostic plots for models fit - using the No-U-Turn-Sampler. +using the No-U-Turn-Sampler. } Other MCMC: \code{\link{MCMC-combos}}, diff --git a/man/MCMC-distributions.Rd b/man/MCMC-distributions.Rd index 972ce7d23..07b08580e 100644 --- a/man/MCMC-distributions.Rd +++ b/man/MCMC-distributions.Rd @@ -47,67 +47,64 @@ the \link{MCMC-overview} page.} \item{pars}{An optional character vector of parameter names. If neither \code{pars} nor \code{regex_pars} is specified then the default is to use -\emph{all} parameters.} +\strong{all} parameters.} -\item{regex_pars}{An optional \link[=grep]{regular expression} to use for +\item{regex_pars}{An optional \link[base:grep]{regular expression} to use for parameter selection. Can be specified instead of \code{pars} or in addition to \code{pars}.} \item{transformations}{Optionally, transformations to apply to parameters - before plotting. If \code{transformations} is a function or a single string - naming a function then that function will be used to transform all - parameters. To apply transformations to particular parameters, the - \code{transformations} argument can be a named list with length equal to - the number of parameters to be transformed. Currently only univariate - transformations of scalar parameters can be specified (multivariate - transformations will be implemented in a future release). If - \code{transformations} is a list, the name of each list element should be a - parameter name and the content of each list element should be a function - (or any item to match as a function via \code{\link{match.fun}}, e.g. a - string naming a function). If a function is specified by its name as a - string (e.g. \code{"log"}), then it can be used to construct a new - parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). - If a function itself is specified (e.g. \code{log} or \code{function(x) - log(x)}) then \code{"t"} is used in the new parameter label to indicate - that the parameter is transformed (e.g. \code{"t(sigma)"}). - - Note: due to partial argument matching \code{transformations} can be - abbreviated for convenience in interactive use (e.g., \code{transform}, - \code{trans}, etc.).} +before plotting. If \code{transformations} is a function or a single string +naming a function then that function will be used to transform all +parameters. To apply transformations to particular parameters, the +\code{transformations} argument can be a named list with length equal to +the number of parameters to be transformed. Currently only univariate +transformations of scalar parameters can be specified (multivariate +transformations will be implemented in a future release). If +\code{transformations} is a list, the name of each list element should be a +parameter name and the content of each list element should be a function +(or any item to match as a function via \code{\link[=match.fun]{match.fun()}}, e.g. a +string naming a function). If a function is specified by its name as a +string (e.g. \code{"log"}), then it can be used to construct a new +parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). +If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate +that the parameter is transformed (e.g. \code{"t(sigma)"}). + +Note: due to partial argument matching \code{transformations} can be +abbreviated for convenience in interactive use (e.g., \code{transform}).} \item{facet_args}{A named list of arguments (other than \code{facets}) passed -to \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} +to \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}} or \code{\link[ggplot2:facet_grid]{ggplot2::facet_grid()}} to control faceting.} \item{...}{Currently ignored.} -\item{binwidth}{Passed to \code{\link[ggplot2]{geom_histogram}} to override +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override the default binwidth.} -\item{breaks}{Passed to \code{\link[ggplot2]{geom_histogram}} as an +\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an alternative to \code{binwidth}.} \item{freq}{For histograms, \code{freq=TRUE} (the default) puts count on the y-axis. Setting \code{freq=FALSE} puts density on the y-axis. (For many plots the y-axis text is off by default. To view the count or density -labels on the y-axis see the \code{\link{yaxis_text}} convenience +labels on the y-axis see the \code{\link[=yaxis_text]{yaxis_text()}} convenience function.)} -\item{trim}{A logical scalar passed to \code{\link[ggplot2]{geom_density}}.} +\item{trim}{A logical scalar passed to \code{\link[ggplot2:geom_density]{ggplot2::geom_density()}}.} -\item{color_chains}{option for whether to separately color chains.} +\item{color_chains}{Option for whether to separately color chains.} \item{bw, adjust, kernel, n_dens}{Optional arguments passed to -\code{\link[stats]{density}} to override default kernel density estimation -parameters. \code{n_dens} defaults to 1024.} +\code{\link[stats:density]{stats::density()}} to override default kernel density estimation +parameters. \code{n_dens} defaults to \code{1024}.} -\item{probs}{A numeric vector passed to \code{\link[ggplot2]{geom_violin}}'s +\item{probs}{A numeric vector passed to \code{\link[ggplot2:geom_violin]{ggplot2::geom_violin()}}'s \code{draw_quantiles} argument to specify at which quantiles to draw horizontal lines. Set to \code{NULL} to remove the lines.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. +A ggplot object that can be further customized using the \strong{ggplot2} package. } \description{ Various types of histograms and kernel density plots of MCMC draws. See the @@ -116,29 +113,29 @@ Various types of histograms and kernel density plots of MCMC draws. See the \section{Plot Descriptions}{ \describe{ - \item{\code{mcmc_hist}}{ - Histograms of posterior draws with all chains merged. - } - \item{\code{mcmc_dens}}{ - Kernel density plots of posterior draws with all chains merged. - } - \item{\code{mcmc_hist_by_chain}}{ - Histograms of posterior draws with chains separated via faceting. - } - \item{\code{mcmc_dens_overlay}}{ - Kernel density plots of posterior draws with chains separated but - overlaid on a single plot. - } - \item{\code{mcmc_violin}}{ - The density estimate of each chain is plotted as a violin with - horizontal lines at notable quantiles. - } - \item{\code{mcmc_dens_chains}}{ - Ridgeline kernel density plots of posterior draws with chains separated - but overlaid on a single plot. In \code{mcmc_dens_overlay} parameters - appear in separate facets; in \code{mcmc_dens_chains} they appear in the - same panel and can overlap vertically. - } +\item{\code{mcmc_hist()}}{ +Histograms of posterior draws with all chains merged. +} +\item{\code{mcmc_dens()}}{ +Kernel density plots of posterior draws with all chains merged. +} +\item{\code{mcmc_hist_by_chain()}}{ +Histograms of posterior draws with chains separated via faceting. +} +\item{\code{mcmc_dens_overlay()}}{ +Kernel density plots of posterior draws with chains separated but +overlaid on a single plot. +} +\item{\code{mcmc_violin()}}{ +The density estimate of each chain is plotted as a violin with +horizontal lines at notable quantiles. +} +\item{\code{mcmc_dens_chains()}}{ +Ridgeline kernel density plots of posterior draws with chains separated +but overlaid on a single plot. In \code{mcmc_dens_overlay()} parameters +appear in separate facets; in \code{mcmc_dens_chains()} they appear in the +same panel and can overlap vertically. +} } } diff --git a/man/MCMC-intervals.Rd b/man/MCMC-intervals.Rd index 9b8941962..dae9479dd 100644 --- a/man/MCMC-intervals.Rd +++ b/man/MCMC-intervals.Rd @@ -46,69 +46,65 @@ the \link{MCMC-overview} page.} \item{pars}{An optional character vector of parameter names. If neither \code{pars} nor \code{regex_pars} is specified then the default is to use -\emph{all} parameters.} +\strong{all} parameters.} -\item{regex_pars}{An optional \link[=grep]{regular expression} to use for +\item{regex_pars}{An optional \link[base:grep]{regular expression} to use for parameter selection. Can be specified instead of \code{pars} or in addition to \code{pars}.} \item{transformations}{Optionally, transformations to apply to parameters - before plotting. If \code{transformations} is a function or a single string - naming a function then that function will be used to transform all - parameters. To apply transformations to particular parameters, the - \code{transformations} argument can be a named list with length equal to - the number of parameters to be transformed. Currently only univariate - transformations of scalar parameters can be specified (multivariate - transformations will be implemented in a future release). If - \code{transformations} is a list, the name of each list element should be a - parameter name and the content of each list element should be a function - (or any item to match as a function via \code{\link{match.fun}}, e.g. a - string naming a function). If a function is specified by its name as a - string (e.g. \code{"log"}), then it can be used to construct a new - parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). - If a function itself is specified (e.g. \code{log} or \code{function(x) - log(x)}) then \code{"t"} is used in the new parameter label to indicate - that the parameter is transformed (e.g. \code{"t(sigma)"}). - - Note: due to partial argument matching \code{transformations} can be - abbreviated for convenience in interactive use (e.g., \code{transform}, - \code{trans}, etc.).} +before plotting. If \code{transformations} is a function or a single string +naming a function then that function will be used to transform all +parameters. To apply transformations to particular parameters, the +\code{transformations} argument can be a named list with length equal to +the number of parameters to be transformed. Currently only univariate +transformations of scalar parameters can be specified (multivariate +transformations will be implemented in a future release). If +\code{transformations} is a list, the name of each list element should be a +parameter name and the content of each list element should be a function +(or any item to match as a function via \code{\link[=match.fun]{match.fun()}}, e.g. a +string naming a function). If a function is specified by its name as a +string (e.g. \code{"log"}), then it can be used to construct a new +parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). +If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate +that the parameter is transformed (e.g. \code{"t(sigma)"}). + +Note: due to partial argument matching \code{transformations} can be +abbreviated for convenience in interactive use (e.g., \code{transform}).} \item{...}{Currently unused.} \item{prob}{The probability mass to include in the inner interval (for -\code{mcmc_intervals}) or in the shaded region (for \code{mcmc_areas}). The +\code{mcmc_intervals()}) or in the shaded region (for \code{mcmc_areas()}). The default is \code{0.5} (50\% interval) and \code{1} for \code{mcmc_areas_ridges}.} \item{prob_outer}{The probability mass to include in the outer interval. The -default is \code{0.9} for \code{mcmc_intervals} (90\% interval) and -\code{1} for \code{mcmc_areas} and for \code{mcmc_areas_ridges}.} +default is \code{0.9} for \code{mcmc_intervals()} (90\% interval) and +\code{1} for \code{mcmc_areas()} and for \code{mcmc_areas_ridges()}.} \item{point_est}{The point estimate to show. Either \code{"median"} (the default), \code{"mean"}, or \code{"none"}.} -\item{rhat}{An optional numeric vector of \eqn{\hat{R}}{Rhat} estimates, with -one element per parameter included in \code{x}. If \code{rhat} is provided, -the intervals/areas and point estimates in the resulting plot are colored -based on \eqn{\hat{R}}{Rhat} value. See \code{\link{rhat}} for methods for -extracting \eqn{\hat{R}}{Rhat} estimates.} +\item{rhat}{An optional numeric vector of R-hat estimates, with one element +per parameter included in \code{x}. If \code{rhat} is provided, the intervals/areas +and point estimates in the resulting plot are colored based on R-hat value. +See \code{\link[=rhat]{rhat()}} for methods for extracting R-hat estimates.} -\item{area_method}{How to constrain the areas in \code{mcmc_areas}. The +\item{area_method}{How to constrain the areas in \code{mcmc_areas()}. The default is \code{"equal area"}, setting the density curves to have the same area. With \code{"equal height"}, the curves are scaled so that the highest -points across the curves are the same height. The method \code{"scaled -height"} tries a compromise between to the two: the heights from +points across the curves are the same height. The method \code{"scaled height"} tries a compromise between to the two: the heights from \code{"equal height"} are scaled using \code{height*sqrt(height)}} \item{bw, adjust, kernel, n_dens}{Optional arguments passed to -\code{\link[stats]{density}} to override default kernel density estimation -parameters. \code{n_dens} defaults to 1024.} +\code{\link[stats:density]{stats::density()}} to override default kernel density estimation +parameters. \code{n_dens} defaults to \code{1024}.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. The \code{_data} functions return the data that - would have been drawn by the plotting function. +A ggplot object that can be further customized using the \strong{ggplot2} +package. The functions with suffix \code{_data} return the data that would have +been drawn by the plotting function. } \description{ Plot central (quantile-based) posterior interval estimates from MCMC draws. @@ -117,19 +113,19 @@ See the \strong{Plot Descriptions} section, below, for details. \section{Plot Descriptions}{ \describe{ - \item{\code{mcmc_intervals}}{ - Plots of uncertainty intervals computed from posterior draws with all - chains merged. - } - \item{\code{mcmc_areas}}{ - Density plots computed from posterior draws with all chains merged, - with uncertainty intervals shown as shaded areas under the curves. - } - \item{\code{mcmc_areas_ridges}}{ - Density plot, as in \code{mcmc_areas}, but drawn with overlapping - ridgelines. This plot provides a compact display of (hierarchically) - related distributions. - } +\item{\code{mcmc_intervals()}}{ +Plots of uncertainty intervals computed from posterior draws with all +chains merged. +} +\item{\code{mcmc_areas()}}{ +Density plots computed from posterior draws with all chains merged, +with uncertainty intervals shown as shaded areas under the curves. +} +\item{\code{mcmc_areas_ridges()}}{ +Density plot, as in \code{mcmc_areas()}, but drawn with overlapping +ridgelines. This plot provides a compact display of (hierarchically) +related distributions. +} } } diff --git a/man/MCMC-nuts.Rd b/man/MCMC-nuts.Rd index 6efe470c4..62387f4ad 100644 --- a/man/MCMC-nuts.Rd +++ b/man/MCMC-nuts.Rd @@ -23,104 +23,104 @@ mcmc_nuts_energy(x, ..., binwidth = NULL, alpha = 0.5, } \arguments{ \item{x}{A molten data frame of NUTS sampler parameters, either created by -\code{\link{nuts_params}} or in the same form as the object returned by -\code{\link{nuts_params}}.} +\code{\link[=nuts_params]{nuts_params()}} or in the same form as the object returned by +\code{\link[=nuts_params]{nuts_params()}}.} \item{lp}{A molten data frame of draws of the log-posterior or, more commonly, of a quantity equal to the log-posterior up to a constant. -\code{lp} should either be created via \code{\link{log_posterior}} or be an +\code{lp} should either be created via \code{\link[=log_posterior]{log_posterior()}} or be an object with the same form as the object returned by -\code{\link{log_posterior}}.} +\code{\link[=log_posterior]{log_posterior()}}.} \item{chain}{A positive integer for selecting a particular chain. The default (\code{NULL}) is to merge the chains before plotting. If \code{chain = k} then the plot for chain \code{k} is overlaid (in a darker shade but with transparency) on top of the plot for all chains. The \code{chain} argument -is not used by \code{mcmc_nuts_energy}.} +is not used by \code{mcmc_nuts_energy()}.} \item{...}{Currently ignored.} -\item{binwidth}{An optional value passed to -\code{\link[ggplot2]{geom_histogram}} to override the default binwidth.} +\item{binwidth}{An optional value passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to +override the default binwidth.} -\item{alpha}{For \code{mcmc_nuts_energy} only, the transparency (alpha) level -in [0,1] used for the overlaid histogram.} +\item{alpha}{For \code{mcmc_nuts_energy()} only, the transparency (alpha) level +in \code{[0,1]} used for the overlaid histogram.} -\item{merge_chains}{For \code{mcmc_nuts_energy} only, should all chains be +\item{merge_chains}{For \code{mcmc_nuts_energy()} only, should all chains be merged or displayed separately? The default is \code{FALSE}, i.e., to show the chains separately.} } \value{ A gtable object (the result of calling - \code{\link[gridExtra]{arrangeGrob}}) created from several ggplot objects, - except for \code{mcmc_nuts_energy}, which returns a ggplot object. +\code{\link[gridExtra:arrangeGrob]{gridExtra::arrangeGrob()}}) created from several ggplot objects, +except for \code{mcmc_nuts_energy()}, which returns a ggplot object. } \description{ Diagnostic plots for the No-U-Turn-Sampler (NUTS), the default MCMC algorithm -used by Stan. See the \strong{Plot Descriptions} section, below. +used by \href{https://mc-stan.org}{Stan}. See the \strong{Plot Descriptions} section, below. } \section{Quick Definitions}{ For more details see Stan Development Team (2016) and Betancourt (2017). \itemize{ - \item \code{accept_stat__}: the average acceptance probabilities of all - possible samples in the proposed tree. - \item \code{divergent__}: the number of leapfrog transitions with diverging - error. Because NUTS terminates at the first divergence this will be either - 0 or 1 for each iteration. - \item \code{stepsize__}: the step size used by NUTS in its Hamiltonian - simulation. - \item \code{treedepth__}: the depth of tree used by NUTS, which is the log - (base 2) of the number of leapfrog steps taken during the Hamiltonian - simulation. - \item \code{energy__}: the value of the Hamiltonian (up to an additive - constant) at each iteration. +\item \code{accept_stat__}: the average acceptance probabilities of all +possible samples in the proposed tree. +\item \code{divergent__}: the number of leapfrog transitions with diverging +error. Because NUTS terminates at the first divergence this will be either +0 or 1 for each iteration. +\item \code{stepsize__}: the step size used by NUTS in its Hamiltonian +simulation. +\item \code{treedepth__}: the depth of tree used by NUTS, which is the log +(base 2) of the number of leapfrog steps taken during the Hamiltonian +simulation. +\item \code{energy__}: the value of the Hamiltonian (up to an additive +constant) at each iteration. } } \section{Plot Descriptions}{ \describe{ - \item{\code{mcmc_nuts_acceptance}}{ - Three plots: - \itemize{ - \item Histogram of \code{accept_stat__} with vertical lines indicating the - mean (solid line) and median (dashed line). - \item Histogram of \code{lp__} with vertical - lines indicating the mean (solid line) and median (dashed line). - \item Scatterplot of \code{accept_stat__} vs \code{lp__}. - } - } - \item{\code{mcmc_nuts_divergence}}{ - Two plots: - \itemize{ - \item Violin plots of \code{lp__|divergent__=1} and - \code{lp__|divergent__=0}. - \item Violin plots of \code{accept_stat__|divergent__=1} and - \code{accept_stat__|divergent__=0}. - } - } - \item{\code{mcmc_nuts_stepsize}}{ - Two plots: - \itemize{ - \item Violin plots of \code{lp__} by chain ordered by - \code{stepsize__} value. - \item Violin plots of \code{accept_stat__} by chain ordered by - \code{stepsize__} value. - } - } - \item{\code{mcmc_nuts_treedepth}}{ - Three plots: - \itemize{ - \item Violin plots of \code{lp__} by value of \code{treedepth__}. - \item Violin plots of \code{accept_stat__} by value of \code{treedepth__}. - \item Histogram of \code{treedepth__}. - } - } - \item{\code{mcmc_nuts_energy}}{ - Overlaid histograms showing \code{energy__} vs the change in - \code{energy__}. See Betancourt (2016) for details. - } +\item{\code{mcmc_nuts_acceptance()}}{ +Three plots: +\itemize{ +\item Histogram of \code{accept_stat__} with vertical lines indicating the +mean (solid line) and median (dashed line). +\item Histogram of \code{lp__} with vertical +lines indicating the mean (solid line) and median (dashed line). +\item Scatterplot of \code{accept_stat__} vs \code{lp__}. +} +} + +\item{\code{mcmc_nuts_divergence()}}{ +Two plots: +\itemize{ +\item Violin plots of \code{lp__|divergent__=1} and \code{lp__|divergent__=0}. +\item Violin plots of \code{accept_stat__|divergent__=1} and \code{accept_stat__|divergent__=0}. +} +} + +\item{\code{mcmc_nuts_stepsize()}}{ +Two plots: +\itemize{ +\item Violin plots of \code{lp__} by chain ordered by \code{stepsize__} value. +\item Violin plots of \code{accept_stat__} by chain ordered by \code{stepsize__} value. +} +} + +\item{\code{mcmc_nuts_treedepth()}}{ +Three plots: +\itemize{ +\item Violin plots of \code{lp__} by value of \code{treedepth__}. +\item Violin plots of \code{accept_stat__} by value of \code{treedepth__}. +\item Histogram of \code{treedepth__}. +} +} + +\item{\code{mcmc_nuts_energy()}}{ +Overlaid histograms showing \code{energy__} vs the change in +\code{energy__}. See Betancourt (2016) for details. +} } } @@ -152,34 +152,35 @@ mcmc_nuts_energy(np) + } \references{ Betancourt, M. (2017). A conceptual introduction to Hamiltonian Monte Carlo. - \url{https://arxiv.org/abs/1701.02434} +\url{https://arxiv.org/abs/1701.02434} Betancourt, M. and Girolami, M. (2013). Hamiltonian Monte Carlo for hierarchical models. \url{https://arxiv.org/abs/1312.0906} Hoffman, M. D. and Gelman, A. (2014). The No-U-Turn Sampler: - adaptively setting path lengths in Hamiltonian Monte Carlo. \emph{Journal - of Machine Learning Research}. 15:1593--1623. +adaptively setting path lengths in Hamiltonian Monte Carlo. +\emph{Journal of Machine Learning Research}. 15:1593--1623. -Stan Development Team. \emph{Stan Modeling Language Users -Guide and Reference Manual.} \url{https://mc-stan.org/users/documentation/} +Stan Development Team. +\emph{Stan Modeling Language Users Guide and Reference Manual.} +\url{https://mc-stan.org/users/documentation/} } \seealso{ \itemize{ -\item The \emph{Visual MCMC Diagnostics} vignette. -\item Several other plotting functions in the \pkg{bayesplot} package -are not NUTS-specific but take optional extra arguments if the model was fit -using NUTS: +\item The \href{https://mc-stan.org/bayesplot/articles/visual-mcmc-diagnostics.html}{Visual MCMC Diagnostics} +vignette. +\item Several other plotting functions are not NUTS-specific but take optional +extra arguments if the model was fit using NUTS: \itemize{ - \item \code{\link{mcmc_trace}}: show divergences as tick marks below the - trace plot. - \item \code{\link{mcmc_parcoord}}: change the color/size/transparency of - lines correspondending to divergences. - \item \code{\link{mcmc_scatter}}: change the color/size/shape of points - corresponding to divergences. - \item \code{\link{mcmc_pairs}}: change the color/size/shape of points - corresponding divergences and/or max treedepth saturation. - } +\item \code{\link[=mcmc_trace]{mcmc_trace()}}: show divergences as tick marks below the +trace plot. +\item \code{\link[=mcmc_parcoord]{mcmc_parcoord()}}: change the color/size/transparency of lines +correspondending to divergences. +\item \code{\link[=mcmc_scatter]{mcmc_scatter()}}: change the color/size/shape of points +corresponding to divergences. +\item \code{\link[=mcmc_pairs]{mcmc_pairs()}}: change the color/size/shape of points +corresponding divergences and/or max treedepth saturation. +} } Other MCMC: \code{\link{MCMC-combos}}, diff --git a/man/MCMC-overview.Rd b/man/MCMC-overview.Rd index 16290e685..8b3d4ced4 100644 --- a/man/MCMC-overview.Rd +++ b/man/MCMC-overview.Rd @@ -5,81 +5,66 @@ \alias{MCMC} \title{Plots for Markov chain Monte Carlo simulations} \description{ -The \pkg{bayesplot} MCMC module provides various plotting functions for +The \strong{bayesplot} MCMC module provides various plotting functions for creating graphical displays of Markov chain Monte Carlo (MCMC) simulations. The \strong{MCMC plotting functions} section, below, provides links to the documentation for various categories of MCMC plots. Currently the MCMC plotting functions accept posterior draws provided in one of the following formats: \itemize{ - \item \strong{3-D array}: An \code{\link{array}} with dimensions - \code{[Iteration, Chain, Parameter]} in that order. - \item \strong{list}: A \code{list} of matrices, where each matrix - corresponds to a Markov chain. All of the matrices should have the same - number of iterations (rows) and parameters (columns), and parameters should - have the same names and be in the same order. - \item \strong{matrix (2-D array)}: A \code{\link{matrix}} with one column - per parameter. If using matrix there should only be a single Markov chain or - all chains should already be merged (stacked). - \item \strong{data frame}: There are two types of \link[=data.frame]{data - frames} allowed. Either a data frame with one column per parameter (if only - a single chain or all chains have already been merged), or a data frame with - one column per parameter plus an additional column \code{"Chain"} that - contains the chain number (an integer) corresponding to each row in - the data frame. -} +\item \strong{3-D array}: An array with dimensions \code{[Iteration, Chain, Parameter]} +in that order. +\item \strong{list}: A list of matrices, where each matrix corresponds to a Markov +chain. All of the matrices should have the same number of iterations (rows) +and parameters (columns), and parameters should have the same names and be +in the same order. +\item \strong{matrix (2-D array)}: A matrix with one column per parameter. If using +matrix there should only be a single Markov chain or all chains should +already be merged (stacked). +\item \strong{data frame}: There are two types of \link[base:data.frame]{data frames} +allowed. Either a data frame with one column per parameter (if only a single +chain or all chains have already been merged), or a data frame with one +column per parameter plus an additional column \code{"Chain"} that contains the +chain number (an integer) corresponding to each row in the data frame. \strong{Note}: typically the user should \emph{not} include warmup iterations -in the object passed to \pkg{bayesplot} plotting functions, although for +in the object passed to \strong{bayesplot} plotting functions, although for certain plots (e.g. trace plots) it can occasionally be useful to include the warmup iterations for diagnostic purposes. } +} \section{MCMC plotting functions}{ - -\describe{ - \item{\strong{\link[=MCMC-distributions]{Posterior distributions}}}{ - Histograms and kernel density plots of parameter draws, optionally - showing each Markov chain separately. - } - \item{\strong{\link[=MCMC-intervals]{Uncertainty intervals}}}{ - Uncertainty intervals computed from parameter draws. - } - \item{\strong{\link[=MCMC-traces]{Trace plots}}}{ - Times series of parameter draws, optionally including with HMC/NUTS - diagnostic information. - } - \item{\strong{\link[=MCMC-scatterplots]{Scatterplots}}}{ - Scatterplots, heatmaps, and pairs plots of parameter draws, optionally - including with HMC/NUTS diagnostic information. - } - \item{\strong{\link[=MCMC-parcoord]{Parallel coordinates plots}}}{ - Parallel coordinates plot of MCMC draws (one dimension per parameter), - optionally including with HMC/NUTS diagnostic information. - } - \item{\strong{\link[=MCMC-combos]{Combinations}}}{ - Combination plots (e.g. trace plot + histogram). - } - \item{\strong{\link[=MCMC-diagnostics]{General MCMC diagnostics}}}{ - MCMC diagnostic plots including Rhat, effective sample size, - autocorrelation. - } - \item{\strong{\link[=MCMC-nuts]{NUTS diagnostics}}}{ - Special diagnostic plots for the No-U-Turn Sampler. - } - \item{\strong{\link[=MCMC-recover]{Comparisons to "true" values}}}{ - Plots comparing MCMC estimates to "true" parameter values (e.g., - values used to simulate data). - } +\itemize{ +\item \link[=MCMC-distributions]{Posterior distributions}: +Histograms and kernel density plots of parameter draws, optionally +showing each Markov chain separately. +\item \link[=MCMC-intervals]{Uncertainty intervals}: Uncertainty intervals computed +from parameter draws. +\item \link[=MCMC-traces]{Trace plots}: Times series of parameter draws, optionally +including with HMC/NUTS diagnostic information. +\item \link[=MCMC-scatterplots]{Scatterplots}: Scatterplots, heatmaps, and pairs +plots of parameter draws, optionally including with HMC/NUTS diagnostic +information. +\item \link[=MCMC-parcoord]{Parallel coordinates plots}: Parallel coordinates plot +of MCMC draws (one dimension per parameter), optionally including with +HMC/NUTS diagnostic information. +\item \link[=MCMC-combos]{Combos}: Combination plots (e.g. trace plot + histogram). +\item \link[=MCMC-diagnostics]{General MCMC diagnostics}: MCMC diagnostic plots +including R-hat, effective sample size, autocorrelation. +\link[=MCMC-nuts]{NUTS diagnostics}: Special diagnostic plots for +the No-U-Turn Sampler. +\item \link[=MCMC-recover]{Comparisons to "true" values}: Plots comparing MCMC +estimates to "true" parameter values (e.g., values used to simulate data). } } \references{ Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and - Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. - Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, - (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, - \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, - \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +Gelman, A. (2019), Visualization in Bayesian workflow. +\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378. +(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, +\href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, +\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) } \seealso{ Other MCMC: \code{\link{MCMC-combos}}, diff --git a/man/MCMC-parcoord.Rd b/man/MCMC-parcoord.Rd index a7ffb0c6d..c00125886 100644 --- a/man/MCMC-parcoord.Rd +++ b/man/MCMC-parcoord.Rd @@ -25,90 +25,86 @@ the \link{MCMC-overview} page.} \item{pars}{An optional character vector of parameter names. If neither \code{pars} nor \code{regex_pars} is specified then the default is to use -\emph{all} parameters.} +\strong{all} parameters.} -\item{regex_pars}{An optional \link[=grep]{regular expression} to use for +\item{regex_pars}{An optional \link[base:grep]{regular expression} to use for parameter selection. Can be specified instead of \code{pars} or in addition to \code{pars}.} \item{transformations}{Optionally, transformations to apply to parameters - before plotting. If \code{transformations} is a function or a single string - naming a function then that function will be used to transform all - parameters. To apply transformations to particular parameters, the - \code{transformations} argument can be a named list with length equal to - the number of parameters to be transformed. Currently only univariate - transformations of scalar parameters can be specified (multivariate - transformations will be implemented in a future release). If - \code{transformations} is a list, the name of each list element should be a - parameter name and the content of each list element should be a function - (or any item to match as a function via \code{\link{match.fun}}, e.g. a - string naming a function). If a function is specified by its name as a - string (e.g. \code{"log"}), then it can be used to construct a new - parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). - If a function itself is specified (e.g. \code{log} or \code{function(x) - log(x)}) then \code{"t"} is used in the new parameter label to indicate - that the parameter is transformed (e.g. \code{"t(sigma)"}). - - Note: due to partial argument matching \code{transformations} can be - abbreviated for convenience in interactive use (e.g., \code{transform}, - \code{trans}, etc.).} +before plotting. If \code{transformations} is a function or a single string +naming a function then that function will be used to transform all +parameters. To apply transformations to particular parameters, the +\code{transformations} argument can be a named list with length equal to +the number of parameters to be transformed. Currently only univariate +transformations of scalar parameters can be specified (multivariate +transformations will be implemented in a future release). If +\code{transformations} is a list, the name of each list element should be a +parameter name and the content of each list element should be a function +(or any item to match as a function via \code{\link[=match.fun]{match.fun()}}, e.g. a +string naming a function). If a function is specified by its name as a +string (e.g. \code{"log"}), then it can be used to construct a new +parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). +If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate +that the parameter is transformed (e.g. \code{"t(sigma)"}). + +Note: due to partial argument matching \code{transformations} can be +abbreviated for convenience in interactive use (e.g., \code{transform}).} \item{...}{Currently ignored.} -\item{size, alpha}{Arguments passed on to \code{\link[ggplot2]{geom_line}}.} +\item{size, alpha}{Arguments passed on to \code{\link[ggplot2:geom_line]{ggplot2::geom_line()}}.} -\item{np}{For models fit using \code{\link{NUTS}} (more generally, -any \href{https://en.wikipedia.org/wiki/Symplectic_integrator}{symplectic -integrator}), an optional data frame providing NUTS -diagnostic information. The data frame should be the object returned by -\code{\link{nuts_params}} or one with the same structure.} +\item{np}{For models fit using \link{NUTS} (more generally, +any \href{https://en.wikipedia.org/wiki/Symplectic_integrator}{symplectic integrator}), +an optional data frame providing NUTS diagnostic information. The data +frame should be the object returned by \code{\link[=nuts_params]{nuts_params()}} or one with the same +structure.} -\item{np_style}{A call to the \code{parcoord_style_np} helper function to +\item{np_style}{A call to the \code{parcoord_style_np()} helper function to specify arguments controlling the appearance of superimposed lines representing NUTS diagnostics (in this case divergences) if the \code{np} argument is specified.} \item{div_color, div_size, div_alpha}{Optional arguments to the -\code{parcoord_style_np} helper function that are eventually passed to -\code{\link[ggplot2]{geom_line}} if the \code{np} argument is also -specified. They control the color, size, and transparency specifications -for showing divergences in the plot. The default values are displayed in -the \strong{Usage} section above.} +\code{parcoord_style_np()} helper function that are eventually passed to +\code{\link[ggplot2:geom_line]{ggplot2::geom_line()}} if the \code{np} argument is also specified. They control +the color, size, and transparency specifications for showing divergences in +the plot. The default values are displayed in the \strong{Usage} section above.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. The \code{_data} functions return the data that - would have been drawn by the plotting function. +A ggplot object that can be further customized using the \strong{ggplot2} +package. The functions with suffix \code{_data} return the data that would have +been drawn by the plotting function. } \description{ -Parallel coordinates plot of MCMC draws (one dimension per parameter). See -the \strong{Plot Descriptions} section below for details, and see -\href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)} +Parallel coordinates plot of MCMC draws (one dimension per parameter). +See the \strong{Plot Descriptions} section below for details, +and see \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)} for more background and a real example. } \section{Plot Descriptions}{ \describe{ - \item{\code{mcmc_parcoord}}{ - (\href{https://en.wikipedia.org/wiki/Parallel_coordinates}{Parallel - coordinates plot}) of MCMC draws. There is one dimension per parameter - along the horizontal axis and each set of connected line segments - represents a single MCMC draw (i.e., a vector of length equal to the - number of parameters). - - The parallel coordinates plot is most useful if the optional HMC/NUTS - diagnostic information is provided via the \code{np} argument. In that - case divergences are highlighted in the plot. The appearance of the - divergences can be customized using the \code{np_style} argument and the - \code{parcoord_style_np} helper function. This version of the plot is the - same as the parallel coordinates plot described in Gabry et al. (2019). - - When the plotted model parameters are on very different scales the - \code{transformations} argument can be useful. For example, to standardize - all variables before plotting you could use function \code{(x - - mean(x))/sd(x)} when specifying the \code{transformations} argument to - \code{mcmc_parcoord}. See the \strong{Examples} section for how to do this. - } +\item{\code{mcmc_parcoord()}}{ +\href{https://en.wikipedia.org/wiki/Parallel_coordinates}{Parallel coordinates plot} +of MCMC draws. There is one dimension per parameter along the horizontal +axis and each set of connected line segments represents a single MCMC draw +(i.e., a vector of length equal to the number of parameters). + +The parallel coordinates plot is most useful if the optional HMC/NUTS +diagnostic information is provided via the \code{np} argument. In that +case divergences are highlighted in the plot. The appearance of the +divergences can be customized using the \code{np_style} argument and the +\code{parcoord_style_np} helper function. This version of the plot is the +same as the parallel coordinates plot described in Gabry et al. (2019). + +When the plotted model parameters are on very different scales the +\code{transformations} argument can be useful. For example, to standardize +all variables before plotting you could use function \code{(x - mean(x))/sd(x)} +when specifying the \code{transformations} argument to +\code{mcmc_parcoord}. See the \strong{Examples} section for how to do this. +} } } @@ -158,14 +154,14 @@ tail(d) } \references{ Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and - Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. - Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, - (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, - \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, - \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +Gelman, A. (2019), Visualization in Bayesian workflow. +\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378. +(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, +\href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, +\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) Hartikainen, A. (2017, Aug 23). Concentration of divergences -[Msg 21]. Message posted to The Stan Forums: +(Msg 21). Message posted to The Stan Forums: \url{https://discourse.mc-stan.org/t/concentration-of-divergences/1590/21}. } \seealso{ diff --git a/man/MCMC-recover.Rd b/man/MCMC-recover.Rd index e6b12d22d..950c9826b 100644 --- a/man/MCMC-recover.Rd +++ b/man/MCMC-recover.Rd @@ -38,10 +38,10 @@ in the same facet in the plot (see the \strong{Examples} section, below). The default is to group all parameters together into a single batch. Changing the default is most useful when parameters are on very different scales, in which case \code{batch} can be used to group them into batches -within which it makes sense to use the same \eqn{y}-axis.} +within which it makes sense to use the same y-axis.} \item{facet_args}{A named list of arguments (other than \code{facets}) passed -to \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} +to \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}} or \code{\link[ggplot2:facet_grid]{ggplot2::facet_grid()}} to control faceting.} \item{...}{Currently unused.} @@ -55,18 +55,17 @@ default is \code{0.9} (90\% interval).} \item{point_est}{The point estimate to show. Either \code{"median"} (the default), \code{"mean"}, or \code{"none"}.} -\item{size, alpha}{Passed to \code{\link[ggplot2]{geom_point}} to control the +\item{size, alpha}{Passed to \code{\link[ggplot2:geom_point]{ggplot2::geom_point()}} to control the appearance of plotted points.} -\item{binwidth}{Passed to \code{\link[ggplot2]{geom_histogram}} to override +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override the default binwidth.} -\item{breaks}{Passed to \code{\link[ggplot2]{geom_histogram}} as an +\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an alternative to \code{binwidth}.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. +A ggplot object that can be further customized using the \strong{ggplot2} package. } \description{ Plots comparing MCMC estimates to "true" parameter values. Before fitting a @@ -79,17 +78,17 @@ available plots. \section{Plot Descriptions}{ \describe{ - \item{\code{mcmc_recover_intervals}}{ - Central intervals and point estimates computed from MCMC draws, with - "true" values plotted using a different shape. - } - \item{\code{mcmc_recover_scatter}}{ - Scatterplot of posterior means (or medians) against "true" values. - } - \item{\code{mcmc_recover_hist}}{ - Histograms of the draws for each parameter with the "true" value overlaid - as a vertical line. - } +\item{\code{mcmc_recover_intervals()}}{ +Central intervals and point estimates computed from MCMC draws, with +"true" values plotted using a different shape. +} +\item{\code{mcmc_recover_scatter()}}{ +Scatterplot of posterior means (or medians) against "true" values. +} +\item{\code{mcmc_recover_hist()}}{ +Histograms of the draws for each parameter with the "true" value overlaid +as a vertical line. +} } } diff --git a/man/MCMC-scatterplots.Rd b/man/MCMC-scatterplots.Rd index 2891d80c6..247891b56 100644 --- a/man/MCMC-scatterplots.Rd +++ b/man/MCMC-scatterplots.Rd @@ -41,149 +41,147 @@ allowed inputs. It is also possible to use an object with an the \link{MCMC-overview} page.} \item{pars}{An optional character vector of parameter names. For -\code{mcmc_scatter} and \code{mcmc_hex} only two parameters can be -selected. To plot more than two parameters use \code{mcmc_pairs}.} +\code{mcmc_scatter()} and \code{mcmc_hex()} only two parameters can be +selected. To plot more than two parameters use \code{mcmc_pairs()}.} -\item{regex_pars}{An optional \link[=grep]{regular expression} to use for +\item{regex_pars}{An optional \link[base:grep]{regular expression} to use for parameter selection. Can be specified instead of \code{pars} or in addition to \code{pars}.} \item{transformations}{Optionally, transformations to apply to parameters - before plotting. If \code{transformations} is a function or a single string - naming a function then that function will be used to transform all - parameters. To apply transformations to particular parameters, the - \code{transformations} argument can be a named list with length equal to - the number of parameters to be transformed. Currently only univariate - transformations of scalar parameters can be specified (multivariate - transformations will be implemented in a future release). If - \code{transformations} is a list, the name of each list element should be a - parameter name and the content of each list element should be a function - (or any item to match as a function via \code{\link{match.fun}}, e.g. a - string naming a function). If a function is specified by its name as a - string (e.g. \code{"log"}), then it can be used to construct a new - parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). - If a function itself is specified (e.g. \code{log} or \code{function(x) - log(x)}) then \code{"t"} is used in the new parameter label to indicate - that the parameter is transformed (e.g. \code{"t(sigma)"}). - - Note: due to partial argument matching \code{transformations} can be - abbreviated for convenience in interactive use (e.g., \code{transform}, - \code{trans}, etc.).} +before plotting. If \code{transformations} is a function or a single string +naming a function then that function will be used to transform all +parameters. To apply transformations to particular parameters, the +\code{transformations} argument can be a named list with length equal to +the number of parameters to be transformed. Currently only univariate +transformations of scalar parameters can be specified (multivariate +transformations will be implemented in a future release). If +\code{transformations} is a list, the name of each list element should be a +parameter name and the content of each list element should be a function +(or any item to match as a function via \code{\link[=match.fun]{match.fun()}}, e.g. a +string naming a function). If a function is specified by its name as a +string (e.g. \code{"log"}), then it can be used to construct a new +parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). +If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate +that the parameter is transformed (e.g. \code{"t(sigma)"}). + +Note: due to partial argument matching \code{transformations} can be +abbreviated for convenience in interactive use (e.g., \code{transform}).} \item{...}{Currently ignored.} -\item{size, alpha}{For \code{mcmc_scatter}, passed to -\code{\link[ggplot2]{geom_point}} to control the appearance of the points.} +\item{size, alpha}{For \code{mcmc_scatter()}, passed to +\code{\link[ggplot2:geom_point]{ggplot2::geom_point()}} to control the appearance of the points.} \item{np}{Optionally, a data frame of NUTS sampler parameters, either created -by \code{\link{nuts_params}} or in the same form as the object returned by -\code{\link{nuts_params}}. The colors, shapes, and sizes of the +by \code{\link[=nuts_params]{nuts_params()}} or in the same form as the object returned by +\code{\link[=nuts_params]{nuts_params()}}. The colors, shapes, and sizes of the superimposed points can be customized using the \code{np_style} argument.} \item{np_style}{If \code{np} is specified, \code{np_style} can be a call to -the \code{scatter_style_np} helper function (for \code{mcmc_scatter}) or -the \code{pairs_style_np} helper function (for \code{mcmc_pars}) to specify +the \code{scatter_style_np()} helper function (for \code{mcmc_scatter()}) or +the \code{pairs_style_np()} helper function (for \code{mcmc_pairs()}) to specify arguments controlling the appearance of superimposed points representing -NUTS diagnostic information. (Note: for \code{pairs_style_np} the +NUTS diagnostic information. (Note: for \code{pairs_style_np()} the \code{size} arguments are interpreted as scaling factors).} -\item{binwidth}{For \code{mcmc_hex}, an optional numeric vector of -\emph{length two} passed to \code{\link[ggplot2]{geom_hex}} to override the +\item{binwidth}{For \code{mcmc_hex()}, an optional numeric vector of +\emph{length two} passed to \code{\link[ggplot2:geom_hex]{ggplot2::geom_hex()}} to override the default binwidth in both the vertical and horizontal directions.} -\item{diag_fun, off_diag_fun}{For \code{mcmc_pairs}, the plotting function to +\item{diag_fun, off_diag_fun}{For \code{mcmc_pairs()}, the plotting function to use for the plots along the diagonal and for the off-diagonal plots, respectively. Currently \code{diag_fun} can be \code{"hist"} for histogram or \code{"dens"} for density, and \code{off_diag_fun} can be \code{"scatter"} for scatterplot or \code{"hex"} for a hexagonal heatmap.} -\item{diag_args, off_diag_args}{For \code{mcmc_pairs}, optional named lists of +\item{diag_args, off_diag_args}{For \code{mcmc_pairs()}, optional named lists of arguments to pass to the functions implied by the \code{diag_fun} and \code{off_diag_fun} arguments, respectively. For example, if \code{off_diag_fun} is \code{"scatter"} then \code{off_diag_args} could -include optional arguments to \code{mcmc_scatter} like \code{size} and +include optional arguments to \code{mcmc_scatter()} like \code{size} and \code{alpha}.} -\item{condition}{For \code{mcmc_pairs}, a call to the \code{pairs_condition} +\item{condition}{For \code{mcmc_pairs()}, a call to the \code{pairs_condition()} helper function, which is used to specify a criterion for determining which chains (or iterations) are shown in the plots above the diagonal and which are shown in the plots below the diagonal. The histograms (or density plots) along the diagonal are always made using all chains and iterations, but the scatterplots (or hex plots) above and below the diagonal show different combinations of chains/iterations depending on \code{condition}. -The default is a call to \code{pairs_condition} with none of its arguments +The default is a call to \code{pairs_condition()} with none of its arguments specified. In this case half of the chains (or roughly half if there are an odd number) will be used in the plots above the diagonal and the rest in the plots below the diagonal. The \code{chains}, \code{draws}, and -\code{nuts} arguments to \code{pairs_condition}, which are documented +\code{nuts} arguments to \code{pairs_condition()}, which are documented below, can be used to change this default.} -\item{lp}{For \code{mcmc_pairs}, a molten data frame of draws of the +\item{lp}{For \code{mcmc_pairs()}, a molten data frame of draws of the log-posterior or, more commonly, of a quantity equal to the log-posterior up to a constant. \code{lp} should either be created via -\code{\link{log_posterior}} or be an object with the same form as the -object returned by \code{\link{log_posterior}}.} +\code{\link[=log_posterior]{log_posterior()}} or be an object with the same form as the +object returned by \code{\link[=log_posterior]{log_posterior()}}.} -\item{max_treedepth}{For \code{mcmc_pairs}, an integer representing the +\item{max_treedepth}{For \code{mcmc_pairs()}, an integer representing the maximum treedepth allowed when fitting the model (if fit using NUTS). This is only needed for detecting which transitions (if any) hit the maximum treedepth.} -\item{grid_args, save_gg_objects}{For \code{mcmc_pairs}, arguments to pass to -\code{\link{bayesplot_grid}}. For example, since \code{mcmc_pairs} returns -more than a single ggplot object, using \code{\link{ggtitle}} afterwards +\item{grid_args, save_gg_objects}{For \code{mcmc_pairs()}, arguments to pass to +\code{\link[=bayesplot_grid]{bayesplot_grid()}}. For example, since \code{mcmc_pairs()} returns +more than a single ggplot object, using \code{\link[=ggtitle]{ggtitle()}} afterwards will not work. But you you can still add a title to the plot using \code{grid_args = list(top="My title")}.} -\item{div_color, div_shape, div_size, div_alpha, td_color, td_shape, td_size, td_alpha}{Optional arguments to the \code{scatter_style_np} or \code{pairs_style_np} +\item{div_color, div_shape, div_size, div_alpha, td_color, td_shape, td_size, td_alpha}{Optional arguments to the \code{scatter_style_np()} or \code{pairs_style_np()} helper functions that are eventually passed to -\code{\link[ggplot2]{geom_point}}.The default values are displayed in the +\code{\link[ggplot2:geom_point]{ggplot2::geom_point()}}.The default values are displayed in the \strong{Usage} section above.} -\item{chains, draws, nuts}{Optional arguments to the \code{pairs_condition} - helper function, which is used to specify the \code{condition} argument for - \code{mcmc_pairs}. +\item{chains, draws, nuts}{Optional arguments to the \code{pairs_condition()} +helper function, which is used to specify the \code{condition} argument for +\code{mcmc_pairs()}. \itemize{ - \item The \code{chains} argument can be used to select some subset of the - chains. If \code{chains} is an integer vector then the behavior is the same - as the default (half the chains above the diagonal and half below) except - using only the specified subset of chains. Alternatively, \code{chains} can - be a list of two integer vectors with the first specifying the chains to be - shown in the plots above the diagonal and the second for below the - diagonal. - \item The \code{draws} argument to \code{pairs_condition} can be used to - directly specify which realizations are plotted above and below the - diagonal. \code{draws} can be a single proportion, which is interpreted as - the proportion of realizations (among all chains) to plot in the lower - panel starting with the first realization in each chain, with the - complement (from the end of each chain) plotted in the upper panel. - Alternatively \code{draws} can be a logical vector with length equal to the - product of the number of iterations and the number of chains, in which case - realizations corresponding to \code{FALSE} and \code{TRUE} will be plotted - in the lower and upper panels, respectively. - \item For models fit using NUTS, the \code{nuts} argument to - \code{pairs_condition} can be used. It takes a (possibly abbreviated) - string to select among \code{"accept_stat__"}, \code{"stepsize__"}, - \code{"treedepth__"}, \code{"n_leapfrog__"}, \code{"divergent__"}, - \code{"energy__"}, and \code{"lp__"}. These are the sampler parameters - associated with \code{\link{NUTS}} (and \code{"lp__"} is the log-posterior - up to an additive constant). In this case, plots below the diagonal will - contain realizations that are below the median of the indicated variable - (or are zero in the case of \code{"divergent__"}), and plots above the - diagonal will contain realizations that are greater than or equal to the - median of the indicated variable (or are one in the case of - \code{"divergent__"}). If \code{"lp__"} is used then the \code{lp} - argument to \code{mcmc_pairs} must also be specified. For the other NUTS - parameters the \code{np} argument to \code{mcmc_pairs} must also be - specified. - }} +\item The \code{chains} argument can be used to select some subset of the +chains. If \code{chains} is an integer vector then the behavior is the same +as the default (half the chains above the diagonal and half below) except +using only the specified subset of chains. Alternatively, \code{chains} can +be a list of two integer vectors with the first specifying the chains to be +shown in the plots above the diagonal and the second for below the +diagonal. +\item The \code{draws} argument to \code{pairs_condition()} can be used to +directly specify which realizations are plotted above and below the +diagonal. \code{draws} can be a single proportion, which is interpreted as +the proportion of realizations (among all chains) to plot in the lower +panel starting with the first realization in each chain, with the +complement (from the end of each chain) plotted in the upper panel. +Alternatively \code{draws} can be a logical vector with length equal to the +product of the number of iterations and the number of chains, in which case +realizations corresponding to \code{FALSE} and \code{TRUE} will be plotted +in the lower and upper panels, respectively. +\item For models fit using NUTS, the \code{nuts} argument to +\code{pairs_condition()} can be used. It takes a (possibly abbreviated) +string to select among \code{"accept_stat__"}, \code{"stepsize__"}, +\code{"treedepth__"}, \code{"n_leapfrog__"}, \code{"divergent__"}, +\code{"energy__"}, and \code{"lp__"}. These are the sampler parameters +associated with \code{\link[=NUTS]{NUTS()}} (and \code{"lp__"} is the log-posterior +up to an additive constant). In this case, plots below the diagonal will +contain realizations that are below the median of the indicated variable +(or are zero in the case of \code{"divergent__"}), and plots above the +diagonal will contain realizations that are greater than or equal to the +median of the indicated variable (or are one in the case of +\code{"divergent__"}). If \code{"lp__"} is used then the \code{lp} +argument to \code{mcmc_pairs} must also be specified. For the other NUTS +parameters the \code{np} argument to \code{mcmc_pairs()} must also be +specified. +}} } \value{ -\code{mcmc_scatter} and \code{mcmc_hex} return a ggplot object that - can be further customized using the \pkg{ggplot2} package. +\code{mcmc_scatter()} and \code{mcmc_hex()} return a ggplot object that +can be further customized using the \strong{ggplot2} package. - \code{mcmc_pairs} returns many ggplot objects organized into a grid via - \code{\link{bayesplot_grid}}. +\code{mcmc_pairs()} returns many ggplot objects organized into a grid via +\code{\link[=bayesplot_grid]{bayesplot_grid()}}. } \description{ Scatterplots, hexagonal heatmaps, and pairs plots from MCMC draws. See the @@ -192,44 +190,43 @@ Scatterplots, hexagonal heatmaps, and pairs plots from MCMC draws. See the \section{Plot Descriptions}{ \describe{ - \item{\code{mcmc_scatter}}{ - Bivariate scatterplot of posterior draws. If using a very large number of - posterior draws then \code{mcmc_hex} may be preferable to avoid - overplotting. For models fit using \code{\link{NUTS}} the \code{np}, - and \code{np_style} arguments can be used to add additional information in - the plot (in this case the approximate location of divergences). - For an example of why the scatter plot with divergences is a useful - diagnostic tool see \href{https://github.com/jgabry/bayes-vis-paper}{Gabry - et al. (2019)}. - } - \item{\code{mcmc_hex}}{ - Hexagonal heatmap of 2-D bin counts. This plot is useful in cases where - the posterior sample size is large enough that \code{mcmc_scatter} suffers - from overplotting. - } - \item{\code{mcmc_pairs}}{ - A square plot matrix with univariate marginal distributions along the - diagonal (as histograms or kernel density plots) and bivariate - distributions off the diagonal (as scatterplots or hex heatmaps). - - For the off-diagonal plots, the default is to split the chains so that - (roughly) half are displayed above the diagonal and half are below (all - chains are always merged together for the plots along the diagonal). Other - possibilities are available by setting the \code{condition} argument. - - Additionally, extra diagnostic information for models fit using - \code{\link{NUTS}} can be added to the pairs plot using the \code{lp}, - \code{np}, and \code{np_style} arguments. If \code{np} is specified (and - \code{condition} is \emph{not} \code{"divergent__"}), then points (red, by - default) will be superimposed onto the off-diagonal plots indicating which - (if any) iterations encountered a divergent transition. Also, if both - \code{np} and \code{max_treedepth} are specified then points (yellow, by - default) will be superimposed to indicate a transition that hit the - maximum treedepth rather than terminated its evolution normally. The - \code{np_style} argument can be used with the \code{pairs_style_np} - convenience function to change the appearance of these overlaid points. - See the \strong{Examples} section. - } +\item{\code{mcmc_scatter()}}{ +Bivariate scatterplot of posterior draws. If using a very large number of +posterior draws then \code{mcmc_hex()} may be preferable to avoid +overplotting. For models fit using \link{NUTS} the \code{np}, +and \code{np_style} arguments can be used to add additional information in +the plot (in this case the approximate location of divergences). +For more on why the scatter plot with divergences is a useful +diagnostic tool see \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)}. +} +\item{\code{mcmc_hex()}}{ +Hexagonal heatmap of 2-D bin counts. This plot is useful in cases where +the posterior sample size is large enough that \code{mcmc_scatter()} suffers +from overplotting. +} +\item{\code{mcmc_pairs()}}{ +A square plot matrix with univariate marginal distributions along the +diagonal (as histograms or kernel density plots) and bivariate +distributions off the diagonal (as scatterplots or hex heatmaps). + +For the off-diagonal plots, the default is to split the chains so that +(roughly) half are displayed above the diagonal and half are below (all +chains are always merged together for the plots along the diagonal). Other +possibilities are available by setting the \code{condition} argument. + +Additionally, extra diagnostic information for models fit using +\link{NUTS} can be added to the pairs plot using the \code{lp}, +\code{np}, and \code{np_style} arguments. If \code{np} is specified (and +\code{condition} is \emph{not} \code{"divergent__"}), then points (red, by +default) will be superimposed onto the off-diagonal plots indicating which +(if any) iterations encountered a divergent transition. Also, if both +\code{np} and \code{max_treedepth} are specified then points (yellow, by +default) will be superimposed to indicate a transition that hit the +maximum treedepth rather than terminated its evolution normally. The +\code{np_style} argument can be used with the \code{pairs_style_np()} +convenience function to change the appearance of these overlaid points. +See the \strong{Examples} section. +} } } @@ -358,11 +355,11 @@ mcmc_pairs( } \references{ Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and - Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. - Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, - (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, - \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, - \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +Gelman, A. (2019), Visualization in Bayesian workflow. +\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378. +(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, +\href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, +\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) } \seealso{ Other MCMC: \code{\link{MCMC-combos}}, diff --git a/man/MCMC-traces.Rd b/man/MCMC-traces.Rd index 1e4c246d6..8b2f0765e 100644 --- a/man/MCMC-traces.Rd +++ b/man/MCMC-traces.Rd @@ -27,36 +27,34 @@ the \link{MCMC-overview} page.} \item{pars}{An optional character vector of parameter names. If neither \code{pars} nor \code{regex_pars} is specified then the default is to use -\emph{all} parameters.} +\strong{all} parameters.} -\item{regex_pars}{An optional \link[=grep]{regular expression} to use for +\item{regex_pars}{An optional \link[base:grep]{regular expression} to use for parameter selection. Can be specified instead of \code{pars} or in addition to \code{pars}.} \item{transformations}{Optionally, transformations to apply to parameters - before plotting. If \code{transformations} is a function or a single string - naming a function then that function will be used to transform all - parameters. To apply transformations to particular parameters, the - \code{transformations} argument can be a named list with length equal to - the number of parameters to be transformed. Currently only univariate - transformations of scalar parameters can be specified (multivariate - transformations will be implemented in a future release). If - \code{transformations} is a list, the name of each list element should be a - parameter name and the content of each list element should be a function - (or any item to match as a function via \code{\link{match.fun}}, e.g. a - string naming a function). If a function is specified by its name as a - string (e.g. \code{"log"}), then it can be used to construct a new - parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). - If a function itself is specified (e.g. \code{log} or \code{function(x) - log(x)}) then \code{"t"} is used in the new parameter label to indicate - that the parameter is transformed (e.g. \code{"t(sigma)"}). - - Note: due to partial argument matching \code{transformations} can be - abbreviated for convenience in interactive use (e.g., \code{transform}, - \code{trans}, etc.).} +before plotting. If \code{transformations} is a function or a single string +naming a function then that function will be used to transform all +parameters. To apply transformations to particular parameters, the +\code{transformations} argument can be a named list with length equal to +the number of parameters to be transformed. Currently only univariate +transformations of scalar parameters can be specified (multivariate +transformations will be implemented in a future release). If +\code{transformations} is a list, the name of each list element should be a +parameter name and the content of each list element should be a function +(or any item to match as a function via \code{\link[=match.fun]{match.fun()}}, e.g. a +string naming a function). If a function is specified by its name as a +string (e.g. \code{"log"}), then it can be used to construct a new +parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). +If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate +that the parameter is transformed (e.g. \code{"t(sigma)"}). + +Note: due to partial argument matching \code{transformations} can be +abbreviated for convenience in interactive use (e.g., \code{transform}).} \item{facet_args}{A named list of arguments (other than \code{facets}) passed -to \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} +to \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}} or \code{\link[ggplot2:facet_grid]{ggplot2::facet_grid()}} to control faceting.} \item{...}{Currently ignored.} @@ -67,7 +65,7 @@ iterations are included. If \code{n_warmup > 0} then the background for iterations \code{1:n_warmup} is shaded gray.} \item{iter1}{An integer; the iteration number of the first included draw -(default 0). This can be used to make it more obvious that the warmup +(default is \code{0}). This can be used to make it more obvious that the warmup iterations have been discarded from the traceplot. It cannot be specified if \code{n_warmup} is also set to a positive value.} @@ -75,41 +73,38 @@ if \code{n_warmup} is also set to a positive value.} range of iterations to display.} \item{size}{An optional value to override the default line size -(\code{mcmc_trace}) or the default point size -(\code{mcmc_trace_highlight}).} - -\item{np}{For models fit using \code{\link{NUTS}} (more generally, any -\href{https://en.wikipedia.org/wiki/Symplectic_integrator}{symplectic -integrator}), an optional data frame providing NUTS diagnostic -information. The data frame should be the object returned by -\code{\link{nuts_params}} or one with the same structure. If \code{np} is -specified then tick marks are added to the bottom of the trace plot -indicating within which iterations there was a divergence (if there were any). -See the end of the \strong{Examples} section, below.} - -\item{np_style}{A call to the \code{trace_style_np} helper function to +(\code{mcmc_trace()}) or the default point size +(\code{mcmc_trace_highlight()}).} + +\item{np}{For models fit using \link{NUTS} (more generally, any +(https://en.wikipedia.org/wiki/Symplectic_integrator)\link{symplectic integrator}), +an optional data frame providing NUTS diagnostic information. The data +frame should be the object returned by \code{\link[=nuts_params]{nuts_params()}} or one with the same +structure. If \code{np} is specified then tick marks are added to the bottom of +the trace plot indicating within which iterations there was a divergence +(if there were any). See the end of the \strong{Examples} section, below.} + +\item{np_style}{A call to the \code{trace_style_np()} helper function to specify arguments controlling the appearance of tick marks representing divergences (if the \code{np} argument is specified).} \item{divergences}{Deprecated. Use the \code{np} argument instead.} -\item{alpha}{For \code{mcmc_trace_highlight}, passed to -\code{\link[ggplot2]{geom_point}} to control the transparency of the points +\item{alpha}{For \code{mcmc_trace_highlight()}, passed to +\code{\link[ggplot2:geom_point]{ggplot2::geom_point()}} to control the transparency of the points for the chains not highlighted.} -\item{highlight}{For \code{mcmc_trace_highlight}, an integer specifying one +\item{highlight}{For \code{mcmc_trace_highlight()}, an integer specifying one of the chains that will be more visible than the others in the plot.} \item{div_color, div_size, div_alpha}{Optional arguments to the -\code{trace_style_np} helper function that are eventually passed to -\code{\link[ggplot2]{geom_rug}} if the \code{np} argument is also -specified. They control the color, size, and transparency specifications -for showing divergences in the plot. The default values are displayed in -the \strong{Usage} section above.} +\code{trace_style_np()} helper function that are eventually passed to +\code{\link[ggplot2:geom_rug]{ggplot2::geom_rug()}} if the \code{np} argument is also specified. They control +the color, size, and transparency specifications for showing divergences in +the plot. The default values are displayed in the \strong{Usage} section above.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. +A ggplot object that can be further customized using the \strong{ggplot2} package. } \description{ Trace plot (or traceplot) of MCMC draws. See the \strong{Plot Descriptions} @@ -118,14 +113,14 @@ section, below, for details. \section{Plot Descriptions}{ \describe{ - \item{\code{mcmc_trace}}{ - Standard trace plots of MCMC draws. For models fit using \code{\link{NUTS}}, - the \code{np} argument can be used to also show divergences on the trace plot. - } - \item{\code{mcmc_trace_highlight}}{ - Traces are plotted using points rather than lines and the opacity of all - chains but one (specified by the \code{highlight} argument) is reduced. - } +\item{\code{mcmc_trace()}}{ +Standard trace plots of MCMC draws. For models fit using \link{NUTS}, +the \code{np} argument can be used to also show divergences on the trace plot. +} +\item{\code{mcmc_trace_highlight()}}{ +Traces are plotted using points rather than lines and the opacity of all +chains but one (specified by the \code{highlight} argument) is reduced. +} } } diff --git a/man/PPC-discrete.Rd b/man/PPC-discrete.Rd index 48537efc3..09b44a46f 100644 --- a/man/PPC-discrete.Rd +++ b/man/PPC-discrete.Rd @@ -21,38 +21,36 @@ ppc_rootogram(y, yrep, style = c("standing", "hanging", "suspended"), \item{yrep}{An \eqn{S} by \eqn{N} matrix of draws from the posterior predictive distribution, where \eqn{S} is the size of the posterior sample -(or subset of the posterior sample used to generate \code{yrep}) and -\eqn{N} is the number of observations (the length of \code{y}). The columns -of \code{yrep} should be in the same order as the data points in \code{y} -for the plots to make sense. See \strong{Details} for additional -instructions.} +(or subset of the posterior sample used to generate \code{yrep}) and \eqn{N} is +the number of observations (the length of \code{y}). The columns of \code{yrep} +should be in the same order as the data points in \code{y} for the plots to make +sense. See \strong{Details} for additional instructions.} \item{...}{Currently unused.} -\item{prob}{A value between 0 and 1 indicating the desired probability mass -to include in the \code{yrep} intervals. Set \code{prob=0} to -remove the intervals. For \code{ppc_rootogram} these are intervals -of the \emph{square roots} of the expected counts.} +\item{prob}{A value between \code{0} and \code{1} indicating the desired probability +mass to include in the \code{yrep} intervals. Set \code{prob=0} to remove the +intervals. For \code{ppc_rootogram()} these are intervals of the \emph{square roots} +of the expected counts.} -\item{width}{For \code{ppc_bars} and \code{ppc_bars_grouped}, -passed to \code{\link[ggplot2]{geom_bar}} to control the bar width.} +\item{width}{For \code{ppc_bars()} and \code{ppc_bars_grouped()}, passed to +\code{\link[ggplot2:geom_bar]{ggplot2::geom_bar()}} to control the bar width.} -\item{size, fatten}{For \code{ppc_bars} and \code{ppc_bars_grouped}, -\code{size} and \code{fatten} are passed to -\code{\link[ggplot2]{geom_pointrange}} to control the appearance of the -\code{yrep} points and intervals. For \code{ppc_rootogram} \code{size} is -passed to \code{\link[ggplot2]{geom_line}}.} +\item{size, fatten}{For \code{ppc_bars()} and \code{ppc_bars_grouped()}, \code{size} and +\code{fatten} are passed to \code{\link[ggplot2:geom_pointrange]{ggplot2::geom_pointrange()}} to control the +appearance of the \code{yrep} points and intervals. For \code{ppc_rootogram()} \code{size} +is passed to \code{\link[ggplot2:geom_line]{ggplot2::geom_line()}}.} -\item{freq}{For \code{ppc_bars} and \code{ppc_bars_grouped}, if \code{TRUE} -(the default) the y-axis will display counts. Setting \code{freq=FALSE} -will put proportions on the y-axis.} +\item{freq}{For \code{ppc_bars()} and \code{ppc_bars_grouped()}, if \code{TRUE} (the +default) the y-axis will display counts. Setting \code{freq=FALSE} will put +proportions on the y-axis.} \item{group}{A grouping variable (a vector or factor) the same length as \code{y}. Each value in \code{group} is interpreted as the group level pertaining to the corresponding value of \code{y}.} \item{facet_args}{An optional list of arguments (other than \code{facets}) -passed to \code{\link[ggplot2]{facet_wrap}} to control faceting.} +passed to \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}} to control faceting.} \item{style}{For \code{ppc_rootogram}, a string specifying the rootogram style. The options are \code{"standing"}, \code{"hanging"}, and @@ -60,11 +58,10 @@ style. The options are \code{"standing"}, \code{"hanging"}, and details on the different styles.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. +A ggplot object that can be further customized using the \strong{ggplot2} package. } \description{ -Many of the \link{PPC} functions in \pkg{bayesplot} can +Many of the \link[=PPC-overview]{PPC} functions in \strong{bayesplot} can be used with discrete data. The small subset of these functions that can \emph{only} be used if \code{y} and \code{yrep} are discrete are documented on this page. Currently these include rootograms for count outcomes and bar @@ -72,41 +69,42 @@ plots for ordinal, categorical, and multinomial outcomes. See the \strong{Plot Descriptions} section below. } \details{ -For all of these plots \code{y} and \code{yrep} must be - integers, although they need not be integers in the strict sense - of \R's \code{\link{integer}} type. For rootogram plots \code{y} - and \code{yrep} must also be non-negative. +For all of these plots \code{y} and \code{yrep} must be integers, although +they need not be integers in the strict sense of \R's +\link[base:integer]{integer} type. For rootogram plots \code{y} and \code{yrep} must also +be non-negative. } \section{Plot Descriptions}{ \describe{ -\item{\code{ppc_bars}}{ - Bar plot of \code{y} with \code{yrep} medians and uncertainty intervals - superimposed on the bars. +\item{\code{ppc_bars()}}{ +Bar plot of \code{y} with \code{yrep} medians and uncertainty intervals +superimposed on the bars. } -\item{\code{ppc_bars_grouped}}{ - Same as \code{ppc_bars} but a separate plot (facet) is generated for each - level of a grouping variable. +\item{\code{ppc_bars_grouped()}}{ +Same as \code{ppc_bars()} but a separate plot (facet) is generated for each +level of a grouping variable. } -\item{\code{ppc_rootogram}}{ - Rootograms allow for diagnosing problems in count data models such as - overdispersion or excess zeros. They consist of a histogram of \code{y} - with the expected counts based on \code{yrep} overlaid as a line along with - uncertainty intervals. The y-axis represents the square roots of the counts - to approximately adjust for scale differences and thus ease comparison - between observed and expected counts. Using the \code{style} argument, the - histogram style can be adjusted to focus on different aspects of the data: - \itemize{ - \item \emph{Standing}: basic histogram of observed counts with curve - showing expected counts. - \item \emph{Hanging}: observed counts counts hanging from the curve - representing expected counts. - \item \emph{Suspended}: histogram of the differences between expected and - observed counts. - } - \strong{All of these are plotted on the square root scale}. See Kleiber and - Zeileis (2016) for advice on interpreting rootograms and selecting among - the different styles. +\item{\code{ppc_rootogram()}}{ +Rootograms allow for diagnosing problems in count data models such as +overdispersion or excess zeros. They consist of a histogram of \code{y} with the +expected counts based on \code{yrep} overlaid as a line along with uncertainty +intervals. The y-axis represents the square roots of the counts to +approximately adjust for scale differences and thus ease comparison between +observed and expected counts. Using the \code{style} argument, the histogram +style can be adjusted to focus on different aspects of the data: +\itemize{ +\item \emph{Standing}: basic histogram of observed counts with curve +showing expected counts. +\item \emph{Hanging}: observed counts counts hanging from the curve +representing expected counts. +\item \emph{Suspended}: histogram of the differences between expected and +observed counts. +} + +\strong{All of these are plotted on the square root scale}. See Kleiber and +Zeileis (2016) for advice on interpreting rootograms and selecting among +the different styles. } } } @@ -144,8 +142,9 @@ ppc_rootogram(y, yrep, style = "suspended") } \references{ -Kleiber, C. and Zeileis, A. (2016). Visualizing count data regressions using -rootograms. \emph{The American Statistician}. 70(3): 296--303. +Kleiber, C. and Zeileis, A. (2016). +Visualizing count data regressions using rootograms. +\emph{The American Statistician}. 70(3): 296--303. \url{https://arxiv.org/abs/1605.01311}. } \seealso{ diff --git a/man/PPC-distributions.Rd b/man/PPC-distributions.Rd index 80385c97a..b0d765a07 100644 --- a/man/PPC-distributions.Rd +++ b/man/PPC-distributions.Rd @@ -43,11 +43,10 @@ ppc_violin_grouped(y, yrep, group, ..., probs = c(0.1, 0.5, 0.9), \item{yrep}{An \eqn{S} by \eqn{N} matrix of draws from the posterior predictive distribution, where \eqn{S} is the size of the posterior sample -(or subset of the posterior sample used to generate \code{yrep}) and -\eqn{N} is the number of observations (the length of \code{y}). The columns -of \code{yrep} should be in the same order as the data points in \code{y} -for the plots to make sense. See \strong{Details} for additional -instructions.} +(or subset of the posterior sample used to generate \code{yrep}) and \eqn{N} is +the number of observations (the length of \code{y}). The columns of \code{yrep} +should be in the same order as the data points in \code{y} for the plots to make +sense. See \strong{Details} for additional instructions.} \item{group}{A grouping variable (a vector or factor) the same length as \code{y}. Each value in \code{group} is interpreted as the group level @@ -55,57 +54,54 @@ pertaining to the corresponding value of \code{y}.} \item{...}{Currently unused.} -\item{binwidth}{Passed to \code{\link[ggplot2]{geom_histogram}} to override +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override the default binwidth.} -\item{breaks}{Passed to \code{\link[ggplot2]{geom_histogram}} as an +\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an alternative to \code{binwidth}.} \item{freq}{For histograms, \code{freq=TRUE} (the default) puts count on the y-axis. Setting \code{freq=FALSE} puts density on the y-axis. (For many plots the y-axis text is off by default. To view the count or density -labels on the y-axis see the \code{\link{yaxis_text}} convenience +labels on the y-axis see the \code{\link[=yaxis_text]{yaxis_text()}} convenience function.)} -\item{notch}{A logical scalar passed to \code{\link[ggplot2]{geom_boxplot}}. -Unlike for \code{geom_boxplot}, the default is \code{notch=TRUE}.} +\item{notch}{A logical scalar passed to \code{\link[ggplot2:geom_boxplot]{ggplot2::geom_boxplot()}}. +Unlike for \code{geom_boxplot()}, the default is \code{notch=TRUE}.} \item{size, alpha}{Passed to the appropriate geom to control the appearance of the \code{yrep} distributions.} -\item{trim}{A logical scalar passed to \code{\link[ggplot2]{geom_density}}.} +\item{trim}{A logical scalar passed to \code{\link[ggplot2:geom_density]{ggplot2::geom_density()}}.} \item{bw, adjust, kernel, n_dens}{Optional arguments passed to -\code{\link[stats]{density}} to override default kernel density estimation -parameters. \code{n_dens} defaults to 1024.} +\code{\link[stats:density]{stats::density()}} to override default kernel density estimation +parameters. \code{n_dens} defaults to \code{1024}.} -\item{discrete}{For \code{ppc_ecdf_overlay}, should the data be treated as +\item{discrete}{For \code{ppc_ecdf_overlay()}, should the data be treated as discrete? The default is \code{FALSE}, in which case \code{geom="line"} is -passed to \code{\link[ggplot2]{stat_ecdf}}. If \code{discrete} is set to +passed to \code{\link[ggplot2:stat_ecdf]{ggplot2::stat_ecdf()}}. If \code{discrete} is set to \code{TRUE} then \code{geom="step"} is used.} -\item{pad}{A logical scalar passed to \code{\link[ggplot2]{stat_ecdf}}.} +\item{pad}{A logical scalar passed to \code{\link[ggplot2:stat_ecdf]{ggplot2::stat_ecdf()}}.} -\item{probs}{A numeric vector passed to \code{\link[ggplot2]{geom_violin}}'s +\item{probs}{A numeric vector passed to \code{\link[ggplot2:geom_violin]{ggplot2::geom_violin()}}'s \code{draw_quantiles} argument to specify at which quantiles to draw horizontal lines. Set to \code{NULL} to remove the lines.} -\item{y_draw}{For \code{ppc_violin_grouped}, a string specifying how to draw -\code{y}: \code{"violin"} (default), \code{"points"} (jittered points), or -\code{"both"}.} +\item{y_draw}{For \code{ppc_violin_grouped()}, a string specifying how to draw +\code{y}: \code{"violin"} (default), \code{"points"} (jittered points), or \code{"both"}.} -\item{y_jitter, y_size, y_alpha}{For \code{ppc_violin_grouped}, if -\code{y_draw} is \code{"points"} or \code{"both"} then \code{y_size}, -\code{y_alpha}, and \code{y_jitter} are passed to to the \code{size}, -\code{alpha}, and \code{width} arguments of -\code{\link[ggplot2]{geom_jitter}} to control the appearance of \code{y} -points. The default of \code{y_jitter=NULL} will let \pkg{ggplot2} -determine the amount of jitter.} +\item{y_jitter, y_size, y_alpha}{For \code{ppc_violin_grouped()}, if \code{y_draw} is +\code{"points"} or \code{"both"} then \code{y_size}, \code{y_alpha}, and \code{y_jitter} are passed +to to the \code{size}, \code{alpha}, and \code{width} arguments of \code{\link[ggplot2:geom_jitter]{ggplot2::geom_jitter()}} +to control the appearance of \code{y} points. The default of \code{y_jitter=NULL} +will let \strong{ggplot2} determine the amount of jitter.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. The \code{_data} functions return the data that - would have been drawn by the plotting function. +A ggplot object that can be further customized using the \strong{ggplot2} +package. The functions with suffix \code{_data} return the data that would have +been drawn by the plotting function. } \description{ Compare the empirical distribution of the data \code{y} to the distributions @@ -115,37 +111,37 @@ for details. } \details{ For Binomial data, the plots will typically be most useful if - \code{y} and \code{yrep} contain the "success" proportions (not discrete - "success" or "failure" counts). +\code{y} and \code{yrep} contain the "success" proportions (not discrete +"success" or "failure" counts). } \section{Plot Descriptions}{ \describe{ - \item{\code{ppc_hist, ppc_freqpoly, ppc_dens, ppc_boxplot}}{ - A separate histogram, shaded frequency polygon, smoothed kernel density - estimate, or box and whiskers plot is displayed for \code{y} and each - dataset (row) in \code{yrep}. For these plots \code{yrep} should therefore - contain only a small number of rows. See the \strong{Examples} section. - } - \item{\code{ppc_freqpoly_grouped}}{ - A separate frequency polygon is plotted for each level of a grouping - variable for \code{y} and each dataset (row) in \code{yrep}. For this plot - \code{yrep} should therefore contain only a small number of rows. See the - \strong{Examples} section. - } - \item{\code{ppc_dens_overlay, ppc_ecdf_overlay}}{ - Kernel density or empirical CDF estimates of each dataset (row) in - \code{yrep} are overlaid, with the distribution of \code{y} itself on top - (and in a darker shade). When using \code{ppc_ecdf_overlay} with discrete - data, set the \code{discrete} argument to \code{TRUE} for better results. - For an example of \code{ppc_dens_overlay} also see Gabry et al. (2019). - } - \item{\code{ppc_violin_grouped}}{ - The density estimate of \code{yrep} within each level of a grouping - variable is plotted as a violin with horizontal lines at notable - quantiles. \code{y} is overlaid on the plot either as a violin, points, or - both, depending on the \code{y_draw} argument. - } +\item{\code{ppc_hist(), ppc_freqpoly(), ppc_dens(), ppc_boxplot()}}{ +A separate histogram, shaded frequency polygon, smoothed kernel density +estimate, or box and whiskers plot is displayed for \code{y} and each +dataset (row) in \code{yrep}. For these plots \code{yrep} should therefore +contain only a small number of rows. See the \strong{Examples} section. +} +\item{\code{ppc_freqpoly_grouped()}}{ +A separate frequency polygon is plotted for each level of a grouping +variable for \code{y} and each dataset (row) in \code{yrep}. For this plot +\code{yrep} should therefore contain only a small number of rows. See the +\strong{Examples} section. +} +\item{\code{ppc_dens_overlay(), ppc_ecdf_overlay()}}{ +Kernel density or empirical CDF estimates of each dataset (row) in +\code{yrep} are overlaid, with the distribution of \code{y} itself on top +(and in a darker shade). When using \code{ppc_ecdf_overlay()} with discrete +data, set the \code{discrete} argument to \code{TRUE} for better results. +For an example of \code{ppc_dens_overlay()} also see Gabry et al. (2019). +} +\item{\code{ppc_violin_grouped()}}{ +The density estimate of \code{yrep} within each level of a grouping +variable is plotted as a violin with horizontal lines at notable +quantiles. \code{y} is overlaid on the plot either as a violin, points, or +both, depending on the \code{y_draw} argument. +} } } @@ -196,15 +192,15 @@ ppc_violin_grouped(y, yrep, group, alpha = 0, y_draw = "both", } \references{ Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and - Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. - Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, - (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, - \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, - \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +Gelman, A. (2019), Visualization in Bayesian workflow. +\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378. +(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, +\href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, +\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, - A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC - Press, London, third edition. (Ch. 6) +A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC +Press, London, third edition. (Ch. 6) } \seealso{ Other PPCs: \code{\link{PPC-discrete}}, diff --git a/man/PPC-errors.Rd b/man/PPC-errors.Rd index 33216eb6c..11ab72ef3 100644 --- a/man/PPC-errors.Rd +++ b/man/PPC-errors.Rd @@ -29,24 +29,23 @@ ppc_error_binned(y, yrep, ..., bins = NULL, size = 1, alpha = 0.25) \item{yrep}{An \eqn{S} by \eqn{N} matrix of draws from the posterior predictive distribution, where \eqn{S} is the size of the posterior sample -(or subset of the posterior sample used to generate \code{yrep}) and -\eqn{N} is the number of observations (the length of \code{y}). The columns -of \code{yrep} should be in the same order as the data points in \code{y} -for the plots to make sense. See \strong{Details} for additional -instructions.} +(or subset of the posterior sample used to generate \code{yrep}) and \eqn{N} is +the number of observations (the length of \code{y}). The columns of \code{yrep} +should be in the same order as the data points in \code{y} for the plots to make +sense. See \strong{Details} for additional instructions.} \item{...}{Currently unused.} -\item{binwidth}{Passed to \code{\link[ggplot2]{geom_histogram}} to override +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override the default binwidth.} -\item{breaks}{Passed to \code{\link[ggplot2]{geom_histogram}} as an +\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an alternative to \code{binwidth}.} \item{freq}{For histograms, \code{freq=TRUE} (the default) puts count on the y-axis. Setting \code{freq=FALSE} puts density on the y-axis. (For many plots the y-axis text is off by default. To view the count or density -labels on the y-axis see the \code{\link{yaxis_text}} convenience +labels on the y-axis see the \code{\link[=yaxis_text]{yaxis_text()}} convenience function.)} \item{group}{A grouping variable (a vector or factor) the same length as @@ -54,21 +53,20 @@ function.)} pertaining to the corresponding value of \code{y}.} \item{size, alpha}{For scatterplots, arguments passed to -\code{\link[ggplot2]{geom_point}} to control the appearance of the -points. For the binned error plot, arguments controlling the size of -the outline and opacity of the shaded region indicating the 2-SE bounds.} +\code{\link[ggplot2:geom_point]{ggplot2::geom_point()}} to control the appearance of the points. For the +binned error plot, arguments controlling the size of the outline and +opacity of the shaded region indicating the 2-SE bounds.} \item{x}{A numeric vector the same length as \code{y} to use as the x-axis variable.} -\item{bins}{For \code{ppc_error_binned}, the number of bins to use (approximately).} +\item{bins}{For \code{ppc_error_binned()}, the number of bins to use (approximately).} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. +A ggplot object that can be further customized using the \strong{ggplot2} package. } \description{ -Various plots of predictive errors \code{y} - \code{yrep}. See the +Various plots of predictive errors \code{y - yrep}. See the \strong{Details} and \strong{Plot Descriptions} sections, below. } \details{ @@ -77,50 +75,48 @@ compute and plot predictive errors for each row of the matrix \code{yrep}, so it is usually a good idea for \code{yrep} to contain only a small number of draws (rows). See \strong{Examples}, below. -For binomial and Bernoulli data the \code{ppc_error_binned} function can be -used to generate binned error plots. Bernoulli data can be input as a vector -of 0s and 1s, whereas for binomial data \code{y} and \code{yrep} should -contain "success" proportions (not counts). See the \strong{Examples} -section, below. +For binomial and Bernoulli data the \code{ppc_error_binned()} function can be used +to generate binned error plots. Bernoulli data can be input as a vector of 0s +and 1s, whereas for binomial data \code{y} and \code{yrep} should contain "success" +proportions (not counts). See the \strong{Examples} section, below. } \section{Plot descriptions}{ \describe{ - \item{\code{ppc_error_hist}}{ - A separate histogram is plotted for the predictive errors computed from - \code{y} and each dataset (row) in \code{yrep}. For this plot \code{yrep} - should have only a small number of rows. - } - \item{\code{ppc_error_hist_grouped}}{ - Like \code{ppc_error_hist}, except errors are computed within levels of a - grouping variable. The number of histograms is therefore equal to the - product of the number of rows in \code{yrep} and the number of groups - (unique values of \code{group}). - } - \item{\code{ppc_error_scatter}}{ - A separate scatterplot is displayed for \code{y} vs. the predictive errors - computed from \code{y} and each dataset (row) in \code{yrep}. For this - plot \code{yrep} should have only a small number of rows. - } - \item{\code{ppc_error_scatter_avg}}{ - A single scatterplot of \code{y} vs. the average of the errors computed - from \code{y} and each dataset (row) in \code{yrep}. For each individual - data point \code{y[n]} the average error is the average of the - errors for \code{y[n]} computed over the the draws from the posterior - predictive distribution. - } - \item{\code{ppc_error_scatter_avg_vs_x}}{ - Same as \code{ppc_error_scatter_avg}, except the average is plotted on the - \eqn{y}-axis and a a predictor variable \code{x} is plotted on the - \eqn{x}-axis. - } - \item{\code{ppc_error_binned}}{ - Intended for use with binomial data. A separate binned error plot (similar - to \code{arm::binnedplot}) is generated for each dataset (row) in - \code{yrep}. For this plot \code{y} and \code{yrep} should contain - proportions rather than counts, and \code{yrep} should have only a small - number of rows. - } +\item{\code{ppc_error_hist()}}{ +A separate histogram is plotted for the predictive errors computed from +\code{y} and each dataset (row) in \code{yrep}. For this plot \code{yrep} +should have only a small number of rows. +} +\item{\code{ppc_error_hist_grouped()}}{ +Like \code{ppc_error_hist()}, except errors are computed within levels of a +grouping variable. The number of histograms is therefore equal to the +product of the number of rows in \code{yrep} and the number of groups +(unique values of \code{group}). +} +\item{\code{ppc_error_scatter()}}{ +A separate scatterplot is displayed for \code{y} vs. the predictive errors +computed from \code{y} and each dataset (row) in \code{yrep}. For this +plot \code{yrep} should have only a small number of rows. +} +\item{\code{ppc_error_scatter_avg()}}{ +A single scatterplot of \code{y} vs. the average of the errors computed +from \code{y} and each dataset (row) in \code{yrep}. For each individual +data point \code{y[n]} the average error is the average of the +errors for \code{y[n]} computed over the the draws from the posterior +predictive distribution. +} +\item{\code{ppc_error_scatter_avg_vs_x()}}{ +Same as \code{ppc_error_scatter_avg()}, except the average is plotted on the +\eqn{y}-axis and a a predictor variable \code{x} is plotted on the +\eqn{x}-axis. +} +\item{\code{ppc_error_binned()}}{ +Intended for use with binomial data. A separate binned error plot (similar +to \code{arm::binnedplot()}) is generated for each dataset (row) in \code{yrep}. For +this plot \code{y} and \code{yrep} should contain proportions rather than counts, +and \code{yrep} should have only a small number of rows. +} } } @@ -167,8 +163,8 @@ ppc_error_binned(y_prop, yrep_prop[1:6, ]) } \references{ Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, - A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC - Press, London, third edition. (Ch. 6) +A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC +Press, London, third edition. (Ch. 6) } \seealso{ Other PPCs: \code{\link{PPC-discrete}}, diff --git a/man/PPC-intervals.Rd b/man/PPC-intervals.Rd index 047a12fb9..e7c44eeff 100644 --- a/man/PPC-intervals.Rd +++ b/man/PPC-intervals.Rd @@ -33,16 +33,15 @@ ppc_ribbon_data(y, yrep, x = NULL, group = NULL, prob = 0.5, \item{yrep}{An \eqn{S} by \eqn{N} matrix of draws from the posterior predictive distribution, where \eqn{S} is the size of the posterior sample -(or subset of the posterior sample used to generate \code{yrep}) and -\eqn{N} is the number of observations (the length of \code{y}). The columns -of \code{yrep} should be in the same order as the data points in \code{y} -for the plots to make sense. See \strong{Details} for additional -instructions.} +(or subset of the posterior sample used to generate \code{yrep}) and \eqn{N} is +the number of observations (the length of \code{y}). The columns of \code{yrep} +should be in the same order as the data points in \code{y} for the plots to make +sense. See \strong{Details} for additional instructions.} \item{x}{A numeric vector the same length as \code{y} to use as the x-axis variable. For example, \code{x} could be a predictor variable from a regression model, a time variable for time-series models, etc. If \code{x} -is missing or NULL, then \code{1:length(y)} is used for the x-axis.} +is missing or \code{NULL}, then \code{1:length(y)} is used for the x-axis.} \item{...}{Currently unused.} @@ -55,17 +54,16 @@ are \code{prob=0.5} and \code{prob_outer=0.9}.} pertaining to the corresponding value of \code{y}.} \item{facet_args}{An optional list of arguments (other than \code{facets}) -passed to \code{\link[ggplot2]{facet_wrap}} to control faceting.} +passed to \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}} to control faceting.} -\item{alpha, size, fatten}{Arguments passed to geoms. For ribbon plots -\code{alpha} and \code{size} are passed to -\code{\link[ggplot2]{geom_ribbon}}. For interval plots \code{size} and -\code{fatten} are passed to \code{\link[ggplot2]{geom_pointrange}}.} +\item{alpha, size, fatten}{Arguments passed to geoms. For ribbon plots \code{alpha} +and \code{size} are passed to \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_ribbon()}}. For interval plots +\code{size} and \code{fatten} are passed to \code{\link[ggplot2:geom_pointrange]{ggplot2::geom_pointrange()}}.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. The \code{_data} functions return the data that - would have been drawn by the plotting function. +A ggplot object that can be further customized using the \strong{ggplot2} +package. The functions with suffix \code{_data} return the data that would have +been drawn by the plotting function. } \description{ Medians and central interval estimates of \code{yrep} with \code{y} overlaid. @@ -74,23 +72,23 @@ See the \strong{Plot Descriptions} section, below. \section{Plot Descriptions}{ \describe{ - \item{\code{ppc_intervals, ppc_ribbon}}{ - \code{100*prob}\% central intervals for \code{yrep} at each \code{x} - value. \code{ppc_intervals} plots intervals as vertical bars with points - indicating \code{yrep} medians and darker points indicating observed - \code{y} values. \code{ppc_ribbon} plots a ribbon of connected intervals - with a line through the median of \code{yrep} and a darker line connecting - observed \code{y} values. In both cases an optional \code{x} variable can - also be specified for the x-axis variable. - - Depending on the number of observations and the variability in the - predictions at different values of \code{x}, one or the other of these - plots may be easier to read than the other. - } - \item{\code{ppc_intervals_grouped, ppc_ribbon_grouped}}{ - Same as \code{ppc_intervals} and \code{ppc_ribbon}, respectively, but a - separate plot (facet) is generated for each level of a grouping variable. - } +\item{\code{ppc_intervals(), ppc_ribbon()}}{ +\code{100*prob}\% central intervals for \code{yrep} at each \code{x} +value. \code{ppc_intervals()} plots intervals as vertical bars with points +indicating \code{yrep} medians and darker points indicating observed +\code{y} values. \code{ppc_ribbon()} plots a ribbon of connected intervals +with a line through the median of \code{yrep} and a darker line connecting +observed \code{y} values. In both cases an optional \code{x} variable can +also be specified for the x-axis variable. + +Depending on the number of observations and the variability in the +predictions at different values of \code{x}, one or the other of these +plots may be easier to read than the other. +} +\item{\code{ppc_intervals_grouped(), ppc_ribbon_grouped()}}{ +Same as \code{ppc_intervals()} and \code{ppc_ribbon()}, respectively, but a +separate plot (facet) is generated for each level of a grouping variable. +} } } @@ -157,8 +155,8 @@ ppc_intervals(mtcars$mpg, yrep, prob = 0.5) + } \references{ Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, - A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC - Press, London, third edition. (Ch. 6) +A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC +Press, London, third edition. (Ch. 6) } \seealso{ Other PPCs: \code{\link{PPC-discrete}}, diff --git a/man/PPC-loo.Rd b/man/PPC-loo.Rd index 7f9289838..161b7f093 100644 --- a/man/PPC-loo.Rd +++ b/man/PPC-loo.Rd @@ -32,23 +32,21 @@ ppc_loo_ribbon(y, yrep, lw, psis_object, subset = NULL, \item{yrep}{An \eqn{S} by \eqn{N} matrix of draws from the posterior predictive distribution, where \eqn{S} is the size of the posterior sample -(or subset of the posterior sample used to generate \code{yrep}) and -\eqn{N} is the number of observations (the length of \code{y}). The columns -of \code{yrep} should be in the same order as the data points in \code{y} -for the plots to make sense. See \strong{Details} for additional -instructions.} +(or subset of the posterior sample used to generate \code{yrep}) and \eqn{N} is +the number of observations (the length of \code{y}). The columns of \code{yrep} +should be in the same order as the data points in \code{y} for the plots to make +sense. See \strong{Details} for additional instructions.} \item{lw}{A matrix of (smoothed) log weights with the same dimensions as -\code{yrep}. See \code{\link[loo]{psis}} and the associated \code{weights} -method and the \strong{Examples} section, below.} +\code{yrep}. See \code{\link[loo:psis]{loo::psis()}} and the associated \code{weights()} method as well as +the \strong{Examples} section, below.} -\item{pit}{For \code{ppc_loo_pit_overlay} and \code{ppc_loo_pit_qq}, -optionally a vector of precomputed PIT values that can be specified instead -of \code{y}, \code{yrep}, and \code{lw} (these are all ignored if -\code{pit} is specified). If not specified the PIT values are computed -internally before plotting.} +\item{pit}{For \code{ppc_loo_pit_overlay()} and \code{ppc_loo_pit_qq()}, optionally a +vector of precomputed PIT values that can be specified instead of \code{y}, +\code{yrep}, and \code{lw} (these are all ignored if \code{pit} is specified). If not +specified the PIT values are computed internally before plotting.} -\item{samples}{For \code{ppc_loo_pit_overlay}, the number of data sets (each +\item{samples}{For \code{ppc_loo_pit_overlay()}, the number of data sets (each the same size as \code{y}) to simulate from the standard uniform distribution. The default is 100. The density estimate of each dataset is plotted as a thin line in the plot, with the density estimate of the LOO @@ -57,41 +55,39 @@ PITs overlaid as a thicker dark line.} \item{...}{Currently unused.} \item{alpha, size, fatten}{Arguments passed to code geoms to control plot -aesthetics. For \code{ppc_loo_pit_qq} and \code{ppc_loo_pit_overlay}, -\code{size} and \code{alpha} are passed to -\code{\link[ggplot2]{geom_point}} and \code{\link[ggplot2]{geom_density}}, -respectively. For \code{ppc_loo_intervals}, \code{size} and \code{fatten} -are passed to \code{\link[ggplot2]{geom_pointrange}}. For -\code{ppc_loo_ribbon}, \code{alpha} and \code{size} are passed to -\code{\link[ggplot2]{geom_ribbon}}.} +aesthetics. For \code{ppc_loo_pit_qq()} and \code{ppc_loo_pit_overlay()}, \code{size} and +\code{alpha} are passed to \code{\link[ggplot2:geom_point]{ggplot2::geom_point()}} and +\code{\link[ggplot2:geom_density]{ggplot2::geom_density()}}, respectively. For \code{ppc_loo_intervals()}, \code{size} +and \code{fatten} are passed to \code{\link[ggplot2:geom_pointrange]{ggplot2::geom_pointrange()}}. For +\code{ppc_loo_ribbon()}, \code{alpha} and \code{size} are passed to +\code{\link[ggplot2:geom_ribbon]{ggplot2::geom_ribbon()}}.} -\item{trim}{Passed to \code{\link[ggplot2]{stat_density}}.} +\item{trim}{Passed to \code{\link[ggplot2:stat_density]{ggplot2::stat_density()}}.} \item{bw, adjust, kernel, n_dens}{Optional arguments passed to -\code{\link[stats]{density}} to override default kernel density estimation -parameters. \code{n_dens} defaults to 1024.} +\code{\link[stats:density]{stats::density()}} to override default kernel density estimation +parameters. \code{n_dens} defaults to \code{1024}.} -\item{compare}{For \code{ppc_loo_pit_qq}, a string that can be either -\code{"uniform"} or \code{"normal"}. If \code{"uniform"} (the default) the -Q-Q plot compares computed PIT values to the standard uniform distribution. -If \code{compare="normal"}, the Q-Q plot compares standardized PIT values -to the standard normal distribution.} +\item{compare}{For \code{ppc_loo_pit_qq()}, a string that can be either +\code{"uniform"} or \code{"normal"}. If \code{"uniform"} (the default) the Q-Q plot +compares computed PIT values to the standard uniform distribution. If +\code{compare="normal"}, the Q-Q plot compares standardized PIT values to the +standard normal distribution.} -\item{psis_object}{If using \pkg{loo} version \code{2.0.0} or greater, an -object returned by the \code{psis} function (or by the \code{loo} function +\item{psis_object}{If using \strong{loo} version \code{2.0.0} or greater, an +object returned by the \code{psis()} function (or by the \code{loo()} function with argument \code{save_psis} set to \code{TRUE}).} -\item{subset}{For \code{ppc_loo_intervals} and \code{ppc_loo_ribbon}, an -optional integer vector indicating which observations in \code{y} (and -\code{yrep}) to include. Dropping observations from \code{y} and -\code{yrep} manually before passing them to the plotting function will not -work because the dimensions will not match up with the dimensions of -\code{psis_object}, but if all of \code{y} and \code{yrep} are passed along -with \code{subset} then \pkg{bayesplot} can do the subsetting internally -for \code{y}, \code{yrep} \emph{and} \code{psis_object}. -See the \strong{Examples} section for a demonstration.} - -\item{intervals}{For \code{ppc_loo_intervals} and \code{ppc_loo_ribbon}, +\item{subset}{For \code{ppc_loo_intervals()} and \code{ppc_loo_ribbon()}, an optional +integer vector indicating which observations in \code{y} (and \code{yrep}) to +include. Dropping observations from \code{y} and \code{yrep} manually before passing +them to the plotting function will not work because the dimensions will not +match up with the dimensions of \code{psis_object}, but if all of \code{y} and \code{yrep} +are passed along with \code{subset} then \strong{bayesplot} can do the subsetting +internally for \code{y}, \code{yrep} \emph{and} \code{psis_object}. See the \strong{Examples} +section for a demonstration.} + +\item{intervals}{For \code{ppc_loo_intervals()} and \code{ppc_loo_ribbon()}, optionally a matrix of precomputed LOO predictive intervals that can be specified instead of \code{yrep} and \code{lw} (these are both ignored if \code{intervals} is specified). If not specified the intervals @@ -105,51 +101,50 @@ interval, median (50\%), upper inner interval and upper outer interval probability mass to include in the inner and outer intervals. The defaults are \code{prob=0.5} and \code{prob_outer=0.9}.} -\item{order}{For \code{ppc_loo_intervals}, a string indicating how to arrange +\item{order}{For \code{ppc_loo_intervals()}, a string indicating how to arrange the plotted intervals. The default (\code{"index"}) is to plot them in the order of the observations. The alternative (\code{"median"}) arranges them by median value from smallest (left) to largest (right).} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. +A ggplot object that can be further customized using the \strong{ggplot2} package. } \description{ -Leave-One-Out (LOO) predictive checks. See the \strong{Plot Descriptions} -section, below, and \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et -al. (2019)} for details. +Leave-One-Out (LOO) predictive checks. See the \strong{Plot Descriptions} section, +below, and \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)} +for details. } \section{Plot Descriptions}{ \describe{ -\item{\code{ppc_loo_pit_overlay, ppc_loo_pit_qq}}{ - The calibration of marginal predictions can be assessed using probability - integral transformation (PIT) checks. LOO improves the check by avoiding the - double use of data. See the section on marginal predictive checks in Gelman - et al. (2013, p. 152--153) and section 5 of Gabry et al. (2019) for an - example of using \pkg{bayesplot} for these checks. - - The LOO PIT values are asymptotically uniform (for continuous data) if the - model is calibrated. The \code{ppc_loo_pit_overlay} function creates a plot - comparing the density of the LOO PITs (thick line) to the density estimates - of many simulated data sets from the standard uniform distribution (thin - lines). See Gabry et al. (2019) for an example of interpreting the shape of - the miscalibration that can be observed in these plots. - - The \code{ppc_loo_pit_qq} function provides an alternative visualization of - the miscalibration with a quantile-quantile (Q-Q) plot comparing the LOO - PITs to the standard uniform distribution. Comparing to the uniform is not - good for extreme probabilities close to 0 and 1, so it can sometimes be - useful to set the \code{compare} argument to \code{"normal"}, which will - produce a Q-Q plot comparing standardized PIT values to the standard normal - distribution that can help see the (mis)calibration better for the extreme - values. However, in most cases we have found that the overlaid density plot - (\code{ppc_loo_pit_overlay}) function will provided a clearer picture of - calibration problems that the Q-Q plot. +\item{\code{ppc_loo_pit_overlay()}, \code{ppc_loo_pit_qq()}}{ +The calibration of marginal predictions can be assessed using probability +integral transformation (PIT) checks. LOO improves the check by avoiding the +double use of data. See the section on marginal predictive checks in Gelman +et al. (2013, p. 152--153) and section 5 of Gabry et al. (2019) for an +example of using \strong{bayesplot} for these checks. + +The LOO PIT values are asymptotically uniform (for continuous data) if the +model is calibrated. The \code{ppc_loo_pit_overlay()} function creates a plot +comparing the density of the LOO PITs (thick line) to the density estimates +of many simulated data sets from the standard uniform distribution (thin +lines). See Gabry et al. (2019) for an example of interpreting the shape of +the miscalibration that can be observed in these plots. + +The \code{ppc_loo_pit_qq()} function provides an alternative visualization of +the miscalibration with a quantile-quantile (Q-Q) plot comparing the LOO +PITs to the standard uniform distribution. Comparing to the uniform is not +good for extreme probabilities close to 0 and 1, so it can sometimes be +useful to set the \code{compare} argument to \code{"normal"}, which will +produce a Q-Q plot comparing standardized PIT values to the standard normal +distribution that can help see the (mis)calibration better for the extreme +values. However, in most cases we have found that the overlaid density plot +(\code{ppc_loo_pit_overlay()}) function will provided a clearer picture of +calibration problems that the Q-Q plot. } -\item{\code{ppc_loo_intervals, ppc_loo_ribbon}}{ - Similar to \code{\link{ppc_intervals}} and \code{\link{ppc_ribbon}} but the - intervals are for the LOO predictive distribution. +\item{\code{ppc_loo_intervals()}, \code{ppc_loo_ribbon()}}{ +Similar to \code{\link[=ppc_intervals]{ppc_intervals()}} and \code{\link[=ppc_ribbon]{ppc_ribbon()}} but the intervals are for +the LOO predictive distribution. } } } @@ -195,21 +190,21 @@ ppc_loo_intervals(y, yrep, psis_object = psis1, subset = keep_obs, } \references{ Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, - A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC - Press, London, third edition. (p. 152--153) +A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC +Press, London, third edition. (p. 152--153) Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and - Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. - Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, - (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, - \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, - \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +Gelman, A. (2019), Visualization in Bayesian workflow. +\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378. +(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, +\href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, +\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) Vehtari, A., Gelman, A., and Gabry, J. (2017). Practical - Bayesian model evaluation using leave-one-out cross-validation and WAIC. - \emph{Statistics and Computing}. 27(5), 1413--1432. - doi:10.1007/s11222-016-9696-4. arXiv preprint: - \url{https://arxiv.org/abs/1507.04544/} +Bayesian model evaluation using leave-one-out cross-validation and WAIC. +\emph{Statistics and Computing}. 27(5), 1413--1432. +doi:10.1007/s11222-016-9696-4. arXiv preprint: +\url{https://arxiv.org/abs/1507.04544/} } \seealso{ Other PPCs: \code{\link{PPC-discrete}}, diff --git a/man/PPC-overview.Rd b/man/PPC-overview.Rd index 61189fcc0..9337ed35d 100644 --- a/man/PPC-overview.Rd +++ b/man/PPC-overview.Rd @@ -5,12 +5,12 @@ \alias{PPC} \title{Graphical posterior predictive checking} \description{ -The \pkg{bayesplot} PPC module provides various plotting functions for +The \strong{bayesplot} PPC module provides various plotting functions for creating graphical displays comparing observed data to simulated data from the posterior predictive distribution. See below for a brief discussion of the ideas behind posterior predictive checking, a description of the structure of this package, and tips on providing an interface to -\pkg{bayesplot} from another package. +\strong{bayesplot} from another package. } \details{ The idea behind posterior predictive checking is simple: if a model is a good @@ -24,8 +24,9 @@ distribution is the distribution of the outcome variable implied by a model after using the observed data \eqn{y} (a vector of outcome values), and typically predictors \eqn{X}, to update our beliefs about the unknown parameters \eqn{\theta} in the model. For each draw of the parameters -\eqn{\theta} from the posterior distribution \eqn{p(\theta \,|\, y, -X)}{p(\theta | y, X)} we generate an entire vector of outcomes. The result is +\eqn{\theta} from the posterior distribution +\eqn{p(\theta \,|\, y, X)}{p(\theta | y, X)} +we generate an entire vector of outcomes. The result is an \eqn{S \times N}{S x N} matrix of simulations, where \eqn{S} is the the size of the posterior sample (number of draws from the posterior distribution) and \eqn{N} is the number of data points in \eqn{y}. That is, @@ -44,79 +45,65 @@ for this package. } \subsection{Graphical posterior predictive checking}{ Using the datasets \eqn{y^{rep}}{yrep} drawn from the posterior predictive -distribution, the functions in the \pkg{bayesplot} package produce various +distribution, the functions in the \strong{bayesplot} package produce various graphical displays comparing the observed data \eqn{y} to the replications. For a more thorough discussion of posterior predictive checking see Chapter 6 of Gelman et. al. (2013). } } \section{PPC plotting functions}{ - - -The plotting functions for posterior predictive checking in this package are -organized into several categories, each with its own documentation: - -\describe{ - \item{\strong{\link[=PPC-distributions]{Distributions}}}{ - Histograms, kernel density estimates, boxplots, and other plots comparing - the empirical distribution of the observed data \code{y} to the - distributions of individual replicated datasets (rows) in \code{yrep}. - } - \item{\strong{\link[=PPC-test-statistics]{Test statistics}}}{ - The distribution of a test statistic, or a pair of test statistics, over - the replicated datasets (rows) in \code{yrep} compared to value of the - statistic(s) computed from \code{y}. - } - \item{\strong{\link[=PPC-intervals]{Intervals}}}{ - Interval estimates of \code{yrep} with \code{y} overlaid. The x-axis - variable can be optionally specified by the user (e.g. to plot against - against a predictor variable or over time). - } - \item{\strong{\link[=PPC-errors]{Predictive errors}}}{ - Plots of predictive errors (\code{y - yrep}) computed from \code{y} and - replicated datasets (rows) in \code{yrep}. For binomial models binned - error plots are also available. - } - \item{\strong{\link[=PPC-scatterplots]{Scatterplots}}}{ - Scatterplots (and similar visualizations) of the observed data \code{y} - vs. individual replicated datasets (rows) in \code{yrep}, or vs. the - average value of the distributions of each data point (columns) in - \code{yrep}. - } - \item{\strong{\link[=PPC-discrete]{Plots for discrete outcomes}}}{ - PPC functions that can only be used if \code{y} and \code{yrep} are - discrete. For example, rootograms for count outcomes and bar - plots for ordinal, categorical, and multinomial outcomes. - } - \item{\strong{\link[=PPC-loo]{LOO predictive checks}}}{ - PPC functions for predictive checks based on (approximate) leave-one-out - (LOO) cross-validation. - } + The plotting functions for posterior +predictive checking in this package are organized into several categories, +each with its own documentation: +\itemize{ +\item \link[=PPC-distributions]{Distributions}: Histograms, kernel density +estimates, boxplots, and other plots comparing the empirical distribution +of the observed data \code{y} to the distributions of individual replicated +datasets (rows) in \code{yrep}. +\item \link[=PPC-test-statistics]{Statistics}: The distribution of a statistic, or a +pair of statistics, over the replicated datasets (rows) in \code{yrep} compared +to value of the statistic(s) computed from \code{y}. +\item \link[=PPC-intervals]{Intervals}: Interval estimates of \code{yrep} with \code{y} +overlaid. The x-axis variable can be optionally specified by the user +(e.g. to plot against against a predictor variable or over time). +\item \link[=PPC-errors]{Predictive errors}: Plots of predictive errors +(\code{y - yrep}) computed from \code{y} and replicated datasets (rows) in \code{yrep}. +For binomial models binned error plots are also available. +\item \link[=PPC-scatterplots]{Scatterplots}: Scatterplots (and similar +visualizations) of the observed data \code{y} vs. individual replicated datasets +(rows) in \code{yrep}, or vs. the average value of the distributions of each data +point (columns) in \code{yrep}. +\item \link[=PPC-discrete]{Plots for discrete outcomes}: PPC functions that can +only be used if \code{y} and \code{yrep} are discrete. For example, rootograms for +count outcomes and bar plots for ordinal, categorical, and +multinomial outcomes. +\item \link[=PPC-loo]{LOO predictive checks}: PPC functions for predictive checks +based on (approximate) leave-one-out (LOO) cross-validation. } } \section{Providing an interface for posterior predictive checking from another package}{ -In addition to the various plotting functions, the \pkg{bayesplot} package -provides the S3 generic \code{\link{pp_check}}. Authors of \R packages for -Bayesian inference are encouraged to define \code{pp_check} methods for the +In addition to the various plotting functions, the \strong{bayesplot} package +provides the S3 generic \code{\link[=pp_check]{pp_check()}}. Authors of \R packages for +Bayesian inference are encouraged to define \code{pp_check()} methods for the fitted model objects created by their packages. See the package vignettes for -more details and a simple example, and see the \pkg{rstanarm} and \pkg{brms} -packages for full examples of \code{pp_check} methods. +more details and a simple example, and see the \strong{rstanarm} and \strong{brms} +packages for full examples of \code{pp_check()} methods. } \references{ Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and - Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. - Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, - (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, - \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, - \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +Gelman, A. (2019), Visualization in Bayesian workflow. +\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378. +(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, +\href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, +\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, - A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC - Press, London, third edition. (Ch. 6) +A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC +Press, London, third edition. (Ch. 6) } \seealso{ Other PPCs: \code{\link{PPC-discrete}}, diff --git a/man/PPC-scatterplots.Rd b/man/PPC-scatterplots.Rd index cc651c31c..486930fab 100644 --- a/man/PPC-scatterplots.Rd +++ b/man/PPC-scatterplots.Rd @@ -18,52 +18,50 @@ ppc_scatter_avg_grouped(y, yrep, group, ..., size = 2.5, alpha = 0.8) \item{yrep}{An \eqn{S} by \eqn{N} matrix of draws from the posterior predictive distribution, where \eqn{S} is the size of the posterior sample -(or subset of the posterior sample used to generate \code{yrep}) and -\eqn{N} is the number of observations (the length of \code{y}). The columns -of \code{yrep} should be in the same order as the data points in \code{y} -for the plots to make sense. See \strong{Details} for additional -instructions.} +(or subset of the posterior sample used to generate \code{yrep}) and \eqn{N} is +the number of observations (the length of \code{y}). The columns of \code{yrep} +should be in the same order as the data points in \code{y} for the plots to make +sense. See \strong{Details} for additional instructions.} \item{...}{Currently unused.} -\item{size, alpha}{Arguments passed to \code{\link[ggplot2]{geom_point}} to -control the appearance of the points.} +\item{size, alpha}{Arguments passed to \code{\link[ggplot2:geom_point]{ggplot2::geom_point()}} to control the +appearance of the points.} \item{group}{A grouping variable (a vector or factor) the same length as \code{y}. Each value in \code{group} is interpreted as the group level pertaining to the corresponding value of \code{y}.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. +A ggplot object that can be further customized using the \strong{ggplot2} package. } \description{ Scatterplots of the observed data \code{y} vs. simulated/replicated data -\code{yrep} from the posterior predictive distribution. See the \strong{Plot -Descriptions} and \strong{Details} sections, below. +\code{yrep} from the posterior predictive distribution. See the +\strong{Plot Descriptions} and \strong{Details} sections, below. } \details{ For Binomial data, the plots will typically be most useful if - \code{y} and \code{yrep} contain the "success" proportions (not discrete - "success" or "failure" counts). +\code{y} and \code{yrep} contain the "success" proportions (not discrete +"success" or "failure" counts). } \section{Plot Descriptions}{ \describe{ - \item{\code{ppc_scatter}}{ - For each dataset (row) in \code{yrep} a scatterplot is generated showing - \code{y} against that row of \code{yrep}. For this plot \code{yrep} should - only contain a small number of rows. - } - \item{\code{ppc_scatter_avg}}{ - A scatterplot of \code{y} against the average values of \code{yrep}, i.e., - the points \code{(mean(yrep[, n]), y[n])}, where each \code{yrep[, n]} is - a vector of length equal to the number of posterior draws. - } - \item{\code{ppc_scatter_avg_grouped}}{ - The same as \code{ppc_scatter_avg}, but a separate plot is generated for - each level of a grouping variable. - } +\item{\code{ppc_scatter()}}{ +For each dataset (row) in \code{yrep} a scatterplot is generated showing \code{y} +against that row of \code{yrep}. For this plot \code{yrep} should only contain a +small number of rows. +} +\item{\code{ppc_scatter_avg()}}{ +A scatterplot of \code{y} against the average values of \code{yrep}, i.e., +the points \code{(mean(yrep[, n]), y[n])}, where each \code{yrep[, n]} is +a vector of length equal to the number of posterior draws. +} +\item{\code{ppc_scatter_avg_grouped()}}{ +The same as \code{ppc_scatter_avg()}, but a separate plot is generated for +each level of a grouping variable. +} } } @@ -86,8 +84,8 @@ ppc_scatter_avg_grouped(y, yrep, group, alpha = 0.7) + lims } \references{ Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, - A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC - Press, London, third edition. (Ch. 6) +A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC +Press, London, third edition. (Ch. 6) } \seealso{ Other PPCs: \code{\link{PPC-discrete}}, diff --git a/man/PPC-test-statistics.Rd b/man/PPC-test-statistics.Rd index 86ed6de32..a581a6e42 100644 --- a/man/PPC-test-statistics.Rd +++ b/man/PPC-test-statistics.Rd @@ -25,31 +25,30 @@ ppc_stat_2d(y, yrep, stat = c("mean", "sd"), ..., size = 2.5, \item{yrep}{An \eqn{S} by \eqn{N} matrix of draws from the posterior predictive distribution, where \eqn{S} is the size of the posterior sample -(or subset of the posterior sample used to generate \code{yrep}) and -\eqn{N} is the number of observations (the length of \code{y}). The columns -of \code{yrep} should be in the same order as the data points in \code{y} -for the plots to make sense. See \strong{Details} for additional -instructions.} +(or subset of the posterior sample used to generate \code{yrep}) and \eqn{N} is +the number of observations (the length of \code{y}). The columns of \code{yrep} +should be in the same order as the data points in \code{y} for the plots to make +sense. See \strong{Details} for additional instructions.} \item{stat}{A single function or a string naming a function, except for -\code{ppc_stat_2d} which requires a vector of exactly two functions or +\code{ppc_stat_2d()} which requires a vector of exactly two functions or function names. In all cases the function(s) should take a vector input and -return a scalar test statistic. If specified as a string (or strings) then +return a scalar statistic. If specified as a string (or strings) then the legend will display function names. If specified as a function (or functions) then generic naming is used in the legend.} \item{...}{Currently unused.} -\item{binwidth}{Passed to \code{\link[ggplot2]{geom_histogram}} to override +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override the default binwidth.} -\item{breaks}{Passed to \code{\link[ggplot2]{geom_histogram}} as an +\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an alternative to \code{binwidth}.} \item{freq}{For histograms, \code{freq=TRUE} (the default) puts count on the y-axis. Setting \code{freq=FALSE} puts density on the y-axis. (For many plots the y-axis text is off by default. To view the count or density -labels on the y-axis see the \code{\link{yaxis_text}} convenience +labels on the y-axis see the \code{\link[=yaxis_text]{yaxis_text()}} convenience function.)} \item{group}{A grouping variable (a vector or factor) the same length as @@ -57,18 +56,17 @@ function.)} pertaining to the corresponding value of \code{y}.} \item{facet_args}{A named list of arguments (other than \code{facets}) passed -to \code{\link[ggplot2]{facet_wrap}} or \code{\link[ggplot2]{facet_grid}} +to \code{\link[ggplot2:facet_wrap]{ggplot2::facet_wrap()}} or \code{\link[ggplot2:facet_grid]{ggplot2::facet_grid()}} to control faceting.} -\item{size, alpha}{Arguments passed to \code{\link[ggplot2]{geom_point}} to -control the appearance of scatterplot points.} +\item{size, alpha}{Arguments passed to \code{\link[ggplot2:geom_point]{ggplot2::geom_point()}} to control the +appearance of scatterplot points.} } \value{ -A ggplot object that can be further customized using the - \pkg{ggplot2} package. +A ggplot object that can be further customized using the \strong{ggplot2} package. } \description{ -The distribution of a test statistic \code{T(yrep)}, or a pair of test +The distribution of a (test) statistic \code{T(yrep)}, or a pair of (test) statistics, over the simulated datasets in \code{yrep}, compared to the observed value \code{T(y)} computed from the data \code{y}. See the \strong{Plot Descriptions} and \strong{Details} sections, below, as @@ -76,31 +74,30 @@ well as \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)}. } \details{ For Binomial data, the plots will typically be most useful if - \code{y} and \code{yrep} contain the "success" proportions (not discrete - "success" or "failure" counts). +\code{y} and \code{yrep} contain the "success" proportions (not discrete +"success" or "failure" counts). } \section{Plot Descriptions}{ \describe{ - \item{\code{ppc_stat}}{ - A histogram of the distribution of a test statistic computed by applying - \code{stat} to each dataset (row) in \code{yrep}. The value of the - statistic in the observed data, \code{stat(y)}, is overlaid as a vertical - line. More details on \code{ppc_stat} can be found in Gabry et al. - (2019). - } - \item{\code{ppc_stat_grouped,ppc_stat_freqpoly_grouped}}{ - The same as \code{ppc_stat}, but a separate plot is generated for each - level of a grouping variable. In the case of - \code{ppc_stat_freqpoly_grouped} the plots are frequency polygons rather - than histograms. More details on \code{ppc_stat_grouped} can be found in - Gabry et al. (2019). - } - \item{\code{ppc_stat_2d}}{ - A scatterplot showing the joint distribution of two test statistics - computed over the datasets (rows) in \code{yrep}. The value of the - statistics in the observed data is overlaid as large point. - } +\item{\code{ppc_stat()}}{ +A histogram of the distribution of a test statistic computed by applying +\code{stat} to each dataset (row) in \code{yrep}. The value of the statistic in the +observed data, \code{stat(y)}, is overlaid as a vertical line. More details on +\code{ppc_stat()} can be found in Gabry et al. (2019). +} +\item{\code{ppc_stat_grouped()},\code{ppc_stat_freqpoly_grouped()}}{ +The same as \code{ppc_stat()}, but a separate plot is generated for each +level of a grouping variable. In the case of +\code{ppc_stat_freqpoly_grouped()} the plots are frequency polygons rather +than histograms. More details on \code{ppc_stat_grouped()} can be found in +Gabry et al. (2019). +} +\item{\code{ppc_stat_2d()}}{ +A scatterplot showing the joint distribution of two test statistics +computed over the datasets (rows) in \code{yrep}. The value of the +statistics in the observed data is overlaid as large point. +} } } @@ -131,15 +128,15 @@ ppc_stat(y, yrep, stat = function(y) quantile(y, 0.25)) } \references{ Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and - Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. - Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, - (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, - \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, - \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +Gelman, A. (2019), Visualization in Bayesian workflow. +\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378. +(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, +\href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, +\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) Gelman, A., Carlin, J. B., Stern, H. S., Dunson, D. B., Vehtari, - A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC - Press, London, third edition. (Ch. 6) +A., and Rubin, D. B. (2013). \emph{Bayesian Data Analysis.} Chapman & Hall/CRC +Press, London, third edition. (Ch. 6) } \seealso{ Other PPCs: \code{\link{PPC-discrete}}, diff --git a/man/available_ppc.Rd b/man/available_ppc.Rd index 3953387e4..9866af5b3 100644 --- a/man/available_ppc.Rd +++ b/man/available_ppc.Rd @@ -10,15 +10,15 @@ available_ppc(pattern, fixed = FALSE, invert = FALSE) available_mcmc(pattern, fixed = FALSE, invert = FALSE) } \arguments{ -\item{pattern, fixed, invert}{Passed to \code{\link[base]{grep}}.} +\item{pattern, fixed, invert}{Passed to \code{\link[base:grep]{base::grep()}}.} } \value{ A possibly empty character vector of function names with several - additional attributes (for use by a custom print method). If \code{pattern} - is missing then the returned object contains the names of all available - plotting functions in the \link{MCMC} or \link{PPC} module, depending on - which function is called. If \code{pattern} is specified then a subset of - function names is returned. +additional attributes (for use by a custom print method). If \code{pattern} +is missing then the returned object contains the names of all available +plotting functions in the \link{MCMC} or \link{PPC} module, depending on +which function is called. If \code{pattern} is specified then a subset of +function names is returned. } \description{ Get or view the names of available plotting functions diff --git a/man/bayesplot-colors.Rd b/man/bayesplot-colors.Rd index 28aaeaa3d..0ccb0e3ef 100644 --- a/man/bayesplot-colors.Rd +++ b/man/bayesplot-colors.Rd @@ -150,6 +150,6 @@ ppc_stat(y, yrep, stat = "var") + legend_none() } \seealso{ -\code{\link{theme_default}} for the default ggplot theme used by - \pkg{bayesplot} and \code{\link{bayesplot_theme_set}} to change it. +\code{\link[=theme_default]{theme_default()}} for the default ggplot theme used by +\strong{bayesplot} and \code{\link[=bayesplot_theme_set]{bayesplot_theme_set()}} to change it. } diff --git a/man/bayesplot-extractors.Rd b/man/bayesplot-extractors.Rd index bd54ab062..2f7855b32 100644 --- a/man/bayesplot-extractors.Rd +++ b/man/bayesplot-extractors.Rd @@ -55,28 +55,26 @@ neff_ratio(object, ...) whether to include warmup draws, if applicable.} \item{pars}{An optional character vector of parameter names. For -\code{nuts_params} these will be NUTS sampler parameter names rather than +\code{nuts_params()} these will be NUTS sampler parameter names rather than model parameters. If \code{pars} is omitted all parameters are included.} -\item{regex_pars}{An optional \link[=grep]{regular expression} to use for +\item{regex_pars}{An optional \link[base:grep]{regular expression} to use for parameter selection. Can be specified instead of \code{pars} or in addition to \code{pars}.} } \value{ \describe{ -\item{\code{log_posterior}}{ -\code{log_posterior} methods return a molten data frame (see -\code{\link[reshape2]{melt}}). The data frame should have columns -\code{"Iteration"} (integer), \code{"Chain"} (integer), and \code{"Value"} -(numeric). See \strong{Examples}, below. -} -\item{\code{nuts_params}}{ -\code{nuts_params} methods return a molten data frame (see -\code{\link[reshape2]{melt}}). The data frame should have columns -\code{"Parameter"} (factor), \code{"Iteration"} (integer), \code{"Chain"} +\item{\code{log_posterior()}}{ +\code{log_posterior()} methods return a molten data frame (see \code{\link[reshape2:melt]{reshape2::melt()}}). +The data frame should have columns \code{"Iteration"} (integer), \code{"Chain"} (integer), and \code{"Value"} (numeric). See \strong{Examples}, below. } -\item{\code{rhat}, \code{neff_ratio}}{ +\item{\code{nuts_params()}}{ +\code{nuts_params()} methods return a molten data frame (see \code{\link[reshape2:melt]{reshape2::melt()}}). +The data frame should have columns \code{"Parameter"} (factor), \code{"Iteration"} +(integer), \code{"Chain"} (integer), and \code{"Value"} (numeric). See \strong{Examples}, below. +} +\item{\code{rhat()}, \code{neff_ratio()}}{ Methods return (named) vectors. } } @@ -84,7 +82,7 @@ Methods return (named) vectors. \description{ Generics and methods for extracting quantities needed for plotting from various types of model objects. Currently methods are only provided for -stanfit (\pkg{rstan}) and stanreg (\pkg{rstanarm}) objects, but adding new +stanfit (\strong{rstan}) and stanreg (\strong{stanreg}) objects, but adding new methods should be relatively straightforward. } \examples{ @@ -103,5 +101,5 @@ tail(lp) } \seealso{ -\code{\link{MCMC-nuts}}, \code{\link{MCMC-diagnostics}} +\link{MCMC-nuts}, \link{MCMC-diagnostics} } diff --git a/man/bayesplot-helpers.Rd b/man/bayesplot-helpers.Rd index c5f01b50a..bf336881e 100644 --- a/man/bayesplot-helpers.Rd +++ b/man/bayesplot-helpers.Rd @@ -76,26 +76,26 @@ the first argument to \code{fun}.} vector.} \item{...}{For the various \code{vline_}, \code{hline_}, and \code{abline_} - functions, \code{...} is passed to \code{\link[ggplot2]{geom_vline}}, - \code{\link[ggplot2]{geom_hline}}, and \code{\link[ggplot2]{geom_abline}}, - respectively, to control the appearance of the line(s). +functions, \code{...} is passed to \code{\link[ggplot2:geom_vline]{ggplot2::geom_vline()}}, +\code{\link[ggplot2:geom_hline]{ggplot2::geom_hline()}}, and \code{\link[ggplot2:geom_abline]{ggplot2::geom_abline()}}, +respectively, to control the appearance of the line(s). - For functions ending in \code{_bg}, \code{...} is passed to - \code{\link[ggplot2]{element_rect}}. +For functions ending in \code{_bg}, \code{...} is passed to +\code{\link[ggplot2:element_rect]{ggplot2::element_rect()}}. - For functions ending in \code{_text} or \code{_title}, \code{...} is passed - to \code{\link[ggplot2]{element_text}}. +For functions ending in \code{_text} or \code{_title}, \code{...} is passed +to \code{\link[ggplot2:element_text]{ggplot2::element_text()}}. - For \code{xaxis_ticks} and \code{yaxis_ticks}, \code{...} is passed to - \code{\link[ggplot2]{element_line}}. +For \code{xaxis_ticks} and \code{yaxis_ticks}, \code{...} is passed to +\code{\link[ggplot2:element_line]{ggplot2::element_line()}}. - For \code{overlay_function}, \code{...} is passed to - \code{\link[ggplot2]{stat_function}}.} +For \code{overlay_function}, \code{...} is passed to +\code{\link[ggplot2:stat_function]{ggplot2::stat_function()}}.} \item{na.rm}{A logical scalar passed to the appropriate geom (e.g. -\code{\link[ggplot2]{geom_vline}}). The default is \code{TRUE}.} +\code{\link[ggplot2:geom_vline]{ggplot2::geom_vline()}}). The default is \code{TRUE}.} -\item{p}{The probability mass (in [0,1]) to include in the interval.} +\item{p}{The probability mass (in \code{[0,1]}) to include in the interval.} \item{med}{Should the median also be included in addition to the lower and upper bounds of the interval?} @@ -106,98 +106,93 @@ or a string among \code{"right"}, \code{"left"}, \code{"top"}, \code{"bottom"}. Using \code{position = "none"} is also allowed and is equivalent to using \code{legend_none()}.} -\item{on}{For functions modifying ggplot \link[ggplot2]{theme} elements, set -\code{on=FALSE} to set the element to \code{\link[ggplot2]{element_blank}}. -For example, facet text can be removed by adding -\code{facet_text(on=FALSE)}, or simply \code{facet_text(FALSE)} to a ggplot -object. If \code{on=TRUE} (the default), then \code{...} can be used to -customize the appearance of the theme element.} +\item{on}{For functions modifying ggplot \link[ggplot2:theme]{theme} elements, +set \code{on=FALSE} to set the element to \code{\link[ggplot2:element_blank]{ggplot2::element_blank()}}. For +example, facet text can be removed by adding \code{facet_text(on=FALSE)}, or +simply \code{facet_text(FALSE)} to a ggplot object. If \code{on=TRUE} (the default), +then \code{...} can be used to customize the appearance of the theme element.} -\item{color, size}{Passed to \code{\link[ggplot2]{element_line}}.} +\item{color, size}{Passed to \code{\link[ggplot2:element_line]{ggplot2::element_line()}}.} } \value{ -A \pkg{ggplot2} layer or \code{\link[ggplot2]{theme}} object that can be +A \strong{ggplot2} layer or \code{\link[ggplot2:theme]{ggplot2::theme()}} object that can be added to existing ggplot objects, like those created by many of the -\pkg{bayesplot} plotting functions. See the \strong{Details} section. +\strong{bayesplot} plotting functions. See the \strong{Details} section. } \description{ Convenience functions for adding to (and changing details of) ggplot objects -(many of the objects returned by \pkg{bayesplot} functions). See the +(many of the objects returned by \strong{bayesplot} functions). See the \strong{Examples} section, below. } \details{ \subsection{Add vertical, horizontal, and diagonal lines to plots}{ \itemize{ -\item \code{vline_at} and \code{hline_at} return an object created by either -\code{geom_vline} or \code{geom_hline} that can be added to a ggplot object -to draw a vertical or horizontal line (at one or several values). If -\code{fun} is missing then the lines are drawn at the values in \code{v}. If -\code{fun} is specified then the lines are drawn at the values returned by -\code{fun(v)}. - -\item \code{vline_0} and \code{hline_0} are wrappers for \code{vline_at} and -\code{hline_at} with \code{v = 0} and \code{fun} missing. - -\item \code{abline_01} is a wrapper for \code{geom_abline} with the intercept -set to 0 and the slope set to 1. - -\item \code{lbub} returns a \emph{function} that takes a single argument -\code{x} and returns the lower and upper bounds (\code{lb}, \code{ub}) of the -\code{100*p}\% central interval of \code{x}, as well as the median (if -\code{med} is \code{TRUE}). +\item \code{vline_at()} and \code{hline_at()} return an object created by either +\code{\link[ggplot2:geom_vline]{ggplot2::geom_vline()}} or \code{\link[ggplot:geom_hline]{ggplot::geom_hline()}} that can be added to a +ggplot object to draw a vertical or horizontal line (at one or several +values). If \code{fun} is missing then the lines are drawn at the values in \code{v}. +If \code{fun} is specified then the lines are drawn at the values returned by \code{fun(v)}. +\item \code{vline_0()} and \code{hline_0()} are wrappers for \code{vline_at()} and \code{hline_at()} +with \code{v = 0} and \code{fun} missing. +\item \code{abline_01()} is a wrapper for \code{\link[ggplot2:geom_abline]{ggplot2::geom_abline()}} with the intercept +set to \code{0} and the slope set to \code{1}. +\item \code{lbub()} returns a \emph{function} that takes a single argument \code{x} and returns +the lower and upper bounds (\code{lb}, \code{ub}) of the \code{100*p}\% central interval +of \code{x}, as well as the median (if \code{med=TRUE}). } } + \subsection{Control appearance of facet strips}{ \itemize{ -\item \code{facet_text} and \code{facet_bg} return ggplot2 theme objects that -can be added to an existing plot (ggplot object) to format the text and the -background for the facet strips. +\item \code{facet_text()} returns ggplot2 theme objects that can be added to an +existing plot (ggplot object) to format the text in facet strips. +\item \code{facet_bg()} can be added to a plot to change the background of the facet strips. } } + \subsection{Move legend, remove legend, or style the legend text}{ \itemize{ -\item \code{legend_move} and \code{legend_none} return a ggplot2 theme object -that can be added to an existing plot (ggplot object) in order to change the -position of the legend (\code{legend_move}) or remove the legend -(\code{legend_none}). \code{legend_text} works much like \code{facet_text}, -except it controls the legend text. +\item \code{legend_move()} and \code{legend_none()} return a ggplot2 theme object that can +be added to an existing plot (ggplot object) in order to change the +position of the legend or remove it. +\item \code{legend_text()} works much like \code{facet_text()} but for the legend. } } + \subsection{Control appearance of \eqn{x}-axis and \eqn{y}-axis features}{ \itemize{ -\item \code{xaxis_title} and \code{yaxis_title} return a ggplot2 theme object +\item \code{xaxis_title()} and \code{yaxis_title()} return a ggplot2 theme object that can be added to an existing plot (ggplot object) in order to toggle or format the titles displayed on the \code{x} or \code{y} axis. (To change -the titles themselves use \code{\link[ggplot2]{labs}}.) - -\item \code{xaxis_text} and \code{yaxis_text} return a ggplot2 theme object +the titles themselves use \code{\link[ggplot2:labs]{ggplot2::labs()}}.) +\item \code{xaxis_text()} and \code{yaxis_text()} return a ggplot2 theme object that can be added to an existing plot (ggplot object) in order to toggle or format the text displayed on the \code{x} or \code{y} axis (e.g. tick labels). - -\item \code{xaxis_ticks} and \code{yaxis_ticks} return a ggplot2 theme object +\item \code{xaxis_ticks()} and \code{yaxis_ticks()} return a ggplot2 theme object that can be added to an existing plot (ggplot object) to change the appearance of the axis tick marks. } } + \subsection{Customize plot background}{ \itemize{ -\item \code{plot_bg} returns a ggplot2 theme object that can be added to an +\item \code{plot_bg()} returns a ggplot2 theme object that can be added to an existing plot (ggplot object) to format the background of the \emph{entire} plot. -\item \code{panel_bg} returns a ggplot2 theme object that can be added to an +\item \code{panel_bg()} returns a ggplot2 theme object that can be added to an existing plot (ggplot object) to format the background of the just the plotting area. -\item \code{grid_lines} returns a ggplot2 theme object that can be added to +\item \code{grid_lines()} returns a ggplot2 theme object that can be added to an existing plot (ggplot object) to add grid lines to the plot background. } } + \subsection{Superimpose a function on an existing plot}{ \itemize{ -\item \code{overlay_function} is a simple wrapper for -\code{\link[ggplot2]{stat_function}} but with the \code{inherit.aes} argument -fixed to \code{FALSE}. Fixing \code{inherit.aes=FALSE} will avoid potential -errors due to the \code{\link[ggplot2]{aes}}thetic mapping used by certain -\pkg{bayesplot} plotting functions). +\item \code{overlay_function()} is a simple wrapper for \code{\link[ggplot2:stat_function]{ggplot2::stat_function()}} but +with the \code{inherit.aes} argument fixed to \code{FALSE}. Fixing \code{inherit.aes=FALSE} +will avoid potential errors due to the \code{\link[ggplot2:aes]{ggplot2::aes()}}thetic mapping used by +certain \strong{bayesplot} plotting functions. } } } @@ -335,6 +330,6 @@ mcmc_hist(x, pars = "beta[1]") + purple_gaussian } \seealso{ -\code{\link{theme_default}} for the default ggplot theme used by - \pkg{bayesplot}. +\code{\link[=theme_default]{theme_default()}} for the default ggplot theme used by +\strong{bayesplot}. } diff --git a/man/bayesplot-package.Rd b/man/bayesplot-package.Rd index e086870f7..c0c0df256 100644 --- a/man/bayesplot-package.Rd +++ b/man/bayesplot-package.Rd @@ -8,36 +8,37 @@ \description{ \if{html}{ \figure{stanlogo.png}{options: width="50px" alt="mc-stan.org"} - \emph{Stan Development Team} } +\emph{Stan Development Team} -The \pkg{bayesplot} package provides a variety of \pkg{ggplot2}-based +The \strong{bayesplot} package provides a variety of \strong{ggplot2}-based plotting functions for use after fitting Bayesian models (typically, though not exclusively, via Markov chain Monte Carlo). The package is designed not only to provide convenient functionality for users, but also a common set of functions that can be easily used by developers working on a variety of packages for Bayesian modeling, particularly (but not necessarily) packages -powered by \pkg{\link[rstan]{rstan}}. Examples of packages that will soon (or -already are) using \pkg{bayesplot} are \pkg{rstan} itself, as well as the -\pkg{rstan}-dependent \pkg{rstanarm} and \pkg{brms} packages for applied -regression modeling. +powered by \link[rstan:rstan-package]{rstan}. Examples of packages that will soon +(or already are) using \strong{bayesplot} are \strong{rstan} itself, as well as the +\strong{rstan}-dependent \strong{rstanarm} and \strong{brms} packages for applied regression +modeling. } \section{Plotting functionality}{ - \if{html}{ +\if{html}{ \figure{bayesplot1.png}{options: width="30\%" alt="mcmc_areas"} \figure{bayesplot2.png}{options: width="30\%" alt="ppc_hist"} \figure{bayesplot3.png}{options: width="30\%" alt="ppc_dens_overlay"} } -The plotting functions in \pkg{bayesplot} are organized into several modules: +The plotting functions in \strong{bayesplot} are organized into several modules: \itemize{ - \item \strong{\link[=MCMC-overview]{MCMC}}: Visualizations of Markov chain - Monte Carlo (MCMC) simulations generated by \emph{any} MCMC algorithm - as well as diagnostics. There are also additional functions specifically - for use with models fit using the \link[=NUTS]{No-U-Turn Sampler (NUTS)}. - \item \strong{\link[=PPC-overview]{PPC}}: Graphical posterior predictive checks (PPCs). +\item \link[=MCMC-overview]{MCMC}: Visualizations of Markov chain +Monte Carlo (MCMC) simulations generated by \emph{any} MCMC algorithm +as well as diagnostics. There are also additional functions specifically +for use with models fit using the \link[=NUTS]{No-U-Turn Sampler (NUTS)}. +\item \link[=PPC-overview]{PPC}: Graphical posterior predictive checks (PPCs). } + In future releases modules will be added specifically for forecasting/out-of-sample prediction and other inference-related tasks. } @@ -45,19 +46,13 @@ forecasting/out-of-sample prediction and other inference-related tasks. \section{Resources}{ \itemize{ - \item{\strong{Bug reports and feature requests}:}{ - If you would like to request a new feature or if you have noticed a bug that - needs to be fixed please let us know at the \pkg{bayesplot} issue tracker on - GitHub: - - \url{https://github.com/stan-dev/bayesplot/issues/}. - } - \item{\strong{General questions and help}:}{ - To ask a question about \pkg{bayesplot} on the Stan Forums - forum please visit: - - \url{https://discourse.mc-stan.org}. -} +\item \strong{Bug reports and feature requests}: If you would like to request a new +feature or if you have noticed a bug that needs to be fixed please let us +know at the \strong{bayesplot} issue tracker at +\url{https://github.com/stan-dev/bayesplot/issues/} +\item \strong{General questions and help}: +To ask a question about \strong{bayesplot} on the Stan Forums forum please visit +\url{https://discourse.mc-stan.org}. } } @@ -95,18 +90,18 @@ ppc_hist(y, yrep[1:8, ]) } \references{ Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and - Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat. - Soc. A}, 182: 389-402. doi:10.1111/rssa.12378, - (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, - \href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, - \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) +Gelman, A. (2019), Visualization in Bayesian workflow. +\emph{J. R. Stat. Soc. A}, 182: 389-402. doi:10.1111/rssa.12378. +(\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version}, +\href{https://arxiv.org/abs/1709.01449}{arXiv preprint}, +\href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub}) } \seealso{ -\code{\link{theme_default}} for the default ggplot theme used by - \pkg{bayesplot} and \code{\link{bayesplot_theme_set}} to change it. +\code{\link[=theme_default]{theme_default()}} for the default ggplot theme used by +\strong{bayesplot} and \code{\link[=bayesplot_theme_set]{bayesplot_theme_set()}} to change it. -\code{\link{bayesplot-colors}} to set or view the color scheme used - for plotting. +\link{bayesplot-colors} to set or view the color scheme used +for plotting. -\code{\link[ggplot2]{ggsave}} in \pkg{ggplot2} for saving plots. +\code{\link[ggplot2:ggsave]{ggplot2::ggsave()}} for saving plots. } diff --git a/man/bayesplot_grid.Rd b/man/bayesplot_grid.Rd index 992e2a3bc..091804c60 100644 --- a/man/bayesplot_grid.Rd +++ b/man/bayesplot_grid.Rd @@ -18,7 +18,7 @@ specifying plot objects via \code{...}.} upper limits for the axes that will be shared across all plots.} \item{grid_args}{An optional named list of arguments to pass to -\code{\link[gridExtra]{arrangeGrob}} (\code{nrow}, \code{ncol}, +\code{\link[gridExtra:arrangeGrob]{gridExtra::arrangeGrob()}} (\code{nrow}, \code{ncol}, \code{widths}, etc.).} \item{titles, subtitles}{Optional character vectors of plot titles and @@ -35,8 +35,8 @@ Setting this to \code{FALSE} will make the returned object smaller but these individual plot objects will not be available.} } \value{ -An object of class "bayesplot_grid" (essentially a gtable object from - \code{\link[gridExtra]{arrangeGrob}}), which has a \code{plot} method. +An object of class \code{"bayesplot_grid"} (essentially a gtable object +from \code{\link[gridExtra:arrangeGrob]{gridExtra::arrangeGrob()}}), which has a \code{plot} method. } \description{ The \code{bayesplot_grid} function makes it simple to juxtapose plots using diff --git a/man/bayesplot_theme_get.Rd b/man/bayesplot_theme_get.Rd index e69e88b69..163dfab38 100644 --- a/man/bayesplot_theme_get.Rd +++ b/man/bayesplot_theme_get.Rd @@ -17,34 +17,32 @@ bayesplot_theme_replace(...) } \arguments{ \item{new}{The new theme (list of theme elements) to use. This is analogous -to the \code{new} argument to \code{\link[ggplot2]{theme_set}}.} +to the \code{new} argument to \code{\link[ggplot2:theme_set]{ggplot2::theme_set()}}.} \item{...}{A named list of theme settings.} } \value{ -\code{bayesplot_theme_get} returns the current theme. The other three - functions (set, update, replace) invisibly return the \emph{previous} theme - so it can be saved and easily restored later. This is the same behavior as - the \pkg{ggplot2} versions of these functions. +\code{bayesplot_theme_get()} returns the current theme. The other three +functions (set, update, replace) invisibly return the \emph{previous} theme +so it can be saved and easily restored later. This is the same behavior as +the \strong{ggplot2} versions of these functions. } \description{ -These functions are the \pkg{bayesplot} equivalent to - \pkg{ggplot2}'s \code{\link[ggplot2]{theme_set}} and friends. They set, - get, and update the active theme but only apply them to \code{bayesplots}. - The current/active theme is automatically applied to every \code{bayesplot} - you draw. - - Use \code{bayesplot_theme_get} to get the current \pkg{bayesplot} theme, - and \code{bayesplot_theme_set} to change it. \code{bayesplot_theme_update} - and \code{bayesplot_theme_replace} are shorthands for changing individual - elements. +These functions are the \strong{bayesplot} equivalent to +\strong{ggplot2}'s \code{\link[ggplot2:theme_set]{ggplot2::theme_set()}} and friends. They set, get, and update +the active theme but only apply them to \code{bayesplots}. The current/active +theme is automatically applied to every \code{bayesplot} you draw. + +Use \code{bayesplot_theme_get()} to get the current \strong{bayesplot} theme, and +\code{bayesplot_theme_set()} to change it. \code{bayesplot_theme_update()} and +\code{bayesplot_theme_replace()} are shorthands for changing individual elements. } \details{ -\code{bayesplot_theme_set} and friends only apply to - \code{bayesplots}. However, \code{ggplot2::theme_set} can also be used to - change the \pkg{bayesplot} theme. Currently, setting a theme with - \code{ggplot2::theme_set} (other than the \pkg{ggplot2} default - \code{\link[ggplot2]{theme_grey}}) will override the \pkg{bayesplot} theme. +\code{bayesplot_theme_set()} and friends only apply to +\code{bayesplots}. However, \code{\link[ggplot2:theme_set]{ggplot2::theme_set()}} can also be used to +change the \strong{bayesplot} theme. Currently, setting a theme with +\code{ggplot2::theme_set()} (other than the \strong{ggplot2} default +\code{\link[ggplot2:theme_grey]{ggplot2::theme_grey()}}) will override the \strong{bayesplot} theme. } \examples{ library(ggplot2) @@ -85,12 +83,12 @@ mcmc_hist(x) + panel_bg(fill = "black") } \seealso{ -\code{\link{theme_default}} for the default \pkg{bayesplot} theme. +\code{\link[=theme_default]{theme_default()}} for the default \strong{bayesplot} theme. \link{bayesplot-helpers} for a variety of convenience functions, - many of which provide shortcuts for tweaking theme elements after creating - a plot. +many of which provide shortcuts for tweaking theme elements after creating +a plot. -\code{\link{bayesplot-colors}} to set or view the color scheme used - for plotting. +\link{bayesplot-colors} to set or view the color scheme used +for plotting. } diff --git a/man/example-data.Rd b/man/example-data.Rd index 4da9f3140..6f1017352 100644 --- a/man/example-data.Rd +++ b/man/example-data.Rd @@ -31,7 +31,7 @@ See \strong{Details}. } \description{ These functions return various objects containing data used in the examples -throughout the \pkg{bayesplot} package documentation. +throughout the \strong{bayesplot} package documentation. } \details{ Each of these functions returns an object containing data, parameter draws, or @@ -41,34 +41,34 @@ predictions corresponding to a basic linear regression model with data (error sd). \describe{ -\item{\code{example_mcmc_draws}}{ - If \code{chains > 1}, a \code{250} (iterations) by \code{chains} by - \code{params} array or, if \code{chains = 1}, a \code{250} by \code{params} - matrix of MCMC draws from the posterior distribution of the parameters in - the linear regression model described above. If \code{params = 1} then only - the draws for \code{alpha} are included in the returned object. If - \code{params >= 2} then draws for \code{sigma} are also included. And if - \code{params} is between \code{3} and the maximum of \code{6} then draws - for regression coefficients \code{beta[k]} (\code{k} in \code{1:(params-2)}) - are also included. +\item{\code{example_mcmc_draws()}}{ +If \code{chains > 1}, a \code{250} (iterations) by \code{chains} by +\code{params} array or, if \code{chains = 1}, a \code{250} by \code{params} +matrix of MCMC draws from the posterior distribution of the parameters in +the linear regression model described above. If \code{params = 1} then only +the draws for \code{alpha} are included in the returned object. If +\code{params >= 2} then draws for \code{sigma} are also included. And if +\code{params} is between \code{3} and the maximum of \code{6} then draws +for regression coefficients \code{beta[k]} (\code{k} in \code{1:(params-2)}) +are also included. } -\item{\code{example_y_data}}{ - A numeric vector with \code{434} observations of the outcome variable in the - linear regression model. +\item{\code{example_y_data()}}{ +A numeric vector with \code{434} observations of the outcome variable in the +linear regression model. } -\item{\code{example_x_data}}{ - A numeric vector with \code{434} observations of one of the predictor - variables in the linear regression model. +\item{\code{example_x_data()}}{ +A numeric vector with \code{434} observations of one of the predictor +variables in the linear regression model. } -\item{\code{example_group_data}}{ - A factor variable with \code{434} observations of a grouping variable with - two levels. +\item{\code{example_group_data()}}{ +A factor variable with \code{434} observations of a grouping variable with +two levels. } -\item{\code{example_yrep_draws}}{ - A \code{500} (draws) by \code{434} (data points) matrix of draws from the - posterior predictive distribution. Each row represents a full dataset drawn - from the posterior predictive distribution of the outcome \code{y} after - fitting the linear regression model mentioned above. +\item{\code{example_yrep_draws()}}{ +A \code{500} (draws) by \code{434} (data points) matrix of draws from the +posterior predictive distribution. Each row represents a full dataset drawn +from the posterior predictive distribution of the outcome \code{y} after +fitting the linear regression model mentioned above. } } } diff --git a/man/pp_check.Rd b/man/pp_check.Rd index 294021192..2f3775549 100644 --- a/man/pp_check.Rd +++ b/man/pp_check.Rd @@ -16,37 +16,35 @@ takes \code{object} to be a \code{y} (outcome) vector.} \item{...}{For the generic, arguments passed to individual methods. For the default method, these are additional arguments to pass to \code{fun}.} -\item{yrep}{For the default method, a \code{yrep} matrix passed to -\code{fun}.} +\item{yrep}{For the default method, a \code{yrep} matrix passed to \code{fun}.} \item{fun}{For the default method, the plotting function to call. Can be any of the \link[=PPC]{PPC functions}. The \code{"ppc_"} prefix can optionally be dropped if \code{fun} is specified as a string.} } \value{ -The exact form of the value returned by \code{pp_check} may vary by - the class of \code{object}, but for consistency we encourage authors of - methods to return the ggplot object created by one of \pkg{bayesplot}'s - plotting functions. The default method returns the object returned by - \code{fun}. +The exact form of the value returned by \code{pp_check()} may vary by +the class of \code{object}, but for consistency we encourage authors of +methods to return the ggplot object created by one of \strong{bayesplot}'s +plotting functions. The default method returns the object returned by \code{fun}. } \description{ S3 generic with simple default method. The intent is to provide a generic so authors of other \R packages who wish to provide interfaces to the functions -in \pkg{bayesplot} will be encouraged to include \code{pp_check} methods in +in \strong{bayesplot} will be encouraged to include \code{pp_check()} methods in their package, preserving the same naming conventions for posterior predictive checking across many \R packages for Bayesian inference. This is for the convenience of both users and developers. See the \strong{Details} and \strong{Examples} sections, below, and the package vignettes for examples -of defining \code{pp_check} methods. +of defining \code{pp_check()} methods. } \details{ A package that creates fitted model objects of class \code{"foo"} - can include a method \code{pp_check.foo} that prepares the appropriate - inputs (\code{y}, \code{yrep}, etc.) for the \pkg{bayesplot} functions. The - \code{pp_check.foo} method may, for example, let the user choose between - various plots, calling the functions from \pkg{bayesplot} internally as - needed. See \strong{Examples}, below, and the package vignettes. +can include a method \code{pp_check.foo()} that prepares the appropriate +inputs (\code{y}, \code{yrep}, etc.) for the \strong{bayesplot} functions. The +\code{pp_check.foo()} method may, for example, let the user choose between +various plots, calling the functions from \strong{bayesplot} internally as +needed. See \strong{Examples}, below, and the package vignettes. } \examples{ # default method diff --git a/man/theme_default.Rd b/man/theme_default.Rd index 1c4985dc6..8117a2f9c 100644 --- a/man/theme_default.Rd +++ b/man/theme_default.Rd @@ -9,19 +9,17 @@ theme_default(base_size = getOption("bayesplot.base_size", 12), } \arguments{ \item{base_size, base_family}{Base font size and family (passed to -\code{\link[ggplot2]{theme_bw}}). It is possible to set -\code{"bayesplot.base_size"} and \code{"bayesplot.base_family"} via -\code{\link{options}} to change the defaults, which are \code{12} and -\code{"serif"}, respectively.} +\code{\link[ggplot2:theme_bw]{ggplot2::theme_bw()}}). It is possible to set \code{"bayesplot.base_size"} and +\code{"bayesplot.base_family"} via \code{\link[=options]{options()}} to change the defaults, which are +\code{12} and \code{"serif"}, respectively.} } \value{ -A ggplot \link[ggplot2]{theme} object. +A ggplot \link[ggplot2:theme]{theme} object. } \description{ -The \code{\link{theme_default}} function returns the default ggplot -\link{theme} used by the \pkg{bayesplot} plotting functions. See -\code{\link{bayesplot_theme_set}} for details on setting and updating the -plotting theme. +The \code{\link[=theme_default]{theme_default()}} function returns the default ggplot +\link[ggplot2:theme]{theme} used by the \strong{bayesplot} plotting functions. See +\code{\link[=bayesplot_theme_set]{bayesplot_theme_set()}} for details on setting and updating the plotting theme. } \examples{ class(theme_default()) @@ -41,12 +39,12 @@ mcmc_areas(x, regex_pars = "beta") } \seealso{ -\code{\link{bayesplot_theme_set}} to change the ggplot theme. +\code{\link[=bayesplot_theme_set]{bayesplot_theme_set()}} to change the ggplot theme. -\code{\link{bayesplot-colors}} to set or view the color scheme used - for plotting. +\link{bayesplot-colors} to set or view the color scheme used +for plotting. \link{bayesplot-helpers} for a variety of convenience functions, - many of which provide shortcuts for tweaking theme elements after creating - a plot. +many of which provide shortcuts for tweaking theme elements after creating +a plot. } From 456c5cee39d5d31622ed68a639dc1cf06a83308f Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 16 May 2019 01:34:50 -0400 Subject: [PATCH 5/8] fix link --- R/mcmc-traces.R | 2 +- man/MCMC-traces.Rd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/R/mcmc-traces.R b/R/mcmc-traces.R index eafce7e4e..9f73ccc59 100644 --- a/R/mcmc-traces.R +++ b/R/mcmc-traces.R @@ -29,7 +29,7 @@ #' @param window An integer vector of length two specifying the limits of a #' range of iterations to display. #' @param np For models fit using [NUTS] (more generally, any -#' (https://en.wikipedia.org/wiki/Symplectic_integrator)[symplectic integrator]), +#' [symplectic integrator](https://en.wikipedia.org/wiki/Symplectic_integrator)), #' an optional data frame providing NUTS diagnostic information. The data #' frame should be the object returned by [nuts_params()] or one with the same #' structure. If `np` is specified then tick marks are added to the bottom of diff --git a/man/MCMC-traces.Rd b/man/MCMC-traces.Rd index 8b2f0765e..ee298294a 100644 --- a/man/MCMC-traces.Rd +++ b/man/MCMC-traces.Rd @@ -77,7 +77,7 @@ range of iterations to display.} (\code{mcmc_trace_highlight()}).} \item{np}{For models fit using \link{NUTS} (more generally, any -(https://en.wikipedia.org/wiki/Symplectic_integrator)\link{symplectic integrator}), +\href{https://en.wikipedia.org/wiki/Symplectic_integrator}{symplectic integrator}), an optional data frame providing NUTS diagnostic information. The data frame should be the object returned by \code{\link[=nuts_params]{nuts_params()}} or one with the same structure. If \code{np} is specified then tick marks are added to the bottom of From dc6ac8dc53c1ffa477c768410acb743ed9524376 Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 16 May 2019 01:35:51 -0400 Subject: [PATCH 6/8] fix R CMD check issues --- R/bayesplot-helpers.R | 2 +- man/bayesplot-helpers.Rd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/R/bayesplot-helpers.R b/R/bayesplot-helpers.R index 0d0bfa8e1..eb2887813 100644 --- a/R/bayesplot-helpers.R +++ b/R/bayesplot-helpers.R @@ -31,7 +31,7 @@ #' @details #' \subsection{Add vertical, horizontal, and diagonal lines to plots}{ #' * `vline_at()` and `hline_at()` return an object created by either -#' [ggplot2::geom_vline()] or [ggplot::geom_hline()] that can be added to a +#' [ggplot2::geom_vline()] or [ggplot2::geom_hline()] that can be added to a #' ggplot object to draw a vertical or horizontal line (at one or several #' values). If `fun` is missing then the lines are drawn at the values in `v`. #' If `fun` is specified then the lines are drawn at the values returned by `fun(v)`. diff --git a/man/bayesplot-helpers.Rd b/man/bayesplot-helpers.Rd index bf336881e..ade6830dc 100644 --- a/man/bayesplot-helpers.Rd +++ b/man/bayesplot-helpers.Rd @@ -128,7 +128,7 @@ Convenience functions for adding to (and changing details of) ggplot objects \subsection{Add vertical, horizontal, and diagonal lines to plots}{ \itemize{ \item \code{vline_at()} and \code{hline_at()} return an object created by either -\code{\link[ggplot2:geom_vline]{ggplot2::geom_vline()}} or \code{\link[ggplot:geom_hline]{ggplot::geom_hline()}} that can be added to a +\code{\link[ggplot2:geom_vline]{ggplot2::geom_vline()}} or \code{\link[ggplot2:geom_hline]{ggplot2::geom_hline()}} that can be added to a ggplot object to draw a vertical or horizontal line (at one or several values). If \code{fun} is missing then the lines are drawn at the values in \code{v}. If \code{fun} is specified then the lines are drawn at the values returned by \code{fun(v)}. From 021a0105ad6406e712e0e647dffdfcee66f56287 Mon Sep 17 00:00:00 2001 From: jgabry Date: Thu, 16 May 2019 17:50:35 -0400 Subject: [PATCH 7/8] final cleaning --- R/bayesplot-colors.R | 2 +- R/bayesplot-ggplot-themes.R | 22 +++++++++++----------- R/bayesplot-package.R | 12 +++++++----- R/mcmc-intervals.R | 3 +-- man-roxygen/args-transformations.R | 7 ++++--- man/MCMC-distributions.Rd | 6 ++++-- man/MCMC-intervals.Rd | 9 +++++---- man/MCMC-parcoord.Rd | 6 ++++-- man/MCMC-scatterplots.Rd | 6 ++++-- man/MCMC-traces.Rd | 6 ++++-- man/bayesplot-colors.Rd | 2 +- man/bayesplot-package.Rd | 12 +++++++----- man/bayesplot_theme_get.Rd | 16 ++++++++-------- man/theme_default.Rd | 6 +++--- 14 files changed, 64 insertions(+), 51 deletions(-) diff --git a/R/bayesplot-colors.R b/R/bayesplot-colors.R index e18dd010e..e03777338 100644 --- a/R/bayesplot-colors.R +++ b/R/bayesplot-colors.R @@ -1,4 +1,4 @@ -#' Set, get, or view color schemes +#' Set, get, or view **bayesplot** color schemes #' #' Set, get, or view color schemes. Choose from a preset scheme or create a #' custom scheme. See the **Available color schemes** section below for a list diff --git a/R/bayesplot-ggplot-themes.R b/R/bayesplot-ggplot-themes.R index 7dd5fa448..fb7c5bed3 100644 --- a/R/bayesplot-ggplot-themes.R +++ b/R/bayesplot-ggplot-themes.R @@ -1,4 +1,4 @@ -#' Default bayesplot plotting theme +#' Default **bayesplot** plotting theme #' #' The [theme_default()] function returns the default ggplot #' [theme][ggplot2::theme] used by the **bayesplot** plotting functions. See @@ -7,8 +7,8 @@ #' @export #' @param base_size,base_family Base font size and family (passed to #' [ggplot2::theme_bw()]). It is possible to set `"bayesplot.base_size"` and -#' `"bayesplot.base_family"` via [options()] to change the defaults, which are -#' `12` and `"serif"`, respectively. +#' `"bayesplot.base_family"` via [options()] to change the defaults, w +#' hich are `12` and `"serif"`, respectively. #' @return A ggplot [theme][ggplot2::theme] object. #' #' @seealso [bayesplot_theme_set()] to change the ggplot theme. @@ -60,22 +60,22 @@ theme_default <- } -#' Get, set, and modify the active bayesplot theme +#' Get, set, and modify the active **bayesplot** theme #' #' @description These functions are the **bayesplot** equivalent to #' **ggplot2**'s [ggplot2::theme_set()] and friends. They set, get, and update #' the active theme but only apply them to `bayesplots`. The current/active #' theme is automatically applied to every `bayesplot` you draw. #' -#' Use `bayesplot_theme_get()` to get the current **bayesplot** theme, and -#' `bayesplot_theme_set()` to change it. `bayesplot_theme_update()` and +#' Use `bayesplot_theme_get()` to get the current **bayesplot** theme and +#' `bayesplot_theme_set()` to set a new theme. `bayesplot_theme_update()` and #' `bayesplot_theme_replace()` are shorthands for changing individual elements. #' -#' @details `bayesplot_theme_set()` and friends only apply to -#' `bayesplots`. However, [ggplot2::theme_set()] can also be used to -#' change the **bayesplot** theme. Currently, setting a theme with -#' `ggplot2::theme_set()` (other than the **ggplot2** default -#' [ggplot2::theme_grey()]) will override the **bayesplot** theme. +#' @details `bayesplot_theme_set()` and friends only apply to `bayesplots`. +#' However, [ggplot2::theme_set()] can also be used to change the +#' **bayesplot** theme. Currently, setting a theme with `ggplot2::theme_set()` +#' (other than the **ggplot2** default [ggplot2::theme_grey()]) will override +#' the **bayesplot** theme. #' #' @export #' @param new The new theme (list of theme elements) to use. This is analogous diff --git a/R/bayesplot-package.R b/R/bayesplot-package.R index 33eba1f5a..9a9f1e403 100644 --- a/R/bayesplot-package.R +++ b/R/bayesplot-package.R @@ -1,4 +1,4 @@ -#' Plots for Bayesian Models +#' **bayesplot**: Plotting for Bayesian Models #' #' @docType package #' @name bayesplot-package @@ -19,10 +19,10 @@ #' only to provide convenient functionality for users, but also a common set of #' functions that can be easily used by developers working on a variety of #' packages for Bayesian modeling, particularly (but not necessarily) packages -#' powered by [rstan][rstan::rstan-package]. Examples of packages that will soon -#' (or already are) using **bayesplot** are **rstan** itself, as well as the -#' **rstan**-dependent **rstanarm** and **brms** packages for applied regression -#' modeling. +#' powered by [**rstan**][rstan::rstan-package] (the \R interface to Stan). +#' Examples of packages that will soon (or already are) using **bayesplot** are +#' **rstan** itself, as well as the **rstan**-dependent **rstanarm** and +#' **brms** packages for applied regression modeling. #' #' @section Plotting functionality: #' \if{html}{ @@ -42,6 +42,8 @@ #' forecasting/out-of-sample prediction and other inference-related tasks. #' #' @section Resources: +#' * __Online documentation and vignettes__: Visit the __bayesplot__ website at +#' #' * __Bug reports and feature requests__: If you would like to request a new #' feature or if you have noticed a bug that needs to be fixed please let us #' know at the **bayesplot** issue tracker at diff --git a/R/mcmc-intervals.R b/R/mcmc-intervals.R index 23f5dfc2b..760f6d36b 100644 --- a/R/mcmc-intervals.R +++ b/R/mcmc-intervals.R @@ -13,8 +13,7 @@ #' @param ... Currently unused. #' @param prob The probability mass to include in the inner interval (for #' `mcmc_intervals()`) or in the shaded region (for `mcmc_areas()`). The -#' default is `0.5` (50\% interval) and `1` for -#' `mcmc_areas_ridges`. +#' default is `0.5` (50\% interval) and `1` for `mcmc_areas_ridges()`. #' @param prob_outer The probability mass to include in the outer interval. The #' default is `0.9` for `mcmc_intervals()` (90\% interval) and #' `1` for `mcmc_areas()` and for `mcmc_areas_ridges()`. diff --git a/man-roxygen/args-transformations.R b/man-roxygen/args-transformations.R index 94262f944..bd10a6819 100644 --- a/man-roxygen/args-transformations.R +++ b/man-roxygen/args-transformations.R @@ -12,9 +12,10 @@ #' string naming a function). If a function is specified by its name as a #' string (e.g. `"log"`), then it can be used to construct a new #' parameter label for the appropriate parameter (e.g. `"log(sigma)"`). -#' If a function itself is specified (e.g. `log` or `function(x) -#' log(x)`) then `"t"` is used in the new parameter label to indicate -#' that the parameter is transformed (e.g. `"t(sigma)"`). +#' If a function itself is specified +#' (e.g. `log` or `function(x) log(x)`) +#' then `"t"` is used in the new parameter label to indicate that the +#' parameter is transformed (e.g. `"t(sigma)"`). #' #' Note: due to partial argument matching `transformations` can be #' abbreviated for convenience in interactive use (e.g., `transform`). diff --git a/man/MCMC-distributions.Rd b/man/MCMC-distributions.Rd index 07b08580e..6a7e2a591 100644 --- a/man/MCMC-distributions.Rd +++ b/man/MCMC-distributions.Rd @@ -67,8 +67,10 @@ parameter name and the content of each list element should be a function string naming a function). If a function is specified by its name as a string (e.g. \code{"log"}), then it can be used to construct a new parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). -If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate -that the parameter is transformed (e.g. \code{"t(sigma)"}). +If a function itself is specified +(e.g. \code{log} or \code{function(x) log(x)}) +then \code{"t"} is used in the new parameter label to indicate that the +parameter is transformed (e.g. \code{"t(sigma)"}). Note: due to partial argument matching \code{transformations} can be abbreviated for convenience in interactive use (e.g., \code{transform}).} diff --git a/man/MCMC-intervals.Rd b/man/MCMC-intervals.Rd index dae9479dd..a81ca0472 100644 --- a/man/MCMC-intervals.Rd +++ b/man/MCMC-intervals.Rd @@ -66,8 +66,10 @@ parameter name and the content of each list element should be a function string naming a function). If a function is specified by its name as a string (e.g. \code{"log"}), then it can be used to construct a new parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). -If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate -that the parameter is transformed (e.g. \code{"t(sigma)"}). +If a function itself is specified +(e.g. \code{log} or \code{function(x) log(x)}) +then \code{"t"} is used in the new parameter label to indicate that the +parameter is transformed (e.g. \code{"t(sigma)"}). Note: due to partial argument matching \code{transformations} can be abbreviated for convenience in interactive use (e.g., \code{transform}).} @@ -76,8 +78,7 @@ abbreviated for convenience in interactive use (e.g., \code{transform}).} \item{prob}{The probability mass to include in the inner interval (for \code{mcmc_intervals()}) or in the shaded region (for \code{mcmc_areas()}). The -default is \code{0.5} (50\% interval) and \code{1} for -\code{mcmc_areas_ridges}.} +default is \code{0.5} (50\% interval) and \code{1} for \code{mcmc_areas_ridges()}.} \item{prob_outer}{The probability mass to include in the outer interval. The default is \code{0.9} for \code{mcmc_intervals()} (90\% interval) and diff --git a/man/MCMC-parcoord.Rd b/man/MCMC-parcoord.Rd index c00125886..d7f7e0d9d 100644 --- a/man/MCMC-parcoord.Rd +++ b/man/MCMC-parcoord.Rd @@ -45,8 +45,10 @@ parameter name and the content of each list element should be a function string naming a function). If a function is specified by its name as a string (e.g. \code{"log"}), then it can be used to construct a new parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). -If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate -that the parameter is transformed (e.g. \code{"t(sigma)"}). +If a function itself is specified +(e.g. \code{log} or \code{function(x) log(x)}) +then \code{"t"} is used in the new parameter label to indicate that the +parameter is transformed (e.g. \code{"t(sigma)"}). Note: due to partial argument matching \code{transformations} can be abbreviated for convenience in interactive use (e.g., \code{transform}).} diff --git a/man/MCMC-scatterplots.Rd b/man/MCMC-scatterplots.Rd index 247891b56..96cfcd4d9 100644 --- a/man/MCMC-scatterplots.Rd +++ b/man/MCMC-scatterplots.Rd @@ -62,8 +62,10 @@ parameter name and the content of each list element should be a function string naming a function). If a function is specified by its name as a string (e.g. \code{"log"}), then it can be used to construct a new parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). -If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate -that the parameter is transformed (e.g. \code{"t(sigma)"}). +If a function itself is specified +(e.g. \code{log} or \code{function(x) log(x)}) +then \code{"t"} is used in the new parameter label to indicate that the +parameter is transformed (e.g. \code{"t(sigma)"}). Note: due to partial argument matching \code{transformations} can be abbreviated for convenience in interactive use (e.g., \code{transform}).} diff --git a/man/MCMC-traces.Rd b/man/MCMC-traces.Rd index ee298294a..2d2d1649e 100644 --- a/man/MCMC-traces.Rd +++ b/man/MCMC-traces.Rd @@ -47,8 +47,10 @@ parameter name and the content of each list element should be a function string naming a function). If a function is specified by its name as a string (e.g. \code{"log"}), then it can be used to construct a new parameter label for the appropriate parameter (e.g. \code{"log(sigma)"}). -If a function itself is specified (e.g. \code{log} or \code{function(x) log(x)}) then \code{"t"} is used in the new parameter label to indicate -that the parameter is transformed (e.g. \code{"t(sigma)"}). +If a function itself is specified +(e.g. \code{log} or \code{function(x) log(x)}) +then \code{"t"} is used in the new parameter label to indicate that the +parameter is transformed (e.g. \code{"t(sigma)"}). Note: due to partial argument matching \code{transformations} can be abbreviated for convenience in interactive use (e.g., \code{transform}).} diff --git a/man/bayesplot-colors.Rd b/man/bayesplot-colors.Rd index 0ccb0e3ef..e8cbc9b23 100644 --- a/man/bayesplot-colors.Rd +++ b/man/bayesplot-colors.Rd @@ -5,7 +5,7 @@ \alias{color_scheme_set} \alias{color_scheme_get} \alias{color_scheme_view} -\title{Set, get, or view color schemes} +\title{Set, get, or view \strong{bayesplot} color schemes} \usage{ color_scheme_set(scheme = "blue") diff --git a/man/bayesplot-package.Rd b/man/bayesplot-package.Rd index c0c0df256..50a1fcafb 100644 --- a/man/bayesplot-package.Rd +++ b/man/bayesplot-package.Rd @@ -4,7 +4,7 @@ \name{bayesplot-package} \alias{bayesplot-package} \alias{bayesplot} -\title{Plots for Bayesian Models} +\title{\strong{bayesplot}: Plotting for Bayesian Models} \description{ \if{html}{ \figure{stanlogo.png}{options: width="50px" alt="mc-stan.org"} @@ -17,10 +17,10 @@ not exclusively, via Markov chain Monte Carlo). The package is designed not only to provide convenient functionality for users, but also a common set of functions that can be easily used by developers working on a variety of packages for Bayesian modeling, particularly (but not necessarily) packages -powered by \link[rstan:rstan-package]{rstan}. Examples of packages that will soon -(or already are) using \strong{bayesplot} are \strong{rstan} itself, as well as the -\strong{rstan}-dependent \strong{rstanarm} and \strong{brms} packages for applied regression -modeling. +powered by \link[rstan:rstan-package]{rstan} (the \R interface to Stan). +Examples of packages that will soon (or already are) using \strong{bayesplot} are +\strong{rstan} itself, as well as the \strong{rstan}-dependent \strong{rstanarm} and +\strong{brms} packages for applied regression modeling. } \section{Plotting functionality}{ @@ -46,6 +46,8 @@ forecasting/out-of-sample prediction and other inference-related tasks. \section{Resources}{ \itemize{ +\item \strong{Online documentation and vignettes}: Visit the \strong{bayesplot} website at +\url{https://mc-stan.org/bayesplot} \item \strong{Bug reports and feature requests}: If you would like to request a new feature or if you have noticed a bug that needs to be fixed please let us know at the \strong{bayesplot} issue tracker at diff --git a/man/bayesplot_theme_get.Rd b/man/bayesplot_theme_get.Rd index 163dfab38..a107b2fea 100644 --- a/man/bayesplot_theme_get.Rd +++ b/man/bayesplot_theme_get.Rd @@ -5,7 +5,7 @@ \alias{bayesplot_theme_set} \alias{bayesplot_theme_update} \alias{bayesplot_theme_replace} -\title{Get, set, and modify the active bayesplot theme} +\title{Get, set, and modify the active \strong{bayesplot} theme} \usage{ bayesplot_theme_get() @@ -33,16 +33,16 @@ These functions are the \strong{bayesplot} equivalent to the active theme but only apply them to \code{bayesplots}. The current/active theme is automatically applied to every \code{bayesplot} you draw. -Use \code{bayesplot_theme_get()} to get the current \strong{bayesplot} theme, and -\code{bayesplot_theme_set()} to change it. \code{bayesplot_theme_update()} and +Use \code{bayesplot_theme_get()} to get the current \strong{bayesplot} theme and +\code{bayesplot_theme_set()} to set a new theme. \code{bayesplot_theme_update()} and \code{bayesplot_theme_replace()} are shorthands for changing individual elements. } \details{ -\code{bayesplot_theme_set()} and friends only apply to -\code{bayesplots}. However, \code{\link[ggplot2:theme_set]{ggplot2::theme_set()}} can also be used to -change the \strong{bayesplot} theme. Currently, setting a theme with -\code{ggplot2::theme_set()} (other than the \strong{ggplot2} default -\code{\link[ggplot2:theme_grey]{ggplot2::theme_grey()}}) will override the \strong{bayesplot} theme. +\code{bayesplot_theme_set()} and friends only apply to \code{bayesplots}. +However, \code{\link[ggplot2:theme_set]{ggplot2::theme_set()}} can also be used to change the +\strong{bayesplot} theme. Currently, setting a theme with \code{ggplot2::theme_set()} +(other than the \strong{ggplot2} default \code{\link[ggplot2:theme_grey]{ggplot2::theme_grey()}}) will override +the \strong{bayesplot} theme. } \examples{ library(ggplot2) diff --git a/man/theme_default.Rd b/man/theme_default.Rd index 8117a2f9c..90002232c 100644 --- a/man/theme_default.Rd +++ b/man/theme_default.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/bayesplot-ggplot-themes.R \name{theme_default} \alias{theme_default} -\title{Default bayesplot plotting theme} +\title{Default \strong{bayesplot} plotting theme} \usage{ theme_default(base_size = getOption("bayesplot.base_size", 12), base_family = getOption("bayesplot.base_family", "serif")) @@ -10,8 +10,8 @@ theme_default(base_size = getOption("bayesplot.base_size", 12), \arguments{ \item{base_size, base_family}{Base font size and family (passed to \code{\link[ggplot2:theme_bw]{ggplot2::theme_bw()}}). It is possible to set \code{"bayesplot.base_size"} and -\code{"bayesplot.base_family"} via \code{\link[=options]{options()}} to change the defaults, which are -\code{12} and \code{"serif"}, respectively.} +\code{"bayesplot.base_family"} via \code{\link[=options]{options()}} to change the defaults, w +hich are \code{12} and \code{"serif"}, respectively.} } \value{ A ggplot \link[ggplot2:theme]{theme} object. From 4a94f368e10361ce4463f35b94e98e205a82d76b Mon Sep 17 00:00:00 2001 From: TJ Mahr Date: Fri, 17 May 2019 08:50:59 -0500 Subject: [PATCH 8/8] fix typos --- R/bayesplot-ggplot-themes.R | 7 ++++--- R/mcmc-diagnostics-nuts.R | 8 +++++--- man/MCMC-nuts.Rd | 8 +++++--- man/theme_default.Rd | 7 ++++--- 4 files changed, 18 insertions(+), 12 deletions(-) diff --git a/R/bayesplot-ggplot-themes.R b/R/bayesplot-ggplot-themes.R index fb7c5bed3..a817b834d 100644 --- a/R/bayesplot-ggplot-themes.R +++ b/R/bayesplot-ggplot-themes.R @@ -2,13 +2,14 @@ #' #' The [theme_default()] function returns the default ggplot #' [theme][ggplot2::theme] used by the **bayesplot** plotting functions. See -#' [bayesplot_theme_set()] for details on setting and updating the plotting theme. +#' [bayesplot_theme_set()] for details on setting and updating the plotting +#' theme. #' #' @export #' @param base_size,base_family Base font size and family (passed to #' [ggplot2::theme_bw()]). It is possible to set `"bayesplot.base_size"` and -#' `"bayesplot.base_family"` via [options()] to change the defaults, w -#' hich are `12` and `"serif"`, respectively. +#' `"bayesplot.base_family"` via [options()] to change the defaults, which are +#' `12` and `"serif"`, respectively. #' @return A ggplot [theme][ggplot2::theme] object. #' #' @seealso [bayesplot_theme_set()] to change the ggplot theme. diff --git a/R/mcmc-diagnostics-nuts.R b/R/mcmc-diagnostics-nuts.R index 8023a2385..471c20a48 100644 --- a/R/mcmc-diagnostics-nuts.R +++ b/R/mcmc-diagnostics-nuts.R @@ -1,7 +1,8 @@ #' Diagnostic plots for the No-U-Turn-Sampler (NUTS) #' #' Diagnostic plots for the No-U-Turn-Sampler (NUTS), the default MCMC algorithm -#' used by [Stan](https://mc-stan.org). See the **Plot Descriptions** section, below. +#' used by [Stan](https://mc-stan.org). See the **Plot Descriptions** section, +#' below. #' #' @name MCMC-nuts #' @aliases NUTS @@ -55,7 +56,8 @@ #' \item{`mcmc_nuts_divergence()`}{ #' Two plots: #' * Violin plots of `lp__|divergent__=1` and `lp__|divergent__=0`. -#' * Violin plots of `accept_stat__|divergent__=1` and `accept_stat__|divergent__=0`. +#' * Violin plots of `accept_stat__|divergent__=1` and +#' `accept_stat__|divergent__=0`. #' } #' #' \item{`mcmc_nuts_stepsize()`}{ @@ -89,7 +91,7 @@ #' * [mcmc_trace()]: show divergences as tick marks below the #' trace plot. #' * [mcmc_parcoord()]: change the color/size/transparency of lines -#' correspondending to divergences. +#' corresponding to divergences. #' * [mcmc_scatter()]: change the color/size/shape of points #' corresponding to divergences. #' * [mcmc_pairs()]: change the color/size/shape of points diff --git a/man/MCMC-nuts.Rd b/man/MCMC-nuts.Rd index 62387f4ad..ed455c91f 100644 --- a/man/MCMC-nuts.Rd +++ b/man/MCMC-nuts.Rd @@ -57,7 +57,8 @@ except for \code{mcmc_nuts_energy()}, which returns a ggplot object. } \description{ Diagnostic plots for the No-U-Turn-Sampler (NUTS), the default MCMC algorithm -used by \href{https://mc-stan.org}{Stan}. See the \strong{Plot Descriptions} section, below. +used by \href{https://mc-stan.org}{Stan}. See the \strong{Plot Descriptions} section, +below. } \section{Quick Definitions}{ @@ -96,7 +97,8 @@ lines indicating the mean (solid line) and median (dashed line). Two plots: \itemize{ \item Violin plots of \code{lp__|divergent__=1} and \code{lp__|divergent__=0}. -\item Violin plots of \code{accept_stat__|divergent__=1} and \code{accept_stat__|divergent__=0}. +\item Violin plots of \code{accept_stat__|divergent__=1} and +\code{accept_stat__|divergent__=0}. } } @@ -175,7 +177,7 @@ extra arguments if the model was fit using NUTS: \item \code{\link[=mcmc_trace]{mcmc_trace()}}: show divergences as tick marks below the trace plot. \item \code{\link[=mcmc_parcoord]{mcmc_parcoord()}}: change the color/size/transparency of lines -correspondending to divergences. +corresponding to divergences. \item \code{\link[=mcmc_scatter]{mcmc_scatter()}}: change the color/size/shape of points corresponding to divergences. \item \code{\link[=mcmc_pairs]{mcmc_pairs()}}: change the color/size/shape of points diff --git a/man/theme_default.Rd b/man/theme_default.Rd index 90002232c..02a0210ff 100644 --- a/man/theme_default.Rd +++ b/man/theme_default.Rd @@ -10,8 +10,8 @@ theme_default(base_size = getOption("bayesplot.base_size", 12), \arguments{ \item{base_size, base_family}{Base font size and family (passed to \code{\link[ggplot2:theme_bw]{ggplot2::theme_bw()}}). It is possible to set \code{"bayesplot.base_size"} and -\code{"bayesplot.base_family"} via \code{\link[=options]{options()}} to change the defaults, w -hich are \code{12} and \code{"serif"}, respectively.} +\code{"bayesplot.base_family"} via \code{\link[=options]{options()}} to change the defaults, which are +\code{12} and \code{"serif"}, respectively.} } \value{ A ggplot \link[ggplot2:theme]{theme} object. @@ -19,7 +19,8 @@ A ggplot \link[ggplot2:theme]{theme} object. \description{ The \code{\link[=theme_default]{theme_default()}} function returns the default ggplot \link[ggplot2:theme]{theme} used by the \strong{bayesplot} plotting functions. See -\code{\link[=bayesplot_theme_set]{bayesplot_theme_set()}} for details on setting and updating the plotting theme. +\code{\link[=bayesplot_theme_set]{bayesplot_theme_set()}} for details on setting and updating the plotting +theme. } \examples{ class(theme_default())