ggspatial R Package Documentation

ggspatial is a framework for interacting with spatial data using ggplot2 as a plotting backend. It extends ggplot2 to support spatial objects from the sf, sp, and raster packages. It leverages geom_sf() and coord_sf() for coordinate transformations, allowing you to layer spatial annotations, tiles, and rasters onto a standard ggplot object.

library(ggplot2)
library(ggspatial)

# Example workflow
ggplot() +
  annotation_map_tile(zoomin = -1) +
  annotation_spatial(your_sf_object, size = 2, col = "black") +
  layer_spatial(your_raster_object, aes(colour = after_stat(band1))) +
  annotation_scale(location = "tl") +
  annotation_north_arrow(location = "br", which_north = "true")

You can install the stable version of ggspatial from CRAN or install the development version directly from GitHub using the remotes package.

# Install stable version from CRAN
install.packages("ggspatial")

# Install development version from GitHub
install.packages("remotes") # if remotes isn't installed
remotes::install_github("paleolimbot/ggspatial")

Use layer_spatial() for spatial data frames (like sf objects) to ensure the scales are trained correctly based on the data's extent.

layer_spatial(longlake_depthdf, aes(fill = DEPTH_M))

The annotation_north_arrow() function adds a spatial-aware north arrow.

Arguments:

• location: Position of the arrow (e.g., "br" for bottom-right).
• which_north: Boolean indicating if it should point to true north.

annotation_north_arrow(location = "br", which_north = "true")

The annotation_spatial() function adds spatial layers (like lines or points) to a map. Note that annotation_spatial() layers do not 'train the scales', meaning they do not influence the coordinate system limits; the data remains central to the existing coordinate context provided by other layers.

# Example: adding road layers with different colors
annotation_spatial(longlake_roadsdf, size = 2, col = "black") +
annotation_spatial(longlake_roadsdf, size = 1.6, col = "white")

Use layer_spatial() to add raster package objects to your plot. Unlike annotation_spatial(), layer_spatial() layers do train the scales and get projected automatically. This makes them ideal for the primary data layer in your map.

# Adding a raster layer with color mapping
layer_spatial(longlake_depth_raster, aes(colour = after_stat(band1)))

# To make no-data values transparent, use scale_fill_viridis_c(na.value = NA)
scale_fill_viridis_c(na.value = NA)

Use annotation_map_tile() to load background map tiles from a tile source into your ggplot object. The zoomin parameter can be used to adjust the zoom level.

ggplot() +
  annotation_map_tile(zoomin = -1)

The annotation_scale() function adds a spatial-aware scale bar to your map. Use the location argument to specify where the scale bar should appear (e.g., "tl" for top-left, "br" for bottom-right).

annotation_scale(location = "tl")