# pointsInPolygons

##### R function to test points-in-polygons relationship

The function allows to test: -scenario a: if there is a significant spatial association between a set of points and a set of polygons, in terms of points falling within the polygons. In other words, it aims at testing whether a set of points falls inside a set of polygons more often than would be expected by chance. The basic assumption is that the polygons are completely contained within the study plot. If the shapefile (of polygon type) representing the study plot is not provided, the calculations use the bounding polygon based on the union the convex hulls of the point and of the polygon feature. -scenario b: if the distribution of points within a set of polygons totally covering the study area can be considered random, or if the observed points count for each polygon is larger or smaller than expected. P values are also reported.

- Keywords
- pointsInPolygons

##### Usage

```
pointsInPolygons(point.feat, polyg.feat, studyplot = NULL, scenario,
buffer = 0, cex.text = 0.7)
```

##### Arguments

- point.feat
Feature (of point type; SpatialPointsDataFrame class) whose spatial association with the polygons has to be assessed.

- polyg.feat
Feature (polygon type; SpatialPolygonsDataFrame) in relation to which the spatial association of the points has to be assessed.

- studyplot
Shapefile (of polygon type; SpatialPolygonsDataFrame) representing the study area; if not provided, the study area is internally worked out as the bounding polygon based on the union the convex hulls of the point and of the polygon feature.

- scenario
Select one of the two types of analysis available ("a" or "b").

- buffer
Add a buffer to the convex hull of the study area (0 by default); the unit depends upon the units of the input data.

- cex.text
Modify the size of the labels in the plot produced by the 'scenario b' option.

##### Details

The computations relative to scenario "a" are based on the 'dbinom() and 'pbinom()' functions. The probability of observed count within polygons is \(dbinom(x, size=n.of.points, prob=p)\), where 'x' is the observed number of points within polygons, 'n.of.points' is the total number of points, and 'p' is the probability that a single point will be found within a polygon, which is equal to the ratio between the area of the polygons and the total area of the study plot. The probability that x or fewer points will be found within the polygons is \(pbinom(x, size=n.of.points, prob=p)\).

The calculations relative to the scenario "b" are again based on the binomial distribution: the probability of the observed counts is \(dbinom(x, size=n.of.points, prob=p)\), where 'x' is the observed number of points within a given polygon, 'n.of.points' is the total number of points, and 'p' is equal to the size of each polygon relative to sum of the polygons' area. The probability that x or fewer points will be found within a given polygon is \(pbinom(x, size=n.of.points, prob=p)\).

##### Value

For scenario "a" the function produces a plot of the points and polygons (plus the study area), and relevant information are reported at the bottom of the chart itself.

A list is also returned, containing what follows: -$Polygons' area; -$Study area's area; -$Total # of points; -$Observed # of points in polygons; -$Expected # of points in polygons; -$Exact probability of observed count within polygons; -$Probability of <= observed count within polygons; -$Probability of >= observed count within polygons.

For scenario "b" the function returns a plot showing the polygons plus the dots; in each polygon the observed and expected counts are reported, and the p-value of the observed count is indicated.

A matrix is also returned, containing what follows: -polygons' area; -percentage area (size of each polygon relative to sum of the polygons' area; it corresponds to the probability (p) fed into the binomial distribution function); -observed number of points; -expected number of points; -probability of observed counts; -probability of observed counts <= than expected; -probability of observed counts >= than expected.

##### See Also

##### Examples

```
# NOT RUN {
data(points)
data(polygons)
result <- pointsInPolygons(points, polygons, scenario="a")
data(events)
data(thiessenpolyg)
result <- pointsInPolygons(events, thiessenpolyg, scenario="b")
# }
```

*Documentation reproduced from package GmAMisc, version 1.0.0, License: GPL (>= 2)*