unknown-sample-reference-comparison
Summary
Assign candidate species scores to unknown mass spectrometry samples by computing similarity metrics between preprocessed unknown spectra and a reference database of known species spectra. This skill enables automated species authentication through ranked candidate lists with match scores.
When to use
You have a preprocessed unknown sample spectrum (m/z peaks and intensities) from high-throughput mass spectrometry (DI-MS, ASAP-MS, or ambient ionization methods) and need to identify the species or authenticate a sample against a curated reference database of known spectra. Apply this skill when the goal is to rank candidate matches rather than perform de novo identification.
When NOT to use
- Reference database is absent, incomplete, or not appropriate for the sample type (e.g., plant reference database used for microbial unknowns).
- Unknown sample spectrum is raw or unpreprocessed; preprocessing (peak picking, normalization, m/z alignment) must precede database search.
- The goal is structural elucidation or compound annotation of novel unknowns; this skill ranks known species, not discovers new compounds.
Inputs
- preprocessed unknown sample spectrum (m/z peaks and intensities)
- reference species database (known spectra with m/z features and intensities)
- species identifiers and accession numbers
Outputs
- ranked candidate species list (CSV or TSV)
- columns: rank, species name, reference_id, similarity_score
- visual outputs for candidate discrimination
How to apply
Load the preprocessed unknown sample spectrum and the reference species database containing known spectra with m/z features and intensities. For each reference spectrum in the database, compute a similarity score using a distance or correlation metric such as cosine similarity or Euclidean distance on aligned m/z features. Rank all reference entries by descending similarity score. Output the full scored candidate list with columns for rank, species name, reference identifier, and similarity score in tabular format (CSV or TSV). The scoring algorithm integrates automatic peak identification to focus the comparison on relevant m/z peaks, improving discrimination accuracy.
Related tools
- RapidMass (integrates data pre-processing, analysis, and database search scoring; provides automatic peak identification and user-friendly visual interface for candidate ranking and species authentication) — github.com/Katherine00689/RapidMass
Evaluation signals
- Output tabular format contains exactly five columns (rank, species, reference_id, similarity_score, and optionally accession details) with no missing values.
- Similarity scores are bounded within a valid metric range (e.g., [0, 1] for normalized cosine similarity or [0, ∞) for Euclidean distance) and monotonically decrease by rank.
- Known or positive control samples return the correct reference species in the top-ranked candidates (rank ≤ 5 for easily confused plant materials, per validation).
- Visual outputs (e.g., spectral overlay plots or heatmaps) clearly distinguish high-scoring matches from low-scoring candidates.
- All reference database entries are scored and ranked; no reference spectra are skipped or omitted from the candidate list.
Limitations
- Performance depends on the quality, completeness, and relevance of the reference database; easily confused or morphologically similar species may produce ambiguous scores.
- Alignment of m/z features between unknown and reference spectra requires consistent preprocessing and calibration; instrument-specific variations (DI-MS vs. ASAP-MS vs. AI-MS) may affect score reliability.
- No changelog or version history documented; stability and reproducibility across software updates cannot be tracked.
- Similarity metrics (cosine similarity, Euclidean distance) are sensitive to peak intensity normalization and m/z tolerance; threshold choice for candidate acceptance is not specified in the article.
Evidence
- [other] For each reference spectrum in the database, compute a similarity score between the unknown sample and the reference using a distance or correlation metric (e.g., cosine similarity or Euclidean distance on aligned m/z features).: "For each reference spectrum in the database, compute a similarity score between the unknown sample and the reference using a distance or correlation metric (e.g., cosine similarity or Euclidean"
- [other] RapidMass integrates data pre-processing, analysis, and evaluation to enable direct discrimination of unknown sample species through database search algorithms that produce candidate scores with visual outputs.: "integrates data pre-processing, analysis, and evaluation to enable direct discrimination of unknown sample species through database search algorithms that produce candidate scores with visual outputs"
- [other] Return results in a tabular format (CSV or TSV) with columns for rank, species, reference_id, and similarity_score.: "Return results in a tabular format (CSV or TSV) with columns for rank, species, reference_id, and similarity_score."
- [intro] RapidMass offers several database search algorithms to achieve unknown sample scoring.: "RapidMass offers several database search algorithms to achieve unknown sample scoring"
- [readme] The performance of RapidMass was validated using easily confused plant materials, with satisfactory results.: "The performance of RapidMass was validated using easily confused plant materials, with satisfactory results."
1---2name: unknown-sample-reference-comparison-23description: Use when you have a preprocessed unknown sample spectrum (m/z peaks and intensities) from high-throughput mass spectrometry (DI-MS, ASAP-MS, or ambient ionization methods) and need to identify the species or authenticate a sample against a curated reference database of known spectra.4license: CC-BY-4.05---67# unknown-sample-reference-comparison89## Summary1011Assign candidate species scores to unknown mass spectrometry samples by computing similarity metrics between preprocessed unknown spectra and a reference database of known species spectra. This skill enables automated species authentication through ranked candidate lists with match scores.1213## When to use1415You have a preprocessed unknown sample spectrum (m/z peaks and intensities) from high-throughput mass spectrometry (DI-MS, ASAP-MS, or ambient ionization methods) and need to identify the species or authenticate a sample against a curated reference database of known spectra. Apply this skill when the goal is to rank candidate matches rather than perform de novo identification.1617## When NOT to use1819- Reference database is absent, incomplete, or not appropriate for the sample type (e.g., plant reference database used for microbial unknowns).20- Unknown sample spectrum is raw or unpreprocessed; preprocessing (peak picking, normalization, m/z alignment) must precede database search.21- The goal is structural elucidation or compound annotation of novel unknowns; this skill ranks known species, not discovers new compounds.2223## Inputs2425- preprocessed unknown sample spectrum (m/z peaks and intensities)26- reference species database (known spectra with m/z features and intensities)27- species identifiers and accession numbers2829## Outputs3031- ranked candidate species list (CSV or TSV)32- columns: rank, species name, reference_id, similarity_score33- visual outputs for candidate discrimination3435## How to apply3637Load the preprocessed unknown sample spectrum and the reference species database containing known spectra with m/z features and intensities. For each reference spectrum in the database, compute a similarity score using a distance or correlation metric such as cosine similarity or Euclidean distance on aligned m/z features. Rank all reference entries by descending similarity score. Output the full scored candidate list with columns for rank, species name, reference identifier, and similarity score in tabular format (CSV or TSV). The scoring algorithm integrates automatic peak identification to focus the comparison on relevant m/z peaks, improving discrimination accuracy.3839## Related tools4041- **RapidMass** (integrates data pre-processing, analysis, and database search scoring; provides automatic peak identification and user-friendly visual interface for candidate ranking and species authentication) — github.com/Katherine00689/RapidMass4243## Evaluation signals4445- Output tabular format contains exactly five columns (rank, species, reference_id, similarity_score, and optionally accession details) with no missing values.46- Similarity scores are bounded within a valid metric range (e.g., [0, 1] for normalized cosine similarity or [0, ∞) for Euclidean distance) and monotonically decrease by rank.47- Known or positive control samples return the correct reference species in the top-ranked candidates (rank ≤ 5 for easily confused plant materials, per validation).48- Visual outputs (e.g., spectral overlay plots or heatmaps) clearly distinguish high-scoring matches from low-scoring candidates.49- All reference database entries are scored and ranked; no reference spectra are skipped or omitted from the candidate list.5051## Limitations5253- Performance depends on the quality, completeness, and relevance of the reference database; easily confused or morphologically similar species may produce ambiguous scores.54- Alignment of m/z features between unknown and reference spectra requires consistent preprocessing and calibration; instrument-specific variations (DI-MS vs. ASAP-MS vs. AI-MS) may affect score reliability.55- No changelog or version history documented; stability and reproducibility across software updates cannot be tracked.56- Similarity metrics (cosine similarity, Euclidean distance) are sensitive to peak intensity normalization and m/z tolerance; threshold choice for candidate acceptance is not specified in the article.5758## Evidence5960- [other] For each reference spectrum in the database, compute a similarity score between the unknown sample and the reference using a distance or correlation metric (e.g., cosine similarity or Euclidean distance on aligned m/z features).: "For each reference spectrum in the database, compute a similarity score between the unknown sample and the reference using a distance or correlation metric (e.g., cosine similarity or Euclidean"61- [other] RapidMass integrates data pre-processing, analysis, and evaluation to enable direct discrimination of unknown sample species through database search algorithms that produce candidate scores with visual outputs.: "integrates data pre-processing, analysis, and evaluation to enable direct discrimination of unknown sample species through database search algorithms that produce candidate scores with visual outputs"62- [other] Return results in a tabular format (CSV or TSV) with columns for rank, species, reference_id, and similarity_score.: "Return results in a tabular format (CSV or TSV) with columns for rank, species, reference_id, and similarity_score."63- [intro] RapidMass offers several database search algorithms to achieve unknown sample scoring.: "RapidMass offers several database search algorithms to achieve unknown sample scoring"64- [readme] The performance of RapidMass was validated using easily confused plant materials, with satisfactory results.: "The performance of RapidMass was validated using easily confused plant materials, with satisfactory results."
HolobiomicsLab 