phylometa 0.1.0

A lightweight toolkit for testing associations between phylogenetic trees and sample metadata

phylometa

phylometa is a lightweight Python toolkit for testing associations between phylogenetic trees and sample metadata.

It is designed for comparative genomics and phylogenomics workflows where users already have a tree and want to test whether categorical or continuous metadata show phylogenetic structure.

Features

• Check consistency between tree tips and metadata IDs
• Test phylogenetic clustering of categorical traits by permutation
• Test phylogenetic association of continuous traits using trait-distance vs patristic-distance correlation
• Run batch categorical tests across multiple traits
• Identify clades enriched for a categorical metadata value
• Plot metadata strips alongside a phylogenetic tree

Installation

pip install -e .

Input formats

Tree

• Newick format

Metadata

• TSV or CSV
• Must include a sample ID column matching tree tip names

Example metadata:

strain	habitat	antarctica	ros_burden	region
A	soil	no	11	Asia
B	soil	no	13	Asia
C	ice	yes	22	Antarctica
D	lake	no	14	Europe

Commands

Check tree and metadata compatibility

phylometa check \
  --tree examples/demo_tree.nwk \
  --meta examples/demo_meta.tsv \
  --id-column strain

Test a categorical trait

phylometa test-categorical \
  --tree examples/demo_tree.nwk \
  --meta examples/demo_meta.tsv \
  --id-column strain \
  --trait habitat \
  --n-perm 1000 \
  --out categorical_results.tsv

Test multiple categorical traits

phylometa test-categorical-batch \
  --tree examples/demo_tree.nwk \
  --meta examples/demo_meta.tsv \
  --id-column strain \
  --traits habitat,antarctica,region \
  --n-perm 1000 \
  --out batch_results.tsv

Test a continuous trait

phylometa test-continuous \
  --tree examples/demo_tree.nwk \
  --meta examples/demo_meta.tsv \
  --id-column strain \
  --trait ros_burden \
  --n-perm 1000 \
  --out continuous_results.tsv

Test clade enrichment

phylometa clade-enrichment \
  --tree examples/demo_tree.nwk \
  --meta examples/demo_meta.tsv \
  --id-column strain \
  --trait antarctica \
  --value yes \
  --min-clade-size 2 \
  --out enrichment_results.tsv

Plot metadata strips on a tree

phylometa plot \
  --tree examples/demo_tree.nwk \
  --meta examples/demo_meta.tsv \
  --id-column strain \
  --traits habitat,antarctica,ros_burden \
  --out phylometa_plot.pdf

Output notes

• test-categorical reports within-group distance, between-group distance, and permutation p-values
• test-categorical-batch additionally reports FDR-adjusted q-values
• clade-enrichment reports Fisher’s exact test p-values and FDR-adjusted q-values
• Missing metadata values are ignored in statistical tests and shown in gray in plots

Current scope

phylometa currently focuses on lightweight downstream association testing and visualization. It does not infer phylogenetic trees or perform ancestral-state reconstruction.

Planned improvements

• Better tree/strip alignment for large trees
• More advanced phylogenetic signal metrics
• HTML report generation
• Multiple-testing correction across mixed test types
• Publication-style figure themes

License

MIT