From 0532266793cb084c00260978f986e39af03a6500 Mon Sep 17 00:00:00 2001 From: hadley Date: Wed, 29 Jul 2015 10:53:25 -0500 Subject: [PATCH] Improve ggplot() docs --- R/plot.r | 57 ++++++++++++++++++++++------------------ man/ggplot.Rd | 27 ++++++++++--------- man/ggplot.data.frame.Rd | 26 ------------------ man/is.ggplot.Rd | 1 + 4 files changed, 47 insertions(+), 64 deletions(-) delete mode 100644 man/ggplot.data.frame.Rd diff --git a/R/plot.r b/R/plot.r index 79cca091df..7e573defac 100644 --- a/R/plot.r +++ b/R/plot.r @@ -1,4 +1,4 @@ -#' Create a new ggplot plot +#' Create a new ggplot plot. #' #' \code{ggplot()} initializes a ggplot object. It can be used to #' declare the input data frame for a graphic and to specify the @@ -31,14 +31,16 @@ #' multiple data frames are used to produce different layers, as #' is often the case in complex graphics. #' -#' The examples below illustrate how these methods of -#' invoking \code{ggplot} can be used in constructing a -#' graphic. -#' @seealso \url{http://had.co.nz/ggplot2} +#' @param data Default dataset to use for plot. If not already a data.frame, +#' will be converted to one by \code{\link{fortify}}. If not specified, +#' must be suppled in each layer added to the plot. +#' @param mapping Default list of aesthetic mappings to use for plot. +#' If not specified, must be suppled in each layer added to the plot. +#' @param ... Other arguments passed on to methods. Not currently used. +#' @param environment If an variable defined in the aesthetic mapping is not +#' found in the data, ggplot will look for it in this environment. It defaults +#' to using the environment in which \code{ggplot()} is called. #' @export -#' @keywords internal -#' @param data default data set -#' @param ... other arguments passed to specific methods #' @examples #' df <- data.frame(gp = factor(rep(letters[1:3], each = 10)), #' y = rnorm(30)) @@ -69,30 +71,27 @@ #' geom_errorbar(data = ds, aes(x = gp, y = mean, #' ymin = mean - sd, ymax = mean + sd), #' colour = 'red', width = 0.4) -ggplot <- function(data = NULL, ...) UseMethod("ggplot") +ggplot <- function(data = NULL, mapping = aes(), ..., + environment = parent.frame()) { + UseMethod("ggplot") +} #' @export -ggplot.default <- function(data = NULL, mapping = aes(), ..., environment = parent.frame()) { +#' @rdname ggplot +#' @usage NULL +ggplot.default <- function(data = NULL, mapping = aes(), ..., + environment = parent.frame()) { ggplot.data.frame(fortify(data, ...), mapping, environment = environment) } -#' Reports whether x is a ggplot object -#' @param x An object to test -#' @export -is.ggplot <- function(x) inherits(x, "ggplot") - -#' Create a new ggplot plot from a data frame -#' -#' @param data default data frame for plot -#' @param mapping default list of aesthetic mappings (these can be colour, -#' size, shape, line type -- see individual geom functions for more details) -#' @param ... ignored -#' @param environment in which evaluation of aesthetics should occur -#' @seealso \url{http://had.co.nz/ggplot2} -#' @method ggplot data.frame #' @export -ggplot.data.frame <- function(data, mapping=aes(), ..., environment = parent.frame()) { - if (!missing(mapping) && !inherits(mapping, "uneval")) stop("Mapping should be created with aes or aes_string") +#' @rdname ggplot +#' @usage NULL +ggplot.data.frame <- function(data, mapping = aes(), ..., + environment = parent.frame()) { + if (!missing(mapping) && !inherits(mapping, "uneval")) { + stop("Mapping should be created with aes or aes_string") + } p <- structure(list( data = data, @@ -118,3 +117,9 @@ plot_clone <- function(plot) { p } + +#' Reports whether x is a ggplot object +#' @param x An object to test +#' @keywords internal +#' @export +is.ggplot <- function(x) inherits(x, "ggplot") diff --git a/man/ggplot.Rd b/man/ggplot.Rd index 06771ff3e7..0d91d995e7 100644 --- a/man/ggplot.Rd +++ b/man/ggplot.Rd @@ -2,14 +2,25 @@ % Please edit documentation in R/plot.r \name{ggplot} \alias{ggplot} -\title{Create a new ggplot plot} +\alias{ggplot.data.frame} +\alias{ggplot.default} +\title{Create a new ggplot plot.} \usage{ -ggplot(data = NULL, ...) +ggplot(data = NULL, mapping = aes(), ..., environment = parent.frame()) } \arguments{ -\item{data}{default data set} +\item{data}{Default dataset to use for plot. If not already a data.frame, +will be converted to one by \code{\link{fortify}}. If not specified, +must be suppled in each layer added to the plot.} -\item{...}{other arguments passed to specific methods} +\item{mapping}{Default list of aesthetic mappings to use for plot. +If not specified, must be suppled in each layer added to the plot.} + +\item{...}{Other arguments passed on to methods. Not currently used.} + +\item{environment}{If an variable defined in the aesthetic mapping is not +found in the data, ggplot will look for it in this environment. It defaults +to using the environment in which \code{ggplot()} is called.} } \description{ \code{ggplot()} initializes a ggplot object. It can be used to @@ -43,10 +54,6 @@ third method initializes a skeleton \code{ggplot} object which is fleshed out as layers are added. This method is useful when multiple data frames are used to produce different layers, as is often the case in complex graphics. - -The examples below illustrate how these methods of -invoking \code{ggplot} can be used in constructing a -graphic. } \examples{ df <- data.frame(gp = factor(rep(letters[1:3], each = 10)), @@ -79,8 +86,4 @@ ggplot() + ymin = mean - sd, ymax = mean + sd), colour = 'red', width = 0.4) } -\seealso{ -\url{http://had.co.nz/ggplot2} -} -\keyword{internal} diff --git a/man/ggplot.data.frame.Rd b/man/ggplot.data.frame.Rd deleted file mode 100644 index 9b2a4a73ef..0000000000 --- a/man/ggplot.data.frame.Rd +++ /dev/null @@ -1,26 +0,0 @@ -% Generated by roxygen2 (4.1.1): do not edit by hand -% Please edit documentation in R/plot.r -\name{ggplot.data.frame} -\alias{ggplot.data.frame} -\title{Create a new ggplot plot from a data frame} -\usage{ -\method{ggplot}{data.frame}(data, mapping = aes(), ..., - environment = parent.frame()) -} -\arguments{ -\item{data}{default data frame for plot} - -\item{mapping}{default list of aesthetic mappings (these can be colour, -size, shape, line type -- see individual geom functions for more details)} - -\item{...}{ignored} - -\item{environment}{in which evaluation of aesthetics should occur} -} -\description{ -Create a new ggplot plot from a data frame -} -\seealso{ -\url{http://had.co.nz/ggplot2} -} - diff --git a/man/is.ggplot.Rd b/man/is.ggplot.Rd index b6c1cabfaf..198b5c2e04 100644 --- a/man/is.ggplot.Rd +++ b/man/is.ggplot.Rd @@ -12,4 +12,5 @@ is.ggplot(x) \description{ Reports whether x is a ggplot object } +\keyword{internal}