library-spectrum-database-format-parsing
Summary
Parse and extract spectral reference data from MSP and CSV library formats to enable MS/MS spectral library matching. This skill transforms raw library files into structured peak and metadata records suitable for cosine similarity or dot-product scoring against experimental spectra.
When to use
Apply this skill when you have experimental MS/MS spectra (from mzML, mzXML, or raw instrument formats) and wish to match them against a reference spectral library provided in MSP or CSV format. The skill is required as the first step before similarity scoring and candidate ranking.
When NOT to use
- Library data is already in a proprietary database or binary format not explicitly listed as MSP or CSV
- Experimental spectra lack precursor m/z or retention time information needed for matching
- Input spectra are MS1-only (no MS/MS fragmentation data available)
Inputs
- MSP library file (text format with spectrum metadata and peak lists)
- CSV library file (tabular format with spectrum identifiers and fragment ions)
- Experimental MS/MS spectral data (mzML, mzXML, or raw instrument format)
Outputs
- Parsed spectral library records (reference spectrum identities, fragment m/z, intensities)
- Matched library spectra ranked by similarity score
- Results file (CSV or JSON) with spectrum metadata, library accession, match score, and fragment ion assignments
How to apply
Load the spectral library file in either MSP or CSV format and parse it to extract reference spectrum identities, fragment m/z values, and intensities for each library entry. MSP files typically contain spectrum metadata headers followed by peak lists; CSV files contain tabular rows of spectrum accessions and fragment ion data. Store the parsed library entries in memory or indexed structure. The TandemMatch module implements this parsing and subsequent matching workflow: after loading the reference library, it applies cosine similarity or dot-product scoring to each experimental MS/MS spectrum against all library entries, filters candidates using a similarity threshold and precursor m/z mass tolerance window, ranks matches by score, and outputs results with spectrum metadata, library accession, match score, and fragment ion assignments.
Related tools
Evaluation signals
- All library entries are successfully parsed without errors or dropped records; verify by comparing input file line count (for CSV) or spectrum count (for MSP) against parsed record count
- Fragment m/z values and intensities are correctly extracted and fall within expected ranges for the instrument and ionization mode
- Precursor m/z values parsed from library metadata match expected mass ranges and are consistent with chemical composition of reference compounds
- Matched results include non-empty library accession, match score, and fragment ion assignment fields; check that match score is within [0, 1] range for normalized similarity metrics
- Output file schema matches expected structure (CSV or JSON) with all required columns or fields populated for each match
Limitations
- No changelog found in repository documentation, limiting visibility into format compatibility and parser version history
- MSP and CSV format specifications and strictness of parsing (e.g., handling malformed headers, missing fields, or non-standard delimiters) are not detailed
- Library matching performance and scalability with very large libraries (millions of spectra) are not characterized
- Support for proprietary or vendor-specific library formats (e.g., NIST .msp dialects, instrument-specific formats) is not discussed
Evidence
- [other] Load spectral library from MSP or CSV format, extracting reference spectrum identities, fragment m/z values, and intensities.: "Load spectral library from MSP or CSV format, extracting reference spectrum identities, fragment m/z values, and intensities."
- [readme] TandemMatch: MS/MS spectral library matching with support for MSP and CSV library formats.: "TandemMatch: MS/MS spectral library matching with support for MSP and CSV library formats."
- [other] Apply cosine similarity or dot-product scoring to compare each experimental MS/MS spectrum against all library entries.: "Apply cosine similarity or dot-product scoring to compare each experimental MS/MS spectrum against all library entries."
- [other] Filter candidate matches using a similarity threshold and mass tolerance window on precursor m/z.: "Filter candidate matches using a similarity threshold and mass tolerance window on precursor m/z."
- [other] Rank matched library spectra by score and output matched records with spectrum metadata, library accession, match score, and fragment ion assignments to a structured results file (CSV or JSON).: "Rank matched library spectra by score and output matched records with spectrum metadata, library accession, match score, and fragment ion assignments to a structured results file (CSV or JSON)."
1---2name: library-spectrum-database-format-parsing3description: Use when you have experimental MS/MS spectra (from mzML, mzXML, or raw instrument formats) and wish to match them against a reference spectral library provided in MSP or CSV format. The skill is required as the first step before similarity scoring and candidate ranking.4license: CC-BY-4.05---67# library-spectrum-database-format-parsing89## Summary1011Parse and extract spectral reference data from MSP and CSV library formats to enable MS/MS spectral library matching. This skill transforms raw library files into structured peak and metadata records suitable for cosine similarity or dot-product scoring against experimental spectra.1213## When to use1415Apply this skill when you have experimental MS/MS spectra (from mzML, mzXML, or raw instrument formats) and wish to match them against a reference spectral library provided in MSP or CSV format. The skill is required as the first step before similarity scoring and candidate ranking.1617## When NOT to use1819- Library data is already in a proprietary database or binary format not explicitly listed as MSP or CSV20- Experimental spectra lack precursor m/z or retention time information needed for matching21- Input spectra are MS1-only (no MS/MS fragmentation data available)2223## Inputs2425- MSP library file (text format with spectrum metadata and peak lists)26- CSV library file (tabular format with spectrum identifiers and fragment ions)27- Experimental MS/MS spectral data (mzML, mzXML, or raw instrument format)2829## Outputs3031- Parsed spectral library records (reference spectrum identities, fragment m/z, intensities)32- Matched library spectra ranked by similarity score33- Results file (CSV or JSON) with spectrum metadata, library accession, match score, and fragment ion assignments3435## How to apply3637Load the spectral library file in either MSP or CSV format and parse it to extract reference spectrum identities, fragment m/z values, and intensities for each library entry. MSP files typically contain spectrum metadata headers followed by peak lists; CSV files contain tabular rows of spectrum accessions and fragment ion data. Store the parsed library entries in memory or indexed structure. The TandemMatch module implements this parsing and subsequent matching workflow: after loading the reference library, it applies cosine similarity or dot-product scoring to each experimental MS/MS spectrum against all library entries, filters candidates using a similarity threshold and precursor m/z mass tolerance window, ranks matches by score, and outputs results with spectrum metadata, library accession, match score, and fragment ion assignments.3839## Related tools4041- **TandemMatch** (Implements MS/MS spectral library matching with MSP and CSV library format parsing, scoring, filtering, and ranking of candidate matches) — https://github.com/pnnl/IonToolPack42- **IonToolPack** (Software suite housing TandemMatch and providing omics-agnostic MS data processing with GUI interface) — https://github.com/pnnl/IonToolPack4344## Evaluation signals4546- All library entries are successfully parsed without errors or dropped records; verify by comparing input file line count (for CSV) or spectrum count (for MSP) against parsed record count47- Fragment m/z values and intensities are correctly extracted and fall within expected ranges for the instrument and ionization mode48- Precursor m/z values parsed from library metadata match expected mass ranges and are consistent with chemical composition of reference compounds49- Matched results include non-empty library accession, match score, and fragment ion assignment fields; check that match score is within [0, 1] range for normalized similarity metrics50- Output file schema matches expected structure (CSV or JSON) with all required columns or fields populated for each match5152## Limitations5354- No changelog found in repository documentation, limiting visibility into format compatibility and parser version history55- MSP and CSV format specifications and strictness of parsing (e.g., handling malformed headers, missing fields, or non-standard delimiters) are not detailed56- Library matching performance and scalability with very large libraries (millions of spectra) are not characterized57- Support for proprietary or vendor-specific library formats (e.g., NIST .msp dialects, instrument-specific formats) is not discussed5859## Evidence6061- [other] Load spectral library from MSP or CSV format, extracting reference spectrum identities, fragment m/z values, and intensities.: "Load spectral library from MSP or CSV format, extracting reference spectrum identities, fragment m/z values, and intensities."62- [readme] TandemMatch: MS/MS spectral library matching with support for MSP and CSV library formats.: "TandemMatch: MS/MS spectral library matching with support for MSP and CSV library formats."63- [other] Apply cosine similarity or dot-product scoring to compare each experimental MS/MS spectrum against all library entries.: "Apply cosine similarity or dot-product scoring to compare each experimental MS/MS spectrum against all library entries."64- [other] Filter candidate matches using a similarity threshold and mass tolerance window on precursor m/z.: "Filter candidate matches using a similarity threshold and mass tolerance window on precursor m/z."65- [other] Rank matched library spectra by score and output matched records with spectrum metadata, library accession, match score, and fragment ion assignments to a structured results file (CSV or JSON).: "Rank matched library spectra by score and output matched records with spectrum metadata, library accession, match score, and fragment ion assignments to a structured results file (CSV or JSON)."
HolobiomicsLab