RInSp (version 1.2.5)

Emc: Monte Carlo resampling procedure for index E and Cws

Description

The procedure performs a Monte Carlo resampling under a null hypothesis to calculate the E measure of interindividual variation and the value of the \(C_{ws}\) measure of modularity following Araujo et al. (2008).

Usage

Emc(dataset, popd.type = "sum", index = "saramaki", replicates=999, precision = 1e-9)

Arguments

dataset

Object of class RInSp. Only data of type “integer” can be used. See import.RInSp for details.

popd.type

Option specifying the way to calculate the population diet. Valid values are “sum” or “average”. See pop.diet for details.

index

The type of clustering coefficient to use. Valid values are Saramaki's and Barrat's index: “saramaki” or “barrat”. See Eindex for details.

replicates

Number of replicates for the Monte Carlo resampling, under the null hypothesis that any observed diet variation arose from individuals sampling stochastically from a shared distribution.

precision

a filter to remove from the PS matrix all values which are lower than "precision". In this way some interactions are removed due to their small weight in the PS matrix.

Value

The result is a list of class ‘RInSp’ composed of:

E

Value of the index of individual specialization E.

meannullE

The mean value of the Monte Carlo resampling simulated data.

Eadj

The adjusted value of E.

p.value

It is the proportion of Monte Carlo resampling simulated values greater than the observed E.

montecarlo

It is a matrix where the first line collects the values of Omean, E, CW and Cws for the provided dataset, and the following lines hold the Monte Carlo resampled values.

pop.diet

Option specifying the way to calculate the population diet. Valid values are “sum” or “average”.

ind.type

The type of clustering coefficient to use. Valid values are Saramaki's and Barrat's index: “saramaki” or “barrat”.

parameter

an index used in sumMC.RInSp to point to the column of the matrix ‘montecarlo’ for plotting results. If zero no Monte Carlo resampling is performed.

Precission

The value of the selected threshold for precision.

Details

For counts of individual prey items representing approximately independent prey-capture decisions (i.e., integer data type), it is possible to run a Monte Carlo resampling simulation to test the null hypothesis that any observed diet variation arose from individuals sampling stochastically from a shared distribution. See Araujo et al. (2011) for a discussion of the biological assumptions underlying this Monte Carlo resampling procedure. In the simulations, each individual is assigned a number of prey items equal to the number of items it was observed eating, and then prey items are randomly assigned to the individual's diet via multinomial sampling from the observed population resource distribution. Next, both \(E\) and \(C_{ws}\) are recalculated for the resulting simulated population. The program generates a specified number of such null datasets, and the observed test statistic is compared to the distribution observed under the null hypothesis.

Note that the Monte Carlo method should not be applied to non-integer diet data (e.g., total mass of each prey species, proportion of stomach volume per prey species).

There are two options for calculating the population's diet proportions (\(q_j\), the proportion of the resource j in the population's diet): sum and average. When sum is specified, one sums up all resource counts within a category across all individuals to get the population's use, then determine the proportion of each resource category in the population's repertoire:

$$ q_j = \frac{\sum_i{n_{ij}}}{\sum_{ji}{n_{ij}}}$$

The drawback of this approach is that individuals that eat large numbers of items, or larger total mass of items, will bias the population to look more like them. The average method (average proportion) circumvents this problem by first converting individual diets into proportions \(p_{ik}\), then averaging these proportions for each resource k.

An adjusted value of E is calculated as:

$$E_{adj} = \frac{E_{obs} - E_{null}}{1 - E_{null}}$$

This rescales the value of E (i.e., the observed value \(E_{obs}\)) to range from a minimum of 0 when the observed value is equal to the mean Null value (i.e., \(E_{null}\), up to a maximum of 1 when individual specialization is strongest). This allows one to compare datasets with different mean Null values.

Version 1.1 of the package fixes the case of highly specialised individuals in the calculation of \(C_{ws}\) by removing a bug in the C code taken from Dieta1.c affecting how the weight matrix and the number of links where calculated when highly specilised individuals are present.

References

Araujo M.S., Guimaraes Jr., P.R., Svanback, R., Pinheiro, A., Guimaraes P., dos Reis, S.F., and Bolnick, D.I. 2008. Network analysis reveals contrasting effects of intraspecific competition on individual vs. population diets. Ecology 89: 1981-1993.

Araujo M.A., Layman C., and Bolnick, D.I. 2011. The ecological causes of individual specialization. Ecology Letters 14: 948-958.

Schoener, T.W. 1968. The Anolis lizards of Bimini: resources partitioning in a complex fauna. Ecology 49: 704-726.

See Also

Function Eindex, Null.Hp.RInSp, sumMC.RInSp.

Examples

# NOT RUN {
# Example with stickleback data from Bolnick and Paull 2009
data(Stickleback)
# Select a single spatial sampling site (site B)
GutContents_SiteB <- import.RInSp(Stickleback, row.names = 1,
info.cols = c(2:13), subset.rows = c("Site", "B"))
# Warning, the number of replicates is set low to speed up the example!
# Note, for real analyses we recommend to set replicates => 999
ResEmc <- Emc(GutContents_SiteB, popd.type = "average", replicates = 99)

# This Eadj re-scales the observed E value to range from 0 when
# it is equal to the null expectation, up to a maximum of 1.
# This allows comparison of E values across samples with
# different null Es.
# For example, consider a case with no individual specialization
Nulldata <- Null.Hp.RInSp(GutContents_SiteB, prop="average")
# Warning, the number of replicates is set low to speed up he example!
# Note, for real analyses we recommend to set replicates => 999
EmcNull <- Emc(Nulldata, popd.type = "average", replicates = 99)
rm(list=ls(all=TRUE))
# }