Threshold based match filtering

threshold-based-match-filtering

Summary

Filter metabolite matches from spectral database searches by applying a similarity threshold to retain only high-confidence assignments. This skill ensures that only metabolites with sufficiently strong spectral correlation to query peak networks are reported, reducing false positives in metabolite identification.

When to use

After calculating similarity metrics (e.g. cosine similarity or spectral correlation) between query peak networks and a simulated INADEQUATE database, when you need to distinguish true metabolite matches from spurious or low-confidence assignments and generate a curated list of identified metabolites with reliable match scores.

When NOT to use

• When no similarity metric has yet been computed between query and database spectra—filtering requires pre-calculated scores.
• When the goal is exploratory discovery of all possible matches regardless of confidence; thresholding discards lower-scoring candidates that may be biologically relevant in some contexts.
• When the query spectral data have not been pre-processed (shifted, picked, and clustered into peak networks); filtering assumes clean, validated input peak networks.

Inputs

• Peak network clusters (from upstream Clustering module)
• Simulated INADEQUATE metabolite database with reference spectral signatures
• Calculated similarity scores (cosine similarity or spectral correlation values) between each query peak network and database metabolites

Outputs

• Filtered metabolite match table
• Linked peak network identifiers to assigned metabolite names
• High-confidence match scores for retained assignments

How to apply

Calculate similarity metrics between each query peak network cluster and all reference metabolite signatures in the simulated INADEQUATE database. Define a similarity threshold appropriate to your confidence requirements and spectral data quality (the article and README do not specify a concrete threshold value). Filter the full match set to retain only those peak network–metabolite pairs exceeding this threshold. This filtering step reduces false positive identifications and produces a high-confidence metabolite assignment table. The filtered output links peak network identifiers, assigned metabolite names, and match scores, which can then be used for downstream interpretation or statistical validation.

Related tools

• PyINETA (Python package that implements the complete matching and filtering workflow, including similarity calculation and threshold-based filtering of peak network–metabolite pairs) — https://github.com/edisonomics/PyINETA
• Python (Language in which PyINETA and similarity metric computations (cosine similarity, spectral correlation) are implemented)

Examples

python <path_to_pyineta_repo>/run_pyineta.py -c config.ini -s match -o output_dir

Evaluation signals

• Verify that all retained matches have similarity scores ≥ the specified threshold and all discarded matches are below it (threshold consistency check).
• Check that the output table contains only peak networks from the input cluster set and only metabolite names present in the reference database (referential integrity).
• Confirm that match scores in the filtered table are numeric, non-null, and span a reasonable range (e.g. 0–1 for normalized metrics) and are monotonically ordered if sorting is applied.
• Validate that the number of retained matches per peak network is reasonable (e.g. typically 0–5 metabolites, or domain-specific expectations) and that no peak network appears with duplicate metabolite assignments after filtering.
• Cross-check a sample of filtered assignments by manual inspection or independent spectral comparison to ensure retained matches correspond to visually plausible peak network–metabolite alignments.

Limitations

• The article and README do not specify a recommended similarity threshold value; practitioners must determine this empirically based on their spectral quality, database composition, and acceptable false-positive rate.
• Threshold-based filtering is sensitive to the quality of the input similarity metric; poor peak picking, inadequate peak clustering, or weak database coverage will degrade match quality before filtering is applied.
• The choice of similarity metric (cosine similarity vs. spectral correlation vs. other measures) is not elaborated in the article; different metrics may produce different threshold-dependent results.
• No changelog or version-specific performance notes are provided, limiting guidance on how filtering behavior may vary across PyINETA versions.

Evidence

• [other] Calculate similarity metrics (e.g., cosine similarity or spectral correlation) between each query peak network and database metabolite signatures.: "Calculate similarity metrics (e.g., cosine similarity or spectral correlation) between each query peak network and database metabolite signatures."
• [other] Filter matches using a similarity threshold to retain high-confidence metabolite assignments.: "Filter matches using a similarity threshold to retain high-confidence metabolite assignments."
• [other] Generate a matched metabolite output table linking peak network identifiers, assigned metabolite names, and match scores using the pyINETA Matching module.: "Generate a matched metabolite output table linking peak network identifiers, assigned metabolite names, and match scores using the pyINETA Matching module."
• [readme] pyINETA matches identified peak networks to a simulated INADEQUATE database of metabolites to identify metabolites present in the query INADEQUATE spectra: "matches to a simulated INADEQUATE database of metabolites to identify metabolites present in the query INADEQUATE spectra"
• [methods] Matching

---

.. automodule:: pyineta.matching: "Matching

.. automodule:: pyineta.matching"