R/dispersalDiversity-package.R

In douglasgscofield/dispersalDiversity: Analyse individual and genetic diversity of dispersal processes in biological populations

#' Analyse individual and genetic diversity of dispersal processes in biological populations
#'
#' A collection of R functions to analyse individual and genetic diversity in
#' biological populations, primarily in the context of studying dispersal
#' processes.  The basic data format is a sites-by-counts matrix.  Functions are
#' provided for calculating alpha, beta, delta/omega and gamma diversity using a
#' variety of measures; calculating alpha, beta, delta/omega and gamma diversity
#' of allelic variation; and comparing diversity measures between samples.
#'
#' A similar set of functions provides analyses for either of two types of data
#' sets.  The first is sites-by-counts data, with sites representing some form
#' of aggregation including groupings, hosts, seed caches, etc., and counts
#' being of species, parents, haplotypes, etc.  Sites-by-counts data is held
#' within a table of class \code{\link{divtable}}.  The methods underlying
#' these analyses are derived from classical biodiversity measures and are
#' described in Scofield \emph{et al}. (2012).
#'
#' The second data set accepted describes similar patterns but for genetic
#' diversity coded as alleles.  An object of class
#' \code{\link{allele_divtables}} is a list of tables of class
#' \code{\link{divtable}}, one table per locus under study.  Each such
#' table contains sites-by-alleles counts for individual loci.  These data
#' are analysed with extensions of the Scofield \emph{et al}. (2012) methods
#' as described in Sork \emph{et al}. (in press).
#'
#' The function \code{createAlleleTables} accepts an argument of class
#' \code{genalex} or of a class and format convertable to class
#' \code{genalex} using \code{\link[readGenalex]{as.genalex}}.
#'
#' @note
#'
#' Due to their mathematical structure, the functions testing structure in
#' diversity cannot accept data sets with rows (sites) containing a single
#' item.  The functions will generate an error if given such data.  The
#' \code{\link{as.divtable}} function will produce a warning if given such
#' data.  Descriptive functions such as \code{\link{diversity}} and the
#' plotting functions will accept such data without warning or error, though
#' some estimators may produce \code{NA} or \code{NaN}.
#'
#' These statistical tools were developed in collaboration with Peter E.
#' Smouse (Rutgers University) and Victoria L. Sork (UCLA) and were funded
#' in part by U.S. National Science Foundation awards NSF-DEB-0514956 and
#' NSF-DEB-0516529.
#'
#' @references
#'
#' Grivet, D., Smouse, P. E. and Sork, V. L. (2005) A novel approach to an old
#' problem: tracking dispersed seeds.  \emph{Molecular Ecology} 14:3585-3595.
#'
#' Nielsen, R., Tarpy, D. R. and Reeve, H. K. (2003) Estimating effective
#' paternity number in social insects and the effective number of alleles in
#' a population.  \emph{Molecular Ecology} 12:3157-3164.
#'
#' Scofield, D. G.,  Sork, V. L. and Smouse, P. E. (2010) Influence of acorn
#' woodpecker social behaviour on transport of coast live oak
#' (\emph{Quercus agrifolia}) acorns in a southern California oak savanna.
#' \emph{Journal of Ecology} 98:561-572.
#'
#' Scofield, D. G., Alfaro, V. R., Sork, V. L., Grivet, D., Martinez, E.,
#' Papp, J., Pluess, A. R., Koenig, W. D. and Smouse, P. E. (2011) Foraging
#' patterns of acorn woodpeckers (\emph{Melanerpes formicivorus}) on valley
#' oak (\emph{Quercus lobata} N\'{e}e) in two California oak savanna-woodlands.
#' Oecologia 166:187-196.
#'
#' Scofield, D. G., Smouse, P. E., Karubian, J. and Sork, V. L. (2012)
#' Use of alpha, beta and gamma diversity measures to characterize seed
#' dispersal by animals.  \emph{American Naturalist} 180:719-732.
#'
#' Sork, V. L., Smouse, P. E., Grivet, D. and Scofield, D. G.  (In press)
#' Impact of asymmetric male and female gamete dispersal on allelic diversity
#' and spatial genetic structure in valley oak (\emph{Quercus lobata} N\'{e}e).
#' \emph{Evolutionary Ecology}.
#'
#' \url{https://github.com/douglasgscofield/dispersalDiversity}
#'
#' @docType package
#'
#' @name dispersalDiversity-package
#'
NULL