Package implementing the Guilds sampling formula for the Neutral Theory of Biodiversity

Description

The GUILDS package contains a number of sampling formula's being the Etienne Sampling Formula (Etienne 2005), the GUILDS sampling formula (Janzen et al. 2014) and the GUILDS sampling formula conditioned on guild Size (Janzen et al. 2015). Furthermore it contains functions to generate data given the guilds model, with or without conditioning on guild size. C++ Code to obtain Sterling numbers of the first kind was adopted from the Tetame program by Jabot et al. (2008).

Updates

Version 1.4 : Cleaner README and Vignettes
Version 1.4 : Extend support to M1 processors where sizeof(long double) < 16
Version 1.4 : Comply with _R_CHECK_LENGTH_0_LOGIC2_
Version 1.3 : GUILDS is now on GitHub: https://github.com/thijsjanzen/GUILDS
Version 1.3 : Wrote code tests to check code integrity, code coverage is >95%
Version 1.3 : Modified maximum likelihood functions to take into account theta_x = theta_y = theta / 2
Version 1.3 : Added a plotting function to plot Preston style plots
Version 1.2.1 : Updated the User manual
Version 1.2 : fixed memory leak issues by adding extra vector access checks
Version 1.2 : fixed memory leak issues by introducing vectors in KDA code
Version 1.2 : renamed logLik to avoid shadowing of the function logLik in the package stats
Version 1.1 : removed malloc header from KDA code

Author(s)

Thijs Janzen

Maintainer: Thijs Janzen <thijsjanzen@gmail.com>

References

Janzen, T., Haegeman B., Etienne, R.S. (2015) A sampling formula for communities with multiple dispersal syndromes. Journal of Theoretical Biology 374: 94-106

Etienne, R.S. (2005). A new sampling formula for neutral biodiversity. Ecology Letters, 8(3), 253-260.

Jabot, F., Etienne, R.S., & Chave, J. (2008). Reconciling neutral community models and environmental filtering: theory and an empirical test. Oikos 117: 1308-1320

Internal Guilds functions

Description

Internal Guilds functions

Details

These are not to be called by the user

Calculate the expected species abundance distribution of the standard neutral model, given theta, m and J

Description

This function calculates the expected species abundance distribution of the standard neutral model given theta, m and J, sensu equation 6 from Etienne and Alonso (2005).

Usage

expected.SAD(theta, m, J)

Arguments

Value

A vector containing the abundances binned into log2 bins (sensu Preston).

Author(s)

Thijs Janzen & Bart Haegeman

References

Etienne, R.S., & Alonso, D. (2005). A dispersal-limited sampling theory for species and alleles. Ecology Letters, 8(100), 1147-1156.

Examples

SAD <- expected.SAD(theta = 42, m = 0.1, J = 200)
barplot(SAD,
        names.arg=0:(length(SAD)-1),
	      xlab="Number of individuals (log2)",
	      ylab="Number of Species" )

Estimate the expected species abundance distribution of both guilds using the guilds model, provided theta, alpha_x, alpha_y and J.

Description

This function estimates the expected species abundance distribution of both guilds using the guilds model, provided theta, alpha_x, alpha_y and J. The expected species abundance distribution is approximated by first drawing px from a beta distribution (equation 4 in Janzen et al. 2014). Then, guild sizes are drawn using equation 3 in Janzen et al. 2014. Because the abundance distributions of the two guilds are independent, the distributions can now be obtained using equation 6 in Etienne and Alonso 2005. Because drawing from the beta distribution and equation 3 is inherently stochastic, this function returns the average over a specified number of replicates.

Usage

expected.SAD.Guilds(theta, alpha_x, alpha_y, J, n_replicates = 100)

Arguments

Value

Author(s)

Thijs Janzen & Bart Haegeman

References

Etienne, R.S., & Alonso, D. (2005). A dispersal-limited sampling theory for species and alleles. Ecology Letters, 8(100), 1147-1156.

Examples

  SADs <- expected.SAD.Guilds(theta = 42, alpha_x = 0.01, alpha_y = 0.1, J = 1000, n_replicates = 3)
  par(mfrow=c(1,2));
  barplot(SADs$guildX,names.arg=0:(length(SADs$guildX)-1),
	  xlab="Number of individuals (log2)",
	  ylab="Number of Species",main="Guild X" )

  barplot(SADs$guildY,names.arg=0:(length(SADs$guildY)-1),
	  xlab="Number of individuals (log2)",
	  ylab="Number of Species",main="Guild Y" )

Estimate the expected species abundance distribution of both guilds using the guilds model, provided theta, alpha_x, alpha_y, conditional on the size of guild X, Jx and the size of guild Y, Jy.

Description

This function estimates the expected species abundance distribution of both guilds using the guilds model, provided theta, alpha_x, alpha_y and J. The expected species abundance distribution is approximated by first drawing px from equation 9. Because the abundance distributions of the two guilds are independent, the distributions can now be obtained using equation 6 in Etienne and Alonso 2005. Because drawing from the beta distribution and equation 3 is inherently stochastic, this function returns the average over a specified number of replicates.

Usage

expected.SAD.Guilds.Conditional(theta, alpha_x, alpha_y, Jx, Jy, n_replicates = 100)

Arguments

Value

Author(s)

Thijs Janzen & Bart Haegeman

References

Etienne, R.S., & Alonso, D. (2005). A dispersal-limited sampling theory for species and alleles. Ecology Letters, 8(100), 1147-1156.

Examples

  SADs <- expected.SAD.Guilds.Conditional(theta = 42,
                                          alpha_x = 0.01,
                                          alpha_y = 0.1,
                                          Jx = 100,
                                          Jy = 200,
                                          n_replicates = 3)

  par(mfrow=c(1,2))
  barplot(SADs$guildX, names.arg=0:(length(SADs$guildX) - 1),
	  xlab = "Number of individuals (log2)",
	  ylab = "Number of Species", main = "Guild X" )
  barplot(SADs$guildY, names.arg = 0:(length(SADs$guildY) - 1),
	  xlab = "Number of individuals (log2)",
	  ylab = "Number of Species", main = "Guild Y" )

Generate community data under the standard neutral model of biodiversity, using the urn scheme as described in Etienne 2005

Description

This function generates community data under the standard neutral model of biodiversity, using the urn scheme as described in Etienne 2005

Usage

generate.ESF(theta, I, J)

Arguments

Value

Vector containing the unlabeled species abundances in the local community

Author(s)

Thijs Janzen & Bart Haegeman

References

Etienne, R.S. (2005). A new sampling formula for neutral biodiversity. Ecology Letters, 8(3), 253-260.

Examples

	generate.ESF(theta = 42, I = 10, J = 2000)

Generate Artificial data under the GUILDS model

Description

Using this function it is possible to generate a community dataset consisting of two separate abundance vectors for each guild, where the data generated adhere to the Guilds model.

Usage

generate.Guilds(theta, alpha_x, alpha_y, J)

Arguments

Value

Author(s)

Thijs Janzen

Examples

generate.Guilds(theta = 200,
                alpha_x = 0.005,
                alpha_y = 0.001,
                J = 10000)

Generate Artificial data under the GUILDS model, conditioned on Guild size

Description

Using this function it is possible to generate a community dataset consisting of two separate abundance vectors for each guild, where the data generated adhere to the Guilds model. Data generated is conditioned on guild size.

Usage

generate.Guilds.Cond(theta, alpha_x, alpha_y, JX, JY)

Arguments

Value

Author(s)

Thijs Janzen

Examples

generate.Guilds.Cond(theta = 200,
                     alpha_x = 0.005,
                     alpha_y = 0.001,
                     JX = 15000,
                     JY = 5000);

Likelihood of the Etienne sampling formula

Description

This function calculates the likelihood of the Etienne Sampling Formula, provided abundance data and parameter values.

Usage

	logLikelihood.ESF(theta, m, abund)

Arguments

Value

Returns the LogLikelihood

Author(s)

Thijs Janzen

References

Etienne, R.S. (2005). A new sampling formula for neutral biodiversity. Ecology Letters, 8(3), 253-260.

Examples

	A <- c(1,1,1,3,5,8); #Artificial abundance dataset
	LL <- logLikelihood.ESF(theta = 7, m = 0.1, abund = A)

Likelihood of the Guilds sampling formula

Description

This function calculates the likelihood of the guilds model, provided abundance data and parameter values.

Usage

logLikelihood.Guilds(parameters, model, sadx, sady, verbose = TRUE)

Arguments

Value

returns the LogLikelihood

Author(s)

Thijs Janzen

Examples

exampleData <- generate.Guilds(theta = 200,
                               alpha_x = 0.005,
                               alpha_y = 0.001,
                               J = 1000)
#theta = 200, alpha X = 0.005, alpha Y = 0.001
parametervals <- c(200, 0.005, 0.001)
LL = logLikelihood.Guilds(parametervals,
                          model = "D1",
			                    exampleData$guildX,
			                    exampleData$guildY,
			                    verbose = TRUE)

Likelihood of the Guilds sampling formula, conditional on guild size

Description

This function calculates the likelihood of the guilds model, conditional on guild size; provided abundance data and parameter values.

Usage

logLikelihood.Guilds.Conditional(parameters, model, sadx, sady, verbose = TRUE)

Arguments

Value

returns the LogLikelihood

Author(s)

Thijs Janzen

Examples

exampleData <- generate.Guilds.Cond(theta = 200,
                                    alpha_x = 0.005,
                                    alpha_y = 0.001,
                                    JX = 1000,
                                    JY = 2000)
#theta = 200, alpha X = 0.005, alpha Y = 0.001
parametervals <- c(200, 0.005, 0.001)
LL = logLikelihood.Guilds.Conditional(parametervals,
                                      model="D1",
				                              exampleData$guildX,
				                              exampleData$guildY,
				                              verbose=TRUE)

Maximization of the loglikelihood given the standard Neutral Model, using the Etienne Sampling Formula

Description

This function computes the maximum likelihood estimates of the parameters of the Neutral model, using the Etienne Sampling Formula

Usage

maxLikelihood.ESF(init_vals, abund, verbose = FALSE)

Arguments

Value

the output is a list containing the following:

Author(s)

Thijs Janzen

References

Etienne, R.S. (2005). A new sampling formula for neutral biodiversity. Ecology Letters, 8(3), 253-260.

Examples

	A <- c(1, 1, 1, 3, 5, 8)
	maxLikelihood.ESF( c(7, 0.1), abund = A)

Maximization of the loglikelihood under the Guilds Model.

Description

This function computes the maximum likelihood estimates of the parameters of the guilds model.

Usage

maxLikelihood.Guilds(init_vals, model = "D0",
                     sadx, sady, verbose = FALSE)

Arguments

Value

The output is a list containing the following:

Author(s)

Thijs Janzen

Examples

## Not run: 
  J <- 10000

  theta <- 100
  alpha_x <- 0.1

  simul_data <- generate.Guilds(theta, alpha_x, alpha_x, J)

  #initial parameters for the D0 model c(theta,alpha)
  LL <- maxLikelihood.Guilds(init_vals = c(theta, alpha_x),
                             model = "D0",
                             sadx  = simul_data$guildX,
                             sady  = simul_data$guildY)

## End(Not run)

Maximization of the loglikelihood under the Guilds Model, conditioned on guild size.

Description

This function computes the maximum likelihood estimates of the parameters of the guilds model, conditioned on guild size.

Usage

maxLikelihood.Guilds.Conditional(init_vals, model, sadx, sady, verbose = TRUE)

Arguments

Value

The output is a list containing the following:

Author(s)

Thijs Janzen

Examples

theta = 20
alpha = 0.1
initParams <- c(theta, alpha)
maxLikelihood.Guilds.Conditional(initParams,
                                 model = "D0",
                                 sadx  = 1:20,
                                 sady  = 1:20,
                                 verbose = TRUE)

Barplot in Preston style of an abundance dataset

Description

This function first sorts abundances into octaves, and then plots the resulting distribution.

Usage

  preston_plot(abund, expected, ...)

Arguments

Author(s)

Thijs Janzen

Examples

  theta = 10
  m = 0.1
  J = 1000
  I = m * (J - 1) / (1 - m)
  
  abund <- generate.ESF(theta, I, J)
  par(mfrow = c(1,2))
  preston_plot(abund)
  abund.expect <- expected.SAD(theta, m, J)
  preston_plot(abund, abund.expect)