calculate.theta: Calculates species habitat specialization using co-occurrence...

In zdealveindy/genspe: Co-occurrence based measure of species habitat specialization

Description

Calculates species habitat specialization using co-occurrence based theta metric.

Usage

calculate.theta(input.matrix, species.data = NULL, psample = 5, reps = 10,
  method = "multiplicative", beta.div.method = "hellinger",
  beta.div.sqrt.D = FALSE, beta.div.samp = TRUE, beals.file = NULL,
  pa.transform = FALSE, force.subsample = FALSE, parallel = FALSE,
  no.cores = 2, remove.out = F, verbal = F, juicer = F, tcltk = F)

calculate.theta.0(temp.matrix, sci.name, sp, remove.out, psample, reps, method,
  beta.div.method, beta.div.sqrt.D, beta.div.samp, force.subsample, parallel,
  win.pb, verbal, juicer)

calculate.theta.tcltk(input.matrix, species.data = NULL, juicer = T)

beals.2(x, include = TRUE, verbal = FALSE)

Arguments

input.matrix	Community data (matrix or data.frame, samples x species). If data are not presence-absence, the matrix will be automatically transformed into presence-absence and warning will be printed.
species.data	Species data (matrix or data.frame). If suplied, it should have at least two columns - the first containing species name, the second containing layer.
psample	Minimal frequency of species. Habitat specialization will be calculated for species occurring in number of samples equal or higher than minimal frequency threshold. Default = 5.
reps	Number of random subsamples. Specifies how many times the fixed number of samples (specified by psample) will be randomly drawn from all samples containing target species. Default = 10.
method	Beta-diversity algorithm used to calculate theta measure. Currently available are 'additive', 'multiplicative', 'pairwise.jaccard', 'pairwise.sorensen', 'pairwise.simpson', 'multi.sorensen', 'multi.simpson', 'rao', 'beals' and 'beta.div'). See Details for available options.
beta.div.method	Argument for the function beta.div, if the method = 'beta.div'. See Details.
beta.div.sqrt.D	Argument for the function beta.div, if the method = 'beta.div'. See Details.
beta.div.samp	Argument for the function beta.div, if the method = 'beta.div'. See Details.
beals.file	Contains pre-calculated matrix of species co-occurrences. Can be used if method = 'beals' to speed up repeated calculation.
pa.transform	Logical; should the compositional data be transformed into presence-absence form? This choice applies only if method is "rao" or "beta.div", since the other methods must be calculated on presence-absence data only (for these methods the matrix is automatically transformed into p/a form).
force.subsample	Logical; should the subsampling be forced even for beta diversity metrics which are not influenced by sample size (c('pairwise.jaccard', 'pairwise.sorensen', 'pairwise.simpson', 'rao', 'beta.div'))? Default behaviour is force.subsample = FALSE, meaning that beta diversity metrics dependent on sample size (method = c('additive', 'multiplicative', 'beals', 'multi.sorensen', 'multi.simpson')) will subsample number of plots equal to psample, while method not dependent on sample size (method = c('pairwise.jaccard', 'pairwise.sorensen', 'pairwise.simpson', 'beta.div')) will be calculated using all plots containing target species. If force.subsample = TRUE, even methods not dependent on sample size will be calculated using subsampling.
parallel	Logical; should be the parallel calculation used?
no.cores	Number of cores (if parallel = TRUE). Note that in case of large datasets the calculation may be limited by RAM of the computer, and increasing number of cores may result in saturation of RAM and calculation collapse.
remove.out	Logical; should be the algorithm removing outliers (sensu Botta-Dukat 2012) applied?
verbal	Logical; if TRUE, tcltk progress bar will popup during the calculation.
juicer	Logical argument specific for launching the function from JUICE software; logical (default = F) - is the function launched from JUICE? If juicer = TRUE, function is expecting that species.data have JUICE-specific structure, which enables to import data back to JUICE.
tcltk	Logical argument specific for launching the function from JUICE sofware.
temp.matrix	Internal argument; matrix with species composition of plots containing target species.
sci.name	Internal argument; the name of the species for which the current calculation is done.
sp	Internal argument; the order of the species for which the current calculation is done.
win.pb	Internal argument.
x	Internal argument of beals.2 function; input compositional matrix.
include	Internal argument of beals.2 function; include argument from vegan::beals.

Details

Function calculate.theta calculates theta metric of species habitat specialization using range of proposed beta diversity measures; it uses internal functions calculate.theta.0 and beals.2 (modified from the library vegan) . Function calculate.theta.tcltk launches tcltk clickable interface, which enables to select methods and parameters used for calculation; this function is primarily used to be lounched externally, e.g. from JUICE program.

The function calculate.theta offers the following method argument to calculate beta diversity among samples:

• additive: This is the original algorithm published by Fridley et al. (2007), in which beta diversity among samples containing given species is calculated by additive beta diversity measure.

• multiplicative: Uses the multiplicative Whittaker's measure of beta diversity instead of the original additive measure, as suggested by Zeleny (2009).

• beals: Multiplicative beta on species pool. Algorithm suggested by Botta-Dukat (2012), calculating the beta diversity using species pool matrix instead of the original species data matrix. Species pool matrix is calculated using Beals smoothing method (invented by Ewald 2002). While the previous multiplicative beta diversity method gives unbiased results only in case of not-saturated communities, this method should give unbiased results also in case of saturated communities. See Zeleny (2009) and Botta-Dukat (2012) for detail discussion of this saturated/not-saturated communities issue.

• pairwise.jaccard, pairwise.sorensen, pairwise.simpson, multi.sorensen and multi.simpson: Mean pairwise Jaccard, Sorensen and Simpson dissimilarity, and multiple Sorensen and Simpson dissimilarity based on reccomendations of Manthey & Fridley (2009). Authors suggested that neither the original additive algorithm (introduced by Fridley et al. 2007), neither the modified version using the multiplicative beta diversity (Zeleny 2009) is the best solution, and introduced other alternatives, using pairwise or multiple site beta diversity algorithm. Mean pairwise Jaccard dissimilarity (or Sorensen and Simpson, respectively) is based on calculating mean of Jaccard (or Sorensen and Simpson, respectively) dissimilarities among all pairs of samples in each subset, while multiple Sorensen (or Simpson, respectively) is using multiple-site Sorensen (or Simpson, respectively) algorithm introduced by Baselga et al. (2007)

• rao: Rao index of dissimilarity; this option has been introduced and used by Boulangeat et al. (2012). Advantage of Rao index is a possibility to incorporate known relationships among species using the among-species distance matrix. If this is not supplied and Rao index is calculated using presence-absence data, it is equal to Gini-Simpson diversity index and results are similar to pairwise Jaccard index.

• beta.div: Calculating the beta diversity as the variation in community matrix, using the concept introduced by Legendre & De Caceres (2013) and function beta.div written by Pierre Legendre (see Appendix S4.r of Legendre & De Caceres 2013; the version used here is from Legendre's website http://adn.biol.umontreal.ca/~numericalecology/labo/fonctions_r/beta-diversity.zip; however, I keep using method = "percentagedifference" instead of "%difference" from the new version, since I had a problem with roxygenizing the R help files with % sign). Three additional arguments can be specified if method = "beta.div", namely beta.div.method, beta.div.sqrt.D and beta.div.samp (the original arguments in the function beta.div are method, sqrt.D and samp). beta.div.method is choosing one of 21 distance metrics (from c("euclidean", "manhattan", "modmeanchardiff", "profiles", "hellinger", "chord", "chisquare", "divergence", "canberra", "whittaker", "percentagedifference", "ruzicka", "wishart", "kulczynski", "ab.jaccard", "ab.sorensen","ab.ochiai","ab.simpson","jaccard","sorensen","ochiai")). Argument beta.div.sqrt.D (logical) decides whether square root of distance should be used for calculation (important for non-euclidean distances like Bray-Curtis, called "percentagedifference" in beta.div function). Argument beta.div.samp is logical; if beta.div.samp = TRUE, the abundance-based distances (c("ab.jaccard", "ab.sorensen", "ab.ochiai", "ab.simpson")) are computed for sample data. If beta.div.samp= FALSE, they are computed for true population data.

Value

The function calculate.theta returns data.frame, with species in rows and the following columns:

• sci.name: scientific name of the species;

• local.avgS: average local species richness (average number of species in plots containing target species);

• occur.freq: occurrence frequency: number of plots in which species occurs;

• meanco: mean number of co-occurring species in subset of selected plots;

• meanco.sd: sd of the number of co-occurring species in subset of selected plots;

• meanco.u, meanco.l: upper and lower confidence interval of the number of co-occuring species in subset of selected plots;

• theta: calculated theta value;

• theta.sd: standard deviation of calculated theta values for individual subsets (not available for metrics which are not calculated by subsampling).

Author(s)

David Zeleny ([e-mail]). Partly based on codes written by Jason Fridley (Fridley et al. 2007) and David Zeleny (Zeleny 2009), extended for other published algorithms and optimised for speed and applicability on large datasets. Function beals.2 is based on function beals from vegan, written by Miquel De Caceres and Jari Oksanen.

Examples

sc <- sample.comm (simul.comm (totS = 100), Np= 100)
niches <- sc$simul.comm$range
additive <- calculate.theta (sc$a.mat, method = 'add')
multi <- calculate.theta (sc$a.mat, method = 'multiplicative')
beals <- calculate.theta (sc$a.mat, method = 'beals')
bray <- calculate.theta (sc$a.mat, method = 'beta.div', beta.div.method = 'percentagedifference', beta.div.sqrt.D = TRUE)
# Visualize the relationship using function pairs with Spearmann's correlation in the boxes above diagonal (see Examples in ?pairs)
panel.cor <- function(x, y, digits = 2, prefix = "", cex.cor, ...)
{
  usr <- par("usr"); on.exit(par(usr))
  par(usr = c(0, 1, 0, 1))
  r <- abs(cor(x, y, method = 'spearman'))
  txt <- format(c(r, 0.123456789), digits = digits)[1]
  txt <- paste0(prefix, txt)
  if(missing(cex.cor)) cex.cor <- 0.8/strwidth(txt)
  text(0.5, 0.5, txt, cex = cex.cor * r)
}
pairs (cbind (niches = niches[names (niches) %in% additive$sci.name], additive = additive$theta, multi = multi$theta, beals = beals$theta, bray = bray$theta), upper.panel = panel.cor)

zdealveindy/genspe documentation built on May 4, 2019, 9:13 p.m.