{"id":28182813,"url":"https://github.com/thegreatherrlebert/rustims","last_synced_at":"2025-05-16T04:14:23.780Z","repository":{"id":199453720,"uuid":"688863182","full_name":"theGreatHerrLebert/rustims","owner":"theGreatHerrLebert","description":"A Framework for IMS-MS Raw Data Processing written in Rust and Python.","archived":false,"fork":false,"pushed_at":"2025-05-15T17:59:29.000Z","size":82194,"stargazers_count":10,"open_issues_count":10,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-05-16T04:13:49.180Z","etag":null,"topics":["bottom-up","data-independent-acquisition","high-throughput","ion-mobility-spectrometry","mass-spectrometry","omics","proteomics","pyo3","python","raw-data","rust-lang","timstof"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/theGreatHerrLebert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-09-08T09:05:28.000Z","updated_at":"2025-05-15T20:44:58.000Z","dependencies_parsed_at":"2024-03-16T14:40:19.364Z","dependency_job_id":"c4dcf0e7-919d-4910-836b-3c878be7e1d7","html_url":"https://github.com/theGreatHerrLebert/rustims","commit_stats":null,"previous_names":["thegreatherrlebert/rustims"],"tags_count":44,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theGreatHerrLebert%2Frustims","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theGreatHerrLebert%2Frustims/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theGreatHerrLebert%2Frustims/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/theGreatHerrLebert%2Frustims/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/theGreatHerrLebert","download_url":"https://codeload.github.com/theGreatHerrLebert/rustims/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254464899,"owners_count":22075572,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bottom-up","data-independent-acquisition","high-throughput","ion-mobility-spectrometry","mass-spectrometry","omics","proteomics","pyo3","python","raw-data","rust-lang","timstof"],"created_at":"2025-05-16T04:13:46.449Z","updated_at":"2025-05-16T04:14:23.770Z","avatar_url":"https://github.com/theGreatHerrLebert.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rustims\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"rustims_logo.png\" alt=\"logo\" width=\"250\"/\u003e\n\u003c/p\u003e\n\n`rustims` is a framework developed for processing raw data from Ion-Mobility Spectrometry (IMS) in proteomics mass spectrometry. It draws inspiration from OpenMS but is distinguished by its use of [Rust](https://www.rust-lang.org/) as the backend language, aiming for efficient algorithm implementations and robust data structures. Like OpenMS, `rustims` exposes most of its logic to Python, here via [PyO3](https://docs.rs/pyo3/latest/pyo3/). This setup is intended to enable easy pick-up, quick prototyping, and integration into existing Python-centric scientific workflows. \n\n`rustims` is about exploring and improving the way we process ion-mobility spectrometry data, providing re-usable building blocks that can be extensively configured. It's a work in progress, reflecting the open-source ethos of collaboration, engagement, and sharing of knowledge. Whether you're here to contribute or learn, we welcome your interest!\n\n# Quickstart\nTo quickly get started, we recommend installing the Python package `imspy`, the high-level Python API designed for most users to interact with `rustims` functionality, via pip into a separate Virtual\nEnvironment using Python3.11 (currently the only supported Python version due to TensorFlow). If you don't know how to create a Virtual Environment, you can follow the instructions [here](https://docs.python.org/3/library/venv.html).\nThis way, you can avoid potential dependency conflicts with other Python packages.\nThe following command installs the latest version of `imspy` from PyPi:\n```shell\npip install imspy\n```\nThis will install tensorflow as a dependency without GPU support.\nThe easiest way to get GPU support is to additionally install the tensorflow[and-cuda] package:\n```shell\npip install tensorflow[and-cuda]==2.15.*\n```\nWhich comes with the necessary CUDA and cuDNN libraries.\nHave a look at the [imspy-README](https://github.com/theGreatHerrLebert/rustims/tree/main/imspy) to learn about basic functionalities of the package.\n\n# Repository Structure\n\u003cfigure align=\"center\"\u003e\n  \u003cimg src=\"rustims_layout.png\" alt=\"RustIMS Project Structure\" width=\"700\"/\u003e\n  \u003cfigcaption\u003e\n    The \u003cem\u003erustims\u003c/em\u003e project architecture is designed around two core Rust crates: \n    \u003ccode\u003emscore\u003c/code\u003e and \u003ccode\u003erustdf\u003c/code\u003e. These crates are the foundation of the project, \n    housing the in-memory data structures, algorithms, and input/output functionalities \n    specifically for TDF files. These Rust components are seamlessly integrated with Python \n    through \u003ccode\u003epyO3\u003c/code\u003e, which allows the main functionalities of \u003ccode\u003emscore\u003c/code\u003e \n    and \u003ccode\u003erustdf\u003c/code\u003e to be accessible in Python by compiling them into a single, \n    installable Python wheel named \u003ccode\u003eimspy_connector\u003c/code\u003e. On top of this, \n    \u003ccode\u003eimspy\u003c/code\u003e is a native Python package that not only interfaces with the Rust \n    crates for enhanced performance but also introduces additional logic, such as TensorFlow \n    models for ion-mobility prediction, thereby combining the strengths of Rust and Python in \n    one cohesive framework.\n  \u003c/figcaption\u003e\n\u003c/figure\u003e\n\n## Citation\n\nIf you find rustims or imspy useful, please consider citing our paper:\n\nTeschner, D et al. “Rustims: An Open-Source Framework for Rapid Development and Processing of timsTOF Data-Dependent Acquisition Data.” [Journal of Proteome Research (2025)]( https://pubs.acs.org/doi/full/10.1021/acs.jproteome.4c00966).\n\nThanks for supporting open-source science!\n\n\n## Analyzing a DDA dataset from Bruker timsTOF with imspy_dda\nYou can directly run the `imspy_dda` command to analyze a DDA dataset:\n```shell\nimspy_dda path/to/bruker.tdf path/to/proteome.fasta\n```\nThe tool has a lot of options, which you can explore by running:\n```shell\nimspy_dda --help\n```\n\n## Dive into processing of timsTOF DDA data with jupyter notebooks\nWe are now providing [jupyter notebook examples](https://github.com/theGreatHerrLebert/rustims/blob/main/imspy/examples/) that allow you to interactively learn about the functionality of our tooling. You can also checkout the [sagepy notebook examples](https://github.com/theGreatHerrLebert/sagepy/tree/main/sagepy/examples) which are hosted in a separate repository since sagepy is not limited to DB searching of timsTOF data.\n\n## Read the docs\nThe codbease of all native rust crates and python packages is now available:\n\n* [rustdf](https://thegreatherrlebert.github.io/rustims/main/rustdf/)\n* [mscore](https://thegreatherrlebert.github.io/rustims/main/mscore/)\n* [rustms](https://thegreatherrlebert.github.io/rustims/main/rustms/)\n* [imspy](https://thegreatherrlebert.github.io/rustims/main/imspy/)\n\n## Generating Synthetic PASEF-like Datasets with TimSim\n\n**TimSim** is a versatile simulation tool designed for generating synthetic PASEF-like datasets for proteomics experiments on Bruker TimsTOF instruments. It offers two complementary modes of operation:\n\n### Command-Line Mode\n\nTimSim can be run directly from the terminal. You have two convenient options:\n\n1. **Direct Parameter Specification:**  \n   Provide the required positional arguments along with any desired options:\n   ```bash\n   timsim path/to/output.tdf path/to/reference.tdf path/to/proteome.fasta [--option value ...]\n   ```\n2. **Configuration File Mode:**  \n   To simplify repetitive runs, supply all simulation parameters via a TOML configuration file using the `--config` option:\n   ```bash\n   timsim --config path/to/config.toml\n   ```\n   This approach lets you store and reuse complete simulation setups without having to specify each parameter on the command line.\n\n### Graphical User Interface (GUI) Mode\n\nFor an interactive, user-friendly experience, launch the TimSim GUI. The GUI allows you to:\n- Adjust simulation parameters via intuitive controls.\n- Visualize real-time logs and plots.\n- Experiment with settings before executing a full simulation.\n\nYou can start the GUI with:\n```bash\ntimsim_gui\n```\n### Example Data and Configuration\n\nTo help you get started, example datasets and sample configuration files are available on our [Zenodo repository](https://zenodo.org/record/XXXXXX) (link coming soon). These examples demonstrate common workflows and parameter settings for both the command-line and GUI modes.\n\n## Rust backend: mscore and rustdf\nThere are two Rrust projects: `mscore` and `rustdf`. The former is a library that contains implementations of in-memory data structures and algorithms for raw-data processing. The latter contains a Rust-native reader and writer of TDF, the serialization format written by [Bruker timsTOF](https://www.bruker.com/en/products-and-solutions/mass-spectrometry/timstof.html) devices. It also contains the implementation of the I/O logic needed for synthetic timsTOF PASEF-like in-silico dataset generation.\n\n## Python bindings: imspy_connector\nThe `imspy_connector` module bridges Rust code with Python, allowing Rust components to be used in Python with minimal dependencies. This setup keeps the system lightweight for Python users but introduces complexity, especially in development and debugging. Changes in Rust need to be reflected in Python, often requiring updates in multiple places. Despite the added complexity, this architecture is chosen for its benefits. It allows for parts of the code in Rust or Python that don't interact with the other language to be developed independently and asynchronously. However, this flexibility is limited to components that do not require cross-language access.\n\n## Python package: imspy\n`imspy` is a Python package designed for end-users. It utilizes `imspy_connector` for accessing Rust functionalities exposed via `pyO3`, incorporating additional libraries like `tensorflow`, `scikit-learn`, and `sagepy`. This setup enables users to perform detailed tasks such as calculating peptide fragment ions, analyzing isotope patterns, studying quadrupole transmission, and applying deep learning to ion mobility and retention time predictions.\n\n## Julia bindings\nJulia support is currently experimental. Julia interfaces via `imsjl_connector`, [FFI](https://doc.rust-lang.org/nomicon/ffi.html).\n\n# Installation\n\n## Install via pip\nWe are now providing stable versions of the python-bound components via Python wheels on PyPi. We recommend that you use a [Python virtual environment](https://docs.python.org/3/library/venv.html) with `python3.11`, since imspy has some heavy weight dependencies like `tensorflow`, `numpy`, and `numba`, where version mismatches can lead to potential issues.\n```shell\npip install imspy\n```\n\n## Build from source\n## Rust backend\nAssuming a [rust](https://www.rust-lang.org/learn/get-started) is installed on your system and you cloned this repository, the build process currently looks like this (example for mscore):\n```shell\ncd rustims/mscore \u0026\u0026 cargo build --release\n```\n\n## Python bindings\nAssuming a [rust](https://www.rust-lang.org/learn/get-started) and Python (==3.11) version is installed on your system, the\nbuild process currently looks like this:\n\n1.  The Python connector `imspy_connector` needs to be built by [Maturin](https://github.com/PyO3/maturin).\n    Maturin can be installed via pip:\n    ```shell\n    pip install maturin[patchelf]\n    ```\n2.  Once Maturin is installed navigate to the `imspy_connector` folder and run:\n    ```shell\n    maturin build --release\n    ```\n    This generates a `.whl` file that can be installed by pip.\n3.  Install the generated `.whl` file:\n    ```shell\n    pip install --force-reinstall ./target/wheels/[FILE_NAME].whl\n    ```\n    The `--force-reinstall` flag ensures that pip is overwriting old installations of the bindings. This\n    is relevant when you make changes in the rust backend code (i.e. the bindings themselves, `mscore` or `rustdf`).\n    \n## Julia bindings\nJulia support is currently experimental.\n\n## Python package\nThe Python library is installed via [Poetry](https://github.com/python-poetry/poetry).\n1.  Poetry can be installed via pip:\n    ```shell\n    pip install poetry\n    ```\n2.  Navigate to the `imspy` folder and install it with Poetry.\n    ```shell\n    poetry install\n    ```\n## Docker image\nFor ease of use and reproducable running of our software, we are now providing a docker image for the AMD64 architecture.\nIt can be also used on macOS ARM64 via virtualization. To get the image, download the here linked [release.zip](https://github.com/MatteoLacki/rustims_docker/blob/main/release.zip), unzip it and follow the installation instructions provided inside the readme.md file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthegreatherrlebert%2Frustims","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthegreatherrlebert%2Frustims","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthegreatherrlebert%2Frustims/lists"}