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.