annotation-table-quality-control
Summary
Apply confidence-based filtering to annotation tables (SIRIUS/ISDB) to retain only high-confidence molecular identifications meeting specified threshold criteria. This ensures downstream analyses operate on reliable, validated compound annotations by removing low-scoring rows.
When to use
After obtaining in silico annotations from SIRIUS (Zodiac/Cosmic scores) or ISDB (cosine/shared peaks metrics), before using the annotation table for Feature Component calculation, chemical class assignment, or metabolite discovery prioritization. Apply when annotation scores vary widely and you need to enforce minimum quality standards (e.g., min_ZodiacScore ≥ 0.9 for SIRIUS or cosine ≥ 0.7 for ISDB).
When NOT to use
- Annotations are already pre-filtered by the annotation tool itself and you have no domain reason to apply stricter thresholds.
- The annotation table contains predominantly high-confidence hits and applying aggressive thresholds would remove too many valid identifications.
- You require all candidate annotations (including low-confidence ones) for comparative or exploratory analysis of annotation uncertainty.
Inputs
- SIRIUS compound_identification.tsv file with Zodiac, Cosmic, and ConfidenceScore columns
- ISDB annotation table with cosine, shared_peaks, ppm_error, and final_score columns
- Tabular annotation file (TSV/CSV format) from spectral database matching workflow
Outputs
- Filtered annotation table (TSV format) retaining all original columns for high-confidence rows only
- Row count and filtering statistics (rows retained vs. removed per filter criterion)
How to apply
Load the annotation table (TSV format with score columns: Zodiac, Cosmic, cosine, shared_peaks, or confidence metrics). Parse and apply multiple filter criteria in sequence: (1) ppm_error ≤ 5 ppm tolerance; (2) shared_peaks ≥ 10 minimum spectral matches; (3) cosine ≥ 0.7 similarity threshold; (4) min_ZodiacScore ≥ 0.9 for SIRIUS annotations; (5) min_ConfidenceScore ≥ 0.0 (or user-defined); (6) min_score_final ≥ 0.0 for ISDB. Retain all original columns for rows passing all thresholds. Validate output by verifying row count ≤ input row count and spot-checking that all retained rows meet the specified thresholds.
Related tools
- SIRIUS (Generates in silico molecular structure predictions with Zodiac and Cosmic confidence scores that are filtered by this skill) — https://bio.informatik.uni-jena.de/software/sirius/
- CANOPUS (Produces chemical class predictions downstream of SIRIUS; quality-controlled annotations feed into Class Component calculation)
- Inventa (Consumes quality-controlled annotation tables to compute Feature Component and downstream novelty scoring) — https://github.com/luigiquiros/inventa
- GNPS (Provides ISDB spectral matching results (cosine, shared_peaks, ppm_error) that are filtered by this skill)
Examples
# Load SIRIUS annotations and apply min_ZodiacScore threshold
import pandas as pd
df = pd.read_csv('compound_identification.tsv', sep='\t')
df_filtered = df[df['ZodiacScore'] >= 0.9]
df_filtered.to_csv('compound_identification_filtered.tsv', sep='\t', index=False)
print(f'Retained {len(df_filtered)} of {len(df)} rows (ZodiacScore >= 0.9)')
Evaluation signals
- Output row count is ≤ input row count; no rows are added, only removed.
- All retained rows in output have Zodiac score ≥ 0.9 (or other specified threshold) with no exceptions.
- All retained rows have shared_peaks ≥ 10 AND cosine ≥ 0.7 AND ppm_error ≤ 5 ppm (if ISDB annotations).
- Output TSV retains all original columns (e.g., compound_name, inchikey, Zodiac, Cosmic, ConfidenceScore); no columns are dropped.
- Filtering statistics report (e.g., '1,247 rows input; 892 rows retained; 355 rows removed by min_ZodiacScore filter') is consistent with manual spot-check of marginal rows.
Limitations
- Hard thresholds (e.g., min_ZodiacScore = 0.9) may be overly restrictive for samples with naturally low annotation confidence or for rare metabolites with few library matches.
- Threshold values are dataset- and ionization-mode dependent; no universal cutoffs are specified in the article; users must empirically validate thresholds for their specific LC-MS method and sample type.
- Filtering is applied independently to each criterion without accounting for correlations among scores; a row may pass one threshold but fail another unrelated one.
- No changelog or versioning mechanism is documented, making it difficult to track changes in filtering logic or threshold definitions over time across projects.
Evidence
- [other] 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, removing lower-scoring rows from the"
- [other] Load SIRIUS annotations file and parse Zodiac score column; apply minimum threshold filter (min_ZodiacScore = 0.9) and optional ConfidenceScore cut-off; write filtered table to TSV retaining all original columns.: "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. 3. Optionally apply the ConfidenceScore cut-off"
- [other] Multiple filter criteria for ISDB annotations: ppm_error = 5 ppm, shared_peaks = 10, cosine = 0.7, min_score_final = 0.0: "ppm_error = 5 # min error in ppm to consider an annotation valable shared_peaks = 10 # min number of shared peaks cosine = 0.7 # min cosine score to consider an annotation valable min_score_final ="
- [other] Validation step verifies output contains only rows meeting threshold criteria and row count ≤ input.: "Validation: verify the output file contains only rows with Zodiac score ≥ 0.9 and row count is less than or equal to the input row count."
- [other] Configure annotation cleaning parameters including ppm_error, shared_peaks, cosine, and ionisation_mode for cleaning GNPS annotations.: "Set annotation cleaning parameters (ppm_error, shared_peaks, cosine, ionisation_mode) [section=other; evidence='For cleaning-up annotations from GNPS ppm_error = 5 # min error in ppm to consider an"
1---2name: annotation-table-quality-control-23description: Use when after obtaining in silico annotations from SIRIUS (Zodiac/Cosmic scores) or ISDB (cosine/shared peaks metrics), before using the annotation table for Feature Component calculation, chemical class assignment, or metabolite discovery prioritization.4license: CC-BY-4.05---67# annotation-table-quality-control89## Summary1011Apply confidence-based filtering to annotation tables (SIRIUS/ISDB) to retain only high-confidence molecular identifications meeting specified threshold criteria. This ensures downstream analyses operate on reliable, validated compound annotations by removing low-scoring rows.1213## When to use1415After obtaining in silico annotations from SIRIUS (Zodiac/Cosmic scores) or ISDB (cosine/shared peaks metrics), before using the annotation table for Feature Component calculation, chemical class assignment, or metabolite discovery prioritization. Apply when annotation scores vary widely and you need to enforce minimum quality standards (e.g., min_ZodiacScore ≥ 0.9 for SIRIUS or cosine ≥ 0.7 for ISDB).1617## When NOT to use1819- Annotations are already pre-filtered by the annotation tool itself and you have no domain reason to apply stricter thresholds.20- The annotation table contains predominantly high-confidence hits and applying aggressive thresholds would remove too many valid identifications.21- You require all candidate annotations (including low-confidence ones) for comparative or exploratory analysis of annotation uncertainty.2223## Inputs2425- SIRIUS compound_identification.tsv file with Zodiac, Cosmic, and ConfidenceScore columns26- ISDB annotation table with cosine, shared_peaks, ppm_error, and final_score columns27- Tabular annotation file (TSV/CSV format) from spectral database matching workflow2829## Outputs3031- Filtered annotation table (TSV format) retaining all original columns for high-confidence rows only32- Row count and filtering statistics (rows retained vs. removed per filter criterion)3334## How to apply3536Load the annotation table (TSV format with score columns: Zodiac, Cosmic, cosine, shared_peaks, or confidence metrics). Parse and apply multiple filter criteria in sequence: (1) ppm_error ≤ 5 ppm tolerance; (2) shared_peaks ≥ 10 minimum spectral matches; (3) cosine ≥ 0.7 similarity threshold; (4) min_ZodiacScore ≥ 0.9 for SIRIUS annotations; (5) min_ConfidenceScore ≥ 0.0 (or user-defined); (6) min_score_final ≥ 0.0 for ISDB. Retain all original columns for rows passing all thresholds. Validate output by verifying row count ≤ input row count and spot-checking that all retained rows meet the specified thresholds.3738## Related tools3940- **SIRIUS** (Generates in silico molecular structure predictions with Zodiac and Cosmic confidence scores that are filtered by this skill) — https://bio.informatik.uni-jena.de/software/sirius/41- **CANOPUS** (Produces chemical class predictions downstream of SIRIUS; quality-controlled annotations feed into Class Component calculation)42- **Inventa** (Consumes quality-controlled annotation tables to compute Feature Component and downstream novelty scoring) — https://github.com/luigiquiros/inventa43- **GNPS** (Provides ISDB spectral matching results (cosine, shared_peaks, ppm_error) that are filtered by this skill)4445## Examples4647```48# Load SIRIUS annotations and apply min_ZodiacScore threshold49import pandas as pd50df = pd.read_csv('compound_identification.tsv', sep='\t')51df_filtered = df[df['ZodiacScore'] >= 0.9]52df_filtered.to_csv('compound_identification_filtered.tsv', sep='\t', index=False)53print(f'Retained {len(df_filtered)} of {len(df)} rows (ZodiacScore >= 0.9)')54```5556## Evaluation signals5758- Output row count is ≤ input row count; no rows are added, only removed.59- All retained rows in output have Zodiac score ≥ 0.9 (or other specified threshold) with no exceptions.60- All retained rows have shared_peaks ≥ 10 AND cosine ≥ 0.7 AND ppm_error ≤ 5 ppm (if ISDB annotations).61- Output TSV retains all original columns (e.g., compound_name, inchikey, Zodiac, Cosmic, ConfidenceScore); no columns are dropped.62- Filtering statistics report (e.g., '1,247 rows input; 892 rows retained; 355 rows removed by min_ZodiacScore filter') is consistent with manual spot-check of marginal rows.6364## Limitations6566- Hard thresholds (e.g., min_ZodiacScore = 0.9) may be overly restrictive for samples with naturally low annotation confidence or for rare metabolites with few library matches.67- Threshold values are dataset- and ionization-mode dependent; no universal cutoffs are specified in the article; users must empirically validate thresholds for their specific LC-MS method and sample type.68- Filtering is applied independently to each criterion without accounting for correlations among scores; a row may pass one threshold but fail another unrelated one.69- No changelog or versioning mechanism is documented, making it difficult to track changes in filtering logic or threshold definitions over time across projects.7071## Evidence7273- [other] 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, removing lower-scoring rows from the"74- [other] Load SIRIUS annotations file and parse Zodiac score column; apply minimum threshold filter (min_ZodiacScore = 0.9) and optional ConfidenceScore cut-off; write filtered table to TSV retaining all original columns.: "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. 3. Optionally apply the ConfidenceScore cut-off"75- [other] Multiple filter criteria for ISDB annotations: ppm_error = 5 ppm, shared_peaks = 10, cosine = 0.7, min_score_final = 0.0: "ppm_error = 5 # min error in ppm to consider an annotation valable shared_peaks = 10 # min number of shared peaks cosine = 0.7 # min cosine score to consider an annotation valable min_score_final ="76- [other] Validation step verifies output contains only rows meeting threshold criteria and row count ≤ input.: "Validation: verify the output file contains only rows with Zodiac score ≥ 0.9 and row count is less than or equal to the input row count."77- [other] Configure annotation cleaning parameters including ppm_error, shared_peaks, cosine, and ionisation_mode for cleaning GNPS annotations.: "Set annotation cleaning parameters (ppm_error, shared_peaks, cosine, ionisation_mode) [section=other; evidence='For cleaning-up annotations from GNPS ppm_error = 5 # min error in ppm to consider an"
HolobiomicsLab