shannon: Shannon

In ecodive: Parallel and Memory-Efficient Ecological Diversity Metrics

Shannon

Description

Shannon alpha diversity metric.

The index considers both the number of different OTUs (richness) and how evenly the observations are distributed among those OTUs (evenness).

Usage

shannon(counts, cpus = n_cpus())

Arguments

counts	An OTU abundance matrix where each column is a sample, and each row is an OTU. Any object coercible with as.matrix() can be given here, as well as phyloseq, rbiom, SummarizedExperiment, and TreeSummarizedExperiment objects.
cpus	How many parallel processing threads should be used. The default, n_cpus(), will use all logical CPU cores.

Value

A numeric vector.

Calculation

Pre-transformation: drop all OTUs with zero abundance.

In the formulas below, x is a single column (sample) from counts. p_i is the proportion of the i-th OTU in the total community.

p_{i} = \displaystyle \frac{x_i}{\sum x}

D = \displaystyle -\sum_{i = 1}^{n} p_{i}\times\ln(p_{i})

  x <- c(4, 0, 3, 2, 6)[-2]  
  p <- x / sum(x)
  -sum(p * log(p))
  #>  1.309526

References

Shannon CE, Weaver W 1949. The Mathematical Theory of Communication. University of Illinois Press.

See Also

Other alpha_diversity: chao1(), faith(), inv_simpson(), simpson()

Examples

    # Example counts matrix
    ex_counts
    
    # Shannon diversity values
    shannon(ex_counts)
    
    # Low diversity
    shannon(c(100, 1, 1, 1, 1)) # 0.22
    
    # High diversity
    shannon(c(20, 20, 20, 20, 20)) # 1.61
    
    # Low richness
    shannon(1:3) # 1.01
    
    # High richness
    shannon(1:100) # 4.42
    

ecodive documentation built on Aug. 23, 2025, 1:13 a.m.