consistent spatial overlay for points, grids and polygons

consistent spatial overlay for points, grids and polygons: at the spatial locations of object x retrieves the indexes or attributes from spatial object y

Usage

over(x, y, returnList = FALSE, fn = NULL, ...)
x %over% y

Arguments

x: geometry (locations) of the queries
y: layer from which the geometries or attributes are queried
returnList: logical; see value
fn: (optional) a function; see value
...: arguments passed on to function fn, except for the special argument minDimension: minimal dimension for an intersection to be counted; -1 takes any intersection, and does not order; 0 takes any intersection but will order according to dimensionality of the intersections (if returnList is TRUE, 1 (2) selects intersections with dimension 1, meaning lines (2, meaning areas); see vignette("over") for details

Value

If y is only geometry an object of length length(x). If returnList is FALSE, a vector with the (first) index of y for each geometry (point, grid cell centre, polygon or lines) matching x. if returnList is TRUE, a list of length length(x), with list element i the vector of all indices of the geometries in y that correspond to the $i$-th geometry in x.

If y has attribute data, attribute data are returned. returnList is FALSE, a data.frame with number of rows equal to length(x) is returned, if it is TRUE a list with length(x) elements is returned, with a list element the data.frame elements of all geometries in y that correspond to that element of x.

Methods

x = "SpatialPoints", y = "SpatialPolygons": returns a numeric vector of length equal to the number of points; the number is the index (number) of the polygon of y in which a point falls; NA denotes the point does not fall in a polygon; if a point falls in multiple polygons, the last polygon is recorded.
x = "SpatialPointsDataFrame", y = "SpatialPolygons": equal to the previous method, except that an argument fn=xxx is allowed, e.g. fn = mean which will then report a data.frame with the mean attribute values of the x points falling in each polygon (set) of y
x = "SpatialPoints", y = "SpatialPolygonsDataFrame": returns a data.frame of the second argument with row entries corresponding to the first argument
x = "SpatialPolygons", y = "SpatialPoints": returns the polygon index of points in y; if x is a SpatialPolygonsDataFrame, a data.frame with rows from x corresponding to points in y is returned.
x = "SpatialGridDataFrame", y = "SpatialPoints": returns object of class SpatialPointsDataFrame with grid attribute values x at spatial point locations y; NA for NA grid cells or points outside grid, and NA values on NA grid cells.
x = "SpatialGrid", y = "SpatialPoints": returns grid values x at spatial point locations y; NA for NA grid cells or points outside the grid
x = "SpatialPixelsDataFrame", y = "SpatialPoints": returns grid values x at spatial point locations y; NA for NA grid cells or points outside the grid
x = "SpatialPixels", y = "SpatialPoints": returns grid values x at spatial point locations y; NA for NA grid cells or points outside the grid
x = "SpatialPoints", y = "SpatialGrid": xx
x = "SpatialPoints", y = "SpatialGridDataFrame": xx
x = "SpatialPoints", y = "SpatialPixels": xx
x = "SpatialPoints", y = "SpatialPixelsDataFrame": xx
x = "SpatialPolygons", y = "SpatialGridDataFrame": xx

Author

Edzer Pebesma, edzer.pebesma@uni-muenster.de

Note

over can be seen as a left outer join in SQL; the match is a spatial intersection.

points on a polygon boundary and points corresponding to a polygon vertex are considered to be inside the polygon.

These methods assume that pixels and grid cells are never overlapping; for objects of class SpatialPixels this is not guaranteed.