Skip to Content

over-methods {sp}

consistent spatial overlay for points, grids and polygons
Package: 
sp
Version: 
1.2-3

Description

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

Values

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.

In case the rgeos over methods are used, matching is done by gRelate, which uses DE-9IM (https://en.wikipedia.org/wiki/DE-9IM). From the string returned, characters 1, 2, 4 and 5 are used, indicating the dimension of the overlap of the inner and boundary of each x geometry with the inner and boundary of each y geometry. The order in which matched y geometries are returned is determined by the dimension of the overlap (2: area overlap, 1: line in common, 0: point in common), and then by the position in the string (1, 2, 4, 5, meaning points in polygons are prefered over points on polygon boundaries).

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

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.

over methods that involve SpatialLines objects, or pairs of SpatialPolygons require package rgeos, and use gIntersects.

See Also

vignette("over") for examples and figures; point.in.polygon, package gIntersects

Examples

r1 = cbind(c(180114, 180553, 181127, 181477, 181294, 181007, 180409, 
180162, 180114), c(332349, 332057, 332342, 333250, 333558, 333676, 
332618, 332413, 332349))
r2 = cbind(c(180042, 180545, 180553, 180314, 179955, 179142, 179437, 
179524, 179979, 180042), c(332373, 332026, 331426, 330889, 330683, 
331133, 331623, 332152, 332357, 332373))
r3 = cbind(c(179110, 179907, 180433, 180712, 180752, 180329, 179875, 
179668, 179572, 179269, 178879, 178600, 178544, 179046, 179110),
c(331086, 330620, 330494, 330265, 330075, 330233, 330336, 330004, 
329783, 329665, 329720, 329933, 330478, 331062, 331086))
r4 = cbind(c(180304, 180403,179632,179420,180304),
c(332791, 333204, 333635, 333058, 332791))
 
sr1=Polygons(list(Polygon(r1)),"r1")
sr2=Polygons(list(Polygon(r2)),"r2")
sr3=Polygons(list(Polygon(r3)),"r3")
sr4=Polygons(list(Polygon(r4)),"r4")
sr=SpatialPolygons(list(sr1,sr2,sr3,sr4))
srdf=SpatialPolygonsDataFrame(sr, data.frame(cbind(1:4,5:2), 
    row.names=c("r1","r2","r3","r4")))
 
data(meuse)
coordinates(meuse) = ~x+y
 
# plot(meuse)
polygon(r1)
polygon(r2)
polygon(r3)
polygon(r4)
# retrieve mean heavy metal concentrations per polygon:
over(sr, meuse[,1:4], fn = mean)
 
# return the number of points in each polygon:
sapply(over(sr, geometry(meuse), returnList = TRUE), length)
 
data(meuse.grid)
coordinates(meuse.grid) = ~x+y
gridded(meuse.grid) = TRUE
 
over(sr, geometry(meuse))
over(sr, meuse)
over(sr, geometry(meuse), returnList = TRUE)
over(sr, meuse, returnList = TRUE)
 
over(meuse, sr)
over(meuse, srdf)
 
# same thing, with grid:
over(sr, meuse.grid)
over(sr, meuse.grid, fn = mean)
over(sr, meuse.grid, returnList = TRUE)
 
over(meuse.grid, sr)
over(meuse.grid, srdf, fn = mean)
over(as(meuse.grid, "SpatialPoints"), sr)
over(as(meuse.grid, "SpatialPoints"), srdf)

Author(s)

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

Documentation reproduced from package sp, version 1.2-3. License: GPL (>= 2)