boyce {spatstat.explore}

Boyce Index

Description

Calculate the discrete or continuous Boyce index for a spatial point pattern dataset.

Usage

boyce(X, Z, ..., breaks = NULL, halfwidth = NULL)

Arguments

X

A spatial point pattern (object of class "ppp").

Z

Habitat suitability classes or habitat suitability index. Either a tessellation (object of class "tess") or a spatial covariate such as a pixel image (object of class "im"), a function(x,y) or one of the letters "a", "b" representing the cartesian coordinates.

...

Additional arguments passed to rhohat.ppp.

breaks

The breakpoint values defining discrete bands of values of the covariate Z for which the discrete Boyce index will be calculated. Either a numeric vector of breakpoints for Z, or a single integer specifying the number of evenly-spaced breakpoints. Incompatible with halfwidth.

halfwidth

The half-width h of the interval [z-h,z+h] which will be used to calculate the continuous Boyce index B(z) for each possible value z of the covariate Z.

Details

Given a spatial point pattern X and some kind of explanatory information Z, this function computes either the index originally defined by Boyce et al (2002) or the ‘continuous Boyce index’ defined by Hirzel et al (2006).

Boyce et al (2002) defined an index of habitat suitability in which the study region W is first divided into separate subregions C_1,\ldots,C_m based on appropriate scientific considerations. Then we count the number n_j of data points of X that fall in each subregion C_j, measure the area a_j of each subregion C_j, and calculate the index

B_j = \frac{n_j/n}{a_j/a}

where a is the total area and n is the total number of points in X.

Hirzel et al (2006) defined another version of this index which is based on a continuous spatial covariate. For each possible value z of the covariate Z, consider the region C(z) where the value of the covariate lies between z-h and z+h, where h is the chosen ‘halfwidth’. The ‘continuous Boyce index’ is

B(z) = \frac{n(z)/n}{a(z)/a}

where n(z) is the number of points of X falling in C(z), and a(z) is the area of C(z).

If Z is a tessellation (object of class "tess"), the algorithm calculates the original (‘discrete’) Boyce index (Boyce et al, 2002) for each tile of the tessellation. The result is another tessellation, identical to Z except that the mark values are the values of the discrete Boyce index.

If Z is a pixel image whose values are categorical (i.e. factor values), then Z is treated as a tessellation, with one tile for each level of the factor. The discrete Boyce index is then calculated. The result is a tessellation with marks that are the values of the discrete Boyce index.

Otherwise, if Z is a spatial covariate such as a pixel image, a function(x,y) or one of the characters "x" or "y", then exactly one of the arguments breaks or halfwidth must be given.

• if halfwidth is given, it should be a single positive number. The continuous Boyce index (Hirzel et al, 2006) is computed using the specified halfwidth h. The result is an object of class "fv" that can be plotted to show B(z) as a function of z.

• if breaks is given, it can be either a numeric vector of possible values of Z defining the breakpoints for the bands of values of Z, or a single integer specifying the number of evenly-spaced breakpoints that should be created. The discrete Boyce index (Boyce et al, 2002) is computed. The result is an object of class "fv" that can be plotted to show the discrete Boyce index as a function of z.

When Z is a spatial covariate (not factor-valued), the calculation is performed using rhohat.ppp (since the Boyce index is a special case of rhohat). Arguments ... passed to rhohat.ppp control the accuracy of the spatial discretisation and other parameters of the algorithm.

Value

A tessellation (object of class "tess") or a function value table (object of class "fv") as explained above.

Author(s)

Adrian Baddeley [e-mail]

References

Boyce, M.S., Vernier, P.R., Nielsen, S.E. and Schmiegelow, F.K.A. (2002) Evaluating resource selection functions. Ecological modelling 157, 281–300.

Hirzel, A.H., Le Lay, V., Helfer, V., Randin, C. and Guisan, A. (2006) Evaluating the ability of habitat suitability models to predict species presences. Ecological Modelling 199, 142–152.

See Also

rhohat

Examples

  online <- interactive()
  ## a simple tessellation
  V <- quadrats(Window(bei), 4, 3)
  if(online) plot(V)

  ## discrete Boyce index for a simple tessellation
  A <- boyce(bei, V)

  if(online) {
   plot(A, do.col=TRUE)
   marks(A)
   tilenames(A)
  }

  ## spatial covariate: terrain elevation
  Z <- bei.extra$elev

  ## continuous Boyce index for terrain elevation
  BC <- boyce(bei, Z, halfwidth=10)

  if(online) plot(BC)

  ## discrete Boyce index for terrain elevation steps of height 5 metres
  bk <- c(seq(min(Z), max(Z), by=5), Inf)
  BD <- boyce(bei, Z, breaks=bk)

  if(online) plot(BD)