nncount: Nearest Neighbour Cross-Type Occurrence Count Function

In spatstat.explore: Exploratory Data Analysis for the 'spatstat' Family

Nearest Neighbour Cross-Type Occurrence Count Function

Description

Compute the estimated nearest neighbour cross-type occurrence count function for a multitype point pattern dataset.

Usage

nncount(X, i = 1, j = 2, ..., kmax = 20, ratio = TRUE, cumulative = TRUE)

Arguments

X	A multitype point pattern (object of class "ppp" with marks that are a factor).
i	The type (mark value) of the points in X which will serve as the reference points from which neighbours are counted. A character string (or something that will be converted to a character string) or an integer. Defaults to the first level of marks(X).
j	The type (mark value) of the points in X which will be counted as neighbours of interest. A character string (or something that will be converted to a character string), or an integer. Defaults to the second level of marks(X).
kmax	Maximum number of neighbours to be considered for each point.
cumulative	Logical value indicating whether to compute the cumulative estimate. See Details.
ratio	Logical value indicating whether to save ratio information for future use in pooling data.
...	Ignored.

Details

The nearest-neighbour cross-type occurrence function counts the frequency with which points of types i and j are found close together, as defined by the nearest-neighbour relationship of order k for k=1,2,...,kmax.

The algorithm visits each point of X that belongs to type i, and finds its nearest neighbour, second-nearest neighbour, and so on, until the nearest neighbour of order kmax. The algorithm counts the number of occurrences of type j.

The result is a function that can be plotted to show the observed and expected frequencies of these occurrences as a function of the nearest-neighbour order k.

The function has two versions: cumulative and non-cumulative. The non-cumulative version is a function P_{ij}(k) which gives, for each integer k, the estimated probability that a typical point in the point pattern of type i will have a k-th nearest neighbour of type j. For example P_{A,B}(5)=0.6 would mean that, for a typical point of type A, there is a 60 percent chance that the fifth-nearest neighbour will be a point of type B. When cumulative=FALSE, the algorithm computes an estimate of P_{ij}(k) for each integer k up to kmax, and returns the result as a function.

The cumulative version is Q_{ij}(k) = \sum_{m=1}^k P_{ij}(m)/k. This means that Q_{ij}(k) is the average proportion of points of type j amongst the nearest k neighbours of a point of type i. For example Q_{A,B}(5)=0.6 would mean that, on average, three out of the first five nearest neighbours of a point of type A will have type B. This function is computed when cumulative=TRUE (the default).

In either case, the result is a function value table (class "fv") with two columns of values, one giving the estimate of P_{i,j}(k) or Q_{i,j}(k), and the other giving the corresponding average value for the pattern. Estimated values greater than the average suggest that points of type j are clustered closer to points of type i than would be expected by chance.

The arguments i and j should specify levels of the factor marks(X). They can be given either as character strings (which will be matched to the levels of the factor) or integers (which will be interpreted as indices for the vector of levels of the factor, so that 1 represents the first level.)

Value

A function value table (object of class "fv") which can be printed and plotted. The function has argument k (the order of neighbour) and columns of values labelled bord (for the border-correction estimate) and theo (for the theoretical value expected under random labelling).

Author(s)

\adrian

and \Lucia Cobo-\Sanchez.

References

Diez-\Martin, F., Cobo-\Sanchez, L., Baddeley, A., Uribelarrea, D., Mabulla, A., Baquedano, E. and \Dominguez-Rodrigo, M. (2021) Tracing the spatial imprint of Oldowan technological behaviors: A view from DS (Bed I, Olduvai Gorge, Tanzania). PLOS ONE, Public Library of Science, 16, 1–47. DOI: 10.1371/journal.pone.0254603

See Also

nnequal

Examples

  plot(nncount(amacrine, "off", "on"))
  plot(envelope(amacrine, nncount, nsim=19))
  plot(envelope(amacrine, nncount, cumulative=FALSE, nsim=19))

spatstat.explore documentation built on Nov. 22, 2025, 9:07 a.m.