[![PyPI](https://img.shields.io/pypi/v/biobalm?style=flat-square)](https://pypi.org/project/biobalm/) 
[![Api Docs](https://img.shields.io/badge/docs-api-yellowgreen?style=flat-square)](https://jcrozum.github.io/biobalm/)
[![Continuous integration](https://img.shields.io/github/actions/workflow/status/jcrozum/biobalm/test.yml?branch=main&style=flat-square)](https://github.com/jcrozum/biobalm/actions?query=workflow%3Atest)
[![GitHub issues](https://img.shields.io/github/issues/jcrozum/biobalm?style=flat-square)](https://github.com/jcrozum/biobalm/issues) 
[![License](https://img.shields.io/github/license/jcrozum/biobalm?style=flat-square)](https://github.com/jcrozum/biobalm/blob/main/LICENSE)

# Boolean Attractor Landscape Mapper (`biobalm`)

`biobalm` is a Python library for exploring the attractor landscape of large-scale Boolean networks with hundreds or thousands of variables. It combines symbolic (BDD) and automated (ASP) reasoning to efficiently construct a *succession diagram* of a Boolean network: an inclusion-based acyclic graph of the network's trap spaces. biobalm can then use this succession diagram to accelerate attractor search and infer control strategies for target trap spaces.

 > `biobalm` is accompanied by an analysis artefact that benchmarks it against `pystablemotifs`, `mts-nfvs` and `aeon.py`. The artefact also compares the succession diagrams generated by published biological Boolean networks to random network ensembles and finds significant differences in structure. The artefact is available at [Zenodo](https://doi.org/10.5281/zenodo.13854760) and [Github](https://github.com/jcrozum/balm-analysis).

### Installation

`biobalm` is on PyPI:

```
pip install biobalm
```

The base installation should enable all core functionalities (generate succession diagrams and control strategies, find attractor seeds states and attractor sets). Optionally, you can also use `pint` during attractor identification as a static analysis step:

 - Native binaries of `pint` can be obtained [here](https://loicpauleve.name/pint/doc/#Binaries).
 
You can also install the latest version of biobalm directly from github:

```
pip install git+https://github.com/jcrozum/biobalm.git@main
```

### Referencing biobalm

`biobalm` is on [bioRxiv](https://www.biorxiv.org/content/10.1101/2024.09.30.615897v1):

```
@article {biobalm,
	author = {Trinh, Van-Giang and Park, Kyu Hyong and Pastva, Samuel and Rozum, Jordan C},
	title = {Mapping the attractor landscape of Boolean networks},
	elocation-id = {2024.09.30.615897},
	year = {2024},
	doi = {10.1101/2024.09.30.615897},
	publisher = {Cold Spring Harbor Laboratory},
	URL = {https://www.biorxiv.org/content/early/2024/10/02/2024.09.30.615897},
	eprint = {https://www.biorxiv.org/content/early/2024/10/02/2024.09.30.615897.full.pdf},
	journal = {bioRxiv}
}
```

### Using biobalm

To learn more about how biobalm functions, API documentation is available [online](https://jcrozum.github.io/biobalm/). You can also explore the analysis artefact mentioned above for more in-depth examples of biobalm usage.

