tidyterra (version 1.3.0)

filter.Spat: Subset cells/geometries of Spat* objects

Description

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

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

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

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

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

Usage

# S3 method for SpatRaster
filter(.data, ..., .preserve = FALSE, .keep_extent = TRUE)
# S3 method for SpatVector
filter(.data, ..., .by = NULL, .preserve = FALSE)
# S3 method for SpatVector
filter_out(.data, ..., .by = NULL, .preserve = FALSE)

Value

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

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.

Methods

Implementation of the generic dplyr::filter() methods for Spat* objects.

SpatRaster

Cells that do not meet the conditions in ... are returned as NA. On a multi-layer SpatRaster, NA is propagated across all layers.

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

The x and y coordinates of the SpatRaster are also available internally for filtering. See Examples.

SpatVector

The result is a SpatVector containing the geometries whose attributes satisfy all conditions.

See Also

dplyr::filter().

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

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)