babappa 1.0.0rc2

BABAPPA: neutral-model calibrated gene-level evolutionary dispersion analysis

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

pip install babappa

For development:

pip install -e .[dev]

Quick demo

babappa demo --outdir demo_run --seed 7

Minimal workflow

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.