Metadata-Version: 2.4
Name: babappa
Version: 1.0.0rc2
Summary: BABAPPA: neutral-model calibrated gene-level evolutionary dispersion analysis
Author: BABAPPA Contributors
License-Expression: MIT
Project-URL: Homepage, https://github.com/sinhakrishnendu/babappa
Project-URL: Documentation, https://github.com/sinhakrishnendu/babappa/tree/main/docs
Project-URL: Issues, https://github.com/sinhakrishnendu/babappa/issues
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: matplotlib>=3.7
Requires-Dist: PyYAML>=6.0
Requires-Dist: jinja2>=3.1
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Provides-Extra: comparators
Requires-Dist: biopython>=1.84; extra == "comparators"
Dynamic: license-file

# 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.
