pyXLMS-pydantic#

a python package to process protein cross-linking data

pyXLMS-pydantic is the Pydantic version of pyXLMS: a python package that aims to simplify and streamline the intermediate step of connecting crosslink search engine results with down-stream analysis tools, enabling researchers even without bioinformatics knowledge to conduct in-depth crosslink analyses and shifting the focus from data transformation to data interpretation and therefore gaining biological insight. Currently pyXLMS supports input from several different crosslink search engines including: MaxLynx (part of MaxQuant), MeroX, MS Annika, pLink 2 and pLink 3, Scout, xiSearch and xiFDR, XlinkX, as well as the mzIdentML format of the HUPO Proteomics Standards Initiative, and a well-documented and human-readable custom tabular format. Down-stream analysis is facilitated by functionality that is directly available within pyXLMS such as validation, annotation, aggregation, filtering, and visualization - and much more - of crosslink-spectrum-matches and crosslinks. In addition, the data can easily be exported to the required data format of the various available down-stream analysis tools such as AlphaLink2, ProXL, xiNET, xiVIEW, xiFDR, XlinkDB, xlms-tools, PyMOL (via PyXlinkViewer), ChimeraX (via XMAS), or IMP-X-FDR.

Why pyXLMS-pydantic and what are the differences to the classic pyXLMS?#

pyXLMS-pydantic is the Pydantic version of the classic pyXLMS. Using Pydantic offers increased type safety and validation, programmatically easier handling of crosslink-spectrum-matches and crosslinks. However, this comes at the slight cost of performance and compatibility - pyXLMS-pydantic requires python version 3.14 or newer!

For writing code there should not be any differences between the Pydantic and classic version, e.g. all the code written with the classic pyXLMS should also work with pyXLMS-pydantic. Crosslink-spectrum-matches, crosslinks, and parser results are now standalone classes based on the Pydantic BaseModel instead of dictionaries though. Some private functions have also been moved. The terms pyXLMS and pyXLMS-pydantic are used synonymously throughout this repository, unless specifically stated!

Installation#

Installing pyXLMS-pydantic will override the classic pyXLMS version if it was previously installed!

pyXLMS-pydantic supports python version 3.14 and greater and can easily be installed via pip:

pip install git+https://github.com/hgb-bin-proteomics/pyXLMS-pydantic.git

Quick Start#

After installation you can use pyXLMS in python like this:

This example shows reading of MS Annika crosslink-spectrum-matches and exporting them to xiFDR format for external validation.

>>> import pyXLMS
>>> pr = pyXLMS.parser.read(
...     "data/ms_annika/XLpeplib_Beveridge_QEx-HFX_DSS_R1_CSMs.xlsx",
...     engine="MS Annika",
...     crosslinker="DSS"
... )
Reading MS Annika CSMs...: 100%|████████████████| 826/826 [00:00<00:00, 20731.70it/s]
>>> _ = pyXLMS.transform.summary(pr)
Number of CSMs: 826.0
Number of unique CSMs: 826.0
Number of intra CSMs: 803.0
Number of inter CSMs: 23.0
Number of target-target CSMs: 786.0
Number of target-decoy CSMs: 39.0
Number of decoy-decoy CSMs: 1.0
Minimum CSM score: 1.11
Maximum CSM score: 452.99
>>> _ = pyXLMS.exporter.to_xifdr(
...     pr["crosslink-spectrum-matches"],
...     filename="msannika_CSMs_for_xiFDR.csv"
... )

Examples and Documentation#

FAQ#

Not sure if pyXLMS is what you are looking for? You can find a collection of common questions and answers about pyXLMS here or in the user guide under Documentation ➡️ FAQ.

Limitations#

Despite our best efforts pyXLMS still comes with some limitations that are a direct result of the differences in the output formats of crosslink search engines. Many crosslink search engines do not report any kind of decoy matches which makes validation in pyXLMS or export to xiFDR impossible which is why we recommend using validated results for pyXLMS. Validation within pyXLMS is currently only supported for MaxLynx, MS Annika, and xiSearch.

Furthermore, the different down-stream analysis tools require varying input information which might not be consistently available from all crosslink search engines. Some of this can be mitigated by functionality in pyXLMS such as annotation or by additional information that needs to be passed to pyXLMS for a successful export. Generally, the export to all downstream analysis tools should work for all crosslink search engines and input formats, with the exception of the export to xiFDR which is limited to MaxLynx, MS Annika, and xiSearch for above reasons. For safety pyXLMS makes sure before the export that all the required information is available and will otherwise throw an error. For more information please check the specific export pages in the user guide and the documentation.

The web app supports most of the features of the python package, features that are not supported in the web app are listed in the user guide under Documentation ➡️ Web Application ➡️ Feature Support.

Interacting with STRING requires an active internet connection and depends on the service availability of STRING.

Citing#

If you are using pyXLMS please cite as described here.

Acknowledgements#

We thank Melanie Birklbauer for designing the logo.

Contact#