filter.Spat: Subset cells/geometries of Spat* objects
In tidyterra: 'tidyverse' Methods and 'ggplot2' Helpers for 'terra' Objects

filter.Spat

R Documentation

Subset cells/geometries of `⁠Spat*⁠` objects

Description

These functions are used to subset a data frame, 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 behaviour can impact how you write your conditions when missing values are involved. See dplyr::filter().

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, ..., .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`	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()`.
`.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 than .data. See Methods.

Methods

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

`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.

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)

tidyterra documentation built on March 11, 2026, 9:08 a.m.