subguide examples in docs and vignettes

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

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

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