add examples to functions

DESCRIPTION

@@ -1,11 +1,14 @@
 Package: ggspatial
 Type: Package
 Title: Spatial Data Framework for ggplot2
-Version: 0.3.0.9000
-Author: Dewey Dunnington <[email protected]>
+Version: 1.0.0
+Authors@R: c(
+    person("Dewey", "Dunnington", , "[email protected]", c("aut", "cre")),
+    person("Brent", "Thorne", role = "ctb")
+  )
 Maintainer: Dewey Dunnington <[email protected]>
 Description: Spatial data plus the power of the ggplot2 framework means easier mapping when input 
-  data are already in the form of Spatial* objects.
+  data are already in the form of spatial objects.
 License: GPL-3
 Depends:
     R (>= 2.10),
@@ -32,6 +35,7 @@ Suggests:
     testthat,
     dplyr,
     withr,
+    ggrepel,
     covr
 URL: https://github.com/paleolimbot/ggspatial
 BugReports: https://github.com/paleolimbot/ggspatial/issues

NAMESPACE

@@ -76,7 +76,6 @@ export(stat_spatial_identity)
 export(xy_transform)
 importFrom(ggplot2,aes)
 importFrom(ggplot2,fortify)
-importFrom(ggplot2,waiver)
 importFrom(grid,makeContent)
 importFrom(grid,unit)
 importFrom(sf,st_zm)

R/geom-osm.R → R/annotation-map-tile.R

@@ -16,6 +16,26 @@
 #' @return A ggplot2 layer
 #' @export
 #'
+#' @examples
+#' load_longlake_data()
+#'
+#' ggplot() +
+#'   annotation_map_tile(zoom = 13, cachedir = system.file("rosm.cache", package = "ggspatial")) +
+#'   geom_sf(data = longlake_waterdf, fill = NA, col = "grey50")
+#'
+#' ggplot() +
+#'   annotation_map_tile(
+#'     data = tibble::tibble(
+#'       type = c("osm", "stamenbw", "cartolight", "cartodark"),
+#'       zoom = 13
+#'     ),
+#'     cachedir = system.file("rosm.cache", package = "ggspatial"),
+#'     mapping = aes(type = type, zoom = zoom)
+#'   ) +
+#'   geom_sf(data = longlake_waterdf, fill = NA, col = "grey50") +
+#'   coord_sf(crs = 3857) +
+#'   facet_wrap(~type)
+#'
 annotation_map_tile <- function(type = "osm", zoom = NULL, zoomin = -2,
                                 forcedownload = FALSE, cachedir = NULL,
                                 progress = c("text", "none"), quiet = TRUE,

R/annotation-north-arrow.R

@@ -15,6 +15,24 @@
 #' @export
 #' @importFrom grid unit
 #'
+#' @examples
+#'
+#' cities <- data.frame(
+#'   x = c(-63.58595, 116.41214),
+#'   y = c(44.64862, 40.19063),
+#'   city = c("Halifax", "Beijing")
+#' )
+#'
+#' ggplot(cities) +
+#'   geom_spatial_point(aes(x, y), crs = 4326) +
+#'   annotation_north_arrow(which_north = "true") +
+#'   coord_sf(crs = 3995)
+#'
+#' ggplot(cities) +
+#'   geom_spatial_point(aes(x, y), crs = 4326) +
+#'   annotation_north_arrow(which_north = "grid") +
+#'   coord_sf(crs = 3995)
+#'
 annotation_north_arrow <- function(height = unit(1.5, "cm"), width = unit(1.5, "cm"),
                                    pad_x = unit(0.25, "cm"), pad_y = unit(0.25, "cm"),
                                    which_north = c("grid", "true"), rotation = NULL,
@@ -182,10 +200,13 @@ true_north <- function(x, y, crs, delta_crs = 0.1, delta_lat = 0.1) {
 #' @examples
 #' grid::grid.newpage()
 #' grid::grid.draw(north_arrow_orienteering())
+#'
 #' grid::grid.newpage()
 #' grid::grid.draw(north_arrow_fancy_orienteering())
+#'
 #' grid::grid.newpage()
 #' grid::grid.draw(north_arrow_minimal())
+#'
 #' grid::grid.newpage()
 #' grid::grid.draw(north_arrow_nautical())
 #'

R/annotation-scale.R

@@ -20,6 +20,18 @@
 #'
 #' @importFrom grid unit
 #'
+#' @examples
+#' cities <- data.frame(
+#'   x = c(-63.58595, 116.41214),
+#'   y = c(44.64862, 40.19063),
+#'   city = c("Halifax", "Beijing")
+#' )
+#'
+#' ggplot(cities) +
+#'   geom_spatial_point(aes(x, y), crs = 4326) +
+#'   annotation_scale() +
+#'   coord_sf(crs = 3995)
+#'
 annotation_scale <- function(plot_unit = NULL, width_hint = 0.25, unit_category = c("metric", "imperial"),
                              style = c("bar", "ticks"),
                              location = c("bl", "br", "tr", "tl"),

R/df-spatial.R

@@ -7,6 +7,12 @@
 #' @return A tibble with coordinates as .x and .y, and features as .feature
 #' @export
 #'
+#' @examples
+#' load_longlake_data()
+#' df_spatial(longlake_osm)
+#' df_spatial(longlake_depthdf)
+#' df_spatial(as(longlake_depthdf, "Spatial"))
+#'
 df_spatial <- function(x, ...) {
   UseMethod("df_spatial")
 }

R/geom-polypath.R

@@ -27,7 +27,7 @@
 #'
 #' @examples
 #' load_longlake_data()
-#' ggplot(spatial_fortify(longlake_waterdf), aes(.long, .lat, group = .group)) +
+#' ggplot(df_spatial(longlake_waterdf), aes(x, y, group = piece_id)) +
 #'   geom_polypath()
 #'
 geom_polypath <- function (mapping = NULL, data = NULL, stat = "identity", position = "identity",

R/geom-spatial.R

@@ -4,8 +4,8 @@
 #' These layers are much like their counterparts, \link[ggplot2]{stat_identity},
 #' \link[ggplot2]{geom_point}, \link[ggplot2]{geom_path},
 #' and \link[ggplot2]{geom_polygon}, except they have a \code{crs} argument that
-#' ensures they are projected when using \link[ggplot2]{coord_sf}. Stats are applied the x and y coordinates
-#' have been transformed.
+#' ensures they are projected when using \link[ggplot2]{coord_sf}. Stats are applied to the x and y coordinates
+#' that have been transformed.
 #'
 #' @param mapping An aesthetic mapping created with \link[ggplot2]{aes}.
 #' @param data A data frame or other object, coerced to a data.frame by \link[ggplot2]{fortify}.
@@ -20,6 +20,19 @@
 #' @return A ggplot2 layer.
 #' @export
 #'
+#' @examples
+#' cities <- data.frame(
+#'   x = c(-63.58595, 116.41214, 0),
+#'   y = c(44.64862, 40.19063, 89.9),
+#'   city = c("Halifax", "Beijing", "North Pole")
+#' )
+#'
+#' library(ggrepel)
+#' ggplot(cities, aes(x, y)) +
+#'   geom_spatial_point(crs = 4326) +
+#'   stat_spatial_identity(aes(label = city), geom = "label_repel") +
+#'   coord_sf(crs = 3857)
+#'
 stat_spatial_identity <- function(
   mapping = NULL, data = NULL, crs = NULL, geom = "point",
   position = "identity", ..., show.legend = NA, inherit.aes = TRUE

R/layer-spatial-raster.R

@@ -16,7 +16,10 @@
 #' @return A ggplot2 layer
 #' @export
 #'
-#' @importFrom ggplot2 waiver
+#' @examples
+#' load_longlake_data()
+#' ggplot() + layer_spatial(longlake_osm)
+#' ggplot() + layer_spatial(longlake_depth_raster) + scale_fill_continuous(na.value = NA)
 #'
 layer_spatial.Raster <- function(data, mapping = NULL, interpolate = TRUE, is_annotation = FALSE,
                                  lazy = FALSE, dpi = 150, ...) {

R/layer-spatial.R

@@ -11,6 +11,28 @@
 #' @export
 #' @importFrom ggplot2 aes
 #'
+#' @examples
+#' load_longlake_data()
+#'
+#' ggplot() +
+#'
+#'   # annotation_spatial() layers don't train the scales, so data stays central
+#'   annotation_spatial(longlake_roadsdf, size = 2, col = "black") +
+#'   annotation_spatial(longlake_roadsdf, size = 1.6, col = "white") +
+#'
+#'   # raster layers train scales and get projected automatically
+#'   layer_spatial(longlake_depth_raster, aes(alpha = stat(band1)), fill = "darkblue") +
+#'   scale_alpha_continuous(na.value = 0) +
+#'
+#'   # layer_spatial() layers train the scales
+#'   layer_spatial(longlake_depthdf, aes(col = DEPTH.M)) +
+#'
+#'   # spatial-aware automagic scale bar
+#'   annotation_scale(location = "tl") +
+#'
+#'   # spatial-aware automagic north arrow
+#'   annotation_north_arrow(location = "br", which_north = "true")
+#'
 layer_spatial <- function(data, mapping, ...) {
   UseMethod("layer_spatial")
 }

README.md

@@ -33,14 +33,17 @@ ggplot() +
   annotation_spatial(longlake_roadsdf, size = 1.6, col = "white") +
 
   # raster layers train scales and get projected automatically
-  layer_spatial(longlake_depth_raster, aes(fill = NULL, alpha = stat(band1)), fill = "darkblue") +
+  layer_spatial(longlake_depth_raster, aes(alpha = stat(band1)), fill = "darkblue") +
   scale_alpha_continuous(na.value = 0) +
 
   # layer_spatial trains the scales
   layer_spatial(longlake_depthdf, aes(col = DEPTH.M)) +
 
   # spatial-aware automagic scale bar
-  annotation_scale(location = "tl")
+  annotation_scale(location = "tl") +
+
+  # spatial-aware automagic north arrow
+  annotation_north_arrow(location = "br", which_north = "true")
 ```
 
 ![](README_files/figure-markdown_github/fig-layer-spatial-sf-1.png)

README.rmd

@@ -38,12 +38,15 @@ ggplot() +
   annotation_spatial(longlake_roadsdf, size = 1.6, col = "white") +
 
   # raster layers train scales and get projected automatically
-  layer_spatial(longlake_depth_raster, aes(fill = NULL, alpha = stat(band1)), fill = "darkblue") +
+  layer_spatial(longlake_depth_raster, aes(alpha = stat(band1)), fill = "darkblue") +
   scale_alpha_continuous(na.value = 0) +
   
   # layer_spatial trains the scales
   layer_spatial(longlake_depthdf, aes(col = DEPTH.M)) +
   
   # spatial-aware automagic scale bar
-  annotation_scale(location = "tl")
+  annotation_scale(location = "tl") +
+
+  # spatial-aware automagic north arrow
+  annotation_north_arrow(location = "br", which_north = "true")
 ```