# Matchms > Procesa, limpia, compara y busca espectros de masas en tándem (MS/MS) con matchms: I/O de archivos, armonización de metadatos, filtrado de picos, similitud espectral, búsqueda en librerías y redes de similitud molecular. Fuente: https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/matchms Markdown: https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/matchms.md Repositorio: https://github.com/K-Dense-AI/scientific-agent-skills Autor: K-Dense-AI Licencia: Apache-2.0 Actualizado: el mes pasado Coste de contexto: 74 tok instalada, 2.6k tok al activarse, 22.3k tok con todos los archivos del bundle Bundle: 8 archivos, 87 KB Permisos que pide: read write edit bash ## Instalación Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina. ```bash # Claude Code npx -y skills add K-Dense-AI/scientific-agent-skills --skill matchms --agent claude-code # Cursor npx -y skills add K-Dense-AI/scientific-agent-skills --skill matchms --agent cursor # Codex npx -y skills add K-Dense-AI/scientific-agent-skills --skill matchms --agent codex # Gemini CLI npx -y skills add K-Dense-AI/scientific-agent-skills --skill matchms --agent gemini # Windsurf npx -y skills add K-Dense-AI/scientific-agent-skills --skill matchms --agent windsurf # Cline npx -y skills add K-Dense-AI/scientific-agent-skills --skill matchms --agent cline ``` ## Qué hace - Carga y limpia espectros MS/MS en formatos MGF, MSP, mzML, mzXML, JSON, mzSpecLib y metabolomics-USI - Armoniza metadatos, filtra picos y aplica el mismo preprocesado a espectros de consulta y referencia - Calcula similitud espectral con CosineGreedy, ModifiedCosine, NeutralLossesCosine, FlashSimilarity, entre otros - Genera matrices de puntuación, extrae los mejores hits y construye redes de similitud molecular - Incluye un script de búsqueda en librería reproducible (library_search.py) con salida CSV ## Cuándo usarla - Buscar en una librería de espectros MS/MS y puntuar consultas frente a referencias - Armonizar metadatos, aductos/precursores y filtrar picos de espectros de masas - Elegir y aplicar un método de puntuación espectral (coseno, pérdida neutra, entropía) - Construir matrices de puntuación estructuradas o redes espectrales ## Cuándo no - Para detección de features LC-MS, alineación cromatográfica o cuantificación de proteínas — usa pyopenms - Para convertir archivos raw de instrumentos — conviértelos primero a mzML/mzXML ## Qué la activa - "Busca estos espectros de consulta contra mi librería MSP" - "Calcula la similitud coseno modificada entre estos espectros" - "Construye una red de similitud molecular con estos espectros MS/MS" - "Filtra estos espectros por número mínimo de picos" ## Antes de instalar - Necesita Python >=3.10,<3.15 y matchms 0.33.1; cargar espectros desde metabolomics-USI requiere acceso a red. ## Archivos - SKILL.md — 10 KB - references/filtering.md — 11 KB - references/importing_exporting.md — 9 KB - references/migration.md — 8 KB - references/similarity.md — 11 KB - references/sources.md — 6 KB - references/workflows.md — 13 KB - scripts/library_search.py — 19 KB ## SKILL.md Reproducido tal cual desde K-Dense-AI/scientific-agent-skills bajo Apache-2.0. Esta sección es el documento original y está en inglés. # Matchms ## Purpose and Scope Matchms is a Python package for importing, cleaning, processing, and comparing tandem mass spectra. This skill targets **matchms 0.33.1**, released 2026-06-08, and corrects several breaking API changes that older tutorials do not reflect. Use matchms for: - MS/MS library search and query-versus-reference scoring - Metadata harmonization, adduct/precursor handling, and peak filtering - Cosine, modified-cosine, neutral-loss, approximate, and entropy scoring - Structured score matrices, top-hit extraction, and spectral networks - MGF, MSP, mzML, mzXML, JSON, mzSpecLib, and metabolomics-USI workflows Do not use matchms as a replacement for: - LC-MS feature detection, chromatographic alignment, peptide identification, or protein quantification — use pyopenms - Vendor raw-file conversion — convert to mzML/mzXML first - A validated compound-identification protocol — similarity is evidence, not proof of identity ## Install the Verified Release Create or activate an environment, then install the release used by this skill: ```bash uv pip install "matchms==0.33.1" ``` Verify the runtime: ```bash uv run python -c "import matchms; print(matchms.__version__)" ``` Matchms 0.33.1 supports Python 3.10-3.14 and installs RDKit as a regular dependency. The old `matchms[chemistry]` extra is not part of the current package metadata. ## Operating Workflow 1. **Inspect the inputs.** Record format, spectrum count, MS level, precursor coverage, ion mode, peak counts, and identifier fields. 2. **Load with metadata harmonization enabled** unless preserving source keys is a deliberate requirement. 3. **Apply the same peak-processing steps** to query and reference spectra. Keep metadata enrichment separate when reference annotations are richer. 4. **Drop invalid spectra explicitly.** Many `require_*` filters return `None`. 5. **Choose the score from the scientific question**, not from convenience. Modified and neutral-loss scores require valid `precursor_mz`. 6. **Estimate `len(references) * len(queries)` before scoring.** A sparse result container does not automatically avoid computing every requested pair. 7. **Report score settings and evidence.** Include tolerance, preprocessing, score name, number of matched peaks when available, and candidate metadata. 8. **Validate top hits visually and chemically.** Use mirror plots, precursor agreement, ion/adduct compatibility, and orthogonal evidence. ## Current API Guardrails These points prevent the most common failures from pre-0.33 examples: - Use `ModifiedCosineGreedy` or `ModifiedCosineHungarian`; `ModifiedCosine` was removed in 0.32.0. - Do not call `add_losses()`. It was removed in 0.27.0; use `spectrum.losses`, `spectrum.compute_losses(...)`, or `NeutralLossesCosine` directly. - `SpectrumProcessor` is not callable. Use `process_spectrum()` or `process_spectra()`. - `process_spectra()` returns `(processed_spectra, processing_report)`. - `Scores.scores` is a `StackedSparseArray`, often with separate structured fields such as `CosineGreedy_score` and `CosineGreedy_matches`. - `scores_by_query()` returns `(reference_spectrum, score_record)` pairs, not reference indices. - Prefer `spectra` in parameter names. The legacy spelling `spectrums` is deprecated. - Never load pickle files from an untrusted source; unpickling can execute code. See `references/migration.md` for a complete old-to-current mapping. ## Quick Start: Clean and Search a Library ```python 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` automatically orders built-in filters according to matchms's filter order. The aggregate `default_filters` callable is not in that registry, so run it first as above or expand its nine component filters. Inspect `processor.processing_steps` and preserve it with results. ## Pair Scoring Similarity classes expose `pair()` for one reference/query pair. Cosine-family results are structured NumPy scalars: ```python from matchms.similarity import CosineGreedy result = CosineGreedy(tolerance=0.02).pair(reference, query) similarity = float(result["score"]) matched_peaks = int(result["matches"]) ``` Use `calculate_scores()` for matrix-oriented methods such as `FlashSimilarity`; its single-pair path is supported but intentionally not the optimized path. ## Choose a Similarity Method - `CosineGreedy` — standard peak cosine with greedy peak assignment. - `CosineHungarian` — exact assignment; slower, useful for benchmarks. - `CosineLinear` — current linear-scaling cosine implementation. - `ModifiedCosineGreedy` — permits precursor-delta-shifted matches; common for analog search. - `ModifiedCosineHungarian` — exact modified-cosine assignment. - `NeutralLossesCosine` — compares losses computed from precursor and fragments. - `BlinkCosine` — fast BLINK-style cosine approximation for larger matrices. - `FlashSimilarity` — optimized matrix scoring using spectral entropy or cosine with fragment, neutral-loss, or hybrid matching. - `BinnedEmbeddingSimilarity` — binned spectral vectors and optional approximate nearest-neighbor indexing. - `PrecursorMzMatch`, `ParentMassMatch`, `MetadataMatch` — candidate masks or metadata constraints, not rich spectral scores. - `FingerprintSimilarity` — molecular-structure similarity; it is not spectral similarity and requires fingerprints prepared from valid structures. Read `references/similarity.md` before choosing a fast method, combining scores, or interpreting structured outputs. ## Large Comparisons For all-vs-all scoring of one collection, set `is_symmetric=True`: ```python scores = calculate_scores( references=spectra, queries=spectra, similarity_function=CosineGreedy(tolerance=0.02), array_type="sparse", is_symmetric=True, ) ``` For a precursor-gated search, compute and filter `PrecursorMzMatch` first, then calculate the spectral metric only on retained coordinates through `Pipeline` or `Scores.calculate(...)`. See `references/workflows.md`. Do not choose a universal "identification threshold." Score distributions depend on preprocessing, mass accuracy, collision conditions, library quality, and metric. At minimum, retain both score and matched-peak count for cosine-family methods. ## Bundled Library-Search CLI `scripts/library_search.py` provides a reproducible query-versus-library search with current score extraction, pair-count limits, preprocessing, and CSV output: ```bash 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 ``` Run `--help` for fast metrics, preprocessing options, identifier fields, overwrite control, and the explicit large-matrix override. ## Spectrum Objects and Visualization ```python 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 Read only the reference needed for the task: - `references/importing_exporting.md` — formats, return types, generic I/O, mzSpecLib, score serialization, and pickle safety - `references/filtering.md` — current filter catalog, clone/`None` semantics, default filters, ordering, and `SpectrumProcessor` - `references/similarity.md` — all current similarity classes, outputs, candidate masking, performance, and interpretation - `references/workflows.md` — library search, sparse gating, `Pipeline`, networks, plotting, and provenance - `references/migration.md` — breaking changes and deprecated APIs - `references/sources.md` — authoritative docs, release notes, user guides, and scientific publications used for this refresh ## Non-Negotiable Checks - Never compare raw queries against differently processed references. - Never use modified or neutral-loss scoring without valid precursor metadata. - Never assume a `Scores` value is a plain float; inspect `score_names`. - Never treat a high similarity score alone as confirmed identification. - Never deserialize untrusted pickle data. - Never launch an unbounded all-pairs comparison without estimating pair count. ## Dónde encaja - Categoría: [Datos y analítica](https://skillsagentes.com/categorias/datos-analitica.md) — Consulta, limpia y visualiza datos sin salir del agente. - Creador: [K-Dense-AI](https://skillsagentes.com/creators/k-dense-ai.md) — 163 skills en el directorio - [Todas las skills](https://skillsagentes.com/skills.md) - [Ranking de instalaciones](https://skillsagentes.com/ranking.md) ## Otras skills del mismo repositorio - [Citation Management](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/citation-management.md): Gestión integral de citas académicas: busca en OpenAlex, PubMed y Google Scholar, extrae metadatos precisos, valida citas y genera entradas BibTeX correctamente formateadas. - [Scientific Slides](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/scientific-slides.md): Crea decks de diapositivas y presentaciones para charlas de investigación: PowerPoint, presentaciones de conferencia, seminarios, defensas de tesis. Da estructura, plantillas, guía de tiempos y validación visual. - [Literature Review](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/literature-review.md): Realiza revisiones bibliográficas sistemáticas y completas usando varias bases académicas (PubMed, arXiv, bioRxiv, Semantic Scholar). Genera markdown y PDF con citas verificadas en varios estilos (APA, Nature, Vancouver). - [Infographics](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/infographics.md): Crea infografías profesionales con Nano Banana Pro AI y refinamiento iterativo inteligente. Usa Gemini 3.6 Flash para revisar la calidad e integra investigación con Perplexity Sonar. Soporta 10 tipos, 8 estilos y paletas para daltonismo. - [Latex Posters](https://skillsagentes.com/skills/k-dense-ai/scientific-agent-skills/latex-posters.md): Crea pósteres de investigación profesionales en LaTeX con beamerposter, tikzposter o baposter, para conferencias y comunicación científica: layout, colores, columnas múltiples e integración de figuras. --- Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)