Metadata-Version: 2.4
Name: dlomix
Version: 0.3.1
Summary: Deep Learning for Proteomics
Home-page: https://github.com/wilhelm-lab/dlomix
Author: Wilhelm Lab
Author-email: o.shouman@tum.de
License-Expression: MIT
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: datasets>=4.0.0
Requires-Dist: huggingface_hub>=0.20.0
Requires-Dist: keras>=3.0.0
Requires-Dist: fpdf
Requires-Dist: pandas
Requires-Dist: numpy>=2.0
Requires-Dist: matplotlib
Requires-Dist: scikit-learn
Requires-Dist: pyarrow>=22
Requires-Dist: seaborn
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: setuptools; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: pylint; extra == "dev"
Requires-Dist: tensorflow<2.20,>=2.18; (platform_system == "Darwin" and python_version < "3.13") and extra == "dev"
Requires-Dist: tensorflow<2.22,>=2.18; (platform_system != "Darwin" or python_version >= "3.13") and extra == "dev"
Requires-Dist: torch>=2.3; extra == "dev"
Provides-Extra: wandb
Requires-Dist: wandb>=0.20.0; extra == "wandb"
Provides-Extra: tensorflow
Requires-Dist: tensorflow<2.20,>=2.18; (platform_system == "Darwin" and python_version < "3.13") and extra == "tensorflow"
Requires-Dist: tensorflow<2.22,>=2.18; (platform_system != "Darwin" or python_version >= "3.13") and extra == "tensorflow"
Provides-Extra: tf
Requires-Dist: tensorflow<2.20,>=2.18; (platform_system == "Darwin" and python_version < "3.13") and extra == "tf"
Requires-Dist: tensorflow<2.22,>=2.18; (platform_system != "Darwin" or python_version >= "3.13") and extra == "tf"
Provides-Extra: tensorflow-cuda
Requires-Dist: tensorflow[and-cuda]<2.22,>=2.18; platform_system == "Linux" and extra == "tensorflow-cuda"
Requires-Dist: tensorflow<2.20,>=2.18; (platform_system == "Darwin" and python_version < "3.13") and extra == "tensorflow-cuda"
Requires-Dist: tensorflow<2.22,>=2.18; (platform_system != "Linux" and (platform_system != "Darwin" or python_version >= "3.13")) and extra == "tensorflow-cuda"
Provides-Extra: tf-cuda
Requires-Dist: tensorflow[and-cuda]<2.22,>=2.18; platform_system == "Linux" and extra == "tf-cuda"
Requires-Dist: tensorflow<2.20,>=2.18; (platform_system == "Darwin" and python_version < "3.13") and extra == "tf-cuda"
Requires-Dist: tensorflow<2.22,>=2.18; (platform_system != "Linux" and (platform_system != "Darwin" or python_version >= "3.13")) and extra == "tf-cuda"
Provides-Extra: torch
Requires-Dist: torch>=2.3; extra == "torch"
Provides-Extra: pytorch
Requires-Dist: torch>=2.3; extra == "pytorch"
Provides-Extra: lightning
Requires-Dist: lightning; extra == "lightning"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: license-expression
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# DLOmix

[![Docs](https://readthedocs.org/projects/dlomix/badge/?version=stable)](https://dlomix.readthedocs.io/en/stable/?badge=stable)
[![Build](https://github.com/wilhelm-lab/dlomix/actions/workflows/build.yaml/badge.svg)](https://github.com/wilhelm-lab/dlomix/actions/workflows/build.yaml)
[![PyPI](https://github.com/wilhelm-lab/dlomix/actions/workflows/pypi.yaml/badge.svg)](https://github.com/wilhelm-lab/dlomix/actions/workflows/pypi.yaml)

**DLOmix** is a Python framework for Deep Learning in Proteomics. DLOmix provides multi-backend support for both **TensorFlow/Keras** and **PyTorch**, allowing researchers to choose their preferred deep learning framework while maintaining identical APIs and functionality. The dataset module is built upon HuggingFace `datasets` and can provide both TensorFlow and PyTorch tensors.

**Note:** Multi-backend support was introduced in `dlomix==0.2`. Earlier versions supported TensorFlow/Keras only.

**Note:** Keras 3 support was introduced in `dlomix==0.3`: the TensorFlow backend now requires TensorFlow 2.18 or newer (where `tf.keras` is Keras 3), and every model is available on both backends and verified to compute the same function given the same weights. Import `dlomix` before `keras`, since DLOmix sets the Keras backend from `DLOMIX_BACKEND`. For TensorFlow < 2.16 (Keras 2), use `dlomix<0.3`. Upgrading from 0.2 on PyTorch: models now start and train like their TensorFlow counterparts, and some older checkpoints no longer load; see the [changelog](CHANGELOG.md).

The PyTorch implementation was largely introduced during a hackathon as part of the EuBIC Developer Meeting 2025. We appreciate the efforts and contributions of the team who joined the hackathon and the efforts of the EuBIC team and organizers.

## Backend Selection

DLOmix automatically detects and uses the appropriate backend based on your environment setup. You can control which backend to use through the `DLOMIX_BACKEND` environment variable:

### TensorFlow Backend (Default)
The TensorFlow backend requires **TensorFlow 2.18+ (Keras 3)**; the PyTorch backend requires **PyTorch 2.3+**.
```bash
# Set TensorFlow as backend (default)
export DLOMIX_BACKEND=tensorflow
# or
export DLOMIX_BACKEND=tf

# Install DLOmix with TensorFlow
pip install dlomix[tensorflow]

# Or install tensorflow separately (existing installation), then only install dlomix
pip install dlomix
```

### PyTorch Backend
```bash
# Set PyTorch as backend
export DLOMIX_BACKEND=pytorch
# or
export DLOMIX_BACKEND=torch
# or
export DLOMIX_BACKEND=pt

# Install DLOmix with PyTorch support
pip install dlomix[pytorch]

# Or install pytorch separately (existing installation), then only install dlomix
pip install dlomix
```

**Note**: The backend must be set **before** importing DLOmix. If no backend is specified, DLOmix defaults to TensorFlow with a user warning.

### GPU Support (Linux, NVIDIA)

**TensorFlow** needs its CUDA libraries installed explicitly. The `tf-cuda` extra installs them as pip packages through `tensorflow[and-cuda]`, so no system-wide CUDA toolkit is needed — only an NVIDIA driver:
```bash
pip install "dlomix[tf-cuda]"
```
NVIDIA publishes these CUDA wheels for Linux only. On macOS and Windows the `tf-cuda` extra installs the regular TensorFlow build instead of failing.

**PyTorch** needs no extra: its Linux wheels on PyPI are already CUDA builds, so `pip install "dlomix[pytorch]"` is enough. Recent PyTorch releases target a recent CUDA version, which requires a correspondingly recent NVIDIA driver. On an older driver, install PyTorch from the matching CUDA index given by the [PyTorch install selector](https://pytorch.org/get-started/locally/), then install DLOmix.

To check what your environment sees — backend, versions, and GPUs visible to the active backend:
```bash
python -m dlomix
```
Please include this output when reporting a bug. If a GPU is present but not detected, the usual causes are a driver that is too old for the CUDA version shown, or an `LD_LIBRARY_PATH` pointing at a different system CUDA installation.

### Apple GPUs (macOS, tensorflow-metal)

With `tensorflow-metal` installed, TensorFlow trains on the Apple GPU. Its fused GRU kernel (tensorflow-metal 1.2.0) does not compute the standard GRU: it ignores the GRU's input bias and adds the recurrent bias outside the reset gate. Both agree while the biases are zero, as Keras initializes them, so training on a Mac looks normal. But once the biases are trained, the weights compute a different function on any other platform or in PyTorch: weights trained on a Mac give other predictions elsewhere, and published weights give wrong predictions on a Mac. This is a different formula, not floating-point error. The DLOmix TensorFlow models therefore use the standard GRU kernel when an Apple GPU is visible, and warn once. Results are then the same on every platform and in PyTorch, but the standard kernel is slow on the Apple GPU. Training Prosit intensity on an M1 Max:

| Setup | Time per epoch |
|---|---|
| TensorFlow, Apple GPU, standard GRU (default with `tensorflow-metal`) | 622 s |
| TensorFlow, CPU | 78 s |
| PyTorch, Apple GPU (MPS) | 16 s |

For the models with GRU layers (Prosit, charge state, detectability, Ionmob), train TensorFlow on the CPU by hiding the GPU before TensorFlow uses it, or use the PyTorch backend:
```python
import tensorflow as tf
tf.config.set_visible_devices([], "GPU")
```
`tensorflow-metal` 1.2.0 only works with TensorFlow below 2.20, which DLOmix installs on macOS for Python 3.11 and 3.12.

## Usage
Experiment a simple retention time prediction use-case using Google Colab &nbsp;&nbsp; [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/wilhelm-lab/dlomix/blob/develop/notebooks/Example_RTModel_Walkthrough_colab.ipynb)

A version that includes experiment tracking with [Weights and Biases](https://www.wandb.ai) is available here &nbsp;&nbsp; [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/wilhelm-lab/dlomix/blob/develop/notebooks/Example_RTModel_Walkthrough_colab-weights-and-biases.ipynb)

**Resources Repository**

More learning resources can be found in the [dlomix-resources](https://github.com/wilhelm-lab/dlomix-resources) repository.

## Installation

### Quick Start
```bash
# Basic installation
# TensorFlow and PyTorch not installed, please install separately
pip install dlomix

# Install DLOmix and additionally install specific backend
pip install dlomix[tensorflow]  # TensorFlow backend
pip install dlomix[pytorch]     # PyTorch backend

```


**General Package Overview**

DLOmix provides a unified API across both TensorFlow and PyTorch backends:

-  `data`: structures for modeling input data, processing functions, and feature extractions based on Hugging Face datasets `Dataset` and `DatasetDict` (backend-agnostic)
-  `eval`: classes for evaluating models and reporting results (backend-specific implementations)
-  `layers`: custom layers for building models
   - TensorFlow: based on `tf.keras.layers.Layer`
   - PyTorch: based on `torch.nn.Module`
-  `losses`: custom loss functions
   - TensorFlow: compatible with `model.fit()`
   - PyTorch: compatible with standard PyTorch training loops
- `models`: common model architectures for relevant use-cases
   - TensorFlow: based on `tf.keras.Model`
   - PyTorch: based on `torch.nn.Module`
-  `pipelines`: high-level pipeline implementations (backend-agnostic)
-  `reports`: classes for generating reports (backend-agnostic)
-  `constants.py`: constants and configuration values

**Available Models by Backend**

| Model | TensorFlow/Keras | PyTorch |
|-------|------------|---------|
| `PrositRetentionTimePredictor` [1] | ✅ | ✅ |
| `PrositIntensityPredictor` [1] | ✅ | ✅ |
| `ChargeStatePredictor` | ✅ | ✅ |
| `DetectabilityModel` [4] | ✅ | ✅ |
| `DeepLCRetentionTimePredictor` [2,3] | ✅ | ✅ |
| `Ionmob` [5] | ✅ | ✅ |
| `PIMMS-CF` [6] | ❌ | ⚠ (experimental) |



**Use-cases**

- Retention Time Prediction:
    - a regression problem where the retention time of a peptide sequence is to be predicted.

- Fragment Ion Intensity Prediction:
    - a multi-output regression problem where the intensity values for fragment ions are predicted given a peptide sequence along with some additional features.

- Peptide Detectability (Pfly) [4]:
    - a multi-class classification problem where the detectability of a peptide is predicted given the peptide sequence.


## Developing DLOmix
To install dlomix, along with the tools needed to develop and run tests, run the following command in your virtualenv:
```bash
$ pip install -e .[dev]
```


## References

[**Prosit**]

[1] Gessulat, S., Schmidt, T., Zolg, D. P., Samaras, P., Schnatbaum, K., Zerweck, J., ... & Wilhelm, M. (2019). Prosit: proteome-wide prediction of peptide tandem mass spectra by deep learning. Nature methods, 16(6), 509-518.

[**DeepLC**]

[2] DeepLC can predict retention times for peptides that carry as-yet unseen modifications
Robbin Bouwmeester, Ralf Gabriels, Niels Hulstaert, Lennart Martens, Sven Degroeve
bioRxiv 2020.03.28.013003; doi: 10.1101/2020.03.28.013003

[3] Bouwmeester, R., Gabriels, R., Hulstaert, N. et al. DeepLC can predict retention times for peptides that carry as-yet unseen modifications. Nat Methods 18, 1363–1369 (2021). https://doi.org/10.1038/s41592-021-01301-5

[**Detectability - Pfly**]

[4] Abdul-Khalek, N., Picciani, M., Wimmer, R., Overgaard, M. T., Wilhelm, M., & Gregersen Echers, S. (2024). To fly, or not to fly, that is the question: A deep learning model for peptide detectability prediction in mass spectrometry. bioRxiv, 2024-10.

[**IonMob**]

[5] Teschner, D., Gomez-Zepeda, D., Declercq, A., Łącki, M. K., Avci, S., Bob, K., ... & Hildebrandt, A. (2023). Ionmob: a Python package for prediction of peptide collisional cross-section values. Bioinformatics, 39(9), btad486.

[**PIMMS**]

[6] Webel, H., Niu, L., Nielsen, A.B. et al.
Imputation of label-free quantitative mass spectrometry-based proteomics data using self-supervised deep learning.
Nat Commun 15, 5405 (2024).
https://doi.org/10.1038/s41467-024-48711-5


### Credit

**PyTorch Implementation Hackathon during EuBIC Developer Meeting 2025**

- Ayla Schröder
- Henry Webel
- David Teschner
- Stan Reinders
