R: consistent spatial overlay for points, grids and polygons

over-methods {sp} | R Documentation

## consistent spatial overlay for points, grids and polygons

### 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`, 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).

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

### Author(s)

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

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

[Package sp version 1.4-5 Index]