Using the tidyverse with terra objects: the tidyterra package


tidyterra is an R (R Core Team 2023) package that allows manipulation of spatial data objects as provided by the terra package (Hijmans 2023), using the syntax of several packages included in the tidyverse (Wickham et al. 2019), such as dplyr (Wickham et al. 2023), tidyr (Wickham, Vaughan, and Girlich 2023), or tibble (Müller and Wickham 2023).

Furthermore, tidyterra extends the functionality of the ggplot2 package (Wickham 2016) by providing additional geoms and stats 1, as well as carefully chosen scales and color palettes specifically designed for map production.

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 (Quoss et al. (2021), Thuiller et al. (2023), Bachl et al. (2019), Lacko (2023), Buller et al. (2021)) and cited in academic research and publications (Bahlburg et al. (2023), Moraga (2023), Leonardi, Colucci, and Manica (2023)) ever since.

Statement of need

The tidyverse 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 2019). This means that dplyr::mutate() can be adapted to work with any object of class foo by creating the corresponding S3 method

While other popular packages designed for spatial data handling, such as sf (Pebesma 2018) or stars (Pebesma and Bivand 2023), 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 (Perpiñán and Hijmans 2023) and ggspatial (Dunnington 2023) 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 (Lindsay 2018). Additionally, it implements the cross-blended hypsometric tints described by Patterson and 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, so it can be easily installed using the following commands in R:


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:

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) +
    palette = "muted",
    labels = label_number(suffix = "º"),
    n.breaks = 12,
    guide = guide_legend(reverse = TRUE)
  ) +
    fill = "",
    title = "Average temperature in Castille and Leon (Spain)",
    subtitle = "Months of April, May and June"

Faceted map with multi-layer raster file.

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


I would like to thank Robert J. Hijmans for his advice and support in adapting some of the methods, as well as for the suggestions that helped us improve the functionalities of the package. I am also thankful to Dewey Dunnington, Brent Thorne, and the rest of contributors of the ggspatial package, which served as a key reference during the initial stages of the development of tidyterra.

tidyterra also incorporates some pieces of code adapted from ggplot2 for computing contours, which relies on the package isoband (Wickham, Wilke, and Pedersen 2022) developed by Claus O. Wilke.


Bachl, Fabian E., Finn Lindgren, David L. Borchers, and Janine B. Illian. 2019. inlabru: An R Package for Bayesian Spatial Modelling from Ecological Survey Data.” Methods in Ecology and Evolution 10: 760–66.
Bahlburg, Dominik, Sally E. Thorpe, Bettina Meyer, Uta Berger, and Eugene J. Murphy. 2023. “An Intercomparison of Models Predicting Growth of Antarctic Krill (Euphausia superba): The Importance of Recognizing Model Specificity.” PLOS ONE 18 (7): 1–29.
Buller, I. D., D. W. Brown, T. A. Myers, R. R. Jones, and M. J. Machiela. 2021. sparrpowR: A Flexible R Package to Estimate Statistical Power to Identify Spatial Clustering of Two Groups and Its Application.” International Journal of Health Geographics 20 (1): 1–7.
Dunnington, Dewey. 2023. ggspatial: Spatial Data Framework for ggplot2.
Hijmans, Robert J. 2023. terra: Spatial Data Analysis.
Lacko, Jindra. 2023. RCzechia: Spatial Objects of the Czech Republic.” Journal of Open Source Software 8 (83).
Leonardi, Michela, Margherita Colucci, and Andrea Manica. 2023. tidysdm: Leveraging the Flexibility of tidymodels for Species Distribution Modelling in R.” bioRxiv.
Lindsay, John. 2018. “Whitebox-Tools.” GitHub repository.
Moraga, Paula. 2023. Spatial Statistics for Data Science: Theory and Practice with R. Chapman & Hall/CRC.
Müller, Kirill, and Hadley Wickham. 2023. tibble: Simple Data Frames.”
Patterson, Tom, and Bernhard Jenny. 2011. “The Development and Rationale of Cross-Blended Hypsometric Tints.” Cartographic Perspectives, no. 69 (June): 31–46.
Pebesma, Edzer. 2018. Simple Features for R: Standardized Support for Spatial Vector Data.” The R Journal 10 (1): 439–46.
Pebesma, Edzer, and Roger Bivand. 2023. Spatial Data Science: With applications in R. London: Chapman; Hall/CRC.
Perpiñán, Oscar, and Robert Hijmans. 2023. rasterVis.
Quoss, Luise, Nestor Fernandez, Christian Langer, Jose Valdez, and Henrique Miguel Pereira. 2021. ebvcube: Working with netCDF for Essential Biodiversity Variables. Germany: German Centre for Integrative Biodiversity Research (iDiv) Halle-Jena-Leipzig.
R Core Team. 2023. R: A Language and Environment for Statistical Computing. Vienna, Austria: R Foundation for Statistical Computing.
Thuiller, Wilfried, Damien Georges, Maya Gueguen, Robin Engler, Frank Breiner, Bruno Lafourcade, and Remi Patin. 2023. biomod2: Ensemble Platform for Species Distribution Modeling.
Wickham, Hadley. 2016. ggplot2: Elegant Graphics for Data Analysis. Springer-Verlag New York.
———. 2019. “S3.” In Advanced R, 2nd ed. Chapman; Hall/CRC.
Wickham, Hadley, Mara Averick, Jennifer Bryan, Winston Chang, Lucy D’Agostino McGowan, Romain François, Garrett Grolemund, et al. 2019. “Welcome to the tidyverse.” Journal of Open Source Software 4 (43): 1686.
Wickham, Hadley, Romain François, Lionel Henry, Kirill Müller, and Davis Vaughan. 2023. dplyr: A Grammar of Data Manipulation.”
Wickham, Hadley, Davis Vaughan, and Maximilian Girlich. 2023. tidyr: Tidy Messy Data.”
Wickham, Hadley, Claus O. Wilke, and Thomas Lin Pedersen. 2022. isoband: Generate Isolines and Isobands from Regularly Spaced Elevation Grids.

  1. The term “geoms” refers to geometric objects, and “stats” refers to statistical transformations, following the naming conventions of ggplot2↩︎