calculate.theta: Co-occurrence based metric of species habitat specialization

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

Description

Set of functions for estimating species niche breadth based on compositional data using co-occurrence based theta metric introduced by Fridley et al. (2007).

Usage

calculate.theta(input.matrix, species.data = NULL, thresh = 5,
  psample = 5, reps = 10, method = "multiplicative", q = 0,
  rarefaction = TRUE, 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, out.metric = "sorensen", verbal = F,
  juicer = F, tcltk = F)

calculate.theta.0(temp.matrix, sci.name, sp, remove.out, out.metric, thresh,
  psample, reps, method, rarefaction, q, 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.
thresh	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.
psample	Size of one random subsample (number of samples) for methods based on subsampling (argument method = c('additive', 'multiplicative', 'multi.sorensen', 'multi.simpson', 'beals', 'rao')). This value should not be higher than mimal frequency of species (argument thresh). For default setting (method = 'multiplicative', rarefaction = TRUE this value number of samples on rarefaction curve on which all the beta diversity calculation is standardized (euqivalent to number of subsamples). 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. Partial match to 'additive', 'multiplicative', 'pairwise.jaccard', 'pairwise.sorensen', 'pairwise.simpson', 'multi.sorensen', 'multi.simpson', 'rao', 'beals' and 'beta.div'). See Details for available options.
q	Generalization of Whittaker's multiplicative beta diversity for abundance data (only if method = 'multiplicative').
rarefaction	Logical value, which applies for method = 'multiplicative' and q = 0: should the Whittaker's multiplicative beta be calculated by rarefaction (rarefaction = TRUE) or by subsampling (rarefaction = FALSE)? Default = TRUE.
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?
out.metric	Dissimilarity metric used to calculate outliers which should be removed (out.metric = c('sorensen', 'euclidean', 'binary.euclidean')). Default value is 'sorensen', which is compatible with Whittaker's multiplicative beta; if using other method, consider to change it into 'binary.euclidean' recommended by Botta-Dukat (2012).
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.

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.

References

Baselga A., Jimenez-Valverde A. & Niccolini G. (2007): A multiple-site similarity measure independent of richness. Biology Letters, 3: 642-645.

Baselga A., Orme D., Villeger S., Bortoli J. & Leprieur F. (2013): betapart: Partitioning beta diversity into turnover and nestedness components. R package version 1.3. http://CRAN.R-project.org/package=betapart

Botta-Dukat Z. (2012): Co-occurrence-based measure of species' habitat specialization: robust, unbiased estimation in saturated communities. Journal of Vegetation Science, 23: 201-207.

Boulangeat I., Lavergne S., Van Es J., Garraud L. & Thuiller W. (2012): Niche breadth, rarity and ecological characteristics within a regional flora spanning large environmental gradients. Journal of Biogeography, 39: 204-214.

De Bello F., Lavergne S., Meynard C.N., Leps J. & Thuiller W. (2010): The partitioning of diversity: showing Theseus the way out of the labyrinth. Journal of Vegetation Science, 21: 992-1000.

Fridley J.D., Vandermast D.B., Kuppinger D.M., Manthey M. & Peet R.K. (2007): Co-occurrence based assessment of habitat generalists and specialists: a new approach for the measurement of niche width. Journal of Ecology, 95: 707-722.

Jost L. (2007): Partitioning diversity into independent alpha and beta components. Ecology, 88: 2427-2439.

Legendre P. & De Caceres M. (2013): Beta diversity as the variance of community data: dissimilarity coefficients and partitioning. Ecology Letters, 16:951-963.

Manthey M. & Fridley J.D. (2009): Beta diversity metrics and the estimation of niche width via species co-occurrence data: reply to Zeleny. Journal of Ecology, 97: 18-22.

Munzbergova Z. & Herben T. (2004): Identification of suitable unoccupied habitats in metapopulation studies using co-occurrence of species. Oikos, 105: 408-414.

Zeleny D. (2009): Co-occurrence based assessment of species habitat specialization is affected by the size of species pool: reply to Fridley et al. (2007). Journal of Ecology, 97: 10-17.

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 = 'percentdiff', 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/theta documentation built on May 4, 2019, 9:13 p.m.