# over-methods

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

##### 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.4-4, License: GPL (>= 2)*