tessl/pypi-pyopenms
Python wrapper for C++ LC-MS library OpenMS for comprehensive mass spectrometry data analysis
—
Pending
ms-data.mddocs/
MS Data Structures
Core data structures for representing mass spectrometry experiments, spectra, and chromatograms. These classes provide the foundation for all MS data processing in pyOpenMS with efficient data access patterns and numpy integration.
Capabilities
MS Experiment Container
MSExperiment
Central container for complete LC-MS experiments including spectra, chromatograms, and metadata.
class MSExperiment:
def __init__(self) -> None: ...
def size(self) -> int:
"""
Get number of spectra in experiment.
Returns:
int: Number of spectra
"""
def empty(self) -> bool:
"""
Check if experiment is empty.
Returns:
bool: True if no spectra, False otherwise
"""
def getSpectrum(self, index: int) -> MSSpectrum:
"""
Get spectrum by index.
Args:
index (int): Spectrum index
Returns:
MSSpectrum: The spectrum at the given index
"""
def addSpectrum(self, spectrum: MSSpectrum) -> None:
"""
Add spectrum to experiment.
Args:
spectrum (MSSpectrum): Spectrum to add
"""
def removeSpectrum(self, index: int) -> None:
"""
Remove spectrum at index.
Args:
index (int): Index of spectrum to remove
"""
def getChromatograms(self) -> list[MSChromatogram]:
"""
Get all chromatograms.
Returns:
list[MSChromatogram]: List of chromatograms
"""
def addChromatogram(self, chromatogram: MSChromatogram) -> None:
"""
Add chromatogram to experiment.
Args:
chromatogram (MSChromatogram): Chromatogram to add
"""
def updateRanges(self) -> None:
"""Update RT/m/z ranges from contained spectra."""
def getMinRT(self) -> float:
"""Get minimum retention time."""
def getMaxRT(self) -> float:
"""Get maximum retention time."""
def getMinMZ(self) -> float:
"""Get minimum m/z value."""
def getMaxMZ(self) -> float:
"""Get maximum m/z value."""
def getMSLevels(self) -> list[int]:
"""
Get all MS levels present in experiment.
Returns:
list[int]: List of MS levels
"""
def get_df(self, ms_levels: list[int] = [], long: bool = False) -> DataFrame:
"""
Export experiment data to pandas DataFrame.
Args:
ms_levels (list[int]): MS levels to include (empty = all)
long (bool): Long format with one row per peak
Returns:
DataFrame: Experiment data in tabular format
"""
def get2DPeakData(self, min_rt: float, max_rt: float,
min_mz: float, max_mz: float, ms_level: int) -> tuple[list[float], list[float], list[float]]:
"""
Extract peak data as separate arrays for specified RT/m/z ranges.
Args:
min_rt (float): Minimum retention time
max_rt (float): Maximum retention time
min_mz (float): Minimum m/z
max_mz (float): Maximum m/z
ms_level (int): MS level to extract
Returns:
tuple: (rt_array, mz_array, intensity_array) as separate lists
"""
def get2DPeakDataPerSpectrum(self, min_rt: float, max_rt: float,
min_mz: float, max_mz: float, ms_level: int) -> tuple[list[float], list[list[float]], list[list[float]]]:
"""
Extract peak data organized per spectrum for specified ranges.
Args:
min_rt (float): Minimum retention time
max_rt (float): Maximum retention time
min_mz (float): Minimum m/z
max_mz (float): Maximum m/z
ms_level (int): MS level to extract
Returns:
tuple: (rt_array, mz_per_spectrum, intensity_per_spectrum)
"""
def get2DPeakDataIM(self, min_rt: float, max_rt: float, min_mz: float, max_mz: float,
ms_level: int) -> tuple[list[float], list[float], list[float], list[float]]:
"""
Extract peak data including ion mobility information.
Args:
min_rt (float): Minimum retention time
max_rt (float): Maximum retention time
min_mz (float): Minimum m/z
max_mz (float): Maximum m/z
ms_level (int): MS level to extract
Returns:
tuple: (rt_array, mz_array, intensity_array, ion_mobility_array)
"""
def aggregateFromMatrix(self, ranges: Matrix, ms_level: int, mz_agg: str) -> list[list[float]]:
"""
Aggregate intensity values for multiple m/z and RT ranges specified in a matrix.
Args:
ranges (Matrix): Matrix defining RT and m/z ranges
ms_level (int): MS level to process
mz_agg (str): Aggregation method ("sum", "mean", "max", etc.)
Returns:
list[list[float]]: Aggregated intensity values per range
"""
def extractXICsFromMatrix(self, ranges: Matrix, ms_level: int, mz_agg: str) -> list[MSChromatogram]:
"""
Extract XIC chromatograms for multiple m/z and RT ranges specified in a matrix.
Args:
ranges (Matrix): Matrix defining RT and m/z ranges
ms_level (int): MS level to process
mz_agg (str): Aggregation method for m/z ranges
Returns:
list[MSChromatogram]: Extracted ion chromatograms
"""
def getNrSpectra(self) -> int:
"""
Get number of spectra in experiment.
Returns:
int: Number of spectra
"""
def getNrChromatograms(self) -> int:
"""
Get number of chromatograms in experiment.
Returns:
int: Number of chromatograms
"""
def getSize(self) -> int:
"""
Get total number of peaks across all spectra.
Returns:
int: Total peak count
"""
def calculateTIC(self) -> MSChromatogram:
"""
Calculate total ion chromatogram.
Returns:
MSChromatogram: Total ion chromatogram
"""
def sortSpectra(self, sort_mz: bool = False) -> None:
"""
Sort spectra by retention time.
Args:
sort_mz (bool): Also sort peaks within spectra by m/z
"""
def sortChromatograms(self, sort_rt: bool = False) -> None:
"""
Sort chromatograms by m/z.
Args:
sort_rt (bool): Also sort data points within chromatograms by RT
"""Individual Spectrum
MSSpectrum
Individual mass spectrum with peaks, metadata, and processing information.
class MSSpectrum:
def __init__(self) -> None: ...
def size(self) -> int:
"""
Get number of peaks in spectrum.
Returns:
int: Number of peaks
"""
def empty(self) -> bool:
"""
Check if spectrum is empty.
Returns:
bool: True if no peaks, False otherwise
"""
def getRT(self) -> float:
"""
Get retention time.
Returns:
float: Retention time in seconds
"""
def setRT(self, rt: float) -> None:
"""
Set retention time.
Args:
rt (float): Retention time in seconds
"""
def getMSLevel(self) -> int:
"""
Get MS level.
Returns:
int: MS level (1, 2, etc.)
"""
def setMSLevel(self, level: int) -> None:
"""
Set MS level.
Args:
level (int): MS level
"""
def get_peaks(self) -> tuple[np.ndarray, np.ndarray]:
"""
Get peak data as numpy arrays.
Returns:
tuple: (mz_array, intensity_array)
"""
def set_peaks(self, mz: np.ndarray, intensity: np.ndarray) -> None:
"""
Set peak data from numpy arrays.
Args:
mz (np.ndarray): m/z values
intensity (np.ndarray): Intensity values
"""
def getPrecursors(self) -> list[Precursor]:
"""
Get precursor information (for MS2+ spectra).
Returns:
list[Precursor]: List of precursors
"""
def setPrecursors(self, precursors: list[Precursor]) -> None:
"""
Set precursor information.
Args:
precursors (list[Precursor]): List of precursors
"""
def getProducts(self) -> list[Product]:
"""
Get product information.
Returns:
list[Product]: List of products
"""
def getNativeID(self) -> str:
"""
Get native spectrum ID.
Returns:
str: Native ID
"""
def setNativeID(self, id: str) -> None:
"""
Set native spectrum ID.
Args:
id (str): Native ID
"""
def getInstrumentSettings(self) -> InstrumentSettings:
"""
Get instrument settings.
Returns:
InstrumentSettings: Instrument configuration
"""
def getAcquisitionInfo(self) -> AcquisitionInfo:
"""
Get acquisition information.
Returns:
AcquisitionInfo: Acquisition metadata
"""
def getDriftTime(self) -> float:
"""
Get ion mobility drift time.
Returns:
float: Drift time value
"""
def setDriftTime(self, dt: float) -> None:
"""
Set ion mobility drift time.
Args:
dt (float): Drift time value
"""
def getDriftTimeUnit(self) -> DriftTimeUnit:
"""
Get drift time unit.
Returns:
DriftTimeUnit: Unit of drift time measurement
"""
def setDriftTimeUnit(self, unit: DriftTimeUnit) -> None:
"""
Set drift time unit.
Args:
unit (DriftTimeUnit): Unit of drift time measurement
"""
def getFloatDataArrays(self) -> list[FloatDataArray]:
"""
Get float data arrays (additional peak annotations).
Returns:
list[FloatDataArray]: List of float data arrays
"""
def setFloatDataArrays(self, arrays: list[FloatDataArray]) -> None:
"""
Set float data arrays.
Args:
arrays (list[FloatDataArray]): List of float data arrays
"""
def getStringDataArrays(self) -> list[StringDataArray]:
"""
Get string data arrays (additional peak annotations).
Returns:
list[StringDataArray]: List of string data arrays
"""
def setStringDataArrays(self, arrays: list[StringDataArray]) -> None:
"""
Set string data arrays.
Args:
arrays (list[StringDataArray]): List of string data arrays
"""
def getIntegerDataArrays(self) -> list[IntegerDataArray]:
"""
Get integer data arrays (additional peak annotations).
Returns:
list[IntegerDataArray]: List of integer data arrays
"""
def setIntegerDataArrays(self, arrays: list[IntegerDataArray]) -> None:
"""
Set integer data arrays.
Args:
arrays (list[IntegerDataArray]): List of integer data arrays
"""
def sortByIntensity(self) -> None:
"""Sort peaks by intensity (descending)."""
def sortByPosition(self) -> None:
"""Sort peaks by m/z position."""
def sortByIonMobility(self) -> None:
"""Sort peaks by ion mobility value."""
def isSorted(self) -> bool:
"""
Check if peaks are sorted by m/z.
Returns:
bool: True if sorted by m/z
"""
def isSortedByIM(self) -> bool:
"""
Check if peaks are sorted by ion mobility.
Returns:
bool: True if sorted by ion mobility
"""
def findNearest(self, mz: float) -> int:
"""
Find peak nearest to specified m/z.
Args:
mz (float): Target m/z value
Returns:
int: Index of nearest peak (-1 if not found)
"""
def findHighestInWindow(self, mz: float, tolerance: float) -> int:
"""
Find highest peak within m/z window.
Args:
mz (float): Center m/z value
tolerance (float): m/z tolerance
Returns:
int: Index of highest peak in window (-1 if not found)
"""
def containsIMData(self) -> bool:
"""
Check if spectrum contains ion mobility data.
Returns:
bool: True if ion mobility data present
"""
def getType(self) -> SpectrumType:
"""
Determine spectrum type (profile vs centroided).
Returns:
SpectrumType: Type of spectrum data
"""
def getBasePeak(self) -> Peak1D:
"""
Get base peak (most intense peak).
Returns:
Peak1D: Base peak
"""
def calculateTIC(self) -> float:
"""
Calculate total ion current.
Returns:
float: Total ion current (sum of all intensities)
"""
def select(self, start: int, end: int) -> MSSpectrum:
"""
Select subset of peaks by index range.
Args:
start (int): Start index
end (int): End index
Returns:
MSSpectrum: New spectrum with selected peaks
"""
def get_df(self, export_meta_values: bool = True) -> DataFrame:
"""
Export spectrum to pandas DataFrame.
Args:
export_meta_values (bool): Include metadata
Returns:
DataFrame: Spectrum data in tabular format
"""Chromatogram Data
MSChromatogram
Chromatographic data over retention time for specific m/z traces or transitions.
class MSChromatogram:
def __init__(self) -> None: ...
def size(self) -> int:
"""
Get number of data points.
Returns:
int: Number of data points
"""
def empty(self) -> bool:
"""
Check if chromatogram is empty.
Returns:
bool: True if no data points, False otherwise
"""
def get_peaks(self) -> tuple[np.ndarray, np.ndarray]:
"""
Get chromatogram data as numpy arrays.
Returns:
tuple: (rt_array, intensity_array)
"""
def set_peaks(self, rt: np.ndarray, intensity: np.ndarray) -> None:
"""
Set chromatogram data from numpy arrays.
Args:
rt (np.ndarray): Retention time values
intensity (np.ndarray): Intensity values
"""
def getPrecursor(self) -> Precursor:
"""
Get precursor ion information.
Returns:
Precursor: Precursor ion data
"""
def setPrecursor(self, precursor: Precursor) -> None:
"""
Set precursor ion information.
Args:
precursor (Precursor): Precursor ion data
"""
def getProduct(self) -> Product:
"""
Get product ion information.
Returns:
Product: Product ion data
"""
def setProduct(self, product: Product) -> None:
"""
Set product ion information.
Args:
product (Product): Product ion data
"""
def getNativeID(self) -> str:
"""
Get native chromatogram ID.
Returns:
str: Native ID
"""
def setNativeID(self, id: str) -> None:
"""
Set native chromatogram ID.
Args:
id (str): Native ID
"""
def getChromatogramType(self) -> ChromatogramType:
"""
Get chromatogram type.
Returns:
ChromatogramType: Type of chromatogram
"""
def get_df(self, export_meta_values: bool = True) -> DataFrame:
"""
Export chromatogram to pandas DataFrame.
Args:
export_meta_values (bool): Include metadata
Returns:
DataFrame: Chromatogram data in tabular format
"""Peak Data Structures
Peak1D
Individual peak with m/z and intensity.
class Peak1D:
def __init__(self, mz: float = 0.0, intensity: float = 0.0) -> None:
"""
Create 1D peak.
Args:
mz (float): m/z value
intensity (float): Intensity value
"""
def getMZ(self) -> float:
"""
Get m/z value.
Returns:
float: m/z value
"""
def setMZ(self, mz: float) -> None:
"""
Set m/z value.
Args:
mz (float): m/z value
"""
def getIntensity(self) -> float:
"""
Get intensity value.
Returns:
float: Intensity value
"""
def setIntensity(self, intensity: float) -> None:
"""
Set intensity value.
Args:
intensity (float): Intensity value
"""Peak2D
Peak with retention time, m/z, and intensity coordinates.
class Peak2D:
def __init__(self, rt: float = 0.0, mz: float = 0.0, intensity: float = 0.0) -> None:
"""
Create 2D peak.
Args:
rt (float): Retention time
mz (float): m/z value
intensity (float): Intensity value
"""
def getRT(self) -> float:
"""
Get retention time.
Returns:
float: Retention time
"""
def setRT(self, rt: float) -> None:
"""
Set retention time.
Args:
rt (float): Retention time
"""
def getMZ(self) -> float:
"""
Get m/z value.
Returns:
float: m/z value
"""
def setMZ(self, mz: float) -> None:
"""
Set m/z value.
Args:
mz (float): m/z value
"""
def getIntensity(self) -> float:
"""
Get intensity value.
Returns:
float: Intensity value
"""
def setIntensity(self, intensity: float) -> None:
"""
Set intensity value.
Args:
intensity (float): Intensity value
"""Ion Information
Precursor
Precursor ion information for MS/MS spectra.
class Precursor:
def __init__(self) -> None: ...
def getMZ(self) -> float:
"""
Get precursor m/z.
Returns:
float: Precursor m/z
"""
def setMZ(self, mz: float) -> None:
"""
Set precursor m/z.
Args:
mz (float): Precursor m/z
"""
def getCharge(self) -> int:
"""
Get precursor charge.
Returns:
int: Precursor charge
"""
def setCharge(self, charge: int) -> None:
"""
Set precursor charge.
Args:
charge (int): Precursor charge
"""
def getIntensity(self) -> float:
"""
Get precursor intensity.
Returns:
float: Precursor intensity
"""
def setIntensity(self, intensity: float) -> None:
"""
Set precursor intensity.
Args:
intensity (float): Precursor intensity
"""
def getActivationMethods(self) -> set:
"""
Get activation methods used.
Returns:
set: Set of activation methods
"""
def getActivationEnergy(self) -> float:
"""
Get activation energy.
Returns:
float: Activation energy
"""Product
Product ion information for transitions and MS/MS spectra.
class Product:
def __init__(self) -> None: ...
def getMZ(self) -> float:
"""
Get product m/z.
Returns:
float: Product m/z
"""
def setMZ(self, mz: float) -> None:
"""
Set product m/z.
Args:
mz (float): Product m/z
"""
def getCharge(self) -> int:
"""
Get product charge.
Returns:
int: Product charge
"""
def setCharge(self, charge: int) -> None:
"""
Set product charge.
Args:
charge (int): Product charge
"""Instrument Settings
InstrumentSettings
Instrument configuration and acquisition parameters.
class InstrumentSettings:
def __init__(self) -> None: ...
def getScanMode(self) -> ScanMode:
"""
Get scan mode.
Returns:
ScanMode: Scan mode
"""
def setScanMode(self, mode: ScanMode) -> None:
"""
Set scan mode.
Args:
mode (ScanMode): Scan mode
"""
def getPolarity(self) -> Polarity:
"""
Get ion polarity.
Returns:
Polarity: Ion polarity
"""
def setPolarity(self, polarity: Polarity) -> None:
"""
Set ion polarity.
Args:
polarity (Polarity): Ion polarity
"""
def getScanWindows(self) -> list[ScanWindow]:
"""
Get scan windows.
Returns:
list[ScanWindow]: List of scan windows
"""Types
Data Array Types
class FloatDataArray:
def __init__(self) -> None: ...
def getName(self) -> str: ...
def setName(self, name: str) -> None: ...
def getData(self) -> list[float]: ...
def setData(self, data: list[float]) -> None: ...
class StringDataArray:
def __init__(self) -> None: ...
def getName(self) -> str: ...
def setName(self, name: str) -> None: ...
def getData(self) -> list[str]: ...
def setData(self, data: list[str]) -> None: ...
class IntegerDataArray:
def __init__(self) -> None: ...
def getName(self) -> str: ...
def setName(self, name: str) -> None: ...
def getData(self) -> list[int]: ...
def setData(self, data: list[int]) -> None: ...Enumeration Types
class DriftTimeUnit:
NONE = 0
MILLISECOND = 1
VOLT_SECOND_PER_SQUARE_CENTIMETER = 2
class SpectrumType:
UNKNOWN = 0
PROFILE = 1
CENTROIDED = 2
class ScanMode:
UNKNOWN = 0
MASS_SPECTRUM = 1
SIM = 2
SRM = 3
CRM = 4
Q1_SCAN = 5
Q3_SCAN = 6
NEUTRAL_LOSS_SCAN = 7
PRECURSOR_ION_SCAN = 8
ENHANCED_MULTIPLY_CHARGED = 9
TIME_DELAYED_FRAGMENTATION = 10
class Polarity:
UNKNOWN = 0
POSITIVE = 1
NEGATIVE = 2
class ChromatogramType:
UNKNOWN = 0
MASS_CHROMATOGRAM = 1
TIC = 2
BASEPEAK = 3
SRM = 4
SIM = 5
EIC = 6Matrix Type
class Matrix:
def __init__(self, rows: int = 0, cols: int = 0) -> None:
"""
Create matrix for range specifications.
Args:
rows (int): Number of rows
cols (int): Number of columns
"""
def getValue(self, row: int, col: int) -> float:
"""Get value at position."""
def setValue(self, row: int, col: int, value: float) -> None:
"""Set value at position."""
def rows(self) -> int:
"""Get number of rows."""
def cols(self) -> int:
"""Get number of columns."""Usage Examples
Basic Spectrum Processing
import pyopenms
import numpy as np
# Create and populate spectrum
spectrum = pyopenms.MSSpectrum()
spectrum.setRT(123.45)
spectrum.setMSLevel(1)
# Set peak data from numpy arrays
mz_array = np.array([100.1, 200.2, 300.3])
intensity_array = np.array([1000.0, 2000.0, 1500.0])
spectrum.set_peaks(mz_array, intensity_array)
# Access peak data
mz_data, intensity_data = spectrum.get_peaks()
print(f"Spectrum at RT {spectrum.getRT():.2f} has {spectrum.size()} peaks")
# Sort peaks by m/z
spectrum.sortByPosition()MS Experiment Manipulation
import pyopenms
# Create experiment and add spectra
exp = pyopenms.MSExperiment()
for i in range(10):
spectrum = pyopenms.MSSpectrum()
spectrum.setRT(i * 10.0) # RT every 10 seconds
spectrum.setMSLevel(1)
# Add some peaks
mz_array = np.array([100.0 + i, 200.0 + i, 300.0 + i])
intensity_array = np.array([1000.0, 2000.0, 1500.0])
spectrum.set_peaks(mz_array, intensity_array)
exp.addSpectrum(spectrum)
# Update ranges and get statistics
exp.updateRanges()
print(f"Experiment: {exp.size()} spectra")
print(f"RT range: {exp.getMinRT():.1f} - {exp.getMaxRT():.1f}")
print(f"m/z range: {exp.getMinMZ():.1f} - {exp.getMaxMZ():.1f}")
print(f"MS levels: {exp.getMSLevels()}")DataFrame Export
import pyopenms
# Load experiment
exp = pyopenms.MSExperiment()
pyopenms.MzMLFile().load("data.mzML", exp)
# Export to DataFrame (long format for analysis)
df = exp.get_df(long=True)
print(df.head())
# Export individual spectrum to DataFrame
spectrum = exp.getSpectrum(0)
spec_df = spectrum.get_df()
print(spec_df.head())Chromatogram Processing
import pyopenms
import numpy as np
# Create chromatogram
chrom = pyopenms.MSChromatogram()
chrom.setNativeID("TIC")
# Set chromatogram data
rt_array = np.linspace(0, 1000, 1000) # 1000 seconds
intensity_array = np.random.normal(10000, 1000, 1000) # Random intensities
chrom.set_peaks(rt_array, intensity_array)
# Set precursor information for XIC
precursor = pyopenms.Precursor()
precursor.setMZ(500.0)
chrom.setPrecursor(precursor)
# Access chromatogram data
rt_data, intensity_data = chrom.get_peaks()
print(f"Chromatogram has {chrom.size()} data points")
print(f"RT range: {rt_data[0]:.1f} - {rt_data[-1]:.1f}")Install with Tessl CLI
npx tessl i tessl/pypi-pyopenms