Merge pull request #5132 from kevinxperese/kevinxperese-ggplot-docstring

Improve clarity of docstring for ggplot()

Author: teunbrand

R/plot.r

@@ -6,26 +6,35 @@
 #' subsequent layers unless specifically overridden.
 #'
 #' `ggplot()` is used to construct the initial plot object,
-#' and is almost always followed by `+` to add component to the
-#' plot. There are three common ways to invoke `ggplot()`:
+#' and is almost always followed by a plus sign (`+`) to add
+#' components to the plot.
 #'
-#' * `ggplot(df, aes(x, y, other aesthetics))`
-#' * `ggplot(df)`
+#' There are three common patterns used to invoke `ggplot()`:
+#'
+#' * `ggplot(data = df, mapping = aes(x, y, other aesthetics))`
+#' * `ggplot(data = df)`
 #' * `ggplot()`
 #'
-#' The first method is recommended if all layers use the same
+#' The first pattern is recommended if all layers use the same
 #' data and the same set of aesthetics, although this method
-#' can also be used to add a layer using data from another
-#' data frame. See the first example below. The second
-#' method specifies the default data frame to use for the plot,
-#' but no aesthetics are defined up front. This is useful when
-#' one data frame is used predominantly as layers are added,
-#' but the aesthetics may vary from one layer to another. The
-#' third method initializes a skeleton `ggplot` object which
-#' is fleshed out as layers are added. This method is useful when
+#' can also be used when adding a layer using data from another
+#' data frame. 
+#'
+#' The second pattern specifies the default data frame to use
+#' for the plot, but no aesthetics are defined up front. This
+#' is useful when one data frame is used predominantly for the
+#' plot, but the aesthetics vary from one layer to another. 
+#'
+#' The third pattern initializes a skeleton `ggplot` object, which
+#' is fleshed out as layers are added. This is useful when
 #' multiple data frames are used to produce different layers, as
 #' is often the case in complex graphics.
 #'
+#' The `data =` and `mapping =` specifications in the arguments are optional
+#' (and are often omitted in practice), so long as the data and the mapping
+#' values are passed into the function in the right order. In the examples
+#' below, however, they are left in place for clarity.
+#'
 #' @param data Default dataset to use for plot. If not already a data.frame,
 #'   will be converted to one by [fortify()]. If not specified,
 #'   must be supplied in each layer added to the plot.
@@ -36,42 +45,61 @@
 #'   evaluation.
 #' @export
 #' @examples
-#' # Generate some sample data, then compute mean and standard deviation
-#' # in each group
+#' # Create a data frame with some sample data, then create a data frame
+#' # containing the mean value for each group in the sample data.
 #' set.seed(1)
-#' df <- data.frame(
-#'   gp = factor(rep(letters[1:3], each = 10)),
-#'   y = rnorm(30)
+#' 
+#' sample_df <- data.frame(
+#'   group = factor(rep(letters[1:3], each = 10)),
+#'   value = rnorm(30)
 #' )
-#' ds <- do.call(rbind, lapply(split(df, df$gp), function(d) {
-#'   data.frame(mean = mean(d$y), sd = sd(d$y), gp = d$gp)
-#' }))
-#'
-#' # The summary data frame ds is used to plot larger red points on top
-#' # of the raw data. Note that we don't need to supply `data` or `mapping`
-#' # in each layer because the defaults from ggplot() are used.
-#' ggplot(df, aes(gp, y)) +
+#' 
+#' group_means_df <- setNames(
+#'   aggregate(value ~ group, sample_df, mean),
+#'   c("group", "group_mean")
+#' )
+#' 
+#' # The following three code blocks create the same graphic, each using one
+#' # of the three patterns specified above. In each graphic, the sample data
+#' # are plotted in the first layer and the group means data frame is used to
+#' # plot larger red points on top of the sample data in the second layer.
+#' 
+#' # Pattern 1
+#' # Both the `data` and `mapping` arguments are passed into the `ggplot()`
+#' # call. Those arguments are omitted in the first `geom_point()` layer
+#' # because they get passed along from the `ggplot()` call. Note that the
+#' # second `geom_point()` layer re-uses the `x = group` aesthetic through
+#' # that mechanism but overrides the y-position aesthetic.
+#' ggplot(data = sample_df, mapping = aes(x = group, y = value)) +
 #'   geom_point() +
-#'   geom_point(data = ds, aes(y = mean), colour = 'red', size = 3)
-#'
-#' # Same plot as above, declaring only the data frame in ggplot().
-#' # Note how the x and y aesthetics must now be declared in
-#' # each geom_point() layer.
-#' ggplot(df) +
-#'   geom_point(aes(gp, y)) +
-#'   geom_point(data = ds, aes(gp, mean), colour = 'red', size = 3)
-#'
-#' # Alternatively we can fully specify the plot in each layer. This
-#' # is not useful here, but can be more clear when working with complex
-#' # mult-dataset graphics
+#'   geom_point(
+#'     mapping = aes(y = group_mean), data = group_means_df,
+#'     colour = 'red', size = 3
+#'   )
+#' 
+#' # Pattern 2
+#' # Same plot as above, passing only the `data` argument into the `ggplot()`
+#' # call. The `mapping` arguments are now required in each `geom_point()`
+#' # layer because there is no `mapping` argument passed along from the
+#' # `ggplot()` call.
+#' ggplot(data = sample_df) +
+#'   geom_point(mapping = aes(x = group, y = value)) +
+#'   geom_point(
+#'     mapping = aes(x = group, y = group_mean), data = group_means_df,
+#'     colour = 'red', size = 3
+#'   )
+#' 
+#' # Pattern 3
+#' # Same plot as above, passing neither the `data` or `mapping` arguments
+#' # into the `ggplot()` call. Both those arguments are now required in
+#' # each `geom_point()` layer. This pattern can be particularly useful when
+#' # creating more complex graphics with many layers using data from multiple
+#' # data frames.
 #' ggplot() +
-#'   geom_point(data = df, aes(gp, y)) +
-#'   geom_point(data = ds, aes(gp, mean), colour = 'red', size = 3) +
-#'   geom_errorbar(
-#'     data = ds,
-#'     aes(gp, mean, ymin = mean - sd, ymax = mean + sd),
-#'     colour = 'red',
-#'     width = 0.4
+#'   geom_point(mapping = aes(x = group, y = value), data = sample_df) +
+#'   geom_point(
+#'     mapping = aes(x = group, y = group_mean), data = group_means_df,
+#'     colour = 'red', size = 3
 #'   )
 ggplot <- function(data = NULL, mapping = aes(), ...,
                    environment = parent.frame()) {