diff --git a/NEWS.md b/NEWS.md index 25c323e3..50e0a0b8 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,5 +1,8 @@ # bayesplot (development version) +* Improved documentation for `binwidth`, `bins`, and `breaks` arguments to clarify they are passed to `ggplot2::geom_area()` and `ggdist::stat_dots()` in addition to `ggplot2::geom_histogram()` +* Improved documentation for `freq` argument to clarify it applies to frequency polygons in addition to histograms +* Fixed test in `test-ppc-distributions.R` that incorrectly used `ppc_dens()` instead of `ppd_dens()` when testing PPD functions * New functions `mcmc_dots` and `mcmc_dots_by_chain` for dot plots of MCMC draws by @behramulukir (#402) * Default to `quantiles=100` for all dot plots by @behramulukir (#402) diff --git a/man-roxygen/args-hist-freq.R b/man-roxygen/args-hist-freq.R index 9d232bd6..d1b182ed 100644 --- a/man-roxygen/args-hist-freq.R +++ b/man-roxygen/args-hist-freq.R @@ -1,5 +1,5 @@ -#' @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 [yaxis_text()] convenience +#' @param freq For histograms and frequency polygons, `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 [yaxis_text()] convenience #' function.) diff --git a/man-roxygen/args-hist.R b/man-roxygen/args-hist.R index 657d20ec..24d77ea3 100644 --- a/man-roxygen/args-hist.R +++ b/man-roxygen/args-hist.R @@ -1,7 +1,7 @@ -#' @param binwidth Passed to [ggplot2::geom_histogram()] to override -#' the default binwidth. -#' @param bins Passed to [ggplot2::geom_histogram()] to override -#' the default binwidth. -#' @param breaks Passed to [ggplot2::geom_histogram()] as an -#' alternative to `binwidth`. +#' @param binwidth Passed to [ggplot2::geom_histogram()], [ggplot2::geom_area()], +#' and [ggdist::stat_dots()] to override the default binwidth. +#' @param bins Passed to [ggplot2::geom_histogram()] and [ggplot2::geom_area()] +#' to override the default binning. +#' @param breaks Passed to [ggplot2::geom_histogram()] as an alternative to +#' `binwidth`. #' diff --git a/man/MCMC-diagnostics.Rd b/man/MCMC-diagnostics.Rd index ae47edac..b396717e 100644 --- a/man/MCMC-diagnostics.Rd +++ b/man/MCMC-diagnostics.Rd @@ -52,14 +52,14 @@ mcmc_acf_bar( default size (for \code{mcmc_rhat()}, \code{mcmc_neff()}) or \code{\link[ggplot2:geom_path]{ggplot2::geom_line()}}'s default line width (for \code{mcmc_acf()}).} -\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} -\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} and \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}} +to override the default binning.} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\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]{neff_ratio()}}.} diff --git a/man/MCMC-distributions.Rd b/man/MCMC-distributions.Rd index cce86f9c..ec69c799 100644 --- a/man/MCMC-distributions.Rd +++ b/man/MCMC-distributions.Rd @@ -188,19 +188,19 @@ to control faceting. Note: if \code{scales} is not included in \code{facet_args} then \strong{bayesplot} may use \code{scales="free"} as the default (depending on the plot) instead of the \strong{ggplot2} default of \code{scales="fixed"}.} -\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} -\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} and \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}} +to override the default binning.} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\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]{yaxis_text()}} convenience +\item{freq}{For histograms and frequency polygons, \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]{yaxis_text()}} convenience function.)} \item{alpha}{Passed to the geom to control the transparency.} diff --git a/man/MCMC-nuts.Rd b/man/MCMC-nuts.Rd index 13bdc690..4a2d7273 100644 --- a/man/MCMC-nuts.Rd +++ b/man/MCMC-nuts.Rd @@ -56,14 +56,14 @@ selected chain. The \code{chain} argument is not used by \code{mcmc_nuts_energy( \item{...}{Currently ignored.} -\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} -\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} and \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}} +to override the default binning.} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an alternative to +\code{binwidth}.} \item{alpha}{For \code{mcmc_nuts_energy()} only, the transparency (alpha) level in \verb{[0,1]} used for the overlaid histogram.} diff --git a/man/MCMC-recover.Rd b/man/MCMC-recover.Rd index de179434..1a46095c 100644 --- a/man/MCMC-recover.Rd +++ b/man/MCMC-recover.Rd @@ -87,14 +87,14 @@ default), \code{"mean"}, or \code{"none"}.} \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]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} -\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} and \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}} +to override the default binning.} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\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 \strong{ggplot2} package. diff --git a/man/PPC-distributions.Rd b/man/PPC-distributions.Rd index c31242e8..ce0f264a 100644 --- a/man/PPC-distributions.Rd +++ b/man/PPC-distributions.Rd @@ -181,19 +181,19 @@ passed to \code{\link[ggplot2:stat_ecdf]{ggplot2::stat_ecdf()}}. If \code{discre \item{pad}{A logical scalar passed to \code{\link[ggplot2:stat_ecdf]{ggplot2::stat_ecdf()}}.} -\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} -\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} and \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}} +to override the default binning.} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\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]{yaxis_text()}} convenience +\item{freq}{For histograms and frequency polygons, \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]{yaxis_text()}} convenience function.)} \item{notch}{For the box plot, a logical scalar passed to diff --git a/man/PPC-errors.Rd b/man/PPC-errors.Rd index fafd0212..8e3d28c7 100644 --- a/man/PPC-errors.Rd +++ b/man/PPC-errors.Rd @@ -100,18 +100,18 @@ to control faceting. Note: if \code{scales} is not included in \code{facet_args} then \strong{bayesplot} may use \code{scales="free"} as the default (depending on the plot) instead of the \strong{ggplot2} default of \code{scales="fixed"}.} -\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} \item{bins}{For \code{ppc_error_binned()}, the number of bins to use (approximately).} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\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]{yaxis_text()}} convenience +\item{freq}{For histograms and frequency polygons, \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]{yaxis_text()}} convenience function.)} \item{group}{A grouping variable of the same length as \code{y}. diff --git a/man/PPC-test-statistics.Rd b/man/PPC-test-statistics.Rd index 364ede99..3f0bf3e0 100644 --- a/man/PPC-test-statistics.Rd +++ b/man/PPC-test-statistics.Rd @@ -87,19 +87,19 @@ then generic naming is used in the legend.} \item{discrete}{For \code{ppc_stat()} and \code{ppc_stat_grouped()}, if \code{TRUE} then a bar chart is used instead of a histogram.} -\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} -\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} and \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}} +to override the default binning.} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\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]{yaxis_text()}} convenience +\item{freq}{For histograms and frequency polygons, \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]{yaxis_text()}} convenience function.)} \item{group}{A grouping variable of the same length as \code{y}. diff --git a/man/PPD-distributions.Rd b/man/PPD-distributions.Rd index 45bbbe74..a53c62e4 100644 --- a/man/PPD-distributions.Rd +++ b/man/PPD-distributions.Rd @@ -96,19 +96,19 @@ passed to \code{\link[ggplot2:stat_ecdf]{ggplot2::stat_ecdf()}}. If \code{discre \item{pad}{A logical scalar passed to \code{\link[ggplot2:stat_ecdf]{ggplot2::stat_ecdf()}}.} -\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} -\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} and \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}} +to override the default binning.} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\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]{yaxis_text()}} convenience +\item{freq}{For histograms and frequency polygons, \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]{yaxis_text()}} convenience function.)} \item{quantiles}{For dot plots, an optional integer passed to diff --git a/man/PPD-test-statistics.Rd b/man/PPD-test-statistics.Rd index 168f2bb3..7c8b41f3 100644 --- a/man/PPD-test-statistics.Rd +++ b/man/PPD-test-statistics.Rd @@ -78,19 +78,19 @@ then generic naming is used in the legend.} \item{discrete}{For \code{ppc_stat()} and \code{ppc_stat_grouped()}, if \code{TRUE} then a bar chart is used instead of a histogram.} -\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{binwidth}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}}, \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}}, +and \code{\link[ggdist:stat_dots]{ggdist::stat_dots()}} to override the default binwidth.} -\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} to override -the default binwidth.} +\item{bins}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} and \code{\link[ggplot2:geom_ribbon]{ggplot2::geom_area()}} +to override the default binning.} -\item{breaks}{Passed to \code{\link[ggplot2:geom_histogram]{ggplot2::geom_histogram()}} as an -alternative to \code{binwidth}.} +\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]{yaxis_text()}} convenience +\item{freq}{For histograms and frequency polygons, \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]{yaxis_text()}} convenience function.)} \item{group}{A grouping variable of the same length as \code{y}. diff --git a/tests/testthat/test-ppc-distributions.R b/tests/testthat/test-ppc-distributions.R index 9062515f..93b52e0a 100644 --- a/tests/testthat/test-ppc-distributions.R +++ b/tests/testthat/test-ppc-distributions.R @@ -76,8 +76,8 @@ test_that("ppc_dens,pp_hist,ppc_freqpoly,ppc_boxplot return ggplot objects", { expect_gg(ppd_hist(yrep[1:8, ], binwidth = 0.1)) expect_gg(ppd_hist(yrep2, binwidth = 0.1)) - expect_gg(ppc_dens(y, yrep[1:8, ])) - expect_gg(ppc_dens(y2, yrep2)) + expect_gg(ppd_dens(yrep[1:8, ])) + expect_gg(ppd_dens(yrep2)) expect_gg(ppd_freqpoly(yrep[1:8, ], binwidth = 2, size = 2, alpha = 0.1)) expect_gg(ppd_freqpoly(yrep2, binwidth = 0.1))