Diversity

The diversity module provides functions for calculating various diversity indices.

General Diversity Function

nuee.diversity.diversity(x: ndarray | DataFrame, index: str = 'shannon', groups: ndarray | Series | None = None, base: float = 2.718281828459045) → float | ndarray | Series

Calculate diversity indices for community data.

This function provides a unified interface for calculating various diversity indices commonly used in ecology. It can calculate diversity for individual samples or for pooled groups.

Parameters:

• x (np.ndarray or pd.DataFrame) – Community data matrix with samples in rows and species in columns. Values should be non-negative abundances or counts. Can also be a 1D array for a single sample.

• index ({'shannon', 'simpson', 'invsimpson', 'fisher'}, default='shannon') – Diversity index to calculate: - ‘shannon’: Shannon entropy H’ = -sum(p_i * log(p_i)) - ‘simpson’: Gini-Simpson index 1 - sum(p_i^2) - ‘invsimpson’: Inverse Simpson 1 / sum(p_i^2) - ‘fisher’: Fisher’s alpha

• groups (np.ndarray or pd.Series, optional) – Grouping factor for calculating pooled diversities. If provided, samples are pooled within each group before calculating diversity.

• base (float, default=e) – Base of logarithm for Shannon index. Common choices: - e (natural log): nats - 2: bits - 10: dits

Returns:

Diversity values for each sample (or group if groups is provided). If input is a DataFrame, returns a pd.Series with sample/group names.

Return type:

float, np.ndarray, or pd.Series

Notes

Shannon diversity (H’) measures both richness and evenness: - Higher values indicate more diverse communities - Ranges from 0 (single species) to log(S) where S is species richness - Most common diversity index in ecology

Simpson’s index measures dominance: - We report the Gini-Simpson form (1 - sum(p_i^2)), matching vegan::diversity - Larger values indicate greater diversity - The inverse Simpson (1 / sum(p_i^2)) is available via index='invsimpson'

Fisher’s alpha assumes a log-series distribution: - Useful for abundance data - Less sensitive to sample size than richness - Can be slow for large datasets

Examples

Calculate Shannon diversity:

>>> import nuee
>>> species = nuee.datasets.varespec()
>>> div = nuee.diversity(species, index="shannon")
>>> print(f"Mean diversity: {div.mean():.3f}")
Mean diversity: 1.754

Calculate Simpson diversity:

>>> div_simp = nuee.diversity(species, index="simpson")

Calculate diversity for grouped samples:

>>> import numpy as np
>>> groups = np.array(['A', 'A', 'B', 'B', 'C', 'C'])
>>> div_grouped = nuee.diversity(species[:6], index="shannon", groups=groups)

Use different logarithm bases:

>>> div_bits = nuee.diversity(species, index="shannon", base=2)
>>> print("Diversity in bits:", div_bits.mean())
Diversity in bits: 2.5300454694165375

See also

shannon

Shannon diversity (convenience function)

simpson

Simpson diversity (convenience function)

fisher_alpha

Fisher’s alpha (convenience function)

renyi

Renyi entropy for multiple scales

specnumber

Species richness

References

[1]

Shannon, C.E. (1948). A mathematical theory of communication. Bell System Technical Journal 27, 379-423.

[2]

Simpson, E.H. (1949). Measurement of diversity. Nature 163, 688.

[3]

Fisher, R.A., Corbet, A.S., Williams, C.B. (1943). The relation between the number of species and the number of individuals in a random sample of an animal population. Journal of Animal Ecology 12, 42-58.

Diversity Indices

Shannon Diversity

nuee.diversity.shannon(x: ndarray | DataFrame, base: float = 2.718281828459045) → DiversityResult

Calculate Shannon diversity index.

H = -sum(p_i * log(p_i))

Parameters:

• x – Community data matrix or vector

• base – Base of logarithm

Returns:

DiversityResult object with automatic plotting

Simpson Diversity

nuee.diversity.simpson(x: ndarray | DataFrame) → DiversityResult

Calculate Gini-Simpson diversity (1 - sum(p_i^2)).

Parameters:

x – Community data matrix or vector

Returns:

DiversityResult object with automatic plotting

Fisher’s Alpha

nuee.diversity.fisher_alpha(x: ndarray | DataFrame) → DiversityResult

Calculate Fisher’s alpha diversity index.

Parameters:

x – Community data matrix or vector

Returns:

DiversityResult object with automatic plotting

Species Richness

nuee.diversity.specnumber(x: ndarray | DataFrame, groups: ndarray | Series | None = None) → DiversityResult

Calculate species richness (number of species).

Parameters:

• x – Community data matrix or vector

• groups – Grouping factor for pooled richness

Returns:

DiversityResult object with automatic plotting

Evenness

nuee.diversity.evenness(x: ndarray | DataFrame, method: str = 'pielou') → DiversityResult

Calculate evenness indices.

Parameters:

• x – Community data matrix or vector

• method – Evenness method (“pielou”, “simpson”, “evar”)

Returns:

DiversityResult object with automatic plotting

Renyi Entropy

nuee.diversity.renyi(x: ndarray | DataFrame, scales: float | List[float] = [0, 1, 2, inf], hill: bool = False) → ndarray | DataFrame

Calculate Renyi entropy or Hill numbers.

Parameters:

• x – Community data matrix or vector

• scales – Scale parameters (alpha values)

• hill – Whether to return Hill numbers instead of Renyi entropy

Returns:

Renyi entropy or Hill numbers for each scale

Rarefaction

nuee.diversity.rarefy(x: ndarray | DataFrame, sample: int) → ndarray | Series

Rarefy species richness to a standard sample size.

Parameters:

• x – Community data matrix

• sample – Sample size for rarefaction

Returns:

Rarefied species richness

nuee.diversity.rarecurve(x: ndarray | DataFrame, step: int = 1, sample: int | None = None) → dict

Calculate rarefaction curves.

Parameters:

• x – Community data matrix

• step – Step size for rarefaction

• sample – Maximum sample size

Returns:

Dictionary with rarefaction curves

Base Classes

class nuee.diversity.DiversityResult(values: ndarray | Series, index_name: str = 'diversity', sample_names: list | None = None)

Bases: object

Container for diversity analysis results with automatic plotting.

__init__(values: ndarray | Series, index_name: str = 'diversity', sample_names: list | None = None)

__getitem__(key)

Allow indexing like an array.

__len__()

Return length.

mean()

Calculate mean diversity.

std()

Calculate standard deviation.

summary()

Return summary statistics.

plot(kind='hist', **kwargs)

Plot the diversity values.

Parameters:

• kind – Plot type (“hist”, “box”, “bar”, “violin”)

• **kwargs – Additional plotting arguments

Returns:

matplotlib Figure object