Spectrum Alignment Scoring

---
name: spectrum-alignment-scoring
description: Use when after generating probability predictions for potential modification sites (via ModiFinder.
license: CC-BY-4.0
metadata:
  edam_operation: http://edamontology.org/operation_3632
  edam_topics:
  - http://edamontology.org/topic_0121
  - http://edamontology.org/topic_3370
  tools:
  - ModiFinder
  - Python
  - BasicEvaluationEngine
  techniques:
  - LC-MS
derived_from:
- doi: 10.1021/jasms.4c00061
  title: ModiFinder
evidence_spans:
- mf = ModiFinder(known_compound, modified_compound, mz_tolerance=0.01, ppm_tolerance=40)
- mf = ModiFinder(known_compound, modified_compound, helpers=helpers_array, **args)
- ModiFinder requires Python 3.9 or above.
- ModiFinder requires Python 3.9 or above
- eval_engine = BasicEvaluationEngine(default_method="is_max")
- eval_engine = BasicEvaluationEngine(default_method="average_distance")
claims: []
provenance:
  collection: https://w3id.org/holobiomicslab/asb-skill/collection/metabolomics/v2
  assembled_by: scripts/collect_metabolomics_collection.py
  sources:
  - build: coll_modifinder_cq
    doi: 10.1021/jasms.4c00061
    title: ModiFinder
  dedup_kept_from: coll_modifinder_cq
schema_version: 0.2.0
attribution:
  generator: AgenticScienceBuilder
  original_doi: 10.1021/jasms.4c00061
  all_source_dois:
  - 10.1021/jasms.4c00061
  zenodo_doi: 10.5281/zenodo.20794027
  curators: []
  promoter: Louis-Félix Nothias
  sponsor: CNRS & Université Côte d'Azur
---

# spectrum-alignment-scoring

## Summary

Score the alignment quality between known and modified compound MS/MS spectra using an evaluation engine that compares predicted modification site probabilities against observed spectral patterns. This skill quantifies how well a candidate modification hypothesis explains the tandem mass spectra.

## When to use

Apply this skill after generating probability predictions for potential modification sites (via ModiFinder.generate_probabilities()) and you need to evaluate whether a specific modification hypothesis—represented by an analog structure, target structure, and predicted probabilities—is consistent with observed MS/MS data. Use it when comparing multiple candidate modification sites or validating predicted structures against reference spectra.

## When NOT to use

- Input spectra have not been normalized or peak-filtered (use spectrum normalization and remove_small_peaks first)
- Probability predictions have not been generated by ModiFinder.generate_probabilities() (evaluation requires valid probability input)
- You are comparing raw spectra without intermediate site prediction—use ModiFinder.get_result() to obtain matched peaks and fragments first

## Inputs

- analog structure (unmodified compound SMILES or structure object)
- target structure (modified compound SMILES or structure object)
- predicted probabilities (dict or array from ModiFinder.generate_probabilities())
- evaluation method name (string: 'average_distance' or 'is_max')

## Outputs

- alignment score (float, typically 0–1 or normalized range)
- evaluation result (pass/fail or score comparison against reference)

## How to apply

Initialize a BasicEvaluationEngine with a specified scoring method (e.g., 'average_distance' as an alternative to 'is_max'). Call evaluate_single() passing the analog structure (unmodified compound), target structure (proposed modification), and predicted probabilities from ModiFinder. The engine computes an alignment score that measures spectral match quality; compare the returned score against expected reference values (e.g., 0.514 in the published workflow) to judge hypothesis validity. The choice of scoring method affects sensitivity to spectrum alignment patterns—average_distance provides continuous distance-based scoring rather than binary classification.

## Related tools

- **ModiFinder** (Generates probability predictions for modification sites and provides the probability input required by the evaluation engine) — https://github.com/Wang-Bioinformatics-Lab/ModiFinder_base
- **BasicEvaluationEngine** (Computes alignment scores between structures using configurable scoring methods (average_distance or is_max)) — https://github.com/Wang-Bioinformatics-Lab/ModiFinder_base
- **Python** (Runtime environment for ModiFinder and evaluation engine (requires Python 3.9 or above))

## Examples

```
from modifinder import BasicEvaluationEngine; engine = BasicEvaluationEngine(default_method='average_distance'); score = engine.evaluate_single(analog_structure, target_structure, predicted_probabilities); print(f'Alignment score: {score}'); assert abs(score - 0.514) < 0.01, f'Expected ~0.514, got {score}'
```

## Evaluation signals

- Returned score is a numeric value in expected range (e.g., 0.0–1.0 or comparable normalized scale)
- Score comparison against reference value documented in workflow produces consistent pass/fail status (e.g., score of 0.514 matches expected result)
- Scores for true modification pairs (known_compound vs modified_compound) are higher than scores for random/unrelated pairs, indicating discrimination power
- Evaluation completes without schema errors or type mismatches between input structures and probability format
- Swapping evaluation method from 'is_max' to 'average_distance' produces monotonic or interpretable differences in score magnitude while preserving rank order

## Limitations

- Evaluation score depends on quality of input probabilities; garbage probability input yields unreliable alignment scores
- No built-in penalty for chemically implausible modifications—evaluation is purely spectral and does not validate biochemical feasibility
- Scoring methods (average_distance, is_max) are abstractions over spectral alignment; choice of method can significantly affect score magnitude and interpretation
- Reference threshold values (e.g., 0.514) are method- and dataset-specific; direct transfer to new datasets may require recalibration

## Evidence

- [other] BasicEvaluationEngine with default_method='average_distance': "Instantiate BasicEvaluationEngine with default_method='average_distance'"
- [other] Call evaluate_single() with structures and probabilities: "Call evaluate_single() with the analog structure, target structure, and predicted probabilities to obtain the evaluation score"
- [other] Compare against reference value of 0.514: "Compare the returned score against the reference value of 0.514 and document the result"
- [other] average_distance scoring method as alternative to is_max: "Extend ModiFinder evaluation to the average_distance scoring method as an alternative to is_max"
- [other] ModiFinder provides evaluation capability within toolkit: "ModiFinder provides six categories of utilities—network, spectrum, file I/O, formula, molecule, and comparison utilities—that work seamlessly with core functionality"