Updates to position_jitterdodge()

  * Motivate the change in NEWS
  * Fix the style
  * Allow jitter.width, jitter.height, dodge.width as arguments
  * Improve the documentation

Author: kevinushey

NAMESPACE

@@ -286,7 +286,6 @@ export(plotmatrix)
 export(position_dodge)
 export(position_fill)
 export(position_identity)
-export(position_jd)
 export(position_jitter)
 export(position_jitterdodge)
 export(position_stack)

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

@@ -1,25 +1,47 @@
-#' Jitter-dodge points to align them with a boxplot including fill aesthetic
+#' 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 width degree of jitter in x direction. Defaults to 40\% of the
+#' @param jitter.width degree of jitter in x direction. Defaults to 40\% of the
 #'   resolution of the data.
-#' @param height degree of jitter in y 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(1: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 (width = NULL, height = NULL) {
-  PositionJitterDodge$new(width = width, height = height)
-}
+#' 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) {
 
-#' @rdname position_jitterdodge
-#' @export
-position_jd <- position_jitterdodge
+  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) {
@@ -34,22 +56,31 @@ PositionJitterDodge <- proto(Position, {
     }
 
     ## Adjust the x transformation based on the number of 'fill' variables
-    nfill <- length( levels(data$fill) )
+    nfill <- length(levels(data$fill))
 
-    if (is.null(.$width)) .$width <- resolution(data$x, zero = FALSE) * 0.4
-    if (is.null(.$height)) .$height <- resolution(data$y, zero = FALSE) * 0.4
+    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(.$width > 0) {
-      trans_x <- function(x) jitter(x, amount = .$width / (nfill + 2))
+    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(.$height > 0) {
-      trans_y <- function(x) jitter(x, amount = .$height)
+
+    if (is.null(.$dodge.width)) {
+      .$dodge.width <- 0.75
     }
 
     ## dodge, then jitter
-    data <- collide(data, 0.75, .$my_name(), pos_dodge, check.width = FALSE)
+    data <- collide(data, .$dodge.width, .$my_name(), pos_dodge, check.width = FALSE)
     transform_position(data, trans_x, trans_y)
   }
 

man/position_dodge.Rd

@@ -42,7 +42,6 @@ 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_jd}},
   \code{\link{position_jitterdodge}};
   \code{\link{position_jitter}};
   \code{\link{position_stack}}

man/position_fill.Rd

@@ -37,7 +37,6 @@ 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_jd}},
   \code{\link{position_jitterdodge}};
   \code{\link{position_jitter}};
   \code{\link{position_stack}}

man/position_identity.Rd

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

man/position_jitter.Rd

@@ -36,7 +36,6 @@ 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_jd}},
   \code{\link{position_jitterdodge}};
   \code{\link{position_stack}}
 }

man/position_jitterdodge.Rd

@@ -1,28 +1,32 @@
 % Generated by roxygen2 (4.0.0): do not edit by hand
 \name{position_jitterdodge}
-\alias{position_jd}
 \alias{position_jitterdodge}
-\title{Jitter-dodge points to align them with a boxplot including fill aesthetic}
+\title{Adjust position by simultaneously dodging and jittering}
 \usage{
-position_jitterdodge(width = NULL, height = NULL)
-
-position_jd(width = NULL, height = NULL)
+position_jitterdodge(jitter.width = NULL, jitter.height = NULL,
+  dodge.width = NULL)
 }
 \arguments{
-  \item{width}{degree of jitter in x direction. Defaults to
-  40\% of the resolution of the data.}
+  \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{height}{degree of jitter in y direction. Defaults
-  to 40\% of the resolution of the data}
+  \item{dodge.width}{the amount to dodge in the x
+  direction. Defaults to 0.75, the default
+  \code{position_dodge()} width.}
 }
 \description{
-Jitter-dodge points to align them with a boxplot including fill aesthetic
+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(1:nrow(diamonds), 1000), ]
-ggplot(dsub, aes(x=cut, y=carat, fill=clarity)) +
-  geom_boxplot(outlier.size=0) +
-  geom_point( pch=21, position=position_jitterdodge() )
+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}};

man/position_stack.Rd

@@ -45,7 +45,6 @@ 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_jd}},
   \code{\link{position_jitterdodge}};
   \code{\link{position_jitter}}
 }