update documentation.

ALL FOR THE GLORY OF #47!

DESCRIPTION

@@ -1,8 +1,8 @@
 Package: poppr
 Type: Package
 Title: Genetic Analysis of Populations with Mixed Reproduction
-Version: 2.0.1.99-5
-Date: 2015-07-15
+Version: 2.0.1.99-15
+Date: 2015-07-16
 Authors@R: c(person(c("Zhian", "N."), "Kamvar", role = c("cre", "aut"),
     email = "kamvarz@science.oregonstate.edu"),
     person(c("Javier", "F."), "Tabima", role = "aut",

R/Index_calculations.r

@@ -127,7 +127,7 @@
 #'   common sample size (set by the parameter \code{minsamp}.} \item{SE}{The 
 #'   standard error for the rarefaction analysis} \item{H}{Shannon-Weiner 
 #'   Diversity index} \item{G}{Stoddard and Taylor's Index} 
-#'   \item{lambda}{Simpson's index} \item{E.5}{Evenness} \item{Hexp}{Nei's
+#'   \item{lambda}{Simpson's index} \item{E.5}{Evenness} \item{Hexp*}{Nei's
 #'   expected heterozygosity} \item{Ia}{A numeric vector giving the value of the
 #'   Index of Association for each population factor, (see \code{\link{ia}}).}
 #'   \item{p.Ia}{A numeric vector indicating the p-value for Ia from the number
@@ -156,11 +156,14 @@
 #'   groupings is "population" and the name for the x axis is "value".}
 #'   
 #' @note The calculation of \code{Hexp} has changed from \pkg{poppr} 1.x. It was
-#'   previously calculated based on the diversity of multilocus genotypes,
-#'   resulting in a value of 1 for sexual populations. This was obviously not
-#'   Nei's 1978 expected heterozygosity. We have thus changed the statistic to
-#'   be the true value of Hexp by calculating (n/(n-1))*lambda for alleles in
-#'   each locus and then returning the average.
+#'   previously calculated based on the diversity of multilocus genotypes, 
+#'   resulting in a value of 1 for sexual populations. This was obviously not 
+#'   Nei's 1978 expected heterozygosity. We have thus changed the statistic to 
+#'   be the true value of Hexp by calculating (kn/(kn-1))*lambda for alleles
+#'   where kn is the number of observed alleles (Nei, 1978) in each locus and
+#'   then returning the average. For polyploids, the number of alleles is
+#'   unknown, so Müller's index: (n/(n-1)) * mean(lambda) will be returned with
+#'   the name "Mu" (Kosman, 2003).
 #'   
 #' @seealso \code{\link{clonecorrect}}, \code{\link{poppr.all}}, 
 #'   \code{\link{ia}}, \code{\link{missingno}}, \code{\link{mlg}}, 
@@ -221,6 +224,10 @@
 #'   J.A. Stoddart and J.F. Taylor. Genotypic diversity: estimation and 
 #'   prediction in samples. Genetics, 118(4):705-11, 1988.
 #'   
+#'   Kosman, E. Nei's gene diversity and the index of average
+#'   differences are identical measures of diversity within populations. Plant
+#'   Pathology, 52(5), 533-535. 2003,
+#'   
 #'   
 #' @examples
 #' data(nancycats)
@@ -819,8 +826,11 @@ pair.ia <- function(gid, quiet = FALSE, plot = TRUE, low = "blue", high = "red",
 #'   
 #' @seealso \code{\link[vegan]{diversity}}, \code{\link{poppr}}
 #'   
-#' @note This will calculate statistics for polyploids as well by only counting
-#'   observed allelic states.
+#' @note This will calculate statistics for polyploids as well by only counting 
+#'   observed allelic states. The only exception is Nei's expected 
+#'   heterozygosity. Since this requires knowledge of allelic dosage, Müller's 
+#'   index (Mu) will be used instead. It can be thought of as an unbiased
+#'   Simpson's index and is calculated as (n/(n-1))*mean(1-D) (Kosman, 2003)
 #' 
 #' @author Zhian N. Kamvar
 #' 
@@ -847,6 +857,10 @@ pair.ia <- function(gid, quiet = FALSE, plot = TRUE, low = "blue", high = "red",
 #' 
 #'   Claude Elwood Shannon. A mathematical theory of communication. Bell Systems
 #'   Technical Journal, 27:379-423,623-656, 1948
+#'   
+#'   Kosman, E. Nei's gene diversity and the index of average differences are
+#'   identical measures of diversity within populations. Plant Pathology, 52(5),
+#'   533-535. 2003.
 #' 
 #' @export
 #' @examples

man/locus_table.Rd

@@ -36,7 +36,10 @@ Create a table of summary statistics per locus.
 }
 \note{
 This will calculate statistics for polyploids as well by only counting
-  observed allelic states.
+  observed allelic states. The only exception is Nei's expected
+  heterozygosity. Since this requires knowledge of allelic dosage, Müller's
+  index (Mu) will be used instead. It can be thought of as an unbiased
+  Simpson's index and is calculated as (n/(n-1))*mean(1-D) (Kosman, 2003)
 }
 \examples{
 # Analyze locus statistics for the North American population of P. infestans.
@@ -69,6 +72,10 @@ Jari Oksanen, F. Guillaume Blanchet, Roeland Kindt, Pierre Legendre, Peter
 
   Claude Elwood Shannon. A mathematical theory of communication. Bell Systems
   Technical Journal, 27:379-423,623-656, 1948
+
+  Kosman, E. Nei's gene diversity and the index of average differences are
+  identical measures of diversity within populations. Plant Pathology, 52(5),
+  533-535. 2003.
 }
 \seealso{
 \code{\link[vegan]{diversity}}, \code{\link{poppr}}

man/poppr.Rd

@@ -85,7 +85,7 @@ poppr(dat, total = TRUE, sublist = "ALL", blacklist = NULL, sample = 0,
   common sample size (set by the parameter \code{minsamp}.} \item{SE}{The
   standard error for the rarefaction analysis} \item{H}{Shannon-Weiner
   Diversity index} \item{G}{Stoddard and Taylor's Index}
-  \item{lambda}{Simpson's index} \item{E.5}{Evenness} \item{Hexp}{Nei's
+  \item{lambda}{Simpson's index} \item{E.5}{Evenness} \item{Hexp*}{Nei's
   expected heterozygosity} \item{Ia}{A numeric vector giving the value of the
   Index of Association for each population factor, (see \code{\link{ia}}).}
   \item{p.Ia}{A numeric vector indicating the p-value for Ia from the number
@@ -128,8 +128,11 @@ The calculation of \code{Hexp} has changed from \pkg{poppr} 1.x. It was
   previously calculated based on the diversity of multilocus genotypes,
   resulting in a value of 1 for sexual populations. This was obviously not
   Nei's 1978 expected heterozygosity. We have thus changed the statistic to
-  be the true value of Hexp by calculating (n/(n-1))*lambda for alleles in
-  each locus and then returning the average.
+  be the true value of Hexp by calculating (kn/(kn-1))*lambda for alleles
+  where kn is the number of observed alleles (Nei, 1978) in each locus and
+  then returning the average. For polyploids, the number of alleles is
+  unknown, so Müller's index: (n/(n-1)) * mean(lambda) will be returned with
+  the name "Mu" (Kosman, 2003).
 }
 \examples{
 data(nancycats)
@@ -234,6 +237,10 @@ Paul-Michael Agapow and Austin Burt. Indices of multilocus
 
   J.A. Stoddart and J.F. Taylor. Genotypic diversity: estimation and
   prediction in samples. Genetics, 118(4):705-11, 1988.
+
+  Kosman, E. Nei's gene diversity and the index of average
+  differences are identical measures of diversity within populations. Plant
+  Pathology, 52(5), 533-535. 2003,
 }
 \seealso{
 \code{\link{clonecorrect}}, \code{\link{poppr.all}},