Tweaking docs & pkgdown desc

Complete up to "layers"

Author: hadley

R/geom-abline.r

@@ -1,11 +1,11 @@
 #' @include stat-.r
 NULL
 
-#' Lines: horizontal, vertical, and specified by slope and intercept.
+#' Reference lines: horizontal, vertical, and diagonal
 #'
-#' These paired geoms and stats add straight lines to a plot, either
-#' horizontal, vertical or specified by slope and intercept. These are useful
-#' for annotating plots.
+#' These geoms add reference lines (sometimes called rules) to a plot, either
+#' horizontal, vertical, or diagonal (specified by slope and intercept).
+#' These are useful for annotating plots.
 #'
 #' These geoms act slightly different to other geoms. You can supply the
 #' parameters in two ways: either as arguments to the layer function,
@@ -21,8 +21,9 @@ NULL
 #'
 #' @section Aesthetics:
 #' These geoms are drawn using with \code{\link{geom_line}} so support the
-#' same aesthetics: alpha, colour, linetype and size. They also each have
-#' aesthetics that control the position of the line:
+#' same aesthetics: \code{alpha}, \code{colour}, \code{linetype} and
+#' \code{size}. They also each have aesthetics that control the position of
+#' the line:
 #'
 #' \itemize{
 #'   \item \code{geom_vline}: \code{xintercept}

R/geom-bar.r

@@ -4,25 +4,27 @@
 #' bar proportional to the number of cases in each group (or if the
 #' \code{weight} aethetic is supplied, the sum of the weights). If you want the
 #' heights of the bars to represent values in the data, use
-#' \code{\link{geom_col}} instead.
+#' \link{geom_col} instead. \code{geom_bar} uses \code{stat_count} by
+#' default: it counts the  number of cases at each x position. \code{geom_col}
+#' uses \code{stat_identity}: it leaves the data as is.
 #'
-#' A bar chart maps the height of the bar to a variable, and so the base of the
+#' A bar chart uses height to represent a value, and so the base of the
 #' bar must always be shown to produce a valid visual comparison. Naomi Robbins
 #' has a nice
 #' \href{http://www.b-eye-network.com/view/index.php?cid=2468}{article on this
 #' topic}. This is why it doesn't make sense to use a log-scaled y axis with a
 #' bar chart.
 #'
-#' By default, multiple x's occurring in the same place will be stacked atop one
-#' another by \code{\link{position_stack}}. If you want them to be dodged
-#' side-to-side, see \code{\link{position_dodge}}. Finally,
-#' \code{\link{position_fill}} shows relative proportions at each x by stacking
-#' the bars and then stretching or squashing to the same height.
+#' By default, multiple bar occupying the same \code{x} position will be
+#' stacked atop one another by \code{\link{position_stack}}. If you want them
+#' to be dodged side-to-side, use \code{\link{position_dodge}}. Finally,
+#' \code{\link{position_fill}} shows relative proportions at each \code{x} by
+#' stacking the bars and then standardising each bar to have the same height.
 #'
 #' @section Aesthetics:
 #' \aesthetics{geom}{bar}
 #'
-#' @seealso \code{\link{geom_col}} which uses \code{stat="identity"} by default,
+#' @seealso
 #'   \code{\link{geom_histogram}} for continuous data,
 #'   \code{\link{position_dodge}} for creating side-by-side barcharts.
 #' @export
@@ -43,11 +45,9 @@
 #' # Total engine displacement of each class
 #' g + geom_bar(aes(weight = displ))
 #'
-#' # To show (e.g.) means, you need stat = "identity"
-#' df <- data.frame(trt = c("a", "b", "c"), outcome = c(2.3, 1.9, 3.2))
-#' ggplot(df, aes(trt, outcome)) +
-#'   geom_bar(stat = "identity")
+#' # To show (e.g.) means, you need geom_col()
 #' # And, even more succinctly with geom_col()
+#' df <- data.frame(trt = c("a", "b", "c"), outcome = c(2.3, 1.9, 3.2))
 #' ggplot(df, aes(trt, outcome)) +
 #'   geom_col()
 #' # But geom_point() displays exactly the same information and doesn't

R/geom-bin2d.r

@@ -1,4 +1,4 @@
-#' Add heatmap of 2d bin counts.
+#' Heatmap of 2d bin counts
 #'
 #' Divides the plane into rectangles, counts the number of cases in
 #' each rectangle, and then (by default) maps the number of cases to the

R/geom-blank.r

@@ -1,7 +1,8 @@
-#' Blank, draws nothing.
+#' Draw nothing
 #'
 #' The blank geom draws nothing, but can be a useful way of ensuring common
-#' scales between different plots.
+#' scales between different plots. See \code{\link{expand_limits}} for
+#' more details.
 #'
 #' @export
 #' @inheritParams layer

R/geom-boxplot.r

@@ -1,20 +1,22 @@
-#' A Tukey box and whiskers plot.
+#' A box and whiskers plot (in the style of Tukey)
 #'
-#' The boxplot gives a compact display of the distribution of a continuous
-#' variable. It displays a five number summary (defined by the median,
-#' two hinges, and two whiskers), and then individually all "outlying" points.
+#' The boxplot compactly displays the distribution of a continuous variable.
+#' It visualises five summary statistics (the median, two hinges
+#' and two whiskers), and all "outlying" points individually.
 #'
+#' @section Summary statistics:
 #' The lower and upper hinges correspond to the first and third quartiles
 #' (the 25th and 75th percentiles). This differs slightly from the method used
 #' by the \code{boxplot} function, and may be apparent with small samples.
 #' See \code{\link{boxplot.stats}} for for more information on how hinge
 #' positions are calculated for \code{boxplot}.
 #'
-#' The upper whisker extends from the hinge to the highest value that is within
-#' 1.5 * IQR of the hinge, where IQR is the inter-quartile range, or distance
-#' between the first and third quartiles. The lower whisker extends from the
-#' hinge to the lowest value within 1.5 * IQR of the hinge. Data beyond the
-#' end of the whiskers are outliers and plotted as points.
+#' The upper whisker extends from the hinge to the largest value no further than
+#' 1.5 * IQR from the hinge (where IQR is the inter-quartile range, or distance
+#' between the first and third quartiles). The lower whisker extends from the
+#' hinge to the smallest value at most 1.5 * IQR of the hinge. Data beyond the
+#' end of the whiskers are called "outlying" points and are plotted
+#' individually.
 #'
 #' In a notched box plot, the notches extend \code{1.58 * IQR / sqrt(n)}.
 #' This gives a roughly 95\% confidence interval for comparing medians.
@@ -23,9 +25,9 @@
 #' @section Aesthetics:
 #' \aesthetics{geom}{boxplot}
 #'
-#' @seealso \code{\link{stat_quantile}} to view quantiles conditioned on a
-#'   continuous variable, \code{\link{geom_jitter}} for another way to look
-#'   at conditional distributions.
+#' @seealso \code{\link{geom_quantile}} for continuous x,
+#'   \code{\link{geom_violin}} for a richer display of the distribution, and
+#'   \code{\link{geom_jitter}} for a useful technique for small data.
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @param geom,stat Use to override the default connection between

R/geom-col.r

@@ -1,41 +1,5 @@
-#' Bars, rectangles with bases on x-axis
-#'
-#' This is an alternate version of \code{geom_bar} that maps the height of
-#' bars to an existing variable in your data. If you want the height of the
-#' bar to represent a count of cases, use \code{\link{geom_bar}}.
-#'
-#' A bar chart maps the height of the bar to a variable, and so the base of the
-#' bar must always be shown to produce a valid visual comparison. Naomi Robbins
-#' has a nice
-#' \href{http://www.b-eye-network.com/view/index.php?cid=2468}{article on this
-#' topic}. This is why it doesn't make sense to use a log-scaled y axis with a
-#' bar chart.
-#'
-#' By default, multiple x's occurring in the same place will be stacked atop one
-#' another by \code{\link{position_stack}}. If you want them to be dodged
-#' side-to-side, see \code{\link{position_dodge}}. Finally,
-#' \code{\link{position_fill}} shows relative proportions at each x by stacking
-#' the bars and then stretching or squashing to the same height.
-#'
-#' @section Aesthetics:
-#' \aesthetics{geom}{col}
-#'
-#' @seealso \code{\link{geom_bar}} to make the height of the bar proportional to
-#'  the number of cases in each group or sum of weights,
-#'   \code{\link{geom_histogram}} for continuous data,
-#'   \code{\link{position_dodge}} for creating side-by-side barcharts.
 #' @export
-#' @inheritParams layer
-#' @inheritParams geom_point
-#' @param width Bar width. By default, set to 90\% of the resolution of the data.
-#' @examples
-#' df <- data.frame(trt = c("a", "b", "c"), outcome = c(2.3, 1.9, 3.2))
-#' ggplot(df, aes(trt, outcome)) +
-#'   geom_col()
-#' # But geom_point() displays exactly the same information and doesn't
-#' # require the y-axis to touch zero.
-#' ggplot(df, aes(trt, outcome)) +
-#'   geom_point()
+#' @rdname geom_bar
 geom_col <- function(mapping = NULL, data = NULL,
                      position = "stack",
                      ...,

R/geom-contour.r

@@ -1,8 +1,12 @@
-#' Display contours of a 3d surface in 2d.
+#' 2d contours of a 3d surface
 #'
-#' To be a valid surface, the most only be a single combination of each
-#' unique \code{x} and \code{y} aesthetics. Contouring tends to work best
-#' when \code{x} and \code{y} form a (roughly) evenly spaced grid.
+#' ggplot2 can not draw true 3d surfaces, but you can use \code{geom_contour}
+#' and \code{\link{geom_tile}} to visualise 3d surfaces in 2d. To be a valid
+#' surface, the data must contain only a single row for each unique combination
+#' of the variables mapped to the \code{x} and \code{y} aesthetics. Contouring
+#' tends to work best when \code{x} and \code{y} form a (roughly) evenly
+#' spaced grid. If you data is not evenly spaced, you may want to interpolate
+#' to a grid before visualising.
 #'
 #' @section Aesthetics:
 #' \aesthetics{geom}{contour}

R/geom-count.r

@@ -1,14 +1,15 @@
-#' Count the number of observations at each location.
+#' Count overlapping points
 #'
 #' This is a variant \code{\link{geom_point}} that counts the number of
-#' observations at each location, then maps the count to point size. It
-#' useful when you have discrete data.
+#' observations at each location, then maps the count to point area. It
+#' useful when you have discrete data and overplotting.
 #'
 #' @section Aesthetics:
 #' \aesthetics{geom}{point}
 #'
 #' @param geom,stat Use to override the default connection between
 #'   \code{geom_count} and \code{stat_sum}.
+#' @seealso For continuous \code{x} and \code{x}, use \code{\link{geom_bin2d}}.
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @export
@@ -23,7 +24,7 @@
 #' # counts of zero would be given size 0. Doesn't make much different
 #' # here because the smallest count is already close to 0.
 #' ggplot(mpg, aes(cty, hwy)) +
-#'  geom_count()
+#'  geom_count() +
 #'  scale_size_area()
 #'
 #' # Display proportions instead of counts -------------------------------------

R/geom-density.r

@@ -1,7 +1,8 @@
-#' Display a smooth density estimate.
+#' Smoothed density estimates
 #'
 #' Computes and draws kernel density estimate, which is a smoothed version of
-#' the histogram.
+#' the histogram. This is a useful alternative to the histogram if for continuous
+#' data that comes from an underlying smooth distribution.
 #'
 #' @section Aesthetics:
 #' \aesthetics{geom}{density}

R/geom-density2d.r

@@ -1,15 +1,15 @@
-#' Contours from a 2d density estimate.
+#' Contours of a 2d density estimate
 #'
 #' Perform a 2D kernel density estimation using \code{\link[MASS]{kde2d}} and
 #' display the results with contours. This can be useful for dealing with
-#' overplotting.
+#' overplotting. This is a 2d version of \code{\link{geom_density}}.
 #'
 #' @section Aesthetics:
 #' \aesthetics{geom}{density_2d}
 #'
 #' @seealso \code{\link{geom_contour}} for information about how contours
 #'  are drawn; \code{\link{geom_bin2d}} for another way of dealing with
-#'  overplotting
+#'  overplotting.
 #' @param geom,stat Use to override the default connection between
 #'   \code{geom_density_2d} and \code{stat_density_2d}.
 #' @inheritParams layer