qdiv.diversity.phyl_beta

qdiv.diversity.phyl_beta(obj, *, q=1, dis=True, viewpoint='regional', use_values_in_tab=False)[source]

Compute phylogenetic pairwise beta diversity of order q.

Implements the two‑community phylogenetic Hill‑number beta framework described in Chao et al. (2014), where branch lengths are weighted by the relative abundances of all features descending from each branch.

For two samples A and B:

α_q = phylogenetic Hill number of the average of A and B γ_q = phylogenetic Hill number of the pooled community β_q = γ_q / α_q

Special case q = 1 uses the Shannon limit.

Parameters:

  • obj (MicrobiomeData-like | dict) –

    Must provide:

    • ’tab’: feature × sample abundance DataFrame

    • ’tree’: branch × columns DataFrame with:

      • ’leaves’ : iterable/list of leaf IDs under each branch

      • ’branchL’: branch length (float)

  • 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.

Returns:

Pairwise phylogenetic β-diversity (or dissimilarity) matrix.

Return type:

pandas.DataFrame

Notes

  • Requires beta2dist() to be defined elsewhere.

  • Only works for ≥ 2 samples.