filter.Spat {tidyterra}

Subset cells/geometries of ⁠Spat*⁠ objects

Description

The filter() function is used to subset ⁠Spat*⁠ objects, retaining all cells/geometries that satisfy your conditions. To be retained, the cell/geometry must produce a value of TRUE for all conditions.

It is possible to filter a SpatRaster by its geographic coordinates. You need to 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, ..., .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

Ignored for ⁠Spat*⁠ objects.

.keep_extent

Should the extent of the resulting SpatRaster be kept? On FALSE, terra::trim() is called so the extent of the result may be different of the extent of the output. See also drop_na.SpatRaster().

Value

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

Methods

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

SpatRaster

Cells that do not fulfill 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 returning SpatRaster has the same crs, extent, resolution and hence the same number of cells than .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 would present in any case the same crs and resolution than .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, rename.Spat, select.Spat, slice.Spat, summarise.SpatVector()

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

Other dplyr methods: arrange.SpatVector(), bind_cols.SpatVector, bind_rows.SpatVector, count.SpatVector(), distinct.SpatVector(), filter-joins.SpatVector, glimpse.Spat, group-by.SpatVector, mutate-joins.SpatVector, mutate.Spat, pull.Spat, relocate.Spat, rename.Spat, 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()