date: "2023-07-18"
description: >-
An introduction to the `tidyterra` **R** package.
bibliography: paper.bib
link-citations: yes
editor_options:
markdown:
wrap: 80
tags:
- R
- CRAN
- spatial
- vector
- raster
- tidyverse
- terra
- ggplot2
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Using the tidyverse with terra objects: the tidyterra package}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
warning = FALSE,
message = FALSE,
out.width = "100%"
)
```
## Summary
`tidyterra` is an R [@r-project] package that allows manipulation of spatial
data objects as provided by the `terra` package [@R-terra], using the syntax of
several packages included in the tidyverse [@R-tidyverse], such as `dplyr`
[@R-dplyr], `tidyr` [@R-tidyr], or `tibble` [@R-tibble].
Furthermore, `tidyterra` extends the functionality of the `ggplot2` package
[@R-ggplot2] by providing additional geoms and stats [^1], as well as carefully
chosen scales and color palettes specifically designed for map production.
[^1]: The term "geoms" refers to geometric objects, and "stats" refers to
statistical transformations, following the naming conventions of `ggplot2`
`tidyterra` can manipulate the following classes of `terra` objects:
1. `SpatVector` objects, which represent vector data such as points, lines, or
polygon geometries.
2. `SpatRaster` objects, which represent raster data in the form of a grid
consisting of equally sized rectangles. Each rectangle can contain one or
more values.
The first stable version of `tidyterra` was included on CRAN on April 24, 2022,
and has been actively used by other packages (@R-ebvcube, @R-biomod2,
@R-inlabru, @R-rczechia, @R-sparrpowr) and cited in academic research and
publications (@bahlburg2023, @moraga2023, @Leonardi2023) ever since.
## Statement of need
The [tidyverse](https://www.tidyverse.org/) is a compilation of R packages that
share an underlying design philosophy, grammar, and data structures. The
packages within the tidyverse are widely used by R users for tidying,
transforming, and visualizing data.
The tidyverse is designed to work with tidy data (*"every column is a variable,
every row is an observation, every cell is a single value"*), represented in the
form of data frames or tibbles. However, it is possible to extend the
functionality of tidyverse packages to work with new R object classes by
registering the corresponding S3 methods [@wickham_s32019]. This means that
`dplyr::mutate()` can be adapted to work with any object of class `foo` by
creating the corresponding S3 method `mutate.foo()`.
While other popular packages designed for spatial data handling, such as `sf`
[@R-sf] or `stars` [@R-stars], already provide integration with the tidyverse as
part of their infrastructure, `terra` objects lack this integration natively.
Instead, `terra` offers a wide set of functions with their own syntax for
transforming and visualizing `SpatRaster` and `SpatVector` objects.
The `tidyterra` package was developed to address this integration gap. By
providing the corresponding S3 methods, data analysts can apply the same syntax
and functions they are already familiar with for rectangular data to the objects
provided by `terra.` This enables users who are not familiar with spatial data
analysis to approach this area more easily.
In addition, `tidyterra` also offers functions for plotting `terra` objects
using the `ggplot2` syntax. Although packages like `rasterVis` [@R-rastervis]
and `ggspatial` [@R-ggspatial] already include similar functionality for
`SpatRaster` objects, `tidyterra` functions also support `SpatVector` objects.
Furthermore, `tidyterra` allows users to create faceted maps for multi-layer
raster files and compute contour lines and contour-filled polygons.
Lastly, `tidyterra` provides a collection of color palettes specifically
designed for representing spatial phenomena [@whitebox]. Additionally, it
implements the cross-blended hypsometric tints described by
@Patterson_Jenny_2011.
### A note on performance
The development philosophy of `tidyterra` consists on adapting `terra` objects
to data frame-like structures by performing different data transformations, that
ultimately may impact in the performance of the package.
When working with large raster files (i.e. more than 10.000.000 cells), it is
recommended to use the native `terra` syntax, that is specifically designed for
handling this type of files.
Note also that when possible, the help page of each function of `tidyterra`
references its equivalent in `terra`.
## Example of use
`tidyterra` is available on
[CRAN](https://CRAN.R-project.org/package=tidyterra), so it can be easily
installed using the following commands in R:
```{r eval=FALSE}
install.packages("tidyterra")
```
The following example demonstrates how to manipulate a `SpatRaster` object using
the `dplyr` syntax. Additionally, it illustrates how to seamlessly plot a
`SpatRaster` object with `ggplot2` using the `geom_spatraster()` function:
```{r eval=FALSE}
library(tidyterra)
library(dplyr)
library(ggplot2)
library(scales) # Additional library for labels
# Temperatures in Castille and Leon (selected months)
rastertemp <- terra::rast(system.file("extdata/cyl_temp.tif",
package = "tidyterra"
))
# Rename with the tidyverse
rastertemp <- rastertemp %>%
rename(April = tavg_04, May = tavg_05, June = tavg_06)
# Plot with facets
ggplot() +
geom_spatraster(data = rastertemp) +
facet_wrap(~lyr, ncol = 2) +
scale_fill_whitebox_c(
palette = "muted",
labels = label_number(suffix = "º"),
n.breaks = 12,
guide = guide_legend(reverse = TRUE)
) +
labs(
fill = "",
title = "Average temperature in Castille and Leon (Spain)",
subtitle = "Months of April, May and June"
)
```
::: figure
Figure 1: Faceted map with multi-layer raster file.
::: The package documentation includes several examples of the use of `tidyterra`, and it can be accessed online at