# BABAPPA

BABAPPA is a Python package for **gene-level detection of excess evolutionary dispersion relative to an explicit neutral model**.

It implements a conservative, reproducible workflow around codon alignments and phylogenetic trees with explicit null-model calibration and exact Monte Carlo rank p-values.

## What BABAPPA does

- Computes gene-level dispersion in a bounded codon representation space.
- Fits a frozen neutral reference model from simulated null data.
- Scores observed genes against the frozen null model.
- Computes exact one-sided Monte Carlo p-values and multiple-testing adjusted q-values.
- Produces QC summaries, site-level contributions, plots, and an HTML report.
- Supports sensitivity analysis over key null and smoothing settings.

## What BABAPPA does not do

- BABAPPA does **not** directly infer positive selection at specific sites or branches.
- BABAPPA is **not** a replacement for codeml/HyPhy; it is complementary for detecting gene-level deviation from a configured neutral model.
- Significant BABAPPA results may reflect adaptation, relaxation, composition/alignment/tree issues, or other null-model deviations.

## Installation

```bash
pip install babappa
```

For development:

```bash
pip install -e .[dev]
```

## Quick demo

```bash
babappa demo --outdir demo_run --seed 7
```

## Minimal workflow

```bash
babappa validate \
  --alignment examples/small_demo/geneA.fasta \
  --tree examples/small_demo/tree.nwk \
  --outdir run/validate

babappa fit-null \
  --alignment examples/small_demo/geneA.fasta \
  --tree examples/small_demo/tree.nwk \
  --outdir run/fit_null \
  --seed 7

babappa score \
  --alignment examples/small_demo/geneA.fasta \
  --tree examples/small_demo/tree.nwk \
  --bundle run/fit_null/null_bundle.json \
  --outdir run/score \
  --seed 7

babappa adjust --scores run/score/scores.tsv --outdir run/adjust
babappa report --scores run/adjust/scores_adjusted.tsv --outdir run/report
```

## Output interpretation

A significant gene indicates that observed dispersion exceeds null expectation under the configured neutral model.
Interpret cautiously when QC/sensitivity flags indicate high gaps, ambiguity, low taxon coverage, branch-length imbalance, or unstable sensitivity results.

## Citation

If you use BABAPPA, cite the BABAPPA manuscript and this software release.

## Support

Please open issues on GitHub with command, config, log, and manifest files.
