Package {tidyterra}

Title:	'tidyverse' Methods and 'ggplot2' Helpers for 'terra' Objects
Version:	1.2.0
Description:	Provides methods from 'tidyverse' packages for 'SpatRaster' and 'SpatVector' objects created with 'terra', plus 'ggplot2' 'geoms' and scales for plotting those objects.
License:	MIT + file LICENSE
URL:	https://dieghernan.github.io/tidyterra/, https://github.com/dieghernan/tidyterra
BugReports:	https://github.com/dieghernan/tidyterra/issues
Depends:	R (≥ 4.1.0)
Imports:	cli (≥ 3.0.0), data.table, dplyr (≥ 1.2.0), generics, ggplot2 (≥ 4.0.0), grDevices, isoband, lifecycle, magrittr, rlang, scales, sf (≥ 1.0.0), terra (≥ 1.8-10), tibble (≥ 3.0.0), tidyr (≥ 1.0.0), tools, utils, vctrs
Suggests:	hexbin, knitr, maptiles, quarto, rmarkdown, s2, stringi, testthat (≥ 3.0.0)
VignetteBuilder:	quarto
Config/Needs/coverage:	covr
Config/Needs/website:	geodata, dieghernan/gitdevr, ragg, styler, metR, ggspatial, cpp11, remotes, gganimate, gifski, tidyverse, bibtex
Config/roxygen2/markdown:	TRUE
Config/roxygen2/version:	8.0.0
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
LazyData:	true
X-schema.org-keywords:	r, terra, ggplot-extension, r-spatial, rspatial, cran, cran-r, r-package, rstats, rstats-package
NeedsCompilation:	no
Packaged:	2026-06-16 18:23:52 UTC; diego
Author:	Diego Hernangómez [aut, cre, cph], Dewey Dunnington [ctb] (for ggspatial code), ggplot2 authors [cph] (for contour code), Andrea Manica [ctb]
Maintainer:	Diego Hernangómez <diego.hernangomezherrero@gmail.com>
Repository:	CRAN
Date/Publication:	2026-06-17 05:10:02 UTC

tidyterra: 'tidyverse' Methods and 'ggplot2' Helpers for 'terra' Objects

Description

Provides methods from 'tidyverse' packages for 'SpatRaster' and 'SpatVector' objects created with 'terra', plus 'ggplot2' 'geoms' and scales for plotting those objects.

Author(s)

Maintainer: Diego Hernangómez diego.hernangomezherrero@gmail.com (ORCID) [copyright holder]

Authors:

• Diego Hernangómez diego.hernangomezherrero@gmail.com (ORCID) [copyright holder]

Other contributors:

• Dewey Dunnington (ORCID) (for ggspatial code) [contributor]

• ggplot2 authors (for contour code) [copyright holder]

• Andrea Manica (ORCID) [contributor]

See Also

Useful links:

• https://dieghernan.github.io/tidyterra/

• https://github.com/dieghernan/tidyterra

• Report bugs at https://github.com/dieghernan/tidyterra/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Order a SpatVector using column values

Description

arrange.SpatVector() orders the geometries of a SpatVector by the values of selected columns.

Usage

## S3 method for class 'SpatVector'
arrange(.data, ..., .by_group = FALSE, .locale = NULL)

Arguments

Value

A SpatVector object.

terra equivalent

terra::sort()

Methods

Implementation of the generic dplyr::arrange() function for SpatVector class.

See Also

dplyr::arrange()

Other dplyr single-table verbs: filter.Spat, mutate.Spat, reframe.SpatVector(), rename.Spat, select.Spat, slice.Spat, summarise.SpatVector()

Other dplyr verbs that operate on rows: distinct.SpatVector(), filter.Spat, rows.SpatVector, slice.Spat

Other dplyr methods: bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
library(dplyr)

v <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

# Single variable

v |>
  arrange(desc(iso2))

# Two variables
v |>
  mutate(even = as.double(cpro) %% 2 == 0) |>
  arrange(desc(even), desc(iso2))

# With new variables
v |>
  mutate(area_geom = terra::expanse(v)) |>
  arrange(area_geom)

Get cell number, row and column from a SpatRaster

Description

as_coordinates() can be used to obtain the position of each cell on the SpatRaster matrix.

Usage

as_coordinates(x, as.raster = FALSE)

Arguments

Value

A tibble or a SpatRaster (if as.raster = TRUE) with the same number of rows (or cells) as the number of cells in x.

When as.raster = TRUE the resulting SpatRaster has the same CRS, extent and resolution as x.

See Also

slice.SpatRaster()

Coercing objects: as_sf(), as_spatraster(), as_spatvector(), as_tibble.Spat, fortify.Spat, tidy.Spat

Examples

library(terra)

f <- system.file("extdata/cyl_temp.tif", package = "tidyterra")

r <- rast(f)

as_coordinates(r)
as_coordinates(r, as.raster = TRUE)

as_coordinates(r, as.raster = TRUE) |> plot()

Coerce a SpatVector to a sf object

Description

as_sf() coerces a SpatVector into an sf object. It wraps sf::st_as_sf() and preserves groups created with group_by.SpatVector().

Usage

as_sf(x, ...)

Arguments

Value

A sf object with an additional tbl_df class for pretty printing.

See Also

Coercing objects: as_coordinates(), as_spatraster(), as_spatvector(), as_tibble.Spat, fortify.Spat, tidy.Spat

Examples

library(terra)

f <- system.file("extdata/cyl.gpkg", package = "tidyterra")
v <- terra::vect(f)

# This is ungrouped
v
is_grouped_spatvector(v)

# Get an ungrouped data
a_sf <- as_sf(v)

dplyr::is_grouped_df(a_sf)

# Grouped

v$gr <- c("C", "A", "A", "B", "A", "B", "B")
v$gr2 <- rep(c("F", "G", "F"), 3)

gr_v <- group_by(v, gr, gr2)

gr_v
is_grouped_spatvector(gr_v)

group_data(gr_v)

# A sf

a_gr_sf <- as_sf(gr_v)

dplyr::is_grouped_df(a_gr_sf)

group_data(a_gr_sf)

Coerce a data frame to SpatRaster

Description

as_spatraster() converts a data frame or tibble into a SpatRaster. It wraps the terra::rast() S4 method for signature data.frame.

Usage

as_spatraster(x, ..., xycols = 1:2, crs = "", digits = 6)

Arguments

Details

If no crs is provided and the tibble has been created with the method as_tibble.SpatRaster(), the crs is inferred from attr(x, "crs").

Value

A SpatRaster.

terra equivalent

terra::rast() (see S4 method for signature data.frame).

See Also

pull_crs() for retrieving CRS and the corresponding utilities sf::st_crs() and terra::crs().

Coercing objects: as_coordinates(), as_sf(), as_spatvector(), as_tibble.Spat, fortify.Spat, tidy.Spat

Examples

library(terra)

r <- rast(matrix(1:90, ncol = 3), crs = "EPSG:3857")

r

# Create tibble
as_tbl <- as_tibble(r, xy = TRUE)

as_tbl

# From tibble
newrast <- as_spatraster(as_tbl, crs = "EPSG:3857")
newrast

Coerce objects to SpatVector

Description

as_spatvector() turns an existing object into a SpatVector. It wraps the terra::vect() S4 method for the data.frame signature.

Usage

as_spatvector(x, ...)

## S3 method for class 'data.frame'
as_spatvector(x, ..., geom = c("lon", "lat"), crs = "")

## S3 method for class 'sf'
as_spatvector(x, ...)

## S3 method for class 'sfc'
as_spatvector(x, ...)

## S3 method for class 'SpatVector'
as_spatvector(x, ...)

Arguments

Details

This function differs from terra::vect() in the following ways:

• Rows with geometry values NA or "" are removed before conversion.

• If x is a grouped data frame (see dplyr::group_by()), the grouping variables are transferred and a grouped SpatVector is created (see group_by.SpatVector()).

• If no crs is provided and the tibble has been created with the method as_tibble.SpatVector(), the crs is inferred from attr(x, "crs").

• It handles the conversion of EMPTY geometries between sf and terra.

Value

A SpatVector.

terra equivalent

terra::vect()

See Also

pull_crs() for retrieving CRS and the corresponding utilities sf::st_crs() and terra::crs().

Coercing objects: as_coordinates(), as_sf(), as_spatraster(), as_tibble.Spat, fortify.Spat, tidy.Spat

Examples

library(terra)

v <- vect(matrix(1:80, ncol = 2), crs = "EPSG:3857")

v$cat <- sample(LETTERS[1:4], size = nrow(v), replace = TRUE)

v

# Create tibble
as_tbl <- as_tibble(v, geom = "WKT")

as_tbl

# From tibble
newvect <- as_spatvector(as_tbl, geom = "geometry", crs = "EPSG:3857")
newvect

Coerce SpatRaster and SpatVector objects to tibbles

Description

as_tibble() methods for SpatRaster and SpatVector objects.

Usage

## S3 method for class 'SpatRaster'
as_tibble(
  x,
  ...,
  xy = FALSE,
  na.rm = FALSE,
  .name_repair = c("unique", "check_unique", "universal", "minimal", "unique_quiet",
    "universal_quiet")
)

## S3 method for class 'SpatVector'
as_tibble(
  x,
  ...,
  geom = NULL,
  .name_repair = c("unique", "check_unique", "universal", "minimal", "unique_quiet",
    "universal_quiet")
)

Arguments

Value

A tibble.

terra equivalent

terra::as.data.frame()

Methods

Implementation of the generic tibble::as_tibble() method.

SpatRaster and SpatVector

The returned tibble includes the CRS of the original object as an attribute in WKT format (see pull_crs()).

About layer/column names

When coercing SpatRaster objects to data frames, x and y are reserved names for the geographic coordinates of each cell. terra also allows layers with duplicated names.

When coercing a SpatRaster to a tibble, tidyterra may rename its layers to avoid these issues. Specifically, layers may be renamed in the following cases:

• Layers with duplicated names.

• When coercing to a tibble, if xy = TRUE, layers named x or y are renamed.

• When working with methods from tidyverse packages, for example filter.SpatRaster(), the same renaming happens.

tidyterra displays a message describing the renamed layers.

The same issue affects SpatVector objects with reserved names such as geometry (when geom = c("WKT", "HEX")) and x, y (when geom = "XY"). These names represent geometry columns in terra::as.data.frame(). If geom is not NULL, the same renaming logic described for SpatRaster also applies to SpatVector columns.

See Also

tibble::as_tibble(), terra::as.data.frame()

Coercing objects: as_coordinates(), as_sf(), as_spatraster(), as_spatvector(), fortify.Spat, tidy.Spat

Examples

library(terra)
# SpatRaster
f <- system.file("extdata/cyl_temp.tif", package = "tidyterra")
r <- rast(f)

as_tibble(r, na.rm = TRUE)

as_tibble(r, xy = TRUE)

# SpatVector

f <- system.file("extdata/cyl.gpkg", package = "tidyterra")
v <- vect(f)

as_tibble(v)

Create a complete ggplot for ⁠Spat*⁠ objects

Description

autoplot() uses ggplot2 to draw plots like those produced by terra::plot()/terra::plotRGB() in a single command.

Usage

## S3 method for class 'SpatRaster'
autoplot(
  object,
  ...,
  rgb = NULL,
  use_coltab = NULL,
  facets = NULL,
  nrow = NULL,
  ncol = 2
)

## S3 method for class 'SpatVector'
autoplot(object, ...)

## S3 method for class 'SpatGraticule'
autoplot(object, ...)

## S3 method for class 'SpatExtent'
autoplot(object, ...)

Arguments

Details

Implementation of ggplot2::autoplot() method.

Value

A ggplot2 layer.

Methods

Implementation of the generic ggplot2::autoplot() method.

SpatRaster

Uses geom_spatraster() or geom_spatraster_rgb().

SpatVector, SpatGraticule and SpatExtent

Uses geom_spatvector(). Labels can be placed with geom_spatvector_text() or geom_spatvector_label().

See Also

ggplot2::autoplot()

Other ggplot2 helpers: fortify.Spat, geom_spat_contour, geom_spatraster(), geom_spatraster_rgb(), ggspatvector, stat_spat_coordinates()

Other ggplot2 methods: fortify.Spat

Examples

file_path <- system.file("extdata/cyl_temp.tif", package = "tidyterra")

library(terra)
temp <- rast(file_path)

library(ggplot2)
autoplot(temp)

# With a tile

tile <- system.file("extdata/cyl_tile.tif", package = "tidyterra") |>
  rast()

autoplot(tile)

# With color tables

ctab <- system.file("extdata/cyl_era.tif", package = "tidyterra") |>
  rast()

autoplot(ctab)

# With vectors
v <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
autoplot(v)

v |> autoplot(aes(fill = cpro)) +
  geom_spatvector_text(aes(label = iso2)) +
  coord_sf(crs = 25829)

Bind multiple SpatVector, sf and data frame objects by column

Description

Bind any number of SpatVector, data frames and sf objects by column, making a wider result. This is similar to do.call(cbind, data_frames).

Where possible prefer using a join to combine SpatVector and data frame objects. bind_spat_cols() binds the rows in order in which they appear so it is easy to create meaningless results without realizing it.

Usage

bind_spat_cols(
  ...,
  .name_repair = c("unique", "universal", "check_unique", "minimal")
)

Arguments

Value

A SpatVector with the corresponding columns. The geometry and CRS correspond to the first SpatVector of ....

terra equivalent

cbind() method

Methods

Implementation of the dplyr::bind_cols() function for SpatVector objects. For the second and subsequent arguments in ..., the geometry is not cbinded and only the data frame-like columns are kept.

See Also

dplyr::bind_cols()

Other dplyr verbs that operate on pairs of SpatVector and data frame objects: bind_rows.SpatVector, cross_join.SpatVector(), filter-joins.SpatVector, mutate-joins.SpatVector, nest_join.SpatVector(), rows.SpatVector

Other dplyr methods: arrange.SpatVector(), bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
sv <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
df2 <- data.frame(letters = letters[seq_len(nrow(sv))])

# Data frame
bind_spat_cols(sv, df2)

# Another SpatVector
bind_spat_cols(sv[1:2, ], sv[3:4, ])

# sf objects
sfobj <- sf::read_sf(system.file("shape/nc.shp", package = "sf"))

bind_spat_cols(sv[1:9, ], sfobj[1:9, ])

# Mixed

end <- bind_spat_cols(sv, sfobj[seq_len(nrow(sv)), 1:2], df2)

end
glimpse(end)

# Row sizes must be compatible when column-binding.
try(bind_spat_cols(sv, sfobj))

Bind multiple SpatVector, sf/sfc and data frame objects by row

Description

Bind any number of SpatVector, data frames and sf/sfc objects by row, making a longer result. This is similar to do.call(rbind, data_frames), but the output will contain all columns that appear in any of the inputs.

Usage

bind_spat_rows(..., .id = NULL)

Arguments

Value

A SpatVector of the same type as the first element of ....

terra equivalent

rbind() method

Methods

Implementation of the dplyr::bind_rows() function for SpatVector objects.

The first argument should be a SpatVector. Each subsequent argument can be a SpatVector, sf/sfc object or data frame:

• If subsequent SpatVector/sf/sfc objects have a different CRS than the first element, those elements are reprojected to the CRS of the first element with a message.

• If any element of ... is a tibble/data frame, the rows are column-bound with empty geometries with a message.

See Also

dplyr::bind_rows()

Other dplyr verbs that operate on pairs of SpatVector and data frame objects: bind_cols.SpatVector, cross_join.SpatVector(), filter-joins.SpatVector, mutate-joins.SpatVector, nest_join.SpatVector(), rows.SpatVector

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
v <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

v1 <- v[1, "cpro"]
v2 <- v[3:5, c("name", "iso2")]

# You can supply individual SpatVector as arguments:
bind_spat_rows(v1, v2)

# When you supply a column name with the `.id` argument, a new column is
# created to link each row to its original data frame.
bind_spat_rows(v1, v2, .id = "id")


# Use with sf
sfobj <- sf::st_as_sf(v2[1, ])

sfobj

bind_spat_rows(v1, sfobj)

# Would reproject with a message on different CRS
sfobj_3857 <- as_spatvector(sfobj) |> project("EPSG:3857")

bind_spat_rows(v1, sfobj_3857)

# And with data frames with a message
data("mtcars")
bind_spat_rows(v1, sfobj, mtcars, .id = "id2")

# Use lists
bind_spat_rows(list(v1[1, ], sfobj[1:2, ]))

# Or named list combined with .id
bind_spat_rows(list(
  SpatVector = v1[1, ], sf = sfobj[1, ],
  mtcars = mtcars[1, ]
), .id = "source")

Compare attributes of two SpatRaster objects

Description

Two SpatRaster objects are compatible (in terms of combining layers) if the CRS, extent and resolution are similar. In those cases you can combine the objects simply as c(x, y).

This function compares those attributes and reports the results. See Solving issues for minimal guidance.

Usage

compare_spatrasters(x, y, digits = 6)

Arguments

Value

An invisible logical TRUE/FALSE indicating whether the SpatRaster objects are compatible, plus an informative message flagging any issues found.

terra equivalent

terra::identical()

Solving issues

• On non-equal CRS, try terra::project().

• On non-equal extent, try terra::resample().

• On non-equal resolution you can try terra::resample(), terra::aggregate() or terra::disagg().

See Also

terra::identical()

Other helpers: is_grouped_spatvector(), is_regular_grid(), pull_crs()

Examples

library(terra)

x <- rast(matrix(1:90, ncol = 3), crs = "EPSG:3857")

# Nothing
compare_spatrasters(x, x)

# Different crs
y_nocrs <- x
crs(y_nocrs) <- NA

compare_spatrasters(x, y_nocrs)

# Different extent
compare_spatrasters(x, x[1:10, , drop = FALSE])

# Different resolution
y_newres <- x

res(y_newres) <- res(x) / 2
compare_spatrasters(x, y_newres)

# Everything

compare_spatrasters(x, project(x, "epsg:3035"))

Complete missing combinations in a SpatVector

Description

complete() turns implicit missing combinations in a SpatVector into explicit rows while preserving geometry and spatial metadata.

Usage

## S3 method for class 'SpatVector'
complete(data, ..., fill = list(), explicit = TRUE)

Arguments

Value

A SpatVector object.

Methods

Implementation of the generic tidyr::complete() method.

SpatVector

complete() preserves the geometry column while expanding missing combinations. New combinations receive empty geometries.

See Also

tidyr::complete()

Other tidyr verbs for handling missing values: drop_na.Spat, expand.SpatVector(), fill.SpatVector(), replace_na.Spat

Other tidyr methods: drop_na.Spat, expand.SpatVector(), fill.SpatVector(), nest.SpatVector(), pivot_longer.SpatVector(), pivot_wider.SpatVector(), replace_na.Spat, uncount.SpatVector(), unite.Spat

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
v <- dplyr::mutate(v, grp = ifelse(iso2 %in% c("ES-AV", "ES-BU"), "a", "b"))

complete(v, grp, tidyr::nesting(iso2, name)) |>
  glimpse()

Count the observations in each SpatVector group

Description

count() lets you quickly count the unique values of one or more variables: df |> count(a, b) is roughly equivalent to df |> group_by(a, b) |> summarise(n = n()). count() is paired with tally(), a lower-level helper that is equivalent to df |> summarise(n = n()). Supply wt to perform weighted counts, switching the summary from n = n() to n = sum(wt).

add_count() is equivalent to count() but use mutate() instead of summarise() so that it adds a new column with group-wise counts.

Usage

## S3 method for class 'SpatVector'
count(
  x,
  ...,
  wt = NULL,
  sort = FALSE,
  name = NULL,
  .drop = deprecated(),
  .dissolve = TRUE
)

## S3 method for class 'SpatVector'
tally(x, wt = NULL, sort = FALSE, name = NULL)

## S3 method for class 'SpatVector'
add_count(x, ..., wt = NULL, sort = FALSE, name = NULL, .drop = deprecated())

Arguments

Value

A SpatVector object with updated grouping metadata.

terra equivalent

terra::aggregate()

Methods

Implementation of the generic dplyr::count() methods for SpatVector objects.

tally() will always return a disaggregated geometry while count() can handle this. See also summarise.SpatVector().

See Also

dplyr::count(), dplyr::tally()

Other dplyr verbs that operate on groups of rows: group_by.SpatVector(), reframe.SpatVector(), rowwise.SpatVector(), summarise.SpatVector()

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
f <- system.file("ex/lux.shp", package = "terra")
p <- vect(f)

p |> count(NAME_1, sort = TRUE)

p |> count(pop = ifelse(POP < 20000, "A", "B"))

# tally() is a lower-level function that assumes grouping is already done.
p |> tally()

p |>
  group_by(NAME_1) |>
  tally()

# Dissolve geometries by default

library(ggplot2)
p |>
  count(NAME_1) |>
  ggplot() +
  geom_spatvector(aes(fill = n))

# Opt out
p |>
  count(NAME_1, .dissolve = FALSE, sort = TRUE) |>
  ggplot() +
  geom_spatvector(aes(fill = n))

Cross-blended hypsometric tints

Description

A tibble including the color map of 4 gradient palettes. All palettes also include a definition of color limits in terms of elevation (meters) that can be used with ggplot2::scale_fill_gradientn().

Format

A tibble of 41 rows and 6 columns with the following fields:

pal

Name of the palette.

limit

Recommended elevation limit (in meters) for each color.

r

Value of the red channel (RGB color mode).

g

Value of the green channel (RGB color mode).

b

Value of the blue channel (RGB color mode).

hex

Hex code of the color.

Details

From Patterson & Jenny (2011):

More recently, the role and design of hypsometric tints have come under scrutiny. One reason for this is the concern that people misread elevation colors as climate or vegetation information. Cross-blended hypsometric tints, introduced in 2009, are a partial solution to this problem. They use variable lowland colors customized to match the differing natural environments of world regions, which merge into one another.

Source

Derived from:

• Patterson, T., & Jenny, B. (2011). The Development and Rationale of Cross-blended Hypsometric Tints. Cartographic Perspectives, (69), 31-46. doi:10.14714/CP69.20.

See Also

scale_fill_cross_blended_c()

Other datasets: grass_db, hypsometric_tints_db, princess_db, volcano2

Examples

data("cross_blended_hypsometric_tints_db")

cross_blended_hypsometric_tints_db

# Select a palette
warm <- cross_blended_hypsometric_tints_db |>
  filter(pal == "warm_humid")

f <- system.file("extdata/asia.tif", package = "tidyterra")
r <- terra::rast(f)

library(ggplot2)

p <- ggplot() +
  geom_spatraster(data = r) +
  labs(fill = "elevation")

p +
  scale_fill_gradientn(colors = warm$hex)

# Use with limits
p +
  scale_fill_gradientn(
    colors = warm$hex,
    values = scales::rescale(warm$limit),
    limit = range(warm$limit),
    na.value = "lightblue"
  )

Cross joins for SpatVector objects

Description

Cross joins match each row in x to every row in y.

See dplyr::cross_join() for details.

Usage

## S3 method for class 'SpatVector'
cross_join(x, y, ..., copy = FALSE, suffix = c(".x", ".y"))

Arguments

Value

A SpatVector object.

Methods

Implementation of the generic dplyr::cross_join() method.

SpatVector

The geometry column has sticky behavior. The result repeats each geometry in x once for every row in y.

If y has a column named geometry, it is treated as a regular attribute and receives the suffix from suffix.

See Also

dplyr::cross_join()

Other dplyr verbs that operate on pairs of SpatVector and data frame objects: bind_cols.SpatVector, bind_rows.SpatVector, filter-joins.SpatVector, mutate-joins.SpatVector, nest_join.SpatVector(), rows.SpatVector

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

labels <- data.frame(period = c("past", "present"))

cross_join(v, labels)

Keep distinct/unique rows and geometries of SpatVector objects

Description

Keep only unique/distinct rows and geometries from a SpatVector.

Usage

## S3 method for class 'SpatVector'
distinct(.data, ..., .keep_all = FALSE)

Arguments

Value

A SpatVector object.

terra equivalent

terra::unique()

Methods

Implementation of the generic dplyr::distinct() method.

SpatVector

You can remove duplicate geometries by passing the reserved name geometry to .... See Examples.

See Also

dplyr::distinct(), terra::unique()

Other dplyr verbs that operate on rows: arrange.SpatVector(), filter.Spat, rows.SpatVector, slice.Spat

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)

v <- vect(system.file("ex/lux.shp", package = "terra"))

# Create a vector with dups
v <- v[sample(seq_len(nrow(v)), 100, replace = TRUE), ]
v$gr <- sample(LETTERS[1:3], 100, replace = TRUE)

# All duplicates
ex1 <- distinct(v)
ex1

nrow(ex1)

# Duplicates by NAME_1
ex2 <- distinct(v, gr)
ex2
nrow(ex2)

# Same but keeping all cols
ex2b <- distinct(v, gr, .keep_all = TRUE)
ex2b
nrow(ex2b)

# Unique geometries
ex3 <- distinct(v, geometry)

ex3
nrow(ex3)
# Same as terra::unique()
terra::unique(ex3)

# Unique keeping info
distinct(v, geometry, .keep_all = TRUE)

Drop attributes of ⁠Spat*⁠ objects containing missing values

Description

• SpatVector: drop_na() method drops geometries where any attribute specified by ... contains a missing value.

• SpatRaster: drop_na() method drops cells where any layer specified by ... contains a missing value.

Usage

## S3 method for class 'SpatVector'
drop_na(data, ...)

## S3 method for class 'SpatRaster'
drop_na(data, ...)

Arguments

Value

A ⁠Spat*⁠ object of the same class as data. See Methods.

terra equivalent

terra::trim()

Methods

Implementation of the generic tidyr::drop_na() method.

SpatVector

The implementation of this method is performed on a by-attribute basis, meaning that NA values are assessed on the attributes (columns) of each vector (rows). The result is a SpatVector with potentially fewer geometries than the input.

SpatRaster

The implementation of ⁠drop_na().SpatRaster⁠ can be understood as a masking method based on the values of the layers (see terra::mask()).

SpatRaster layers are considered as columns and SpatRaster cells as rows, so rows (cells) with any NA value on any layer become NA. You can also mask the cells (rows) based on the values of specific layers (columns).

drop_na() effectively removes outer cells that are NA (see terra::trim()), so the extent of the resulting object may differ from the extent of the input (see terra::resample() for more information).

Check the Examples to have a better understanding of this method.

Feedback needed!

Visit https://github.com/dieghernan/tidyterra/issues. The implementation of this method for SpatRaster may change in the future.

See Also

tidyr::drop_na()

Other tidyr verbs for handling missing values: complete.SpatVector(), expand.SpatVector(), fill.SpatVector(), replace_na.Spat

Other tidyr methods: complete.SpatVector(), expand.SpatVector(), fill.SpatVector(), nest.SpatVector(), pivot_longer.SpatVector(), pivot_wider.SpatVector(), replace_na.Spat, uncount.SpatVector(), unite.Spat

Examples

library(terra)

f <- system.file("extdata/cyl.gpkg", package = "tidyterra")

v <- terra::vect(f)

# Add missing values.
v <- v |> mutate(iso2 = ifelse(cpro <= "09", NA, cpro))

# Initial plot.
plot(v, col = "red")

# Drop geometries with missing values in iso2.
v |>
  drop_na(iso2) |>
  plot(col = "red")
# SpatRaster method


r <- rast(
  crs = "EPSG:3857",
  extent = c(0, 10, 0, 10),
  nlyr = 3,
  resolution = c(2.5, 2.5)
)
terra::values(r) <- seq_len(ncell(r) * nlyr(r))

# Add missing values.
r[r > 13 & r < 22 | r > 31 & r < 45] <- NA

# Initial plot.
plot(r, nc = 3)

# Mask with lyr.1.
r |>
  drop_na(lyr.1) |>
  plot(nc = 3)

# Mask with lyr.2.
r |>
  drop_na(lyr.2) |>
  plot(nc = 3)

# Mask with lyr.3.
r |>
  drop_na(lyr.3) |>
  plot(nc = 3)

# Mask all layers.
r |>
  drop_na() |>
  plot(nc = 3)

Expand SpatVector attribute combinations

Description

expand() returns a tibble with all combinations of selected attributes. It does not return a SpatVector because newly created combinations do not have a well-defined geometry. Use complete.SpatVector() when empty geometries should be added explicitly.

Usage

## S3 method for class 'SpatVector'
expand(data, ..., .name_repair = "check_unique")

Arguments

Value

A tibble.

Methods

Implementation of the generic tidyr::expand() method.

SpatVector

The output is a tibble with attribute combinations. Geometry is not preserved because new combinations do not have a well-defined geometry.

See Also

tidyr::expand(), complete.SpatVector()

Other tidyr verbs for handling missing values: complete.SpatVector(), drop_na.Spat, fill.SpatVector(), replace_na.Spat

Other tidyr methods: complete.SpatVector(), drop_na.Spat, fill.SpatVector(), nest.SpatVector(), pivot_longer.SpatVector(), pivot_wider.SpatVector(), replace_na.Spat, uncount.SpatVector(), unite.Spat

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
v$grp <- rep(c("A", "B"), length.out = nrow(v))

expand(v, grp, cpro)

Fill in missing values with previous or next value on a SpatVector

Description

Fills missing values in selected columns using the next or previous entry. This is useful in the common output format where values are not repeated, and are only recorded when they change.

Usage

## S3 method for class 'SpatVector'
fill(data, ..., .by = NULL, .direction = c("down", "up", "downup", "updown"))

Arguments

Value

A SpatVector object.

Methods

Implementation of the generic tidyr::fill() function for SpatVector.

Grouped SpatVector

With grouped SpatVector created by group_by.SpatVector(), fill() will be applied within each group, meaning that it won't fill across group boundaries.

See Also

tidyr::fill()

Other tidyr verbs for handling missing values: complete.SpatVector(), drop_na.Spat, expand.SpatVector(), replace_na.Spat

Other tidyr methods: complete.SpatVector(), drop_na.Spat, expand.SpatVector(), nest.SpatVector(), pivot_longer.SpatVector(), pivot_wider.SpatVector(), replace_na.Spat, uncount.SpatVector(), unite.Spat

Examples

library(dplyr)

lux <- terra::vect(system.file("ex/lux.shp", package = "terra"))

# Leave some blanks for demo purposes

lux_blnk <- lux |>
  mutate(NAME_1 = if_else(NAME_1 != NAME_2, NA, NAME_2))

as_tibble(lux_blnk)

# `fill()` defaults to replacing missing data from top to bottom
lux_blnk |>
  fill(NAME_1) |>
  as_tibble()

# direction = "up"
lux_blnk |>
  fill(NAME_1, .direction = "up") |>
  as_tibble()

# Grouping and downup - will restore the initial state
lux_blnk |>
  group_by(ID_1) |>
  fill(NAME_1, .direction = "downup") |>
  as_tibble()

Filtering joins for SpatVector objects

Description

Filtering joins filter rows from x based on the presence or absence of matches in y:

• semi_join() return all rows from x with a match in y.

• anti_join() return all rows from x without a match in y.

See dplyr::semi_join() for details.

Usage

## S3 method for class 'SpatVector'
semi_join(x, y, by = NULL, copy = FALSE, ...)

## S3 method for class 'SpatVector'
anti_join(x, y, by = NULL, copy = FALSE, ...)

Arguments

Value

A SpatVector object.

terra equivalent

terra::merge()

Methods

Implementation of the generic dplyr::semi_join() family

SpatVector

The geometry column has sticky behavior. This means that the result always has the geometry of x for the records that match the join conditions.

See Also

dplyr::semi_join(), dplyr::anti_join(), terra::merge()

Other dplyr verbs that operate on pairs of SpatVector and data frame objects: bind_cols.SpatVector, bind_rows.SpatVector, cross_join.SpatVector(), mutate-joins.SpatVector, nest_join.SpatVector(), rows.SpatVector

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
library(ggplot2)

# Vector
v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

# A data frame
df <- data.frame(
  cpro = sprintf("%02d", 1:10),
  x = runif(10),
  y = runif(10),
  letter = rep_len(LETTERS[1:3], length.out = 10)
)

v

# Semi join
semi <- v |> semi_join(df)

semi

autoplot(semi, aes(fill = iso2)) + labs(title = "Semi Join")

# Anti join

anti <- v |> anti_join(df)

anti

autoplot(anti, aes(fill = iso2)) + labs(title = "Anti Join")

Subset cells/geometries of ⁠Spat*⁠ objects

Description

These functions subset a data frame by applying the expressions in ... to determine which rows should be kept (for filter()) or dropped (for filter_out()).

Multiple conditions can be supplied separated by a comma. These will be combined with the & operator. To combine comma separated conditions using | instead, wrap them in dplyr::when_any().

Both filter() and filter_out() treat NA like FALSE. This subtle behavior can affect how you write your conditions when missing values are involved. See dplyr::filter().

You can filter a SpatRaster by its geographic coordinates. Use filter(.data, x > 42). The names x and y are reserved in terra because they refer to the geographic coordinates of the layer.

See Examples and section About layer names on as_tibble.Spat().

Usage

## S3 method for class 'SpatRaster'
filter(.data, ..., .preserve = FALSE, .keep_extent = TRUE)

## S3 method for class 'SpatVector'
filter(.data, ..., .by = NULL, .preserve = FALSE)

## S3 method for class 'SpatVector'
filter_out(.data, ..., .by = NULL, .preserve = FALSE)

Arguments

Value

A ⁠Spat*⁠ object of the same class as .data. See Methods.

Methods

Implementation of the generic dplyr::filter() method.

SpatRaster

Cells that do not meet the conditions on ... are returned with value NA. On a multi-layer SpatRaster the NA is propagated across all the layers.

If .keep_extent = TRUE the returned SpatRaster has the same CRS, extent, resolution and number of cells as .data. If .keep_extent = FALSE the outer NA cells are trimmed with terra::trim(), so the extent and number of cells may differ. The output will still have the same CRS and resolution as .data.

x and y variables, the longitude and latitude of the SpatRaster, are also available internally for filtering. See Examples.

SpatVector

The result is a SpatVector with all the geometries that produce a value of TRUE for all conditions.

See Also

dplyr::filter()

Other dplyr single-table verbs: arrange.SpatVector(), mutate.Spat, reframe.SpatVector(), rename.Spat, select.Spat, slice.Spat, summarise.SpatVector()

Other dplyr verbs that operate on rows: arrange.SpatVector(), distinct.SpatVector(), rows.SpatVector, slice.Spat

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
f <- system.file("extdata/cyl_temp.tif", package = "tidyterra")

r <- rast(f) |> select(tavg_04)

plot(r)

# Filter temps
r_f <- r |> filter(tavg_04 > 11.5)

# Extent is kept
plot(r_f)

# Filter temps and extent
r_f2 <- r |> filter(tavg_04 > 11.5, .keep_extent = FALSE)

# Extent has changed
plot(r_f2)

# Filter by geographic coordinates
r2 <- project(r, "epsg:4326")

r2 |> plot()

r2 |>
  filter(
    x > -4,
    x < -2,
    y > 42
  ) |>
  plot()
v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
glimpse(v)
v |> filter(cpro < 10)

# Same as
v |> filter_out(cpro >= 10)

Fortify ⁠Spat*⁠ objects

Description

Fortify SpatRaster and SpatVector objects to data frames. This provides native compatibility with ggplot2::ggplot().

These methods are now implemented as wrappers around tidy.Spat methods.

Usage

## S3 method for class 'SpatRaster'
fortify(
  model,
  data,
  ...,
  .name_repair = c("unique", "check_unique", "universal", "minimal", "unique_quiet",
    "universal_quiet"),
  maxcell = terra::ncell(model) * 1.1,
  pivot = FALSE
)

## S3 method for class 'SpatVector'
fortify(model, data, ...)

## S3 method for class 'SpatGraticule'
fortify(model, data, ...)

## S3 method for class 'SpatExtent'
fortify(model, data, ..., crs = "")

Arguments

Value

fortify.SpatVector(), fortify.SpatGraticule() and fortify.SpatExtent() return a sf object.

fortify.SpatRaster() returns a tibble. See Methods.

Methods

Implementation of the generic ggplot2::fortify() method.

SpatRaster

Returns a tibble that can be used with ⁠ggplot2::geom_*⁠, such as ggplot2::geom_point() and ggplot2::geom_raster().

The resulting tibble includes coordinates in the x and y columns. The values of each layer are added as extra columns using the layer names from the SpatRaster.

The CRS of the SpatRaster can be retrieved with attr(fortifiedSpatRaster, "crs").

You can convert the fortified object back to a SpatRaster with as_spatraster().

When pivot = TRUE, the SpatRaster is fortified in long format (see tidyr::pivot_longer()). The fortified object has the following columns:

• x, y: Coordinates of the cell center in the corresponding CRS.

• lyr: Name of the SpatRaster layer associated with value.

• value: Cell value for the corresponding lyr.

This option can be useful when combining several ⁠geom_*⁠ layers or when faceting.

SpatVector, SpatGraticule and SpatExtent

Returns an sf object that can be used with ggplot2::geom_sf().

See Also

tidy.Spat, sf::st_as_sf(), as_tibble.Spat, as_spatraster(), ggplot2::fortify().

Other ggplot2 helpers: autoplot.Spat, geom_spat_contour, geom_spatraster(), geom_spatraster_rgb(), ggspatvector, stat_spat_coordinates()

Other ggplot2 methods: autoplot.Spat

Coercing objects: as_coordinates(), as_sf(), as_spatraster(), as_spatvector(), as_tibble.Spat, tidy.Spat

Examples

# Demonstrate use with ggplot2.
library(ggplot2)

# Get a SpatRaster.
r <- system.file("extdata/volcano2.tif", package = "tidyterra") |>
  terra::rast() |>
  terra::project("EPSG:4326")

# You can now use a SpatRaster with any geom.
ggplot(r, maxcell = 50) +
  geom_histogram(aes(x = elevation),
    bins = 20, fill = "lightblue",
    color = "black"
  )

# For SpatVector, SpatGraticule and SpatExtent, use geom_sf().

# Create a SpatVector.
extfile <- system.file("extdata/cyl.gpkg", package = "tidyterra")
cyl <- terra::vect(extfile)

class(cyl)

ggplot(cyl) +
  geom_sf()

# SpatGraticule
g <- terra::graticule(60, 30, crs = "+proj=robin")

class(g)

ggplot(g) +
  geom_sf()

# SpatExtent
ex <- terra::ext(cyl)

class(ex)

ggplot(ex, crs = cyl) +
  geom_sf(fill = "red", alpha = 0.3) +
  geom_sf(data = cyl, fill = NA)

Plot SpatRaster contours

Description

These geoms create contours of SpatRaster objects. To specify a valid surface, you should specify the layer on aes(z = layer_name), otherwise all the layers are considered for creating contours. See also Facets section.

The underlying implementation is based on ggplot2::geom_contour().

geom_spatraster_contour_text() creates labeled contours and it is implemented on top of isoband::isolines_grob().

Usage

geom_spatraster_contour(
  mapping = NULL,
  data,
  ...,
  maxcell = 5e+05,
  bins = NULL,
  binwidth = NULL,
  breaks = NULL,
  na.rm = TRUE,
  show.legend = NA,
  inherit.aes = TRUE,
  mask_projection = FALSE
)

geom_spatraster_contour_text(
  mapping = NULL,
  data,
  ...,
  maxcell = 5e+05,
  bins = NULL,
  binwidth = NULL,
  breaks = NULL,
  size.unit = "mm",
  label_format = scales::label_number(),
  label_placer = isoband::label_placer_minmax(),
  na.rm = TRUE,
  show.legend = NA,
  inherit.aes = TRUE,
  mask_projection = FALSE
)

geom_spatraster_contour_filled(
  mapping = NULL,
  data,
  ...,
  maxcell = 5e+05,
  bins = NULL,
  binwidth = NULL,
  breaks = NULL,
  na.rm = TRUE,
  show.legend = NA,
  inherit.aes = TRUE,
  mask_projection = FALSE
)

Arguments

Value

A ggplot2 layer.

terra equivalent

terra::contour()

Aesthetics

geom_spatraster_contour() / geom_spatraster_contour_text() understands the following aesthetics:

• alpha

• colour

• group

• linetype

• linewidth geom_spatraster_contour_text() understands also:

• size

• label

• family

• fontface

Additionally, geom_spatraster_contour_filled() understands also the following aesthetics, as well as the ones listed above:

• fill

• subgroup

Check ggplot2::geom_contour() for more information on contours and vignette("ggplot2-specs", package = "ggplot2") for an overview of the aesthetics.

Computed variables

These geoms compute some variables internally that are available for use as aesthetics, using (for example) ⁠aes(color = after_stat(<computed>))⁠ (see ggplot2::after_stat()).

• after_stat(lyr): Name of the layer.

• after_stat(level): Height of contour. For contour lines, this is a numeric vector that represents bin boundaries. For contour bands, this is an ordered factor that represents bin ranges.

• after_stat(nlevel): Height of contour, scaled to maximum of 1.

• after_stat(level_low), after_stat(level_high),

• after_stat(level_mid): (contour bands only) Lower and upper bin boundaries for each band, as well as the midpoint between the boundaries.

Dropped variables

• z: After contouring, the z values of individual data points are no longer available.

Coords

When the SpatRaster does not have a CRS, that is, terra::crs(rast) == "", the geom does not make any assumption about the scales.

On SpatRaster objects that have a CRS, the geom uses ggplot2::coord_sf() to adjust the scales. This means that the SpatRaster may be reprojected.

Facets

You can use facet_wrap(~lyr) to create a faceted plot by each layer of the SpatRaster object. See ggplot2::facet_wrap() for details.

See Also

ggplot2::geom_contour().

The metR package also provides a set of alternative functions:

• metR::geom_contour2().

• metR::geom_text_contour() and metR::geom_label_contour().

• metR::geom_contour_tanaka().

Other ggplot2 helpers: autoplot.Spat, fortify.Spat, geom_spatraster(), geom_spatraster_rgb(), ggspatvector, stat_spat_coordinates()

Examples

library(terra)

# Raster
f <- system.file("extdata/volcano2.tif", package = "tidyterra")
r <- rast(f)

library(ggplot2)

ggplot() +
  geom_spatraster_contour(data = r)

# Labeled
ggplot() +
  geom_spatraster_contour_text(
    data = r, breaks = c(110, 130, 160, 190),
    color = "grey10", family = "serif"
  )

ggplot() +
  geom_spatraster_contour(
    data = r, aes(color = after_stat(level)),
    binwidth = 1,
    linewidth = 0.4
  ) +
  scale_color_gradientn(
    colours = hcl.colors(20, "Inferno"),
    guide = guide_coloursteps()
  ) +
  theme_minimal()

# Filled with breaks
ggplot() +
  geom_spatraster_contour_filled(data = r, breaks = seq(80, 200, 10)) +
  scale_fill_hypso_d()

# Both lines and contours
ggplot() +
  geom_spatraster_contour_filled(
    data = r, breaks = seq(80, 200, 10),
    alpha = 0.7
  ) +
  geom_spatraster_contour(
    data = r, breaks = seq(80, 200, 2.5),
    color = "grey30",
    linewidth = 0.1
  ) +
  scale_fill_hypso_d()

Plot SpatRaster objects

Description

This geom plots SpatRaster objects (see terra::rast()). It is designed to plot the object by layers, as terra::plot() does.

For plotting SpatRaster objects as map tiles, such as RGB SpatRaster objects, use geom_spatraster_rgb().

The underlying implementation is based on ggplot2::geom_raster().

stat_spatraster() complements geom_spatraster() when you need to change the geom.

Usage

geom_spatraster(
  mapping = aes(),
  data,
  na.rm = TRUE,
  show.legend = NA,
  inherit.aes = FALSE,
  interpolate = FALSE,
  maxcell = 5e+05,
  use_coltab = TRUE,
  mask_projection = FALSE,
  ...
)

stat_spatraster(
  mapping = aes(),
  data,
  geom = "raster",
  na.rm = TRUE,
  show.legend = NA,
  inherit.aes = FALSE,
  maxcell = 5e+05,
  ...
)

Arguments

Value

A ggplot2 layer.

terra equivalent

terra::plot()

Coords

When the SpatRaster does not have a CRS, that is, terra::crs(rast) == "", the geom does not make any assumption about the scales.

On SpatRaster objects that have a CRS, the geom uses ggplot2::coord_sf() to adjust the scales. This means that the SpatRaster may be reprojected.

Aesthetics

geom_spatraster() understands the following aesthetics:

• fill

• alpha

If fill is not provided, geom_spatraster() creates a ggplot2 layer with all the layers of the SpatRaster object. Use facet_wrap(~lyr) to display the SpatRaster layers.

If fill is used, it should contain the name of one layer that is present on the SpatRaster (for example, ⁠geom_spatraster(data = rast, aes(fill = <name_of_lyr>)⁠). Layer names can be retrieved using names(rast).

Using geom_spatraster(..., mapping = aes(fill = NULL)) or ⁠geom_spatraster(..., fill = <color value(s)>)⁠ creates a layer with no mapped fill aesthetic.

fill can use computed variables.

For alpha, use a computed variable. See section Computed variables.

stat_spatraster()

stat_spatraster() understands the same aesthetics as geom_spatraster() when geom = "raster" (the default):

• fill

• alpha

When geom = "raster", the fill argument behaves as in geom_spatraster(). If another geom is used, stat_spatraster() understands the aesthetics required by that geom, so ⁠aes(fill = <name_of_lyr>)⁠ is not applicable.

The x and y aesthetics are mapped by default, so you do not need to add them in aes(). In every case, aesthetics should be mapped with computed variables. See Computed variables and Examples.

Facets

You can use facet_wrap(~lyr) to create a faceted plot by each layer of the SpatRaster object. See ggplot2::facet_wrap() for details.

Computed variables

This geom computes internally some variables that are available for use as aesthetics, using (for example) aes(alpha = after_stat(value)) (see ggplot2::after_stat()).

• after_stat(value): Cell values of the SpatRaster.

• after_stat(lyr): Name of the layer.

Source

Based on the layer_spatial() implementation in ggspatial. Thanks to Dewey Dunnington and ggspatial contributors.

See Also

ggplot2::geom_raster(), ggplot2::coord_sf(), ggplot2::facet_wrap()

Recommended geoms:

• ggplot2::geom_point().

• ggplot2::geom_label().

• ggplot2::geom_text().

Other ggplot2 helpers: autoplot.Spat, fortify.Spat, geom_spat_contour, geom_spatraster_rgb(), ggspatvector, stat_spat_coordinates()

Examples

# Avg temperature on spring in Castile and Leon (Spain)
file_path <- system.file("extdata/cyl_temp.tif", package = "tidyterra")

library(terra)
temp_rast <- rast(file_path)

library(ggplot2)

# Display a single layer.
names(temp_rast)

ggplot() +
  geom_spatraster(data = temp_rast, aes(fill = tavg_04)) +
  # You can use coord_sf().
  coord_sf(crs = 3857) +
  scale_fill_grass_c(palette = "celsius")

# Display facets.
ggplot() +
  geom_spatraster(data = temp_rast) +
  facet_wrap(~lyr, ncol = 2) +
  scale_fill_grass_b(palette = "celsius", breaks = seq(0, 20, 2.5))

# Non-spatial rasters.

no_crs <- rast(crs = NA, extent = c(0, 100, 0, 100), nlyr = 1)
values(no_crs) <- seq_len(ncell(no_crs))

ggplot() +
  geom_spatraster(data = no_crs)

# Downsample.

ggplot() +
  geom_spatraster(data = no_crs, maxcell = 25)



# Using stat_spatraster
# Default
ggplot() +
  stat_spatraster(data = temp_rast) +
  facet_wrap(~lyr)

# Using points
ggplot() +
  stat_spatraster(
    data = temp_rast,
    aes(color = after_stat(value)),
    geom = "point", maxcell = 250
  ) +
  scale_colour_viridis_c(na.value = "transparent") +
  facet_wrap(~lyr)

# Using points and labels

r_single <- temp_rast |> select(1)

ggplot() +
  stat_spatraster(
    data = r_single,
    aes(color = after_stat(value)),
    geom = "point",
    maxcell = 2000
  ) +
  stat_spatraster(
    data = r_single,
    aes(label = after_stat(round(value, 2))),
    geom = "label",
    alpha = 0.85,
    maxcell = 20
  ) +
  scale_colour_viridis_c(na.value = "transparent")

Plot SpatRaster objects as images

Description

This geom plots SpatRaster objects (see terra::rast()) as RGB images. The layers are combined so they represent the red, green and blue channels.

For plotting SpatRaster objects by layer values use geom_spatraster().

The underlying implementation is based on ggplot2::geom_raster().

Usage

geom_spatraster_rgb(
  mapping = aes(),
  data,
  interpolate = TRUE,
  r = 1,
  g = 2,
  b = 3,
  alpha = 1,
  maxcell = 5e+05,
  max_col_value = 255,
  ...,
  stretch = NULL,
  zlim = NULL,
  mask_projection = FALSE
)

Arguments

Value

A ggplot2 layer.

terra equivalent

terra::plotRGB()

Aesthetics

No aes() is required. In fact, aes() will be ignored.

Coords

When the SpatRaster does not have a CRS, that is, terra::crs(rast) == "", the geom does not make any assumption about the scales.

On SpatRaster objects that have a CRS, the geom uses ggplot2::coord_sf() to adjust the scales. This means that the SpatRaster may be reprojected.

Source

Based on the layer_spatial() implementation in the ggspatial package. Thanks to Dewey Dunnington and to ggspatial contributors.

See Also

ggplot2::geom_raster(), ggplot2::coord_sf(), grDevices::rgb().

You can also get RGB tiles from the maptiles package. See maptiles::get_tiles().

Other ggplot2 helpers: autoplot.Spat, fortify.Spat, geom_spat_contour, geom_spatraster(), ggspatvector, stat_spat_coordinates()

Examples

# Tile of Castile and Leon (Spain) from OpenStreetMap
file_path <- system.file("extdata/cyl_tile.tif", package = "tidyterra")

library(terra)
tile <- rast(file_path)

library(ggplot2)

ggplot() +
  geom_spatraster_rgb(data = tile) +
  # You can use coord_sf
  coord_sf(crs = 3035)

# Combine with sf objects
vect_path <- system.file("extdata/cyl.gpkg", package = "tidyterra")

cyl_sf <- sf::st_read(vect_path)

ggplot(cyl_sf) +
  geom_spatraster_rgb(data = tile) +
  geom_sf(aes(fill = iso2)) +
  coord_sf(crs = 3857) +
  scale_fill_viridis_d(alpha = 0.7)

Plot SpatVector objects

Description

Wrappers of the ggplot2::geom_sf() family used to plot SpatVector objects (see terra::vect()).

Usage

geom_spatvector(
  mapping = aes(),
  data = NULL,
  na.rm = FALSE,
  show.legend = NA,
  ...
)

geom_spatvector_label(
  mapping = aes(),
  data = NULL,
  na.rm = FALSE,
  show.legend = NA,
  ...,
  linewidth = 0.25,
  inherit.aes = TRUE
)

geom_spatvector_text(
  mapping = aes(),
  data = NULL,
  na.rm = FALSE,
  show.legend = NA,
  ...,
  check_overlap = FALSE,
  inherit.aes = TRUE
)

stat_spatvector(
  mapping = NULL,
  data = NULL,
  geom = "rect",
  position = "identity",
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE,
  ...
)

Arguments

Details

These functions are wrappers of ggplot2::geom_sf() functions. Since a fortify.SpatVector() method is provided, ggplot2 treat a SpatVector in the same way that a sf object. A side effect is that you can use ggplot2::geom_sf() directly with SpatVector objects.

See ggplot2::geom_sf() for details on aesthetics, etc.

Value

A ggplot2 layer.

terra equivalent

terra::plot()

See Also

ggplot2::geom_sf()

Other ggplot2 helpers: autoplot.Spat, fortify.Spat, geom_spat_contour, geom_spatraster(), geom_spatraster_rgb(), stat_spat_coordinates()

Examples

# Create a SpatVector
extfile <- system.file("extdata/cyl.gpkg", package = "tidyterra")

cyl <- terra::vect(extfile)
class(cyl)

library(ggplot2)

ggplot(cyl) +
  geom_spatvector()

# With params

ggplot(cyl) +
  geom_spatvector(aes(fill = name), color = NA) +
  scale_fill_viridis_d() +
  coord_sf(crs = 3857)

# Add labels
ggplot(cyl) +
  geom_spatvector(aes(fill = name), color = NA) +
  geom_spatvector_text(aes(label = iso2),
    fontface = "bold",
    color = "red"
  ) +
  scale_fill_viridis_d(alpha = 0.4) +
  coord_sf(crs = 3857)

# You can use now geom_sf with SpatVectors!

ggplot(cyl) +
  geom_sf() +
  labs(
    title = paste("cyl is", as.character(class(cyl))),
    subtitle = "With geom_sf()"
  )

Glance at an ⁠Spat*⁠ object

Description

Glance accepts a model object and returns a tibble::tibble() with exactly one row of Spat. The summaries are typically geographic information.

Usage

## S3 method for class 'SpatRaster'
glance(x, ...)

## S3 method for class 'SpatVector'
glance(x, ...)

Arguments

Value

glance() methods always return a one-row data frame. See Methods.

Methods

Implementation of the generic generics::glance() method for ⁠Spat*⁠ objects.

See Also

glimpse.Spat, generics::glance().

Other generics methods: required_pkgs.Spat, tidy.Spat

Examples

library(terra)

# SpatVector
v <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

glance(v)

# SpatRaster
r <- rast(system.file("extdata/cyl_elev.tif", package = "tidyterra"))

glance(r)

Preview ⁠Spat*⁠ objects

Description

glimpse() is like a transposed version of print(): layers/columns run down the page and data runs across. This makes it possible to see every layer/column in a ⁠Spat*⁠ object.

Usage

## S3 method for class 'SpatRaster'
glimpse(x, width = NULL, ..., n = 10, max_extra_cols = 20)

## S3 method for class 'SpatVector'
glimpse(x, width = NULL, ..., n = 10, max_extra_cols = 20)

Arguments

Value

Original x is invisibly returned, allowing glimpse() to be used within a data pipeline.

terra equivalent

print()

Methods

Implementation of the generic dplyr::glimpse() function for ⁠Spat*⁠ objects.

See Also

tibble::print.tbl_df()

Other dplyr verbs that operate on columns: mutate.Spat, pull.Spat, relocate.Spat, rename.Spat, select.Spat

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)

# SpatVector
v <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

v |> glimpse(n = 2)

# Use on a pipeline
v |>
  glimpse() |>
  mutate(a = 30) |>
  # With options.
  glimpse(geom = "WKT")

# SpatRaster
r <- rast(system.file("extdata/cyl_elev.tif", package = "tidyterra"))

r |> glimpse()

# Use on a pipeline
r |>
  glimpse() |>
  mutate(b = elevation_m / 100) |>
  # With options
  glimpse(xy = TRUE)

GRASS color tables

Description

A tibble including the color map of 51 gradient palettes. Some palettes also include a definition of color limits that can be used with ggplot2::scale_fill_gradientn().

Format

A tibble of 2920 rows and 6 columns with the following fields:

pal

Name of the palette.

limit

(Optional) limit for each color.

r

Value of the red channel (RGB color mode).

g

Value of the green channel (RGB color mode).

b

Value of the blue channel (RGB color mode).

hex

Hex code of the color.

Details

Summary of palettes provided, description and recommended use:

terra equivalent

terra::map.pal()

Source

Derived from https://github.com/OSGeo/grass/tree/main/lib/gis/colors. See also r.color - GRASS GIS Manual.

References

GRASS Development Team (2024). Geographic Resources Analysis Support System (GRASS) Software, Version 8.3.2. Open Source Geospatial Foundation, USA. https://grass.osgeo.org.

See Also

scale_fill_grass_c()

Other datasets: cross_blended_hypsometric_tints_db, hypsometric_tints_db, princess_db, volcano2

Examples

data("grass_db")

grass_db
# Select a palette

srtm_plus <- grass_db |>
  filter(pal == "srtm_plus")

f <- system.file("extdata/asia.tif", package = "tidyterra")
r <- terra::rast(f)

library(ggplot2)

p <- ggplot() +
  geom_spatraster(data = r) +
  labs(fill = "elevation")

p +
  scale_fill_gradientn(colors = srtm_plus$hex)

# Use with limits
p +
  scale_fill_gradientn(
    colors = srtm_plus$hex,
    values = scales::rescale(srtm_plus$limit),
    limit = range(srtm_plus$limit),
    na.value = "lightblue"
  )

Group a SpatVector by one or more variables

Description

Most data operations are done on groups defined by variables. group_by.SpatVector() adds new attributes to an existing SpatVector indicating the corresponding groups. See Methods.

Usage

## S3 method for class 'SpatVector'
group_by(.data, ..., .add = FALSE, .drop = group_by_drop_default(.data))

## S3 method for class 'SpatVector'
ungroup(x, ...)

Arguments

Details

See Details on dplyr::group_by().

Value

A SpatVector object with updated grouping metadata.

Methods

Implementation of the generic dplyr::group_by() family functions for SpatVector objects.

When mixing terra and dplyr syntax on a grouped SpatVector, for example subsetting a SpatVector like v[1:3,1:2], the groups attribute can be corrupted. tidyterra tries to re-group the SpatVector. This is triggered the next time you use a dplyr verb on your SpatVector.

Some operations, such as terra::spatSample(), create a new SpatVector. In these cases, the result does not preserve the groups attribute. Use group_by() to re-group.

See Also

dplyr::group_by(), dplyr::ungroup()

Other dplyr verbs that operate on groups of rows: count.SpatVector(), reframe.SpatVector(), rowwise.SpatVector(), summarise.SpatVector()

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Other dplyr grouping methods: group_map.SpatVector(), group_nest.SpatVector(), group_split.SpatVector(), group_trim.SpatVector()

Examples

library(terra)
f <- system.file("ex/lux.shp", package = "terra")
p <- vect(f)

by_name1 <- p |> group_by(NAME_1)

# Grouping does not change how the SpatVector looks.
by_name1

# But it adds metadata for grouping. See the coercion to tibble.

# Not grouped.
p_tbl <- as_tibble(p)
class(p_tbl)
head(p_tbl, 3)

# Grouped.
by_name1_tbl <- as_tibble(by_name1)
class(by_name1_tbl)
head(by_name1_tbl, 3)

# It changes how it acts with the other dplyr verbs:
by_name1 |> summarise(
  pop = mean(POP),
  area = sum(AREA)
)

# Each call to summarise() removes a layer of grouping.
by_name2_name1 <- p |> group_by(NAME_2, NAME_1)

by_name2_name1
group_data(by_name2_name1)

by_name2 <- by_name2_name1 |> summarise(n = dplyr::n())
by_name2
group_data(by_name2)

# To remove grouping, use ungroup().
by_name2 |>
  ungroup() |>
  summarise(n = sum(n))

# By default, group_by() overrides existing grouping.
by_name2_name1 |>
  group_by(ID_1, ID_2) |>
  group_vars()

# Use add = TRUE to append instead.
by_name2_name1 |>
  group_by(ID_1, ID_2, .add = TRUE) |>
  group_vars()

# You can group by expressions. This is shorthand for a mutate() followed
# by a group_by().
p |>
  group_by(ID_COMB = ID_1 * 100 / ID_2) |>
  relocate(ID_COMB, .before = 1)

Grouping metadata for SpatVector objects

Description

This collection of functions accesses data about grouped SpatVector objects in various ways:

• group_data() returns a tibble that defines the grouping structure. The columns give the values of the grouping variables. The last column, always called .rows, is a list of integer vectors that gives the location of the rows in each group.

• group_keys() returns a tibble describing the groups.

• group_rows() returns a list of integer vectors giving the rows that each group contains.

• group_indices() returns an integer vector the same length as .data that gives the group that each row belongs to.

• group_vars() gives names of grouping variables as character vector.

• groups() gives the names of the grouping variables as a list of symbols.

• group_size() gives the size of each group.

• n_groups() gives the total number of groups.

See dplyr::group_data().

Usage

## S3 method for class 'SpatVector'
group_data(.data)

## S3 method for class 'SpatVector'
group_keys(.tbl, ...)

## S3 method for class 'SpatVector'
group_indices(.data, ...)

## S3 method for class 'SpatVector'
group_vars(x)

## S3 method for class 'SpatVector'
groups(x)

## S3 method for class 'SpatVector'
group_size(x)

## S3 method for class 'SpatVector'
n_groups(x)

Arguments

Value

See the description of the method. The results are usually tibbles, lists or vectors. These functions do not return SpatVector objects.

Examples

library(terra)

v <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
v$gr_1 <- rep_len(c("A", "A", "B"), length.out = nrow(v))
v$gr_2 <- rep_len(c("C", "D"), length.out = nrow(v))

# Ungrouped

n_groups(v)

group_vars(v)

group_keys(v)

group_size(v)

groups(v)

group_rows(v)

group_data(v)

group_indices(v)

# Grouped by one var
gv <- group_by(v, gr_1)

n_groups(gv)

group_vars(gv)

group_keys(gv)

group_size(gv)

groups(gv)

group_rows(gv)

group_data(gv)

group_indices(gv)

# Grouped by several vars

gv2 <- group_by(v, gr_1, gr_2)

n_groups(gv2)

group_vars(gv2)

group_keys(gv2)

group_size(gv2)

groups(gv2)

group_rows(gv2)

group_data(gv2)

group_indices(gv2)

Apply a function to each SpatVector group

Description

dplyr::group_map() and dplyr::group_modify() are purrr-style functions that can be used to iterate on grouped SpatVector objects.

Usage

## S3 method for class 'SpatVector'
group_map(.data, .f, ..., .keep = FALSE)

## S3 method for class 'SpatVector'
group_modify(.data, .f, ..., .keep = FALSE)

Arguments

Details

Each conceptual group is exposed to .f with two pieces of information: .x, the subset of rows for the group as a SpatVector, and .y, a one-row tibble with one column per grouping variable that identifies the group.

These methods also work on ungrouped SpatVector objects. In that case, .f is applied to the entire object and .y is a one-row tibble with no columns.

Value

• group_map() returns a list of results from calling .f on each group.

• group_modify() returns a SpatVector. In that case, .f must return SpatVector objects.

Methods

Implementation of the generic dplyr::group_map() family for SpatVector objects.

SpatVector

group_map() applies .f to each group and returns a list. group_modify() requires .f to return SpatVector objects and binds the results.

See Also

dplyr::group_map() and dplyr::group_modify().

Other dplyr grouping methods: group_by.SpatVector(), group_nest.SpatVector(), group_split.SpatVector(), group_trim.SpatVector()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
v$grp <- rep(c("A", "B"), length.out = nrow(v))

group_map(group_by(v, grp), ~ nrow(.x))

group_modify(group_by(v, grp), ~ mutate(.x, key = .y$grp))

Nest grouped SpatVector rows

Description

group_nest() and nest_by() create tibbles with list-columns containing SpatVector objects.

Usage

## S3 method for class 'SpatVector'
group_nest(.tbl, ..., .key = "data", keep = FALSE)

## S3 method for class 'SpatVector'
nest_by(.data, ..., .key = "data", .keep = FALSE)

Arguments

Value

A tibble with a list-column of SpatVector objects.

terra equivalent

terra::svc().

Methods

Implementation of the generic dplyr::group_nest() family for SpatVector objects.

SpatVector

The nested list-column contains SpatVector objects, preserving the geometries for each group.

See Also

dplyr::group_nest(), dplyr::nest_by(), nest.SpatVector(), terra::svc()

Other dplyr grouping methods: group_by.SpatVector(), group_map.SpatVector(), group_split.SpatVector(), group_trim.SpatVector()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
v$grp <- rep(c("A", "B"), length.out = nrow(v))

group_nest(v, grp)

nest_by(v, grp)

# Convert to a named SpatVectorCollection.
nested <- group_nest(v, grp)

sv <- pull(nested, data)
names(sv) <- pull(nested, grp)

terra::svc(sv)

Split SpatVector by groups

Description

group_split() works like base::split() but:

• It uses the grouping structure from group_by.SpatVector() and therefore is subject to the data mask.

• It does not name the elements of the list based on the grouping as this only works well for a single character grouping variable. Instead, use group_keys.SpatVector() to access a data frame that defines the groups.

See dplyr::group_split() for more information.

Usage

## S3 method for class 'SpatVector'
group_split(.tbl, ..., .keep = TRUE)

Arguments

Details

See Details on dplyr::group_split().

Value

A list of SpatVector objects. Each SpatVector contains the rows of .tbl for the associated group and all columns. When .keep = TRUE, the output includes the grouping variables.

Lifecycle

group_split() is not stable because you can achieve very similar results by manipulating the nested column returned from nest(.by =). That also retains the group keys all within a single data structure. group_split() may be deprecated in the future.

terra equivalent

terra::svc().

Methods

Implementation of the generic dplyr::group_split() for SpatVector objects.

See Also

dplyr::group_split(), terra::svc()

Other dplyr grouping methods: group_by.SpatVector(), group_map.SpatVector(), group_nest.SpatVector(), group_trim.SpatVector()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

v$group <- rep(c("A", "B", "C"), 3)

v |>
  group_by(group) |>
  group_split()

# Coerce the result to a SpatVectorCollection.
v |>
  group_by(group) |>
  group_split() |>
  terra::svc()

Trim grouping structure

Description

This method drops unused levels of all factors that are used as grouping variables and recalculates the grouping structure.

group_trim() is particularly useful after a filter() that is intended to select a subset of groups.

Usage

## S3 method for class 'SpatVector'
group_trim(.tbl, .drop = group_by_drop_default(.tbl))

Arguments

Details

See Details on dplyr::group_trim().

Value

A SpatVector object with updated grouping metadata.

Methods

Implementation of the generic dplyr::group_trim() for SpatVector objects.

See Also

dplyr::group_trim().

Other dplyr grouping methods: group_by.SpatVector(), group_map.SpatVector(), group_nest.SpatVector(), group_split.SpatVector()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

v$group <- rep(c("A", "B", "C"), 3)

v |>
  group_by(group) |>
  filter(group == "B", .preserve = TRUE) |>
  group_trim()

Hypsometric palettes database

Description

A tibble including the color map of 33 gradient palettes. Each palette also includes a definition of color limits in terms of elevation (meters) that can be used with ggplot2::scale_fill_gradientn().

Format

A tibble of 1102 rows and 6 columns with the following fields:

pal

Name of the palette.

limit

Recommended elevation limit (in meters) for each color.

r

Value of the red channel (RGB color mode).

g

Value of the green channel (RGB color mode).

b

Value of the blue channel (RGB color mode).

hex

Hex code of the color.

Source

cpt-city: https://phillips.shef.ac.uk/pub/cpt-city/.

See Also

scale_fill_hypso_c()

Other datasets: cross_blended_hypsometric_tints_db, grass_db, princess_db, volcano2

Examples

data("hypsometric_tints_db")

hypsometric_tints_db

# Select a palette
wikicols <- hypsometric_tints_db |>
  filter(pal == "wiki-2.0")

f <- system.file("extdata/asia.tif", package = "tidyterra")
r <- terra::rast(f)

library(ggplot2)

p <- ggplot() +
  geom_spatraster(data = r) +
  labs(fill = "elevation")

p +
  scale_fill_gradientn(colors = wikicols$hex)

# Use with limits
p +
  scale_fill_gradientn(
    colors = wikicols$hex,
    values = scales::rescale(wikicols$limit),
    limit = range(wikicols$limit)
  )

A grouped SpatVector

Description

The easiest way to create a grouped SpatVector is to call the group_by() method on a SpatVector: this will take care of capturing the unevaluated expressions for you. See group_by.SpatVector() for details.

This function is the adapted version of dplyr::is_grouped_df().

See also group_data.SpatVector() for the accessory functions that retrieve various metadata from a grouped SpatVector.

Usage

is_grouped_spatvector(x)

Arguments

Value

TRUE if x is a grouped SpatVector, otherwise FALSE.

See Also

Other helpers: compare_spatrasters(), is_regular_grid(), pull_crs()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

is_grouped_spatvector(v)

grouped <- group_by(v, iso2)

is_grouped_spatvector(grouped)

Check whether x and y positions form a regular grid

Description

Assess whether the x and y coordinates of an object form a regular grid. This function is called for its side effects.

This function is internally called by as_spatraster().

Usage

is_regular_grid(xy, digits = 6)

Arguments

Value

invisible() if the coordinates form a regular grid. Otherwise, an error.

See Also

as_spatraster()

Other helpers: compare_spatrasters(), is_grouped_spatvector(), pull_crs()

Examples

p <- matrix(1:90, nrow = 45, ncol = 2)

is_regular_grid(p)

# Jitter locations.
set.seed(1234)
jitter <- runif(length(p)) / 10e4
p_jitter <- p + jitter

# Adjust digits.
is_regular_grid(p_jitter, digits = 4)

Mutating joins for SpatVector objects

Description

Mutating joins add columns from y to x, matching observations based on the keys. The four mutating joins are: inner join, left join, right join and full join.

See dplyr::inner_join() for details.

Usage

## S3 method for class 'SpatVector'
inner_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

## S3 method for class 'SpatVector'
left_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

## S3 method for class 'SpatVector'
right_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

## S3 method for class 'SpatVector'
full_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  suffix = c(".x", ".y"),
  ...,
  keep = NULL
)

Arguments

Value

A SpatVector object.

terra equivalent

terra::merge()

Methods

Implementation of the generic dplyr::inner_join() family

SpatVector

The geometry column has sticky behavior. This means that the result always has the geometry of x for the records that match the join conditions.

For right_join() and full_join(), empty geometries may be returned (since y is expected to be a data frame with no geometries). Although these join operations are not common in spatial workflows, the function may crash because handling of EMPTY geometries differs between terra and sf.

See Also

dplyr::inner_join(), dplyr::left_join(), dplyr::right_join(), dplyr::full_join(), terra::merge()

Other dplyr verbs that operate on pairs of SpatVector and data frame objects: bind_cols.SpatVector, bind_rows.SpatVector, cross_join.SpatVector(), filter-joins.SpatVector, nest_join.SpatVector(), rows.SpatVector

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
library(ggplot2)
# Vector
v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

# A data frame
df <- data.frame(
  cpro = sprintf("%02d", 1:10),
  x = runif(10),
  y = runif(10),
  letter = rep_len(LETTERS[1:3], length.out = 10)
)

# Inner join
inner <- v |> inner_join(df)

nrow(inner)
autoplot(inner, aes(fill = letter)) + labs(title = "Inner Join")

# Left join

left <- v |> left_join(df)
nrow(left)

autoplot(left, aes(fill = letter)) + labs(title = "Left Join")


# Right join
right <- v |> right_join(df)
nrow(right)

autoplot(right, aes(fill = letter)) + labs(title = "Right Join")

# There are empty geometries, check with data from df
ggplot(right, aes(x, y)) +
  geom_point(aes(color = letter))

# Full join
full <- v |> full_join(df)
nrow(full)

autoplot(full, aes(fill = letter)) + labs(title = "Full Join")

# Check with data from df
ggplot(full, aes(x, y)) +
  geom_point(aes(color = letter))

Create, modify and delete cell values/layers/attributes of ⁠Spat*⁠ objects

Description

mutate() adds new layers/attributes and preserves existing ones on a ⁠Spat*⁠ object.

Usage

## S3 method for class 'SpatRaster'
mutate(
  .data,
  ...,
  .keep = c("all", "used", "unused", "none"),
  .before = NULL,
  .after = NULL
)

## S3 method for class 'SpatVector'
mutate(
  .data,
  ...,
  .by = NULL,
  .keep = c("all", "used", "unused", "none"),
  .before = NULL,
  .after = NULL
)

Arguments

Value

A ⁠Spat*⁠ object of the same class as .data. See Methods.

terra equivalent

Some terra methods for modifying cell values: terra::ifel(), terra::classify(), terra::clamp(), terra::app(), terra::lapp(), terra::tapp()

Methods

Implementation of the generic dplyr::mutate() method.

SpatRaster

Add new layers and preserves existing ones. The result is a SpatRaster with the same extent, resolution and CRS as .data. Only the values (and possibly the number) of layers is modified.

SpatVector

The result is a SpatVector with the modified (and possibly renamed) attributes on the function call.

See Also

dplyr::mutate() methods.

terra provides several ways to modify ⁠Spat*⁠ objects:

• terra::ifel().

• terra::classify().

• terra::clamp().

• terra::app(), terra::lapp(), terra::tapp().

Other dplyr single-table verbs: arrange.SpatVector(), filter.Spat, reframe.SpatVector(), rename.Spat, select.Spat, slice.Spat, summarise.SpatVector()

Other dplyr verbs that operate on columns: glimpse.Spat, pull.Spat, relocate.Spat, rename.Spat, select.Spat

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)

# SpatRaster method
f <- system.file("extdata/cyl_temp.tif", package = "tidyterra")
spatrast <- rast(f)

mod <- spatrast |>
  mutate(exp_lyr1 = exp(tavg_04 / 10)) |>
  select(tavg_04, exp_lyr1)

mod
plot(mod)

# SpatVector method
f <- system.file("extdata/cyl.gpkg", package = "tidyterra")
v <- vect(f)

v |>
  mutate(cpro2 = paste0(cpro, "-CyL")) |>
  select(cpro, cpro2)

Nest SpatVector rows

Description

nest() creates list-columns of SpatVector objects.

Usage

## S3 method for class 'SpatVector'
nest(.data, ..., .by = NULL, .key = NULL, .names_sep = NULL)

Arguments

Value

A tibble with one or more list-columns of SpatVector objects.

terra equivalent

terra::svc().

Methods

Implementation of the generic tidyr::nest() method.

SpatVector

The geometry column must be nested with the other attributes that form each nested SpatVector. These nested list-columns contain SpatVector objects and cannot be passed directly to tidyr::unnest().

See Also

tidyr::nest(), terra::svc()

Other tidyr methods: complete.SpatVector(), drop_na.Spat, expand.SpatVector(), fill.SpatVector(), pivot_longer.SpatVector(), pivot_wider.SpatVector(), replace_na.Spat, uncount.SpatVector(), unite.Spat

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

v |>
  group_by(cpro) |>
  nest()

# Convert to a named SpatVectorCollection.
nested <- nest(v, .by = cpro)

sv <- pull(nested, data)
names(sv) <- pull(nested, cpro)

terra::svc(sv)

Nest join SpatVector objects

Description

nest_join() returns a tibble with the attributes and geometry of x, plus a list-column containing matching rows from y.

Usage

## S3 method for class 'SpatVector'
nest_join(
  x,
  y,
  by = NULL,
  copy = FALSE,
  keep = NULL,
  name = NULL,
  ...,
  na_matches = c("na", "never")
)

Arguments

Value

A tibble.

Methods

Implementation of the generic dplyr::nest_join() method.

SpatVector

The output is a tibble with the attributes and WKT geometry of x, plus a list-column with matching rows from y.

See Also

dplyr::nest_join()

Other dplyr verbs that operate on pairs of SpatVector and data frame objects: bind_cols.SpatVector, bind_rows.SpatVector, cross_join.SpatVector(), filter-joins.SpatVector, mutate-joins.SpatVector, rows.SpatVector

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
extra <- tibble::tibble(cpro = c("05", "09"), value = c(1, 2))

nest_join(v, extra, by = "cpro")

Pivot SpatVector from wide to long

Description

pivot_longer() "lengthens" data, increasing the number of rows and decreasing the number of columns. The inverse transformation is pivot_wider.SpatVector()

Learn more in tidyr::pivot_longer().

Usage

## S3 method for class 'SpatVector'
pivot_longer(
  data,
  cols,
  ...,
  cols_vary = "fastest",
  names_to = "name",
  names_prefix = NULL,
  names_sep = NULL,
  names_pattern = NULL,
  names_ptypes = NULL,
  names_transform = NULL,
  names_repair = "check_unique",
  values_to = "value",
  values_drop_na = FALSE,
  values_ptypes = NULL,
  values_transform = NULL
)

Arguments

Value

A SpatVector object.

Methods

Implementation of the generic tidyr::pivot_longer() method.

SpatVector

The geometry column has sticky behavior. This means that the result always has the geometry of data.

See Also

tidyr::pivot_longer()

Other tidyr verbs for pivoting: pivot_wider.SpatVector()

Other tidyr methods: complete.SpatVector(), drop_na.Spat, expand.SpatVector(), fill.SpatVector(), nest.SpatVector(), pivot_wider.SpatVector(), replace_na.Spat, uncount.SpatVector(), unite.Spat

Examples

library(dplyr)
library(tidyr)
library(ggplot2)
library(terra)

temp <- rast((system.file("extdata/cyl_temp.tif", package = "tidyterra")))
cyl <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra")) |>
  project(temp)

# Add average temp

temps <- terra::extract(temp, cyl, fun = "mean", na.rm = TRUE, xy = TRUE)
cyl_temp <- cbind(cyl, temps) |>
  glimpse()

# And pivot long for plot
cyl_temp |>
  pivot_longer(
    cols = tavg_04:tavg_06,
    names_to = "label",
    values_to = "temp"
  ) |>
  ggplot() +
  geom_spatvector(aes(fill = temp)) +
  facet_wrap(~label, ncol = 1) +
  scale_fill_whitebox_c(palette = "muted")

Pivot SpatVector from long to wide

Description

pivot_wider() "widens" a SpatVector, increasing the number of columns and decreasing the number of rows. The inverse transformation is pivot_longer.SpatVector().

Usage

## S3 method for class 'SpatVector'
pivot_wider(
  data,
  ...,
  id_cols = NULL,
  id_expand = FALSE,
  names_from = "name",
  names_prefix = "",
  names_sep = "_",
  names_glue = NULL,
  names_sort = FALSE,
  names_vary = "fastest",
  names_expand = FALSE,
  names_repair = "check_unique",
  values_from = "value",
  values_fill = NULL,
  values_fn = NULL,
  unused_fn = NULL
)

Arguments

Value

A SpatVector object.

Methods

Implementation of the generic tidyr::pivot_wider() method.

SpatVector

The geometry column has sticky behavior. This means that the result always has the geometry of data.

See Also

tidyr::pivot_wider()

Other tidyr verbs for pivoting: pivot_longer.SpatVector()

Other tidyr methods: complete.SpatVector(), drop_na.Spat, expand.SpatVector(), fill.SpatVector(), nest.SpatVector(), pivot_longer.SpatVector(), replace_na.Spat, uncount.SpatVector(), unite.Spat

Examples

library(dplyr)
library(tidyr)
library(ggplot2)

cyl <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

# Add an extra row with information.
xtra <- cyl |>
  slice(c(2, 3)) |>
  mutate(
    label = "extra",
    value = TRUE
  ) |>
  rbind(cyl) |>
  glimpse()

# Pivot by geometry.
xtra |>
  pivot_wider(
    id_cols = iso2:name, values_from = value,
    names_from = label
  )

Princess palettes database

Description

A tibble including the color map of 15 gradient palettes.

Format

A tibble of 75 rows and 5 columns with the following fields:

pal

Name of the palette.

r

Value of the red channel (RGB color mode).

g

Value of the green channel (RGB color mode).

b

Value of the blue channel (RGB color mode).

hex

Hex code of the color.

Source

https://leahsmyth.github.io/Princess-Colour-Schemes/index.html.

See Also

scale_fill_princess_c()

Other datasets: cross_blended_hypsometric_tints_db, grass_db, hypsometric_tints_db, volcano2

Examples

data("princess_db")

princess_db

# Select a palette
maori <- princess_db |>
  filter(pal == "maori")

f <- system.file("extdata/volcano2.tif", package = "tidyterra")
r <- terra::rast(f)

library(ggplot2)

p <- ggplot() +
  geom_spatraster(data = r) +
  labs(fill = "elevation")

p +
  scale_fill_gradientn(colors = maori$hex)

Extract a single layer/attribute

Description

pull() is similar to $ on a data frame. It is mostly useful because it looks nicer in pipes and can optionally name the output.

You can extract the geographic coordinates of a SpatRaster. Use pull(.data, x, xy = TRUE). x and y are reserved names on terra, since they refer to the geographic coordinates of the layer.

See Examples and section About layer names on as_tibble.Spat().

Usage

## S3 method for class 'SpatRaster'
pull(.data, var = -1, name = NULL, ...)

## S3 method for class 'SpatVector'
pull(.data, var = -1, name = NULL, ...)

Arguments

Value

A vector the same number of cells/geometries as .data.

On SpatRaster objects, note that the default (na.rm = FALSE) removes empty cells, so you may need to pass (na.rm = FALSE) to .... See terra::as.data.frame().

terra equivalent

terra::values()

Methods

Implementation of the generic dplyr::pull() method. This is done by coercing the ⁠Spat*⁠ object to a tibble first (see as_tibble.Spat) and then using dplyr::pull() method over the tibble.

SpatRaster

When passing option na.rm = TRUE to ..., only cells with a value distinct to NA are extracted. See terra::as.data.frame().

If xy = TRUE option is passed to ..., two columns names x and y (corresponding to the geographic coordinates of each cell) are available in position 1 and 2. Hence, pull(.data, 1) and pull(.data, 1, xy = TRUE) return different result.

SpatVector

When passing geom = "WKT"/geom = "HEX" to ..., the geometry of the SpatVector can be pulled passing var = geometry. Similarly to SpatRaster method, when using geom = "XY" the ⁠x,y⁠ coordinates can be pulled with var = x/var = y. See terra::as.data.frame() options.

See Also

dplyr::pull()

Other dplyr verbs that operate on columns: glimpse.Spat, mutate.Spat, relocate.Spat, rename.Spat, select.Spat

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
f <- system.file("extdata/cyl_tile.tif", package = "tidyterra")
r <- rast(f)

# Extract second layer
r |>
  pull(2) |>
  head()

# With xy the first two cols are `x` (longitude) and `y` (latitude)

r |>
  pull(2, xy = TRUE) |>
  head()

# With renaming

r |>
  mutate(cat = cut(cyl_tile_3, c(0, 100, 300))) |>
  pull(cyl_tile_3, name = cat) |>
  head()

Extract CRS in WKT format

Description

Extract the WKT version of the CRS associated with a string, number or ⁠sf/Spat*⁠ object. Well-known text (WKT) is a character string representation of coordinate reference systems (CRS). It identifies the parameters of each CRS precisely and is the standard used by sf and terra.

Usage

pull_crs(.data, ...)

Arguments

Details

Although the WKT representation is the same, the sf and terra APIs differ slightly. For example, sf can do:

sf::st_transform(x, 25830)

While the terra equivalent is:

terra::project(bb, "epsg:25830")

Knowing the WKT helps smooth workflows when working with different packages and object types.

Value

A WKT representation of the corresponding CRS.

Internals

A thin wrapper around sf::st_crs() and terra::crs().

See Also

terra::crs() and sf::st_crs() to learn how these packages handle CRS definitions.

Other helpers: compare_spatrasters(), is_grouped_spatvector(), is_regular_grid()

Examples

# sf objects.

sfobj <- sf::st_as_sfc("MULTIPOINT ((0 0), (1 1))", crs = 4326)

fromsf1 <- pull_crs(sfobj)
fromsf2 <- pull_crs(sf::st_crs(sfobj))

# terra objects.

v <- terra::vect(sfobj)
r <- terra::rast(v)

fromterra1 <- pull_crs(v)
fromterra2 <- pull_crs(r)

# Integers.
fromint <- pull_crs(4326)

# Characters.
fromchar <- pull_crs("epsg:4326")

all(
  fromsf1 == fromsf2,
  fromsf2 == fromterra1,
  fromterra1 == fromterra2,
  fromterra2 == fromint,
  fromint == fromchar
)

cat(fromsf1)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

dplyr

add_count(), anti_join(), arrange(), count(), cross_join(), distinct(), filter(), filter_out(), full_join(), glimpse, group_by(), group_by_drop_default(), group_data(), group_indices(), group_keys(), group_map(), group_modify(), group_nest(), group_rows(), group_size(), group_split(), group_trim(), group_vars(), groups(), groups(), inner_join(), left_join(), mutate(), n_groups(), nest_by(), nest_join(), pull(), reframe(), relocate(), rename(), rename_with(), right_join(), rows_append(), rows_delete(), rows_insert(), rows_patch(), rows_update(), rows_upsert(), rowwise(), select(), semi_join(), slice(), slice_head(), slice_max(), slice_min(), slice_sample(), slice_tail(), summarise(), summarize(), tally(), transmute(), ungroup()

generics

glance(), required_pkgs(), tidy()

ggplot2

aes(), after_stat(), autoplot(), fortify()

tibble

as_tibble()

tidyr

complete(), drop_na(), expand(), fill(), nest(), pivot_longer(), pivot_wider(), replace_na(), uncount(), unite()

Reframe each group of a SpatVector

Description

reframe() can return any number of rows per group. The geometry of each group is aggregated and repeated for each row created for that group.

Usage

## S3 method for class 'SpatVector'
reframe(.data, ..., .by = NULL, .dissolve = TRUE)

Arguments

Value

A SpatVector.

Methods

Implementation of the generic dplyr::reframe() method.

SpatVector

For grouped inputs, and for calls using .by, geometries are aggregated per group. If a group produces more than one row, the aggregated group geometry is repeated for each output row.

See Also

dplyr::reframe(), summarise.SpatVector()

Other dplyr single-table verbs: arrange.SpatVector(), filter.Spat, mutate.Spat, rename.Spat, select.Spat, slice.Spat, summarise.SpatVector()

Other dplyr verbs that operate on groups of rows: count.SpatVector(), group_by.SpatVector(), rowwise.SpatVector(), summarise.SpatVector()

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, relocate.Spat, rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
v$grp <- rep(c("A", "B"), length.out = nrow(v))

v |>
  reframe(value = c(min(as.double(cpro)), max(as.double(cpro))), .by = grp)

v |>
  rowwise() |>
  reframe(value = 1:2)

Change layer/attribute order

Description

Use relocate() to change layer/attribute positions, using the same syntax as select.Spat to make it easy to move blocks of layers/attributes at once.

Usage

## S3 method for class 'SpatRaster'
relocate(.data, ..., .before = NULL, .after = NULL)

## S3 method for class 'SpatVector'
relocate(.data, ..., .before = NULL, .after = NULL)

Arguments

Value

A ⁠Spat*⁠ object of the same class as .data. See Methods.

terra equivalent

terra::subset(data, c("name_layer", "name_other_layer"))

Methods

Implementation of the generic dplyr::relocate() method.

SpatRaster

Relocate layers of a SpatRaster.

SpatVector

The result is a SpatVector with the attributes on a different order.

See Also

dplyr::relocate()

Other dplyr verbs that operate on columns: glimpse.Spat, mutate.Spat, pull.Spat, rename.Spat, select.Spat

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), rename.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)

f <- system.file("extdata/cyl_tile.tif", package = "tidyterra")
spatrast <- rast(f) |> mutate(aa = 1, bb = 2, cc = 3)

names(spatrast)

spatrast |>
  relocate(bb, .before = cyl_tile_3) |>
  relocate(cyl_tile_1, .after = last_col())

Rename layers/attributes

Description

rename() changes the names of individual layers/attributes using new_name = old_name syntax. rename_with() renames layers/attributes using a function.

Usage

## S3 method for class 'SpatRaster'
rename(.data, ...)

## S3 method for class 'SpatRaster'
rename_with(.data, .fn, .cols = everything(), ...)

## S3 method for class 'SpatVector'
rename(.data, ...)

## S3 method for class 'SpatVector'
rename_with(.data, .fn, .cols = everything(), ...)

Arguments

Value

A ⁠Spat*⁠ object of the same class as .data. See Methods.

terra equivalent

⁠names(Spat*) <- c("a", "b", "c")⁠

Methods

Implementation of the generic dplyr::rename() method.

SpatRaster

Rename layers of a SpatRaster.

SpatVector

The result is a SpatVector with the renamed attributes on the function call.

See Also

dplyr::rename()

Other dplyr single-table verbs: arrange.SpatVector(), filter.Spat, mutate.Spat, reframe.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Other dplyr verbs that operate on columns: glimpse.Spat, mutate.Spat, pull.Spat, relocate.Spat, select.Spat

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rows.SpatVector, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
f <- system.file("extdata/cyl_tile.tif", package = "tidyterra")
spatrast <- rast(f) |> mutate(aa = 1, bb = 2, cc = 3)

spatrast

spatrast |> rename(
  this_first = cyl_tile_1,
  this_second = cyl_tile_2
)

spatrast |> rename_with(
  toupper,
  .cols = starts_with("c")
)

Replace NAs with specified values

Description

Replace NAs values on layers/attributes with specified values

Usage

## S3 method for class 'SpatRaster'
replace_na(data, replace = list(), ...)

## S3 method for class 'SpatVector'
replace_na(data, replace, ...)

Arguments

Value

A ⁠Spat*⁠ object of the same class as data. See Methods.

terra equivalent

Use ⁠r[is.na(r)] <- <replacement>⁠

See Also

tidyr::replace_na()

Other tidyr verbs for handling missing values: complete.SpatVector(), drop_na.Spat, expand.SpatVector(), fill.SpatVector()

Other tidyr methods: complete.SpatVector(), drop_na.Spat, expand.SpatVector(), fill.SpatVector(), nest.SpatVector(), pivot_longer.SpatVector(), pivot_wider.SpatVector(), uncount.SpatVector(), unite.Spat

Examples

library(terra)

f <- system.file("extdata/cyl_temp.tif", package = "tidyterra")
r <- rast(f)

r |> plot()

r |>
  replace_na(list(tavg_04 = 6, tavg_06 = 20)) |>
  plot()

Determine packages required by ⁠Spat*⁠ objects

Description

Determine packages required by ⁠Spat*⁠ objects.

Usage

## S3 method for class 'SpatRaster'
required_pkgs(x, ...)

## S3 method for class 'SpatVector'
required_pkgs(x, ...)

## S3 method for class 'SpatGraticule'
required_pkgs(x, ...)

## S3 method for class 'SpatExtent'
required_pkgs(x, ...)

Arguments

Value

A character string of packages that are required.

Methods

Implementation of generics::required_pkgs() method.

See Also

generics::required_pkgs().

Other generics methods: glance.Spat, tidy.Spat

Examples

file_path <- system.file("extdata/cyl_temp.tif", package = "tidyterra")

library(terra)

r <- rast(file_path)

# With rasters
r
required_pkgs(r)

# With vectors
v <- vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))
v
required_pkgs(v)

Row operations for SpatVector objects

Description

Methods for the dplyr::rows_insert() family on SpatVector objects.

Usage

## S3 method for class 'SpatVector'
rows_insert(
  x,
  y,
  by = NULL,
  ...,
  conflict = c("error", "ignore"),
  copy = FALSE,
  in_place = FALSE
)

## S3 method for class 'SpatVector'
rows_append(x, y, ..., copy = FALSE, in_place = FALSE)

## S3 method for class 'SpatVector'
rows_update(
  x,
  y,
  by = NULL,
  ...,
  unmatched = c("error", "ignore"),
  copy = FALSE,
  in_place = FALSE
)

## S3 method for class 'SpatVector'
rows_patch(
  x,
  y,
  by = NULL,
  ...,
  unmatched = c("error", "ignore"),
  copy = FALSE,
  in_place = FALSE
)

## S3 method for class 'SpatVector'
rows_upsert(x, y, by = NULL, ..., copy = FALSE, in_place = FALSE)

## S3 method for class 'SpatVector'
rows_delete(
  x,
  y,
  by = NULL,
  ...,
  unmatched = c("error", "ignore"),
  copy = FALSE,
  in_place = FALSE
)

Arguments

Value

A SpatVector.

Methods

Implementation of the generic dplyr::rows_insert() family for SpatVector objects.

SpatVector

Row operations update attributes while preserving the geometry column. When inserting data frame rows without geometry, the output contains empty geometries for the new rows.

See Also

dplyr::rows_insert()

Other dplyr verbs that operate on rows: arrange.SpatVector(), distinct.SpatVector(), filter.Spat, slice.Spat

Other dplyr verbs that operate on pairs of SpatVector and data frame objects: bind_cols.SpatVector, bind_rows.SpatVector, cross_join.SpatVector(), filter-joins.SpatVector, mutate-joins.SpatVector, nest_join.SpatVector()

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

v <- terra::vect(system.file("extdata/cyl.gpkg", package = "tidyterra"))

rows_update(
  v,
  tibble::tibble(cpro = "05", name = "New name"),
  by = "cpro"
)

rows_insert(
  v,
  tibble::tibble(cpro = "99", name = "New province"),
  by = "cpro"
)

Group SpatVector objects by rows

Description

rowwise() lets you compute on a SpatVector one row at a time. This is most useful when a vectorised function does not exist.

Most dplyr verb implementations in tidyterra preserve row-wise grouping. The exception is summarise.SpatVector(), which returns a grouped SpatVector. You can explicitly ungroup with ungroup.SpatVector() or as_tibble() or convert to a grouped SpatVector with group_by.SpatVector().

Usage

## S3 method for class 'SpatVector'
rowwise(data, ...)

Arguments

Details

See Details on dplyr::rowwise().

Value

The same SpatVector object with updated grouping metadata.

Methods

Implementation of the generic dplyr::rowwise() function for SpatVector objects.

When mixing terra and dplyr syntax on a row-wise SpatVector, for example subsetting a SpatVector like v[1:3,1:2], the groups attribute can be corrupted. tidyterra tries to regenerate the SpatVector. This is triggered the next time you use a dplyr verb on your SpatVector.

Some operations, such as terra::spatSample(), create a new SpatVector. In these cases, the result does not preserve the groups attribute. Use rowwise.SpatVector() to re-group.

See Also

dplyr::rowwise()

Other dplyr verbs that operate on groups of rows: count.SpatVector(), group_by.SpatVector(), reframe.SpatVector(), summarise.SpatVector()

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), cross_join.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group_by.SpatVector(), mutate-joins.SpatVector, mutate.Spat, nest_join.SpatVector(), pull.Spat, reframe.SpatVector(), relocate.Spat, rename.Spat, rows.SpatVector, select.Spat, slice.Spat, summarise.SpatVector()

Examples

library(terra)
library(dplyr)

v <- terra::vect(system.file("shape/nc.shp", package = "sf"))

# Select new births
nb <- v |>
  select(starts_with("NWBIR")) |>
  glimpse()

# Compute the mean of NWBIR on each geometry
nb |>
  rowwise() |>
  mutate(nb_mean = mean(c(NWBIR74, NWBIR79)))

# Additional examples

# Use c_across() to select many variables more easily.
nb |>
  rowwise() |>
  mutate(m = mean(c_across(NWBIR74:NWBIR79)))

# Compute the minimum of x and y in each row

nb |>
  rowwise() |>
  mutate(min = min(c_across(NWBIR74:NWBIR79)))

# Summarize.
v |>
  rowwise() |>
  summarise(mean_bir = mean(BIR74, BIR79)) |>
  glimpse() |>
  autoplot(aes(fill = mean_bir))

# Supply a variable to be kept
v |>
  mutate(id2 = as.integer(CNTY_ID / 100)) |>
  rowwise(id2) |>
  summarise(mean_bir = mean(BIR74, BIR79)) |>
  glimpse() |>
  autoplot(aes(fill = as.factor(id2)))

Gradient scales from Wikipedia color schemes

Description

Implementation based on the Wikipedia Colorimetric conventions for topographic maps.

Three scales are provided:

• ⁠scale_*_wiki_d()⁠: For discrete values.

• ⁠scale_*_wiki_c()⁠: For continuous values.

• ⁠scale_*_wiki_b()⁠: For binning continuous values.

Additionally, a color palette wiki.colors() is provided. See also grDevices::terrain.colors() for details.