biobagel


Namebiobagel JSON
Version 0.1.3 PyPI version JSON
download
home_pageNone
SummaryProtein Engineering via Exploration of an Energy Landscape
upload_time2025-08-11 16:44:45
maintainerNone
docs_urlNone
authorNone
requires_python>=3.11
licenseNone
keywords energy landscape monte carlo optimization protein protein design sampling
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # BAGEL: Protein Engineering via Exploration of an Energy Landscape

[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI version](https://img.shields.io/pypi/v/biobagel.svg)](https://pypi.org/project/biobagel/)
[![GitHub last commit](https://img.shields.io/github/last-commit/softnanolab/bagel.svg)](https://github.com/softnanolab/bagel/commits/main)
[![GitHub issues](https://img.shields.io/github/issues/softnanolab/bagel.svg)](https://github.com/softnanolab/bagel/issues)
[![DOI](https://zenodo.org/badge/968747892.svg)](https://doi.org/10.5281/zenodo.15808838)

BAGEL is a model-agnostic, modular, fully customizable Python framework for programmable protein design.

The package formalizes the protein design task as an optimization (sampling) over an energy landscape.

<p align="center">
  <img src="https://raw.githubusercontent.com/softnanolab/bagel/main/docs/demo.gif" alt="BAGEL demo" width="600"/>
</p>

The BAGEL package is made up of several components that need to be specified to form a protein engineering task:

| **Component**      | **Description**                                                                                      | **Examples**                                         |
|--------------------|------------------------------------------------------------------------------------------------------|------------------------------------------------------|
| `EnergyTerms`      | Define specific design constraints as terms in the energy function.                                  | `TemplateMatchEnergy`, `PLDDTEnergy`, `HydrophobicEnergy` |
| `Oracles`          | Provide information (often via ML models) to compute optimization/sampling metrics.<br>Oracles are typically wrappers around models from [boileroom](https://github.com/softnanolab/boileroom). | `ESMFold`, `ESM-2`                                   |
| `Minimizers`       | Algorithms that sample or optimize sequences to find optima or diverse variants.                     | Monte Carlo, `SimulatedTempering`, `SimulatedAnnealing` |
| `MutationProtocols`| Methods for perturbing sequences to generate new candidates.                                         | `Canonical`, `GrandCanonical`                            |

For more details, consult the available [pre-print](https://www.biorxiv.org/content/10.1101/2025.07.05.663138v1).

## Installation

### From PyPI (Recommended)

The easiest way to install BAGEL is through PyPI:

```bash
pip install biobagel
```

**Optional Extras:**

- For local protein model execution (requires GPU):
```bash
pip install biobagel[local]
```

- For development (testing, linting, documentation):
```bash
pip install biobagel[dev]
```

### From Source

If you want to install from source or contribute to development:

1. Clone the repository:

```bash
git clone https://github.com/softnanolab/bagel
```

2. Install `uv` (if not already installed):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

3. Navigate to the repository:

```bash
cd bagel
```

4. Install the environment:

```bash
uv sync
```

**Optional Extras:**

- For local protein model execution (requires GPU):
```bash
uv sync --extra local
```

- For development (testing, linting, documentation):
```bash
uv sync --extra dev
```

- For all extras:
```bash
uv sync --all-extras
```


## Usage

### With PyPI Installation

```bash
python scripts/script.py
```

### With Source Installation

```bash
uv run python scripts/script.py
```

To execute templates reproducibly from the [technical report manuscript](https://www.biorxiv.org/content/10.1101/2025.07.05.663138v1) (within statistical noise due to the nature of Monte Carlo sampling), follow release v0.1.0, also stored on Zenodo [![DOI](https://zenodo.org/badge/968747892.svg)](https://doi.org/10.5281/zenodo.15812348). Otherwise, use the most recent `biobagel` distribution.

## Oracles
One can either run Oracles locally, or remotely.

- `use_modal=True`: Run Oracles on [Modal](www.modal.com). Using the [boileroom](https://pypi.org/project/boileroom) package, running remotely is made seamless and does not require installing any dependencies. However, you need to have credits to use Modal.
- `use_modal=False`: Run Oracles locally through [boileroom](https://pypi.org/project/boileroom). You need a GPU with suitable memory requirements.

To use Modal, one needs to create an account and authenticate through:

        modal token new

You also need to set `HF_MODEL_DIR` to an accessible folder, where HuggingFace models will be stored.

### Google Colab
A prototyping, but unscalable alterantive is to run BAGEL in Google Colab, having an access to a T4 processing unit for free. See this [notebook](https://colab.research.google.com/drive/1dtX8j6t5VhSed4iiqSrjM35DyPSFE1yF?usp=sharing), which includes the installation, and the template script for [simple binder](scripts/binders/simple_binder.py).

### Examples
[Templates](scripts/) and [example applications from the manuscript](scripts/technical-report/) are included as ready-to-run Python scripts.

## Contributing

For development setup, testing, and contribution guidelines, see [Development Guide](docs/development.md).

## Citation
```
@article{lala2025bagel,
        author = {L{\'a}la, Jakub and Al-Saffar, Ayham and Angioletti-Uberti, Stefano},
        title = {BAGEL: Protein Engineering via Exploration of an Energy Landscape},
        journal = {bioRxiv},
        year = {2025},
        doi = {10.1101/2025.07.05.663138},
        url = {https://www.biorxiv.org/content/early/2025/07/08/2025.07.05.663138},
        note = {Preprint}
}
```

## Acknowledgments
BAGEL's development was lead by Jakub Lála, Ayham Al-Saffar, and Dr Stefano Angioletti-Uberti at Imperial College London.
We thank Shanil Panara, Dr Daniele Visco, Arnav Cheruku, and Harsh Agrawal for helpful discussions.
We also thank [Hie et. al 2022](https://doi.org/10.1101/2022.12.21.521526), whose work inspired the creation of this package.

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "biobagel",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.11",
    "maintainer_email": null,
    "keywords": "energy landscape, monte carlo, optimization, protein, protein design, sampling",
    "author": null,
    "author_email": "Jakub L\u00e1la <jakublala@gmail.com>, Ayham Al-Saffar <ayham.saffar@gmail.com>, Stefano Angioletti-Uberti <sangiole@imperial.ac.uk>",
    "download_url": "https://files.pythonhosted.org/packages/9a/ab/c9d26138fe4f67582076aecf45f4ecc971f503d46fb1d16f2e08e9e44557/biobagel-0.1.3.tar.gz",
    "platform": null,
    "description": "# BAGEL: Protein Engineering via Exploration of an Energy Landscape\n\n[![Python 3.12](https://img.shields.io/badge/python-3.12-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PyPI version](https://img.shields.io/pypi/v/biobagel.svg)](https://pypi.org/project/biobagel/)\n[![GitHub last commit](https://img.shields.io/github/last-commit/softnanolab/bagel.svg)](https://github.com/softnanolab/bagel/commits/main)\n[![GitHub issues](https://img.shields.io/github/issues/softnanolab/bagel.svg)](https://github.com/softnanolab/bagel/issues)\n[![DOI](https://zenodo.org/badge/968747892.svg)](https://doi.org/10.5281/zenodo.15808838)\n\nBAGEL is a model-agnostic, modular, fully customizable Python framework for programmable protein design.\n\nThe package formalizes the protein design task as an optimization (sampling) over an energy landscape.\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/softnanolab/bagel/main/docs/demo.gif\" alt=\"BAGEL demo\" width=\"600\"/>\n</p>\n\nThe BAGEL package is made up of several components that need to be specified to form a protein engineering task:\n\n| **Component**      | **Description**                                                                                      | **Examples**                                         |\n|--------------------|------------------------------------------------------------------------------------------------------|------------------------------------------------------|\n| `EnergyTerms`      | Define specific design constraints as terms in the energy function.                                  | `TemplateMatchEnergy`, `PLDDTEnergy`, `HydrophobicEnergy` |\n| `Oracles`          | Provide information (often via ML models) to compute optimization/sampling metrics.<br>Oracles are typically wrappers around models from [boileroom](https://github.com/softnanolab/boileroom). | `ESMFold`, `ESM-2`                                   |\n| `Minimizers`       | Algorithms that sample or optimize sequences to find optima or diverse variants.                     | Monte Carlo, `SimulatedTempering`, `SimulatedAnnealing` |\n| `MutationProtocols`| Methods for perturbing sequences to generate new candidates.                                         | `Canonical`, `GrandCanonical`                            |\n\nFor more details, consult the available [pre-print](https://www.biorxiv.org/content/10.1101/2025.07.05.663138v1).\n\n## Installation\n\n### From PyPI (Recommended)\n\nThe easiest way to install BAGEL is through PyPI:\n\n```bash\npip install biobagel\n```\n\n**Optional Extras:**\n\n- For local protein model execution (requires GPU):\n```bash\npip install biobagel[local]\n```\n\n- For development (testing, linting, documentation):\n```bash\npip install biobagel[dev]\n```\n\n### From Source\n\nIf you want to install from source or contribute to development:\n\n1. Clone the repository:\n\n```bash\ngit clone https://github.com/softnanolab/bagel\n```\n\n2. Install `uv` (if not already installed):\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n3. Navigate to the repository:\n\n```bash\ncd bagel\n```\n\n4. Install the environment:\n\n```bash\nuv sync\n```\n\n**Optional Extras:**\n\n- For local protein model execution (requires GPU):\n```bash\nuv sync --extra local\n```\n\n- For development (testing, linting, documentation):\n```bash\nuv sync --extra dev\n```\n\n- For all extras:\n```bash\nuv sync --all-extras\n```\n\n\n## Usage\n\n### With PyPI Installation\n\n```bash\npython scripts/script.py\n```\n\n### With Source Installation\n\n```bash\nuv run python scripts/script.py\n```\n\nTo execute templates reproducibly from the [technical report manuscript](https://www.biorxiv.org/content/10.1101/2025.07.05.663138v1) (within statistical noise due to the nature of Monte Carlo sampling), follow release v0.1.0, also stored on Zenodo [![DOI](https://zenodo.org/badge/968747892.svg)](https://doi.org/10.5281/zenodo.15812348). Otherwise, use the most recent `biobagel` distribution.\n\n## Oracles\nOne can either run Oracles locally, or remotely.\n\n- `use_modal=True`: Run Oracles on [Modal](www.modal.com). Using the [boileroom](https://pypi.org/project/boileroom) package, running remotely is made seamless and does not require installing any dependencies. However, you need to have credits to use Modal.\n- `use_modal=False`: Run Oracles locally through [boileroom](https://pypi.org/project/boileroom). You need a GPU with suitable memory requirements.\n\nTo use Modal, one needs to create an account and authenticate through:\n\n        modal token new\n\nYou also need to set `HF_MODEL_DIR` to an accessible folder, where HuggingFace models will be stored.\n\n### Google Colab\nA prototyping, but unscalable alterantive is to run BAGEL in Google Colab, having an access to a T4 processing unit for free. See this [notebook](https://colab.research.google.com/drive/1dtX8j6t5VhSed4iiqSrjM35DyPSFE1yF?usp=sharing), which includes the installation, and the template script for [simple binder](scripts/binders/simple_binder.py).\n\n### Examples\n[Templates](scripts/) and [example applications from the manuscript](scripts/technical-report/) are included as ready-to-run Python scripts.\n\n## Contributing\n\nFor development setup, testing, and contribution guidelines, see [Development Guide](docs/development.md).\n\n## Citation\n```\n@article{lala2025bagel,\n        author = {L{\\'a}la, Jakub and Al-Saffar, Ayham and Angioletti-Uberti, Stefano},\n        title = {BAGEL: Protein Engineering via Exploration of an Energy Landscape},\n        journal = {bioRxiv},\n        year = {2025},\n        doi = {10.1101/2025.07.05.663138},\n        url = {https://www.biorxiv.org/content/early/2025/07/08/2025.07.05.663138},\n        note = {Preprint}\n}\n```\n\n## Acknowledgments\nBAGEL's development was lead by Jakub L\u00e1la, Ayham Al-Saffar, and Dr Stefano Angioletti-Uberti at Imperial College London.\nWe thank Shanil Panara, Dr Daniele Visco, Arnav Cheruku, and Harsh Agrawal for helpful discussions.\nWe also thank [Hie et. al 2022](https://doi.org/10.1101/2022.12.21.521526), whose work inspired the creation of this package.\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "Protein Engineering via Exploration of an Energy Landscape",
    "version": "0.1.3",
    "project_urls": {
        "Issues": "https://github.com/softnanolab/bagel/issues",
        "Repository": "https://github.com/softnanolab/bagel.git"
    },
    "split_keywords": [
        "energy landscape",
        " monte carlo",
        " optimization",
        " protein",
        " protein design",
        " sampling"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "4226f5b39b20aaff8154ddcb53359cb499fda07d5a9404aa2b0f7a18b50fc692",
                "md5": "fab0e0833b8096da48b651071742ee8c",
                "sha256": "c467cef13a04a195353232432b8b8372d35024e1625dd130d052b4a972a1b4f7"
            },
            "downloads": -1,
            "filename": "biobagel-0.1.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "fab0e0833b8096da48b651071742ee8c",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.11",
            "size": 39889,
            "upload_time": "2025-08-11T16:44:43",
            "upload_time_iso_8601": "2025-08-11T16:44:43.318208Z",
            "url": "https://files.pythonhosted.org/packages/42/26/f5b39b20aaff8154ddcb53359cb499fda07d5a9404aa2b0f7a18b50fc692/biobagel-0.1.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "9aabc9d26138fe4f67582076aecf45f4ecc971f503d46fb1d16f2e08e9e44557",
                "md5": "39dd0b7497459721721d501565ead429",
                "sha256": "96904f783f3334bda51a8088f1d9a2a2b2c8a068f49528e9ddb7a504e0b77b77"
            },
            "downloads": -1,
            "filename": "biobagel-0.1.3.tar.gz",
            "has_sig": false,
            "md5_digest": "39dd0b7497459721721d501565ead429",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.11",
            "size": 33839187,
            "upload_time": "2025-08-11T16:44:45",
            "upload_time_iso_8601": "2025-08-11T16:44:45.621399Z",
            "url": "https://files.pythonhosted.org/packages/9a/ab/c9d26138fe4f67582076aecf45f4ecc971f503d46fb1d16f2e08e9e44557/biobagel-0.1.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-08-11 16:44:45",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "softnanolab",
    "github_project": "bagel",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "biobagel"
}
        
Elapsed time: 0.54062s