From c86fc92ef23eac9eddf0f0ede36e2237583e4551 Mon Sep 17 00:00:00 2001 From: Zhian Kamvar Date: Thu, 16 Jul 2015 21:44:05 -0700 Subject: [PATCH] update documentation. ALL FOR THE GLORY OF #47! --- DESCRIPTION | 4 ++-- R/Index_calculations.r | 30 ++++++++++++++++++++++-------- man/locus_table.Rd | 9 ++++++++- man/poppr.Rd | 13 ++++++++++--- 4 files changed, 42 insertions(+), 14 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index b7a9f3cc..3a4c8ff2 100644 --- a/DESCRIPTION +++ b/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", diff --git a/R/Index_calculations.r b/R/Index_calculations.r index 98992aec..938d0bd8 100755 --- a/R/Index_calculations.r +++ b/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 diff --git a/man/locus_table.Rd b/man/locus_table.Rd index dab714a8..49bf3cca 100644 --- a/man/locus_table.Rd +++ b/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}} diff --git a/man/poppr.Rd b/man/poppr.Rd index 25b2dbae..7546bbd8 100755 --- a/man/poppr.Rd +++ b/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}},