st_extract: Extract cell values at point locations

In r-spatial/stars: Spatiotemporal Arrays, Raster and Vector Data Cubes

Extract cell values at point locations

Description

Extract cell values at point locations

Usage

st_extract(x, ...)

## S3 method for class 'stars'
st_extract(
  x,
  at,
  ...,
  bilinear = FALSE,
  time_column = attr(at, "time_column") %||% attr(at, "time_col"),
  interpolate_time = bilinear,
  FUN = mean,
  resampling = c("nearest", "bilinear", "cubic", "cubicspline"),
  sfc_attribute = NULL
)

Arguments

x	object of class stars or stars_proxy
...	passed on to aggregate.stars when geometries are not exclusively POINT geometries
at	object of class sf or sfc with geometries, or two-column matrix with coordinate points in rows, indicating where to extract values of x, or a stars object with geometry and temporal dimensions (vector data cube)
bilinear	logical; use bilinear interpolation rather than nearest neighbour?
time_column	character or integer; name or index of a column with time or date values that will be matched to values of the first temporal dimension (matching classes POSIXct, POSIXt, Date, or PCICt), in x, after which this dimension is reduced. This is useful to extract data cube values along a trajectory; see https://github.com/r-spatial/stars/issues/352 .
interpolate_time	logical; should time be interpolated? if FALSE, time instances are matched using the coinciding or the last preceding time in the data cube.
FUN	function used to aggregate pixel values when geometries of at intersect with more than one pixel
resampling	character; resampling method; for method cubic or cubicspline, 'stars_proxy' objects should be used and GDAL should have version >= 3.10.0
sfc_attribute	character; if at is of class stars should the aggregation be performed for the attribute geometry rather than the dimension geometry? If NULL (default), the aggregation is performed at the dimension geometries, else the name of the attribute geometry to perform the aggregation on. If the given attribute geometry does not exist, the aggregation defaults to the dimension geometry.

Details

points outside the raster are returned as NA values. For large sets of points for which extraction is needed, passing a matrix as to at may be much faster than passing an sf or sfc object.

Value

if at is of class matrix, a matrix with extracted values is returned; if at is of class stars and a temporal dimension was passed to time_column, a stars object with the original at dimensions and the extracted values as attributes. otherwise: if x has more dimensions than only x and y (raster), an object of class stars with POINT geometries replacing x and y raster dimensions, if this is not the case, an object of sf with extracted values.

Examples

tif = system.file("tif/L7_ETMs.tif", package = "stars")
r = read_stars(tif)
pnt = st_sample(st_as_sfc(st_bbox(r)), 10)
st_extract(r, pnt)
st_extract(r, pnt) %>% st_as_sf()
st_extract(r[,,,1], pnt)
st_extract(r, st_coordinates(pnt)) # "at" is a matrix: return a matrix
# Extraction on non-POINT geometries
poly = st_buffer(pnt, 1000)
st_extract(r, poly)

# Extraction with time matching
rdate = c(r, r*2, along = "date")
dates = c(Sys.Date()-1, Sys.Date())
rdate = st_set_dimensions(rdate, "date", values = c(dates))

pntsf = st_sf(date = dates, geometry = pnt)
st_extract(split(rdate, "band"), pntsf) # POINT geometries

polysf = st_buffer(pntsf, 1000)
st_extract(split(rdate, "band"), polysf, time_column = "date") # POLYGON geometries

vdc = st_sf(rdm = rnorm(20), polygons = st_buffer(st_sample(st_bbox(pnt), 20), 500),
			geometry = rep(pnt, 2), date = rep(dates, each = 10)) |> 
	st_as_stars(dims = c("geometry", "date"))

(vdc_new = st_extract(split(rdate, "band"), vdc)) # stars vector data cube
merge(vdc_new, name = "band")

### Extraction applied to the geometries inside the vector data cube (cell values)
(vdc_new2 = st_extract(split(rdate, "band"), vdc,
					   sfc_attribute = "polygons")) # stars vector data cube
merge(vdc_new2, name = "band")

r-spatial/stars documentation built on Feb. 19, 2025, 12:04 a.m.