imspy-core 0.4.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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/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/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'
+]