Added geom_col() & updated references & examples in other functions. Substituted geom_col() for geom_bar() in one test to ensure it had test coverage outside the examples.

Author: hrbrmstr

DESCRIPTION

@@ -100,6 +100,7 @@ Collate:
     'geom-bin2d.r'
     'geom-blank.r'
     'geom-boxplot.r'
+    'geom-col.r'
     'geom-path.r'
     'geom-contour.r'
     'geom-count.r'

NAMESPACE

@@ -130,6 +130,7 @@ export(GeomArea)
 export(GeomBar)
 export(GeomBlank)
 export(GeomBoxplot)
+export(GeomCol)
 export(GeomContour)
 export(GeomCrossbar)
 export(GeomCurve)
@@ -269,6 +270,7 @@ export(geom_bar)
 export(geom_bin2d)
 export(geom_blank)
 export(geom_boxplot)
+export(geom_col)
 export(geom_contour)
 export(geom_count)
 export(geom_crossbar)

NEWS.md

@@ -14,8 +14,14 @@
   default. The `caption` annotation below the plot will be right-justified
   by default. (@hrbrmstr)
 
-* Minor code formatting issues in examples and function parameters were
-  fixed. (@hrbrmstr)
+* Minor code formatting and grammar issues in examples and function 
+  parameters were fixed. (@hrbrmstr)
+  
+* `geom_col()` was added to complement `geom_bar()`. It uses `stat="identity"`
+  by default, making the `y` aesthetic mandatory. It does not support any 
+  other `stat_()` and does not provide fallback support for the `binwidth`
+  parameter. Examples and references in other functions were updated to
+  demonstrate `geom_col()` usage. (@hrbrmstr)
 
 # ggplot2 2.1.0
 

R/coord-polar.r

@@ -36,7 +36,7 @@
 #'   value = c(20, 80)
 #' )
 #' ggplot(df, aes(x = "", y = value, fill = variable)) +
-#'   geom_bar(width = 1, stat = "identity") +
+#'   geom_col(width = 1) +
 #'   scale_fill_manual(values = c("red", "yellow")) +
 #'   coord_polar("y", start = pi / 3) +
 #'   labs(title = "Pac man")

R/fortify-lm.r

@@ -50,7 +50,7 @@
 #'
 #' plot(mod, which = 4)
 #' ggplot(mod, aes(seq_along(.cooksd), .cooksd)) +
-#'   geom_bar(stat = "identity")
+#'   geom_col()
 #'
 #' plot(mod, which = 5)
 #' ggplot(mod, aes(.hat, .stdresid)) +

R/geom-bar.r

@@ -2,7 +2,7 @@
 #'
 #' There are two types of bar charts, determined by what is mapped to bar
 #' height. By default, \code{geom_bar} uses \code{stat="count"} which makes the
-#' height of the bar proportion to the number of cases in each group (or if the
+#' height of the 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{stat="identity"} and map a variable to the \code{y} aesthetic.
@@ -23,7 +23,8 @@
 #' @section Aesthetics:
 #'   \Sexpr[results=rd,stage=build]{ggplot2:::rd_aesthetics("geom", "bar")}
 #'
-#' @seealso \code{\link{geom_histogram}} for continuous data,
+#' @seealso \code{\link{geom_col}} which uses \code{stat="identity"} by default,
+#'   \code{\link{geom_histogram}} for continuous data,
 #'   \code{\link{position_dodge}} for creating side-by-side barcharts.
 #' @export
 #' @inheritParams layer
@@ -47,7 +48,10 @@
 #' 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")
-#' # But geom_point() display exactly the same information and doesn't
+#' # And, even more succinctly with geom_col()
+#' 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()

R/geom-col.r

@@ -0,0 +1,85 @@
+#' Bars, rectangles with bases on x-axis
+#'
+#' This is an alternate version of \code{geom_bar} that uses
+#' \code{stat="identity"} (i.e. the heights of the bars represent values in the
+#' data) by default, requiring the use of a \code{y} aesthetic.
+#' If you need \code{stat="count"} functionality, use \code{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:
+#'   \Sexpr[results=rd,stage=build]{ggplot2:::rd_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()
+geom_col <- function(mapping = NULL, data = NULL,
+                     position = "stack",
+                     ...,
+                     width = NULL,
+                     na.rm = FALSE,
+                     show.legend = NA,
+                     inherit.aes = TRUE) {
+
+  layer(
+    data = data,
+    mapping = mapping,
+    stat = "identity",
+    geom = GeomCol,
+    position = position,
+    show.legend = show.legend,
+    inherit.aes = inherit.aes,
+    params = list(
+      width = width,
+      na.rm = na.rm,
+      ...
+    )
+  )
+}
+
+#' @rdname ggplot2-ggproto
+#' @format NULL
+#' @usage NULL
+#' @export
+#' @include geom-rect.r
+GeomCol <- ggproto("GeomCol", GeomRect,
+  required_aes = c("x", "y"),
+
+  setup_data = function(data, params) {
+    data$width <- data$width %||%
+      params$width %||% (resolution(data$x, FALSE) * 0.9)
+    transform(data,
+      ymin = pmin(y, 0), ymax = pmax(y, 0),
+      xmin = x - width / 2, xmax = x + width / 2, width = NULL
+    )
+  },
+
+  draw_panel = function(self, data, panel_scales, coord, width = NULL) {
+    # Hack to ensure that width is detected as a parameter
+    ggproto_parent(GeomRect, self)$draw_panel(data, panel_scales, coord)
+  }
+)

R/geom-linerange.r

@@ -40,14 +40,14 @@
 #' # specify the dodge width
 #' p <- ggplot(df, aes(trt, resp, fill = group))
 #' p +
-#'  geom_bar(position = "dodge", stat = "identity") +
+#'  geom_col(position = "dodge") +
 #'  geom_errorbar(aes(ymin = lower, ymax = upper), position = "dodge", width = 0.25)
 #'
 #' # Because the bars and errorbars have different widths
 #' # we need to specify how wide the objects we are dodging are
 #' dodge <- position_dodge(width=0.9)
 #' p +
-#'   geom_bar(position = dodge, stat = "identity") +
+#'   geom_col(position = dodge) +
 #'   geom_errorbar(aes(ymin = lower, ymax = upper), position = dodge, width = 0.25)
 geom_linerange <- function(mapping = NULL, data = NULL,
                            stat = "identity", position = "identity",

R/geom-text.r

@@ -87,23 +87,23 @@
 #' # ggplot2 doesn't know you want to give the labels the same virtual width
 #' # as the bars:
 #' ggplot(data = df, aes(x, y, fill = grp, label = y)) +
-#'   geom_bar(stat = "identity", position = "dodge") +
+#'   geom_col(position = "dodge") +
 #'   geom_text(position = "dodge")
 #' # So tell it:
 #' ggplot(data = df, aes(x, y, fill = grp, label = y)) +
-#'   geom_bar(stat = "identity", position = "dodge") +
+#'   geom_col(position = "dodge") +
 #'   geom_text(position = position_dodge(0.9))
 #' # Use you can't nudge and dodge text, so instead adjust the y postion
 #' ggplot(data = df, aes(x, y, fill = grp, label = y)) +
-#'   geom_bar(stat = "identity", position = "dodge") +
+#'   geom_col(position = "dodge") +
 #'   geom_text(aes(y = y + 0.05), position = position_dodge(0.9), vjust = 0)
 #'
 #' # To place text in the middle of each bar in a stacked barplot, you
 #' # need to do the computation yourself
 #' df <- transform(df, mid_y = ave(df$y, df$x, FUN = function(val) cumsum(val) - (0.5 * val)))
 #'
 #' ggplot(data = df, aes(x, y, fill = grp, label = y)) +
-#'  geom_bar(stat = "identity") +
+#'  geom_col() +
 #'  geom_text(aes(y = mid_y))
 #'
 #' # Justification -------------------------------------------------------------

R/position-dodge.r

@@ -17,9 +17,8 @@
 #' # To dodge items with different widths, you need to be explicit
 #' df <- data.frame(x = c("a","a","b","b"), y = 2:5, g = rep(1:2, 2))
 #' p <- ggplot(df, aes(x, y, group = g)) +
-#'   geom_bar(
-#'     stat = "identity", position = "dodge",
-#'     fill = "grey50", colour = "black"
+#'   geom_col(
+#'     position = "dodge", fill = "grey50", colour = "black"
 #'   )
 #' p
 #'

R/position-stack.r

@@ -4,7 +4,7 @@
 #' height.
 #'
 #' @family position adjustments
-#' @seealso See \code{\link{geom_bar}} and \code{\link{geom_area}} for
+#' @seealso See \code{\link{geom_bar}}, and \code{\link{geom_area}} for
 #'   more examples.
 #' @export
 #' @examples