add helper functions for ggplot2 (#5)

The functions scale_color_cmocean, scale_colour_cmocean, scale_fill_cmocean
are supposed to mimic similarly-named functions from the viridis package.

DESCRIPTION

@@ -5,7 +5,7 @@ Title: Beautiful Colour Maps for Oceanography
 Authors@R: c(person('Kristen', 'Thyng', email = '[email protected]', role = 'aut'), person('Clark', 'Richards', email = '[email protected]', role = 'ctb'), person('Ivan', 'Krylov', email = '[email protected]', role = 'cre'))
 Imports: grDevices
 Depends: R (>= 3.0.0)
-Suggests: knitr, rmarkdown
+Suggests: knitr, rmarkdown, ggplot2
 LazyData: no
 Description: Perceptually uniform palettes for commonly used
 	variables in oceanography as functions taking an integer

NAMESPACE

@@ -1,2 +1,2 @@
 importFrom(grDevices, colorRampPalette, rgb)
-export(cmocean)
+export(cmocean, scale_colour_cmocean, scale_color_cmocean, scale_fill_cmocean)

R/ggplot2.R

@@ -0,0 +1,47 @@
+scale_fill_cmocean <- function(
+	..., alpha = 1, start = 0, end = 1, direction = 1,
+	discrete = FALSE, name = 'thermal'
+) {
+	loadNamespace('ggplot2')
+	if (discrete) {
+		ggplot2::discrete_scale(
+			'fill', 'cmocean', cmocean(
+				name = name, start = start, end = end,
+				direction = direction, alpha = alpha
+			),
+			...
+		)
+	} else {
+		ggplot2::scale_fill_gradientn(
+			colours = cmocean(
+				name = name, start = start, end = end,
+				direction = direction, alpha = alpha
+			)(256),
+			...
+		)
+	}
+}
+
+scale_colour_cmocean <- scale_color_cmocean <- function(
+	..., alpha = 1, start = 0, end = 1, direction = 1,
+	discrete = FALSE, name = 'thermal'
+) {
+	loadNamespace('ggplot2')
+	if (discrete) {
+		ggplot2::discrete_scale(
+			'colour', 'cmocean', cmocean(
+				name = name, start = start, end = end,
+				direction = direction, alpha = alpha
+			),
+			...
+		)
+	} else {
+		ggplot2::scale_color_gradientn(
+			colours = cmocean(
+				name = name, start = start, end = end,
+				direction = direction, alpha = alpha
+			)(256),
+			...
+		)
+	}
+}

man/ggplot2.Rd

@@ -0,0 +1,68 @@
+\name{scale_colour_cmocean}
+\alias{scale_colour_cmocean}
+\alias{scale_color_cmocean}
+\alias{scale_fill_cmocean}
+\title{cmocean colour scales for ggplot2}
+\description{
+  Helper functions to allow the colour scale to be used effectively
+  in \pkg{ggplot2}.
+}
+\usage{
+  scale_color_cmocean(
+    \dots, alpha = 1, start = 0, end = 1, direction = 1,
+    discrete = FALSE, name = "thermal"
+  )
+  scale_colour_cmocean(
+    \dots, alpha = 1, start = 0, end = 1, direction = 1,
+    discrete = FALSE, name = "thermal"
+  )
+  scale_fill_cmocean(
+    \dots, alpha = 1, start = 0, end = 1, direction = 1,
+    discrete = FALSE, name = "thermal"
+  )
+}
+\arguments{
+  \item{\dots}{
+    parameters to \pkg{ggplot2} functions \code{discrete_scale} or
+    \code{scale_fill_gradientn}.
+  }
+  \item{alpha}{
+    opacity of the palette in the range \eqn{[0, 1]}.
+}
+  \item{start}{
+    fraction of the colormap to clip from its start, in \eqn{[0, 1]}.
+}
+  \item{end}{
+    fraction of the colormap where it should stop, in \eqn{[0, 1]};
+    \eqn{\mathtt{start} < \mathtt{end}}{start < end}.
+}
+  \item{direction}{
+    set to \code{-1} to reverse the palette.
+}
+  \item{discrete}{
+    set to \code{TRUE} to generate a discrete palette instead of a
+    continuous one.
+}
+  \item{name}{
+    the name of one of the available cmocean colormaps, see
+    \code{\link{cmocean}} for the full list.
+   }
+}
+\value{
+  A \code{ggplot} object to be added to other \code{ggplot} objects.
+}
+\author{
+  As requested by Ilja Kocken in \url{https://github.com/aitap/cmocean/issues/5}.
+}
+
+\seealso{
+  \code{\link{cmocean}}
+}
+\examples{if (require('ggplot2')) {
+  dat <- data.frame(
+    a = 1:10, b = 11:20, c = stats::rnorm(10)
+  )
+
+  ggplot(dat, aes(x = a, y = b, fill = c)) +
+  geom_raster() + scale_fill_cmocean()
+}}