idar (version 1.5)

isar: Individual Diversity Area Relationships

Description

Estimate different Individual Diversity-Area Relationships from a multivariate point pattern.

Usage

isar(mippp, mippp.sp=NULL, mimark=NULL,  namesmark=NULL, r=NULL,
   buffer=0, bfw=NULL)
  ipscar(mippp, mippp.sp=NULL, mimark=NULL,  namesmark=NULL,
   tree=NULL, r=NULL, buffer=0, bfw=NULL, correct.phylo="mean")
  ipsear(mippp, mippp.sp=NULL, mimark=NULL,  namesmark=NULL,
   tree=NULL, r=NULL, buffer=0, bfw=NULL, correct.phylo="mean")
  ipsvar(mippp, mippp.sp=NULL, mimark=NULL,  namesmark=NULL,
   tree=NULL, r=NULL, buffer=0, bfw=NULL, correct.phylo="mean")
  ipsrar(mippp, mippp.sp=NULL, mimark=NULL,  namesmark=NULL,
   tree=NULL, r=NULL, buffer=0, bfw=NULL, correct.phylo="mean")
  ifdar(mippp, mippp.sp=NULL, mimark=NULL,  namesmark=NULL,
   traits=NULL, r=NULL, buffer=0, bfw=NULL, correct.trait.na=FALSE,
     correct.trait="mean")

Value

An object of class "fv", see fv.object, which can be plotted directly using plot.fv.

Essentially a data frame containing a column named r with the vector of values of the argument r at which the IDAR(r) function has been estimated and aonther column, named "isar", "ipsvar", "ipsrar", "ipsear", "ipscar" or "ifdar", according to the selected idar argment. This column contains an estimate of the selected IDAR(R) function.

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.

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

buffer

One of "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.

r

Vector of distances to compute IDAR(r) functions

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.

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.

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.

Simulation envelopes

To compute simulation envelopes for the IDAR(r) functions, use envelope. See the examples in this help page and in ipsim to know how to compute simulation envelopes from appropriate null models.

To compute envelopes for "crossed" IDAR(r) functions or to accelerate the computation of "single" IDAR(r) functions, use envelope4idar.

Author

Marcelino de la Cruz

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 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 (ipsvar), phylogenetic species richness (ipsrar), phylogenetic species evenness (ipsear), and phylogenetic species clustering (ipscar). The individual functional-diversity function (ifdar) is based in the functional dispersion measure (FDis) of Laliberté and Legendre (2010).

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 functionsare 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").

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.

See Also

psd for a description of the phylogenetic measures of Helmus et al. (2007).

fdisp for a description of the functional dispersion measure (FDis) of Laliberté and Legendre (2010).

Examples

# ISAR
   # Point pattern with a data.frame of marks
   data(SF)
   isar.sp_44 <- isar(mippp = SF, mimark="sp_44", namesmark="species", r=1:40) 
   plot(isar.sp_44)
 
   # Point pattern with just a vector of marks
    data(lansing)
    isar.blackoak <- isar(mippp = lansing, mimark="blackoak",  r=seq(0.01, 0.25, le=100))
    plot(isar.blackoak)

   # Examples of the use of different buffers
     # No  buffer at all (by deffault, buffer = 0)
     isar.sp_44.0 <- isar(mippp = SF, mimark="sp_44", namesmark="species", r=1:18)    

     # Adaptive buffer (for each r, use only points within a r distance form the border)
     isar.sp_44.a <- isar(mippp = SF, mimark="sp_44", namesmark="species", r=1:18,
                                buffer="adapt") 

     # Predefined window, for example with a buffer of 7 m within plot limits
     mibfw<- erosion(SF$win, r=7)
      isar.sp_44.w <- isar(mippp = SF, mimark="sp_44", namesmark="species", r=1:18, bfw=mibfw) 


   ######################
   ### Phylogenetic functions ###
   ######################
   
data(SFphylotree)

# IPSCAR
    ipscar.sp_44 <- ipscar(mippp = SF, mimark="sp_44", namesmark="species", r=1:40,
                                     tree=SFphylotree)
    plot(ipscar.sp_44)
 
# IPSEAR
    ipsear.sp_44 <- ipsear(mippp = SF, mimark="sp_44", namesmark="species", r=1:40,
                                  tree=SFphylotree)
    plot(ipsear.sp_44)

# IPSVAR
    ipsvar.sp_44 <- ipsvar(mippp = SF, mimark="sp_44", namesmark="species", r=1:40,
                                   tree=SFphylotree)
    plot(ipsvar.sp_44)

# IPSRAR
    ipsrar.sp_44 <- ipsrar(mippp = SF, mimark="sp_44", namesmark="species", r=1:40,
                                  tree=SFphylotree)
    plot(ipsrar.sp_44)
 
  #####################
  ###  Functional functions ###
  #####################
 
data(SFtraits)

# IFDAR
   # this will cause an error becuse some species have NA's in the vector of trait values
if (FALSE) {
  # ifdar.sp_44 <- ifdar(mippp = SF, mimark="sp_44", namesmark="species", traits=SFtraits,
  #                           r=1:40, correct.trait="exclude")
}
   # "correct" NA's in trait values  by assigning tospecies without traits the average of the trait 
   # for  all the other species
   ifdar.sp_44 <- ifdar(mippp = SF, mimark="sp_44", namesmark="species",  traits=SFtraits,
			      r=1:40, correct.trait.na=TRUE)

    #"correct"  the existence of NA's in trait values  by excluding species without traits from the
    # analysis
    ifdar.sp_44 <- ifdar(mippp = SF, mimark="sp_44", namesmark="species", traits=SFtraits,
                               r=1:40, correct.trait.na=TRUE,correct.trait="exclude")

     plot(ifdar.sp_44)

# For examples of envelopes for these functions  see the help page of ipsim() or envelope4idar()