qdiv.diversity.func_beta

qdiv.diversity.func_beta(tab, distmat, *, q=1, dis=True, viewpoint='regional', use_values_in_tab=False, use_tqdm=True)[source]

Compute functional pairwise beta diversity of order q.

Implements the two‑community functional Hill‑number beta framework based on local functional overlaps as in Chao et al. (2014). Functional diversity is derived from pairwise trait distances between ASVs and their abundances.

For each pair of samples (A, B), the method computes:

  • Dg : functional Hill number for the pooled community (gamma)

  • Da : functional Hill number for the “average” community (alpha)

  • beta = Dg / Da

For q = 1, the Shannon-type limit is used; for q ≠ 1, the general Hill-number form is used.

Parameters:

  • tab (DataFrame | MicrobiomeData-like | dict) – Abundance table (features x samples) or convertible structure.

  • distmat (pandas.DataFrame) – Functional distance matrix (ASVs × ASVs), symmetric and indexed by the same ASVs as tab.

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

  • dis (bool, default=True) – If True, convert β to a dissimilarity using beta2dist.

  • viewpoint ({'local', 'regional'}, default='regional') – Viewpoint for converting β to dissimilarity.

  • use_values_in_tab (bool, default=False) – If False, convert abundances to relative abundances. If True, assume tab already contains relative abundances.

  • use_tqdm (bool, default=True) – Use tqdm for progress bars.

Returns:

Pairwise functional dissimilarity matrix (if dis=True) or squared functional beta (β²) matrix (if dis=False).

Return type:

pandas.DataFrame

Notes

  • Only works for ≥ 2 samples.