ads (version 1.5-5)

krfun: Multiscale second-order neighbourhood analysis of a multivariate spatial point pattern using Rao quadratic entropy

Description

Computes distance-dependent estimates of Rao's quadratic entropy from a multivariate spatial point pattern in a simple (rectangular or circular) or complex sampling window. Computes optionally local confidence limits of the functions under the null hypothesis of either a random labelling or a species equivalence (see Details).

Usage

krfun(p, upto, by, nsim=0, dis = NULL, H0 = c("rl", "se"), alpha = 0.01)

Arguments

p

a "spp" object defining a spatial point pattern in a given sampling window (see spp).

upto

maximum radius of the sample circles (see Details).

by

interval length between successive sample circles radii (see Details).

nsim

number of Monte Carlo simulations to estimate local confidence limits of the null hypothesis of a random allocation of species labels (see Details). By default nsim = 0, so that no confidence limits are computed.

dis

(optional) a "dist" object defining Euclidean distances between species. By default \(dis = NULL\) so that species are considered equidistant.

H0

one of c("rl","se") to select either the null hypothesis of random labelling (H0 = "rl") or species equivalence (H0 = "se") (see Details). By default, the null hypothesis is random labelling.

alpha

if nsim>0, significant level of the confidence limits. By default \(\alpha = 0.01\).

Value

A list of class "fads" with essentially the following components:

r

a vector of regularly spaced out distances (seq(by,upto,by)).

gr

a data frame containing values of the function \(gr(r)\).

kr

a data frame containing values of the function \(Kr(r)\).

Each component except r is a data frame with the following variables:

obs

a vector of estimated values for the observed point pattern.

theo

a vector of theoretical values expected under the selected null hypothesis.

sup

(optional) if nsim>0 a vector of the upper local confidence limits of a random distribution of the selected null hypothesis at a significant level \(\alpha\).

inf

(optional) if nsim>0 a vector of the lower local confidence limits of a random distribution of the selected null hypothesis at a significant level \(\alpha\).

pval

(optional) if nsim>0 a vector of local p-values of departure from the selected null hypothesis.

Details

Function krfun computes distance-dependent functions of Rao (1982) quadratic entropy (see divc in package ade4). For a multivariate point pattern consisting of \(S\) species with intensity \(\lambda\)p, such functions can be estimated from the bivariate \(Kpq\)-functions between each pair of different species \(p\) and \(q\). Function krfun is thus a simple wrapper function of k12fun and kfun, standardized by Rao diversity coefficient (Pelissier & Goreaud 2014):

\(Kr(r) = sum(\lambda p * \lambda q * Kpq(r)*dpq) / (\lambda * \lambda * K(r) * HD)\). \(gr(r) = sum(\lambda p * \lambda q * gpq(r)*dpq) / (\lambda * \lambda * g(r) * HD)\).

where \(dpq\) is the distance between species \(p\) and \(q\) defined by matrix dis, typically a taxonomic, phylogenetic or functional distance, and \(HD=sum(Np*Nq*dpq/(N(N - 1)))\) is the unbiased version of Rao diversity coefficient (see Shimatani 2001). When dis = NULL, species are considered each other equidistant and krfun returns the same results than ksfun.

The program introduces an edge effect correction term according to the method proposed by Ripley (1977) and extended to circular and complex sampling windows by Goreaud & Pelissier (1999).

Theoretical values under the null hypothesis of either random labelling or species equivalence as well as local Monte Carlo confidence limits and p-values of departure from the null hypothesis (Besag & Diggle 1977) are estimated at each distance \(r\).

The random labelling hypothesis (H0 = "rl") is tested by reallocating species labels at random among all points of the pattern, keeping the point locations unchanged, so that expectations of \(gr(r)\) and \(Kr(r)\) are 1 for all \(r\). The species equivalence hypothesis (H0 = "se") is tested by randomizing the between-species distances, keeping the point locations and distribution of species labels unchanged. The theoretical expectations of \(gr(r)\) and \(Kr(r)\) are thus \(gs(r)\) and \(Ks(r)\), respectively (see ksfun).

References

Rao, C.R. 1982. Diversity and dissimilarity coefficient: a unified approach. Theoretical Population Biology, 21:24-43.

Shimatani, K. 2001. On the measurement of species diversity incorporating species differences. Oikos, 93, 135-147.

Goreaud F. & Pelissier R. 1999. On explicit formulas of edge effect correction for Ripley's K-function. Journal of Vegetation Science, 10:433-438.

Ripley B.D. 1977. Modelling spatial patterns. Journal of the Royal Statistical Society B, 39:172-192.

Pelissier, R. & Goreaud, F. 2014. ads package for R: A fast unbiased implementation of the k-function family for studying spatial point patterns in irregular-shaped sampling windows. Journal of Statistical Software, in press.

See Also

plot.fads, spp, ksfun, kdfun, divc.

Examples

# NOT RUN {
  data(Paracou15)
  P15<-Paracou15
  
# }
# NOT RUN {
spatial point pattern in a rectangle sampling window of size 125 x 125
# }
# NOT RUN {
  swmr <- spp(P15$trees, win = c(175, 175, 250, 250), marks = P15$species)
  
# }
# NOT RUN {
testing the random labeling hypothesis
# }
# NOT RUN {
  krwmr.rl <- krfun(swmr, dis = P15$spdist, H0 = "rl", 25, 2, 50)
  
# }
# NOT RUN {
running more simulations is slow
# }
# NOT RUN {
  
# }
# NOT RUN {
krwmr.rl <- krfun(swmr, dis = P15$spdist, H0 = "rl", 25, 2, 500)
# }
# NOT RUN {
  plot(krwmr.rl)
  
# }
# NOT RUN {
testing the species equivalence hypothesis
# }
# NOT RUN {
  krwmr.se <- krfun(swmr, dis = P15$spdist, H0 = "se", 25, 2, 50)
  
# }
# NOT RUN {
running more simulations is slow
# }
# NOT RUN {
  
# }
# NOT RUN {
krwmr.se <- krfun(swmr, dis = P15$spdist, H0 = "se", 25, 2, 500)
# }
# NOT RUN {
  plot(krwmr.se)

  
# }
# NOT RUN {
spatial point pattern in a circle with radius 50 centred on (125,125)
# }
# NOT RUN {
  swmc <- spp(P15$trees, win = c(125,125,50), marks = P15$species)
  krwmc <- krfun(swmc, dis = P15$spdist, H0 = "rl", 25, 2, 100)
  
# }
# NOT RUN {
running more simulations is slow
# }
# NOT RUN {
  
# }
# NOT RUN {
krwmc <- krfun(swmc, dis = P15$spdist, H0 = "rl", 25, 2, 500)
# }
# NOT RUN {
  plot(krwmc)
  
  
# }
# NOT RUN {
spatial point pattern in a complex sampling window
# }
# NOT RUN {
  swrt <- spp(P15$trees, win = c(125,125,250,250), tri = P15$tri, marks = P15$species)
  krwrt <- krfun(swrt, dis = P15$spdist, H0 = "rl", 25, 2)
  
# }
# NOT RUN {
running simulations is slow
# }
# NOT RUN {
  
# }
# NOT RUN {
krwrt <- krfun(swrt, dis = P15$spdist, H0 = "rl", 25, 2, 500)
# }
# NOT RUN {
  plot(krwrt)
# }