raster (version 2.1-41)

extract: Extract values from Raster objects

Description

Extract values from a Raster* object at the locations of other spatial data (that is, perform a spatial query). You can use coordinates (points), lines, polygons or an Extent (rectangle) object. You can also use cell numbers to extract values. If y represents points, extract returns the values of a Raster* object for the cells in which a set of points fall. If y represents lines, the extract method returns the values of the cells of a Raster* object that are touched by a line. If y represents polygons, the extract method returns the values of the cells of a Raster* object that are covered by a polygon. A cell is covered if its center is inside the polygon (but see the weights option for considering partly covered cells; and argument small for getting values for small polygons anyway).

Usage

## S3 method for class 'Raster,matrix':
extract(x, y, method='simple', buffer=NULL, small=FALSE, cellnumbers=FALSE, 
     fun=NULL, na.rm=TRUE, layer, nl, df=FALSE, factors=FALSE, ...)

## S3 method for class 'Raster,SpatialLines':
extract(x, y, fun=NULL, na.rm=FALSE, cellnumbers=FALSE, df=FALSE, layer,
     nl, factors=FALSE, along=FALSE, sp=FALSE, ...)

## S3 method for class 'Raster,SpatialPolygons':
extract(x, y, fun=NULL, na.rm=FALSE, weights=FALSE, cellnumbers=FALSE,
     small=FALSE, df=FALSE, layer, nl, factors=FALSE, sp=FALSE, ...)

Arguments

x

Raster* object

y

points represented by a two-column matrix or data.frame, or SpatialPoints*; SpatialPolygons*; Spat

method

character. 'simple' or 'bilinear'. If 'simple' values for the cell a point falls in are returned. If 'bilinear' the returned values are interpolated from the values of the four nearest raster cells.

buffer

numeric. The radius of a buffer around each point from which to extract cell values. If the distance between the sampling point and the center of a cell is less than or equal to the buffer, the cell is included. The buffer can be specified as a single val

small

logical. If TRUE and y represents points and a buffer argument is used, the function always return a number, also when the buffer does not include the center of a single cell. The value of the cell in which the point

fun

function to summarize the values (e.g. mean). The function should take a single numeric vector as argument and return a single value (e.g. mean, min or max), and accept a na.rm argument. Thus, standard R functions not including a

na.rm

logical. Only useful when an argument fun is supplied. If na.rm=TRUE (the default value), NA values are removed before fun is applied. This argument may be ignored if the function used has a ... argument and ignores

cellnumbers

logical. If cellnumbers=TRUE, cell-numbers will also be returned (if no fun argument is supplied, and when extracting values with points, if buffer is NULL)

df

logical. If df=TRUE, results will be returned as a data.frame. The first column is a sequential ID, the other column(s) are the extracted values.

weights

logical. If TRUE, the function returns, for each polygon, a matrix with the cell values and the approximate fraction of each cell that is covered by the polygon(rounded to 1/100). The weights can be used for averaging; see examples. This opti

factors

logical. If TRUE, factor values are returned, else their integer representation is returned

layer

integer. First layer for which you want values (if x is a multilayer object)

nl

integer. Number of layers for which you want values (if x is a multilayer object)

along

boolean. Should returned values be ordered to go along the lines?

sp

boolean. Should the extracted values be added to the data.frame of the Spatial* object y? This only applies if y is a Spatial* object and, for SpatialLines and SpatialPolygons, if fun is not NULL. In this case the re

...

additional arguments (none implemented)

Value

• A vector for RasterLayer objects, and a matrix for RasterStack or RasterBrick objects. A list or data.frame {df=TRUE} if y is a SpatialPolygons* or SpatialLines* object or if a buffer argument is used (but not a fun argument). If sp=TRUE (and y is a Spatial* object and fun is not NULL) a Spatial* object is returned. The order of the returned values corresponds to the order of object y.

See Also

getValues, getValuesFocal

Examples

r <- raster(ncol=36, nrow=18)
r[] <- 1:ncell(r)

###############################
# extract values by cell number
###############################
extract(r, c(1:2, 10, 100))
s <- stack(r, sqrt(r), r/r)
extract(s, c(1, 10, 100), layer=2, n=2)

###############################
# extract values with points
###############################
xy <- cbind(-50, seq(-80, 80, by=20))
extract(r, xy)

sp <- SpatialPoints(xy)
extract(r, sp, method='bilinear')

# examples with a buffer
extract(r, xy[1:3,], buffer=1000000)
extract(r, xy[1:3,], buffer=1000000, fun=mean)

## illustrating the varying size of a buffer (expressed in meters) 
## on a longitude/latitude raster
 z <- extract(r, xy, buffer=1000000)
 s <- raster(r)
 for (i in 1:length(z)) { s[z[[i]]] <- i }
 
## compare with raster that is not longitude/latitude
 projection(r) <- "+proj=utm +zone=17" 
 xy[,1] <- 50
 z <- extract(r, xy, buffer=8)
 for (i in 1:length(z)) { s[z[[i]]] <- i }
 plot(s)
# library(maptools)
# data(wrld_simpl)
# plot(wrld_simpl, add=TRUE)

###############################
# extract values with lines
###############################

cds1 <- rbind(c(-50,0), c(0,60), c(40,5), c(15,-45), c(-10,-25))
cds2 <- rbind(c(80,20), c(140,60), c(160,0), c(140,-55))
lines <- SpatialLines(list(Lines(list(Line(cds1)), "1"), Lines(list(Line(cds2)), "2") ))

extract(r, lines)

###############################
# extract values with polygons
###############################
cds1 <- rbind(c(-180,-20), c(-160,5), c(-60, 0), c(-160,-60), c(-180,-20))
cds2 <- rbind(c(80,0), c(100,60), c(120,0), c(120,-55), c(80,0))
polys <- SpatialPolygons(list(Polygons(list(Polygon(cds1)), 1), 
                              Polygons(list(Polygon(cds2)), 2)))

#plot(r)
#plot(polys, add=TRUE)
v <- extract(r, polys)
v
# mean for each polygon
unlist(lapply(v, function(x) if (!is.null(x)) mean(x, na.rm=TRUE) else NA ))

# v <- extract(r, polys, cellnumbers=TRUE)

# weighted mean
# v <- extract(r, polys, weights=TRUE, fun=mean)
# equivalent to:
# v <- extract(r, polys, weights=TRUE)
# sapply(v, function(x) if (!is.null(x)) {sum(apply(x, 1, prod)) / sum(x[,2])} else NA  )


###############################
# extract values with an extent
###############################
e <- extent(150,170,-60,-40)
extract(r, e)
#plot(r)
#plot(e, add=T)

Run the code above in your browser using DataCamp Workspace