tidyterra

Because tidyterra acts as a user-friendly wrapper around terra to provide tidyverse-style verbs, there is a performance cost compared to using terra directly.

Recommendation:

• Use terra directly for maximum speed, especially with very large datasets.
• Use tidyterra when your raster has fewer than 10,000,000 data slots. A good rule of thumb is: terra::ncell(your_rast) * terra::nlyr(your_rast) < 1e7.

When plotting rasters, tidyterra performs automatic resampling (similar to terra::plot()). You can control this behavior using the maxcell argument.

The tidyterra package provides tidyverse methods for terra objects. The implementation logic differs based on the object type:

• SpatVector: Methods use terra::as.data.frame() coercion. Each row corresponds to a geometry, and columns correspond to the attributes of that geometry.
• SpatRaster: Methods treat layers as columns of a tibble and cells as rows. For example, dplyr::select(a_spatraster, 1) selects the first layer.

Implemented methods generally return the same type of object as the input (e.g., a SpatRaster remains a SpatRaster), unless the method is explicitly designed to return a different type, such as as_tibble() returning a tibble.

tidyterra provides tidyverse-style methods for terra objects. The implementation logic differs based on the object type:

• SpatVector: Methods use terra::as.data.frame() coercion. Each row represents a geometry, and columns represent attributes.
• SpatRaster: Methods treat layers as columns of a tibble and cells as rows. For example, dplyr::select(a_spatraster, 1) selects the first layer.

Implemented methods generally return the same type of object as the input (e.g., as_tibble() returns a tibble), unless the method is explicitly designed to change the type.

Performance Note

tidyterra is a wrapper around terra, which introduces a performance cost. For very large datasets, use terra directly. A rule of thumb is to use tidyterra if your raster has fewer than 10,000,000 data slots (terra::ncell(your_rast) * terra::nlyr(your_rast) < 1e7).

You can install tidyterra from CRAN using the standard install.packages() function. If you want to use the development version, you can use pak or install it via r-universe.

Install from CRAN

install.packages("tidyterra")

Install development version via pak

# install.packages("pak")
pak::pak("dieghernan/tidyterra")

Install via r-universe

install.packages(
  "tidyterra",
  repos = c(
    "https://dieghernan.r-universe.dev",
    "https://cloud.r-project.org"
  )
)

You can manipulate SpatVector objects using tidyverse-style verbs like mutate() and then plot them directly using autoplot(). This integrates seamlessly with ggplot2 scales and labels.

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

# Manipulate SpatVector and plot
vect(system.file("ex/lux.shp", package = "terra")) |>
  mutate(pop_dens = POP / AREA) |>
  autoplot(aes(fill = pop_dens)) +
  scale_fill_whitebox_c(palette = "pi_y_g") +
  labs(
    fill = "population per km2",
    title = "Population density of Luxembourg",
    subtitle = "By canton"
  )

The tidyterra package provides specialized scales for mapping:

1. Whitebox scales: Use scale_fill_whitebox_c() for continuous data. It supports various palettes (e.g., "muted", "deep") and allows for custom labels and guides.
2. Hypsometric scales: Use scale_fill_hypso_tint_c() to create maps with hypsometric tints (elevation-based color schemes). This is ideal for topographic maps.

Example of a hypsometric map:

# Hypsometric map example
ها <- rast(system.file("extdata/asia.tif", package = "tidyterra"))

ggplot() +
  geom_spatraster(data = asia) +
  scale_fill_hypso_tint_c(
    palette = "gmt_globe",
    labels = scales::label_number(),
    breaks = c(-10000, -5000, 0, 2000, 5000, 8000),
    guide = guide_colorbar(reverse = TRUE)
  ) +
  labs(fill = "elevation (m)", title = "Hypsometric map of Asia")

Use geom_spatraster() to plot SpatRaster objects within a ggplot2 workflow. You can facet across multiple layers using facet_wrap(~lyr, ...) to visualize different time steps or variables in a single plot.

To plot RGB SpatRaster objects (like map tiles), use geom_spatraster_rgb() instead.

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

# Load a SpatRaster
rastertemp <- rast(system.file("extdata/cyl_temp.tif", package = "tidyterra"))

# Plotting all layers faceted
ggplot() +
  geom_spatraster(data = rastertemp) +
  facet_wrap(~lyr, ncol = 2)

tidyterra allows you to use tidyverse verbs on SpatVector objects and plot them using ggplot2 via autoplot() or geom_spatvector().

Example: Mutate and Plot SpatVector

library(tidyterra)
library(terra)

# Create a SpatVector, mutate attributes, and plot
vect(system.file("ex/lux.shp", package = "terra")) |>
  mutate(pop_dens = POP / AREA) |>
  glimpse() |>
  autoplot(aes(fill = pop_dens)) +
  scale_fill_whitebox_c(palette = "pi_y_g")

tidyterra implements a wide range of tidyverse methods for both SpatVector and SpatRaster objects.