Package 'tidyterra'

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

.data	A SpatVector created with terra::vect().
...	<data-masking> Variables, or functions of variables. Use desc() to sort a variable in descending order.
.by_group	If TRUE, sort first by grouping variable. This applies to grouped SpatVector objects only.
.locale	The locale to sort character vectors in. If NULL, the default, uses the "C" locale unless the deprecated dplyr.legacy_locale global option escape hatch is active. See the dplyr-locale help page for more details. If a single string from stringi::stri_locale_list() is supplied, then this will be used as the locale to sort with. For example, "en" will sort with the American English locale. This requires the stringi package. If "C" is supplied, then character vectors will always be sorted in the C locale. This does not require stringi and is often much faster than supplying a locale identifier. The C locale is not the same as English locales, such as "en", particularly when it comes to data containing a mix of upper and lower case letters. This is explained in more detail on the locale help page under the ⁠Default locale⁠ section.

Value

A SpatVector object.

terra equivalent

terra::sort()

Methods

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

See Also

dplyr::arrange()

Other 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

x	A SpatRaster object.
as.raster	If TRUE, the result is a SpatRaster object with three layers indicating the position of each cell (cell number, row and column).

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, extension 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

x	A SpatVector created with terra::vect().
...	Additional arguments passed on to sf::st_as_sf().

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

x	A tibble or data frame.
...	Additional arguments passed on to terra::rast().
xycols	A vector of integers of length 2 determining the position of the columns that hold the x and y coordinates.
crs	A CRS in several formats (PROJ.4, WKT, EPSG code, etc.) or a spatial object from sf or terra that includes the target coordinate reference system. See pull_crs() and Details.
digits	Integer to set the precision for detecting whether points are on a regular grid (a low number of digits is a low precision).

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 utils 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

x	A tibble, data frame or sf object of class sf or sfc.
...	Additional arguments passed on to terra::vect().
geom	Character vector naming the fields that contain the geometry data. Use two names for point coordinates (x and y) or one name for a column with WKT geometries.
crs	A CRS in several formats (PROJ.4, WKT, EPSG code, etc.) or a spatial object from sf or terra that includes the target coordinate reference system. See pull_crs() and Details.

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 utils 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

x	A SpatRaster created with terra::rast() or a SpatVector created with terra::vect().
...	Arguments passed on to terra::as.data.frame().
xy	logical. If TRUE, the coordinates of each raster cell are included
na.rm	logical. If TRUE, cells that have a NA value in at least one layer are removed. If the argument is set to NA only cells that have NA values in all layers are removed
.name_repair	Treatment of problematic column names: "minimal": No name repair or checks, beyond basic existence, "unique": Make sure names are unique and not empty, "check_unique": (default value), no name repair, but check they are unique, "universal": Make the names unique and syntactic "unique_quiet": Same as "unique", but "quiet" "universal_quiet": Same as "universal", but "quiet" a function: apply custom name repair (e.g., .name_repair = make.names for names in the style of base R). A purrr-style anonymous function, see rlang::as_function() This argument is passed on as repair to vctrs::vec_as_names(). See there for more details on these terms and the strategies used to enforce them.
geom	character or NULL. If not NULL, either "WKT" or "HEX", to get the geometry included in Well-Known-Text or hexadecimal notation. If x has point geometry, it can also be "XY" to add the coordinates of each point

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 tidyverse methods (i.e. 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

object	A SpatRaster created with terra::rast(), a SpatVector created with terra::vect(), a SpatGraticule (see terra::graticule()) or a SpatExtent (see terra::ext()).
...	Other arguments passed to geom_spatraster(), geom_spatraster_rgb() or geom_spatvector().
rgb	Logical. If TRUE, plot as an RGB image. If NULL (the default), autoplot.SpatRaster() tries to guess.
use_coltab	Logical. If TRUE, plot with the corresponding terra::coltab(). If NULL (the default), autoplot.SpatRaster() tries to guess. See also scale_fill_coltab().
facets	Logical. If TRUE, display facets. If NULL (the default), autoplot.SpatRaster() tries to guess.
nrow, ncol	Number of rows and columns in the facet.

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 utils: 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 coltabs

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

...	Objects to combine. The first argument must be a SpatVector. Each subsequent argument can be a SpatVector, sf object or data frame. Inputs are recycled to the same length, then matched by position.
.name_repair	One of "unique", "universal", or "check_unique". See vctrs::vec_as_names() for the meaning of these options.

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. Note that for the second and subsequent arguments on ..., 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 Spat*/data.frame: 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

...	Objects to combine. The first argument must be a SpatVector. Each subsequent argument can be a SpatVector, sf/sfc object or data frame. Columns are matched by name and any missing columns are filled with NA.
.id	The name of an optional identifier column. Provide a string to create an output column that identifies each input. The column will use names if available, otherwise it will use positions.

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 Spat*/data.frame: 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 informing of the results. See Solving issues section for minimal guidance.

Usage

compare_spatrasters(x, y, digits = 6)

Arguments

x, y	SpatRaster objects.
digits	Integer to set the precision for comparing the extent and the resolution.

Value

A invisible logical TRUE/FALSE indicating if the SpatRaster objects are compatible, plus an informative message flagging the issues found (if any).

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

data	A SpatVector.
...	<data-masking> Specification of columns to expand or complete. Columns can be atomic vectors or lists. To find all unique combinations of x, y and z, including those not present in the data, supply each variable as a separate argument: expand(df, x, y, z) or complete(df, x, y, z). To find only the combinations that occur in the data, use nesting: expand(df, nesting(x, y, z)). You can combine the two forms. For example, expand(df, nesting(school_id, student_id), date) would produce a row for each present school-student combination for all possible dates. When used with factors, expand() and complete() use the full set of levels, not just those that appear in the data. If you want to use only the values seen in the data, use forcats::fct_drop(). When used with continuous variables, you may need to fill in values that do not appear in the data: to do so use expressions like year = 2010:2020 or year = full_seq(year,1).
fill	A named list that for each variable supplies a single value to use instead of NA for missing combinations.
explicit	Should both implicit (newly created) and explicit (pre-existing) missing values be filled by fill? By default, this is TRUE, but if set to FALSE this will limit the fill to only implicit missing values.

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

x	A SpatVector created with terra::vect().
...	<data-masking> Variables to group by.
wt	<data-masking> Frequency weights. Can be NULL or a variable: If NULL (the default), counts the number of rows in each group. If a variable, computes sum(wt) for each group.
sort	If TRUE, will show the largest groups at the top.
name	The name of the new column in the output. If omitted, it will default to n. If there's already a column called n, it will use nn. If there's a column called n and nn, it'll use nnn, and so on, adding ns until it gets a new name.
.drop	Argument no longer supported, empty groups are always removed (see dplyr::count(), .drop = TRUE argument).
.dissolve	Logical. If TRUE, dissolve borders between aggregated geometries.

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 group 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 you've done the grouping
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

x	A SpatVector created with terra::vect().
y	A data frame or other object coercible to a data frame. If a SpatVector or sf object is provided, this method returns an error.
...	Additional arguments passed on to sf::st_as_sf().
copy	If x and y are not from the same data source, and copy is TRUE, then y will be copied into the same src as x. This allows you to join tables across srcs, but it is a potentially expensive operation so you must opt into it.
suffix	If there are non-joined duplicate variables in x and y, these suffixes will be added to the output to disambiguate them. Should be a character vector of length 2.

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 Spat*/data.frame: 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

.data	A SpatVector created with terra::vect().
...	<data-masking> Optional variables to use when determining uniqueness. If there are multiple rows for a given combination of inputs, only the first row will be preserved. If omitted, all variables in the data frame are used. There is a reserved variable name, geometry, that removes duplicate geometries. See Methods.
.keep_all	If TRUE, keep all variables in .data. If a combination of ... is not distinct, this keeps the first row of values.

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

data	A SpatVector created with terra::vect() or a SpatRaster terra::rast().
...	<tidy-select> Attributes to inspect for missing values. If empty, all attributes are used.

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 NAs
v <- v |> mutate(iso2 = ifelse(cpro <= "09", NA, cpro))

# Init
plot(v, col = "red")

# Mask with lyr.1
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 NAs
r[r > 13 & r < 22 | r > 31 & r < 45] <- NA

# Init
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)

# Auto-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

data	A SpatVector.
...	<data-masking> Specification of columns to expand or complete. Columns can be atomic vectors or lists. To find all unique combinations of x, y and z, including those not present in the data, supply each variable as a separate argument: expand(df, x, y, z) or complete(df, x, y, z). To find only the combinations that occur in the data, use nesting: expand(df, nesting(x, y, z)). You can combine the two forms. For example, expand(df, nesting(school_id, student_id), date) would produce a row for each present school-student combination for all possible dates. When used with factors, expand() and complete() use the full set of levels, not just those that appear in the data. If you want to use only the values seen in the data, use forcats::fct_drop(). When used with continuous variables, you may need to fill in values that do not appear in the data: to do so use expressions like year = 2010:2020 or year = full_seq(year,1).
.name_repair	One of "check_unique", "unique", "universal", "minimal", "unique_quiet", or "universal_quiet". See vec_as_names() for the meaning of these options.

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

data	A SpatVector.
...	<tidy-select> Columns to fill.
.by	<tidy-select> Optionally, a selection of columns to group by for just this operation, functioning as an alternative to group_by(). For details and examples, see ?dplyr_by.
.direction	Direction in which to fill missing values. Currently either "down" (the default), "up", "downup" (i.e. first down and then up) or "updown" (first up and then down).

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

x	A SpatVector created with terra::vect().
y	A data frame or other object coercible to a data frame. If a SpatVector or sf object is provided, this method returns an error. See terra::intersect() for spatial joins.
by	A join specification created with join_by(), or a character vector of variables to join by. If NULL, the default, ⁠*_join()⁠ will perform a natural join, using all variables in common across x and y. A message lists the variables so that you can check they're correct; suppress the message by supplying by explicitly. To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b. To join by multiple variables, use a join_by() specification with multiple expressions. For example, join_by(a == b, c == d) will match x$a to y$b and x$c to y$d. If the column names are the same between x and y, you can shorten this by listing only the variable names, like join_by(a, c). join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins. For simple equality joins, you can alternatively specify a character vector of variable names to join by. For example, by = c("a", "b") joins x$a to y$a and x$b to y$b. If variable names differ between x and y, use a named character vector like by = c("x_a" = "y_a", "x_b" = "y_b"). To perform a cross-join, generating all combinations of x and y, see cross_join().
copy	If x and y are not from the same data source, and copy is TRUE, then y will be copied into the same src as x. This allows you to join tables across srcs, but it is a potentially expensive operation so you must opt into it.
...	Other parameters passed onto methods.

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 Spat*/data.frame: 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). Note that 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'
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

.data	A SpatRaster created with terra::rast() or a SpatVector created with terra::vect().
...	<data-masking> Expressions that return a logical value and are defined in terms of the layers/attributes in .data. If multiple expressions are included, they are combined with the & operator. Only cells/geometries for which all conditions evaluate to TRUE are kept. See Methods.
.preserve	Relevant when the .data input is grouped. If .preserve = FALSE (the default), the grouping structure is recalculated based on the resulting data, otherwise the grouping is kept as is.
.keep_extent	Logical. If TRUE, keep the extent of the resulting SpatRaster. On FALSE, terra::trim() is called so the extent may differ from the extent of the output. See also drop_na.SpatRaster().
.by	<tidy-select> Optionally, a selection of columns to group by for just this operation, functioning as an alternative to group_by(). For details and examples, see ?dplyr_by.

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 hence the same 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 (i.e. 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 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().

Note that these methods are now implemented as a wrapper 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

model	A SpatRaster created with terra::rast(), a SpatVector created with terra::vect(), a SpatGraticule (see terra::graticule()) or a SpatExtent (see terra::ext()).
data	Not used by this method.
...	Ignored by these methods.
.name_repair	Treatment of problematic column names: "minimal": No name repair or checks, beyond basic existence, "unique": Make sure names are unique and not empty, "check_unique": (default value), no name repair, but check they are unique, "universal": Make the names unique and syntactic "unique_quiet": Same as "unique", but "quiet" "universal_quiet": Same as "universal", but "quiet" a function: apply custom name repair (e.g., .name_repair = make.names for names in the style of base R). A purrr-style anonymous function, see rlang::as_function() This argument is passed on as repair to vctrs::vec_as_names(). See there for more details on these terms and the strategies used to enforce them.
maxcell	Positive integer. Maximum number of cells to use for the plot.
pivot	Logical. When TRUE, a SpatRaster is returned in long format. When FALSE (the default), it is returned as a data frame with one column per layer. See Details.
crs	Input that includes or represents a CRS. It can be an sf/sfc object, a SpatRaster/SpatVector object, a crs object from sf::st_crs(), a character string (for example a proj4 string), or an integer representing an EPSG code.

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

Return a tibble that can be used with ⁠ggplot2::geom_*⁠ like ggplot2::geom_point(), ggplot2::geom_raster(), etc.

The resulting tibble includes the coordinates on the columns ⁠x, y⁠. The values of each layer are included as additional columns named as per the name of the layer on 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 a "long" format (see tidyr::pivot_longer()). The fortified object has the following columns:

• ⁠x,y⁠: Coordinates (center) of the cell on the corresponding CRS.

• lyr: Indicating the name of the SpatRaster layer of value.

• value: The value of the SpatRaster in the corresponding lyr.

This option may be useful when using several ⁠geom_*⁠ and for faceting, see Examples.

SpatVector, SpatGraticule and SpatExtent

Return a 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 utils: 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 the 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 you can use now 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

mapping	Set of aesthetic mappings created by ggplot2::aes(). See Aesthetics, especially in the use of the fill aesthetic.
data	A SpatRaster object.
...	Other arguments passed on to layer()'s params argument. These arguments broadly fall into one of 4 categories below. Notably, further arguments to the position argument, or aesthetics that are required can not be passed through .... Unknown arguments that are not part of the 4 categories below are ignored. Static aesthetics that are not mapped to a scale, but are at a fixed value and apply to the layer as a whole. For example, colour = "red" or linewidth = 3. The geom's documentation has an Aesthetics section that lists the available options. The 'required' aesthetics cannot be passed on to the params. Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data. When constructing a layer using a ⁠stat_*()⁠ function, the ... argument can be used to pass on parameters to the geom part of the layer. An example of this is stat_density(geom = "area", outline.type = "both"). The geom's documentation lists which parameters it can accept. Inversely, when constructing a layer using a ⁠geom_*()⁠ function, the ... argument can be used to pass on parameters to the stat part of the layer. An example of this is geom_area(stat = "density", adjust = 0.5). The stat's documentation lists which parameters it can accept. The key_glyph argument of layer() may also be passed on through .... This can be one of the functions described as key glyphs, to change the display of the layer in the legend.
maxcell	Positive integer. Maximum number of cells to use for the plot.
bins	Number of contour bins. Overridden by breaks.
binwidth	The width of the contour bins. Overridden by bins.
breaks	One of: Numeric vector to set the contour breaks A function that takes the range of the data and binwidth as input and returns breaks as output. A function can be created from a formula (e.g. ~ fullseq(.x, .y)). Overrides binwidth and bins. By default, this is a vector of length ten with pretty() breaks.
na.rm	If TRUE, the default, missing values are silently removed. If FALSE, missing values are removed with a warning.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display. To include legend keys for all levels, even when no data exists, use TRUE. If NA, all levels are shown in legend, but unobserved levels are omitted.
inherit.aes	If FALSE, override the default aesthetics rather than combining with them.
mask_projection	Logical, defaults to FALSE. If TRUE, mask out areas outside the input extent. For example, to avoid data wrapping around the dateline in equal-area projections. This argument is passed to terra::project() when reprojecting the SpatRaster.
size.unit	How the size aesthetic is interpreted: as millimetres ("mm", default), points ("pt"), centimetres ("cm"), inches ("in"), or picas ("pc").
label_format	One of: NULL for no labels. This produces the same result as geom_spatraster_contour(). A character vector giving labels (must have the same length as the breaks produced by bins, binwidth or breaks). A function that takes the breaks as input and returns labels as output, as the default setup (scales::label_number()).
label_placer	Function that controls how labels are placed along the isolines. Uses label_placer_minmax() by default.

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 info on contours and vignette("ggplot2-specs", package = "ggplot2") for an overview of the aesthetics.

Computed variables

These geom computes internally some variables 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 the mid point 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 (i.e., terra::crs(rast) == "") the geom does not make any assumption about the scales.

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

Facets

You can use facet_wrap(~lyr) for creating 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 utils: 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)

# Labelled
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()

---

Visualise SpatRaster objects

Description

This geom is used to visualise SpatRaster objects (see terra::rast()). The geom is designed for visualise the object by layers, as terra::plot() does.

For plotting SpatRaster objects as map tiles (i.e. RGB SpatRaster), 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

mapping	Set of aesthetic mappings created by ggplot2::aes(). See Aesthetics, especially in the use of the fill aesthetic.
data	A SpatRaster object.
na.rm	If TRUE, the default, missing values are silently removed. If FALSE, missing values are removed with a warning.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. It can also be a named logical vector to finely select the aesthetics to display. To include legend keys for all levels, even when no data exists, use TRUE. If NA, all levels are shown in legend, but unobserved levels are omitted.
inherit.aes	If FALSE, override the default aesthetics rather than combining with them.
interpolate	If TRUE interpolate linearly, if FALSE (the default) don't interpolate.
maxcell	Positive integer. Maximum number of cells to use for the plot.
use_coltab	Logical. Only applicable to SpatRaster objects that have an associated coltab. If TRUE, use the coltab on the plot. See also scale_fill_coltab().
mask_projection	Logical, defaults to FALSE. If TRUE, mask out areas outside the input extent. For example, to avoid data wrapping around the dateline in equal-area projections. This argument is passed to terra::project() when reprojecting the SpatRaster.
...	Other arguments passed on to layer()'s params argument. These arguments broadly fall into one of 4 categories below. Notably, further arguments to the position argument, or aesthetics that are required can not be passed through .... Unknown arguments that are not part of the 4 categories below are ignored. Static aesthetics that are not mapped to a scale, but are at a fixed value and apply to the layer as a whole. For example, colour = "red" or linewidth = 3. The geom's documentation has an Aesthetics section that lists the available options. The 'required' aesthetics cannot be passed on to the params. Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data. When constructing a layer using a ⁠stat_*()⁠ function, the ... argument can be used to pass on parameters to the geom part of the layer. An example of this is stat_density(geom = "area", outline.type = "both"). The geom's documentation lists which parameters it can accept. Inversely, when constructing a layer using a ⁠geom_*()⁠ function, the ... argument can be used to pass on parameters to the stat part of the layer. An example of this is geom_area(stat = "density", adjust = 0.5). The stat's documentation lists which parameters it can accept. The key_glyph argument of layer() may also be passed on through .... This can be one of the functions described as key glyphs, to change the display of the layer in the legend.
geom	Geom used to display the data. Recommended values for SpatRaster are "raster" (the default), "point", "text" and "label".

Value

A ggplot2 layer

terra equivalent

terra::plot()

Coords

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

On SpatRaster that have a CRS, the geom uses ggplot2::coord_sf() to adjust the scales. That means that also 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 properly display the SpatRaster layers.

If fill is used, it should contain the name of one layer that is present on the SpatRaster (i.e. ⁠geom_spatraster(data = rast, aes(fill = <name_of_lyr>)⁠). Names of the layers 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 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) for creating 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): Values of the SpatRaster.

• after_stat(lyr): Name of the layer.

Source

Based on the layer_spatial() implementation on ggspatial package. 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 utils: 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")

---

Visualise SpatRaster objects as images

Description

This geom is used to visualise 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

mapping	Ignored.
data	A SpatRaster object.
interpolate	If TRUE interpolate linearly, if FALSE (the default) don't interpolate.
r, g, b	Integer giving the layer number in data used for the red (r), green (g) and blue (b) channel.
alpha	The alpha transparency, a number in [0,1], see argument alpha in hsv.
maxcell	Positive integer. Maximum number of cells to use for the plot.
max_col_value	Number giving the upper bound of the color value range. When this is 255 (the default), the result is computed most efficiently. See grDevices::rgb().
...	Other arguments passed on to layer()'s params argument. These arguments broadly fall into one of 4 categories below. Notably, further arguments to the position argument, or aesthetics that are required can not be passed through .... Unknown arguments that are not part of the 4 categories below are ignored. Static aesthetics that are not mapped to a scale, but are at a fixed value and apply to the layer as a whole. For example, colour = "red" or linewidth = 3. The geom's documentation has an Aesthetics section that lists the available options. The 'required' aesthetics cannot be passed on to the params. Please note that while passing unmapped aesthetics as vectors is technically possible, the order and required length is not guaranteed to be parallel to the input data. When constructing a layer using a ⁠stat_*()⁠ function, the ... argument can be used to pass on parameters to the geom part of the layer. An example of this is stat_density(geom = "area", outline.type = "both"). The geom's documentation lists which parameters it can accept. Inversely, when constructing a layer using a ⁠geom_*()⁠ function, the ... argument can be used to pass on parameters to the stat part of the layer. An example of this is geom_area(stat = "density", adjust = 0.5). The stat's documentation lists which parameters it can accept. The key_glyph argument of layer() may also be passed on through .... This can be one of the functions described as key glyphs, to change the display of the layer in the legend.
stretch	character. Option to stretch the values to increase contrast: "lin" (linear) or "hist" (histogram). The linear stretch uses stretch with arguments minq=0.02 and maxq=0.98
zlim	numeric vector of length 2. Range of values to plot (optional). If this is set, and stretch="lin" is used, then the values are stretched within the range of zlim. This allows creating consistent coloring between SpatRasters with different cell-value ranges, even when stretching the colors for improved contrast
mask_projection	Logical, defaults to FALSE. If TRUE, mask out areas outside the input extent. For example, to avoid data wrapping around the dateline in equal-area projections. This argument is passed to terra::project() when reprojecting the SpatRaster.

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 (i.e., terra::crs(rast) == "") the geom does not make any assumption about the scales.

On SpatRaster that have a CRS, the geom uses ggplot2::coord_sf() to adjust the scales. That means that also 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 utils: 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)

---

Visualise SpatVector objects

Description

Wrappers of ggplot2::geom_sf() family used to visualise 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

mapping	Set of aesthetic mappings created by aes(). If specified and inherit.aes = TRUE (the default), it is combined with the default mapping at the top level of the plot. You must supply mapping if there is no plot mapping.
data	A SpatVector object, see terra::vect().
na.rm	If FALSE, the default, missing values are removed with a warning. If TRUE, missing values are silently removed.
show.legend	logical. Should this layer be included in the legends? NA, the default, includes if any aesthetics are mapped. FALSE never includes, and TRUE always includes. You can also set this to one of "polygon", "line", and "point" to override the default legend.
...	Other arguments passed on to ggplot2::geom_sf() functions. These are often aesthetics, used to set an aesthetic to a fixed value, like colour = "red" or linewidth = 3.
linewidth	Size of label border, in mm.
inherit.aes	If FALSE, overrides the default aesthetics, rather than combining with them. This is most useful for helper functions that define both data and aesthetics and shouldn't inherit behaviour from the default plot specification, e.g. annotation_borders().
check_overlap	If TRUE, text that overlaps previous text in the same layer will not be plotted. check_overlap happens at draw time and in the order of the data. Therefore data should be arranged by the label column before calling geom_text(). Note that this argument is not supported by geom_label().
geom	The geometric object to use to display the data for this layer. When using a ⁠stat_*()⁠ function to construct a layer, the geom argument can be used to override the default coupling between stats and geoms. The geom argument accepts the following: A Geom ggproto subclass, for example GeomPoint. A string naming the geom. To give the geom as a string, strip the function name of the geom_ prefix. For example, to use geom_point(), give the geom as "point". For more information and other ways to specify the geom, see the layer geom documentation.
position	A position adjustment to use on the data for this layer. This can be used in various ways, including to prevent overplotting and improving the display. The position argument accepts the following: The result of calling a position function, such as position_jitter(). This method allows for passing extra arguments to the position. A string naming the position adjustment. To give the position as a string, strip the function name of the position_ prefix. For example, to use position_jitter(), give the position as "jitter". For more information and other ways to specify the position, see the layer position documentation.

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 utils: 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

x	A SpatRaster created with terra::rast() or a SpatVector created with terra::vect().
...	Ignored by this method.

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)

---

Get a nice glimpse of your ⁠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

x	A SpatRaster created with terra::rast() or a SpatVector created with terra::vect().
width	Width of output: defaults to the setting of the width option (if finite) or the width of the console.
...	Arguments passed on to as_tibble() methods for SpatRaster and SpatVector.
n	Maximum number of rows to show.
max_extra_cols	Number of extra columns or layers to print abbreviated information for, if n is too small for the ⁠Spat*⁠ object.

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:

palette	use	description	range
aspect	General	aspect oriented grey colors
aspectcolr	General	aspect oriented rainbow colors	0 to 360
bcyr	General	blue through cyan through yellow to red
bgyr	General	blue through green through yellow to red
blues	General	white to blue
byg	General	blue through yellow to green
byr	General	blue through yellow to red
celsius	General	blue to red for degree Celsius temperature	-80 to 80
corine	Land Cover	EU Corine land cover colors	111 to 995
curvature	General	for terrain curvatures	-0.1 to 0.1
differences	General	differences oriented colors
elevation	Topography	maps relative ranges of raster values to elevation color ramp
etopo2	Topography	colors for ETOPO2 worldwide bathymetry/topography	-11000 to 8850
evi	Natural	enhanced vegetative index colors	-1 to 1
fahrenheit	Temperature	blue to red for Fahrenheit temperature	-112 to 176
forest_cover	Natural	percentage of forest cover	0 to 1
gdd	Natural	accumulated growing degree days	0 to 6000
grass	General	GRASS GIS green (perceptually uniform)
greens	General	white to green
grey	General	grey scale
gyr	General	green through yellow to red
haxby	Topography	relative colors for bathymetry or topography
inferno	General	perceptually uniform sequential color table inferno
kelvin	Temperature	blue to red for temperature in Kelvin scale	193.15 to 353.15
magma	General	perceptually uniform sequential color table magma
ndvi	Natural	Normalized Difference Vegetation Index colors	-1 to 1
ndwi	Natural	Normalized Difference Water Index colors	-200 to 200
nlcd	Land Cover	US National Land Cover Dataset colors	0 to 95
oranges	General	white to orange
plasma	General	perceptually uniform sequential color table plasma
population	Human	color table covering human population classification breaks	0 to 1000000
population_dens	Human	color table covering human population density classification breaks	0 to 1000
precipitation	Climate	precipitation color table (0..2000mm)	0 to 7000
precipitation_daily	Climate	precipitation color table (0..1000mm)	0 to 100
precipitation_monthly	Climate	precipitation color table (0..1000mm)	0 to 1000
rainbow	General	rainbow color table
ramp	General	color ramp
reds	General	white to red
roygbiv	General
rstcurv	General	terrain curvature (from r.resamp.rst)	-0.1 to 0.1
ryb	General	red through yellow to blue
ryg	General	red through yellow to green
sepia	General	yellowish-brown through to white
slope	General	r.slope.aspect-type slope colors for raster values 0-90	0 to 90
soilmoisture	Natural	soil moisture color table (0.0-1.0)	0 to 1
srtm	Topography	color palette for Shuttle Radar Topography Mission elevation	-11000 to 8850
srtm_plus	Topography	color palette for Shuttle Radar Topography Mission elevation (with seafloor colors)	-11000 to 8850
terrain	Topography	global elevation color table covering -11000 to +8850m	-11000 to 8850
viridis	General	perceptually uniform sequential color table viridis
water	Natural	water depth
wave	General	color wave

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

.data, x	A SpatVector object. See Methods.
...	<data-masking> In group_by(), variables or computations to group by. Computations are always done on the ungrouped data frame. To perform computations on the grouped data, you need to use a separate mutate() step before the group_by(). Computations are not allowed in nest_by(). In ungroup(), variables to remove from the grouping.
.add	When FALSE, the default, group_by() will override existing groups. To add to the existing groups, use .add = TRUE.
.drop	Drop groups formed by factor levels that don't appear in the data? The default is TRUE except when .data has been previously grouped with .drop = FALSE. See group_by_drop_default() for details.

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 (i.e. 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.

Note also that 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 group 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 removing 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 instead append
by_name2_name1 |>
  group_by(ID_1, ID_2, .add = TRUE) |>
  group_vars()

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

---

Hypsometric palettes database

Description

A tibble including the color map of 33 gradient palettes. All the palettes. It 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)
  )

---

Check if x and y positions conforms a regular grid

Description

Assess if the coordinates x,y of an object conforms a regular grid. This function is called by its side effects.

This function is internally called by as_spatraster().

Usage

is_regular_grid(xy, digits = 6)

Arguments

xy	A matrix, data frame or tibble of at least two columns representing x and y coordinates.
digits	Integer to set the precision for detecting whether points are on a regular grid (a low number of digits is a low precision).

Value

invisible() if is regular or an error message otherwise

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 location
set.seed(1234)
jitter <- runif(length(p)) / 10e4
p_jitter <- p + jitter

# Need to 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

x	A SpatVector created with terra::vect().
y	A data frame or other object coercible to a data frame. If a SpatVector or sf object is provided, this method returns an error. See terra::intersect() for spatial joins.
by	A join specification created with join_by(), or a character vector of variables to join by. If NULL, the default, ⁠*_join()⁠ will perform a natural join, using all variables in common across x and y. A message lists the variables so that you can check they're correct; suppress the message by supplying by explicitly. To join on different variables between x and y, use a join_by() specification. For example, join_by(a == b) will match x$a to y$b. To join by multiple variables, use a join_by() specification with multiple expressions. For example, join_by(a == b, c == d) will match x$a to y$b and x$c to y$d. If the column names are the same between x and y, you can shorten this by listing only the variable names, like join_by(a, c). join_by() can also be used to perform inequality, rolling, and overlap joins. See the documentation at ?join_by for details on these types of joins. For simple equality joins, you can alternatively specify a character vector of variable names to join by. For example, by = c("a", "b") joins x$a to y$a and x$b to y$b. If variable names differ between x and y, use a named character vector like by = c("x_a" = "y_a", "x_b" = "y_b"). To perform a cross-join, generating all combinations of x and y, see cross_join().
copy	If x and y are not from the same data source, and copy is TRUE, then y will be copied into the same src as x. This allows you to join tables across srcs, but it is a potentially expensive operation so you must opt into it.
suffix	If there are non-joined duplicate variables in x and y, these suffixes will be added to the output to disambiguate them. Should be a character vector of length 2.
...	Other parameters passed onto methods.
keep	Should the join keys from both x and y be preserved in the output? If NULL, the default, joins on equality retain only the keys from x, while joins on inequality retain the keys from both inputs. If TRUE, all keys from both inputs are retained. If FALSE, only keys from x are retained. For right and full joins, the data in key columns corresponding to rows that only exist in y are merged into the key columns from x. Can't be used when joining on inequality conditions.

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 Spat*/data.frame: 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))

---