Spectrum alignment scoring

spectrum-alignment-scoring

License: restricted — no clear open-source license detected for the underlying tool; verify licensing before commercial use or redistribution. <!-- asb-license-banner -->

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"