terra (version 1.1-17)

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 matrix with (x, y) or (longitude, latitude -- in that order!) coordinates, or a vector with cell numbers.

Usage

# S4 method for SpatRaster,SpatVector
extract(x, y, fun=NULL, method="simple", list=FALSE, factors=TRUE, 
        cells=FALSE, xy=FALSE, weights=FALSE, touches=is.lines(y), ...)
# S4 method for SpatRaster,SpatExtent
extract(x, y, factors=TRUE, cells=FALSE, xy=FALSE)
# S4 method for SpatRaster,matrix
extract(x, y, ...)
# S4 method for SpatRaster,numeric
extract(x, y, ...)

Arguments

x

SpatRaster

y

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

fun

function to summarize the data by geometry (e.g. polygon)

...

additional arguments to fun if y is a SpatVector or arguments passed to the SpatRaster,SpatVector method if y is a matrix (i.e., the method and cells arguments)

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

list

logical. If FALSE the output is simplified to a matrix (if fun=NULL)

factors

logical. If TRUE the categories are returned as factors instead of their numerical representation. The value returned becomes a data.frame if it otherwise would have been a matrix, even if there are no factors

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. Also see xyFromCell

weights

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

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

Value

matrix, list, or data.frame

See Also

values

Examples

# NOT RUN {
r <- rast(ncol=5, nrow=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/test.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,]
z <- rast(v, res=.1, names="test")
values(z) <- 1:ncell(z)
#e <- extract(z, v)
#e
#tapply(e[,2], e[,1], mean)

#ee <- extract(z, v, list=TRUE)
#rapply(ee, mean)

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

#extract(x, v, mean)

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

#ee <- extract(x, v, list=TRUE)
#matrix(rapply(ee, mean), ncol=nlyr(x), byrow=TRUE)
# }