envelope4idar: Compute Simulation Envelopes for IDAR(r) Functions

Description

Compute simulation envelopes for IDAR(r) functions.

Usage

envelope4idar(mippp, mippp.sp.sim, mippp.sp, mimark=NULL,
    namesmark=NULL, r, idar="isar", buffer="adapt", bfw=NULL,
    nsim=NULL, nrank=1, tree = NULL, traits = NULL, 
    cross.idar=FALSE, savefuns=TRUE, correct.phylo="exclude",
    correct.trait.na=FALSE, correct.trait="mean" )
idar2(mippp.sp, mippp, mimark, idar="isar", buffer,bfw, r, 
    cross.idar=FALSE,  tree = NULL, traits = NULL)
    raoDmod(comm, phy = NULL)

Value

An object of class "fv", see fv.object, and envelope,which can be plotted directly using plot.fv. Essentially a data frame containing columns

r: the vector of values of the argument r at which the idar(r) function has been estimated
obs: values of the summary function for the data point pattern
lo: lower envelope of simulations
hi: upper envelope of simulations
nmean: estimated theoretical value of the summary function under the considered null model, computed by averaging simulated values

Arguments

mippp: A multitype (a.k.a. multivariate) marked point pattern. An object with the ppp format of spatstat.
mippp.sp: Univariate point pattern of the focal species. An object with the ppp format of spatstat.
mippp.sp.sim: A list with simulations of the focal species point pattern created with simulador2
mimark: Character. Name of the focal species in the multitype mippp.
namesmark: Character. If the marks in mippp are within a data.frame, the name of the column with the species names
r: Vector of distances to compute IDAR(r) functions
idar: Character. The name of the idar fucntion to be computed. Either "isar", "ipsvar", "ipsrar", "ipsear", "ipscar", "icwmar", "icwmar.O", "iraodar"or "imntdar"
buffer: Character or numeric. Either "adapt" (i.e., compute an adaptive buffer), or a number indicating de width of a fixed buffer area around the plot border
bfw: An owin object indicating the limits of the buffer area.
nsim: The number of simulations.
nrank: Integer. Rank of the envelope value amongst the nsim simulated values. A rank of 1 means that the minimum and maximum simulated values will be used.
tree: A phylogenetic tree in phylo format (ape) or a phylogenetic covariance matrix
traits: A data.frame of traits, or a distance matrix among species (in dist or matrix format) computed on a data.frame of traits.
cross.idar: Logical. If TRUE, the focal pattern be excluded form the community being measured.
savefuns: Logical flag indicating whether to save all the simulated function values.
correct.phylo: Character. Either "mean" meaning "include missing species in the tree with a constant mean phylogenetic covariance" or "exclude", meaning "exclude missing species in the tree from the analysis"
correct.trait.na: Logical flag indicating whether NA values in the matrix of traits should be "corrected": NA values will be assigned the mean trait value.
correct.trait: Character. Either "mean" or "exclude". Species missing in the data.frame of traits will be assigned mean trait values or will be excluded from the analysis, respectively.
comm: A data.frame with community data
phy: a phylogenetic tree in phylo format (ape) or more probably, a distance matrix.

Warning

The transcription of species names in the multivariate mippp, in the row names of the data.frame of traits (or in the names or dimnames of the distance matrices) should be identical. The same applies to the tiplabels of the phylogenetic tree.

Author

Marcelino de la Cruz marcelino.delacruz@urjc.es

Details

In 2007, Wiegand et al. developed the concept of Individual Species-Area Relationship. Basically, this consist in computing species accumulation curves by samping areas with varying radius \(r\) around the individual trees of a focal species. Here we provide a version of ISAR(r) (idar="isar"), but we also extend this concept to other diversity-area relationships and provide functions to compute individual phylogenetic diversity-area and individual functional diversity-area relationships. The individual phylogenetic functions are based in Helmus et al. (2007) measures, i.e., phylogenetic species variability (idar="ipsvar"), phylogenetic species richness (idar="ipsrar"), phylogenetic species evenness (idar="ipsear"), and phylogenetic species clustering (idar="ipscar"). Also, an individual version of the mean nearest taxon distance of Webb et al. (2002) (idar="imntd"). The individual functional-diversity function (idar="ifdar") is based in the functional dispersion measure (FDis) of Laliberté and Legendre (2010). Other available functions are based in a weighted community mean of traits (idar="icwmar"), on a verison of Rao quadratic entropy (idar="iraodar"), and on the same functions but computed in "rings" defined by the neighbour r values (idar="icwmar.O" and idar="iraodar.O"), which would eliminate the "accumulative" or "memory" effect on ICWMAR(r) and IRAODAR(r).

Although recent litterature (e.g., Wiegand and Moloney 2014) suggest that buffer correction is not necessary for this type of statistics, and by default all functions are estimated without buffer (e.g., buffer=0), several edge correction coould be employed. For example, an adaptative buffer correction could be used (buffer="adapt"), i.e., for each radius \(r\), only individuals of the focal species that are placed at a distance \(>=r\) from the border of the plot are considered in the computation of the different meassures. It is also possible to set a fixed buffer width (e.g., buffer=30), which will accelerate te computations but will discard many useful trees. It is also possible to provide also a fixed window (in the argument bfw) to indicate the limits of the buffer area. This could be useful to computing the IDAR(r) functions in different subsets of the original plot (e.g., in different "habitats").

In general, computing envelopes with envelope4idar is a little faster than using envelope and the individual functions (e.g., ipsvar, ifdar, etc). In addition, envelope4idar has the possibility of computing "crossed" individual functions, i.e., using a focal species that is not part of the community whose diversities are being measured. This allows evaluating the diversity of e.g., young trees around older trees, etc. This is accomplished by seting the argument cross.idar=TRUE.

While envelope4idar manages data and results, idar2 actually computes the individual functions (both observed and simulated) . In general, idar2 would not be called directly by the user.

raoDmod is a modification of the function raoD of picante to accept distance matrices instead of phylogenetoc trees. It would not be called directly by the user.

References

Helmus M.R., Bland T.J., Williams C.K. and Ives A.R. (2007) Phylogenetic measures of biodiversity. American Naturalist, 169, E68-E83.

Laliberté, E. and Legendre, P. (2010) A distance-based framework for measuring functional diversity from multiple traits. Ecology 91, 299-305.

Wiegand,T., Gunatilleke, C.V.S., Gunatilleke, I.A.U.N. and Huth, A. (2007) How individual species structure diversity in tropical forests. PNAS 104, 19029-19033.

Webb, C., Ackerly, D., McPeek, M., and Donoghue M. 2002. Phylogenies and community ecology. Annual Review of Ecology and Systematics 33:475-505

Examples

Run this code




# compute envelope for isar around sp_44
data(SF)
data(SFtraits)
data(SFphylotree)

  
# 1) Create a list with simulations of the focal species point pattern  with simulador2()
#     or by hand. # Beware that each simulated ppp should be marked (with the mark
#      of the focal species)

#  Example for simulations of an inomogenous PP
# Adjust an IPP:
    
    sp_44.ipp<- density.ppp(unmark(SF[SF$marks$species=="sp_44"]))
   
# simulate 19 realizations of the adjusted IPP
# (BEWARE: in real tests you should use 199 or higher)
    sp_44.ipp.sim <- vector(mode="list", le=19)
    sp_44.ipp.sim <- lapply(sp_44.ipp.sim, function(x) x=rpoispp(sp_44.ipp))
   # mark each simulated pattern
    sp_44.ipp.sim.m <- lapply(sp_44.ipp.sim, function(x) 
                                       {marks(x) = factor(rep("sp_44", x$n)); return(x)})

# 2) compute.envelopes
     # ISAR
  isar.sp_44.ipp.env<- envelope4idar(mippp=SF, mippp.sp.sim= sp_44.ipp.sim.m,
                mimark="sp_44", namesmark="species",r=1:30, buffer=0) 
if (FALSE) {
     # IFDAR
 ifdar.sp_44.ipp.env<- envelope4idar(mippp=SF, mippp.sp.sim= sp_44.ipp.sim.m,
                mimark="sp_44",  namesmark="species", r=1:30, idar="ifdar", buffer=0, 
		 traits=SFtraits, correct.trait.na=TRUE)

    #IPSVAR
   ipsvar.sp_44.ipp.env<- envelope4idar(mippp=SF, mippp.sp.sim= sp_44.ipp.sim.m,
                 mimark="sp_44", namesmark="species", r=1:30, idar="ipsvar", buffer=0, 
		  tree=SFphylotree)

####################################
# Computing CROSS_IDAR
#--------------------------------------------------

# You need a focal pattern that its not part of the multivariate pattern which is "measured"
# to estimate diversity.
# For example, let's measure diversity of small trees  around large trees of the focal species.

# First, obtain the pattern of large and small trees
# the pattern of small trees will be the "measured" one, i.e., the argument "mippp"

SFlarge<- SF[SF$marks$dbh>=10]
SFsmall <- SF[SF$marks$dbh<10]

# pattern of the focal species (this will be the argument "mippp.sp")
sp_44.large<- SFlarge[SFlarge$marks$species=="sp_44"]

# list of simulated patterns of the focal species (e.g., from an IPP)
sp_44.large.ipp<- density.ppp(sp_44.large)
sp_44.large.ipp.sim <- vector(mode="list", le=99)
sp_44.large.ipp.sim <- lapply(sp_44.large.ipp.sim, function(x) x=rpoispp(sp_44.large.ipp))

# COMPUTE envelopes for cross-ISAR(r)
 isar.sp_44.large.cross.ipp.env<- envelope4idar(mippp=SFsmall, r=1:30, buffer=0,
			mippp.sp.sim= sp_44.large.ipp.sim, mippp.sp=sp_44.large,
                        namesmark="species", cross.idar =TRUE) 

# COMPUTE envelopes for cross-IFDAR(r)
ifdar.sp_44.large.cross.ipp.env<- envelope4idar(mippp=SFsmall, r=1:30, idar="ifdar", 
                       buffer=0, mippp.sp.sim= sp_44.large.ipp.sim,  mippp.sp=sp_44.large,
                       namesmark="species", traits=SFtraits, correct.trait.na=TRUE,
                       cross.idar =TRUE) 

# COMPUTE envelopes for cross-IPSVAR(r)
ipsvar.sp_44.large.cross.ipp.env<- envelope4idar(mippp=SFsmall, r=1:30, idar="ipsvar", 
                      buffer=0, mippp.sp.sim= sp_44.large.ipp.sim,  mippp.sp=sp_44.large,
                      namesmark="species",  tree=SFphylotree, cross.idar =TRUE) 


####################################
# Comparing the performance of envelope() and envelope4idar()
# 
#--------------------------------------------------
require(ecespa) # for the ipc.estK() function
data(SF)
SFsp<- unmark(SF)
marks(SFsp)<- SF$marks$species
sp_44.ppp<-unmark(SF[SF$marks$species=="sp_44"])
sp_44.pc<- ipc.estK(sp_44.ppp)


# use multifocalsimulator() to use the same simulations with both functions.
sp_44.pc.sim.mf0<-multifocalsimulator(pp=SFsp, mimark="sp_44",
                           simulate=expression(rIPCP(sp_44.pc)), nsim=99, nmin=sp_44.ppp$n)

# envelopes with function envelope()
gc()
t0<- Sys.time()
  ifdar.sp_44.pc.env.e2<- envelope(SFsp, fun=ifdar, mimark="sp_44", traits=SFtraits,
                            correct.trait.na=TRUE, nsim=99, simulate=sp_44.pc.sim.mf0, r=1:30,
                            savefuns=TRUE, buffer=0)
Sys.time()-t0

# envelopes with function envelope4idar()

# Here you should input simulated patterns only for the focal species so, first,
# extract it fom the list of simulated multivariate ppp

sp_44.pc.sim.mf00<- lapply(sp_44.pc.sim.mf0, function(x) {x=x[x$marks=="sp_44"];return(x)})

gc()
t0<- Sys.time()
ifdar.sp_44.pc.env2<- envelope4idar(mippp=SF, mippp.sp.sim= sp_44.pc.sim.mf00, mimark="sp_44",
				namesmark="species", r=1:30, idar="ifdar", buffer=0, 
                                nsim=99, traits=SFtraits, correct.trait.na=TRUE)
Sys.time()-t0


}

Run the code above in your browser using DataLab