From a3be3a13df76f494002a0c154af473614ba5aff2 Mon Sep 17 00:00:00 2001 From: Matthew Kay Date: Sat, 13 Jan 2024 12:45:54 -0600 Subject: [PATCH] subguide examples in docs and vignettes --- R/subguide.R | 32 +++++++++++++++++++++++++++++++- man/subguide_axis.Rd | 31 +++++++++++++++++++++++++++++++ vignettes/dotsinterval.Rmd | 8 ++++++-- vignettes/slabinterval.Rmd | 7 +++++-- 4 files changed, 73 insertions(+), 5 deletions(-) diff --git a/R/subguide.R b/R/subguide.R index bc859b08..8b9e344b 100755 --- a/R/subguide.R +++ b/R/subguide.R @@ -41,6 +41,36 @@ #' @param ... Arguments passed to other functions, typically back to #' `subguide_axis()` itself. #' @family sub-guides +#' @examples +#' # example code +#' library(ggplot2) +#' library(distributional) +#' +#' df = data.frame(d = dist_normal(2:3, 2:3), g = c("a", "b")) +#' +#' # subguides allow you to label thickness axes +#' ggplot(df, aes(xdist = d, y = g)) + +#' stat_slabinterval(subguide = "inside") +#' +#' # they respect normalization and use of scale_thickness_shared() +#' ggplot(df, aes(xdist = d, y = g)) + +#' stat_slabinterval(subguide = "inside", normalize = "groups") +#' +#' # they can also be positioned outside the plot area, though +#' # this typically requires manually adjusting plot margins +#' ggplot(df, aes(xdist = d, y = g)) + +#' stat_slabinterval(subguide = subguide_outside(title = "density", position = "right")) + +#' theme(plot.margin = margin(5.5, 50, 5.5, 5.5)) +#' +#' # any of the subguide types will also work to indicate bin counts in +#' # geom_dots(); subguide_count() can be useful for dotplots as its default +#' # `breaks` value will label every whole number: +#' df = data.frame(d = dist_gamma(2:3, 2:3), g = c("a", "b")) +#' ggplot(df, aes(xdist = d, y = g)) + +#' stat_dots(subguide = subguide_count(label_side = "left", title = "count")) + +#' scale_y_discrete(expand = expansion(add = 0.1)) + +#' scale_x_continuous(expand = expansion(add = 0.5)) +#' #' @export subguide_axis = auto_partial(name = "subguide_axis", function( values, @@ -76,7 +106,7 @@ subguide_axis = auto_partial(name = "subguide_axis", function( title_width = grob_width(title_grob) # determine positions of title and axis grobs in the table layout - col_widths = unit.c(title_margin, title_width, title_margin, axis_width) + col_widths = unit.c(title_margin, title_width, if (!is.null(title)) title_margin else unit(0, "npc"), axis_width) if (axis_is_topleft) { title_i = 2 axis_i = 4 diff --git a/man/subguide_axis.Rd b/man/subguide_axis.Rd index 8f924588..a09fe349 100755 --- a/man/subguide_axis.Rd +++ b/man/subguide_axis.Rd @@ -106,6 +106,37 @@ region. \code{\link[=subguide_count]{subguide_count()}} is a shortcut for drawing labels where each whole number is labeled, useful for labeling counts in \code{\link[=geom_dots]{geom_dots()}}. +} +\examples{ +# example code +library(ggplot2) +library(distributional) + +df = data.frame(d = dist_normal(2:3, 2:3), g = c("a", "b")) + +# subguides allow you to label thickness axes +ggplot(df, aes(xdist = d, y = g)) + + stat_slabinterval(subguide = "inside") + +# they respect normalization and use of scale_thickness_shared() +ggplot(df, aes(xdist = d, y = g)) + + stat_slabinterval(subguide = "inside", normalize = "groups") + +# they can also be positioned outside the plot area, though +# this typically requires manually adjusting plot margins +ggplot(df, aes(xdist = d, y = g)) + + stat_slabinterval(subguide = subguide_outside(title = "density", position = "right")) + + theme(plot.margin = margin(5.5, 50, 5.5, 5.5)) + +# any of the subguide types will also work to indicate bin counts in +# geom_dots(); subguide_count() can be useful for dotplots as its default +# `breaks` value will label every whole number: +df = data.frame(d = dist_gamma(2:3, 2:3), g = c("a", "b")) +ggplot(df, aes(xdist = d, y = g)) + + stat_dots(subguide = subguide_count(label_side = "left", title = "count")) + + scale_y_discrete(expand = expansion(add = 0.1)) + + scale_x_continuous(expand = expansion(add = 0.5)) + } \seealso{ Other sub-guides: diff --git a/vignettes/dotsinterval.Rmd b/vignettes/dotsinterval.Rmd index 1d63990f..c8782cc5 100755 --- a/vignettes/dotsinterval.Rmd +++ b/vignettes/dotsinterval.Rmd @@ -703,13 +703,17 @@ dist_df = tibble( dist_df %>% ggplot(aes(y = dist_name, xdist = dist)) + - stat_dotsinterval() + + stat_dotsinterval(subguide = 'inside') + ggtitle( - "stat_dotsinterval()", + "stat_dotsinterval(subguide = 'inside')", "aes(y = dist_name, xdist = dist)" ) ``` +This example also shows the use of sub-guides to label dot counts. See the documentation +of `subguide_axis()` and its shortcuts (particularly `subguide_count()`) for more +examples. + Analytical distributions are shown by default using 100 quantiles, sometimes referred to as a *quantile dotplot*, which can help people make better decisions under uncertainty ([Kay 2016](https://doi.org/10.1145/2858036.2858558), [Fernandes 2018](https://doi.org/10.1145/3173574.3173718)). This can be changed using the `quantiles` argument. For example, we can plot the same diff --git a/vignettes/slabinterval.Rmd b/vignettes/slabinterval.Rmd index 507b282b..8ed4bfe7 100644 --- a/vignettes/slabinterval.Rmd +++ b/vignettes/slabinterval.Rmd @@ -499,15 +499,18 @@ parameter. The `.dist_obj` vector can be assigned to the `xdist` or `ydist` aest priors %>% parse_dist(prior) %>% ggplot(aes(y = paste(class, "~", format(.dist_obj)), xdist = .dist_obj)) + - stat_halfeye() + + stat_halfeye(subguide = subguide_inside(position = "right", title = "density")) + labs( title = "stat_halfeye()", - subtitle = "with brms::prior() and ggdist::parse_dist() to visualize priors", + subtitle = "with parse_dist() and brms::prior() to show priors", x = NULL, y = NULL ) ``` +This example also demonstrates the use of sub-guides to label the `thickness` axis. +For more on subguides, see the documentation for the `subguide_axis()` function. + The `format()` function in `format(.dist_obj)` generates a string containing a human-readable name for the distribution for labeling purposes. ### Sharing thickness scaling across geometries