imspy-core 0.4.0__tar.gz

imspy_core-0.4.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.4
+Name: imspy-core
+Version: 0.4.0
+Summary: Core data structures and utilities for processing timsTOF ion mobility spectrometry data.
+License-Expression: MIT
+Author: theGreatHerrLebert
+Author-email: davidteschner@googlemail.com
+Requires-Python: >=3.11,<3.14
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: imspy-connector (>=0.3.0)
+Requires-Dist: mendeleev (>=0.7.0)
+Requires-Dist: numba (>=0.53)
+Requires-Dist: numpy (>=1.21)
+Requires-Dist: opentims-bruker-bridge (>=1.1.0)
+Requires-Dist: pandas (>=2.1)
+Requires-Dist: pyarrow (>=13.0)
+Requires-Dist: scipy (>=1.7.1)
+Requires-Dist: tabulate (>=0.9.0)
+Requires-Dist: toml (>=0.10.2)
+Requires-Dist: tqdm (>=4.66)
+Requires-Dist: zstd (>=1.5.6.1)
+Description-Content-Type: text/markdown
+
+# imspy-core
+
+Core data structures and utilities for processing timsTOF ion mobility spectrometry data.
+
+## Installation
+
+```bash
+pip install imspy-core
+```
+
+## Features
+
+- **Data Structures**: MzSpectrum, TimsSpectrum, PeptideSequence, and more
+- **Chemistry Utilities**: Elements, amino acids, UNIMOD modifications, CCS/mobility conversions
+- **TimsTOF Readers**: Read DDA and DIA datasets from Bruker timsTOF instruments
+- **Low Dependencies**: Only essential packages (numpy, pandas, scipy, numba)
+
+## Quick Start
+
+```python
+from imspy_core.timstof import TimsDatasetDDA
+from imspy_core.data import PeptideSequence
+
+# Read a DDA dataset
+dataset = TimsDatasetDDA("/path/to/data.d")
+frame = dataset.get_tims_frame(1)
+print(frame)
+
+# Work with peptides
+peptide = PeptideSequence("PEPTIDEK")
+print(f"Mass: {peptide.mono_isotopic_mass}")
+```
+
+## Related Packages
+
+- **imspy-predictors**: ML-based predictions (CCS, RT, intensity) - requires TensorFlow
+- **imspy-search**: Database search functionality - requires sagepy, mokapot
+- **imspy-simulation**: Simulation tools for timsTOF data
+- **imspy-vis**: Visualization tools - requires Plotly, Matplotlib
+
+## License
+
+MIT License - see LICENSE file for details.
+

imspy_core-0.4.0/README.md

@@ -0,0 +1,43 @@
+# imspy-core
+
+Core data structures and utilities for processing timsTOF ion mobility spectrometry data.
+
+## Installation
+
+```bash
+pip install imspy-core
+```
+
+## Features
+
+- **Data Structures**: MzSpectrum, TimsSpectrum, PeptideSequence, and more
+- **Chemistry Utilities**: Elements, amino acids, UNIMOD modifications, CCS/mobility conversions
+- **TimsTOF Readers**: Read DDA and DIA datasets from Bruker timsTOF instruments
+- **Low Dependencies**: Only essential packages (numpy, pandas, scipy, numba)
+
+## Quick Start
+
+```python
+from imspy_core.timstof import TimsDatasetDDA
+from imspy_core.data import PeptideSequence
+
+# Read a DDA dataset
+dataset = TimsDatasetDDA("/path/to/data.d")
+frame = dataset.get_tims_frame(1)
+print(frame)
+
+# Work with peptides
+peptide = PeptideSequence("PEPTIDEK")
+print(f"Mass: {peptide.mono_isotopic_mass}")
+```
+
+## Related Packages
+
+- **imspy-predictors**: ML-based predictions (CCS, RT, intensity) - requires TensorFlow
+- **imspy-search**: Database search functionality - requires sagepy, mokapot
+- **imspy-simulation**: Simulation tools for timsTOF data
+- **imspy-vis**: Visualization tools - requires Plotly, Matplotlib
+
+## License
+
+MIT License - see LICENSE file for details.

imspy_core-0.4.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "imspy-core"
+version = "0.4.0"
+description = "Core data structures and utilities for processing timsTOF ion mobility spectrometry data."
+authors = [
+    { name = "theGreatHerrLebert", email = "davidteschner@googlemail.com" }
+]
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11,<3.14"
+
+dependencies = [
+    "pandas>=2.1",
+    "numpy>=1.21",
+    "numba>=0.53",
+    "scipy>=1.7.1",
+    "zstd>=1.5.6.1",
+    "tabulate>=0.9.0",
+    "tqdm>=4.66",
+    "pyarrow>=13.0",
+    "mendeleev>=0.7.0",
+    "toml>=0.10.2",
+    "imspy-connector>=0.3.0",
+    "opentims-bruker-bridge>=1.1.0",
+]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.0.0"
+pytest-cov = "^4.1.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --tb=short"

imspy_core-0.4.0/src/imspy_core/__init__.py

@@ -0,0 +1,75 @@
+"""
+imspy_core - Core data structures and utilities for processing timsTOF ion mobility spectrometry data.
+
+This package provides the foundational components for working with timsTOF data:
+- Data structures for spectra and peptides
+- Chemistry utilities (elements, amino acids, UNIMOD)
+- TimsTOF dataset readers (DDA and DIA)
+- General utilities
+
+For ML-based predictions, install imspy-predictors.
+For database search functionality, install imspy-search.
+For simulation tools, install imspy-simulation.
+"""
+
+__version__ = "0.4.0"
+
+# Core base classes
+from imspy_core.core import RustWrapperObject
+
+# Data structures
+from imspy_core.data import (
+    MzSpectrum, IndexedMzSpectrum, MzSpectrumVectorized, TimsSpectrum,
+    PeptideSequence, PeptideIon, PeptideProductIon,
+    PeptideProductIonSeries, PeptideProductIonSeriesCollection
+)
+
+# Chemistry
+from imspy_core.chemistry import (
+    MASS_PROTON, MASS_NEUTRON, MASS_ELECTRON, MASS_WATER,
+    AMINO_ACID_MASSES, AMINO_ACIDS,
+    UNIMOD_MASSES,
+    one_over_k0_to_ccs, ccs_to_one_over_k0,
+    SumFormula, calculate_mz
+)
+
+# TimsTOF
+from imspy_core.timstof import (
+    TimsDataset, AcquisitionMode,
+    TimsFrame, TimsFrameVectorized,
+    TimsSlice, TimsSliceVectorized,
+    TimsDatasetDDA, PrecursorDDA, FragmentDDA,
+    TimsDatasetDIA,
+    TimsTofQuadrupoleDDA, TimsTofQuadrupoleDIA
+)
+
+# Utility
+from imspy_core.utility import (
+    re_index_indices, tokenize_unimod_sequence
+)
+
+__all__ = [
+    # Version
+    '__version__',
+    # Core
+    'RustWrapperObject',
+    # Data
+    'MzSpectrum', 'IndexedMzSpectrum', 'MzSpectrumVectorized', 'TimsSpectrum',
+    'PeptideSequence', 'PeptideIon', 'PeptideProductIon',
+    'PeptideProductIonSeries', 'PeptideProductIonSeriesCollection',
+    # Chemistry
+    'MASS_PROTON', 'MASS_NEUTRON', 'MASS_ELECTRON', 'MASS_WATER',
+    'AMINO_ACID_MASSES', 'AMINO_ACIDS',
+    'UNIMOD_MASSES',
+    'one_over_k0_to_ccs', 'ccs_to_one_over_k0',
+    'SumFormula', 'calculate_mz',
+    # TimsTOF
+    'TimsDataset', 'AcquisitionMode',
+    'TimsFrame', 'TimsFrameVectorized',
+    'TimsSlice', 'TimsSliceVectorized',
+    'TimsDatasetDDA', 'PrecursorDDA', 'FragmentDDA',
+    'TimsDatasetDIA',
+    'TimsTofQuadrupoleDDA', 'TimsTofQuadrupoleDIA',
+    # Utility
+    're_index_indices', 'tokenize_unimod_sequence',
+]

imspy_core-0.4.0/src/imspy_core/chemistry/__init__.py

@@ -0,0 +1,37 @@
+"""
+Chemistry module for imspy_core.
+
+Contains elements, amino acids, UNIMOD, mobility functions, and sum formulas.
+"""
+
+from .constants import (
+    MASS_PROTON, MASS_NEUTRON, MASS_ELECTRON, MASS_WATER,
+    STANDARD_TEMPERATURE, STANDARD_PRESSURE, ELEMENTARY_CHARGE,
+    K_BOLTZMANN, AVOGADRO_NUMBER
+)
+from .elements import (
+    ELEMENTAL_MONO_ISOTOPIC_MASSES, ELEMENTAL_ISOTOPIC_MASSES,
+    ELEMENTAL_ISOTOPIC_ABUNDANCES
+)
+from .amino_acids import AMINO_ACID_MASSES, AMINO_ACIDS, AMINO_ACID_ATOMIC_COMPOSITIONS
+from .unimod import UNIMOD_MASSES, UNIMOD_ATOMIC_COMPOSITIONS
+from .mobility import (
+    one_over_k0_to_ccs, ccs_to_one_over_k0,
+    ccs_to_one_over_k0_par, one_over_k0_to_ccs_par
+)
+from .sum_formula import SumFormula
+from .utility import calculate_mz, calculate_transmission_dependent_fragment_ion_isotope_distribution
+
+__all__ = [
+    'MASS_PROTON', 'MASS_NEUTRON', 'MASS_ELECTRON', 'MASS_WATER',
+    'STANDARD_TEMPERATURE', 'STANDARD_PRESSURE', 'ELEMENTARY_CHARGE',
+    'K_BOLTZMANN', 'AVOGADRO_NUMBER',
+    'ELEMENTAL_MONO_ISOTOPIC_MASSES', 'ELEMENTAL_ISOTOPIC_MASSES',
+    'ELEMENTAL_ISOTOPIC_ABUNDANCES',
+    'AMINO_ACID_MASSES', 'AMINO_ACIDS', 'AMINO_ACID_ATOMIC_COMPOSITIONS',
+    'UNIMOD_MASSES', 'UNIMOD_ATOMIC_COMPOSITIONS',
+    'one_over_k0_to_ccs', 'ccs_to_one_over_k0',
+    'ccs_to_one_over_k0_par', 'one_over_k0_to_ccs_par',
+    'SumFormula',
+    'calculate_mz', 'calculate_transmission_dependent_fragment_ion_isotope_distribution'
+]

imspy_core-0.4.0/src/imspy_core/chemistry/amino_acids.py

@@ -0,0 +1,7 @@
+import imspy_connector
+ims = imspy_connector.py_amino_acids
+
+
+AMINO_ACID_MASSES = ims.get_amino_acid_mono_isotopic_masses()
+AMINO_ACIDS = ims.get_amino_acids()
+AMINO_ACID_ATOMIC_COMPOSITIONS = ims.get_amino_acid_atomic_compositions()

imspy_core-0.4.0/src/imspy_core/chemistry/constants.py

@@ -0,0 +1,12 @@
+import imspy_connector
+ims = imspy_connector.py_constants
+
+MASS_PROTON = ims.mass_proton()
+MASS_NEUTRON = ims.mass_neutron()
+MASS_ELECTRON = ims.mass_electron()
+MASS_WATER = ims.mass_water()
+STANDARD_TEMPERATURE = ims.standard_temperature()
+STANDARD_PRESSURE = ims.standard_pressure()
+ELEMENTARY_CHARGE = ims.elementary_charge()
+K_BOLTZMANN = ims.k_boltzmann()
+AVOGADRO_NUMBER = ims.avogadro()

imspy_core-0.4.0/src/imspy_core/chemistry/elements.py

@@ -0,0 +1,6 @@
+import imspy_connector
+ims = imspy_connector.py_elements
+
+ELEMENTAL_MONO_ISOTOPIC_MASSES = ims.get_elemental_mono_isotopic_weight_map()
+ELEMENTAL_ISOTOPIC_MASSES = ims.get_elemental_isotope_weight_map()
+ELEMENTAL_ISOTOPIC_ABUNDANCES = ims.get_elemental_isotope_abundance_map()

imspy_core-0.4.0/src/imspy_core/chemistry/mobility.py

@@ -0,0 +1,82 @@
+import os
+from numpy.typing import NDArray
+import imspy_connector
+ims = imspy_connector.py_chemistry
+
+
+def one_over_k0_to_ccs(one_over_k0, mz, charge, mass_gas=28.013, temp=31.85, t_diff=273.15):
+    """Convert reduced ion mobility (1/k0) to CCS.
+
+    Args:
+        one_over_k0: reduced ion mobility
+        mz: mass-over-charge of the ion
+        charge: charge state of the ion
+        mass_gas: mass of drift gas
+        temp: temperature of the drift gas in C°
+        t_diff: factor to translate from C° to K
+
+    Returns:
+        float: collision cross-section
+    """
+    return ims.one_over_reduced_mobility_to_ccs(one_over_k0, mz, charge, mass_gas, temp, t_diff)
+
+
+def ccs_to_one_over_k0(ccs, mz, charge, mass_gas=28.013, temp=31.85, t_diff=273.15):
+    """Convert CCS to reduced ion mobility (1/k0).
+
+    Args:
+        ccs: collision cross-section
+        mz: mass-over-charge of the ion
+        charge: charge state of the ion
+        mass_gas: mass of drift gas
+        temp: temperature of the drift gas in C°
+        t_diff: factor to translate from C° to K
+
+    Returns:
+        float: reduced ion mobility
+    """
+    return ims.ccs_to_one_over_reduced_mobility(ccs, mz, charge, mass_gas, temp, t_diff)
+
+def ccs_to_one_over_k0_par(ccs: NDArray, mz: NDArray, charge: NDArray, mass_gas: float = 28.013, temp: float = 31.85,
+                          t_diff: float = 273.15, num_threads: int = -1) -> NDArray:
+    """Convert CCS to reduced ion mobility (1/k0) in parallel.
+
+    Args:
+        ccs: collision cross-section
+        mz: mass-over-charge of the ion
+        charge: charge state of the ion
+        mass_gas: mass of drift gas
+        temp: temperature of the drift gas in C°
+        t_diff: factor to translate from C° to K
+        num_threads: number of threads
+
+    Returns:
+        NDArray: reduced ion mobility
+    """
+
+    if num_threads == -1:
+        num_threads = os.cpu_count()
+
+    return ims.ccs_to_one_over_reduced_mobility_par(ccs, mz, charge, mass_gas, temp, t_diff, num_threads)
+
+def one_over_k0_to_ccs_par(one_over_k0: NDArray, mz: NDArray, charge: NDArray, mass_gas: float = 28.013, temp: float = 31.85,
+                            t_diff: float = 273.15, num_threads: int = -1) -> NDArray:
+     """Convert reduced ion mobility (1/k0) to CCS in parallel.
+
+     Args:
+          one_over_k0: reduced ion mobility
+          mz: mass-over-charge of the ion
+          charge: charge state of the ion
+          mass_gas: mass of drift gas
+          temp: temperature of the drift gas in C°
+          t_diff: factor to translate from C° to K
+          num_threads: number of threads
+
+     Returns:
+          NDArray: collision cross-section
+     """
+
+     if num_threads == -1:
+          num_threads = os.cpu_count()
+
+     return ims.one_over_reduced_mobility_to_ccs_par(one_over_k0, mz, charge, mass_gas, temp, t_diff, num_threads)

imspy_core-0.4.0/src/imspy_core/chemistry/sum_formula.py

@@ -0,0 +1,38 @@
+import imspy_connector
+
+from imspy_core.data.spectrum import MzSpectrum
+from imspy_core.core.base import RustWrapperObject
+
+ims = imspy_connector.py_sum_formula
+
+
+class SumFormula(RustWrapperObject):
+    def __init__(self, sum_formula: str):
+        self.__ptr = ims.PySumFormula(sum_formula)
+
+    @property
+    def formula(self) -> str:
+        return self.__ptr.formula
+
+    @property
+    def formula_dict(self) -> dict:
+        return self.__ptr.elements
+
+    @property
+    def monoisotopic_mass(self) -> float:
+        return self.__ptr.monoisotopic_mass
+
+    def __repr__(self):
+        return f"SumFormula('{self.formula}')"
+
+    @classmethod
+    def from_py_ptr(cls, py_ptr):
+        instance = cls.__new__(cls)
+        instance.__ptr = py_ptr
+        return instance
+
+    def get_py_ptr(self):
+        return self.__ptr
+
+    def generate_isotope_distribution(self, charge: int) -> 'MzSpectrum':
+        return MzSpectrum.from_py_ptr(self.__ptr.generate_isotope_distribution(charge))

imspy_core-0.4.0/src/imspy_core/chemistry/unimod.py

@@ -0,0 +1,5 @@
+import imspy_connector
+ims = imspy_connector.py_unimod
+
+UNIMOD_MASSES = ims.get_unimod_masses()
+UNIMOD_ATOMIC_COMPOSITIONS = ims.get_unimod_atomic_compositions()

imspy_core-0.4.0/src/imspy_core/chemistry/utility.py

@@ -0,0 +1,43 @@
+import imspy_connector
+
+from imspy_core.data.spectrum import MzSpectrum
+
+ims = imspy_connector.py_chemistry
+
+
+def calculate_mz(mass: float, charge: int) -> float:
+    """Calculate m/z value.
+
+    Args:
+        mass (float): Mass.
+        charge (int): Charge.
+
+    Returns:
+        float: m/z value.
+    """
+    return ims.calculate_mz(mass, charge)
+
+
+def calculate_transmission_dependent_fragment_ion_isotope_distribution(
+        target_spec: MzSpectrum,
+        complement_spec: MzSpectrum,
+        transmitted_isotopes: MzSpectrum,
+        max_isotope: int) -> MzSpectrum:
+    """Calculate transmission dependent fragment ion isotope distribution.
+
+    Args:
+        target_spec (MzSpectrum): Target spectrum.
+        complement_spec (MzSpectrum): Complement spectrum.
+        transmitted_isotopes (MzSpectrum): Transmitted isotopes.
+        max_isotope (int): Maximum isotope.
+
+    Returns:
+        MzSpectrum: Transmission dependent fragment ion isotope distribution.
+    """
+    return MzSpectrum.from_py_ptr(
+        ims.calculate_transmission_dependent_fragment_ion_isotope_distribution(
+            target_spec.get_py_ptr(),
+            complement_spec.get_py_ptr(),
+            transmitted_isotopes.get_py_ptr(), max_isotope
+        )
+    )

imspy_core-0.4.0/src/imspy_core/core/__init__.py

@@ -0,0 +1,9 @@
+"""
+Core module for imspy_core.
+
+Contains base classes and utilities used across the package.
+"""
+
+from .base import RustWrapperObject
+
+__all__ = ['RustWrapperObject']

imspy_core-0.4.0/src/imspy_core/core/base.py

@@ -0,0 +1,38 @@
+"""
+Base classes for imspy_core.
+
+This module contains base classes used across the package,
+separated to avoid circular imports.
+"""
+
+from abc import ABC, abstractmethod
+
+
+class RustWrapperObject(ABC):
+    """Abstract base class for Python wrappers around Rust objects.
+
+    All classes that wrap PyO3 Rust objects should inherit from this
+    and implement from_py_ptr and get_py_ptr methods.
+    """
+
+    @classmethod
+    @abstractmethod
+    def from_py_ptr(cls, obj):
+        """Create a Python wrapper from a PyO3 pointer.
+
+        Args:
+            obj: The PyO3 Rust object pointer.
+
+        Returns:
+            An instance of the wrapper class.
+        """
+        pass
+
+    @abstractmethod
+    def get_py_ptr(self):
+        """Get the underlying PyO3 Rust object pointer.
+
+        Returns:
+            The PyO3 Rust object pointer.
+        """
+        pass

imspy_core-0.4.0/src/imspy_core/data/__init__.py

@@ -0,0 +1,17 @@
+"""
+Data module for imspy_core.
+
+Contains spectrum and peptide data structures.
+"""
+
+from .spectrum import MzSpectrum, IndexedMzSpectrum, MzSpectrumVectorized, TimsSpectrum
+from .peptide import (
+    PeptideSequence, PeptideIon, PeptideProductIon,
+    PeptideProductIonSeries, PeptideProductIonSeriesCollection
+)
+
+__all__ = [
+    'MzSpectrum', 'IndexedMzSpectrum', 'MzSpectrumVectorized', 'TimsSpectrum',
+    'PeptideSequence', 'PeptideIon', 'PeptideProductIon',
+    'PeptideProductIonSeries', 'PeptideProductIonSeriesCollection'
+]