Add position_jitterdodge

DESCRIPTION

@@ -143,6 +143,7 @@ Collate:
     'position-fill.r'
     'position-identity.r'
     'position-jitter.r'
+    'position-jitterdodge.R'
     'position-stack.r'
     'quick-plot.r'
     'save.r'

NAMESPACE

@@ -287,6 +287,7 @@ export(position_dodge)
 export(position_fill)
 export(position_identity)
 export(position_jitter)
+export(position_jitterdodge)
 export(position_stack)
 export(qplot)
 export(quickplot)

NEWS

@@ -1,6 +1,11 @@
 ggplot2 0.9.3.1.99
 ----------------------------------------------------------------
 
+* `position_jitterdodge()` combines `position_jitter()` and `position_dodge()`,
+  allowing the user to plot and align points generated by e.g. `geom_point()`
+  with those generated by a dodged `geom_boxplot()`. See
+  `example(position_jitterdodge)` for a potential usage. (@kevinushey, #932)
+
 * Allow specifying only one of the limits in a scale and use the automatic
   calculation of the other limit by passing NA to to the limit function,
   `xlim()` or `ylim()` (@jimhester, #557).

R/position-jitterdodge.R

@@ -0,0 +1,87 @@
+#' Adjust position by simultaneously dodging and jittering
+#'
+#' This is primarily used for aligning points generated through
+#' \code{geom_point()} with dodged boxplots (e.g., a \code{geom_boxplot()} with
+#' a fill aesthetic supplied).
+#'
+#' @family position adjustments
+#' @param jitter.width degree of jitter in x direction. Defaults to 40\% of the
+#'   resolution of the data.
+#' @param jitter.height degree of jitter in y direction. Defaults to 0.
+#' @param dodge.width the amount to dodge in the x direction. Defaults to 0.75,
+#'   the default \code{position_dodge()} width.
+#' @export
+#' @examples
+#' dsub <- diamonds[ sample(nrow(diamonds), 1000), ]
+#' ggplot(dsub, aes(x = cut, y = carat, fill = clarity)) +
+#'   geom_boxplot(outlier.size = 0) +
+#'   geom_point(pch = 21, position = position_jitterdodge())
+position_jitterdodge <- function (jitter.width = NULL,
+                                  jitter.height = NULL,
+                                  dodge.width = NULL) {
+
+  PositionJitterDodge$new(jitter.width = jitter.width,
+                          jitter.height = jitter.height,
+                          dodge.width = dodge.width)
+}
+
+PositionJitterDodge <- proto(Position, {
+
+  jitter.width <- NULL
+  jitter.height <- NULL
+  dodge.width <- NULL
+
+  new <- function(.,
+                  jitter.width = NULL,
+                  jitter.height = NULL,
+                  dodge.width = NULL) {
+
+    .$proto(jitter.width=jitter.width,
+            jitter.height=jitter.height,
+            dodge.width=dodge.width)
+
+  }
+
+  objname <- "jitterdodge"
+
+  adjust <- function(., data) {
+
+    if (empty(data)) return(data.frame())
+    check_required_aesthetics(c("x", "y", "fill"), names(data), "position_jitterdodge")
+
+    ## Workaround to avoid this warning:
+    ## ymax not defined: adjusting position using y instead
+    if (!("ymax" %in% names(data))) {
+      data$ymax <- data$y
+    }
+
+    ## Adjust the x transformation based on the number of 'fill' variables
+    nfill <- length(levels(data$fill))
+
+    if (is.null(.$jitter.width)) {
+      .$jitter.width <- resolution(data$x, zero = FALSE) * 0.4
+    }
+
+    if (is.null(.$jitter.height)) {
+      .$jitter.height <- 0
+    }
+
+    trans_x <- NULL
+    trans_y <- NULL
+    if (.$jitter.width > 0) {
+      trans_x <- function(x) jitter(x, amount = .$jitter.width / (nfill + 2))
+    }
+    if (.$jitter.height > 0) {
+      trans_y <- function(x) jitter(x, amount = .$jitter.height)
+    }
+
+    if (is.null(.$dodge.width)) {
+      .$dodge.width <- 0.75
+    }
+
+    ## dodge, then jitter
+    data <- collide(data, .$dodge.width, .$my_name(), pos_dodge, check.width = FALSE)
+    transform_position(data, trans_x, trans_y)
+  }
+
+})

man/position_dodge.Rd

@@ -42,6 +42,7 @@ p + geom_errorbar(aes(ymin = y-1, ymax = y+1, width = 0.2),
 \seealso{
 Other position adjustments: \code{\link{position_fill}};
   \code{\link{position_identity}};
+  \code{\link{position_jitterdodge}};
   \code{\link{position_jitter}};
   \code{\link{position_stack}}
 }

man/position_fill.Rd

@@ -37,6 +37,7 @@ See \code{\link{geom_bar}} and \code{\link{geom_area}} for
 
 Other position adjustments: \code{\link{position_dodge}};
   \code{\link{position_identity}};
+  \code{\link{position_jitterdodge}};
   \code{\link{position_jitter}};
   \code{\link{position_stack}}
 }

man/position_identity.Rd

@@ -18,6 +18,7 @@ Don't adjust position
 \seealso{
 Other position adjustments: \code{\link{position_dodge}};
   \code{\link{position_fill}};
+  \code{\link{position_jitterdodge}};
   \code{\link{position_jitter}};
   \code{\link{position_stack}}
 }

man/position_jitter.Rd

@@ -36,6 +36,7 @@ qplot(class, hwy, data = mpg, geom = c("boxplot", "jitter"))
 Other position adjustments: \code{\link{position_dodge}};
   \code{\link{position_fill}};
   \code{\link{position_identity}};
+  \code{\link{position_jitterdodge}};
   \code{\link{position_stack}}
 }
 

man/position_jitterdodge.Rd

@@ -0,0 +1,38 @@
+% Generated by roxygen2 (4.0.0): do not edit by hand
+\name{position_jitterdodge}
+\alias{position_jitterdodge}
+\title{Adjust position by simultaneously dodging and jittering}
+\usage{
+position_jitterdodge(jitter.width = NULL, jitter.height = NULL,
+  dodge.width = NULL)
+}
+\arguments{
+  \item{jitter.width}{degree of jitter in x direction.
+  Defaults to 40\% of the resolution of the data.}
+
+  \item{jitter.height}{degree of jitter in y direction.
+  Defaults to 0.}
+
+  \item{dodge.width}{the amount to dodge in the x
+  direction. Defaults to 0.75, the default
+  \code{position_dodge()} width.}
+}
+\description{
+This is primarily used for aligning points generated through
+\code{geom_point()} with dodged boxplots (e.g., a \code{geom_boxplot()} with
+a fill aesthetic supplied).
+}
+\examples{
+dsub <- diamonds[ sample(nrow(diamonds), 1000), ]
+ggplot(dsub, aes(x = cut, y = carat, fill = clarity)) +
+  geom_boxplot(outlier.size = 0) +
+  geom_point(pch = 21, position = position_jitterdodge())
+}
+\seealso{
+Other position adjustments: \code{\link{position_dodge}};
+  \code{\link{position_fill}};
+  \code{\link{position_identity}};
+  \code{\link{position_jitter}};
+  \code{\link{position_stack}}
+}
+

man/position_stack.Rd

@@ -45,6 +45,7 @@ qplot(Time, Value, data = data.set, colour = Type, geom = "line",
 Other position adjustments: \code{\link{position_dodge}};
   \code{\link{position_fill}};
   \code{\link{position_identity}};
+  \code{\link{position_jitterdodge}};
   \code{\link{position_jitter}}
 }