Add aes_q

Author: hadley

NAMESPACE

@@ -179,6 +179,7 @@ export("%+replace%")
 export(aes)
 export(aes_all)
 export(aes_auto)
+export(aes_q)
 export(aes_string)
 export(annotate)
 export(annotation_custom)

NEWS

@@ -1,6 +1,10 @@
 ggplot2 0.9.3.1.99
 ----------------------------------------------------------------
 
+* New `aes_q()` function to generate aesthetic specifications from
+  quoted calls/names. `aes_string()` uses names `x` and `y` for first
+  two unnamed arguments.
+
 * Marginal improvements to `theme_bw` and `theme_classic` (@jiho, #934)
 
 * `stat_ellipse()` adds data ellipses. It supports bivariate normal and t distributions,

R/aes.r

@@ -29,11 +29,9 @@
 #' performs partial name matching, converts color to colour, and old style R
 #' names to ggplot names (eg. pch to shape, cex to size)
 #'
-#' @param x x value
-#' @param y y value
-#' @param ... List of name value pairs giving aesthetics to map.
-#' @seealso \code{\link{aes_string}} for passing quoted variable names.
-#"    Useful when creating plots within user defined functions. Also,
+#' @param x,y,... List of name value pairs giving aesthetics to map.
+#' @family aesthetic generators
+#' @seealso See
 #'    \code{\link{aes_colour_fill_alpha}}, \code{\link{aes_group_order}},
 #'    \code{\link{aes_linetype_size_shape}} and \code{\link{aes_position}}
 #'    for more specific examples with different aesthetics.
@@ -81,30 +79,42 @@ is_position_aes <- function(vars) {
   aes_to_scale(vars) %in% c("x", "y")
 }
 
-#' Generate aesthetic mappings from a string
+#' Generate aesthetic mappings from a string/quoted objects
 #'
 #' Aesthetic mappings describe how variables in the data are mapped to visual
-#' properties (aesthetics) of geoms.  Compared to aes this function operates
-#' on strings rather than expressions.
+#' properties (aesthetics) of geoms. \code{\link{aes}} uses non-standard
+#' evaluation to capture the variable names. These two variants use
+#' regular evaluation, which is easier to use inside functions.
 #'
-#' \code{aes_string} is particularly useful when writing functions that create
-#' plots because you can use strings to define the aesthetic mappings, rather
-#' than having to mess around with expressions.
+#' \code{aes_string} and \code{aes_q} are particularly useful when writing
+#' functions that create plots because you can use strings or quoted
+#' names/calls to define the aesthetic mappings, rather than having to use
+#' \code{\link{substitute}} to generate a call to \code{aes()}.
 #'
-#' @param ... List of name value pairs
+#' @param x,y,... List of name value pairs
+#' @family aesthetic generators
 #' @seealso \code{\link{aes}}
 #' @export
 #' @examples
-#' aes_string(x = "mpg", y = "wt")
-#' aes(x = mpg, y = wt)
-aes_string <- function(...) {
-  mapping <- list(...)
-  mapping[sapply(mapping, is.null)] <- "NULL"
+#' # Threee ways of generating the same aesthetics
+#' aes(mpg, wt, col = cyl, fill = NULL)
+#' aes_string("mpg", "wt", col = "cyl", fill = NULL)
+#' aes_q(quote(mpg), quote(wt), col = quote(cyl), fill = NULL)
+aes_string <- function(x, y, ...) {
+  mapping <- list(x = x, y = y, ...)
+  mapping[vapply(mapping, is.null, logical(1))] <- "NULL"
 
   parsed <- lapply(mapping, function(x) parse(text = x)[[1]])
   structure(rename_aes(parsed), class = "uneval")
 }
 
+#' @rdname aes_string
+#' @export
+aes_q <- function(x, y, ...) {
+  mapping <- list(x = x, y = y, ...)
+  structure(rename_aes(mapping), class = "uneval")
+}
+
 #' Given a character vector, create a set of identity mappings
 #'
 #' @param vars vector of variable names

man/aes.Rd

@@ -7,11 +7,7 @@ mapped to visual properties (aesthetics) of geoms.}
 aes(x, y, ...)
 }
 \arguments{
-\item{x}{x value}
-
-\item{y}{y value}
-
-\item{...}{List of name value pairs giving aesthetics to map.}
+\item{x,y,...}{List of name value pairs giving aesthetics to map.}
 }
 \description{
 \code{aes} creates a list of unevaluated expressions.  This function also
@@ -23,9 +19,12 @@ aes(x = mpg, y = wt)
 aes(x = mpg ^ 2, y = wt / cyl)
 }
 \seealso{
-\code{\link{aes_string}} for passing quoted variable names.
+See
    \code{\link{aes_colour_fill_alpha}}, \code{\link{aes_group_order}},
    \code{\link{aes_linetype_size_shape}} and \code{\link{aes_position}}
    for more specific examples with different aesthetics.
+
+Other aesthetic generators: \code{\link{aes_q}},
+  \code{\link{aes_string}}
 }
 

man/aes_string.Rd

@@ -1,28 +1,37 @@
 % Generated by roxygen2 (4.0.0): do not edit by hand
 \name{aes_string}
+\alias{aes_q}
 \alias{aes_string}
-\title{Generate aesthetic mappings from a string}
+\title{Generate aesthetic mappings from a string/quoted objects}
 \usage{
-aes_string(...)
+aes_string(x, y, ...)
+
+aes_q(x, y, ...)
 }
 \arguments{
-\item{...}{List of name value pairs}
+\item{x,y,...}{List of name value pairs}
 }
 \description{
 Aesthetic mappings describe how variables in the data are mapped to visual
-properties (aesthetics) of geoms.  Compared to aes this function operates
-on strings rather than expressions.
+properties (aesthetics) of geoms. \code{\link{aes}} uses non-standard
+evaluation to capture the variable names. These two variants use
+regular evaluation, which is easier to use inside functions.
 }
 \details{
-\code{aes_string} is particularly useful when writing functions that create
-plots because you can use strings to define the aesthetic mappings, rather
-than having to mess around with expressions.
+\code{aes_string} and \code{aes_q} are particularly useful when writing
+functions that create plots because you can use strings or quoted
+names/calls to define the aesthetic mappings, rather than having to use
+\code{\link{substitute}} to generate a call to \code{aes()}.
 }
 \examples{
-aes_string(x = "mpg", y = "wt")
-aes(x = mpg, y = wt)
+# Threee ways of generating the same aesthetics
+aes(mpg, wt, col = cyl, fill = NULL)
+aes_string("mpg", "wt", col = "cyl", fill = NULL)
+aes_q(quote(mpg), quote(wt), col = quote(cyl), fill = NULL)
 }
 \seealso{
 \code{\link{aes}}
+
+Other aesthetic generators: \code{\link{aes}}
 }