Extract a single layer/attribute

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

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

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

Usage

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

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

Arguments

.data

A SpatRaster created with terra::rast() or a SpatVector created with terra::vect().

var

A variable specified as:

• a literal layer/attribute name.

• a positive integer, giving the position counting from the left.

• a negative integer, giving the position counting from the right.

The default returns the last layer/attribute (on the assumption that's the column you've created most recently).

name

An optional parameter that specifies the column to be used as names for a named vector. Specified in a similar manner as var.

...

Arguments passed on to as_tibble.Spat()

Value

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

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

terra equivalent

terra::values()

Methods

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

SpatRaster

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

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

SpatVector

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

See also

dplyr::pull()

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

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, filter.Spat, glimpse.Spat, group-by.SpatVector, mutate-joins.SpatVector, mutate.Spat, relocate.Spat, rename.Spat, rowwise.SpatVector(), select.Spat, slice.Spat, summarise.SpatVector()

Examples

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

# Extract second layer
r %>%
  pull(2) %>%
  head()
#> [1] 229 235 229 229 239 153

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

r %>%
  pull(2, xy = TRUE) %>%
  head()
#> [1] 5370160 5370160 5370160 5370160 5370160 5370160

# With renaming

r %>%
  mutate(cat = cut(cyl_tile_3, c(0, 100, 300))) %>%
  pull(cyl_tile_3, name = cat) %>%
  head()
#> (100,300] (100,300] (100,300] (100,300] (100,300] (100,300] 
#>       206       224       206       206       233       169