tidyterra FAQs

This document is a compendium of frequently asked questions about using the tidyterra package and its answers, primarily focused on the integration of terra and ggplot2. You can ask for help or search previous questions using the following links.

You can also ask in Stack Overflow using the tag tidyterra.

Report a bug [link].
Ask a question [link].

Example data

Source

This article uses a sample of LiDAR for Scotland Phase 5 - DSM provided by The Scottish Remote Sensing Portal. This data is made available under the Open Government Licence v3.

About the file

The file holyroodpark.tif represents the DEM¹ of Holyrood Park, Edinburgh (Scotland), including Arthur’s Seat, an extinct volcano, pretty much as the famous Maungawhau / Mount Eden volcano represented in datasets::volcano.

The original file has been cropped and downsampled for demo purposes. holyroodpark.tif is available online in the data-raw folder at https://github.com/dieghernan/tidyterra/tree/main/data-raw.

`NA` values are shown in gray

This is the default behavior of ggplot2. tidyterra color scales (i.e., scale_fill_whitebox_c(), etc.) have na.value = "transparent" by default, which prevents NA values from being filled².

library(terra)
library(tidyterra)
library(ggplot2)

# Get raster data from Holyrood Park, Edinburgh.
holyrood <- "holyroodpark.tif"

r <- holyrood |>
  rast() |>
  filter(elevation > 80 & elevation < 180)

# Default
def <- ggplot() +
  geom_spatraster(data = r)

def +
  labs(
    title = "Default in ggplot2",
    subtitle = "NA values in gray"
  )

# Modify with scales
def +
  scale_fill_continuous(na.value = "transparent") +
  labs(
    title = "Default colors in ggplot2",
    subtitle = "But NA values are not plotted"
  )

# Use a different scale provided by ggplot2
def +
  scale_fill_viridis_c(na.value = "orange") +
  labs(
    title = "Use any ggplot2 fill scale",
    subtitle = "Note that na.value = 'orange'"
  )

Labeling contours

Use geom_spatraster_contour_text() :

library(terra)
library(tidyterra)
library(ggplot2)

holyrood <- "holyroodpark.tif"

r <- rast(holyrood)

ggplot() +
  geom_spatraster_contour_text(data = r) +
  labs(title = "Labeling contours")

# With options and aes.

# Use a labeler function so only selected breaks are labeled.
labeller <- function(labs) {
  # Must return a function.
  function(x) {
    x[!x %in% labs] <- NA
    scales::label_comma(suffix = " m.")(x)
  }
}

# Common labels across ggplot.

labs <- c(100, 140, 180, 220)

ggplot(r) +
  geom_spatraster_contour_text(
    data = r,
    aes(
      linewidth = after_stat(level),
      size = after_stat(level),
      color = after_stat(level)
    ),
    breaks = seq(100, 250, 10),
    # Label selected isolines.
    label_format = labeller(labs = labs),
    family = "mono",
    fontface = "bold"
  ) +
  scale_linewidth_continuous(range = c(0.1, 0.5), breaks = labs) +
  scale_color_gradient(low = "grey50", high = "grey10", breaks = labs) +
  scale_size_continuous(range = c(2, 3), breaks = labs) +
  # Integrate scales.
  guides(
    linewidth = guide_legend("meters"),
    size = guide_legend("meters"),
    color = guide_legend("meters")
  ) +
  # Theme and titles.
  theme_bw() +
  theme(text = element_text(family = "mono")) +
  labs(
    title = "Labeling contours",
    subtitle = "With options: b/w plot"
  )

Other alternatives

With fortify.SpatRaster(), you can use your SpatRaster directly with the metR package (see Hexagonal grids and other geoms). Use bins, binwidth or breaks to align both labels and lines:

library(metR)
br <- seq(100, 250, 10)
labs <- c(100, 140, 180, 220)

# Replicate the previous map with tidyterra and metR.
ggplot(r, aes(x, y)) +
  geom_spatraster_contour(
    data = r,
    aes(
      linewidth = after_stat(level),
      color = after_stat(level)
    ),
    breaks = br,
    # Do not inherit fortified aesthetics.
    inherit.aes = FALSE
  ) +
  geom_text_contour(
    aes(
      z = elevation,
      color = after_stat(level),
      size = after_stat(level)
    ),
    breaks = br,
    # Text options
    check_overlap = TRUE,
    label.placer = label_placer_minmax(),
    stroke = 0.3,
    stroke.colour = "white",
    family = "mono",
    fontface = "bold",
    key_glyph = "path"
  ) +
  scale_linewidth_continuous(range = c(0.1, 0.5), breaks = labs) +
  scale_color_gradient(low = "grey50", high = "grey10", breaks = labs) +
  scale_size_continuous(range = c(2, 3), breaks = labs) +
  # Integrate scales.
  guides(
    linewidth = guide_legend("meters"),
    size = guide_legend("meters"),
    color = guide_legend("meters")
  ) +
  # Theme and titles.
  theme_bw() +
  theme(text = element_text(family = "mono")) +
  labs(
    title = "Labeling contours",
    subtitle = "tidyterra and metR: b/w plot",
    x = "",
    y = ""
  )

Figure 3: Alternative (metR): Contour labeling combining tidyterra and metR packages with customized styling.

Using a different color scale

Since tidyterra builds on ggplot2, please refer to ggplot2 documentation on scales:

library(terra)
library(tidyterra)
library(ggplot2)

holyrood <- "holyroodpark.tif"

r <- rast(holyrood)

# Hillshade with gray colors.
slope <- terrain(r, "slope", unit = "radians")
aspect <- terrain(r, "aspect", unit = "radians")
hill <- shade(slope, aspect, 10, 340)

ggplot() +
  geom_spatraster(data = hill, show.legend = FALSE) +
  # Use a grayscale palette.
  scale_fill_gradientn(
    colours = grey(0:100 / 100),
    na.value = "transparent"
  ) +
  labs(title = "A hillshade plot with gray colors")

Figure 4: Hillshade visualization using grayscale colors to enhance terrain relief.

Can I change the default palette of my maps?

Yes, use options("ggplot2.continuous.fill") to modify the default colors in your session.

library(terra)
library(tidyterra)
library(ggplot2)

holyrood <- "holyroodpark.tif"

r <- rast(holyrood)

p <- ggplot() +
  geom_spatraster(data = r)

# Set options.
tmp <- getOption("ggplot2.continuous.fill") # store current setting
options(ggplot2.continuous.fill = scale_fill_grass_c)

p

# Restore the previous setting.
options(ggplot2.continuous.fill = tmp)

p

(a) Use of new default palette via options.

My map tiles are blurry

Blurriness is typically related to the tile source rather than the package. Most base tiles are provided in EPSG:3857, so verify that your tile uses this CRS rather than a different one. If your tile is not in EPSG:3857, it has likely been reprojected, which involves resampling and causes blurriness. Also, modify the maxcell argument to avoid resampling and ensure the ggplot2 map uses EPSG:3857 with ggplot2::coord_sf(crs = 3857):

library(terra)
library(tidyterra)
library(ggplot2)
library(sf)
library(maptiles)

# Get a tile from a point in sf format.
p <- st_point(c(-3.166011, 55.945235)) |>
  st_sfc(crs = 4326) |>
  st_buffer(500)

tile1 <- get_tiles(
  p,
  provider = "OpenStreetMap",
  zoom = 14,
  cachedir = ".",
  crop = TRUE
)

ggplot() +
  geom_spatraster_rgb(data = tile1) +
  labs(title = "CRS EPSG:4326") +
  theme_void()

st_crs(tile1)$epsg
#> [1] 4326

# The tile was in EPSG:4326.

# Get the tile in EPSG:3857.
p2 <- st_transform(p, 3857)

tile2 <- get_tiles(
  p2,
  provider = "OpenStreetMap",
  zoom = 14,
  cachedir = ".",
  crop = TRUE
)

st_crs(tile2)$epsg
#> [1] 3857

# Now the tile is EPSG:3857.

ggplot() +
  geom_spatraster_rgb(data = tile2, maxcell = Inf) +
  # Force the CRS to EPSG:3857.
  coord_sf(crs = 3857) +
  labs(title = "CRS EPSG:3857") +
  theme_void()

(a) Plot with resampled raster (EPSG:4326).

Avoid degree labels on axes

This is a ggplot2 default behavior, but you can modify it using the ggplot2::coord_sf(datum) argument:

library(terra)
library(tidyterra)
library(ggplot2)
library(sf)

holyrood <- "holyroodpark.tif"

r <- rast(holyrood)

ggplot() +
  geom_spatraster(data = r) +
  labs(
    title = "Axis auto-converted to lon/lat",
    subtitle = paste("But SpatRaster is EPSG:", st_crs(r)$epsg)
  )

# Use datum.

ggplot() +
  geom_spatraster(data = r) +
  coord_sf(datum = pull_crs(r)) +
  labs(
    title = "Axis in the units of the SpatRaster",
    subtitle = paste("EPSG:", st_crs(r)$epsg)
  )

Modify the number of axis breaks

Of course. Use the scales package:

library(terra)
library(tidyterra)
library(ggplot2)
library(sf)

holyrood <- "holyroodpark.tif"

r <- rast(holyrood)

ggplot() +
  geom_spatraster(data = r) +
  labs(title = "Default axis breaks")

# Modify breaks on x and y.
ggplot() +
  geom_spatraster(data = r) +
  scale_y_continuous(breaks = scales::breaks_extended(n = 5)) +
  scale_x_continuous(breaks = scales::breaks_extended(n = 5)) +
  labs(title = "Three breaks on x and y axes with scales::breaks_extended()")

Plotting a `SpatRaster` with color tables

Note

We omitted the legends in this section’s figures to improve readability.

tidyterra provides several methods for handling SpatRaster objects with color tables. This example uses clc_edinburgh.tif, available online in the data-raw folder, which contains data from the Corine Land Cover Dataset (2018) for Edinburgh³.

library(terra)
library(tidyterra)
library(ggplot2)

# Get a SpatRaster with a color table.
r_coltab <- rast("clc_edinburgh.tif")

has.colors(r_coltab)
#> [1] TRUE

r_coltab
#> class       : SpatRaster
#> size        : 196, 311, 1  (nrow, ncol, nlyr)
#> resolution  : 178.8719, 177.9949  (x, y)
#> extent      : -380397.3, -324768.1, 7533021, 7567908  (xmin, xmax, ymin, ymax)
#> coord. ref. : WGS 84 / Pseudo-Mercator (EPSG:3857)
#> source      : clc_edinburgh.tif
#> color table : 1
#> categories  : label
#> name        :                   label
#> min value   : Continuous urban fabric
#> max value   :           Sea and ocean

# Native handling by the terra package.
plot(r_coltab, legend = FALSE)

Figure 9: Color tables: native plot with the terra package.

# Autoplot method.
autoplot(r_coltab, maxcell = Inf, show.legend = FALSE) +
  labs(title = "autoplot method")

# geom_spatraster method.
ggplot() +
  geom_spatraster(data = r_coltab, maxcell = Inf, show.legend = FALSE) +
  labs(title = "geom_spatraster method")

# scale_fill_coltab method.
ggplot() +
  geom_spatraster(
    data = r_coltab,
    use_coltab = FALSE,
    maxcell = Inf,
    show.legend = FALSE
  ) +
  scale_fill_coltab(data = r_coltab) +
  labs(title = "scale_fill_coltab method")

# Extract named colors and use scale_fill_manual().
cols <- get_coltab_pal(r_coltab)

cols |> head()
#>                    Continuous urban fabric 
#>                                  "#E6004D" 
#>                 Discontinuous urban fabric 
#>                                  "#FF0000" 
#>             Industrial or commercial units 
#>                                  "#CC4DF2" 
#> Road and rail networks and associated land 
#>                                  "#CC0000" 
#>                                 Port areas 
#>                                  "#E6CCCC" 
#>                                   Airports 
#>                                  "#E6CCE6"

# Use the extracted colors.
ggplot() +
  geom_spatraster(
    data = r_coltab,
    use_coltab = FALSE,
    maxcell = Inf,
    show.legend = FALSE
  ) +
  scale_fill_manual(
    values = cols,
    na.value = "transparent",
    na.translate = FALSE
  ) +
  labs(title = "scale_fill_manual method")

Use with gganimate

Yes. Here is an example (thanks to @frzambra):

library(gganimate)
library(tidyterra)
library(geodata)
library(ggplot2)

temp <- worldclim_country("che", "tavg", path = ".")

che_cont <- gadm("che", level = 0, path = ".")

temp_m <- crop(temp, che_cont, mask = TRUE)
names(temp_m) <- month.name

anim <- ggplot() +
  geom_spatraster(data = temp_m) +
  scale_fill_viridis_c(
    option = "inferno",
    na.value = "transparent",
    labels = scales::label_number(suffix = "º C")
  ) +
  transition_manual(lyr) +
  theme_bw() +
  theme(
    axis.text = element_blank(),
    axis.ticks = element_blank()
  ) +
  labs(
    title = "Avg temp Switzerland: {current_frame}",
    fill = ""
  )

gganimate::animate(anim, duration = 12, device = "ragg_png")

Figure 11: Animation of average monthly temperatures.

North arrows and scale bar

tidyterra does not provide north arrows or scale bars directly for ggplot2 plots. However, you can use ggspatial functions (ggspatial::annotation_north_arrow() and ggspatial::annotation_scale()):

library(terra)
library(tidyterra)
library(ggplot2)
library(ggspatial)

holyrood <- "holyroodpark.tif"

r <- rast(holyrood)

autoplot(r) +
  annotation_north_arrow(
    which_north = TRUE,
    pad_x = unit(0.8, "npc"),
    pad_y = unit(0.75, "npc"),
    style = north_arrow_fancy_orienteering()
  ) +
  annotation_scale(
    height = unit(0.015, "npc"),
    width_hint = 0.5,
    pad_x = unit(0.07, "npc"),
    pad_y = unit(0.07, "npc"),
    text_cex = 0.8
  )

Figure 12: Map with north arrow (top right) and scale bar (bottom left) annotations added using ggspatial.

How to overlay a `SpatRaster` on an RGB tile

This is straightforward: use geom_spatraster_rgb() for the background tile, and then add your data layers on top:

library(terra)
library(tidyterra)
library(ggplot2)
library(sf)
# Get example data.
library(maptiles)
library(geodata)

# Area of interest.
aoi <- gadm(country = "CHE", path = ".", level = 0) |>
  project("EPSG:3857")

# Tile.
rgb_tile <- get_tiles(
  aoi,
  crop = TRUE,
  provider = "Esri.WorldShadedRelief",
  zoom = 8,
  project = FALSE,
  cachedir = "."
)

# Climate data (mean precipitation).
clim <- worldclim_country("CHE", var = "prec", path = ".") |>
  project(rgb_tile) |>
  mask(aoi) |>
  terra::mean()

# Labels.
cap_lab <- paste0(
  c(
    "Tiles © Esri - Source: Esri",
    "Data: © Copyright 2020-2022, WorldClim.org."
  ),
  collapse = "\n"
)
tit_lab <- "Average precipitation in Switzerland"

ggplot(aoi) +
  geom_spatraster_rgb(data = rgb_tile, alpha = 1) +
  geom_spatraster(data = clim) +
  geom_spatvector(fill = NA) +
  scale_fill_whitebox_c(
    palette = "deep",
    alpha = 0.5,
    labels = scales::label_number(suffix = " mm.")
  ) +
  coord_sf(expand = FALSE) +
  labs(
    title = tit_lab,
    subtitle = "With continuous overlay",
    fill = "Precipitation",
    caption = cap_lab
  )

Figure 13: Continuous precipitation data overlaid as semi-transparent layer on RGB satellite imagery.

You can create variations with binned legends and filled contours using geom_spatraster_contour_filled():

# Binned legend.
ggplot(aoi) +
  geom_spatraster_rgb(data = rgb_tile, alpha = 1) +
  geom_spatraster(data = clim) +
  geom_spatvector(fill = NA) +
  scale_fill_whitebox_b(
    palette = "deep",
    alpha = 0.5,
    n.breaks = 4,
    labels = scales::label_number(suffix = " mm.")
  ) +
  coord_sf(expand = FALSE) +
  labs(
    title = tit_lab,
    subtitle = "With overlay: binned legend",
    fill = "Precipitation",
    caption = cap_lab
  )

# Filled contour.
ggplot(aoi) +
  geom_spatraster_rgb(data = rgb_tile, alpha = 1) +
  geom_spatraster_contour_filled(data = clim, bins = 4) +
  geom_spatvector(fill = NA) +
  coord_sf(expand = FALSE) +
  scale_fill_whitebox_d(
    palette = "deep",
    alpha = 0.5,
    guide = guide_legend(reverse = TRUE)
  ) +
  labs(
    title = tit_lab,
    subtitle = "With overlay and filled contour",
    fill = "Precipitation (mm)",
    caption = cap_lab
  )

Hexagonal grids (and other `geoms`)

While SpatRaster cells are inherently rectangular, you can create plots with hexagonal cells using fortify.SpatRaster() and stat_summary_hex(). The final plot requires coordinate adjustment with coord_sf():

library(terra)
library(tidyterra)
library(ggplot2)

holyrood <- "holyroodpark.tif"

r <- rast(holyrood)

# With a hexagonal grid.
ggplot(r, aes(x, y, z = elevation)) +
  stat_summary_hex(
    fun = mean,
    color = NA,
    linewidth = 0,
    # Bin size determines the number of cells displayed.
    bins = 30
  ) +
  coord_sf(crs = pull_crs(r)) +
  labs(
    title = "Hexagonal SpatRaster",
    subtitle = "Using fortify (implicit) and stat_summary_hex",
    x = NULL,
    y = NULL
  )

Figure 15: Elevation data aggregated and visualized as hexagonal grid cells.

Note that you do not need to call fortify.SpatRaster() directly because ggplot2 invokes it implicitly when you use ggplot(data = a_spatraster).

Thanks to this extension mechanism, you can use additional geoms and stats from ggplot2:

# Point plot.
ggplot(r, aes(x, y, z = elevation), maxcell = 1000) +
  geom_point(
    aes(size = elevation, alpha = elevation),
    fill = "darkblue",
    color = "grey50",
    shape = 21
  ) +
  coord_sf(crs = pull_crs(r)) +
  scale_radius(range = c(1, 5)) +
  scale_alpha(range = c(0.01, 1)) +
  labs(
    title = "SpatRaster as points",
    subtitle = "Using fortify (implicit)",
    x = NULL,
    y = NULL
  )

Figure 16: Elevation data represented as points with size and transparency scaled by elevation values.

tidyterra and metR

metR is a package that provides ggplot2 extensions, primarily for meteorological data visualization. As shown previously (see Labeling contours), you can combine both packages to create rich, complex plots.

# Load libraries and files.
library(terra)
library(tidyterra)
library(ggplot2)
library(metR)

holyrood <- "holyroodpark.tif"

r <- rast(holyrood)

ggplot(r, aes(x, y)) +
  geom_relief(aes(z = elevation)) +
  geom_spatraster(
    data = r,
    inherit.aes = FALSE,
    aes(alpha = after_stat(value))
  ) +
  scale_fill_cross_blended_c(breaks = seq(0, 250, 25)) +
  scale_alpha(range = c(1, 0.25)) +
  guides(alpha = "none", fill = guide_legend(reverse = TRUE)) +
  labs(x = "", y = "", title = "tidyterra and metR: reliefs")

Figure 17: Relief rendering combining tidyterra for raster visualization and metR for terrain relief representation.