Metadata-Version: 2.3
Name: bella-companion
Version: 0.1.40
Summary: Companion tool with experiments and evaluation for Bayesian Evolutionary Layered Learning Architectures (BELLA) BEAST2 package.
Author: gabriele-marino
Author-email: gabriele-marino <gabmarino.8601@gmail.com>
Requires-Dist: arviz==0.22.0
Requires-Dist: beartype>=0.22.9
Requires-Dist: jaxtyping>=0.3.7
Requires-Dist: kaleido>=1.2.0
Requires-Dist: phylogenie>=3.10.0
Requires-Dist: plotly>=6.5.0
Requires-Dist: seaborn>=0.13.2
Requires-Dist: shap>=0.49.1
Requires-Dist: statsmodels>=0.14.6
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# BELLA-Companion

### ⚠️🚧🚨 The documentation for this repository is still under development.

## Installation

BELLA-Companion is a Python package, and can be installed via pip:

```bash
pip install bella-companion
```

To reproduce BEAST analyses, you will need to have [BEAST2](https://www.beast2.org/) as well as [SLURM](https://slurm.schedmd.com/) installed and properly configured on your system, as well as the following BEAST2 packages:
- [BDMM-Prime](https://tgvaughan.github.io/BDMM-Prime/);
- [Feast](https://tgvaughan.github.io/feast/);
- [BELLA](https://gabriele-marino.github.io/BELLA/)

## CLI

The CLI entrypoint is `bella` (see `src/bella_companion/cli.py`). It requires an `.env` file to be present in the current working directory defining the settings for the analyses to be run.

Basic usage is as follows:

```bash
bella <command> <subcommand> <...>
```

Where commands and subcommands are as follows:

```text
sim
  generate            Generate synthetic simulation datasets.
  run                 Run BEAST2 analyses on simulated datasets.
  summarize           Summarize BEAST2 log outputs for simulated datasets.
  metrics             Compute and print metrics for simulated datasets.
  plot
    all               Generate plots for all simulation scenarios.
    epi-multitype     Generate plots for the epi-multitype scenario.
    epi-skyline       Generate plots for the epi-skyline scenarios.
    fbd-2traits       Generate plots for the fbd-2traits scenario.
    fbd-no-traits     Generate plots for the fbd-no-traits scenarios.
    scenarios         Generate scenario overview plots.

platyrrhine
  run                 Run BEAST2 analyses on empirical platyrrhine datasets.
  summarize           Summarize BEAST2 log outputs for empirical datasets.
  plot
    all               Generate plots for all platyrrhine datasets.
    estimates         Generate parameter estimate plots.
    trees             Generate tree-mapped parameter estimate plots.
    shap              Generate SHAP plots.

eucovid
  run                 Run BEAST2 analyses on empirical eucovid datasets.
  summarize           Summarize BEAST2 log outputs for empirical datasets.
  plot
    all                       Generate plots for all eucovid datasets.
    likelihood                Generate likelihood distribution plots.
    sankey                    Generate sankey plots.
    trees                     Generate tree plots.
    flights-and-populations   Plots for the flights and populations scenario.
    flights-over-populations  Plots for the flights over populations scenario.
```