% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/allocate.diversity.R
\name{allocate.diversity}
\alias{allocate.diversity}
\title{Allocation of Entries to be Selected from Clusters/Groups based on Diversity
Index Estimates for Core Collection Development}
\usage{
allocate.diversity(
  data,
  names,
  group,
  qualitative,
  method = c("div", "div.prop", "div.sqrt", "div.log"),
  div.index = c("richness", "shannon", "simpson", "mcintosh"),
  shannon.base = exp(1),
  div.fun = NULL,
  log.base = exp(1),
  metric = c("pooled", "mean"),
  size
)
}
\arguments{
\item{data}{The data as a data frame object. The data frame should possess
one row per individual and columns with the individual names and multiple
trait/character data.}

\item{names}{Name of column with the accession names as a character string.}

\item{group}{Name of column with the accession group/cluster names as a
character string.}

\item{qualitative}{Name of columns with the qualitative traits as a character
vector.}

\item{method}{The allocation method. Either \code{"div"} for constant or
\code{"div.prop"} for proportional or \code{"div.log"} for logarithmic or
\code{"div.sqrt"} for square root allocation.}

\item{div.index}{The diversity index to be used to estimate within
cluster/group diversity.}

\item{shannon.base}{The logarithm base to be used for estimation of Shannon
diversity index. Default is \code{exp(1)}.}

\item{div.fun}{A function to estimate diversity index from a factor vector of
qualitative trait data.}

\item{log.base}{The logarithm base to be used for logarithmic method of
sampling. Default is \code{exp(1)}.}

\item{metric}{The metric to be computed from the diversity index. Either
\code{"pooled"} or \code{"mean"}.}

\item{size}{The desired core set size proportion.}
}
\value{
A named numeric vector specifying the number of entries to be
  selected from each cluster/group. The vector names correspond to the levels
  of the "\code{"group"} column, and values indicate the number of elements
  to be selected from each level.
}
\description{
Estimate the number of entries to be allocated from each cluster/group in the
entire collection to construct a core collection on the basis of different
metrics computed from within cluster/group diversity index estimates. The
following strategies are implemented. \loadmathjax
\itemize{
\item{Diversity}
\item{Diversity & Proportional}
\item{Diversity & Logarithmic}
\item{Diversity & Square root}}
}
\section{Details}{


  The number of entries to be chosen from each cluster is estimated either on
  the basis of diversity of entries within that cluster/group alone or in
  combination with the size of the cluster/group (See
  \strong{\code{Methods}}).

  There are several methods proposed on the basis of diversity indices such
  as genetic multiplicity (G) dependent method based on the range of genetic
  diversity \insertCite{yonezawa_sampling_1995}{SampleCore}, H strategy based
  on Nei's gene diversity \insertCite{nei_analysis_1973}{SampleCore} and a
  method based on the pooled Shannon diversity index
  \insertCite{bisht_assessment_1999,mahajan_sampling_1999}{SampleCore}.
  Similarly, measures such as expected proportion of heterozygous loci per
  individual and effective number of alleles have also been employed as a
  diversity measure for determining sample size
  \insertCite{franco_sampling_2006}{SampleCore}.

  The within-cluster/group diversity is estimated as either pooled or mean
  value of cluster/group-wise diversity indices. The following diversity
  indices are implemented in this function.

  \itemize{
   \item{Shannon or Shannon-Weaver or Shannon-Wiener Diversity Index or
   Shannon entropy
   (\mjseqn{H}) \insertCite{shannon_mathematical_1949,peet_measurement_1974}{SampleCore}}
   \item{Simpson's Index of Diversity or Gini's Diversity Index or
   Gini-Simpson Index or Nei's Diversity Index or Nei's Variation Index
   (\mjseqn{D}) or Hurlbert’s probability of interspecific encounter
   (\mjseqn{PIE}) \insertCite{gini_variabilita_1912,gini_variabilita_1912-1,greenberg_measurement_1956,berger_diversity_1970,hurlbert_nonconcept_1971,nei_analysis_1973,peet_measurement_1974}{SampleCore}}
   \item{McIntosh Diversity Index (\mjseqn{D_{Mc}})
   \insertCite{mcintosh_index_1967,peet_measurement_1974}{DiversityStats}}}
}

\section{Methods}{


  \subsection{Diversity method}{From an entire collection of size \mjseqn{N},
  to construct a core set of sample size \mjseqn{n}, the number of entries to
  be selected from the \mjseqn{i}th group among \mjseqn{1 \cdots g} groups
  (\mjseqn{n_{i}}) is estimated as below.

   \mjsdeqn{n_{i} = n \times \frac{D_{i}}{\sum_{i=1}^{g}D_{i}}}

   Where, \mjseqn{D_{i}} is a measure of the extent of diversity present in
   the \mjseqn{i}th cluster.

   }

   \subsection{Diversity and proportional method}{Here the number of entries
   to be selected is proportional to the diversity of the cluster/group
   (\mjseqn{D_{i}}) weighted by the the cluster/group size (\mjseqn{N_{i}}).

    \mjsdeqn{n_{i} = n \times \frac{N_{i}D_{i}}{\sum_{i=1}^{g}N_{i}D_{i}}}

   }

   \subsection{Diversity and logarithmic method}{Here the number of entries
   to be selected is proportional to the diversity of the cluster/group
   (\mjseqn{D_{i}}) weighted by the logarithm of the cluster/group size
   (\mjseqn{N_{i}}).

   \mjsdeqn{n_{i} = n \times
   \frac{\log(N_{i})D_{i}}{\sum_{i=1}^{g}\log(N_{i})D_{i}}}

   }

   \subsection{Diversity and square root method}{Here the number of entries
   to be selected is proportional to the diversity of the cluster/group
   (\mjseqn{D_{i}}) weighted by the square root of the cluster/group size
   (\mjseqn{N_{i}}).

   \mjsdeqn{n_{i} = n \times
   \frac{\sqrt{N_{i}}D_{i}}{\sum_{i=1}^{g}\sqrt{N_{i}}D_{i}}}

   }
}

\examples{
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Prepare example data
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

# Get data
data("cassava_EC_gp")

set.seed(123)
cassava_EC_gp <- cassava_EC_gp[sample(1:nrow(cassava_EC_gp), 500), ]

data <- cbind(genotypes = rownames(cassava_EC_gp), cassava_EC_gp)
row.names(data) <- NULL

# Column names of traits
quant <- c("NMSR", "TTRN", "TFWSR", "TTRW", "TFWSS", "TTSW", "TTPW",
           "AVPW", "ARSR", "SRDM")
qual <- c("CUAL", "LNGS", "PTLC", "DSTA", "LFRT", "LBTEF", "CBTR", "NMLB",
          "ANGB", "CUAL9M", "LVC9M", "TNPR9M", "PL9M", "STRP", "STRC",
          "PSTR")

# Convert qualitative data columns to factor
data[, qual] <- lapply(data[, qual], as.factor)

# Convert quantitative data columns to qualitative scores
quant_to_score5 <- function(x) {

  brks <- unique( quantile(x,
                           probs = seq(0, 1, 0.2),
                           na.rm = TRUE))
  cut(x, breaks = brks,
      include.lowest = TRUE,
      labels = seq_len(length(brks) - 1))
}

data[, quant] <- lapply(data[, quant], quant_to_score5)

traits <- c(quant, qual)

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Custom diversity index functions
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

div_fun_brillouin <- function(x) {
  n <- tabulate(x)
  n <- n[n > 0]
  N <- sum(n)
  if (N <= 1) {
    return(0)
  }
  (lgamma(N + 1) - sum(lgamma(n + 1)))/N
}

div_fun_margalef <- function(x) {
  tab <- tabulate(x)
  tab <- tab[tab > 0]
  S <- length(tab)
  N <- length(x)
  if (N <= 1) {
    return(0)
  }
  (S - 1)/log(N)
}

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Diversity allocation
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

## Shannon-Weaver Diversity Index
div_out_shannon1 <-
  allocate.diversity(data = data, names = "genotypes",
                    group = "Cluster",
                    qualitative = traits,
                    method = "div",
                    div.index = "shannon", metric = "pooled",
                    size = 0.2)
div_out_shannon1

div_out_shannon2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.index = "shannon", metric = "mean",
                     size = 0.2)
div_out_shannon2

##  Gini-Simpson Index
div_out_simpson1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.index = "simpson", metric = "pooled",
                     size = 0.2)
div_out_simpson1

div_out_simpson2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.index = "simpson", metric = "mean",
                     size = 0.2)
div_out_simpson2

## McIntosh Diversity Index
div_out_mcintosh1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.index = "mcintosh", metric = "pooled",
                     size = 0.2)
div_out_mcintosh1

div_out_mcintosh2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.index = "mcintosh", metric = "mean",
                     size = 0.2)
div_out_mcintosh2

## Richness
div_out_richness1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.index = "richness", metric = "pooled",
                     size = 0.2)
div_out_richness1

div_out_richness2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.index = "richness", metric = "mean",
                     size = 0.2)
div_out_richness2

## Brillouin Diversity Index
div_out_brillouin1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.fun = div_fun_brillouin, metric = "pooled",
                     size = 0.2)
div_out_brillouin1

div_out_brillouin2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.fun = div_fun_brillouin, metric = "mean",
                     size = 0.2)
div_out_brillouin2

## Margalef's richness Index
div_out_margalef1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.fun = div_fun_margalef, metric = "pooled",
                     size = 0.2)
div_out_margalef1

div_out_margalef2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div",
                     div.fun = div_fun_margalef, metric = "mean",
                     size = 0.2)
div_out_margalef2


#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Diversity allocation & Proportional
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

## Shannon-Weaver Diversity Index
dist_prop_out_shannon1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.index = "shannon", metric = "pooled",
                     size = 0.2)
dist_prop_out_shannon1

dist_prop_out_shannon2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.index = "shannon", metric = "mean",
                     size = 0.2)
dist_prop_out_shannon2

##  Gini-Simpson Index
dist_prop_out_simpson1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.index = "simpson", metric = "pooled",
                     size = 0.2)
dist_prop_out_simpson1

dist_prop_out_simpson2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.index = "simpson", metric = "mean",
                     size = 0.2)
dist_prop_out_simpson2

## McIntosh Diversity Index
dist_prop_out_mcintosh1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.index = "mcintosh", metric = "pooled",
                     size = 0.2)
dist_prop_out_mcintosh1

dist_prop_out_mcintosh2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.index = "mcintosh", metric = "mean",
                     size = 0.2)
dist_prop_out_mcintosh2

## Richness
div_out_richness1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "richness", metric = "pooled",
                     size = 0.2)
div_out_richness1

div_out_richness2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "richness", metric = "mean",
                     size = 0.2)
div_out_richness2

## Brillouin Diversity Index
div_out_brillouin1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.fun = div_fun_brillouin, metric = "pooled",
                     size = 0.2)
div_out_brillouin1

div_out_brillouin2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.fun = div_fun_brillouin, metric = "mean",
                     size = 0.2)
div_out_brillouin2

## Margalef's richness Index
div_out_margalef1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.fun = div_fun_margalef, metric = "pooled",
                     size = 0.2)
div_out_margalef1

div_out_margalef2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.prop",
                     div.fun = div_fun_margalef, metric = "mean",
                     size = 0.2)
div_out_margalef2

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Diversity allocation & Logarithmic
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

## Shannon-Weaver Diversity Index
dist_log_out_shannon1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "shannon", metric = "pooled",
                     size = 0.2)
dist_log_out_shannon1

dist_log_out_shannon2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "shannon", metric = "mean",
                     size = 0.2)
dist_log_out_shannon2

##  Gini-Simpson Index
dist_log_out_simpson1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "simpson", metric = "pooled",
                     size = 0.2)
dist_log_out_simpson1

dist_log_out_simpson2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "simpson", metric = "mean",
                     size = 0.2)
dist_log_out_simpson2

## McIntosh Diversity Index
dist_log_out_mcintosh1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "mcintosh", metric = "pooled",
                     size = 0.2)
dist_log_out_mcintosh1

dist_log_out_mcintosh2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "mcintosh", metric = "mean",
                     size = 0.2)
dist_log_out_mcintosh2

## Richness
div_out_richness1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "richness", metric = "pooled",
                     size = 0.2)
div_out_richness1

div_out_richness2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.index = "richness", metric = "mean",
                     size = 0.2)
div_out_richness2

## Brillouin Diversity Index
div_out_brillouin1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.fun = div_fun_brillouin, metric = "pooled",
                     size = 0.2)
div_out_brillouin1

div_out_brillouin2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.fun = div_fun_brillouin, metric = "mean",
                     size = 0.2)
div_out_brillouin2

## Margalef's richness Index
div_out_margalef1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.fun = div_fun_margalef, metric = "pooled",
                     size = 0.2)
div_out_margalef1

div_out_margalef2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.log",
                     div.fun = div_fun_margalef, metric = "mean",
                     size = 0.2)
div_out_margalef2

#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
# Diversity allocation & Square root
#~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

## Shannon-Weaver Diversity Index
dist_sqrt_out_shannon1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.index = "shannon", metric = "pooled",
                     size = 0.2)
dist_sqrt_out_shannon1

dist_sqrt_out_shannon2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.index = "shannon", metric = "mean",
                     size = 0.2)
dist_sqrt_out_shannon2

##  Gini-Simpson Index
dist_sqrt_out_simpson1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.index = "simpson", metric = "pooled",
                     size = 0.2)
dist_sqrt_out_simpson1

dist_sqrt_out_simpson2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.index = "simpson", metric = "mean",
                     size = 0.2)
dist_sqrt_out_simpson2

## McIntosh Diversity Index
dist_sqrt_out_mcintosh1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.index = "mcintosh", metric = "pooled",
                     size = 0.2)
dist_sqrt_out_mcintosh1

dist_sqrt_out_mcintosh2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.index = "mcintosh", metric = "mean",
                     size = 0.2)
dist_sqrt_out_mcintosh2

## Richness
div_out_richness1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.index = "richness", metric = "pooled",
                     size = 0.2)
div_out_richness1

div_out_richness2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.index = "richness", metric = "mean",
                     size = 0.2)
div_out_richness2

## Brillouin Diversity Index
div_out_brillouin1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.fun = div_fun_brillouin, metric = "pooled",
                     size = 0.2)
div_out_brillouin1

div_out_brillouin2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.fun = div_fun_brillouin, metric = "mean",
                     size = 0.2)
div_out_brillouin2

## Margalef's richness Index
div_out_margalef1 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.fun = div_fun_margalef, metric = "pooled",
                     size = 0.2)
div_out_margalef1

div_out_margalef2 <-
  allocate.diversity(data = data, names = "genotypes",
                     group = "Cluster",
                     qualitative = traits,
                     method = "div.sqrt",
                     div.fun = div_fun_margalef, metric = "mean",
                     size = 0.2)
div_out_margalef2

}
\references{
\insertAllCited
}
\seealso{
\code{\link[SampleCore]{allocate.basic}},
  \code{\link[SampleCore]{allocate.distance}}
}
