## Multiscale second-order neighbourhood analysis of a spatial phylogenetic or functional community pattern from fully mapped data

### Description

Computes distance-dependent estimates of Shen et al. (2014) phylogenetic or functional mark correlation functions 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 species equivalence (see Details).

### Usage

```kdfun(p, upto, by, dis, nsim=0, 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). `dis ` a `"dist"` object defining Euclidean distances between species. `nsim ` number of Monte Carlo simulations to estimate local confidence limits of the null hypothesis of a random allocation of species distances (species equivalence; see Details). By default `nsim = 0`, so that no confidence limits are computed. `alpha ` if `nsim>0`, significant level of the confidence limits. By default α = 0.01.

### Details

Function `kdfun` computes Shen et al. (2014) Kd and gd-functions. For a multivariate point pattern consisting of S species with intensity λp, such functions can be estimated from the bivariate Kpq-functions between each pair of different species p and q. Function `kdfun` is thus a simple wrapper of `k12fun` (P?Pelissier & Goreaud 2014):

Kd(r) = D * Kr(r) / HD * Ks(r) = D * sum(λ p * λ q * Kpq(r) * dpq) / HD * sum(λ p * λ q * Kpq(r)).
gd(r) = D * g(r) / HD * gs(r) = D * sum(λ p * λ q * gpq(r) * dpq) / HD * sum(λ p * λ q * gpq(r)).

where Ks(r) and gs(r) are distance-dependent versions of Simpson's diversity index, D (see `ksfun`), Kr(r) and gr(r) are distance-dependent versions of Rao's diversity coefficient (see `krfun`); dpq is the distance between species p and q defined by matrix `dis`, typically a taxonomic, phylogenetic or functional distance. The advantage here is that as the edge effects vanish between Kr(r) and Ks(r), implementation is fast for a sampling window of any shape. Kd(r) provides the expected phylogenetic or functional distance of two heterospecific individuals a distance less than r apart (Shen et al. 2014), while gd(r) provides the same within an annuli between two consecutive distances of r and r-by.

Theoretical values under the null hypothesis of 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, by randomizing the between-species distances, keeping the point locations and distribution of species labels unchanged. The theoretical expectations of gd(r) and Kd(r) are thus 1.

### Value

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

 `r ` a vector of regularly spaced out distances (`seq(by,upto,by)`). `gd ` a data frame containing values of the function gd(r). `kd ` a data frame containing values of the function Kd(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 null hypothesis of species equivalence. `sup ` (optional) if `nsim>0` a vector of the upper local confidence limits of a random distribution of the null hypothesis at a significant level α. `inf ` (optional) if `nsim>0` a vector of the lower local confidence limits of a random distribution of the null hypothesis at a significant level α. `pval ` (optional) if `nsim>0` a vector of local p-values of departure from the null hypothesis.

### Note

There are printing and plotting methods for `"fads"` objects.

### Author(s)

Raphael.Pelissier@ird.fr

### References

Shen, G., Wiegand, T., Mi, X. & He, F. (2014). Quantifying spatial phylogenetic structures of fully stem-mapped plant communities. Methods in Ecology and Evolution, 4, 1132-1141.

P?Pelissier, R. & Goreaud, F. 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.

`plot.fads`, `spp`, `ksfun`, `krfun`, `divc`.

### Examples

```  data(Paracou15)
P15<-Paracou15
## Not run: spatial point pattern in a rectangle sampling window of size 125 x 125
swmr <- spp(P15\$trees, win = c(175, 175, 250, 250), marks = P15\$species)
## Not run: testing the species equivalence hypothesis
kdswmr <- kdfun(swmr, dis = P15\$spdist, 50, 2, 100)
## Not run: running more simulations is slow
kdswmr <- kdfun(swmr, dis = P15\$spdist, 50, 2, 500)
plot(kdswmr)

## Not run: spatial point pattern in a circle with radius 50 centred on (125,125)
swmc <- spp(P15\$trees, win = c(125,125,50), marks = P15\$species)
kdswmc <- kdfun(swmc, dis = P15\$spdist, 50, 2, 100)
## Not run: running more simulations is slow
kdswmc <- kdfun(swmc, dis = P15\$spdist, 50, 2, 500)
plot(kdswmc)

## Not run: spatial point pattern in a complex sampling window
swrt <- spp(P15\$trees, win = c(125,125,250,250), tri = P15\$tri, marks = P15\$species)
kdswrt <- kdfun(swrt, dis = P15\$spdist, 50, 2, 100)
## Not run: running simulations is slow
kdswrt <- kdfun(swrt, dis = P15\$spdist, 50, 2, 500)
plot(kdswrt)
```