matchms

Matchms

概述

Matchms 是一个用于质谱数据处理和分析的开源 Python 库。可从各种格式导入光谱、标准化元数据、筛选峰、计算光谱相似度，并构建可复现的分析工作流。

核心功能

1. 导入和导出质谱数据

从多种文件格式加载光谱，并导出处理后的数据：

from matchms.importing import load_from_mgf, load_from_mzml, load_from_msp, load_from_json
from matchms.exporting import save_as_mgf, save_as_msp, save_as_json

# Import spectra
spectra = list(load_from_mgf("spectra.mgf"))
spectra = list(load_from_mzml("data.mzML"))
spectra = list(load_from_msp("library.msp"))

# Export processed spectra
save_as_mgf(spectra, "output.mgf")
save_as_json(spectra, "output.json")

支持的格式：

• mzML 和 mzXML（原始质谱格式）
• MGF（Mascot 通用格式）
• MSP（光谱库格式）
• JSON（兼容 GNPS）
• metabolomics-USI 引用
• Pickle（Python 序列化）

有关导入和导出的详细文档，请参阅 references/importing_exporting.md。

2. 光谱筛选和处理

应用全面的筛选器来标准化元数据并优化峰数据：

from matchms.filtering import default_filters, normalize_intensities
from matchms.filtering import select_by_relative_intensity, require_minimum_number_of_peaks

# Apply default metadata harmonization filters
spectrum = default_filters(spectrum)

# Normalize peak intensities
spectrum = normalize_intensities(spectrum)

# Filter peaks by relative intensity
spectrum = select_by_relative_intensity(spectrum, intensity_from=0.01, intensity_to=1.0)

# Require minimum peaks
spectrum = require_minimum_number_of_peaks(spectrum, n_required=5)

筛选类别：

• 元数据处理：统一化合物名称、推导化学结构、标准化加合物、校正电荷
• 峰筛选：归一化强度、按 m/z 或强度进行选择、移除前体峰
• 质量控制：要求达到最低峰数、验证前体 m/z、确保元数据完整
• 化学注释：添加指纹、推导 InChI/SMILES、修复结构不匹配

Matchms 提供 40 多种筛选器。如需完整的筛选器参考，请参阅 references/filtering.md。

3. 计算光谱相似度

使用各种相似度指标比较光谱：

from matchms import calculate_scores
from matchms.similarity import CosineGreedy, ModifiedCosine, CosineHungarian

# Calculate cosine similarity (fast, greedy algorithm)
scores = calculate_scores(references=library_spectra,
                         queries=query_spectra,
                         similarity_function=CosineGreedy())

# Calculate modified cosine (accounts for precursor m/z differences)
scores = calculate_scores(references=library_spectra,
                         queries=query_spectra,
                         similarity_function=ModifiedCosine(tolerance=0.1))

# Get best matches
best_matches = scores.scores_by_query(query_spectra[0], sort=True)[:10]

可用的相似度函数：

• CosineGreedy/CosineHungarian：基于峰的余弦相似度，采用不同的匹配算法
• ModifiedCosine：考虑前体质量差异的余弦相似度
• NeutralLossesCosine：基于中性丢失模式的相似度
• FingerprintSimilarity：使用指纹计算分子结构相似度
• MetadataMatch：比较用户定义的元数据字段
• PrecursorMzMatch/ParentMassMatch：基于质量的简单筛选

有关相似度函数的详细文档，请参阅 references/similarity.md。

4. 构建处理流水线

创建可复现的多步骤分析工作流：

from matchms import SpectrumProcessor
from matchms.filtering import default_filters, normalize_intensities
from matchms.filtering import select_by_relative_intensity, remove_peaks_around_precursor_mz

# Define a processing pipeline
processor = SpectrumProcessor([
    default_filters,
    normalize_intensities,
    lambda s: select_by_relative_intensity(s, intensity_from=0.01),
    lambda s: remove_peaks_around_precursor_mz(s, mz_tolerance=17)
])

# Apply to all spectra
processed_spectra = [processor(s) for s in spectra]

5. 使用 Spectrum 对象

核心 Spectrum 类包含质谱数据：

from matchms import Spectrum
import numpy as np

# Create a spectrum
mz = np.array([100.0, 150.0, 200.0, 250.0])
intensities = np.array([0.1, 0.5, 0.9, 0.3])
metadata = {"precursor_mz": 250.5, "ionmode": "positive"}

spectrum = Spectrum(mz=mz, intensities=intensities, metadata=metadata)

# Access spectrum properties
print(spectrum.peaks.mz)           # m/z values
print(spectrum.peaks.intensities)  # Intensity values
print(spectrum.get("precursor_mz")) # Metadata field

# Visualize spectra
spectrum.plot()
spectrum.plot_against(reference_spectrum)

6. 元数据管理

标准化并统一光谱元数据：

# Metadata is automatically harmonized
spectrum.set("Precursor_mz", 250.5)  # Gets harmonized to lowercase key
print(spectrum.get("precursor_mz"))   # Returns 250.5

# Derive chemical information
from matchms.filtering import derive_inchi_from_smiles, derive_inchikey_from_inchi
from matchms.filtering import add_fingerprint

spectrum = derive_inchi_from_smiles(spectrum)
spectrum = derive_inchikey_from_inchi(spectrum)
spectrum = add_fingerprint(spectrum, fingerprint_type="morgan", nbits=2048)

常见工作流

常见的质谱分析工作流包括：

• 加载并预处理光谱库
• 将未知光谱与参考库进行匹配
• 质量筛选和数据清理
• 大规模相似度比较
• 基于网络的光谱聚类

如需详细示例，请参阅 references/workflows.md。

安装

uv pip install matchms

如需处理分子结构（SMILES、InChI）：

uv pip install matchms[chemistry]

参考文档

详细参考文档位于 references/ 目录中：

• filtering.md - 完整的筛选函数参考及说明
• similarity.md - 所有相似度指标及其适用场景
• importing_exporting.md - 文件格式详情及输入/输出操作
• workflows.md - 常见分析模式和示例

根据需要加载这些参考文档，以了解 matchms 特定功能的详细信息。