Spectral annotation filtering by similarity metrics

Spectral Annotation Filtering by Similarity Metrics

Summary

Filter and retain high-confidence mass spectrometry annotations by applying empirical similarity thresholds (cosine score, shared peaks, ppm error, and ZodiacScore) to in silico or database-matched compound identities. This skill ensures that only structurally plausible annotations meeting multi-dimensional spectral agreement criteria are used in downstream metabolomic analysis.

When to use

After running GNPS molecular networking, SIRIUS compound identification, or ISDB in silico annotation on LC-MS/MS data, when you have provisional annotations for features but need to filter them to retain only high-confidence matches before calculating novelty scores, detecting chemical classes, or building metabolite inventories. Use when combining annotations from multiple sources (GNPS, SIRIUS, ISDB) and parameter heterogeneity requires standardization.

When NOT to use

• When input annotations are already manually curated or from a small, highly curated reference library (e.g. pure standards)—threshold-based filtering may over-filter or introduce bias.
• When spectral data are from different ionization modes or MS instruments not represented in your reference database—similarity metrics may be artificially low and thresholds inappropriate.
• When the goal is exploratory annotation ranking rather than strict novelty filtering—excessive filtering may obscure biological signals and lower Feature Component scores artificially.

Inputs

• GNPS molecular networking job results with candidate annotations
• SIRIUS compound_identification.tsv with ZodiacScore and ConfidenceScore columns
• ISDB in silico annotation results with cosine similarity and shared peaks
• MZmine2/MZmine3 feature table with m/z and retention time
• Annotation metadata table specifying annotation source (GNPS/SIRIUS/ISDB) and associated scores

Outputs

• Filtered annotation table retaining only high-confidence matches meeting all similarity thresholds
• Binary indicator column marking which features retain annotations after filtering
• Filtered Feature Component (FC) input: non-annotated feature set after removal of low-confidence annotations
• Summary statistics on annotation retention rate and threshold application per annotation source

How to apply

Apply four complementary similarity and scoring filters in sequence: (1) cosine similarity ≥ 0.7 to ensure MS2 spectral overlap; (2) shared_peaks ≥ 10 to confirm that experimental and library MS2 spectra have minimum fragment agreement; (3) ppm_error ≤ 5 to retain only mass matches within 5 ppm tolerance; (4) for SIRIUS annotations, apply min_ZodiacScore ≥ 0.9 to filter by structural plausibility scored by the Zodiac ranking system. For ISDB annotations, optionally apply min_score_final ≥ 0.0 (or higher if stricter filtering is required). These thresholds are user-configurable and should be adjusted based on instrument resolution, ionization mode, and database characteristics. The filtering workflow reduces false-positive annotations while preserving structurally relevant features for novelty discovery and component scoring.

Related tools

• GNPS (Source of molecular networking job ID and candidate annotations; provides cosine-based spectral matching results)
• SIRIUS (Generates compound_identification.tsv with ZodiacScore and ConfidenceScore for de novo structure elucidation; output filtered by min_ZodiacScore threshold) — https://bio.informatik.uni-jena.de/software/sirius/
• ISDB (In silico spectral library matching; annotations filtered by cosine score, shared peaks, and ppm error thresholds)
• MZmine2/MZmine3 (Feature detection and quantification; input feature table used to map filtered annotations back to features)
• Inventa (Applies these filtering parameters during Feature Component and downstream novelty scoring pipeline; accepts cleaned annotation tables from this skill) — https://github.com/luigiquiros/inventa

Examples

ppm_error = 5; shared_peaks = 10; cosine = 0.7; min_ZodiacScore = 0.9; min_ConfidenceScore = 0.0; annotations_filtered = annotations[(annotations['ppm_error'] <= ppm_error) & (annotations['shared_peaks'] >= shared_peaks) & (annotations['cosine'] >= cosine) & (annotations['ZodiacScore'] >= min_ZodiacScore)].copy()

Evaluation signals

• Verify that the number of retained annotations is strictly ≤ the input annotation count; confirm 0% false-positive retention.
• Check that all retained annotations meet ALL four thresholds simultaneously (cosine ≥ 0.7 AND shared_peaks ≥ 10 AND ppm_error ≤ 5 AND ZodiacScore ≥ 0.9); no annotation should pass if any single threshold fails.
• Confirm that the filtered annotation table has no null values in the similarity metric columns and that Feature Component (FC) is recomputed as ratio of (non-annotated features after filtering) / (total features).
• Validate that output retains all expected columns from input (m/z, retention time, annotation source, cosine, shared_peaks, ppm_error, ZodiacScore, ConfidenceScore) and adds a binary 'filtered_pass' column.
• Spot-check 5–10 borderline annotations (e.g., cosine = 0.70, shared_peaks = 10) to confirm threshold application is consistent and reproducible.

Limitations

• Thresholds are empirically derived and may be overly stringent or permissive for atypical sample types (e.g., lipids, halogenated compounds, sulfated metabolites) not well-represented in SIRIUS or ISDB reference databases.
• Filtering assumes that cosine similarity, shared peaks, and ppm error are orthogonal metrics; in practice, high cosine scores often co-occur with high shared_peaks, reducing the effective filtering stringency.
• When annotations from SIRIUS and ISDB are combined, their confidence scores (ZodiacScore vs. score_final) may not be directly comparable; separate threshold application per source is advised but is not automated in the referenced Inventa notebook.
• No changelog found for threshold parameter versioning; it is unclear whether thresholds (ppm=5, cosine=0.7, shared_peaks=10) were optimized for a specific MS instrument class or are general recommendations.
• Filtering does not account for false-negatives: some true metabolites may fall below thresholds due to poor ionization, low abundance, or database incompleteness, reducing the reported Feature Component and potentially underestimating novelty.

Evidence

• [other] For cleaning-up annotations from GNPS ppm_error = 5 # min error in ppm to consider an annotation valable shared_peaks = 10 # min number of shared peaks: "For cleaning-up annotations from GNPS ppm_error = 5 # min error in ppm to consider an annotation valable shared_peaks = 10 # min number of shared peaks"
• [other] cosine = 0.7 # min cosine score to consider an annotation valable: "cosine = 0.7 # min cosine score to consider an annotation valable"
• [other] min_ZodiacScore = 0.9 #cut-off filter for considering a sirius annotation valable: "min_ZodiacScore = 0.9 #cut-off filter for considering a sirius annotation valable"
• [other] min_ConfidenceScore = 0.0 #cut-off filter for considering a sirius annotation valable: "min_ConfidenceScore = 0.0 #cut-off filter for considering a sirius annotation valable"
• [other] Calculate Feature Component (FC) as ratio of specific non-annotated features (with specificity ≥ min_specificity threshold of 90%) over total features per sample, optionally incorporating ISDB and SIRIUS annotations filtered by ppm_error=5, shared_peaks=10, cosine=0.7, min_ZodiacScore=0.9, min_ConfidenceScore=0.0.: "Calculate Feature Component (FC) as ratio of specific non-annotated features (with specificity ≥ min_specificity threshold of 90%) over total features per sample, optionally incorporating ISDB and"
• [other] Set annotation cleaning parameters (ppm_error, shared_peaks, cosine, ionisation_mode): "Set annotation cleaning parameters (ppm_error, shared_peaks, cosine, ionisation_mode)"