Metadata-Version: 2.5
Name: biotrainer
Version: 2.1.0
Summary: Biological prediction models made simple.
Project-URL: Issues, https://github.com/sacdallago/biotrainer/issues
Project-URL: Repository, https://github.com/sacdallago/biotrainer
Author-email: Sebastian Franz <sebastian.franz@tum.de>, Christian Dallago <christian.dallago@tum.de>, Joaquin Gomez Sanchez <joaquin.gomez@tum.de>, Michael Heinzinger <mheinzinger@rostlab.org>
License: MIT
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: <3.14,>=3.12
Requires-Dist: aaanalysis<1.2.0,>=1.1.0
Requires-Dist: accelerate<2.0.0,>=1.15.0
Requires-Dist: appdirs>=1.4.4
Requires-Dist: biotrainer-core>=2.0.0
Requires-Dist: blosum<2.3.0,>=2.2.0
Requires-Dist: cyclopts<4.23.0,>=4.22.0
Requires-Dist: datasets<6.0.0,>=5.0.1
Requires-Dist: einops<0.9.0,>=0.8.2
Requires-Dist: gpytorch<2.0,>=1.15.2
Requires-Dist: h5py<4.0.0,>=3.15.0
Requires-Dist: junban<1.1.0,>=1.0.3
Requires-Dist: llvmlite<0.52.0,>=0.49.0
Requires-Dist: numpy<2.6.0,>=2.4.1
Requires-Dist: onnx<1.25.0,>=1.23.0
Requires-Dist: onnxscript<0.8.0,>=0.7.0
Requires-Dist: peft<0.23.0,>=0.21.0
Requires-Dist: pydantic<2.15.0,>=2.12.0
Requires-Dist: ruamel-yaml<0.18.0,>=0.17.40
Requires-Dist: safetensors>=0.4.4
Requires-Dist: scikit-learn>=1.5.1
Requires-Dist: scipy<1.20.0,>=1.18.1
Requires-Dist: sentencepiece>=0.2.0
Requires-Dist: tensorboard<2.22.0,>=2.20.0
Requires-Dist: torch<3.0.0,>=2.11.0
Requires-Dist: torchmetrics>=1.9.0
Requires-Dist: tqdm<5.0.0,>=4.67.3
Requires-Dist: transformers<5.20.0,>=5.17.0
Requires-Dist: umap-learn<0.6.0,>=0.5.7
Provides-Extra: autoeval-frontend
Requires-Dist: altair<6.5.0,>=6.3.0; extra == 'autoeval-frontend'
Requires-Dist: streamlit<1.65.0,>=1.64.0; extra == 'autoeval-frontend'
Provides-Extra: dev
Requires-Dist: build<2.0.0,>=1.5.0; extra == 'dev'
Requires-Dist: pip-audit<2.11.0,>=2.10.0; extra == 'dev'
Requires-Dist: pytest<9.2.0,>=9.1.1; extra == 'dev'
Provides-Extra: jupyter
Requires-Dist: jupyter<1.2.0,>=1.1.1; extra == 'jupyter'
Requires-Dist: notebook<7.7.0,>=7.4.0; extra == 'jupyter'
Provides-Extra: onnx-cpu
Requires-Dist: onnxruntime<1.30.0,>=1.25.0; extra == 'onnx-cpu'
Provides-Extra: onnx-gpu
Requires-Dist: onnxruntime<1.30.0,>=1.25.0; extra == 'onnx-gpu'
Provides-Extra: onnx-mac
Requires-Dist: onnxruntime<1.30.0,>=1.25.0; extra == 'onnx-mac'
Description-Content-Type: text/markdown

# Biotrainer

[![License](https://img.shields.io/github/license/sacdallago/biotrainer)](https://github.com/sacdallago/biotrainer/blob/main/LICENSE)
[![Documentation](https://img.shields.io/badge/docs-biocentral-blue)](https://docs.biocentral.cloud/docs/biotrainer)
[![GitHub release (latest by date)](https://img.shields.io/github/v/release/sacdallago/biotrainer)](https://github.com/sacdallago/biotrainer/releases)

<p align="center">
  <img width="25%" height="20%" alt="biotrainer logo" src="biotrainer_logo.svg" />
<br />
Biological prediction models made simple. 
</p>

## Overview

*Biotrainer* is an open-source framework that simplifies machine learning model development for protein analysis.
It provides the following modules:

- **Training**: Easy to use training and inference pipelines for protein feature prediction
- **Embedding**: Built-in support for protein language models (ProtT5, ESM-2, ESM-C, ...) and baselines (blosum62,
  one_hot_encoding, ...)
- **BioEngineer**: Zero-shot predictions and mutation generation of protein sequences
- **AutoEval**: Automated evaluation of protein language models on curated downstream tasks

## Quick Start

### 1. Installation

Install using pip:

```shell
pip install biotrainer
```

Manual installation using [uv](https://github.com/astral-sh/uv):

```shell
# First, install uv if you haven't already:
pip install uv

# Create and activate a virtual environment
uv venv
source .venv/bin/activate  # On Unix/macOS
# OR
.venv\Scripts\activate  # On Windows

# Basic installation
uv sync

# Installation with extras (jupyter, onnx, tensorboard)
uv sync --all-extras

# For Windows users with CUDA support:
# Visit https://pytorch.org/get-started/locally/ and follow GPU-specific installation, e.g.:
pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
```

### 2. Basic Usage

```shell
# Training
biotrainer train --config examples/training/sequence_to_class/config.yml

# Inference after Training
python3
>>> from biotrainer.training import BiotrainerModel
>>> model = BiotrainerModel.from_training_result("output/out.yml")
>>> predictions = model.predict("SEQUENCE")

# AutoEval
autoeval_report = (AutoEval(embedder_name="facebook/esm2_t6_8M_UR50D", development_mode=True).
                    pbc_supervised_contact().
                    pbc_zeroshot_contact().
                    pbc_supervised().
                    pgym(zero_shot_method=ZeroShotMethod.MASKED_MARGINALS).
                    run())
autoeval_report.summary(development_mode=False)
```

*Note: [Biocentral](https://pypi.org/project/biocentral/) provides a more powerful CLI
that uses biotrainer for local or remote model training. The biotrainer CLI is marked as deprecated and might be removed
in a future release.*

### 3. Quick Start Datasets

- **Subcellular Localization Prediction**
    - *Protocol*: `sequence_to_class`/`residues_to_class`
    - [Citations and Download](https://github.com/Rostlab/pbc/tree/main/supervised/scl)
- **Secondary Structure Prediction**
    - *Protocol*: `residue_to_class`
    - [Citations and Download](https://github.com/Rostlab/pbc/tree/main/supervised/secondary_structure)

## Features

### Supported Training Protocols

- **Residue-level classification** (`residue_to_class`)
- **Residue-level regression** (`residue_to_value`) *[BETA]*
- **Sequence-level classification** (`sequence_to_class`)
- **Sequence-level regression** (`sequence_to_value`)
- **Residues-level classification** (`residues_to_class`, like sequence_to_class with per-residue embeddings)
- **Residues-level regression** (`residues_to_value`, like sequence_to_value with per-residue embeddings)

## Autoeval

The biotrainer `autoeval` module allows automatical evaluation of a protein language model on downstream tasks.
You can find public results (*wip!*) on the [autoeval dashboard](https://autoeval.biocentral.cloud) and compare them
to your own. Learn more in the [autoeval examples](examples/autoeval).

## Documentation

### Tutorials

- [First Steps Guide](https://docs.biocentral.cloud/docs/biotrainer/training_first_steps)
- [Interactive Training Tutorial](examples/training/biotrainer_training_tutorial.ipynb)
- [Config Options Overview](https://docs.biocentral.cloud/docs/biotrainer/training_config_file_options_overview)
- [Biocentral Web Interface (Biotrainer Frontend)](https://app.biocentral.cloud/)

### Detailed Guides

- [Data Standards](https://docs.biocentral.cloud/docs/biotrainer/training_data_standardization)
- [Configuration Options](https://docs.biocentral.cloud/docs/biotrainer/training_config_file_options)
- [Troubleshooting](https://docs.biocentral.cloud/docs/biotrainer/troubleshooting)

## Example Training Configuration

```yaml
protocol: residue_to_class
input_file: input.fasta
model_choice: CNN
optimizer_choice: adam
learning_rate: 1e-3
loss_choice: cross_entropy_loss
use_class_weights: True
num_epochs: 200
batch_size: 128
embedder_name: Rostlab/prot_t5_xl_uniref50
```

## Docker Support

```shell
# Run using pre-built image
docker run --gpus all --rm \
    -v "$(pwd)/examples/docker":/mnt \
    -u $(id -u ${USER}):$(id -g ${USER}) \
    ghcr.io/sacdallago/biotrainer:latest /mnt/config.yml
```

More information on running docker with gpus:
[Nvidia container toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)

## Getting Help

- Check our [Troubleshooting Guide](docs/troubleshooting.md)
- [Create an issue](https://github.com/sacdallago/biotrainer/issues/new)
- Visit [biocentral.cloud](https://biocentral.cloud/docs/biotrainer/config_file_options)

## Citation

```bibtex
@inproceedings{
sanchez2022standards,
title={Standards, tooling and benchmarks to probe representation learning on proteins},
author={Joaquin Gomez Sanchez and Sebastian Franz and Michael Heinzinger and Burkhard Rost and Christian Dallago},
booktitle={NeurIPS 2022 Workshop on Learning Meaningful Representations of Life},
year={2022},
url={https://openreview.net/forum?id=adODyN-eeJ8}
}
```