Expand on docs/example for cases with non-equal-width bins in stat_bin()

R/geom-histogram.R

@@ -63,6 +63,18 @@
 #' ggplot(diamonds, aes(price, after_stat(density), colour = cut)) +
 #'   geom_freqpoly(binwidth = 500)
 #'
+#'
+#' # When using the non-equal-width bins, we need to set the area of the bars to
+#' # represent the counts (not the height).
+#' # Here we're using 10 equi-probable bins:
+#' price_bins <- quantile(diamonds$price, probs = seq(0, 1, length = 11))
+#'
+#' ggplot(diamonds, aes(price)) +
+#'   geom_histogram(breaks = price_bins, color = "black") # wrong (height = count)
+#'
+#' ggplot(diamonds, aes(price, after_stat(count / width))) +
+#'   geom_histogram(breaks = price_bins, color = "black") # area = count
+#'
 #' if (require("ggplot2movies")) {
 #' # Often we don't want the height of the bar to represent the
 #' # count of observations, but the sum of some other variable.

R/stat-bin.R

@@ -31,7 +31,7 @@
 #'   density  = "density of points in bin, scaled to integrate to 1.",
 #'   ncount   = "count, scaled to a maximum of 1.",
 #'   ndensity = "density, scaled to a maximum of 1.",
-#'   width    = "widths of bins."
+#'   width    = "widths of bins. Use with `after_stat(count / width)` to obtain bars with _areas_ representing counts (e.g., with non-equal-width bins). See example."
 #' )
 #'
 #' @section Dropped variables: