minor doc and vignette cleaning

link to visualization paper on help pages of specific functions

Author: jgabry

R/mcmc-parcoord.R

@@ -1,7 +1,9 @@
 #' 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.
+#' 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.
 #'
 #' @name MCMC-parcoord
 #' @family MCMC
@@ -38,7 +40,8 @@
 #'    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.
+#'    \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

R/mcmc-scatterplots.R

@@ -44,6 +44,9 @@
 #'    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

R/ppc-distributions.R

@@ -37,7 +37,8 @@
 #'    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.
+#'    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
@@ -47,6 +48,7 @@
 #'   }
 #' }
 #'
+#' @template reference-vis-paper
 #' @templateVar bdaRef (Ch. 6)
 #' @template reference-bda
 #'
@@ -120,12 +122,12 @@ ppc_data <- function(y, yrep, group = NULL) {
 
 #' @rdname PPC-distributions
 #' @export
-ppc_hist <- function(y, yrep, ..., binwidth = NULL, breaks = NULL, 
+ppc_hist <- function(y, yrep, ..., binwidth = NULL, breaks = NULL,
                      freq = TRUE) {
   check_ignored_arguments(...)
   data <- ppc_data(y, yrep)
   aes_list <- set_hist_aes(freq, fill = ~ is_y_label, color = ~ is_y_label)
-    
+
   ggplot(data) +
     aes_list +
     geom_histogram(size = 0.25, binwidth = binwidth, breaks = breaks) +

R/ppc-loo.R

@@ -1,7 +1,8 @@
 #' LOO predictive checks
 #'
 #' Leave-One-Out (LOO) predictive checks. See the \strong{Plot Descriptions}
-#' section below for details.
+#' section, below, and \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et
+#' al. (2019)} for details.
 #'
 #' @name PPC-loo
 #' @family PPCs
@@ -23,7 +24,7 @@
 #'
 #' @section Plot Descriptions:
 #' \describe{
-#' \item{\code{ppc_loo_pit_qq,ppc_loo_pit_overlay}}{
+#' \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
@@ -34,7 +35,7 @@
 #'  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. (2018) for an example of interpreting the shape of
+#'  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

R/ppc-test-statistics.R

@@ -3,7 +3,8 @@
 #' 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.
+#' \strong{Plot Descriptions} and \strong{Details} sections, below, as
+#' well as \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)}.
 #'
 #' @name PPC-test-statistics
 #' @family PPCs
@@ -21,6 +22,7 @@
 #' @template details-binomial
 #' @template return-ggplot
 #'
+#' @template reference-vis-paper
 #' @templateVar bdaRef (Ch. 6)
 #' @template reference-bda
 #'
@@ -30,13 +32,15 @@
 #'    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.
+#'    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.
+#'    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

man-roxygen/reference-vis-paper.R

@@ -1,5 +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},
-#'   \href{https://arxiv.org/abs/1709.01449}{arXiv preprint})
+#'   (\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})