CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pyopenms

Python wrapper for C++ LC-MS library OpenMS for comprehensive mass spectrometry data analysis

—

Pending
Overview
Eval results
Files

chemistry.mddocs/

Chemistry and Molecular Properties

Chemical calculations including empirical formulas, isotope distributions, elemental compositions, and theoretical spectrum generation. Essential for accurate mass calculations and spectral interpretation.

Capabilities

Molecular Formulas

EmpiricalFormula

Chemical formula representation with isotope support and mass calculations.

class EmpiricalFormula:
    def __init__(self, formula: str = "") -> None:
        """
        Create empirical formula.
        
        Args:
            formula (str): Chemical formula string (e.g., "C6H12O6")
        """
    
    def getMonoWeight(self) -> float:
        """
        Get monoisotopic molecular weight.
        
        Returns:
            float: Monoisotopic weight in Da
        """
    
    def getAverageWeight(self) -> float:
        """
        Get average molecular weight.
        
        Returns:
            float: Average weight in Da
        """
    
    def toString(self) -> str:
        """
        Get formula as string.
        
        Returns:
            str: Chemical formula string
        """
    
    def isEmpty(self) -> bool:
        """
        Check if formula is empty.
        
        Returns:
            bool: True if empty formula
        """
    
    def getNumberOf(self, element: str) -> int:
        """
        Get number of atoms for element.
        
        Args:
            element (str): Element symbol
            
        Returns:
            int: Number of atoms
        """
    
    def setNumberOf(self, element: str, number: int) -> None:
        """
        Set number of atoms for element.
        
        Args:
            element (str): Element symbol
            number (int): Number of atoms
        """
    
    def getNumberOfAtoms(self) -> int:
        """
        Get total number of atoms.
        
        Returns:
            int: Total atom count
        """
    
    def getElements(self) -> set[str]:
        """
        Get all elements in formula.
        
        Returns:
            set[str]: Set of element symbols
        """
    
    def __add__(self, other: EmpiricalFormula) -> EmpiricalFormula:
        """
        Add formulas.
        
        Args:
            other (EmpiricalFormula): Formula to add
            
        Returns:
            EmpiricalFormula: Sum of formulas
        """
    
    def __sub__(self, other: EmpiricalFormula) -> EmpiricalFormula:
        """
        Subtract formulas.
        
        Args:
            other (EmpiricalFormula): Formula to subtract
            
        Returns:
            EmpiricalFormula: Difference of formulas
        """
    
    def __mul__(self, factor: int) -> EmpiricalFormula:
        """
        Multiply formula by factor.
        
        Args:
            factor (int): Multiplication factor
            
        Returns:
            EmpiricalFormula: Multiplied formula
        """
    
    @staticmethod
    def fromString(formula: str) -> EmpiricalFormula:
        """
        Parse formula from string.
        
        Args:
            formula (str): Formula string
            
        Returns:
            EmpiricalFormula: Parsed formula
        """

Elements and Isotopes

Element

Chemical element with isotope information.

class Element:
    def __init__(self) -> None: ...
    
    def getName(self) -> str:
        """
        Get element name.
        
        Returns:
            str: Full element name
        """
    
    def setName(self, name: str) -> None:
        """
        Set element name.
        
        Args:
            name (str): Element name
        """
    
    def getSymbol(self) -> str:
        """
        Get element symbol.
        
        Returns:
            str: Chemical symbol
        """
    
    def setSymbol(self, symbol: str) -> None:
        """
        Set element symbol.
        
        Args:
            symbol (str): Chemical symbol
        """
    
    def getAtomicNumber(self) -> int:
        """
        Get atomic number.
        
        Returns:
            int: Atomic number
        """
    
    def setAtomicNumber(self, number: int) -> None:
        """
        Set atomic number.
        
        Args:
            number (int): Atomic number
        """
    
    def getAverageWeight(self) -> float:
        """
        Get average atomic weight.
        
        Returns:
            float: Average weight in Da
        """
    
    def setAverageWeight(self, weight: float) -> None:
        """
        Set average weight.
        
        Args:
            weight (float): Average weight
        """
    
    def getMonoWeight(self) -> float:
        """
        Get monoisotopic weight.
        
        Returns:
            float: Monoisotopic weight in Da
        """
    
    def setMonoWeight(self, weight: float) -> None:
        """
        Set monoisotopic weight.
        
        Args:
            weight (float): Monoisotopic weight
        """
    
    def getIsotopeDistribution(self) -> IsotopeDistribution:
        """
        Get natural isotope distribution.
        
        Returns:
            IsotopeDistribution: Isotope distribution
        """
    
    def setIsotopeDistribution(self, distribution: IsotopeDistribution) -> None:
        """
        Set isotope distribution.
        
        Args:
            distribution (IsotopeDistribution): Isotope distribution
        """

class ElementDB:
    @staticmethod
    def getInstance() -> ElementDB:
        """
        Get singleton instance.
        
        Returns:
            ElementDB: Element database instance
        """
    
    def getElement(self, name: str) -> Element:
        """
        Get element by name or symbol.
        
        Args:
            name (str): Element name or symbol
            
        Returns:
            Element: Chemical element
        """
    
    def hasElement(self, name: str) -> bool:
        """
        Check if element exists.
        
        Args:
            name (str): Element name or symbol
            
        Returns:
            bool: True if element exists
        """
    
    def getNames(self) -> list[str]:
        """
        Get all element names.
        
        Returns:
            list[str]: Element names
        """
    
    def getSymbols(self) -> list[str]:
        """
        Get all element symbols.
        
        Returns:
            list[str]: Element symbols
        """

Isotope Distributions

IsotopeDistribution

Theoretical and experimental isotope pattern calculations.

class IsotopeDistribution:
    def __init__(self) -> None: ...
    
    def set(self, formula: EmpiricalFormula) -> None:
        """
        Set distribution from empirical formula.
        
        Args:
            formula (EmpiricalFormula): Molecular formula
        """
    
    def getContainer(self) -> list[Peak1D]:
        """
        Get isotope peaks.
        
        Returns:
            list[Peak1D]: Isotope peaks with m/z and intensity
        """
    
    def setContainer(self, peaks: list[Peak1D]) -> None:
        """
        Set isotope peaks.
        
        Args:
            peaks (list[Peak1D]): Isotope peaks
        """
    
    def getMax(self) -> Peak1D:
        """
        Get most abundant isotope peak.
        
        Returns:
            Peak1D: Monoisotopic or most abundant peak
        """
    
    def getMin(self) -> Peak1D:
        """
        Get least abundant isotope peak.
        
        Returns:
            Peak1D: Least abundant peak
        """
    
    def getMostAbundant(self) -> Peak1D:
        """
        Get most abundant peak.
        
        Returns:
            Peak1D: Most abundant isotope peak
        """
    
    def size(self) -> int:
        """
        Get number of isotope peaks.
        
        Returns:
            int: Peak count
        """
    
    def empty(self) -> bool:
        """
        Check if distribution is empty.
        
        Returns:
            bool: True if empty
        """
    
    def clear(self) -> None:
        """Clear isotope distribution."""
    
    def normalize(self) -> None:
        """Normalize peak intensities to sum to 1."""
    
    def sort(self) -> None:
        """Sort peaks by m/z."""
    
    def trimIntensity(self, cutoff: float) -> None:
        """
        Remove peaks below intensity cutoff.
        
        Args:
            cutoff (float): Intensity cutoff (0-1)
        """
    
    def __add__(self, other: IsotopeDistribution) -> IsotopeDistribution:
        """
        Convolve with another distribution.
        
        Args:
            other (IsotopeDistribution): Distribution to convolve
            
        Returns:
            IsotopeDistribution: Convolved distribution
        """

class CoarseIsotopePatternGenerator:
    def __init__(self) -> None: ...
    
    def run(self, formula: EmpiricalFormula, dist: IsotopeDistribution) -> None:
        """
        Generate coarse isotope pattern.
        
        Args:
            formula (EmpiricalFormula): Molecular formula
            dist (IsotopeDistribution): Output distribution
        """
    
    def getParameters(self) -> Param:
        """Get generator parameters."""
    
    def setParameters(self, param: Param) -> None:
        """Set generator parameters."""

class FineIsotopePatternGenerator:
    def __init__(self) -> None: ...
    
    def run(self, formula: EmpiricalFormula, dist: IsotopeDistribution) -> None:
        """
        Generate fine isotope pattern.
        
        Args:
            formula (EmpiricalFormula): Molecular formula
            dist (IsotopeDistribution): Output distribution
        """
    
    def getParameters(self) -> Param:
        """Get generator parameters."""
    
    def setParameters(self, param: Param) -> None:
        """Set generator parameters."""

Theoretical Spectrum Generation

TheoreticalSpectrumGenerator

Generate theoretical MS/MS spectra from peptide sequences.

class TheoreticalSpectrumGenerator:
    def __init__(self) -> None: ...
    
    def getSpectrum(self, spectrum: MSSpectrum, peptide: AASequence, 
                    charge: int, intensity: float) -> None:
        """
        Generate theoretical spectrum for peptide.
        
        Args:
            spectrum (MSSpectrum): Output spectrum
            peptide (AASequence): Peptide sequence
            charge (int): Precursor charge
            intensity (float): Base peak intensity
        """
    
    def addPeaks(self, spectrum: MSSpectrum, peptide: AASequence, 
                 residue_type: Residue.ResidueType, charge: int) -> None:
        """
        Add specific fragment ion peaks.
        
        Args:
            spectrum (MSSpectrum): Output spectrum
            peptide (AASequence): Peptide sequence
            residue_type (Residue.ResidueType): Fragment type (b, y, etc.)
            charge (int): Fragment charge
        """
    
    def getParameters(self) -> Param:
        """
        Get generation parameters.
        
        Returns:
            Param: Parameters for ion types, charges, etc.
        """
    
    def setParameters(self, param: Param) -> None:
        """
        Set generation parameters.
        
        Args:
            param (Param): Generation parameters
        """
    
    def addAbundantImmoniumIons(self, spectrum: MSSpectrum, peptide: AASequence, 
                                intensity: float) -> None:
        """
        Add immonium ion peaks.
        
        Args:
            spectrum (MSSpectrum): Output spectrum
            peptide (AASequence): Peptide sequence
            intensity (float): Base intensity
        """
    
    def addPrecursorPeaks(self, spectrum: MSSpectrum, peptide: AASequence, 
                          charge: int, intensity: float) -> None:
        """
        Add precursor ion peaks.
        
        Args:
            spectrum (MSSpectrum): Output spectrum
            peptide (AASequence): Peptide sequence
            charge (int): Precursor charge
            intensity (float): Base intensity
        """

Mass Decomposition

MassDecompositionAlgorithm

Find possible elemental compositions for given masses.

class MassDecompositionAlgorithm:
    def __init__(self) -> None: ...
    
    def getDecompositions(self, mass: float, tolerance: float) -> list[MassDecomposition]:
        """
        Get possible decompositions for mass.
        
        Args:
            mass (float): Target mass
            tolerance (float): Mass tolerance
            
        Returns:
            list[MassDecomposition]: Possible compositions
        """
    
    def getParameters(self) -> Param:
        """Get algorithm parameters."""
    
    def setParameters(self, param: Param) -> None:
        """Set algorithm parameters."""

class MassDecomposition:
    def __init__(self) -> None: ...
    
    def getFormula(self) -> EmpiricalFormula:
        """
        Get empirical formula.
        
        Returns:
            EmpiricalFormula: Chemical formula
        """
    
    def getMass(self) -> float:
        """
        Get calculated mass.
        
        Returns:
            float: Mass in Da
        """
    
    def getMassError(self) -> float:
        """
        Get mass error.
        
        Returns:
            float: Mass error in Da
        """
    
    def getNumberOfAtoms(self) -> int:
        """
        Get total atom count.
        
        Returns:
            int: Number of atoms
        """

Chemical Constants

Constants

Physical and chemical constants for mass spectrometry.

class Constants:
    # Fundamental constants
    AVOGADRO = 6.02214179e23
    ELEMENTARY_CHARGE = 1.602176487e-19
    
    # Mass constants (in Da)
    C13C12_MASSDIFF_U = 1.0033548378
    H2H_MASSDIFF_U = 1.006276744
    N15N14_MASSDIFF_U = 0.997035
    O18O16_MASSDIFF_U = 2.0042463
    S34S32_MASSDIFF_U = 1.995797
    
    # Proton mass
    PROTON_MASS_U = 1.007276466812
    
    # Electron mass
    ELECTRON_MASS_U = 0.00054857990907
    
    # Neutron mass
    NEUTRON_MASS_U = 1.00866491588
    
    # Common modifications (mass shifts in Da)
    MOD_OXIDATION_M = 15.994915
    MOD_CARBAMIDOMETHYL_C = 57.021464
    MOD_ACETYL_NTERM = 42.010565
    MOD_AMIDATION_CTERM = -0.984016
    MOD_DEAMIDATION_NQ = 0.984016
    MOD_PHOSPHORYLATION_STY = 79.966331
    
    @staticmethod
    def calculateMZ(mass: float, charge: int) -> float:
        """
        Calculate m/z from mass and charge.
        
        Args:
            mass (float): Neutral mass in Da
            charge (int): Charge state
            
        Returns:
            float: m/z value
        """
    
    @staticmethod
    def calculateMass(mz: float, charge: int) -> float:
        """
        Calculate neutral mass from m/z and charge.
        
        Args:
            mz (float): m/z value
            charge (int): Charge state
            
        Returns:
            float: Neutral mass in Da
        """

Usage Examples

Empirical Formula Calculations

import pyopenms

# Create empirical formulas
glucose = pyopenms.EmpiricalFormula("C6H12O6")
water = pyopenms.EmpiricalFormula("H2O")

print(f"Glucose: {glucose.toString()}")
print(f"Monoisotopic weight: {glucose.getMonoWeight():.6f} Da")
print(f"Average weight: {glucose.getAverageWeight():.6f} Da")
print(f"Number of atoms: {glucose.getNumberOfAtoms()}")

# Formula arithmetic
dehydrated = glucose - water
print(f"Glucose - H2O: {dehydrated.toString()}")
print(f"Weight: {dehydrated.getMonoWeight():.6f} Da")

# Multiply formula
glucose_polymer = glucose * 10
print(f"(Glucose)10: {glucose_polymer.toString()}")
print(f"Weight: {glucose_polymer.getMonoWeight():.2f} Da")

# Access individual elements
print(f"Carbon atoms in glucose: {glucose.getNumberOf('C')}")
print(f"Elements: {glucose.getElements()}")

Isotope Distribution Calculations

import pyopenms

# Calculate isotope distribution for peptide
peptide_formula = pyopenms.EmpiricalFormula("C43H66N12O12S")

# Generate coarse isotope pattern
generator = pyopenms.CoarseIsotopePatternGenerator()
isotope_dist = pyopenms.IsotopeDistribution()
generator.run(peptide_formula, isotope_dist)

print(f"Isotope peaks: {isotope_dist.size()}")

# Get isotope peaks
peaks = isotope_dist.getContainer()
for i, peak in enumerate(peaks):
    print(f"Peak {i}: m/z {peak.getMZ():.6f}, intensity {peak.getIntensity():.4f}")

# Get most abundant peak
most_abundant = isotope_dist.getMostAbundant()
print(f"Most abundant: m/z {most_abundant.getMZ():.6f}")

# Fine isotope pattern for higher accuracy
fine_generator = pyopenms.FineIsotopePatternGenerator()
fine_dist = pyopenms.IsotopeDistribution()
fine_generator.run(peptide_formula, fine_dist)

print(f"Fine isotope peaks: {fine_dist.size()}")

Theoretical Spectrum Generation

import pyopenms

# Create peptide sequence
peptide = pyopenms.AASequence.fromString("PEPTIDER")

# Generate theoretical spectrum
generator = pyopenms.TheoreticalSpectrumGenerator()

# Configure parameters
params = generator.getParameters()
params.setValue("add_b_ions", "true")
params.setValue("add_y_ions", "true") 
params.setValue("add_a_ions", "false")
params.setValue("add_c_ions", "false")
params.setValue("add_x_ions", "false")
params.setValue("add_z_ions", "false")
params.setValue("add_losses", "true")
params.setValue("add_metainfo", "true")
generator.setParameters(params)

# Generate spectrum for charge 2
spectrum = pyopenms.MSSpectrum()
generator.getSpectrum(spectrum, peptide, 2, 100.0)

print(f"Generated {spectrum.size()} theoretical peaks")

# Display peaks
mz_array, intensity_array = spectrum.get_peaks()
for i in range(min(10, len(mz_array))):
    print(f"Peak {i+1}: m/z {mz_array[i]:.4f}, intensity {intensity_array[i]:.1f}")

# Add specific fragment types
b_spectrum = pyopenms.MSSpectrum()
generator.addPeaks(b_spectrum, peptide, pyopenms.Residue.BIon, 1)
print(f"B-ion peaks: {b_spectrum.size()}")

y_spectrum = pyopenms.MSSpectrum()
generator.addPeaks(y_spectrum, peptide, pyopenms.Residue.YIon, 1)
print(f"Y-ion peaks: {y_spectrum.size()}")

Element Database Usage

import pyopenms

# Access element database
element_db = pyopenms.ElementDB.getInstance()

# Get element information
carbon = element_db.getElement("C")
print(f"Carbon:")
print(f"  Name: {carbon.getName()}")
print(f"  Symbol: {carbon.getSymbol()}")
print(f"  Atomic number: {carbon.getAtomicNumber()}")
print(f"  Average weight: {carbon.getAverageWeight():.6f} Da")
print(f"  Monoisotopic weight: {carbon.getMonoWeight():.6f} Da")

# Check element existence
print(f"Has carbon: {element_db.hasElement('C')}")
print(f"Has unknown element: {element_db.hasElement('Xx')}")

# Get all elements
symbols = element_db.getSymbols()
print(f"Available elements: {len(symbols)}")
print(f"First 10 symbols: {symbols[:10]}")

Mass Decomposition

import pyopenms

# Set up mass decomposition
decomposer = pyopenms.MassDecompositionAlgorithm()

# Configure elements and ranges
params = decomposer.getParameters()
params.setValue("tolerance", 0.01)  # 10 mDa tolerance
params.setValue("charge_min", 1)
params.setValue("charge_max", 3)
decomposer.setParameters(params)

# Find decompositions for a given mass
target_mass = 1234.5678
decompositions = decomposer.getDecompositions(target_mass, 0.01)

print(f"Found {len(decompositions)} possible compositions for mass {target_mass}")

for i, decomp in enumerate(decompositions[:10]):  # Show first 10
    formula = decomp.getFormula()
    mass = decomp.getMass()
    error = decomp.getMassError()
    atoms = decomp.getNumberOfAtoms()
    
    print(f"{i+1}. {formula.toString()}")
    print(f"   Mass: {mass:.6f} Da (error: {error*1000:.2f} mDa)")
    print(f"   Atoms: {atoms}")

Constants and Conversions

import pyopenms

# Use predefined constants
print(f"Proton mass: {pyopenms.Constants.PROTON_MASS_U:.9f} Da")
print(f"Electron mass: {pyopenms.Constants.ELECTRON_MASS_U:.9f} Da")
print(f"C13-C12 mass difference: {pyopenms.Constants.C13C12_MASSDIFF_U:.9f} Da")

# Common modifications
print(f"Oxidation (+O): {pyopenms.Constants.MOD_OXIDATION_M:.6f} Da")
print(f"Carbamidomethylation: {pyopenms.Constants.MOD_CARBAMIDOMETHYL_C:.6f} Da")
print(f"Acetylation (N-term): {pyopenms.Constants.MOD_ACETYL_NTERM:.6f} Da")

# Mass/charge conversions
neutral_mass = 1000.0
charge = 2

mz = pyopenms.Constants.calculateMZ(neutral_mass, charge)
print(f"Mass {neutral_mass} Da at charge {charge} -> m/z {mz:.6f}")

back_to_mass = pyopenms.Constants.calculateMass(mz, charge)
print(f"m/z {mz:.6f} at charge {charge} -> mass {back_to_mass:.6f} Da")

# Calculate m/z for different charge states
for z in range(1, 5):
    mz_z = pyopenms.Constants.calculateMZ(neutral_mass, z)
    print(f"Charge {z}: m/z {mz_z:.4f}")

Formula from Sequence

import pyopenms

# Get formula for peptide sequence
peptide = pyopenms.AASequence.fromString("PEPTIDER")
formula = peptide.getFormula()

print(f"Peptide: {peptide.toString()}")
print(f"Formula: {formula.toString()}")
print(f"Monoisotopic mass: {formula.getMonoWeight():.6f} Da")

# Add modifications and see formula change
modified_peptide = pyopenms.AASequence.fromString("PEPTIDEM(Oxidation)R")
modified_formula = modified_peptide.getFormula()

print(f"Modified peptide: {modified_peptide.toString()}")
print(f"Modified formula: {modified_formula.toString()}")
print(f"Modified mass: {modified_formula.getMonoWeight():.6f} Da")

# Calculate mass difference
mass_diff = modified_formula.getMonoWeight() - formula.getMonoWeight()
print(f"Mass difference: {mass_diff:.6f} Da")
print(f"Expected oxidation: {pyopenms.Constants.MOD_OXIDATION_M:.6f} Da")

Install with Tessl CLI

npx tessl i tessl/pypi-pyopenms

docs

alignment.md

chemistry.md

feature-detection.md

file-io.md

index.md

ms-data.md

peptide-protein.md

targeted-analysis.md

tile.json