Spectral Match Threshold Application
Summary
Apply confidence score cutoffs to MS/MS spectral annotations to retain only high-quality matches from spectral databases or in silico prediction tools. This skill filters annotation tables by requiring matches to meet or exceed user-defined thresholds on metrics like cosine similarity, shared peak count, and mass accuracy.
When to use
After running spectral matching (e.g., GNPS library search, SIRIUS in silico annotation) and obtaining an annotation table with confidence scores, apply threshold filtering to remove low-confidence or spurious matches before downstream analysis (e.g., Feature Component calculation, chemical class assignment, or priority scoring in natural product discovery).
When NOT to use
- Input is already a curated or manually validated annotation set — re-filtering may introduce unnecessary data loss.
- Thresholds are not defined or justified for your annotation source — arbitrary cutoffs risk over-filtering or under-filtering.
- You need to preserve all annotations for comparison or exploratory analysis — thresholding is irreversible without the original file.
Inputs
- Annotation table in TSV format (e.g., compound_identification.tsv from SIRIUS, GNPS spectral library matches, or ISDB database search results)
- Metadata defining threshold parameters (cosine, shared_peaks, ppm_error, min_ZodiacScore, min_ConfidenceScore, min_score_final)
Outputs
- Filtered annotation table (TSV format) containing only rows meeting all confidence thresholds
- Annotation count summary (rows retained vs. removed)
How to apply
Load the annotation table (TSV format with confidence score columns such as cosine, Zodiac score, or shared peak counts). Define threshold parameters: minimum cosine similarity (e.g., 0.7), minimum shared peaks (e.g., 10), maximum ppm mass error (e.g., 5 ppm), and annotation-specific confidence cutoffs (e.g., min_ZodiacScore = 0.9 for SIRIUS, min_score_final = 0.0 for ISDB). Apply these thresholds sequentially or in combination as boolean filters to retain only rows meeting all criteria. Write the filtered table to a new TSV file preserving all original columns for retained rows. Validate the output by confirming row count is ≤ input row count and spot-checking that all remaining annotations meet the specified thresholds.
Related tools
- SIRIUS (Generates Zodiac and Cosmic confidence scores for in silico molecular formula and structure annotation; output filtered by min_ZodiacScore threshold) — https://bio.informatik.uni-jena.de/software/sirius/
- GNPS (Performs spectral library matching to generate cosine similarity and shared peak metrics; thresholds applied to clean up annotations before downstream analysis) — https://gnps.ucsd.edu
- Inventa (Implements threshold filtering for ppm_error, shared_peaks, cosine, min_ZodiacScore, min_ConfidenceScore, and min_score_final as part of annotation cleaning and Feature Component calculation) — https://github.com/luigiquiros/inventa
Examples
# In Inventa notebook:
min_ZodiacScore = 0.9 # Retain only SIRIUS annotations with Zodiac score ≥ 0.9
ppm_error = 5 # Retain annotations within 5 ppm mass error
shared_peaks = 10 # Retain matches with ≥10 shared MS2 peaks
cosine = 0.7 # Retain spectral matches with cosine similarity ≥ 0.7
# Filter is applied during annotation cleaning before Feature Component calculation
Evaluation signals
- Output row count is ≤ input row count (no rows added, only removed or retained).
- All retained rows have cosine ≥ threshold, shared_peaks ≥ threshold, ppm_error ≤ threshold, and (if applicable) min_ZodiacScore ≥ threshold.
- No rows in output violate any of the specified filter criteria; spot-check a sample of retained rows.
- Filter parameter values are documented and match the analysis goal (e.g., high stringency for Feature Component vs. exploratory annotation).
- Output file retains all original columns and metadata, with no unintended data loss.
Limitations
- Threshold values are user-defined and dataset-specific; suboptimal thresholds may result in over-filtering (missing true annotations) or under-filtering (retaining false positives).
- Different annotation sources (SIRIUS, GNPS, ISDB) use different scoring metrics; thresholds cannot be directly transferred between sources.
- Thresholding assumes independence between scoring dimensions (cosine, shared peaks, ppm error); some metrics may be correlated, potentially biasing the filtered set.
- No automatic mechanism to validate whether retained annotations are chemically or biologically plausible; manual curation may be needed for high-stakes applications.
Evidence
- [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] The min_ZodiacScore filtering mechanism applies a cut-off threshold of 0.9 to retain only SIRIUS annotations meeting or exceeding this confidence score, removing lower-scoring rows from the annotation table.: "The min_ZodiacScore filtering mechanism applies a cut-off threshold of 0.9 to retain only SIRIUS annotations meeting or exceeding this confidence score"
- [other] Parse the Zodiac score column and apply a minimum threshold filter (min_ZodiacScore = 0.9) to retain only rows where Zodiac score is ≥ 0.9.: "Parse the Zodiac score column and apply a minimum threshold filter (min_ZodiacScore = 0.9) to retain only rows where Zodiac score is ≥ 0.9"
- [other] ppm_error = 5 # min error in ppm to consider an annotation valable: "ppm_error = 5 # min error in ppm to consider an annotation valable"
- [other] shared_peaks = 10 # min number of shared peaks between the MS2 experimental and MS2 fro, the database, to consider an annotation valable: "shared_peaks = 10 # min number of shared peaks between the MS2 experimental and MS2 fro, the database"
- [other] cosine = 0.7 # min cosine score to consider an annotation valable: "cosine = 0.7 # min cosine score to consider an annotation valable"
- [other] Write the filtered annotation table to a new TSV file, retaining all original columns for retained rows.: "Write the filtered annotation table to a new TSV file, retaining all original columns for retained rows"
- [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"
1---2name: spectral-match-threshold-application3description: Use when after running spectral matching (e.g., GNPS library search, SIRIUS in silico annotation) and obtaining an annotation table with confidence scores, apply threshold filtering to remove low-confidence or spurious matches before downstream analysis (e.4license: CC-BY-4.05---67# Spectral Match Threshold Application89## Summary1011Apply confidence score cutoffs to MS/MS spectral annotations to retain only high-quality matches from spectral databases or in silico prediction tools. This skill filters annotation tables by requiring matches to meet or exceed user-defined thresholds on metrics like cosine similarity, shared peak count, and mass accuracy.1213## When to use1415After running spectral matching (e.g., GNPS library search, SIRIUS in silico annotation) and obtaining an annotation table with confidence scores, apply threshold filtering to remove low-confidence or spurious matches before downstream analysis (e.g., Feature Component calculation, chemical class assignment, or priority scoring in natural product discovery).1617## When NOT to use1819- Input is already a curated or manually validated annotation set — re-filtering may introduce unnecessary data loss.20- Thresholds are not defined or justified for your annotation source — arbitrary cutoffs risk over-filtering or under-filtering.21- You need to preserve all annotations for comparison or exploratory analysis — thresholding is irreversible without the original file.2223## Inputs2425- Annotation table in TSV format (e.g., compound_identification.tsv from SIRIUS, GNPS spectral library matches, or ISDB database search results)26- Metadata defining threshold parameters (cosine, shared_peaks, ppm_error, min_ZodiacScore, min_ConfidenceScore, min_score_final)2728## Outputs2930- Filtered annotation table (TSV format) containing only rows meeting all confidence thresholds31- Annotation count summary (rows retained vs. removed)3233## How to apply3435Load the annotation table (TSV format with confidence score columns such as cosine, Zodiac score, or shared peak counts). Define threshold parameters: minimum cosine similarity (e.g., 0.7), minimum shared peaks (e.g., 10), maximum ppm mass error (e.g., 5 ppm), and annotation-specific confidence cutoffs (e.g., min_ZodiacScore = 0.9 for SIRIUS, min_score_final = 0.0 for ISDB). Apply these thresholds sequentially or in combination as boolean filters to retain only rows meeting all criteria. Write the filtered table to a new TSV file preserving all original columns for retained rows. Validate the output by confirming row count is ≤ input row count and spot-checking that all remaining annotations meet the specified thresholds.3637## Related tools3839- **SIRIUS** (Generates Zodiac and Cosmic confidence scores for in silico molecular formula and structure annotation; output filtered by min_ZodiacScore threshold) — https://bio.informatik.uni-jena.de/software/sirius/40- **GNPS** (Performs spectral library matching to generate cosine similarity and shared peak metrics; thresholds applied to clean up annotations before downstream analysis) — https://gnps.ucsd.edu41- **Inventa** (Implements threshold filtering for ppm_error, shared_peaks, cosine, min_ZodiacScore, min_ConfidenceScore, and min_score_final as part of annotation cleaning and Feature Component calculation) — https://github.com/luigiquiros/inventa4243## Examples4445```46# In Inventa notebook:47min_ZodiacScore = 0.9 # Retain only SIRIUS annotations with Zodiac score ≥ 0.948ppm_error = 5 # Retain annotations within 5 ppm mass error49shared_peaks = 10 # Retain matches with ≥10 shared MS2 peaks50cosine = 0.7 # Retain spectral matches with cosine similarity ≥ 0.751# Filter is applied during annotation cleaning before Feature Component calculation52```5354## Evaluation signals5556- Output row count is ≤ input row count (no rows added, only removed or retained).57- All retained rows have cosine ≥ threshold, shared_peaks ≥ threshold, ppm_error ≤ threshold, and (if applicable) min_ZodiacScore ≥ threshold.58- No rows in output violate any of the specified filter criteria; spot-check a sample of retained rows.59- Filter parameter values are documented and match the analysis goal (e.g., high stringency for Feature Component vs. exploratory annotation).60- Output file retains all original columns and metadata, with no unintended data loss.6162## Limitations6364- Threshold values are user-defined and dataset-specific; suboptimal thresholds may result in over-filtering (missing true annotations) or under-filtering (retaining false positives).65- Different annotation sources (SIRIUS, GNPS, ISDB) use different scoring metrics; thresholds cannot be directly transferred between sources.66- Thresholding assumes independence between scoring dimensions (cosine, shared peaks, ppm error); some metrics may be correlated, potentially biasing the filtered set.67- No automatic mechanism to validate whether retained annotations are chemically or biologically plausible; manual curation may be needed for high-stakes applications.6869## Evidence7071- [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"72- [other] The min_ZodiacScore filtering mechanism applies a cut-off threshold of 0.9 to retain only SIRIUS annotations meeting or exceeding this confidence score, removing lower-scoring rows from the annotation table.: "The min_ZodiacScore filtering mechanism applies a cut-off threshold of 0.9 to retain only SIRIUS annotations meeting or exceeding this confidence score"73- [other] Parse the Zodiac score column and apply a minimum threshold filter (min_ZodiacScore = 0.9) to retain only rows where Zodiac score is ≥ 0.9.: "Parse the Zodiac score column and apply a minimum threshold filter (min_ZodiacScore = 0.9) to retain only rows where Zodiac score is ≥ 0.9"74- [other] ppm_error = 5 # min error in ppm to consider an annotation valable: "ppm_error = 5 # min error in ppm to consider an annotation valable"75- [other] shared_peaks = 10 # min number of shared peaks between the MS2 experimental and MS2 fro, the database, to consider an annotation valable: "shared_peaks = 10 # min number of shared peaks between the MS2 experimental and MS2 fro, the database"76- [other] cosine = 0.7 # min cosine score to consider an annotation valable: "cosine = 0.7 # min cosine score to consider an annotation valable"77- [other] Write the filtered annotation table to a new TSV file, retaining all original columns for retained rows.: "Write the filtered annotation table to a new TSV file, retaining all original columns for retained rows"78- [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"
HolobiomicsLab 