name: matchms description: “质谱分析。处理mzML/MGF/MSP格式，光谱相似性（余弦、修改余弦），元数据协调，化合物识别，用于代谢组学和质谱数据处理。”

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

# 导入光谱
spectra = list(load_from_mgf("spectra.mgf"))
spectra = list(load_from_mzml("data.mzML"))
spectra = list(load_from_msp("library.msp"))

# 导出处理后的光谱
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

# 应用默认元数据协调过滤器
spectrum = default_filters(spectrum)

# 标准化峰值强度
spectrum = normalize_intensities(spectrum)

# 按相对强度过滤峰值
spectrum = select_by_relative_intensity(spectrum, intensity_from=0.01, intensity_to=1.0)

# 要求最小峰值数
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

# 计算余弦相似性（快速贪心算法）
scores = calculate_scores(references=library_spectra,
                         queries=query_spectra,
                         similarity_function=CosineGreedy())

# 计算修改余弦（考虑前体 m/z 差异）
scores = calculate_scores(references=library_spectra,
                         queries=query_spectra,
                         similarity_function=ModifiedCosine(tolerance=0.1))

# 获取最佳匹配
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

# 定义处理管道
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)
])

# 应用于所有光谱
processed_spectra = [processor(s) for s in spectra]

5. 使用光谱对象

核心 Spectrum 类包含质谱数据：

from matchms import Spectrum
import numpy as np

# 创建光谱
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)

# 访问光谱属性
print(spectrum.peaks.mz)           # m/z 值
print(spectrum.peaks.intensities)  # 强度值
print(spectrum.get("precursor_mz")) # 元数据字段

# 可视化光谱
spectrum.plot()
spectrum.plot_against(reference_spectrum)

6. 元数据管理

标准化和协调光谱元数据：

# 元数据自动协调
spectrum.set("Precursor_mz", 250.5)  # 被协调为小写键
print(spectrum.get("precursor_mz"))   # 返回 250.5

# 推导化学信息
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。

安装

pip install matchms

用于分子结构处理（SMILES、InChI）：

pip install matchms[chemistry]

参考文档

详细的参考文档可在 references/ 目录中找到：

filtering.md - 完整过滤器函数参考与描述
similarity.md - 所有相似性度量及使用时机
importing_exporting.md - 文件格式详情和 I/O 操作
workflows.md - 常见分析模式和示例

根据需要加载这些参考以获取特定 matchms 功能的详细信息。