over-methods

0th

Percentile

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

Keywords
methods
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.

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 preferred over points on polygon boundaries).

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.

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

See Also

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

Aliases
  • over
  • %over%
  • over-methods
  • over,SpatialPoints,SpatialPoints-method
  • over,SpatialPoints,SpatialPointsDataFrame-method
  • over,SpatialPoints,SpatialPolygons-method
  • over,SpatialPoints,SpatialPolygonsDataFrame-method
  • over,SpatialGridDataFrame,SpatialPolygonsDataFrame-method
  • over,SpatialPolygons,SpatialPoints-method
  • over,SpatialPolygons,SpatialPointsDataFrame-method
  • over,SpatialGridDataFrame,SpatialPoints-method
  • over,SpatialGrid,SpatialPoints-method
  • over,SpatialPixelsDataFrame,SpatialPoints-method
  • over,SpatialPixels,SpatialPoints-method
  • over,SpatialPoints,SpatialGrid-method
  • over,SpatialPoints,SpatialGridDataFrame-method
  • over,SpatialPoints,SpatialPixels-method
  • over,SpatialPoints,SpatialPixelsDataFrame-method
  • over,SpatialPolygons,SpatialGridDataFrame-method
  • over,SpatialGrid,SpatialPolygons-method
  • over,SpatialGrid,SpatialPolygonsDataFrame-method
  • over,SpatialPolygons,SpatialGrid-method
  • over,SpatialGrid,SpatialGrid-method
  • over,SpatialGrid,SpatialGridDataFrame-method
  • over,SpatialGrid,SpatialPixels-method
  • over,SpatialGrid,SpatialPixelsDataFrame-method
  • over,SpatialGrid,SpatialPointsDataFrame-method
  • over,Spatial,Spatial-method
  • overDF_for_rgeos
Examples
# NOT RUN {
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)
# }
Documentation reproduced from package sp, version 1.3-1, License: GPL (>= 2)

Community examples

Looks like there are no examples yet.