distRandSign: R function to test for a significant spatial association...
In GmAMisc: 'Gianmarco Alberti' Miscellaneous
distRandSign R Documentation
R function to test for a significant spatial association between two features (points-to-points,
points-to-lines, points-to-polygons)
Description
The function allows to assess if there is a significant spatial association between a point
pattern and the features of another pattern. For instance, users may want to assess if some
locations tend to lie close to some features represented by polylines. By the same token, users
may want to know if there is a spatial association between the location of a given event and the
location of another event. See the example provided further below (in the examples section),
where the question to address is if there is a spatial association between springs and geological
fault-lines; in other words: do springs tend to be located near the geological faults?
Usage
distRandSign(
from.feat,
to.feat,
studyplot = NULL,
buffer = 0,
B = 199,
oneplot = TRUE,
export = FALSE
)
Arguments
from.feat
Feature (of point type; SpatialPointsDataFrame class) whose spatial association
with the to-feature has to be assessed.
to.feat
Feature (point, polyline, or polygon type; SpatialPointsDataFrame,
SpatialLinesDataFrame, SpatialPolygonsDataFrame class) in relation to which the spatial
association of the from-feature has to be assessed.
studyplot
Feature (of polygon type; SpatialPolygonsDataFrame class) 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 from- and of the to-feature.
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.
B
Number of randomizations to be used (199 by default).
oneplot
TRUE (default) or FALSE if the user wants or does not want the plots displayed in
a single window.
export
FALSE (default) or TRUE is the user wants to export the input dataset as a shapefile
(see description for further info).
Details
Given a from-feature (event for which we want to estimate the spatial association with the
to-feature) and a to-feature (event in relation to which we want to estimate the spatial
association for the from-feature), the assessment is performed by means of a randomized
procedure:
-keeping fixed the location of the to-feature, random from-features are drawn B times (the number
of randomized from-features is equal to the number of observed from-features);
-for each draw,
the average minimum distance to the to-features is calculated; if the to-feature is made up of
polygons, the from-features falling within a polygon will have a distance of 0;
-a
distribution of average minimum distances is thus obtained;
-p values are computed following
Baddeley et al., "Spatial Point Patterns. Methodology and Applications with R", CRC Press 2016,
p. 387.
The from-feature must be a point feature, whilst the to-feature can be a point or a polyline or a
polygon feature.
The rationale of the procedure is that, if there indeed is a spatial association between the two
features, the from-feature should be on average closer to the to-feature than randomly generated
from-features. If the studyplot shapefile is not provided, the random locations are drawn within
a bounding polygon based on the union the convex hulls of the from- and of the to-feature.
If both the from-feature and the to-feature are of point type (SpatialPointsDataFrame class), the
function also test the spatial association by means of a permuted procedures. Unlike the
procedure described above, whereby random points are drawn within the study area, the
permutation-based routine builds a distribution of averages minimum distances keeping the points
location unchanged and randomly assigning the points to either of the two patterns. The
re-assignment is performed B times (199 by default) and each time the average minimum distance is
calculated.
The function produces a histogram showing: the distribution of randomized average minimum
distances; a black dot indicating the observed average minimum distance; a hollow dot
representing the average of the randomized minimum distances; two blue reference lines correspond
to the 0.025th and to the 0.975th quantile of the randomized distribution. P-values are reported
at the bottom of the plot.
In case both the from- and the to- feature are of point type, another histogram is produced,
which provides the same information of the preceding histogram, but derived from the
permutation-based routine that has been detailed above.
The function also produces a map showing the study area, the from- and the to-features.
The from-features are given a colour according to whether or not their minimum distance to
the nearest to-feature is smaller (GREEN) or larger (RED) than the 0.025 and 0.975 quantile
(respectively) of the distribution of the randomized average distances.
This information is also reported in a new field that is appended to the input dataset.
Optionally, the input dataset (with 2 new columns added) can be exported using the 'export'parameter.
The new columns store: the features' minimum distance to the nearest to-feature;
a string indicating if the corresponding feature is closer or more distant than expected to the
nearest to-feature.
Value
The function returns a list storing the following components
$from.feat.min.dist: distance of each entity of the from-feature to the nearest entity
of the to-feature
$avrg.obs.min.dist: observed average minimum distance
$avrg.rnd.min.dist: average randomized minimum distance
$avrg.perm.min.dist: average permuted minimum distance (returned only when both the
from- and to- features are of point type)
$p.value closer than expected-rnd-
$p.value closer than expected-perm- (returned only when both the from- and to-
features are of point type)
$p.value more distant than expected-rnd-
$p.value more distant than expected-perm- (returned only when both the from- and to-
features are of point type)
$p.value different from random-rnd-:
$p.value different from random-perm- (returned only when both the from- and to-
features are of point type)
$dataset: from.feature dataset with 2 fields added: one ('obs.min.dist') storing the from-features's minimum
distance to the nearest to-feature, one ('signif') storing the significance of the distance (see description)
See Also
distRandCum , distCovarModel , Aindex
Examples
data(springs)
data(faults)
#calculate the significance of the spatial association between springs and geological
#fault-lines; plots displayed in a single panel
result <- distRandSign(from.feat=springs, to.feat=faults, oneplot=TRUE, B=19)
data(points)
data(polygons)
#calculate the significance of the spatial association between points and polygons
result <- distRandSign(from.feat=points, to.feat=polygons, oneplot=FALSE, B=19)
GmAMisc documentation built on March 18, 2022, 6:32 p.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| distRandSign | R Documentation |
R function to test for a significant spatial association between two features (points-to-points, points-to-lines, points-to-polygons)
Description
The function allows to assess if there is a significant spatial association between a point
pattern and the features of another pattern. For instance, users may want to assess if some
locations tend to lie close to some features represented by polylines. By the same token, users
may want to know if there is a spatial association between the location of a given event and the
location of another event. See the example provided further below (in the examples section),
where the question to address is if there is a spatial association between springs and geological
fault-lines; in other words: do springs tend to be located near the geological faults?
Usage
distRandSign( from.feat, to.feat, studyplot = NULL, buffer = 0, B = 199, oneplot = TRUE, export = FALSE )
Arguments
from.feat |
Feature (of point type; SpatialPointsDataFrame class) whose spatial association with the to-feature has to be assessed. |
to.feat |
Feature (point, polyline, or polygon type; SpatialPointsDataFrame, SpatialLinesDataFrame, SpatialPolygonsDataFrame class) in relation to which the spatial association of the from-feature has to be assessed. |
studyplot |
Feature (of polygon type; SpatialPolygonsDataFrame class) 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 from- and of the to-feature. |
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. |
B |
Number of randomizations to be used (199 by default). |
oneplot |
TRUE (default) or FALSE if the user wants or does not want the plots displayed in a single window. |
export |
FALSE (default) or TRUE is the user wants to export the input dataset as a shapefile (see description for further info). |
Details
Given a from-feature (event for which we want to estimate the spatial association with the
to-feature) and a to-feature (event in relation to which we want to estimate the spatial
association for the from-feature), the assessment is performed by means of a randomized
procedure:
-keeping fixed the location of the to-feature, random from-features are drawn B times (the number
of randomized from-features is equal to the number of observed from-features);
-for each draw,
the average minimum distance to the to-features is calculated; if the to-feature is made up of
polygons, the from-features falling within a polygon will have a distance of 0;
-a
distribution of average minimum distances is thus obtained;
-p values are computed following
Baddeley et al., "Spatial Point Patterns. Methodology and Applications with R", CRC Press 2016,
p. 387.
The from-feature must be a point feature, whilst the to-feature can be a point or a polyline or a
polygon feature.
The rationale of the procedure is that, if there indeed is a spatial association between the two
features, the from-feature should be on average closer to the to-feature than randomly generated
from-features. If the studyplot shapefile is not provided, the random locations are drawn within
a bounding polygon based on the union the convex hulls of the from- and of the to-feature.
If both the from-feature and the to-feature are of point type (SpatialPointsDataFrame class), the
function also test the spatial association by means of a permuted procedures. Unlike the
procedure described above, whereby random points are drawn within the study area, the
permutation-based routine builds a distribution of averages minimum distances keeping the points
location unchanged and randomly assigning the points to either of the two patterns. The
re-assignment is performed B times (199 by default) and each time the average minimum distance is
calculated.
The function produces a histogram showing: the distribution of randomized average minimum
distances; a black dot indicating the observed average minimum distance; a hollow dot
representing the average of the randomized minimum distances; two blue reference lines correspond
to the 0.025th and to the 0.975th quantile of the randomized distribution. P-values are reported
at the bottom of the plot.
In case both the from- and the to- feature are of point type, another histogram is produced,
which provides the same information of the preceding histogram, but derived from the
permutation-based routine that has been detailed above.
The function also produces a map showing the study area, the from- and the to-features. The from-features are given a colour according to whether or not their minimum distance to the nearest to-feature is smaller (GREEN) or larger (RED) than the 0.025 and 0.975 quantile (respectively) of the distribution of the randomized average distances. This information is also reported in a new field that is appended to the input dataset. Optionally, the input dataset (with 2 new columns added) can be exported using the 'export'parameter. The new columns store: the features' minimum distance to the nearest to-feature; a string indicating if the corresponding feature is closer or more distant than expected to the nearest to-feature.
Value
The function returns a list storing the following components
$from.feat.min.dist: distance of each entity of the from-feature to the nearest entity of the to-feature
$avrg.obs.min.dist: observed average minimum distance
$avrg.rnd.min.dist: average randomized minimum distance
$avrg.perm.min.dist: average permuted minimum distance (returned only when both the from- and to- features are of point type)
$p.value closer than expected-rnd-
$p.value closer than expected-perm- (returned only when both the from- and to- features are of point type)
$p.value more distant than expected-rnd-
$p.value more distant than expected-perm- (returned only when both the from- and to- features are of point type)
$p.value different from random-rnd-:
$p.value different from random-perm- (returned only when both the from- and to- features are of point type)
$dataset: from.feature dataset with 2 fields added: one ('obs.min.dist') storing the from-features's minimum distance to the nearest to-feature, one ('signif') storing the significance of the distance (see description)
See Also
distRandCum , distCovarModel , Aindex
Examples
data(springs) data(faults) #calculate the significance of the spatial association between springs and geological #fault-lines; plots displayed in a single panel result <- distRandSign(from.feat=springs, to.feat=faults, oneplot=TRUE, B=19) data(points) data(polygons) #calculate the significance of the spatial association between points and polygons result <- distRandSign(from.feat=points, to.feat=polygons, oneplot=FALSE, B=19)
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.