# over-methods {sp}

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

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