terra: extract – R documentation

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

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.

When argument y is a SpatVector, and list=FALSE, the first column has the ID (record number) of the SpatVector used.

Usage

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

## S4 method for signature 'SpatRaster,SpatExtent'
extract(x, y, factors=TRUE, cells=FALSE, xy=FALSE)

## S4 method for signature 'SpatRaster,matrix'
extract(x, y, ...)

## S4 method for signature '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. If `weights=TRUE` or `exact=TRUE` only codemean, `sum`, `min` and `max` are accepted)
`...`	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)
`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 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`

Value

matrix, list, or data.frame

Examples

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/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,]
z <- rast(v, res=.1, names="test")
values(z) <- 1:ncell(z)

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

#e <- extract(z, v)
#e
#tapply(e[,2], e[,1], mean, na.rm=TRUE)

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

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


#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)

terra

Spatial Data Analysis

v1.2-10

GPL (>= 3)

Authors

Robert J. Hijmans [cre, aut] (<https://orcid.org/0000-0001-5872-2872>), Roger Bivand [ctb] (<https://orcid.org/0000-0003-2392-6140>), Karl Forner [ctb], Jeroen Ooms [ctb] (<https://orcid.org/0000-0002-4035-0289>), Edzer Pebesma [ctb] (<https://orcid.org/0000-0001-8049-7069>)

Initial release

2021-05-12