MSPeeps

A Python package for extracting mass spectrometry spectra from mzML files and converting them to MSP format.

Overview

This tool allows you to:

• Extract spectra from mzML files using either spectrum index or retention time
• Apply intensity cutoffs to filter peaks
• Convert SMILES to InChI and InChIKey when available
• Format the extracted data into MSP files according to standard conventions
• Process multiple spectra in batch mode via a tabular input file (TSV or Excel)
• Match peaks to molecular formulas using the fragfit package

Installation

From PyPI (Recommended)

Install the latest release from PyPI:

pip install mspeeps

From conda

conda install -c gkreder mspeeps

From Source

Clone the repository and install in development mode:

git clone https://github.com/gkreder/mspeeps.git
cd mspeeps
pip install -e .

Using pixi

If you prefer using pixi for dependency management:

git clone https://github.com/gkreder/mspeeps.git
cd mspeeps
pixi install

Usage

Command-line Interface

MSPeeps provides a flexible command-line interface with several subcommands:

mspeeps --help

Batch Processing (TSV file)

Process an input file using the default settings:

mspeeps batch input_file.tsv

Specify custom output directory and log file:

mspeeps batch input_file.tsv --output_dir my_output --log_file custom_log.log

Enable verbose logging:

mspeeps batch input_file.tsv --verbose

Extract Spectra

Extract a spectrum from an mzML file using its index:

mspeeps extract --mzml_file file.mzML --spectrum_index 123 --output spectrum.json

Extract a spectrum using retention time:

mspeeps extract --mzml_file file.mzML --retention_time 305.9 --ms_level 2 --format csv

Convert to MSP Format

Convert a JSON spectrum file to MSP:

mspeeps convert --json_file spectrum.json --output spectrum.msp

Convert separate m/z and intensity files:

mspeeps convert --mz_file mz_values.txt --intensity_file intensities.txt --output spectrum.msp

Match Formulas

Match m/z values to molecular formulas:

mspeeps match-formula --mz_values "30.03,55.05,84.08" --parent_formula "C5H11N" --tolerance 0.002

Or use a file with m/z values:

mspeeps match-formula --mz_values mz_values.txt --parent_formula "C5H11N" --format json

Convert SMILES

Convert a SMILES string to InChI and InChIKey:

mspeeps convert-smiles --smiles "N1CCCCC1"

Get mzML File Information

Get information about an mzML file:

mspeeps info --mzml_file file.mzML

Python API

import mspeeps
import pandas as pd

# Parse input file
df = mspeeps.parse_input_file("input_file.tsv")

# Process each row
for _, row in df.iterrows():
    output_path = mspeeps.process_file(row, output_dir="output")
    if output_path:
        print(f"Successfully processed: {output_path}")

# Or extract a spectrum directly
mz_array, intensity_array, metadata = mspeeps.extract_spectrum(
    mzml_path="file.mzML",
    spectrum_index=123,
    ms_level=2
)

# Format MSP data
msp_data = mspeeps.format_msp(
    mz_array,
    intensity_array,
    metadata,
    row_data={"Molecule_name": "Example"}
)

Input Format

The input should be a TSV or Excel file with the following columns:

Column Name	Description	Required?
Molecule_name	Name of the molecule	Yes
SMILES	SMILES notation	No
Molecular_formula	Chemical formula	No
Raw_Intensity_Cutoff	Cutoff for peak intensity	No (default: 0)
Formula_Matching_Tolerance	Tolerance for formula matching (in Da)	No
m/z	Precursor m/z	No
RT_seconds	Retention time in seconds	No*
RT	Retention time in minutes	No*
MS_level	MS level	No (default: 2)
Collision_energy	Collision energy used	No
mzML_filepath	Path to the mzML file	Yes
Spectrum_index	Index of the spectrum in the mzML file	No*

* Either Spectrum_index or retention time (RT_seconds/RT) must be provided.

Notes:

• If both spectrum index and RT are provided, the index is used.
• RT values in "min" format (e.g., "1.453 min") are automatically converted to seconds.

Output Format

The output is an MSP file for each spectrum with the following format:

NAME: [Molecule_name]
[Additional metadata from input file]
INCHI: [Calculated from SMILES if provided]
INCHIKEY: [Calculated from SMILES if provided]
RETENTIONTIME: [Retention time in seconds]
PRECURSORMZ: [Precursor m/z]
MSLEVEL: [MS level]
NUM PEAKS: [Number of peaks]
[m/z] [intensity]
[m/z] [intensity]
...

Formula Matching

The tool supports matching fragments in the spectrum to the closest possible molecular formula, within a specified tolerance, given the parent formula. This enables:

• Fragment Formula Assignment: Each m/z peak is annotated with its most likely molecular formula
• Exact Mass Calculation: The exact mass of each assigned formula is calculated
• Enhanced Output Format: Peak lines include formula, exact mass, and m/z difference (actual - theoretical): [m/z] [intensity] "[formula]" [exact_mass] [m/z_difference]

When formula matching is enabled, the output MSP file will look like:

NAME: Piperidine
SMILES: N1CCCCC1
MOLECULAR FORMULA: C5H11N
RAW INTENSITY CUTOFF: 100.0
FORMULA MATCHING TOLERANCE: 0.002
M/Z: 86.09643
RT SECONDS: 305.9
MS LEVEL: 2
COLLISION ENERGY: 0 V
MZML FILEPATH: /path/to/file.mzML
SPECTRUM INDEX: 576
INCHI: InChI=1S/C5H11N/c1-2-4-6-5-3-1/h6H,1-5H2
INCHIKEY: WEVYAHXRMPXWCK-UHFFFAOYSA-N
RETENTIONTIME: 5.04
PRECURSORMZ: 86.096430
MSLEVEL: 2
NUM PEAKS: 5
30.033819 2461 "CH4N" 30.033826 -0.000007
55.054611 1497 "C4H7" 55.054227 0.000384
57.070259 356 "C4H9" 57.069877 0.000382
68.049652 568 "C5H6" 68.049476 0.000176
84.080811 2834 "C5H10N" 84.080776 0.000035

Development

Running Tests

pytest

With coverage:

pytest --cov=mspeeps

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.