matchms

Matchms

用途和范围

Matchms 是一个 Python 包，用于导入、清理、处理和比较串联质谱。本技能针对 matchms 0.33.1，该版本于 2026-06-08 发布，并修正了旧教程未反映的多项破坏性 API 变更。

使用 matchms 进行：

• MS/MS 谱库搜索以及查询谱与参考谱的评分
• 元数据协调、加合物／前体处理和峰过滤
• 余弦、修正余弦、中性丢失、近似和熵评分
• 结构化评分矩阵、最高命中提取和谱网络
• MGF、MSP、mzML、mzXML、JSON、mzSpecLib 和 metabolomics-USI 工作流

不要将 matchms 用作以下任务的替代方案：

• LC-MS 特征检测、色谱对齐、肽段鉴定或蛋白质定量——请使用 pyopenms
• 厂商原始文件转换——请先转换为 mzML/mzXML
• 经验证的化合物鉴定方案——相似性是证据，而非身份确证

安装经过验证的版本

创建或激活环境，然后安装本技能使用的版本：

uv pip install "matchms==0.33.1"

验证运行环境：

uv run python -c "import matchms; print(matchms.__version__)"

Matchms 0.33.1 支持 Python 3.10-3.14，并将 RDKit 作为常规依赖项安装。旧的 matchms[chemistry] 附加组件不属于当前软件包元数据。

操作工作流

1. 检查输入。 记录格式、谱图数量、MS 级别、前体覆盖情况、离子模式、峰数量和标识符字段。
2. 启用元数据协调后加载，除非保留源键是有意的要求。
3. 对查询谱和参考谱应用相同的峰处理步骤。 如果参考谱的注释更丰富，请将元数据补充与此步骤分开处理。
4. 明确丢弃无效谱图。 许多 require_* 过滤器会返回 None。
5. 根据科学问题选择评分方法，而不是为了方便。修正余弦和中性丢失评分要求 precursor_mz 有效。
6. 在评分前估算 len(references) * len(queries)。 稀疏结果容器并不会自动避免计算所有要求的配对。
7. 报告评分设置和证据。 包括容差、预处理方法、评分名称、可用时的匹配峰数量，以及候选项元数据。
8. 通过目视和化学方法验证最高命中项。 使用镜像图、前体一致性、离子／加合物兼容性及正交证据。

当前 API 注意事项

以下要点可避免旧版示例中最常见的错误：

• 使用 ModifiedCosineGreedy 或 ModifiedCosineHungarian；ModifiedCosine 已在 0.32.0 中移除。
• 不要调用 add_losses()。它已在 0.27.0 中移除；请直接使用 spectrum.losses、spectrum.compute_losses(...) 或 NeutralLossesCosine。
• SpectrumProcessor 不可调用。请使用 process_spectrum() 或 process_spectra()。
• process_spectra() 会返回 (processed_spectra, processing_report)。
• Scores.scores 是一个 StackedSparseArray，通常包含独立的结构化字段，例如 CosineGreedy_score 和 CosineGreedy_matches。
• scores_by_query() 返回 (reference_spectrum, score_record) 配对，而不是参考谱索引。
• 参数名称优先使用 spectra。旧拼写 spectrums 已弃用。
• 切勿加载来自不可信来源的 pickle 文件；取消封存可能会执行代码。

完整的新旧版本映射请参阅 references/migration.md。

快速入门：清理并搜索谱库

from matchms import SpectrumProcessor, calculate_scores
from matchms.filtering import (
    default_filters,
    normalize_intensities,
    require_minimum_number_of_peaks,
    select_by_relative_intensity,
)
from matchms.importing import load_spectra
from matchms.similarity import ModifiedCosineGreedy


def load_and_process(path):
    spectra = [default_filters(spectrum) for spectrum in load_spectra(path)]
    processor = SpectrumProcessor(
        [
            normalize_intensities,
            (select_by_relative_intensity, {"intensity_from": 0.01}),
            (require_minimum_number_of_peaks, {"n_required": 5}),
        ]
    )
    processed, _ = processor.process_spectra(
        spectra,
        progress_bar=False,
        create_report=False,
    )
    return processed


references = load_and_process("library.msp")
queries = load_and_process("queries.mgf")

metric = ModifiedCosineGreedy(tolerance=0.02)
scores = calculate_scores(
    references=references,
    queries=queries,
    similarity_function=metric,
)

score_name = "ModifiedCosineGreedy_score"
matches_name = "ModifiedCosineGreedy_matches"
for query in queries:
    ranked = scores.scores_by_query(query, name=score_name, sort=True)
    for reference, values in ranked[:5]:
        print(
            query.get("spectrum_id", query.get("id")),
            reference.get("compound_name", reference.get("spectrum_id")),
            float(values[score_name]),
            int(values[matches_name]),
        )

SpectrumProcessor 会根据 matchms 的过滤器顺序自动排列内置过滤器。聚合的 default_filters 可调用对象不在该注册表中，因此请像上面那样先运行它，或展开其九个组成过滤器。检查 processor.processing_steps，并与结果一同保存。

成对评分

相似度类提供了针对一对参考谱图和查询谱图的 pair()。余弦系列的结果是结构化 NumPy 标量：

from matchms.similarity import CosineGreedy

result = CosineGreedy(tolerance=0.02).pair(reference, query)
similarity = float(result["score"])
matched_peaks = int(result["matches"])

对于 FlashSimilarity 等面向矩阵的方法，请使用 calculate_scores()；它支持单对计算，但这并非优化路径。

选择相似度方法

• CosineGreedy — 标准峰值余弦相似度，使用贪心峰值匹配。
• CosineHungarian — 精确匹配；速度较慢，适用于基准测试。
• CosineLinear — 当前的线性缩放余弦相似度实现。
• ModifiedCosineGreedy — 允许前体质量差偏移后的匹配；常用于类似物搜索。
• ModifiedCosineHungarian — 精确的改进余弦匹配。
• NeutralLossesCosine — 比较根据前体和碎片计算出的中性丢失。
• BlinkCosine — 快速的 BLINK 风格余弦近似，适用于较大的矩阵。
• FlashSimilarity — 使用谱熵或余弦相似度，并通过碎片、中性丢失或混合匹配进行优化的矩阵评分方法。
• BinnedEmbeddingSimilarity — 分箱后的谱图向量，可选近似最近邻索引。
• PrecursorMzMatch、ParentMassMatch、MetadataMatch — 候选掩码或元数据约束，不是丰富的谱图评分方法。
• FingerprintSimilarity — 分子结构相似度；它不是谱图相似度，需要根据有效结构预先准备指纹。

选择快速方法、组合评分或解读结构化输出前，请阅读 references/similarity.md。

大规模比较

对单个集合进行全对全评分时，请设置 is_symmetric=True：

scores = calculate_scores(
    references=spectra,
    queries=spectra,
    similarity_function=CosineGreedy(tolerance=0.02),
    array_type="sparse",
    is_symmetric=True,
)

对于经前体离子门控的搜索，请先计算并筛选 PrecursorMzMatch，然后通过 Pipeline 或 Scores.calculate(...) 仅对保留的坐标计算谱图指标。请参阅 references/workflows.md。

不要选择通用的“鉴定阈值”。评分分布取决于预处理、质量精度、碰撞条件、谱库质量和指标。对于余弦系列方法，至少应同时保留评分和匹配峰数。

附带的谱库搜索 CLI

scripts/library_search.py 提供可复现的查询谱图与谱库搜索，包含当前的评分提取、成对数量限制、预处理和 CSV 输出：

uv run python scripts/library_search.py \
  queries.mgf library.msp hits.csv \
  --metric modified \
  --tolerance 0.02 \
  --top-k 10 \
  --min-score 0.6 \
  --min-matches 5

运行 --help，了解快速指标、预处理选项、标识符字段、覆盖控制以及明确的大矩阵覆盖选项。

谱图对象与可视化

import numpy as np
from matchms import Spectrum

spectrum = Spectrum(
    mz=np.array([100.0, 150.0, 200.0]),
    intensities=np.array([0.2, 1.0, 0.4]),
    metadata={"spectrum_id": "query-1", "precursor_mz": 250.5},
)

print(spectrum.peaks.mz)
print(spectrum.get("precursor_mz"))
losses = spectrum.compute_losses(loss_mz_from=5.0, loss_mz_to=200.0)
spectrum.plot()
spectrum.plot_against(reference_spectrum)

参考资料

仅阅读任务所需的参考资料：

• references/importing_exporting.md — 格式、返回类型、通用 I/O、mzSpecLib、评分序列化和 pickle 安全性
• references/filtering.md — 当前的筛选器目录、克隆与 None 语义、默认筛选器、顺序和 SpectrumProcessor
• references/similarity.md — 所有当前的相似度类、输出、候选掩码、性能和解读
• references/workflows.md — 谱库搜索、稀疏门控、Pipeline、网络、绘图和溯源信息
• references/migration.md — 破坏性变更和已弃用的 API
• references/sources.md — 本次更新所用的权威文档、发行说明、用户指南和科学出版物

必须遵守的检查项

• 绝不要将未经不同处理的查询谱图与参考谱图进行比较。
• 没有有效的前体元数据时，绝不要使用改进余弦或中性丢失评分。
• 绝不要假设 Scores 值是普通浮点数；请检查 score_names。
• 绝不要仅凭高相似度评分就认定鉴定结果已确认。
• 绝不要反序列化不可信的 pickle 数据。
• 未估算成对数量前，绝不要启动无界全对全比较。

Agent 操作流程

1. 检查环境。 确认工具版本、参考基因组／注释版本，以及输入格式（FASTQ、BAM、VCF、h5ad）。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。凡是会改变结果的值，都应询问而非猜测。
3. 先运行小规模版本。 先在小型子集上运行流水线（一个样本、一个染色体、几千个细胞）。
4. 使用上述说明和参考资料执行完整任务。
5. 验证结果。 在解读结果前，检查 QC 指标、样本身份、基因组版本一致性和批次效应。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及仍有哪些不确定之处。

如果出现这种情况	请这样做
输入之间的基因组版本或标识符不匹配	停止并进行协调（liftover、ID 映射）后再继续。
已安装版本中缺少这些说明提到的函数、标志或端点	查阅已安装版本自己的文档（help()、--help、官方文档），进行调整并告知用户。切勿虚构 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明所采用的假设。

完整性规则

• 切勿捏造结果、参数、标识符、引用或统计数据。若无法运行或验证某项内容，请如实说明。
• 不要作出超出统计数据支持范围的生物学意义解读；报告多重检验校正情况。
• 本文中的版本特定细节可能已过时：请根据已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征得同意。

相关技能

• pyopenms：完整的质谱分析平台。
• qdrant-vector-search：用于 RAG 和语义搜索的高性能向量相似度搜索引擎。
• faiss：Facebook 用于高效相似性搜索和稠密向量聚类的库。