qdiv.diversity.evenness

qdiv.diversity.evenness(obj, distmat=None, *, q=1, div_type='naive', index='pielou', perspective='samples', use_values_in_tab=False)[source]

Compute evenness measures from Chao & Ricotta (2019, Ecology 100:e02852), with optional support for Pielou’s classical evenness index.

Supports:

  • naive (taxonomic) evenness

  • phylogenetic evenness

  • functional evenness

Supported evenness indices:

  • CR1 (regional evenness)

  • CR2 (local evenness)

  • CR3

  • CR4

  • CR5

  • pielou (Pielou’s J; defined only for q = 1)

Parameters:

  • obj (DataFrame | MicrobiomeData-like | dict) – Including abundance table (features × samples) and optionally tree (pandas.DataFrame, required if divType=’phyl’)

  • distmat (pandas.DataFrame, optional) – Required if divType=’func’. Functional distance matrix.

  • q (float, default=1) – Diversity order.

  • div_type ({'naive', 'phyl', 'func'}) – Type of diversity measure used to compute D.

  • index ({'CR1','CR2','CR3','CR4','CR5','local','regional','pielou'}) – Evenness index to compute.

  • perspective ({'samples','taxa'}) – Whether to compute evenness across samples (columns) or across taxa/branches (rows).

  • use_values_in_tab (bool, default=False) – If False, convert abundances to relative abundances.

Returns:

Evenness values indexed by sample or taxon.

Return type:

pandas.Series

Notes

  • CR1 = regional evenness

  • CR2 = local evenness

  • CR3–CR5 are alternative evenness formulations from Chao & Ricotta (2019)

  • Pielou’s index is included for convenience and corresponds to:

    J = H’ / ln(S) = ln(D₁) / ln(S)

    where D₁ is the Hill number of order q = 1.