/pyopenms-mass-spectrometry

name: pyopenms-mass-spectrometry
description: MS data processing with PyOpenMS for LC-MS/MS proteomics and metabolomics — mzML/mzXML I/O, signal processing (smoothing, peak picking, centroiding), feature detection/linking, peptide/protein ID with FDR, untargeted metabolomics. Use matchms for simple spectral matching.
license: BSD-3-Clause

PyOpenMS — Mass Spectrometry Analysis

Overview

PyOpenMS provides Python bindings to the OpenMS C++ library for computational mass spectrometry. It supports proteomics and metabolomics data processing including file I/O for 10+ MS formats, signal processing, feature detection, peptide/protein identification, and quantitative analysis across samples.

When to Use

• Processing raw LC-MS/MS data (mzML, mzXML) for proteomics or metabolomics
• Detecting chromatographic features and linking them across multiple samples
• Identifying peptides and proteins from MS/MS search engine results with FDR control
• Running untargeted metabolomics workflows (peak picking → feature detection → alignment → annotation)
• Converting between mass spectrometry file formats (mzML, mzXML, featureXML, idXML)
• Smoothing, filtering, and centroiding raw spectral data
• For simple spectral library matching and metabolite identification, use **matchms** instead
• For protein sequence analysis (not mass spec), use **biopython** instead

Prerequisites

uv pip install pyopenms numpy pandas matplotlib

• Python 3.8+; NumPy for peak array operations
• Input data: mzML files (standard MS format), FASTA databases (for identification)
• All algorithms follow a consistent pattern: `algo = Algorithm(); params = algo.getParameters(); params.setValue(...); algo.setParameters(params)`

Pre-flight Interview

Settle these with the user before writing any analysis code.

decisions:
  - id: D1
    param: instrumentResolution
    kind: required
    source: data
    ask: "Is this high-resolution data, and are the spectra already centroided or still in profile mode?"
    default: null

  - id: D2
    param: signalToNoiseThreshold
    kind: required
    source: user
    depends_on: [D1]
    ask: "How far above noise must a peak rise to be kept during centroiding?"
    default: 1.0
    skip_if: "spectra already centroided by the acquisition software"

  - id: D3
    param: massTolerance
    kind: required
    source: data
    depends_on: [D1]
    ask: "What mass accuracy should feature detection and linking assume?"
    default: "10 ppm"

  - id: D4
    param: retentionTimeTolerance
    kind: required
    source: data
    ask: "How far apart in retention time may the same feature appear across runs?"
    default: "100 s"

  - id: D5
    param: chargeStateRange
    kind: required
    source: user
    ask: "Which charge states should features be searched for?"
    default: "1 to 3 - widen for intact protein or metabolite work"

  - id: D6
    param: intensityNormalization
    kind: optional
    source: user
    ask: "Should spectra be normalized before comparison, and to total ion current or to the base peak?"
    default: "not normalized"

  - id: D7
    param: smoothingFilter
    kind: optional_conditional
    source: data
    ask: "Does the signal need smoothing before peak picking, and with which filter width?"
    default: "no smoothing"

D1 governs almost everything after it: profile data that skips centroiding produces one feature per scan point, and high-resolution tolerances applied to low-resolution data link features that are not the same compound. Both yield a full feature table.

Quick Start

import pyopenms as ms

# Load mzML file
exp = ms.MSExperiment()
ms.MzMLFile().load("sample.mzML", exp)
print(f"Spectra: {exp.getNrSpectra()}, Chromatograms: {exp.getNrChromatograms()}")

# Examine first spectrum
spec = exp.getSpectrum(0)
mz, intensity = spec.get_peaks()
print(f"MS level: {spec.getMSLevel()}, RT: {spec.getRT():.2f}s, Peaks: {len(mz)}")

# Quick preprocessing: smooth + centroid
gauss = ms.GaussFilter()
p = gauss.getParameters(); p.setValue("gaussian_width", 0.1); gauss.setParameters(p)
gauss.filterExperiment(exp)

picker = ms.PeakPickerHiRes()
centroided = ms.MSExperiment()
picker.pickExperiment(exp, centroided)
print(f"Centroided spectra: {centroided.getNrSpectra()}")

Core API

Module 1: File I/O & Data Access

Read and write mass spectrometry data in multiple formats.

import pyopenms as ms

# Read mzML (standard MS format)
exp = ms.MSExperiment()
ms.MzMLFile().load("data.mzML", exp)

# Indexed access for large files (memory-efficient)
loader = ms.IndexedMzMLFileLoader()
indexed_file = ms.OnDiscMSExperiment()
loader.load("large_data.mzML", indexed_file)
spec = indexed_file.getSpectrum(0)  # Load single spectrum on demand
print(f"Total spectra: {indexed_file.getNrSpectra()}")

# Read identification results (idXML)
protein_ids, peptide_ids = [], []
ms.IdXMLFile().load("results.idXML", protein_ids, peptide_ids)
print(f"Peptide IDs: {len(peptide_ids)}, Protein IDs: {len(protein_ids)}")

# Read feature map
fm = ms.FeatureMap()
ms.FeatureXMLFile().load("features.featureXML", fm)
print(f"Features: {fm.size()}")

# Write mzML with compression
exp_out = ms.MSExperiment()
# ... populate experiment ...
ms.MzMLFile().store("output.mzML", exp_out)

# Read FASTA database
entries = []
ms.FASTAFile().load("database.fasta", entries)
print(f"Proteins in DB: {len(entries)}")
for e in entries[:3]:
    print(f"  {e.identifier}: {e.sequence[:30]}...")

**Supported formats**: mzML, mzXML, mzData (spectra); featureXML, consensusXML (features); idXML, mzIdentML, pepXML (identifications); TraML (transitions); mzTab (results); FASTA (sequences)

Module 2: Signal Processing & Peak Picking

Preprocess raw spectral data for downstream analysis.

import pyopenms as ms

exp = ms.MSExperiment()
ms.MzMLFile().load("raw.mzML", exp)

# Gaussian smoothing
gauss = ms.GaussFilter()
p = gauss.getParameters()
p.set