Improve stat/geom docs

R/geom_calendar.R

@@ -105,15 +105,41 @@ GeomCalendar <- ggplot2::ggproto("GeomCalendar", ggplot2::GeomTile,
 #' Any `x` values that are infinite (i.e. `-Inf` or `Inf`) would normally be
 #' dropped by ggplot's layers. If any such values survive the stat processing,
 #' they will be drawn by `geom_calendar()` as triangles at the respective edges
-#' of the scale. This is intended to work with a scale configures to use
+#' of the scale. This is intended to work with a scale configured to use
 #' [oob_infinite()] for out of bounds handling.
+#' The triangles are drawn with their base (vertical edge) sitting on the scale
+#' limit, and their width equal to half of the median bin width.
+#'
+#' Note that the `label` aesthetic will be dropped if the data are not grouped
+#' in the expected way. In general this means that all rows contributing to a
+#' given bin must have the same value for the `label` aesthetic.
 #'
 #' @param label_params additional parameters for text labels if present
 #'   (see [ggplot2::geom_text()]).
 #' @param mapping,data,stat,position,linejoin,na.rm,show.legend,inherit.aes,...
 #'   see [ggplot2::geom_tile()].
 #'
 #' @export
+#' @examples
+#' library(ggplot2)
+#'
+#' set.seed(1)
+#' events <- rep(as.Date("2024-01-31") - 0:30, rpois(31, 6))
+#' values <- round(rgamma(length(events), 1, 0.01))
+#' df <- data.frame(date = events, value = values)
+#'
+#' ggplot(df) +
+#'     geom_calendar(
+#'         aes(date, value, label = after_stat(count)),
+#'         colour = "white",
+#'         stat = "week_2d",
+#'         week_start = "Monday",
+#'         bins.y = 10
+#'     ) +
+#'     scale_x_week(
+#'         limits = as.Date(c("2024-01-08", NA)),
+#'         expand = expansion(add = 3.5)
+#'     )
 geom_calendar <- function(
   mapping = NULL,
   data = NULL,

R/scale_week.R

@@ -1,5 +1,13 @@
 #' Date scale with breaks specified by week
 #'
+#' This produces a scale that is measured in days as with [ggplot2::scale_x_date],
+#' however it will snap breaks and limits to week boundaries so that things
+#' work as intended when binning by week.
+#'
+#' Any `limits` specified are converted to the nearest week boundary that
+#' includes the specified dates, i.e. the lower limit will be rounded down and
+#' the upper limit rounded up so that the limits are week boundaries.
+#'
 #' @param week_breaks,week_minor_breaks
 #'   frequency of breaks in number of weeks (e.g. `2` for fortnightly breaks).
 #' @param name,labels,date_labels,oob,limits,...

R/stat_week.R

@@ -10,6 +10,17 @@
 #'
 #' @return ggplot2 stat layer.
 #' @export
+#' @examples
+#' library(ggplot2)
+#'
+#' set.seed(1)
+#' events <- rep(as.Date("2024-01-31") - 0:30, rpois(31, 2))
+#' df <- data.frame(date = events)
+#'
+#' ggplot(df) + stat_week(aes(date), week_start = "Monday")
+#'
+#' # or equivalently:
+#' # ggplot(df) + geom_bar(aes(date), stat = "week", week_start = "Monday")
 stat_week <- function(
   mapping = NULL,
   data = NULL,

R/stat_week_2d.R

@@ -4,6 +4,10 @@
 #' the binning to be specified for the y aesthetic. This is mostly equivalent to
 #' [ggplot2::stat_bin_2d()] with the x aesthetic handling fixed to weeks.
 #'
+#' The computed aesthetics are similar to those of `stat_bin_2d()`, including
+#' `after_stat(count)`, `after_stat(density)`, and the bin positions and sizes:
+#' `after_stat(xmin)`, `after_stat(height)`, and so on.
+#'
 #' @param mapping,data,geom,position,na.rm,show.legend,inherit.aes,...
 #'   See [ggplot2::stat_bin_2d].
 #' @param bins.y,binwidth.y,breaks.y,center.y,boundary.y,closed.y
@@ -13,6 +17,15 @@
 #'
 #' @return ggplot2 stat layer.
 #' @export
+#' @examples
+#' library(ggplot2)
+#'
+#' set.seed(1)
+#' events <- rep(as.Date("2024-01-31") - 0:30, rpois(31, 6))
+#' values <- round(rgamma(length(events), 1, 0.01))
+#' df <- data.frame(date = events, value = values)
+#'
+#' ggplot(df) + stat_week_2d(aes(date, value), week_start = "Monday")
 stat_week_2d <- function(
   mapping = NULL,
   data = NULL,