gblg: Pair-correlation based estimates of gliding box lacunarity

In lacunaritycovariance: Gliding Box Lacunarity and Other Metrics for 2D Random Closed Sets

Pair-correlation based estimates of gliding box lacunarity

Description

Estimates the gliding box lacunarity (GBL) of a stationary RACS by estimating pair-correlation from a binary map (Hingee et al., 2017). It can also calculate the GBL of a RACS from a provided pair-correlation function.

Usage

gblg(boxes, paircorr = NULL, xiim = NULL, integrationMethod = "cubature")

Arguments

boxes	Either a list of side lengths for square boxes or a list of owin objects of any shape.
paircorr	A im object containing the pair-correlation function
xiim	An observation of a stationary RACS as an im object. xiim must have values of either 1, 0 or NA; 1 denotes inside the RACS, 0 denotes outside, and NA denotes unobserved.
integrationMethod	The integration method used by innerprod.im().

Details

If we denote the estimated pair-correlation by \hat{g}(v) then the estimate of GBL is

\frac{1}{|B|^2}\int \gamma_B(v)\hat{g}(v)dv,

where B is each of the sets (often called a box) specified by boxes, \gamma_B is the set covariance of B, |B| is the area of B, p is the coverage probability of a stationary RACS. This can be used to compute the GBL from model parameters by passing gblc the covariance and coverage probability of the model.

If the xiim argument to gblg is used then pair correlation is estimated from xiim using paircorr and the pickaH estimator.

The set covariance of B is computed empirically using spatstat's setcov function, which converts B into a binary pixel mask using as.mask defaults. Computation speed can be increased by setting a small default number of pixels, npixel, in spatstat's global options (accessed through spatstat.options), however fewer pixels also decreases the accuracy of the GBL computation.

The default integration method for this function uses cubature::cubintegrate() from the cubature package. The 'harmonisesum' integration method is known to produce numerical artefacts (Section 6.2 of (Hingee et al., 2019))

Value

If boxes is a list of numerical values then GBL is estimated for square boxes with side length given by boxes. The returned object is then an fv object containing estimates of GBL. If boxes is a list of owin objects then gblg returns a dataframe of with columns corresponding to estimates of GBL.

Note that if any values in the paircorr object needed for gblg are NA or NaN then gblg will return NA or NaN, respectively.

References

Hingee K, Baddeley A, Caccetta P, Nair G (2019). Computation of lacunarity from covariance of spatial binary maps. Journal of Agricultural, Biological and Environmental Statistics, 24, 264-288. DOI: 10.1007/s13253-019-00351-9.

Examples

xi <- as.im(heather$coarse, na.replace = 0, eps = 4 * heather$coarse$xstep)
sidelengths <- seq(0.3, 14, by = 3)

# reduce resolution in setcov() for faster (less accurate) computation 
oldopt <- spatstat.options()
spatstat.options("npixel" = 2^4)

# compute GBL estimates from binary map
xiim <- as.im(xi, na.replace = 0)
gblgest <- gblg(sidelengths, xiim = xiim)

spatstat.options(oldopt)

lacunaritycovariance documentation built on Aug. 29, 2025, 5:13 p.m.