WTdMC: Monte Carlo resampling of WIC/TNW for the discrete case
In RInSp: R Individual Specialization
WTdMC R Documentation
Monte Carlo resampling of WIC/TNW for the discrete case
Description
The program calculates the Total Niche Width (TNW), and breaks TNW down into its Between Individual Component (BIC) and Within Individual Component (WIC). It reports these three statistics and the proportion WIC/TNW. Niche widths of the population, within individuals, and among individuals are calculated using the Shannon-Weaver diversity index on count data, following Roughgarden's formulas (1974) and Bolnick et al. (2002).
A Monte Carlo resampling routine is used to calculate a null distribution for each of these statistics and generate a p-value testing the null hypothesis that all individuals sample equally from the population diet distribution. Note that the bootstrapping procedure is only biologically meaningful when applied to integer data representing counts of individual prey within individual predators' diets, and should not be applied to other forms of data such as prey mass or proportion of total volume.
Usage
WTdMC(dataset, pop.diet = "sum", replicates=999, print.ris=TRUE)
Arguments
dataset
Object of class RInSp with data of type “integer”.
pop.diet
Option specifying the way to calculate the population diet. Valid values are “sum” or “average”. See pop.diet for details.
replicates
Number of replicates for the Monte Carlo resampling.
print.ris
Printing results to screen. Default is TRUE.
Details
The Roughgarden's measures are the most widely reported indices of diet variation, due to historical precedent. They are closely analogous to an Analysis of Variance, in that one partitions the total variation in resource use (TNW) into within- and between-individual components (WIC and BIC). An advantage of this approach is that one can simultaneously evaluate the degree of diet variation (WIC/TNW), and shifts in individual and population niche widths. A drawback is that, for categorical diet data, the Shannon-Weaver measure of diversity can lead to biased estimates of diet variation (Bolnick et al. 2002). Despite its historical precedent, users are advised to avoid using WIC/TNW. This bias is not a concern for WIC/TNW measured on quantitative traits (prey size) rather than prey categories, but this is rarely done.
Roughgarden (1979, pg 510) proposed a measure to describe the niche width based on Shannon-Weaver information theory. The following formulae are equivalent to Roughgarden's formulation, although we use different notation. Let N be a matrix of diet data, where elements n_{ij} represent the number (or mass) of diet items in individual i's diet that fall in category j. This raw data matrix is then transformed into a proportion matrix P, with elements p_{ij} describing the proportion of the jth resource category in individual (or phenotype) i's diet.
Using these proportions or the raw numerical counts one then calculates population diet proportions (q_{k}, see pop.diet for details). These data can then be used to calculate WIC, BIC, and TNW (Roughgarden 1979; Bolnick et al. 2002):
WIC = ∑_i{p_i} (- ∑_k{p_{ik} ln(p_{ik})})
BIC = ∑_k{p_i ln(p_i)} - ∑_k{q_k (- ∑_i{t_{ik}ln(t_{ik})})}
TNW = - ∑_k{q_k ln(q_k)}
where: p_i is the proportion of all resources used by individual i (\frac{∑_k{n_{ik}}}{∑_{ik}{n_{ik}}}); q_k is the proportion of the kth resource category in the population's niche, and t_{ik} is the proportion of the population's total use of resource k that was used by individual i (i.e., \frac{n_{ik}}{∑_i{n_{ik}}}).
It is important to remember that TNW = BIC + WIC, and one can easily calculate the proportion WIC, which we refer to as WIC/TNW.
Be aware that monophagous individuals (100% of diet from a single resource) have excessively large leverage drawing WIC towards zero, possibly leading to downward-biased WIC/TNW exaggerating individual specialization. The procedure prints a warning message with the name of monophagous individuals in the dataset.
The Monte Carlo resampling procedure first determines the number of prey used by each individual, n_i. It then determines the frequencies with which the population as a whole used the various resources (see pop.diet for details). Subsequently, the procedure randomly reassigns each individual n_i prey drawn from the population frequency distribution, and then recalculates a null measure of diet variation. This is repeated a user-specified number of times. Hence, the resampled population yields a null model corresponding to a population composed of generalists that sample randomly from the population's diet, and have diet sizes equal to those of the observed data set.
The original statistics are merged into the Monte Carlo set.
Value
The result is a list of class ‘RInSp’ composed of:
WonT
The value of WIC/TNW for the dataset “dataset”.
Zeros
A character vector with the names of individuals with Shannon-Weaver scores equal to zero. Or zero otherwise.
p.value
The Monte Carlo resampling probability value for the calculated WIC/TNW ratio;
montecarlo
A matrix with the replicate number ‘Zeroes’, the value of ‘WIC’, the value of ‘BIC’, the value of ‘TNW’ and the derived value for ‘WonT’. The first line holds the values for the provided dataset, and the following lines the results of the Monte Carlo resampling.
parameter
An index used in sumMC.RInSp to point to the column of the matrix ‘montecarlo’ for plotting results.
Author(s)
Dr. Nicola ZACCARELLI. Please note that the C code is partially based on the C++ source of IndSpec from Bolnick et al. (2002).
The original source code of IndSpec1.0.exe is available from the “Ecological Archives” of the Ecological Society of America (http://esapubs.org/archive/): identifier E083-056-S1; http://esapubs.org/archive/ecol/E083/056/.
References
Bolnick, D.I., L.H. Yang, J.A. Fordyce, J.M. Davis, and Svanback, R. 2002. Measuring individual-level resource specialization. Ecology 83: 2936-2941.
Roughgarden, J. 1979. Theory of population genetics and evolutionary ecology: an introduction. Macmillan, New York, NY, USA.
See Also
For the continuous case see WTcMC and for a summary statistics the function sumMC.RInSp.
Examples
data(Stickleback)
# Select a single spatial sampling site (site A)
GutContents_SiteA <- import.RInSp(Stickleback, row.names = 1,
info.cols = c(2:13), subset.rows = c("Site", "A"))
# Warning, the number of replicates is set low to speed up he example!
# Note, for real analyses we recommend to set replicates => 999
WT <- WTdMC(GutContents_SiteA, replicates = 99)
sumMC.RInSp(WT)
rm(list=ls(all=TRUE))
RInSp documentation built on May 20, 2022, 9:06 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| WTdMC | R Documentation |
Monte Carlo resampling of WIC/TNW for the discrete case
Description
The program calculates the Total Niche Width (TNW), and breaks TNW down into its Between Individual Component (BIC) and Within Individual Component (WIC). It reports these three statistics and the proportion WIC/TNW. Niche widths of the population, within individuals, and among individuals are calculated using the Shannon-Weaver diversity index on count data, following Roughgarden's formulas (1974) and Bolnick et al. (2002). A Monte Carlo resampling routine is used to calculate a null distribution for each of these statistics and generate a p-value testing the null hypothesis that all individuals sample equally from the population diet distribution. Note that the bootstrapping procedure is only biologically meaningful when applied to integer data representing counts of individual prey within individual predators' diets, and should not be applied to other forms of data such as prey mass or proportion of total volume.
Usage
WTdMC(dataset, pop.diet = "sum", replicates=999, print.ris=TRUE)
Arguments
dataset |
Object of class RInSp with data of type “integer”. |
pop.diet |
Option specifying the way to calculate the population diet. Valid values are “sum” or “average”. See |
replicates |
Number of replicates for the Monte Carlo resampling. |
print.ris |
Printing results to screen. Default is TRUE. |
Details
The Roughgarden's measures are the most widely reported indices of diet variation, due to historical precedent. They are closely analogous to an Analysis of Variance, in that one partitions the total variation in resource use (TNW) into within- and between-individual components (WIC and BIC). An advantage of this approach is that one can simultaneously evaluate the degree of diet variation (WIC/TNW), and shifts in individual and population niche widths. A drawback is that, for categorical diet data, the Shannon-Weaver measure of diversity can lead to biased estimates of diet variation (Bolnick et al. 2002). Despite its historical precedent, users are advised to avoid using WIC/TNW. This bias is not a concern for WIC/TNW measured on quantitative traits (prey size) rather than prey categories, but this is rarely done.
Roughgarden (1979, pg 510) proposed a measure to describe the niche width based on Shannon-Weaver information theory. The following formulae are equivalent to Roughgarden's formulation, although we use different notation. Let N be a matrix of diet data, where elements n_{ij} represent the number (or mass) of diet items in individual i's diet that fall in category j. This raw data matrix is then transformed into a proportion matrix P, with elements p_{ij} describing the proportion of the jth resource category in individual (or phenotype) i's diet.
Using these proportions or the raw numerical counts one then calculates population diet proportions (q_{k}, see pop.diet for details). These data can then be used to calculate WIC, BIC, and TNW (Roughgarden 1979; Bolnick et al. 2002):
WIC = ∑_i{p_i} (- ∑_k{p_{ik} ln(p_{ik})})
BIC = ∑_k{p_i ln(p_i)} - ∑_k{q_k (- ∑_i{t_{ik}ln(t_{ik})})}
TNW = - ∑_k{q_k ln(q_k)}
where: p_i is the proportion of all resources used by individual i (\frac{∑_k{n_{ik}}}{∑_{ik}{n_{ik}}}); q_k is the proportion of the kth resource category in the population's niche, and t_{ik} is the proportion of the population's total use of resource k that was used by individual i (i.e., \frac{n_{ik}}{∑_i{n_{ik}}}).
It is important to remember that TNW = BIC + WIC, and one can easily calculate the proportion WIC, which we refer to as WIC/TNW.
Be aware that monophagous individuals (100% of diet from a single resource) have excessively large leverage drawing WIC towards zero, possibly leading to downward-biased WIC/TNW exaggerating individual specialization. The procedure prints a warning message with the name of monophagous individuals in the dataset.
The Monte Carlo resampling procedure first determines the number of prey used by each individual, n_i. It then determines the frequencies with which the population as a whole used the various resources (see pop.diet for details). Subsequently, the procedure randomly reassigns each individual n_i prey drawn from the population frequency distribution, and then recalculates a null measure of diet variation. This is repeated a user-specified number of times. Hence, the resampled population yields a null model corresponding to a population composed of generalists that sample randomly from the population's diet, and have diet sizes equal to those of the observed data set.
The original statistics are merged into the Monte Carlo set.
Value
The result is a list of class ‘RInSp’ composed of:
WonT |
The value of WIC/TNW for the dataset “dataset”. |
Zeros |
A character vector with the names of individuals with Shannon-Weaver scores equal to zero. Or zero otherwise. |
p.value |
The Monte Carlo resampling probability value for the calculated WIC/TNW ratio; |
montecarlo |
A matrix with the replicate number ‘Zeroes’, the value of ‘WIC’, the value of ‘BIC’, the value of ‘TNW’ and the derived value for ‘WonT’. The first line holds the values for the provided dataset, and the following lines the results of the Monte Carlo resampling. |
parameter |
An index used in |
Author(s)
Dr. Nicola ZACCARELLI. Please note that the C code is partially based on the C++ source of IndSpec from Bolnick et al. (2002).
The original source code of IndSpec1.0.exe is available from the “Ecological Archives” of the Ecological Society of America (http://esapubs.org/archive/): identifier E083-056-S1; http://esapubs.org/archive/ecol/E083/056/.
References
Bolnick, D.I., L.H. Yang, J.A. Fordyce, J.M. Davis, and Svanback, R. 2002. Measuring individual-level resource specialization. Ecology 83: 2936-2941.
Roughgarden, J. 1979. Theory of population genetics and evolutionary ecology: an introduction. Macmillan, New York, NY, USA.
See Also
For the continuous case see WTcMC and for a summary statistics the function sumMC.RInSp.
Examples
data(Stickleback)
# Select a single spatial sampling site (site A)
GutContents_SiteA <- import.RInSp(Stickleback, row.names = 1,
info.cols = c(2:13), subset.rows = c("Site", "A"))
# Warning, the number of replicates is set low to speed up he example!
# Note, for real analyses we recommend to set replicates => 999
WT <- WTdMC(GutContents_SiteA, replicates = 99)
sumMC.RInSp(WT)
rm(list=ls(all=TRUE))
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.