Skip to contents

Plot a raster with a stretched colour scale and boundary

Source: R/plot_raster.R
plot_raster.Rd

Maps x with ggplot2, clamping the colour scale to central quantiles of the values and overlaying a boundary polygon. Intended as a quick visual check of a harmonized or exported layer: whether the spatial pattern looks right, and whether the layer is clipped to the boundary it should be.

Usage

plot_raster(
  x,
  stretch = c(0.02, 0.98),
  col = NULL,
  boundary = "alberta",
  boundary_col = "grey20",
  boundary_lwd = 0.4,
  na_col = NA,
  main = NULL,
  legend_title = NULL,
  axes = FALSE,
  maxcell = 5e+05,
  ...
)

Arguments

x

A SpatRaster, or the path to a single raster file.

stretch

Numeric vector of two probabilities giving the quantiles the colour scale is clamped to. Default c(0.02, 0.98); values beyond them take the end colours. NULL uses the full value range, as does a layer whose two quantiles coincide.

col

Character vector of colours for the value scale. Defaults to a 256-step reversed "Hiroshige" ramp.

boundary

Polygon drawn over the raster: a SpatVector, an sf object, or one of the shortcuts accepted by mask_to_boundary(). Defaults to "alberta", the packaged provincial boundary; NULL draws no overlay.

boundary_col

Colour of the boundary outline. Default "grey20".

boundary_lwd

Width of the boundary outline, as ggplot2 linewidth. Default 0.4.

na_col

Fill for NA cells. Default NA, leaving them unpainted. Set to e.g. "firebrick2" to see which cells are missing.

main

Plot title. Defaults to the layer name for a single-layer raster, and to none for a facetted one, where the strips carry the names.

legend_title

Title for the fill legend. Default NULL, no title.

axes

Logical; draw coordinate axes. Default FALSE.

maxcell

Numeric; the raster is downsampled to this many cells before plotting. Default 5e5.

...

Additional arguments passed to ggplot2::geom_tile(), e.g. alpha.

Value

A ggplot object.

Details

The raster is downsampled to at most maxcell cells before plotting, so stretch limits and the drawn surface are approximations for large layers. Cells are drawn as tiles sized from the raster's own resolution, so a masked layer's gaps stay gaps. Multi-layer rasters are drawn as facets sharing one colour scale, stretched on the pooled values; pass a single layer (x[[1]]) when each layer needs its own scale.

Unprojected (longitude/latitude) rasters are given a latitude-corrected aspect ratio; projected rasters are drawn with equal axes.

The default colours are the "Hiroshige" palette from MetBrewer, reversed so low values are dark blue and high values red, and the default theme is theme_science_map(). Both are ordinary ggplot2 components, so either can be replaced by adding a new scale_fill_*() or theme to the returned plot.

See also

plot_hist() for the value distribution behind the map; raster_stats() for the same values as a table; theme_science_map() for the theme applied.

Examples

if (FALSE) { # \dontrun{
library(terra)
r <- get_layer("fab_dem")

plot_raster(r)                       # stretched, Alberta outline
plot_raster(r, stretch = NULL)       # full value range
plot_raster(r, na_col = "firebrick2")  # highlight missing cells
plot_raster(r, boundary = my_study_area)

# A ggplot object, so it composes and saves as one
p <- plot_raster(r, main = "FABDEM") +
  ggplot2::labs(caption = "1 km, EPSG:3400")
ggplot2::ggsave("2_pipeline/fab_dem.png", p,
                width = 9, height = 6, dpi = 200)
} # }