GeoNeighIndex: Spatial, spatio-temporal, or bivariate nearest-neighbour...

In GeoModels: Procedures for Gaussian and Non Gaussian Geostatistical (Large) Data Analysis

Spatial, spatio-temporal, or bivariate nearest-neighbour indices

Description

Builds directed nearest-neighbour candidate pairs for spatial, spatio-temporal, or bivariate data. Candidate pairs can optionally be thinned using independent Bernoulli sampling or an exact fixed-budget, stratum-wise design.

Usage

GeoNeighIndex(coordx=NULL, coordy=NULL, coordz=NULL, coordt=NULL,
 coordx_dyn=NULL, distance="Eucl", neighb=4,
 maxdist=NULL, maxtime=1, radius=1,
 bivariate=FALSE, p_neighb=1,
 thin_method="bernoulli", check.duplicates=FALSE)

Arguments

coordx	A numeric N \times 2 or N \times 3 coordinate matrix. Longitude/latitude coordinates can be supplied for spherical distances. It may be omitted when coordx_dyn is supplied.
coordy	Optional numeric vector giving a second spatial coordinate when coordinates are supplied separately.
coordz	Optional numeric vector giving a third spatial coordinate when coordinates are supplied separately.
coordt	A numeric vector giving the temporal coordinates. Optional argument, default is NULL; if NULL, a purely spatial random field is expected. Temporal coordinates may be irregularly spaced; temporal lags are computed from the supplied coordinate values.
coordx_dyn	A list of numeric coordinate matrices. For spatio-temporal data, the list must contain one coordinate matrix per element of coordt. For bivariate data with different spatial supports, it must contain the two variable-specific coordinate matrices. Optional argument, default is NULL.
distance	Character string specifying the spatial distance. Default is "Eucl". See GeoFit.
neighb	A positive integer giving the nearest-neighbour candidate size. In the bivariate case, a length-three positive integer vector can be supplied for within-variable 1, cross-variable, and within-variable 2 pairs.
maxdist	Optional non-negative maximum spatial distance. In the bivariate case, a length-three vector can be supplied for the three pair types.
maxtime	A non-negative numeric value giving the maximum temporal distance in the same units as coordt. Spatio-temporal candidate pairs satisfy the corresponding temporal-distance restriction; see Details.
radius	Numeric radius used for spherical distances. Default is 1.
bivariate	Logical; if FALSE (default), construct univariate spatial or spatio-temporal pairs. If TRUE, construct bivariate spatial pairs.
p_neighb	Numeric scalar in (0,1]. If 1, the candidate set is returned without thinning. For thin_method="bernoulli", it is the marginal inclusion probability in the constant-probability design and hence controls the retained size in expectation. For thin_method="FixedBudget", it defines the exact global retained-pair budget K=\mathrm{round}(p_{neighb} d), where d is the candidate pair count.
thin_method	Character string selecting the thinning design. Accepted values are "bernoulli" and "FixedBudget", case-insensitively. The legacy name "TargetBalanced" is accepted as a backward-compatible alias for "FixedBudget".
check.duplicates	Logical. If TRUE, perform a fast exact scan for duplicated observation locations at this user entry point. The default is FALSE, so no duplicate-location scan is imposed. Internal bootstrap, cross-validation, and refitting calls do not repeat the scan.

Details

The unthinned output is a directed candidate graph: rowidx identifies candidate targets and colidx their neighbours. For a purely spatial configuration with N locations and candidate size m, the regular case contains approximately Nm directed candidate pairs.

For chordal and geodesic distances, nearest-neighbour ordering is built in three-dimensional unit-sphere coordinates. Because chordal distance is monotone in great-circle distance, this gives the correct global nearest-neighbour order, including near the dateline and poles. Reported lags are then evaluated in the requested spherical metric and scaled by radius.

For spatio-temporal data, temporal coordinates are treated as numeric coordinates, not as equally spaced indices. Candidate temporal separations are computed as

|t_i-t_j|,

and maxtime is interpreted as a temporal-distance threshold in the same units as coordt. Thus irregularly spaced temporal coordinates are supported directly.

With thin_method="bernoulli" and p_neighb < 1, candidate pairs are retained independently. In the current constant-weight implementation the inclusion probability is p_neighb, so the retained count is random with expectation approximately p_{neighb}d.

With thin_method="FixedBudget" and p_neighb < 1, exactly K=\mathrm{round}(p_{neighb}d) candidate pairs are retained, subject only to truncation to the available candidate count. The budget is allocated across natural candidate strata using proportional quotas with randomized residual allocation, followed by sampling without replacement within each stratum. For purely spatial data, strata are the target-specific nearest-neighbour lists. For spatio-temporal data, target and temporal-lag descriptors define the strata; for bivariate data, the variable-pair descriptors are also included. The resulting global retained size is exact.

For thin_method="FixedBudget", the exact target is round(p d). Hence very small p_neighb values may legitimately return zero retained pairs. This is a valid graph-selection result; GeoFit rejects such a graph because a pairwise likelihood cannot be estimated without pair contributions. Exact duplicate observation locations are rejected before nearest-neighbor construction.

When p_neighb = 1, no thinning is applied, independently of thin_method.

Value

A list containing the pair indices and distances required by downstream GeoModels procedures. Depending on the setting, components include:

rowidx	Directed target indices.
colidx	Directed neighbour indices.
lags	Spatial distances for the retained pairs.
lagt	Temporal distances for spatio-temporal pairs.
first	First variable indicator for bivariate pairs.
second	Second variable indicator for bivariate pairs.
maxdist	Spatial-distance threshold, when stored for the selected case.
neighb	Nearest-neighbour candidate size, when stored for the selected case.

The function returns only the retained pair structure; it does not append summary fields such as candidate or retained counts. These can be obtained from the lengths of the returned index vectors.

Author(s)

Moreno Bevilacqua, [e-mail], https://sites.google.com/view/moreno-bevilacqua/home, Victor Morales Onate, [e-mail], https://sites.google.com/site/moralesonatevictor/, Christian Caamano-Carrillo, [e-mail], https://www.researchgate.net/profile/Christian-Caamano

Examples

require(GeoModels)
NN <- 400
coords <- cbind(runif(NN), runif(NN))

## Full directed 5-NN candidate graph.
sel <- GeoNeighIndex(coordx=coords, neighb=5)
length(sel$rowidx)

## Bernoulli thinning: retained size is random with expectation 20 percent
## of the candidate graph.
set.seed(1)
sel_ber <- GeoNeighIndex(coordx=coords, neighb=5,
 p_neighb=0.2, thin_method="bernoulli")
length(sel_ber$rowidx)

## Fixed-budget thinning: the global retained size is exact.
set.seed(1)
sel_fix <- GeoNeighIndex(coordx=coords, neighb=5,
 p_neighb=0.2, thin_method="FixedBudget")
length(sel_fix$rowidx)

## Irregular temporal coordinates: maxtime is a distance threshold.
times <- c(0, 0.25, 1.1, 2.8)
sel_st <- GeoNeighIndex(coordx=coords[1:30, ], coordt=times,
 neighb=3, maxtime=1)
head(sel_st$lagt)

GeoModels documentation built on Sept. 23, 2026, 5:07 p.m.