lacunaritycovariance (version 1.1-7)

gblc: Gliding box lacunarity estimator using plug-in moment covariance estimator

Description

Can be used to estimate the gliding box lacunarity (GBL) of a stationary RACS from a binary map using the plug-in moment covariance covariance estimator (Hingee et al., 2019). It can also calculate the GBL of a RACS from a given covariance function and coverage probability.

Usage

gblc(
  boxes,
  covariance = NULL,
  p = NULL,
  xiim = NULL,
  integrationMethod = "cubature"
)

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, box mass variance and box mass mean. If boxes is a list of owin objects then gblc returns a dataframe with columns corresponding to estimates of GBL, box mass variance and box mass mean.

Note if NA or NaN values in the covariance object are used then gblc will return NA or NaN.

Arguments

boxes

Either a list of side lengths for square boxes or a list of owin objects of any shape.

covariance

A im object containing the covariance function

p

The coverage probability. Typically estimated by the fraction of the observation window covered by the set of interest.

xiim

A binary coverage map 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

Computes a numerical approximation of $$\int \gamma_B(v) C(v) dv / (p^2 |B|^2).$$ 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, and \(C(v)\) is the covariance 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.

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 method of integration for the above integral is cubature::cubintegrate() from the cubature package. The 'harmonisesum' method is known to produce numerical artefacts (Section 6.2 of (Hingee et al., 2019))

If a binary map is supplied then \(p\) and \(C(v)\) are estimated using the usual coverage probability estimator and the plug-in moment covariance estimator, respectively (see coverageprob and plugincvc).

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 <- heather$coarse

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

covar <- plugincvc(xi, Frame(xi))
p <- area(xi) / area(Frame(xi))
sidelengths <- seq(0.3, 14, by = 1)

# compute GBL estimate for square boxes from estimated covariance
gblest <- gblc(sidelengths, covar, p)

# compute GBL estimate for boxes that are discs 
discboxes <- lapply(sidelengths / 2, disc)
discgbls <- gblc(discboxes, covar, p)

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

spatstat.options(oldopt)