R/dec_equit.R

In diversityArch: Computes Diversity Indices for Archaeological Data

#' @title Decomposition of the equitability index
#'
#' @description Computes equitability and its decomposition
#'
#' @param x Vector of dimension S (number of species) with the number of individuals observed in each species, or the distribution frequencies of species. NA values are allowed.
#' @param groups Vector of dimension S of factors indicating the group of each species.
#'
#' @return
#' \itemize{
#'   \item \code{equitability}: Equitability index.
#'   \item \code{within}: Within groups equitability.
#'   \item \code{between}: Between groups equitability.
#' }
#'
#' @seealso \link{dec_shannon}
#'
#' @references
#' Arnaud Barat, Andreu Sansó, Maite Arilla-Osuna, Ruth Blasco, Iñaki Pérez-Fernández, Gabriel Cifuentes-Alcobenda, Rubén Llorente, Daniel Vivar-Ríos, Ella Assaf, Ran Barkai, Avi Gopher, & Jordi Rosell-Ardèvol (2026) <doi:10.1007/s10816-026-09802-3>.
#'
#' @examples
#' data(Qesem_s)
#' dec_equit(Qesem_s$HU, Qesem_s$Group)
#'
#' @export

# function to compute equitability and its decomposition
dec_equit <- function(x, groups){
  d <- dec_shannon(x, groups)
  g <- d$groups
  S <- sum(g$S)
  return(list(equitability = equitability(x),
              within = d$within/log(S),
              between = d$between/log(S)))
}