Metadata-Version: 2.4
Name: phylometa
Version: 0.1.0
Summary: A lightweight toolkit for testing associations between phylogenetic trees and sample metadata
Author-email: Inwoo Baek <YOUR_EMAIL@example.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/YOUR_USERNAME/phylometa
Project-URL: Repository, https://github.com/YOUR_USERNAME/phylometa
Project-URL: Issues, https://github.com/YOUR_USERNAME/phylometa/issues
Keywords: phylogenetics,phylogenomics,comparative-genomics,bioinformatics,metadata
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=2.0
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: biopython>=1.81
Dynamic: license-file

# 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

```bash
pip install -e .
```

## Input formats

### Tree
- Newick format

### Metadata
- TSV or CSV
- Must include a sample ID column matching tree tip names

Example metadata:

```tsv
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

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

### Test a categorical trait

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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
