standalone docs for ?Stat

Author: teunbrand

R/stat-.R

@@ -1,93 +1,201 @@
-#' @section Stats:
+#' Stats
 #'
+#' @description
 #' All `stat_*()` functions (like `stat_bin()`) return a layer that
 #' contains a `Stat*` object (like `StatBin`). The `Stat*`
 #' object is responsible for rendering the data in the plot.
 #'
+#' @details
 #' Each of the `Stat*` objects is a [ggproto()] object, descended
 #' from the top-level `Stat`, and each implements various methods and
-#' fields. To create a new type of Stat object, you typically will want to
+#' fields.
+#'
+#' To create a new type of Stat object, you typically will want to
 #' override one or more of the following:
 #'
-#'   - One of :
-#'     `compute_layer(self, data, scales, ...)`,
-#'     `compute_panel(self, data, scales, ...)`, or
-#'     `compute_group(self, data, scales, ...)`.
+#' * The `required_aes` and `default_aes` fields.
+#' * One of the `compute_layer()`, `compute_panel()` or `compute_group()`
+#'   functions. Typically it best to implement `compute_group()` and use the
+#'   higher-up methods when there are substantial performance improvements to
+#'   be gained.
+#' * The `finish_layer()` method
 #'
-#'     `compute_layer()` is called once per layer, `compute_panel()`
-#'     is called once per panel, and `compute_group()` is called once per
-#'     group. All must return a data frame.
+#' @section Conventions:
 #'
-#'     It's usually best to start by overriding `compute_group`: if
-#'     you find substantial performance optimisations, override higher up.
-#'     You'll need to read the source code of the default methods to see
-#'     what else you should be doing.
+#' The object name that a new class is assigned to is typically the same as the
+#' class name. Stat class names are in UpperCamelCase and start with the `Stat*`
+#' prefix, like `StatNew`.
 #'
-#'     `data` is a data frame containing the variables named according
-#'     to the aesthetics that they're mapped to. `scales` is a list
-#'     containing the `x` and `y` scales. There functions are called
-#'     before the facets are trained, so they are global scales, not local
-#'     to the individual panels.`...` contains the parameters returned by
-#'     `setup_params()`.
-#'   - `finish_layer(data, params)`: called once for each layer. Used
-#'     to modify the data after scales has been applied, but before the data is
-#'     handed of to the geom for rendering. The default is to not modify the
-#'     data. Use this hook if the stat needs access to the actual aesthetic
-#'     values rather than the values that are mapped to the aesthetic.
-#'   - `setup_params(data, params)`: called once for each layer.
-#'     Used to setup defaults that need to complete dataset, and to inform
-#'     the user of important choices. Should return list of parameters.
-#'   - `setup_data(data, params)`: called once for each layer,
-#'     after `setup_params()`. Should return modified `data`.
-#'     Default methods removes all rows containing a missing value in
-#'     required aesthetics (with a warning if `!na.rm`).
-#'   - `required_aes`: A character vector of aesthetics needed to
-#'     render the geom.
-#'   - `default_aes`: A list (generated by [aes()] of
-#'     default values for aesthetics.
-#'   - `dropped_aes` is a vecor of aesthetic names that are safe to drop after
-#'     statistical transformation. A classic example is the `weight` aesthetic
-#'     that is consumed during computation of the stat.
+#' A constructor function is usually paired wih a Stat class. The constructor
+#' wraps a call t o `layer()`, where e.g. `layer(stat = StatNew)`. The
+#' constructor function name is formatted by taking the Stat class name and
+#' formatting it with snake_case, so that `StatNew` becomes `stat_new()`.
 #'
-#' See also the `r link_book("new stats section", "extensions#sec-new-stats")`
-#' @rdname ggplot2-ggproto
-#' @format NULL
-#' @usage NULL
 #' @export
-Stat <- ggproto("Stat",
-  # Should the values produced by the statistic also be transformed
-  # in the second pass when recently added statistics are trained to
-  # the scales
-  retransform = TRUE,
+#' @format NULL
+#' @usage
+#' # Creating a new subclass
+#' StatNew <- ggproto("StatNew", Stat, ...)
+#'
+#' # Usage in the `layer()` function
+#' layer(stat = StatNew)
+#' @seealso The `r link_book("new stats section", "extensions#sec-new-stats")`.
+#' @seealso Run `vignette("extending-ggplot2")`, in particular the "Creating a
+#' new stat" section.
+#' @examples
+#' # Extending the class
+#' StatKmeans <- ggproto(
+#'   "StatKmeans", Stat,
+#'   # Fields
+#'   required_aes = c("x", "y"),
+#'   # You can relate computed variables to aesthetics using `after_stat()`
+#'   # in defaults
+#'   default_aes = aes(colour = after_stat(cluster)),
+#'   # Methods
+#'   compute_panel = function(data, scales, k = 2L) {
+#'     km <- kmeans(cbind(scale(data$x), scale(data$y)), centers = k)
+#'     data$cluster <- factor(km$cluster)
+#'     data
+#'   }
+#' )
+#'
+#' # Building a constructor
+#' stat_kmeans <- function(mapping = NULL, data = NULL, geom = "point",
+#'                         position = "identity", ..., k = 2L, na.rm = FALSE,
+#'                         show.legend = NA, inherit.aes = TRUE) {
+#'   layer(
+#'     mapping = mapping, data = data,
+#'     geom = geom, stat = StatKmeans, position = position,
+#'     show.legend = show.legend, inherit.aes = inherit.aes,
+#'     params = list(na.rm = na.rm, k = k, ...)
+#'   )
+#' }
+#'
+#' # Use new stat in plot
+#' ggplot(mpg, aes(displ, hwy)) +
+#'   stat_kmeans(k = 3)
+Stat <- ggproto(
+  "Stat",
 
-  default_aes = aes(),
+  # Fields ------------------------------------------------------------------
 
+  #' @field required_aes A character vector naming aesthetics that are necessary
+  #' to compute the stat.
   required_aes = character(),
 
+  #' @field non_missing_aes A character vector naming aesthetics that will cause
+  #' removal if they have missing values.
   non_missing_aes = character(),
 
-  # Any aesthetics that are dropped from the data frame during the
-  # statistical transformation should be listed here to suppress a
-  # warning about dropped aesthetics
+  #' @field optional_aes A character vector naming aesthetics that will be
+  #' accepted by `layer()`, but are not required or dscribed in the `default_aes`
+  #' field.
+  optional_aes = character(),
+
+  #' @field default_aes A [mapping][aes()] of default values for aesthetics.
+  #' Aesthetics can be set to `NULL` to be included as optional aesthetic.
+  default_aes = aes(),
+
+  #' @field dropped_aes A character vector naming aesthetics that can be dropped
+  #' from the data without warning. Typically used for aesthetics that are
+  #' 'consumed' during computation like `"weight"`.
   dropped_aes = character(),
 
-  optional_aes = character(),
+  #' @field extra_params A character vector of parameter names in addition to
+  #' those imputed from the `compute_panel()` or `compute_groups()` methods.
+  #' This field can be set to include parameters for `setup_data()` methods.
+  #' By default, this only contains `"na.rm"`.
+  extra_params = "na.rm",
+
+  #' @field retransform A scalar boolean: should the values produced by the
+  #' statistic also be transformed in the second pass when recently added
+  #' statistics are trained to the scales
+  retransform = TRUE,
 
+  # Methods -----------------------------------------------------------------
+
+  ## compute_statistic ------------------------------------------------------
+
+  #' @field setup_params
+  #' **Description**
+  #'
+  #' A function method for modifying or checking the parameters based on the
+  #' data. The default method returns the parameters unaltered.
+  #'
+  #' **Usage**
+  #' ```r
+  #' Stat$setup_params(data, params)
+  #' ```
+  #' **Arguments**
+  #' \describe{
+  #'   \item{`data`}{A data frame with the layer's data.}
+  #'   \item{`params`}{A list of current parameters}
+  #' }
+  #'
+  #' **Value**
+  #'
+  #' A list of parameters
   setup_params = function(data, params) {
     params
   },
 
+  #' @field setup_data
+  #' **Description**
+  #'
+  #' A function method for modifying or checking the data. The default method
+  #' returns data unaltered.
+  #'
+  #' **Usage**
+  #' ```r
+  #' Stat$setup_data(data, params)
+  #' ```
+  #' **Arguments**
+  #' \describe{
+  #'   \item{`data`}{A data frame with the layer's data.}
+  #'   \item{`params`}{A list of parameters coming from the `setup_params()`
+  #'   method}
+  #' }
+  #'
+  #' **Value**
+  #'
+  #' A data frame with layer data
   setup_data = function(data, params) {
     data
   },
 
+  #' @field compute_layer
+  #' **Description**
+  #'
+  #' A function method for orchestrating the computation of the statistic. The
+  #' default method splits the data and passes on computation tasks to the
+  #' panel-level `compute_panel()` method. In addition, the default method
+  #' handles missing values by removing rows that have missing values for the
+  #' aesthetics listed in the `required_aes` and `non_missing_aes` fields. It is
+  #' not recommended to use this method as an extension point.
+  #'
+  #' **Usage**
+  #' ```r
+  #' Stat$compute_layer(data, params, layout)
+  #' ```
+  #'
+  #' **Arguments**
+  #' \describe{
+  #'   \item{`data`}{A data frame with the layer's data.}
+  #'   \item{`params`}{A list of parameters}
+  #'   \item{`layout`}{A pre-trained `<Layout>` ggproto object.}
+  #' }
+  #'
+  #' **Value**
+  #'
+  #' A data frame with computed data
   compute_layer = function(self, data, params, layout) {
     check_required_aesthetics(
       self$required_aes,
       c(names(data), names(params)),
       snake_class(self)
     )
 
+    # TODO: for symmetry with Geom, should Stat have separate `handle_na()` method?
     # Make sure required_aes consists of the used set of aesthetics in case of
     # "|" notation in self$required_aes
     required_aes <- intersect(
@@ -117,6 +225,34 @@ Stat <- ggproto("Stat",
     })
   },
 
+  #' @field compute_panel,compute_group
+  #' **Description**
+  #'
+  #' A function method orchestrating the computation of statistics for a single
+  #' panel or group. The default `compute_panel()` method splits the data into
+  #' groups, and passes on computation tasks to the `compute_group()` method.
+  #' In addition, `compute_panel()` is tasked with preserving aesthetics that
+  #' are constant within a group and preserving these if the computation loses
+  #' them. The default `compute_group()` is not implemented.
+  #'
+  #' **Usage**
+  #' ```r
+  #' Stat$compute_panel(data, scales, ...)
+  #' Stat$compute_group(data, scales, ...)
+  #' ```
+  #' **Arguments**
+  #' \describe{
+  #'   \item{`data`}{A data frame with the layer's data.}
+  #'   \item{`scales`}{A list containing pre-trained `x` and `y` scales.
+  #'   Note that these are global scales trained on all data, not panel-specific
+  #'   scales.}
+  #'   \item{`...`}{Reserved for extensions. By default, this passes parameters
+  #'   to the `compute_group()` method.}
+  #' }
+  #'
+  #' **Value**
+  #'
+  #' A data frame with layer data
   compute_panel = function(self, data, scales, ...) {
     if (empty(data)) return(data_frame0())
 
@@ -182,17 +318,54 @@ Stat <- ggproto("Stat",
     data_new[, !names(data_new) %in% non_constant_columns, drop = FALSE]
   },
 
-  compute_group = function(self, data, scales) {
-    cli::cli_abort("Not implemented.")
-  },
-
+  compute_group = not_implemented("compute_group"),
+
+  # finish_statistics -------------------------------------------------------
+
+  #' @field finish_layer
+  #' **Description**
+  #'
+  #' A function method acting as a hook to modify data after scales have been
+  #' applied, but before geoms have to render. The default is to pass the data
+  #' unaltered. This can be used as an extension point when actual aesthetic
+  #' values rather than values mapped to the aesthetic are needed.
+  #'
+  #' **Usage**
+  #' ```r
+  #' Stat$finish_layer(data, params)
+  #' ```
+  #' **Arguments**
+  #' \describe{
+  #'   \item{`data`}{A data frame with layer data}
+  #'   \item{`params`}{A list of parameters}
+  #' }
+  #'
+  #' **Value**
+  #'
+  #' A data frame with layer data
   finish_layer = function(self, data, params) {
     data
   },
 
-
-  # See discussion at Geom$parameters()
-  extra_params = "na.rm",
+  ## Utilities ---------------------------------------------------------------
+
+  #' @field parameters
+  #' **Description**
+  #'
+  #' A function method for listing out all acceptable parameters for this stat.
+  #'
+  #' **Usage**
+  #' ```r
+  #' Stat$parameters(extra)
+  #' ```
+  #' **Arguments**
+  #' \describe{
+  #'   \item{`extra`}{A boolean: whether to include the `extra_params` field.}
+  #' }
+  #'
+  #' **Value**
+  #'
+  #' A character vector of parameter names.
   parameters = function(self, extra = FALSE) {
     # Look first in compute_panel. If it contains ... then look in compute_group
     panel_args <- names(ggproto_formals(self$compute_panel))
@@ -208,6 +381,18 @@ Stat <- ggproto("Stat",
     args
   },
 
+  #' @field aesthetics
+  #' **Description**
+  #'
+  #' A function method for listing out all acceptable aesthetics for this stat.
+  #'
+  #' **Usage**
+  #' ```r
+  #' Stat$aesthetics()
+  #' ```
+  #' **Value**
+  #'
+  #' A character vector of aesthetic names.
   aesthetics = function(self) {
     if (is.null(self$required_aes)) {
       required_aes <- NULL