Improve docs for geom_contour as discussed in issue #4324 (#4325)

* Improve docs for geom_contour as discussed in issue #4324

* Stop default testing of new example.

* Recommend interp instead of akima

Author: dmurdoch

DESCRIPTION

@@ -46,6 +46,7 @@ Suggests:
     ggplot2movies,
     hexbin,
     Hmisc,
+    interp,
     knitr,
     lattice,
     mapproj,

R/geom-contour.r

@@ -1,12 +1,16 @@
 #' 2D contours of a 3D surface
 #'
 #' ggplot2 can not draw true 3D surfaces, but you can use `geom_contour()`,
-#' `geom_contour_filled()`, and [geom_tile()] to visualise 3D surfaces in 2D.
-#' To specify a valid surface, the data must contain `x`, `y`, and `z` coordinates,
-#' and each unique combination of `x` and `y` can appear exactly once. Contouring
-#' tends to work best when `x` and `y` form a (roughly) evenly
-#' spaced grid. If your data is not evenly spaced, you may want to interpolate
-#' to a grid before visualising, see [geom_density_2d()].
+#' `geom_contour_filled()`, and [geom_tile()] to visualise 3D surfaces in 2D. To
+#' specify a valid surface, the data must contain `x`, `y`, and `z` coordinates,
+#' and each unique combination of `x` and `y` can appear at most once.
+#' Contouring requires that the points can be rearranged so that the `z` values
+#' form a matrix, with rows corresponding to unique `x` values, and columns
+#' corresponding to unique `y` values. Missing entries are allowed, but contouring
+#' will only be done on cells of the grid with all four `z` values present. If
+#' your data is irregular, you can interpolate to a grid before visualising
+#' using the [interp::interp()] function from the `interp` package
+#' (or one of the interpolating functions from the `akima` package.)
 #'
 #' @eval rd_aesthetics("geom", "contour")
 #' @eval rd_aesthetics("geom", "contour_filled")
@@ -15,9 +19,9 @@
 #' @inheritParams geom_path
 #' @param bins Number of contour bins. Overridden by `binwidth`.
 #' @param binwidth The width of the contour bins. Overridden by `breaks`.
-#' @param breaks Numeric vector to set the contour breaks.
-#'   Overrides `binwidth` and `bins`. By default, this is a vector of
-#'   length ten with [pretty()] breaks.
+#' @param breaks Numeric vector to set the contour breaks. Overrides `binwidth`
+#'   and `bins`. By default, this is a vector of length ten with [pretty()]
+#'   breaks.
 #' @seealso [geom_density_2d()]: 2d density contours
 #' @export
 #' @examples
@@ -47,6 +51,22 @@
 #' v + geom_contour(colour = "red")
 #' v + geom_raster(aes(fill = density)) +
 #'   geom_contour(colour = "white")
+#'
+#' # Irregular data
+#' if (requireNamespace("interp")) {
+#'   # Use a dataset from the interp package
+#'   data(franke, package = "interp")
+#'   origdata <- as.data.frame(interp::franke.data(1, 1, franke))
+#'   grid <- with(origdata, interp::interp(x, y, z))
+#'   griddf <- subset(data.frame(x = rep(grid$x, nrow(grid$z)),
+#'                               y = rep(grid$y, each = ncol(grid$z)),
+#'                               z = as.numeric(grid$z)),
+#'                    !is.na(z))
+#'   ggplot(griddf, aes(x, y, z = z)) +
+#'     geom_contour_filled() +
+#'     geom_point(data = origdata)
+#' } else
+#'   message("Irregular data requires the 'interp' package")
 #' }
 geom_contour <- function(mapping = NULL, data = NULL,
                          stat = "contour", position = "identity",