Merge pull request #925 from jiho/feature/brewer-continuous

Rebased version of continuous brewer color scales

Author: hadley

NAMESPACE

@@ -301,6 +301,7 @@ export(scale_area)
 export(scale_color_brewer)
 export(scale_color_continuous)
 export(scale_color_discrete)
+export(scale_color_distiller)
 export(scale_color_gradient)
 export(scale_color_gradient2)
 export(scale_color_gradientn)
@@ -311,6 +312,7 @@ export(scale_color_manual)
 export(scale_colour_brewer)
 export(scale_colour_continuous)
 export(scale_colour_discrete)
+export(scale_colour_distiller)
 export(scale_colour_gradient)
 export(scale_colour_gradient2)
 export(scale_colour_gradientn)
@@ -321,6 +323,7 @@ export(scale_colour_manual)
 export(scale_fill_brewer)
 export(scale_fill_continuous)
 export(scale_fill_discrete)
+export(scale_fill_distiller)
 export(scale_fill_gradient)
 export(scale_fill_gradient2)
 export(scale_fill_gradientn)

NEWS

@@ -8,6 +8,9 @@ ggplot2 0.9.3.1.99
   to `theme_gray`. `theme_light` is similar but with light gray box and axes
   around the plot, to emphasise content more (@jiho, #923)
 
+* Allow to use brewer palettes for continuous scales, through the new
+  `scale_fill/colour_distiller()` functions (@jiho, #925).
+
 * 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/scale-brewer.r

@@ -1,33 +1,59 @@
 #' Sequential, diverging and qualitative colour scales from colorbrewer.org
 #'
+#' ColorBrewer provides sequential, diverging and qualitative colour schemes
+#' which are particularly suited and tested to display discrete values (levels
+#' of a factor) on a map. ggplot2 can use those colours in discrete scales. It
+#' also allows to smoothly interpolate 6 colours from any palette to a
+#' continuous scale (6 colours per palette gives nice gradients; more results in
+#' more saturated colours which do not look as good). However, the original
+#' colour schemes (particularly the qualitative ones) were not intended for this
+#' and the perceptual result is left to the appreciation of the user.
+#'
 #' See \url{http://colorbrewer2.org} for more information.
 #'
 #' @inheritParams scales::brewer_pal
 #' @inheritParams scale_colour_hue
+#' @inheritParams scale_colour_gradient
 #' @family colour scales
 #' @rdname scale_brewer
 #' @export
 #' @examples
 #' dsamp <- diamonds[sample(nrow(diamonds), 1000), ]
-#' (d <- qplot(carat, price, data=dsamp, colour=clarity))
+#' (d <- qplot(carat, price, data = dsamp, colour = clarity))
 #'
 #' # Change scale label
 #' d + scale_colour_brewer()
 #' d + scale_colour_brewer("clarity")
 #' d + scale_colour_brewer(expression(clarity[beta]))
 #'
 #' # Select brewer palette to use, see ?scales::brewer_pal for more details
-#' d + scale_colour_brewer(type="seq")
-#' d + scale_colour_brewer(type="seq", palette=3)
+#' d + scale_colour_brewer(type = "seq")
+#' d + scale_colour_brewer(type = "seq", palette = 3)
 #'
-#' d + scale_colour_brewer(palette="Blues")
-#' d + scale_colour_brewer(palette="Set1")
+#' d + scale_colour_brewer(palette = "Blues")
+#' d + scale_colour_brewer(palette = "Set1")
 #'
 #' # scale_fill_brewer works just the same as
 #' # scale_colour_brewer but for fill colours
-#' ggplot(diamonds, aes(x=price, fill=cut)) +
-#'   geom_histogram(position="dodge", binwidth=1000) +
+#' ggplot(diamonds, aes(x = price, fill = cut)) +
+#'   geom_histogram(position = "dodge", binwidth = 1000) +
 #'   scale_fill_brewer()
+#'
+#' # Generate map data
+#' library(reshape2) # for melt
+#' volcano3d <- melt(volcano)
+#' names(volcano3d) <- c("x", "y", "z")
+#'
+#' # Basic plot
+#' v <- ggplot() + geom_tile(aes(x = x, y = y, fill = z), data = volcano3d)
+#' v
+#' v + scale_fill_distiller()
+#' v + scale_fill_distiller(palette = 2)
+#' v + scale_fill_distiller(type = "div")
+#' v + scale_fill_distiller(palette = "Spectral")
+#' v + scale_fill_distiller(palette = "Spectral", trans = "reverse")
+#' v + scale_fill_distiller(type = "qual")
+#' # Not appropriate for continuous data, issues a warning
 scale_colour_brewer <- function(..., type = "seq", palette = 1) {
   discrete_scale("colour", "brewer", brewer_pal(type, palette), ...)
 }
@@ -37,3 +63,33 @@ scale_colour_brewer <- function(..., type = "seq", palette = 1) {
 scale_fill_brewer <- function(..., type = "seq", palette = 1) {
   discrete_scale("fill", "brewer", brewer_pal(type, palette), ...)
 }
+
+#' @export
+#' @rdname scale_brewer
+scale_colour_distiller <- function(..., type = "seq", palette = 1, values = NULL, space = "Lab", na.value = "grey50") {
+  # warn about using a qualitative brewer palette to generate the gradient
+  type <- match.arg(type, c("seq", "div", "qual"))
+  if (type == "qual") {
+    warning("Using a discrete colour palette in a continuous scale.\n  Consider using type = \"seq\" or type = \"div\" instead", call. = FALSE)
+  }
+  continuous_scale("colour", "distiller",
+    gradient_n_pal(brewer_pal(type, palette)(6), values, space), na.value = na.value, ...)
+  # NB: 6 colours per palette gives nice gradients; more results in more saturated colours which do not look as good
+}
+
+#' @export
+#' @rdname scale_brewer
+scale_fill_distiller <- function(..., type = "seq", palette = 1, values = NULL, space = "Lab", na.value = "grey50") {
+  type <- match.arg(type, c("seq", "div", "qual"))
+  if (type == "qual") {
+    warning("Using a discrete colour palette in a continuous scale.\n  Consider using type = \"seq\" or type = \"div\" instead", call. = FALSE)
+  }
+  continuous_scale("fill", "distiller",
+    gradient_n_pal(brewer_pal(type, palette)(6), values, space), na.value = na.value, ...)
+}
+
+# icon.brewer <- function() {
+#   rectGrob(c(0.1, 0.3, 0.5, 0.7, 0.9), width = 0.21, 
+#     gp = gpar(fill = RColorBrewer::brewer.pal(5, "PuOr"), col = NA)
+#   )
+# }

R/zxx.r

@@ -22,6 +22,10 @@ scale_fill_continuous <- scale_fill_gradient
 #' @rdname scale_brewer
 scale_color_brewer <- scale_colour_brewer
 
+#' @export
+#' @rdname scale_brewer
+scale_color_distiller <- scale_colour_distiller
+
 #' @export
 #' @rdname scale_gradient
 scale_color_continuous <- scale_colour_gradient

man/scale_brewer.Rd

@@ -1,15 +1,27 @@
 % Generated by roxygen2 (4.0.0): do not edit by hand
 \name{scale_colour_brewer}
 \alias{scale_color_brewer}
+\alias{scale_color_distiller}
 \alias{scale_colour_brewer}
+\alias{scale_colour_distiller}
 \alias{scale_fill_brewer}
+\alias{scale_fill_distiller}
 \title{Sequential, diverging and qualitative colour scales from colorbrewer.org}
 \usage{
 scale_colour_brewer(..., type = "seq", palette = 1)
 
 scale_fill_brewer(..., type = "seq", palette = 1)
 
+scale_colour_distiller(..., type = "seq", palette = 1, values = NULL,
+  space = "Lab", na.value = "grey50")
+
+scale_fill_distiller(..., type = "seq", palette = 1, values = NULL,
+  space = "Lab", na.value = "grey50")
+
 scale_color_brewer(..., type = "seq", palette = 1)
+
+scale_color_distiller(..., type = "seq", palette = 1, values = NULL,
+  space = "Lab", na.value = "grey50")
 }
 \arguments{
   \item{type}{One of seq (sequential), div (diverging) or
@@ -22,31 +34,59 @@ scale_color_brewer(..., type = "seq", palette = 1)
   \item{...}{Other arguments passed on to
   \code{\link{discrete_scale}} to control name, limits,
   breaks, labels and so forth.}
+
+  \item{na.value}{Colour to use for missing values}
 }
 \description{
+ColorBrewer provides sequential, diverging and qualitative colour schemes
+which are particularly suited and tested to display discrete values (levels
+of a factor) on a map. ggplot2 can use those colours in discrete scales. It
+also allows to smoothly interpolate 6 colours from any palette to a
+continuous scale (6 colours per palette gives nice gradients; more results in
+more saturated colours which do not look as good). However, the original
+colour schemes (particularly the qualitative ones) were not intended for this
+and the perceptual result is left to the appreciation of the user.
+}
+\details{
 See \url{http://colorbrewer2.org} for more information.
 }
 \examples{
 dsamp <- diamonds[sample(nrow(diamonds), 1000), ]
-(d <- qplot(carat, price, data=dsamp, colour=clarity))
+(d <- qplot(carat, price, data = dsamp, colour = clarity))
 
 # Change scale label
 d + scale_colour_brewer()
 d + scale_colour_brewer("clarity")
 d + scale_colour_brewer(expression(clarity[beta]))
 
 # Select brewer palette to use, see ?scales::brewer_pal for more details
-d + scale_colour_brewer(type="seq")
-d + scale_colour_brewer(type="seq", palette=3)
+d + scale_colour_brewer(type = "seq")
+d + scale_colour_brewer(type = "seq", palette = 3)
 
-d + scale_colour_brewer(palette="Blues")
-d + scale_colour_brewer(palette="Set1")
+d + scale_colour_brewer(palette = "Blues")
+d + scale_colour_brewer(palette = "Set1")
 
 # scale_fill_brewer works just the same as
 # scale_colour_brewer but for fill colours
-ggplot(diamonds, aes(x=price, fill=cut)) +
-  geom_histogram(position="dodge", binwidth=1000) +
+ggplot(diamonds, aes(x = price, fill = cut)) +
+  geom_histogram(position = "dodge", binwidth = 1000) +
   scale_fill_brewer()
+
+# Generate map data
+library(reshape2) # for melt
+volcano3d <- melt(volcano)
+names(volcano3d) <- c("x", "y", "z")
+
+# Basic plot
+v <- ggplot() + geom_tile(aes(x = x, y = y, fill = z), data = volcano3d)
+v
+v + scale_fill_distiller()
+v + scale_fill_distiller(palette = 2)
+v + scale_fill_distiller(type = "div")
+v + scale_fill_distiller(palette = "Spectral")
+v + scale_fill_distiller(palette = "Spectral", trans = "reverse")
+v + scale_fill_distiller(type = "qual")
+# Not appropriate for continuous data, issues a warning
 }
 \seealso{
 Other colour scales: \code{\link{scale_color_continuous}},

man/scale_gradient.Rd

@@ -99,8 +99,11 @@ qplot(mpg, wt, data = mtcars, colour = miss) +
   palette
 
 Other colour scales: \code{\link{scale_color_brewer}},
+  \code{\link{scale_color_distiller}},
   \code{\link{scale_colour_brewer}},
-  \code{\link{scale_fill_brewer}};
+  \code{\link{scale_colour_distiller}},
+  \code{\link{scale_fill_brewer}},
+  \code{\link{scale_fill_distiller}};
   \code{\link{scale_color_discrete}},
   \code{\link{scale_color_hue}},
   \code{\link{scale_colour_discrete}},

man/scale_gradient2.Rd

@@ -87,8 +87,11 @@ p + scale_fill_gradient2("fill")
 }
 \seealso{
 Other colour scales: \code{\link{scale_color_brewer}},
+  \code{\link{scale_color_distiller}},
   \code{\link{scale_colour_brewer}},
-  \code{\link{scale_fill_brewer}};
+  \code{\link{scale_colour_distiller}},
+  \code{\link{scale_fill_brewer}},
+  \code{\link{scale_fill_distiller}};
   \code{\link{scale_color_continuous}},
   \code{\link{scale_color_gradient}},
   \code{\link{scale_colour_continuous}},

man/scale_gradientn.Rd

@@ -68,8 +68,11 @@ d + scale_colour_gradientn(colours = terrain.colors(10),
 }
 \seealso{
 Other colour scales: \code{\link{scale_color_brewer}},
+  \code{\link{scale_color_distiller}},
   \code{\link{scale_colour_brewer}},
-  \code{\link{scale_fill_brewer}};
+  \code{\link{scale_colour_distiller}},
+  \code{\link{scale_fill_brewer}},
+  \code{\link{scale_fill_distiller}};
   \code{\link{scale_color_continuous}},
   \code{\link{scale_color_gradient}},
   \code{\link{scale_colour_continuous}},

man/scale_grey.Rd

@@ -41,8 +41,11 @@ qplot(mpg, wt, data = mtcars, colour = miss) +
 }
 \seealso{
 Other colour scales: \code{\link{scale_color_brewer}},
+  \code{\link{scale_color_distiller}},
   \code{\link{scale_colour_brewer}},
-  \code{\link{scale_fill_brewer}};
+  \code{\link{scale_colour_distiller}},
+  \code{\link{scale_fill_brewer}},
+  \code{\link{scale_fill_distiller}};
   \code{\link{scale_color_continuous}},
   \code{\link{scale_color_gradient}},
   \code{\link{scale_colour_continuous}},

man/scale_hue.Rd

@@ -86,8 +86,11 @@ qplot(mpg, wt, data = mtcars, colour = miss) +
 }
 \seealso{
 Other colour scales: \code{\link{scale_color_brewer}},
+  \code{\link{scale_color_distiller}},
   \code{\link{scale_colour_brewer}},
-  \code{\link{scale_fill_brewer}};
+  \code{\link{scale_colour_distiller}},
+  \code{\link{scale_fill_brewer}},
+  \code{\link{scale_fill_distiller}};
   \code{\link{scale_color_continuous}},
   \code{\link{scale_color_gradient}},
   \code{\link{scale_colour_continuous}},