Perform bootstrap statistics, calculate, and plot confidence intervals.
Description
This function is for calculating bootstrap statistics and their confidence intervals. It is important to note that the calculation of confidence intervals is not perfect (See Details). Please be cautious when interpreting the results.
Usage
1 2 3 
Arguments
tab 
a 
n 
an integer defining the number of bootstrap replicates (defaults to 1000). 
n.boot 
an integer specifying the number of samples to be drawn in each
bootstrap replicate. If 
ci 
the percent for confidence interval. 
total 
argument to be passed on to 
rarefy 
if 
n.rare 
an integer specifying the smallest size at which to resample
data. This is only used if 
plot 
If 
raw 
if 
center 
if 
... 
parameters to be passed on to 
Details
Bootstrapping
For details on the bootstrapping procedures, see
diversity_boot
. Default bootstrapping is performed by
sampling N samples from a multinomial distribution weighted by the
relative multilocus genotype abundance per population where N is
equal to the number of samples in the data set. If n.boot > 2,
then n.boot samples are taken at each bootstrap replicate. When
rarefy = TRUE
, then samples are taken at the smallest population
size without replacement. This will provide confidence intervals for all
but the smallest population.
Confidence intervals
Confidence intervals are derived from the function
norm.ci
. This function will attempt to correct for bias
between the observed value and the bootstrapped estimate. When center
= TRUE
(default), the confidence interval is calculated from the
bootstrapped distribution and centered around the biascorrected estimate
as prescribed in Marcon (2012). This method can lead to undesirable
properties, such as the confidence interval lying outside of the maximum
possible value. For rarefaction, the confidence interval is simply
determined by calculating the percentiles from the bootstrapped
distribution. If you want to calculate your own confidence intervals, you
can use the results of the permutations stored in the $boot
element
of the output.
Rarefaction
Rarefaction in the sense of this function is simply sampling a subset of the data at size n.rare. The estimates derived from this method have straightforward interpretations and allow you to compare diversity across populations since you are controlling for sample size.
Plotting
Results are plotted as boxplots with point estimates. If there is no rarefaction applied, confidence intervals are displayed around the point estimates. The boxplots represent the actual values from the bootstrapping and will often appear below the estimates and confidence intervals.
Value
raw = TRUE

obs  a matrix with observed statistics in columns, populations in rows

est  a matrix with estimated statistics in columns, populations in rows

CI  an array of 3 dimensions giving the lower and upper bound, the index measured, and the population.

boot  a list containing the output of
boot
for each population.
raw = FALSE
a data frame with the statistic observations, estimates, and confidence intervals in columns, and populations in rows. Note that the confidence intervals are converted to characters and rounded to three decimal places.
Note
Confidence interval calculation
Almost all of the statistics supplied here have a maximum when all genotypes are equally represented. This means that bootstrapping the samples will always be downwardly biased. In many cases, the confidence intervals from the bootstrapped distribution will fall outside of the observed statistic. The reported confidence intervals here are reported by assuming the variance of the bootstrapped distribution is the same as the variance around the observed statistic. As different statistics have different properties, there will not always be one clear method for calculating confidence intervals. A suggestion for correction in Shannon's index is to center the CI around the observed statistic (Marcon, 2012), but there are theoretical limitations to this. For details, see http://stats.stackexchange.com/q/156235/49413.
Userdefined functions
While it is possible to use custom functions with this, there are three important things to remember when using these functions:
The function must return a single value.
The function must allow for both matrix and vector inputs
The function name cannot match or partially match any arguments from
boot
Anonymous functions are okay
(e.g. function(x)
vegan::rarefy(t(as.matrix(x)), 10)
).
Author(s)
Zhian N. Kamvar
References
Marcon, E., Herault, B., Baraloto, C. and Lang, G. (2012). The Decomposition of Shannonâ€™s Entropy and a Confidence Interval for Beta Diversity. Oikos 121(4): 516522.
See Also
diversity_boot
diversity_stats
poppr
boot
norm.ci
boot.ci
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31  library(poppr)
data(Pinf)
diversity_ci(Pinf, n = 100L)
## Not run:
# With pretty results
diversity_ci(Pinf, n = 100L, raw = FALSE)
# This can be done in a parallel fasion (OSX uses "multicore", Windows uses "snow")
system.time(diversity_ci(Pinf, 10000L, parallel = "multicore", ncpus = 4L))
system.time(diversity_ci(Pinf, 10000L))
# We often get many requests for a clonal fraction statistic. As this is
# simply the number of observed MLGs over the number of samples, we
# recommended that people calculate it themselves. With this function, you
# can add it in:
CF < function(x){
x < drop(as.matrix(x))
if (length(dim(x)) > 1){
res < rowSums(x > 0)/rowSums(x)
} else {
res < sum(x > 0)/sum(x)
}
return(res)
}
# Show pretty results
diversity_ci(Pinf, 1000L, CF = CF, center = TRUE, raw = FALSE)
diversity_ci(Pinf, 1000L, CF = CF, rarefy = TRUE, raw = FALSE)
## End(Not run)
