nndist: Nearest neighbour distances
In spatstat.geom: Geometrical Functionality of the 'spatstat' Family
nndist R Documentation
Nearest neighbour distances
Description
Computes the distance from each point to its nearest neighbour
in a point pattern. Alternatively computes the distance to the
second nearest neighbour, or third nearest, etc.
Usage
nndist(X, ...)
## S3 method for class 'ppp'
nndist(X, ..., k=1, by=NULL, method="C", metric=NULL)
## Default S3 method:
nndist(X, Y=NULL, ..., k=1, by=NULL, method="C")
Arguments
X, Y
Arguments specifying the locations of
a set of points.
For nndist.ppp, the argument X should be a point
pattern (object of class "ppp").
For nndist.default, typically X and Y would be
numeric vectors of equal length. Alternatively Y may be
omitted and X may be
a list with two components x and y,
or a matrix with two columns.
Alternatively X can be
a three-dimensional point pattern (class "pp3"),
a higher-dimensional point pattern (class "ppx"),
a point pattern on a linear network (class "lpp"),
or a spatial pattern of line segments (class "psp").
...
Ignored by nndist.ppp
and nndist.default.
k
Integer, or integer vector. The algorithm will compute the distance to the
kth nearest neighbour.
by
Optional. A factor, which separates X into groups.
The algorithm will compute the distance to the nearest point in each
group. See Details.
method
String specifying which method of calculation to use.
Values are "C" and "interpreted".
metric
Optional. A metric (object of class "metric")
that will be used to define and compute the distances.
Details
This function computes the Euclidean distance from each point
in a point pattern to its nearest neighbour (the nearest other
point of the pattern). If k is specified, it computes the
distance to the kth nearest neighbour.
The function nndist is generic, with
a method for point patterns (objects of class "ppp"),
and a default method for coordinate vectors.
There are also methods for line segment patterns,
nndist.psp,
three-dimensional point patterns, nndist.pp3,
higher-dimensional point patterns, nndist.ppx
and point patterns on a linear network,
nndist.lpp;
these are described in their own help files.
Type methods(nndist) to see all available methods.
The method for planar point patterns nndist.ppp expects a single
point pattern argument X and returns the vector of its
nearest neighbour distances.
The default method expects that X and Y will determine
the coordinates of a set of points. Typically X and
Y would be numeric vectors of equal length. Alternatively
Y may be omitted and X may be a list with two components
named x and y, or a matrix or data frame with two columns.
The argument k may be a single integer, or an integer vector.
If it is a vector, then the kth nearest neighbour distances are
computed for each value of k specified in the vector.
If the argument by is given, it should be a factor,
of length equal to the number of points in X.
This factor effectively partitions X into subsets,
each subset associated with one of the levels of X.
The algorithm will then compute, for each point of X,
the distance to the nearest neighbour in each subset.
The argument method is not normally used. It is
retained only for checking the validity of the software.
If method = "interpreted" then the distances are
computed using interpreted R code only. If method="C"
(the default) then C code is used.
The C code is faster by two to three orders of magnitude
and uses much less memory.
If there is only one point (if x has length 1),
then a nearest neighbour distance of Inf is returned.
If there are no points (if x has length zero)
a numeric vector of length zero is returned.
To identify which point is the nearest neighbour of a given point,
use nnwhich.
To use the nearest neighbour distances for statistical inference,
it is often advisable to use the edge-corrected empirical distribution,
computed by Gest.
To find the nearest neighbour distances from one point pattern
to another point pattern, use nncross.
Value
Numeric vector or matrix containing the
nearest neighbour distances for each point.
If k = 1 (the default), the return value is a
numeric vector v such that v[i] is the
nearest neighbour distance for the ith data point.
If k is a single integer, then the return value is a
numeric vector v such that v[i] is the
kth nearest neighbour distance for the
ith data point.
If k is a vector, then the return value is a
matrix m such that m[i,j] is the
k[j]th nearest neighbour distance for the
ith data point.
If the argument by is given, then it should be a factor
which separates X into groups (or any type of data acceptable to
split.ppp that determines the grouping).
The result is a data frame containing the distances described above,
from each point of X,
to the nearest point in each subset of X
defined by the grouping factor by.
Nearest neighbours of each type
If X is a multitype point pattern
and by=marks(X), then the algorithm will compute,
for each point of X, the distance to the nearest neighbour
of each type. See the Examples.
To find the minimum distance from any point of type i
to the nearest point of type j, for all combinations of i and
j, use minnndist,
or the R function aggregate as
suggested in the Examples.
Warnings
An infinite or NA value is returned if the
distance is not defined (e.g. if there is only one point
in the point pattern).
Author(s)
\pavel
and
\adrian.
See Also
nndist.psp,
nndist.pp3,
nndist.ppx,
pairdist,
Gest,
nnwhich,
nncross,
minnndist, maxnndist.
Examples
# nearest neighbours
d <- nndist(cells)
# second nearest neighbours
d2 <- nndist(cells, k=2)
# first, second and third nearest
d1to3 <- nndist(cells, k=1:3)
x <- runif(100)
y <- runif(100)
d <- nndist(x, y)
# Stienen diagram
plot(cells %mark% nndist(cells), markscale=1)
# distance to nearest neighbour of each type
nnda <- nndist(ants, by=marks(ants))
head(nnda)
# For nest number 1, the nearest Cataglyphis nest is 87.32125 units away
# minimum distance between each pair of types
minnndist(ants, by=marks(ants))
# Use of 'aggregate':
# _minimum_ distance between each pair of types
aggregate(nnda, by=list(from=marks(ants)), min)
# _mean_ nearest neighbour distances
aggregate(nnda, by=list(from=marks(ants)), mean)
# The mean distance from a Messor nest to
# the nearest Cataglyphis nest is 59.02549 units
spatstat.geom documentation built on Sept. 18, 2024, 9:08 a.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.
| nndist | R Documentation |
Nearest neighbour distances
Description
Computes the distance from each point to its nearest neighbour in a point pattern. Alternatively computes the distance to the second nearest neighbour, or third nearest, etc.
Usage
nndist(X, ...)
## S3 method for class 'ppp'
nndist(X, ..., k=1, by=NULL, method="C", metric=NULL)
## Default S3 method:
nndist(X, Y=NULL, ..., k=1, by=NULL, method="C")
Arguments
X, Y |
Arguments specifying the locations of
a set of points.
For |
... |
Ignored by |
k |
Integer, or integer vector. The algorithm will compute the distance to the
|
by |
Optional. A factor, which separates |
method |
String specifying which method of calculation to use.
Values are |
metric |
Optional. A metric (object of class |
Details
This function computes the Euclidean distance from each point
in a point pattern to its nearest neighbour (the nearest other
point of the pattern). If k is specified, it computes the
distance to the kth nearest neighbour.
The function nndist is generic, with
a method for point patterns (objects of class "ppp"),
and a default method for coordinate vectors.
There are also methods for line segment patterns,
nndist.psp,
three-dimensional point patterns, nndist.pp3,
higher-dimensional point patterns, nndist.ppx
and point patterns on a linear network,
nndist.lpp;
these are described in their own help files.
Type methods(nndist) to see all available methods.
The method for planar point patterns nndist.ppp expects a single
point pattern argument X and returns the vector of its
nearest neighbour distances.
The default method expects that X and Y will determine
the coordinates of a set of points. Typically X and
Y would be numeric vectors of equal length. Alternatively
Y may be omitted and X may be a list with two components
named x and y, or a matrix or data frame with two columns.
The argument k may be a single integer, or an integer vector.
If it is a vector, then the kth nearest neighbour distances are
computed for each value of k specified in the vector.
If the argument by is given, it should be a factor,
of length equal to the number of points in X.
This factor effectively partitions X into subsets,
each subset associated with one of the levels of X.
The algorithm will then compute, for each point of X,
the distance to the nearest neighbour in each subset.
The argument method is not normally used. It is
retained only for checking the validity of the software.
If method = "interpreted" then the distances are
computed using interpreted R code only. If method="C"
(the default) then C code is used.
The C code is faster by two to three orders of magnitude
and uses much less memory.
If there is only one point (if x has length 1),
then a nearest neighbour distance of Inf is returned.
If there are no points (if x has length zero)
a numeric vector of length zero is returned.
To identify which point is the nearest neighbour of a given point,
use nnwhich.
To use the nearest neighbour distances for statistical inference,
it is often advisable to use the edge-corrected empirical distribution,
computed by Gest.
To find the nearest neighbour distances from one point pattern
to another point pattern, use nncross.
Value
Numeric vector or matrix containing the nearest neighbour distances for each point.
If k = 1 (the default), the return value is a
numeric vector v such that v[i] is the
nearest neighbour distance for the ith data point.
If k is a single integer, then the return value is a
numeric vector v such that v[i] is the
kth nearest neighbour distance for the
ith data point.
If k is a vector, then the return value is a
matrix m such that m[i,j] is the
k[j]th nearest neighbour distance for the
ith data point.
If the argument by is given, then it should be a factor
which separates X into groups (or any type of data acceptable to
split.ppp that determines the grouping).
The result is a data frame containing the distances described above,
from each point of X,
to the nearest point in each subset of X
defined by the grouping factor by.
Nearest neighbours of each type
If X is a multitype point pattern
and by=marks(X), then the algorithm will compute,
for each point of X, the distance to the nearest neighbour
of each type. See the Examples.
To find the minimum distance from any point of type i
to the nearest point of type j, for all combinations of i and
j, use minnndist,
or the R function aggregate as
suggested in the Examples.
Warnings
An infinite or NA value is returned if the
distance is not defined (e.g. if there is only one point
in the point pattern).
Author(s)
\paveland \adrian.
See Also
nndist.psp,
nndist.pp3,
nndist.ppx,
pairdist,
Gest,
nnwhich,
nncross,
minnndist, maxnndist.
Examples
# nearest neighbours
d <- nndist(cells)
# second nearest neighbours
d2 <- nndist(cells, k=2)
# first, second and third nearest
d1to3 <- nndist(cells, k=1:3)
x <- runif(100)
y <- runif(100)
d <- nndist(x, y)
# Stienen diagram
plot(cells %mark% nndist(cells), markscale=1)
# distance to nearest neighbour of each type
nnda <- nndist(ants, by=marks(ants))
head(nnda)
# For nest number 1, the nearest Cataglyphis nest is 87.32125 units away
# minimum distance between each pair of types
minnndist(ants, by=marks(ants))
# Use of 'aggregate':
# _minimum_ distance between each pair of types
aggregate(nnda, by=list(from=marks(ants)), min)
# _mean_ nearest neighbour distances
aggregate(nnda, by=list(from=marks(ants)), mean)
# The mean distance from a Messor nest to
# the nearest Cataglyphis nest is 59.02549 units
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.