Metadata-Version: 2.4
Name: xirt-torch
Version: 2.0.1
Summary: Multi-dimensional retention time prediction for linear and crosslinked peptides
Author-email: Sven Giese <sven.giese@hpi.de>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/gieses/xiRT
Project-URL: Documentation, https://gieses.github.io/xiRT/
Project-URL: Repository, https://github.com/gieses/xiRT
Project-URL: Issues, https://github.com/gieses/xiRT/issues
Keywords: proteomics,crosslinking,retention time,chromatography,PyTorch
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: torch<3,>=2.9
Requires-Dist: numpy<3,>=2
Requires-Dist: pandas<3,>=2.2
Requires-Dist: scipy>=1.14
Requires-Dist: scikit-learn>=1.6
Requires-Dist: biopython>=1.85
Requires-Dist: pyteomics>=4.7
Requires-Dist: pyyaml>=6
Requires-Dist: matplotlib>=3.9
Requires-Dist: seaborn<0.14,>=0.13
Requires-Dist: palettable>=3.3
Requires-Dist: statannotations>=0.7
Requires-Dist: pydantic<3,>=2.10
Requires-Dist: tqdm>=4.67
Requires-Dist: marimo>=0.25.1
Provides-Extra: cpu
Requires-Dist: torch<3,>=2.9; extra == "cpu"
Provides-Extra: cuda
Requires-Dist: torch<3,>=2.9; extra == "cuda"
Provides-Extra: esm
Requires-Dist: esm<3.3,>=3.2.3; python_version == "3.12" and extra == "esm"
Provides-Extra: experiments
Requires-Dist: lion-pytorch; extra == "experiments"
Provides-Extra: tracking
Requires-Dist: mlflow<4,>=3; extra == "tracking"
Provides-Extra: tensorboard
Requires-Dist: tensorboard; extra == "tensorboard"
Dynamic: license-file

<p align="center">
  <img src="https://gieses.github.io/xiRT/assets/xirt-logo.svg" alt="xiRT — retention-time prediction" width="360">
</p>

<p align="center">
  <strong>Retention-time prediction for linear and crosslinked peptides.</strong><br>
  Modification-aware sequences. Shared recurrent encoders. PyTorch on CPU or CUDA.
</p>

<p align="center">
  <a href="https://gieses.github.io/xiRT/">Documentation</a> ·
  <a href="https://gieses.github.io/xiRT/getting-started/">Quick start</a> ·
  <a href="https://gieses.github.io/xiRT/tutorials/">Notebooks</a> ·
  <a href="https://gieses.github.io/xiRT/benchmarks/">Benchmarks</a> ·
  <a href="https://pypi.org/project/xirt-torch/">PyPI</a>
</p>

## What xiRT does

xiRT learns peptide embeddings and predicts continuous retention times or
fraction labels. Crosslinked peptides share a recurrent encoder between their
two sequence branches; linear peptides use a single input. Train a model for
your experiment, use a saved checkpoint for prediction, or adapt a recurrent
model with full fine-tuning, a frozen encoder, LoKr, or LoRA.

## Install

Requires **Python 3.12–3.14**. The PyPI distribution is `xirt-torch`; the Python
import and command remain `xirt`.

```bash
pip install xirt-torch
```

Generate the two configuration files, then edit their input columns and targets
before training:

```bash
xirt -p xirt_params.yaml -s learning_params.yaml
xirt -i psms.csv -o results -x xirt_params.yaml -l learning_params.yaml
```

For a locked source installation, clone this repository and run
`uv sync --locked --extra cpu` (or `--extra cuda`), then prefix the commands with
`uv run --no-sync`. See [installation and CLI](https://gieses.github.io/xiRT/getting-started/) for
backend selection and optional tracking, TensorBoard, Lion, and ESM-C extras.

## Learn with real peptide data

Two [CPU notebooks](https://gieses.github.io/xiRT/tutorials/) use 2,048 observed peptide pairs:

| Notebook | Covers |
| --- | --- |
| [Train and predict](https://github.com/gieses/xiRT/blob/master/examples/train_predict.py) | Prepare inputs, train a model, save a checkpoint, and predict retention times |
| [Fine-tune a model](https://github.com/gieses/xiRT/blob/master/examples/fine_tune.py) | Compare full, frozen-encoder, GRU-LoKr, and GRU-LoRA fine-tuning |

From the source checkout:

```bash
uv run --no-sync marimo edit examples/train_predict.py --host 127.0.0.1
uv run --no-sync marimo edit examples/fine_tune.py --host 127.0.0.1
```

`make examples` executes both without a notebook server. Training uses up to
150 epochs with validation-based early stopping. The
[fine-tuning guide](https://gieses.github.io/xiRT/fine-tuning/) covers checkpoint compatibility, the
Python API, and YAML settings.

## Results and compatibility

The [benchmark documentation](https://gieses.github.io/xiRT/benchmarks/) links protocols, predictions,
checkpoint provenance, and plots. PyTorch had lower mean held-out RMSE than
TensorFlow on **two of five** evaluated cohorts, not all five. Full fine-tuning
had the lowest mean RMSE among the four native fine-tuning strategies on all
five cohorts under the fixed comparison protocol.

**Upgrading from 1.x:** TensorFlow is no longer an application dependency or
supported backend, and xiRT 2.0 cannot load Keras `.h5` models. See the
[migration guide](https://gieses.github.io/xiRT/migration/). Historical artifacts remain in
`benchmark-tf-torch/<cohort>/results/`.

## Development

```bash
make sync
make check
make build
```

`pixi run sync` bootstraps the same locked uv environment. `make help` lists
documentation, notebook, test and release commands. Benchmark code lives in
`xirt/data_pipelines/benchmarks/` and is excluded from the production wheel.

[Configuration](https://gieses.github.io/xiRT/configuration/) ·
[Migration](https://gieses.github.io/xiRT/migration/) ·
[Python API](https://gieses.github.io/xiRT/api/) ·
[Development](https://gieses.github.io/xiRT/development/)

## Citation

Giese, S.H., Sinn, L.R., Wegner, F. et al. Retention time prediction using neural
networks increases identifications in crosslinking mass spectrometry.
*Nature Communications* **12**, 3237 (2021).
[DOI: 10.1038/s41467-021-23441-0](https://doi.org/10.1038/s41467-021-23441-0)

Contributors: Sven Giese and Ludwig Sinn.
