matchms

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

用途与范围

matchms 适用于：MS/MS 库检索与查询-参考谱打分；元数据协调、加合物/前体离子处理与峰过滤；余弦、修饰余弦、中性丢失、近似和熵评分；结构化评分矩阵、最佳命中提取与谱网络；MGF、MSP、mzML、mzXML、JSON、mzSpecLib 及代谢组学 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] 附加项已不在当前包元数据中。

操作流程

检查输入：记录格式、谱图数量、MS 级别、前体覆盖、离子模式、峰数量和标识符字段。加载时启用元数据协调，除非有意保留源键。对查询谱和参考谱应用相同的峰处理步骤；当参考注释更丰富时，将元数据富集单独处理。显式丢弃无效谱图，许多 require_* 过滤器会返回 None。根据科学问题而非便利性选择评分方法；修饰和中性丢失评分需要有效的 precursor_mz。评分前估算 len(references) * len(queries)；稀疏结果容器不会自动避免计算每个请求的配对。报告评分设置与证据，包括容差、预处理、评分名称、可用时的匹配峰数以及候选元数据。通过镜像图、前体一致性、离子/加合物兼容性和正交证据对最佳命中进行视觉与化学验证。

当前 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 文件，反序列化可能执行代码。

快速开始：清洗并检索库

示例代码展示了使用 default_filters 加载谱图、通过 SpectrumProcessor 进行归一化、相对强度筛选和最小峰数过滤，再用 ModifiedCosineGreedy 计算评分并按分数排序输出前 5 个命中。SpectrumProcessor 会自动按 matchms 的过滤器顺序排列内置过滤器；聚合的 default_filters 可调用对象不在该注册表中，因此需先单独运行或展开其九个组件过滤器。检查 processor.processing_steps 并随结果保留。

配对评分

相似度类提供 pair() 用于单个参考/查询配对。余弦族结果为结构化 NumPy 标量，可通过 result["score"] 和 result["matches"] 获取。对于 FlashSimilarity 等面向矩阵的方法应使用 calculate_scores()。

相似度方法选择

CosineGreedy：标准峰余弦，贪心峰分配。CosineHungarian：精确分配，较慢，适合基准测试。CosineLinear：当前线性扩展余弦实现。ModifiedCosineGreedy：允许前体差值偏移匹配，常用于类似物检索。ModifiedCosineHungarian：精确修饰余弦分配。NeutralLossesCosine：比较由前体和碎片计算的中性丢失。BlinkCosine：面向较大矩阵的快速 BLINK 风格余弦近似。FlashSimilarity：使用谱熵或余弦（含碎片、中性丢失或混合匹配）的优化矩阵评分。BinnedEmbeddingSimilarity：分箱谱向量及可选近似最近邻索引。PrecursorMzMatch、ParentMassMatch、MetadataMatch：候选掩码或元数据约束，不是丰富的谱评分。FingerprintSimilarity：分子结构相似度，不是谱相似度，需要从有效结构准备的指纹。

大规模比较

对单一集合进行全对全评分时设置 is_symmetric=True。对于前体门控检索，先计算并过滤 PrecursorMzMatch，再通过 Pipeline 或 Scores.calculate(...) 仅对保留坐标计算谱度量。不要选择通用的“鉴定阈值”；评分分布取决于预处理、质量精度、碰撞条件、库质量和度量。至少保留余弦族方法的分数和匹配峰数。

内置库检索 CLI

scripts/library_search.py 提供可复现的查询-库检索，支持当前评分提取、配对数量限制、预处理和 CSV 输出，示例命令使用 --metric modified --tolerance 0.02 --top-k 10 --min-score 0.6 --min-matches 5。运行 --help 可查看快速度量、预处理选项、标识符字段、覆盖控制和显式大矩阵覆盖。

谱对象与可视化

可通过 Spectrum 构造谱图，访问 spectrum.peaks.mz、spectrum.get("precursor_mz")，使用 spectrum.compute_losses(...) 计算丢失，并用 spectrum.plot() 和 spectrum.plot_against(reference_spectrum) 绘图。

参考文档

按任务需要阅读：references/importing_exporting.md（格式、返回类型、通用 I/O、mzSpecLib、评分序列化和 pickle 安全）；references/filtering.md（当前过滤器目录、clone/None 语义、默认过滤器、排序和 SpectrumProcessor）；references/similarity.md（所有当前相似度类、输出、候选掩码、性能和解释）；references/workflows.md（库检索、稀疏门控、Pipeline、网络、绘图和溯源）；references/migration.md（破坏性变更和弃用 API）；references/sources.md（权威文档、发行说明、用户指南和科学出版物）。

不可妥协的检查

切勿将原始查询与经过不同处理的参考谱比较。切勿在没有有效前体元数据的情况下使用修饰或中性丢失评分。切勿假设 Scores 值是普通浮点数，应检查 score_names。切勿仅凭高相似度分数就视为确证鉴定。切勿反序列化不可信的 pickle 数据。切勿在未估算配对数量的情况下启动无界全对全比较。

智能体操作流程

检查环境，确认工具版本、参考基因组/注释构建和输入格式。明确输入，从数据或用户确认格式、标识符和参数，对影响结果的任何值应询问而非猜测。先运行小版本，在小样本子集上运行流程。按上述说明和参考执行完整任务。验证结果，在解释结果前检查 QC 指标、样本身份、基因组构建一致性和批次效应。报告运行内容（版本、命令、参数）、已检查内容和仍不确定之处。若输入间基因组构建或标识符不匹配，停止并先协调（liftover、ID 映射）。若安装版本中缺少某函数、标志或端点，查阅该版本自身文档并告知用户，切勿臆造 API。若必需输入、标识符或参数不明确，询问用户或明确说明假设后再运行。

完整性规则

切勿捏造结果、参数、标识符、引用或统计。若无法运行或验证，应明确说明。不要超出统计支持范围解释生物学意义；报告多重检验校正。将此处版本特定细节视为可能过时，对照已安装版本的官方文档确认。对涉及费用、共享 GPU 或云配额、个人或患者数据、或不可撤销的操作，先询问。

技能介绍