terra (version 1.8-5)

extract: Extract values from a SpatRaster

Description

Extract values from a SpatRaster for a set of locations. The locations can be a SpatVector (points, lines, polygons), a data.frame or matrix with (x, y) or (longitude, latitude -- in that order!) coordinates, or a vector with cell numbers.

When argument y is a SpatVector the first column has the ID (record number) of the SpatVector used (unless you set ID=FALSE).

Alternatively, you can use zonal after using rasterize with a SpatVector (this may be more efficient in some cases).

Usage

# S4 method for SpatRaster,SpatVector
extract(x, y, fun=NULL, method="simple", cells=FALSE, xy=FALSE,
    ID=TRUE, weights=FALSE, exact=FALSE, touches=is.lines(y), small=TRUE,
	layer=NULL, bind=FALSE, raw=FALSE, ...)
# S4 method for SpatRaster,SpatExtent
extract(x, y, cells=FALSE, xy=FALSE)
# S4 method for SpatRaster,matrix
extract(x, y, cells=FALSE, method="simple")
# S4 method for SpatRaster,numeric
extract(x, y, xy=FALSE, raw=FALSE)
# S4 method for SpatVector,SpatVector
extract(x, y)

Value

data.frame, matrix or SpatVector

Arguments

x

SpatRaster or SpatVector of polygons

y

SpatVector (points, lines, or polygons). Alternatively, for points, a 2-column matrix or data.frame (x, y) or (lon, lat). Or a vector with cell numbers

fun

function to summarize the extracted data by line or polygon geometry. You can use fun=table to tabulate raster values for each line or polygon geometry. If weights=TRUE or exact=TRUE only mean, sum, min, max and table are accepted). Ignored if y has point geometry

method

character. method for extracting values with points ("simple" or "bilinear"). With "simple" values for the cell a point falls in are returned. With "bilinear" the returned values are interpolated from the values of the four nearest raster cells

cells

logical. If TRUE the cell numbers are also returned, unless fun is not NULL. Also see cells

xy

logical. If TRUE the coordinates of the cells are also returned, unless fun is not NULL. See xyFromCell

ID

logical. Should an ID column be added? If so, the first column returned has the IDs (record numbers) of y

weights

logical. If TRUE and y has polygons, the approximate fraction of each cell that is covered is returned as well, for example to compute a weighted mean

exact

logical. If TRUE and y has polygons, the exact fraction of each cell that is covered is returned as well, for example to compute a weighted mean

touches

logical. If TRUE, values for all cells touched by lines or polygons are extracted, not just those on the line render path, or whose center point is within the polygon. Not relevant for points; and always considered TRUE when weights=TRUE or exact=TRUE

small

logical. If TRUE, values for all cells in touched polygons are extracted if none of the cells center points is within the polygon; even if touches=FALSE

layer

character or numeric to select the layer to extract from for each geometry. If layer is a character it can be a name in y or a vector of layer names. If it is numeric, it must be integer values between 1 and nlyr(x)

bind

logical. If TRUE, a SpatVector is returned consisting of the input SpatVector y and the cbind-ed extracted values

raw

logical. If TRUE, a matrix is returned with the "raw" numeric cell values. If FALSE, a data.frame is returned and the cell values are transformed to factor, logical, or integer values, where appropriate

...

additional arguments to fun if y is a SpatVector. For example na.rm=TRUE. Or arguments passed to the SpatRaster,SpatVector method if y is a matrix (such as the method and cells arguments)

See Also

values, zonal, extractAlong, extractRange, rapp

Examples

r <- rast(ncols=5, nrows=5, xmin=0, xmax=5, ymin=0, ymax=5)
values(r) <- 1:25
xy <- rbind(c(0.5,0.5), c(2.5,2.5))
p <- vect(xy, crs="+proj=longlat +datum=WGS84")

extract(r, xy)
extract(r, p)

r[1,]
r[5]
r[,5]

r[c(0:2, 99:101)]

f <- system.file("ex/meuse.tif", package="terra")
r <- rast(f)

xy <- cbind(179000, 330000)
xy <- rbind(xy-100, xy, xy+1000)
extract(r, xy)

p <- vect(xy)
g <- geom(p)
g

extract(r, p)

x <- r + 10
extract(x, p)

i <- cellFromXY(r, xy)
x[i]
r[i]

y <- c(x,x*2,x*3)
y[i]

## extract with a polygon
f <- system.file("ex/lux.shp", package="terra")
v <- vect(f)
v <- v[1:2,]

rf <- system.file("ex/elev.tif", package="terra")
x <- rast(rf)
extract(x, v, mean, na.rm=TRUE)

z <- rast(v, resolution=.1, names="test")
values(z) <- 1:ncell(z)
e <- extract(z, v, ID=TRUE)
e
tapply(e[,2], e[,1], mean, na.rm=TRUE)

x <- c(z, z*2, z/3)
names(x) <- letters[1:3]

e <- extract(x, v, ID=TRUE)
de <- data.frame(e)
aggregate(de[,2:4], de[,1,drop=FALSE], mean)