Skip to content

Commit cbe5df2

Browse files
committed
minor doc and vignette cleaning
link to visualization paper on help pages of specific functions
1 parent daf14d8 commit cbe5df2

17 files changed

+112
-53
lines changed

R/mcmc-parcoord.R

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,9 @@
11
#' Parallel coordinates plot of MCMC draws
22
#'
33
#' Parallel coordinates plot of MCMC draws (one dimension per parameter). See
4-
#' the \strong{Plot Descriptions} section, below, for details.
4+
#' the \strong{Plot Descriptions} section below for details, and see
5+
#' \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)}
6+
#' for more background and a real example.
57
#'
68
#' @name MCMC-parcoord
79
#' @family MCMC
@@ -38,7 +40,8 @@
3840
#' diagnostic information is provided via the \code{np} argument. In that
3941
#' case divergences are highlighted in the plot. The appearance of the
4042
#' divergences can be customized using the \code{np_style} argument and the
41-
#' \code{parcoord_style_np} helper function.
43+
#' \code{parcoord_style_np} helper function. This version of the plot is the
44+
#' same as the parallel coordinates plot described in Gabry et al. (2019).
4245
#'
4346
#' When the plotted model parameters are on very different scales the
4447
#' \code{transformations} argument can be useful. For example, to standardize

R/mcmc-scatterplots.R

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,9 @@
4444
#' overplotting. For models fit using \code{\link{NUTS}} the \code{np},
4545
#' and \code{np_style} arguments can be used to add additional information in
4646
#' the plot (in this case the approximate location of divergences).
47+
#' For an example of why the scatter plot with divergences is a useful
48+
#' diagnostic tool see \href{https://github.com/jgabry/bayes-vis-paper}{Gabry
49+
#' et al. (2019)}.
4750
#' }
4851
#' \item{\code{mcmc_hex}}{
4952
#' Hexagonal heatmap of 2-D bin counts. This plot is useful in cases where

R/ppc-distributions.R

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,7 +37,8 @@
3737
#' Kernel density or empirical CDF estimates of each dataset (row) in
3838
#' \code{yrep} are overlaid, with the distribution of \code{y} itself on top
3939
#' (and in a darker shade). When using \code{ppc_ecdf_overlay} with discrete
40-
#' data set the \code{discrete} argument to \code{TRUE} for better results.
40+
#' data, set the \code{discrete} argument to \code{TRUE} for better results.
41+
#' For an example of \code{ppc_dens_overlay} also see Gabry et al. (2019).
4142
#' }
4243
#' \item{\code{ppc_violin_grouped}}{
4344
#' The density estimate of \code{yrep} within each level of a grouping
@@ -47,6 +48,7 @@
4748
#' }
4849
#' }
4950
#'
51+
#' @template reference-vis-paper
5052
#' @templateVar bdaRef (Ch. 6)
5153
#' @template reference-bda
5254
#'
@@ -120,12 +122,12 @@ ppc_data <- function(y, yrep, group = NULL) {
120122

121123
#' @rdname PPC-distributions
122124
#' @export
123-
ppc_hist <- function(y, yrep, ..., binwidth = NULL, breaks = NULL,
125+
ppc_hist <- function(y, yrep, ..., binwidth = NULL, breaks = NULL,
124126
freq = TRUE) {
125127
check_ignored_arguments(...)
126128
data <- ppc_data(y, yrep)
127129
aes_list <- set_hist_aes(freq, fill = ~ is_y_label, color = ~ is_y_label)
128-
130+
129131
ggplot(data) +
130132
aes_list +
131133
geom_histogram(size = 0.25, binwidth = binwidth, breaks = breaks) +

R/ppc-loo.R

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
#' LOO predictive checks
22
#'
33
#' Leave-One-Out (LOO) predictive checks. See the \strong{Plot Descriptions}
4-
#' section below for details.
4+
#' section, below, and \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et
5+
#' al. (2019)} for details.
56
#'
67
#' @name PPC-loo
78
#' @family PPCs
@@ -23,7 +24,7 @@
2324
#'
2425
#' @section Plot Descriptions:
2526
#' \describe{
26-
#' \item{\code{ppc_loo_pit_qq,ppc_loo_pit_overlay}}{
27+
#' \item{\code{ppc_loo_pit_overlay, ppc_loo_pit_qq}}{
2728
#' The calibration of marginal predictions can be assessed using probability
2829
#' integral transformation (PIT) checks. LOO improves the check by avoiding the
2930
#' double use of data. See the section on marginal predictive checks in Gelman
@@ -34,7 +35,7 @@
3435
#' model is calibrated. The \code{ppc_loo_pit_overlay} function creates a plot
3536
#' comparing the density of the LOO PITs (thick line) to the density estimates
3637
#' of many simulated data sets from the standard uniform distribution (thin
37-
#' lines). See Gabry et al. (2018) for an example of interpreting the shape of
38+
#' lines). See Gabry et al. (2019) for an example of interpreting the shape of
3839
#' the miscalibration that can be observed in these plots.
3940
#'
4041
#' The \code{ppc_loo_pit_qq} function provides an alternative visualization of

R/ppc-test-statistics.R

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
#' The distribution of a test statistic \code{T(yrep)}, or a pair of test
44
#' statistics, over the simulated datasets in \code{yrep}, compared to the
55
#' observed value \code{T(y)} computed from the data \code{y}. See the
6-
#' \strong{Plot Descriptions} and \strong{Details} sections, below.
6+
#' \strong{Plot Descriptions} and \strong{Details} sections, below, as
7+
#' well as \href{https://github.com/jgabry/bayes-vis-paper}{Gabry et al. (2019)}.
78
#'
89
#' @name PPC-test-statistics
910
#' @family PPCs
@@ -21,6 +22,7 @@
2122
#' @template details-binomial
2223
#' @template return-ggplot
2324
#'
25+
#' @template reference-vis-paper
2426
#' @templateVar bdaRef (Ch. 6)
2527
#' @template reference-bda
2628
#'
@@ -30,13 +32,15 @@
3032
#' A histogram of the distribution of a test statistic computed by applying
3133
#' \code{stat} to each dataset (row) in \code{yrep}. The value of the
3234
#' statistic in the observed data, \code{stat(y)}, is overlaid as a vertical
33-
#' line.
35+
#' line. More details on \code{ppc_stat} can be found in Gabry et al.
36+
#' (2019).
3437
#' }
3538
#' \item{\code{ppc_stat_grouped,ppc_stat_freqpoly_grouped}}{
3639
#' The same as \code{ppc_stat}, but a separate plot is generated for each
3740
#' level of a grouping variable. In the case of
3841
#' \code{ppc_stat_freqpoly_grouped} the plots are frequency polygons rather
39-
#' than histograms.
42+
#' than histograms. More details on \code{ppc_stat_grouped} can be found in
43+
#' Gabry et al. (2019).
4044
#' }
4145
#' \item{\code{ppc_stat_2d}}{
4246
#' A scatterplot showing the joint distribution of two test statistics

man-roxygen/reference-vis-paper.R

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
#' @references Gabry, J. , Simpson, D. , Vehtari, A. , Betancourt, M. and
22
#' Gelman, A. (2019), Visualization in Bayesian workflow. \emph{J. R. Stat.
33
#' Soc. A}, 182: 389-402. doi:10.1111/rssa.12378,
4-
#' (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal},
5-
#' \href{https://arxiv.org/abs/1709.01449}{arXiv preprint})
4+
#' (\href{https://rss.onlinelibrary.wiley.com/doi/full/10.1111/rssa.12378}{journal version},
5+
#' \href{https://arxiv.org/abs/1709.01449}{arXiv preprint},
6+
#' \href{https://github.com/jgabry/bayes-vis-paper}{code on GitHub})

man/MCMC-overview.Rd

Lines changed: 3 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/MCMC-parcoord.Rd

Lines changed: 8 additions & 4 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/MCMC-scatterplots.Rd

Lines changed: 6 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

man/PPC-distributions.Rd

Lines changed: 9 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)