OmicVerse Microbiome — Phylogenetic Diversity

Goal

Take a 16S amplicon AnnData (samples × ASVs, with ASV centroid sequences in var) plus the ASV centroid FASTA from the amplicon pipeline, build a per-cohort phylogenetic tree (MAFFT alignment → FastTree under GTR+Γ), attach it to adata.uns['tree'], and run the phylogenetically-aware diversity stack: Faith's PD (alpha) and unweighted / weighted UniFrac (beta). Compare against non-phylogenetic baselines (Bray-Curtis) to confirm that phylogeny adds signal — or that it doesn't.

This skill assumes the upstream omicverse-microbiome-16s-amplicon-dada2 skill has already produced the AnnData and the ASV FASTA (the FASTA is the nochim['asv'] output of the stepwise pipeline, or is regenerable from the saved AnnData).

Quick Workflow

1. Load the saved AnnData; identify the ASV FASTA from the workdir.
2. Build the tree: tree = ov.alignment.build_phylogeny(asvs_fasta, workdir, mafft_threads=8, fasttree_threads=4). Returns a dict with aligned, tree, newick paths/strings.
3. Attach to AnnData: ov.micro.attach_tree(adata, newick=tree['newick']). Stores at adata.uns['tree']; tip-name validation runs by default.
4. Faith PD (alpha): include 'faith_pd' in Alpha(adata).run(metrics=[...]). Result column lands in adata.obs['faith_pd'].
5. UniFrac (beta): Beta(adata).run(metric='unweighted_unifrac') and metric='weighted_unifrac'. Distance matrices land in adata.obsp[<metric>]. Both call out to the unifrac package which expects rooted newick (FastTree midpoint-roots automatically).
6. Compare with Bray-Curtis: run all three on the same AnnData; PCoA on each; visually compare PC1/PC2 cluster separation. UniFrac usually agrees with Bray-Curtis on cohorts dominated by abundance shifts; it diverges when the which taxa shifted matters more than how much.
7. Save the now-tree-augmented AnnData (adata.write_h5ad(...)).

Interface Summary