Matchms

Propósito e Escopo

Matchms é um pacote Python para importar, limpar, processar e comparar espectros de massa em tandem. Esta habilidade tem como alvo a versão matchms 0.33.1, lançada em 08-06-2026, verificada novamente em 01-10-2026. Tutoriais mais antigos podem usar nomes removidos; consulte a referência de migração.

Use matchms para:

• Busca em bibliotecas MS/MS e pontuação de consulta versus referência
• Harmonização de metadados, tratamento de adutos/precursores e filtragem de picos
• Pontuação por cosseno, cosseno modificado, perda neutra, aproximada e entropia
• Matrizes de pontuação estruturadas, extração de melhores resultados e redes espectrais
• Fluxos de trabalho MGF, MSP, mzML, mzXML, JSON, mzSpecLib e metabolômica-USI

Não use matchms como substituto para:

• Detecção de características LC-MS, alinhamento cromatográfico, identificação de peptídeos ou quantificação de proteínas — use pyopenms
• Conversão de arquivos brutos do fornecedor — converta para mzML/mzXML primeiro
• Um protocolo validado de identificação de compostos — similaridade é evidência, não prova de identidade

Instale a Versão Verificada

Crie ou ative um ambiente e, em seguida, instale a versão usada por esta habilidade:

uv pip install "matchms==0.33.1"

Verifique o tempo de execução:

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

Matchms 0.33.1 suporta Python 3.10-3.14 e instala RDKit como uma dependência regular. O antigo extra matchms[chemistry] não faz parte dos metadados atuais do pacote.

Fluxo de Trabalho Operacional

1. Inspecione as entradas. Formato de registro, contagem de espectros, nível de MS, cobertura de precursores, modo de íon, contagem de picos e campos identificadores.
2. Carregue com a harmonização de metadados habilitada por padrão. Mantenha os arquivos originais: desabilitar o sinalizador em 0.33.1 ainda harmoniza as chaves de metadados.
3. Aplique as mesmas etapas de processamento de picos aos espectros de consulta e referência. Mantenha o enriquecimento de metadados separado quando as anotações de referência forem mais ricas.
4. Descarte espectros inválidos explicitamente. Muitos filtros require_* retornam None.
5. Escolha a pontuação com base na pergunta científica, não na conveniência. Pontuações modificadas e de perda neutra exigem precursor_mz válidos.
6. Estime len(references) * len(queries) antes de pontuar. Um contêiner de resultados esparso não evita automaticamente o cálculo de cada par solicitado.
7. Relate as configurações de pontuação e evidências. Inclua tolerância e unidades, pré-processamento, nome da pontuação, número de picos correspondentes quando disponíveis e metadados do candidato. A família de cossenos tolerance é uma janela de m/z absoluta em Da, não ppm; um filtro de precursor com tolerance_type="ppm" não altera a tolerância do fragmento.
8. Valide os melhores resultados visualmente e quimicamente. Use gráficos espelhados, concordância de precursores, compatibilidade de íons/adutos e evidências ortogonais.

Diretrizes Atuais da API

Estes pontos evitam as falhas mais comuns de exemplos anteriores a 0.33:

• Use ModifiedCosineGreedy ou ModifiedCosineHungarian; ModifiedCosine foi removido em 0.32.0.
• Não chame add_losses(). Foi removido em 0.27.0; use spectrum.losses, spectrum.compute_losses(...) ou NeutralLossesCosine diretamente.
• SpectrumProcessor não é chamável. Use process_spectrum() ou process_spectra(). A chamada de espectro único modifica por padrão; passe uma cópia ao preservar o original.
• process_spectra() retorna (processed_spectra, processing_report).
• Scores.scores é um StackedSparseArray, muitas vezes com campos estruturados separados, como CosineGreedy_score e CosineGreedy_matches.
• scores_by_query() retorna pares (reference_spectrum, score_record), não índices de referência.
• Prefira spectra em nomes de parâmetros. A grafia legada spectrums está obsoleta.
• Nunca carregue arquivos pickle de uma fonte não confiável; descompactar pode executar código.

Consulte references/migration.md para um mapeamento completo de antigo para atual.

Início Rápido: Limpar e Pesquisar uma Biblioteca

from math import isfinite

from matchms import SpectrumProcessor, calculate_scores
from matchms.filtering import (
    default_filters,
    normalize_intensities,
    require_minimum_number_of_peaks,
    require_precursor_mz,
    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(
        [
            (require_precursor_mz, {"minimum_accepted_mz": 10.0}),
            normalize_intensities,

…