eduKateSG · Why Science?
Share reference spectra as an inspectable scientific library—while preserving analytes, interpretations, provenance, identifiers and uncertainty
Choose the closest route, then return to the full index whenever you need the wider evidence chain.
Science learning becomes powerful when students can tell a measured pattern from a model, a statistical decision from a mechanism, and a useful lead from a finished conclusion. mzSpecLib is the HUPO Proteomics Standards Initiative standard for storing and distributing mass-spectral libraries. The official PSI page says version 1.0 has been formally ratified and explains that earlier libraries used several provider-specific formats, making exchange and tool comparison difficult. mzSpecLib focuses on a structured data model and controlled-vocabulary metadata while permitting interchangeable serialisations. A library spectrum is reusable reference evidence; it is not automatically an identification of a new sample, a quantitative result or proof of biological function. This guide supports Primary Science, PSLE Science, Secondary Science, O-Level Science and STEM education as a longform evidence-reading route; it is not medical advice, a laboratory protocol, an admission promise or a career guarantee.
Related eduKate reading: mzML and open mass-spectrometry data; Universal Spectrum Identifiers and mass spectrometry; mzIdentML and proteomics identification results; PSI-MOD and protein modification vocabulary; Science Learning Hub; Education Hub; STEM Education; Careers by Subject Capability.
Primary and official sources checked on 12 October 2026: HUPO-PSI mzSpecLib official standard page, updated 7 August 2025 and checked 12 October 2026; HUPO-PSI mzSpecLib official repository and version 1.0 specification, checked 12 October 2026; HUPO-PSI mzPAF official companion standard for peak annotations, checked 12 October 2026; 2026 Singapore–Cambridge O-Level Biology syllabus; MOE G2/G3 Lower Secondary Science teaching and learning syllabus; 2026 MOE G2 Computing syllabus. Specifications, vocabularies, repository services and recommendations can change, so preserve dated documentation, exact source data and software versions.
A deeper reading route
A spectral library collects representative spectra with enough context for software and people to reuse them. A query spectrum can be compared with library spectra, but the match is a model-based result. Its meaning depends on precursor information, peaks, candidate analyte, acquisition conditions, scoring and the construction of the library. mzSpecLib supplies a common vocabulary and data model so that these ingredients do not disappear inside a provider-specific export.
The need for a shared format is practical. The official page lists MSP, X!Hunter binary MGF, BiblioSpec SQLite and SSL/MS2, SpectraST SPLIB/SPTXT, MassBank formats and vendor tables as examples of earlier ecosystems. Some search engines read several formats and some read only a subset. Conversion can lose metadata or reinterpret fields, so a standard must define meaning rather than merely choose a new filename.
The standard treats a library as organised records rather than a bag of peak lists. Library-level metadata describes the collection and its provenance. Spectrum-level attributes locate and characterise an entry. Analytes describe the molecular entities proposed to produce it, and interpretations connect evidence with a particular explanation. Those layers should remain distinguishable when one spectrum has alternatives or one analyte has several spectra.
Peak annotations are a separate but related challenge. mzPAF is the PSI companion format for annotating fragment-ion peaks and is linked from the official mzSpecLib page. A peak label can propose an ion series, charge, neutral loss or other interpretation, yet an annotation still depends on rules and evidence. The raw m/z and intensity values should remain available beside the interpretation.
Controlled vocabulary terms reduce ambiguity for instruments, acquisition methods, spectrum attributes, scores and units. A stable accession is safer than free text, but vocabulary releases change. Reproducible exchange therefore pins the mzSpecLib specification, the relevant PSI-MS and PSI-MOD releases, software versions and any local terms used by the library builder.
Spectral libraries can be empirical, predicted or hybrid. An empirical entry may combine observations from one or many runs; a predicted entry comes from a model. Both can be useful, but they should not be presented as the same evidence type. Aggregation, peak filtering and normalisation rules belong in the provenance because they shape the reference used by every later match.
Serialization flexibility is deliberate. The official page says the specification concentrates on the data model and controlled-vocabulary mechanism while allowing several interchangeable serializations. That design invites broad tooling, but it raises the bar for round-trip tests. Converting text to another representation should preserve identifiers, attributes, analytes, interpretations, peaks and numerical precision.
A library match should remain linked to the query spectrum. mzML can carry acquired spectra, a Universal Spectrum Identifier can help point to a public spectrum, and mzIdentML can carry identification results. mzSpecLib occupies the reusable-reference layer. Keeping those roles separate prevents a reference entry from being mistaken for a sample observation or a downstream acceptance decision.
A useful audit selects one library spectrum and walks every relationship. Resolve its library identifier, spectrum attributes, analyte and interpretation, then check precursor values, peak array, annotations, source evidence and creation method. Recalculate a few mass differences and inspect a query match. If a relationship or unit cannot be resolved, report the limitation instead of guessing from the display label.
The optimistic promise is shared reuse. A well-governed open spectral library can let laboratories compare tools, teach spectrum reasoning and build new analyses without re-entering local formats. The standard does not erase experimental differences; it makes those differences easier to describe, test and improve together.
A preservation package should include the original library, any converted representation, final specification, controlled-vocabulary files, build scripts, source identifiers, validation output and checksums. When the library is updated, publish a change log that distinguishes newly added spectra, revised interpretations and purely technical re-serialization. Users can then decide whether a change should alter a search result.
Library coverage should be reported positively and negatively. State which analytes, charge states, modifications, instruments and collision conditions are represented, then name major exclusions. A query that returns no convincing match may fall outside that boundary; it is not evidence that the molecule is absent from the sample.
Benchmarking should avoid circular evidence. If spectra used to build a library also appear in the evaluation set, apparent performance can be inflated. Hold out independent source files or datasets, disclose overlap checks and compare performance across compatible acquisition settings. The standard helps exchange the library, while study design determines whether the benchmark is fair.
A reader-facing record can show the spectrum identifier, analyte notation, precursor, a small peak plot, provenance and confidence note, then link to the full machine-readable entry. This layered presentation makes an advanced standard approachable without hiding the raw numerical evidence or turning a library explanation into a claim about a person or patient.
Search thresholds should be validated in the intended domain. A score calibrated on one instrument, fragmentation mode or library composition may not transfer cleanly to another. Record decoy strategy, candidate competition and false-discovery method, and keep the unfiltered result so a later reviewer can examine how the accepted set changed at the boundary.
| Stage | Question | Evidence | Responsible output |
|---|---|---|---|
| Collect | Which spectra belong in the library? | Source observations or predictions, selection rules and provenance | A governed reference collection |
| Describe | What does each record contain? | Spectrum attributes, analytes, interpretations and peaks | A machine-readable library entry |
| Compare | How is a new spectrum matched? | Search settings, scores, alternatives and source links | A bounded identification candidate |
| Preserve | Can another tool reproduce the meaning? | Versioned terms, validation, round trips and hashes | A reusable open library |
Inside this guide
1–12 · Foundations and design
- 1. Start with the reuse question
- 2. Use the ratified standard
- 3. Define the library boundary
- 4. Describe library provenance
- 5. Assign stable identifiers
- 6. Read spectrum attributes
- 7. Read the peak array
- 8. Separate analyte from spectrum
- 9. Separate interpretation from observation
- 10. Use mzPAF deliberately
- 11. Describe modifications precisely
- 12. Record decoys and negatives
13–24 · Models and estimation
- 13. Distinguish empirical spectra
- 14. Distinguish predicted spectra
- 15. Explain consensus building
- 16. Preserve units and precision
- 17. Use controlled vocabulary accessions
- 18. Test serialization round trips
- 19. Validate structure
- 20. Validate semantic meaning
- 21. Validate search behaviour
- 22. Follow one query spectrum
- 23. Treat similarity as evidence
- 24. Check transfer integrity
25–36 · Diagnostics and interpretation
- 25. Protect governed source data
- 26. Separate identification from quantity
- 27. Separate identity from function
- 28. Connect to Primary Science
- 29. Connect to Secondary Science
- 30. Connect to mathematics
- 31. Connect to computing
- 32. Connect to pathways
- 33. Did you know?
- 34. Write a reader-ready methods note
- 35. Build a validation ladder
- 36. Finish with a reproducible bundle
Section 1 of 36
1. Start with the reuse question
Decide whether the library will support identification, teaching, method development, quality checks or tool comparison. Each purpose changes the required coverage and metadata.
Working checkpoint — mzSpecLib: Write the intended users, analytes, acquisition scope and acceptance rules. Keep library provenance, spectrum attributes, analytes, interpretations, peaks and controlled terms together.
For a classroom model, compare fictional peak lists with clear tolerances.
Section 2 of 36
2. Use the ratified standard
The official PSI page says mzSpecLib has completed the PSI Document Process and provides the final 1.0 specification.
Working checkpoint — spectral library: Record the exact specification and retrieval date. Read every search score beside query processing, candidate set, threshold and alternative matches.
For future study, connect chemistry to computation while checking official pathways separately.
Section 3 of 36
3. Define the library boundary
A library needs an explicit molecular, organism, instrument and acquisition scope so absence is not mistaken for negative evidence.
Working checkpoint — library spectrum: Publish inclusion and exclusion criteria. Preserve empirical sources and prediction receipts; a final library entry is not the whole construction process.
For scientific writing, cite library version, source, search method, score, validation and limits.
Section 4 of 36
4. Describe library provenance
Readers need to know who assembled the library, from which data or prediction system, under what licence and on what date.
Working checkpoint — analyte: Keep a versioned build manifest. Separate format conformance from spectrum quality, match confidence and biological meaning.
For students, ask which peaks and source records support a library interpretation.
Section 5 of 36
5. Assign stable identifiers
Library and spectrum identifiers should remain unique through export, validation and updates. Display names alone are not durable keys.
Working checkpoint — interpretation: Test uniqueness and keep old-to-new mappings. Treat identifiers, units, charge and modifications as scientific inputs: one mismatch can change the candidate.
For parents, ask whether a convenient match still exposes uncertainty and provenance.
Section 6 of 36
6. Read spectrum attributes
Precursor m/z, charge, retention context and other spectrum properties shape search interpretation. Missing values should remain visibly missing.
Working checkpoint — controlled metadata: Validate types, units and allowed terms. Keep library provenance, spectrum attributes, analytes, interpretations, peaks and controlled terms together.
For a classroom model, compare fictional peak lists with clear tolerances.
Section 7 of 36
7. Read the peak array
Every m/z and intensity pair is measured or predicted evidence. Sorting, precision, scaling and filtering rules affect downstream similarity.
Working checkpoint — mzSpecLib: Compare peak counts before and after conversion. Read every search score beside query processing, candidate set, threshold and alternative matches.
For future study, connect chemistry to computation while checking official pathways separately.
Section 8 of 36
8. Separate analyte from spectrum
An analyte is the molecular entity proposed for an entry; the spectrum is a signal representation. Several spectra may support one analyte.
Working checkpoint — spectral library: Keep relationships explicit rather than name-based. Preserve empirical sources and prediction receipts; a final library entry is not the whole construction process.
For scientific writing, cite library version, source, search method, score, validation and limits.
Section 9 of 36
9. Separate interpretation from observation
Fragment or precursor interpretations explain peaks but do not replace numerical peak evidence.
Working checkpoint — library spectrum: Preserve both raw values and annotations. Separate format conformance from spectrum quality, match confidence and biological meaning.
For students, ask which peaks and source records support a library interpretation.
Section 10 of 36
10. Use mzPAF deliberately
The companion mzPAF standard supplies a shared way to express peak annotations for spectral-library use.
Working checkpoint — analyte: Pin its version and validate representative annotations. Treat identifiers, units, charge and modifications as scientific inputs: one mismatch can change the candidate.
For parents, ask whether a convenient match still exposes uncertainty and provenance.
Section 11 of 36
11. Describe modifications precisely
Modified analytes need residue, position and controlled meaning. Equal mass shifts can have different chemistry.
Working checkpoint — interpretation: Use ProForma or governed modification accessions where appropriate. Keep library provenance, spectrum attributes, analytes, interpretations, peaks and controlled terms together.
For a classroom model, compare fictional peak lists with clear tolerances.
Section 12 of 36
12. Record decoys and negatives
Some libraries include decoys or background entries for evaluation. Their construction affects error estimates.
Working checkpoint — controlled metadata: Label generation method and never mix them silently with targets. Read every search score beside query processing, candidate set, threshold and alternative matches.
For future study, connect chemistry to computation while checking official pathways separately.
Section 13 of 36
13. Distinguish empirical spectra
Empirical entries derive from acquired observations and inherit sample, instrument and processing context.
Working checkpoint — mzSpecLib: Link them to inspectable source evidence where possible. Preserve empirical sources and prediction receipts; a final library entry is not the whole construction process.
For scientific writing, cite library version, source, search method, score, validation and limits.
Section 14 of 36
14. Distinguish predicted spectra
Predicted entries derive from a model and depend on its version, training scope and parameters.
Working checkpoint — spectral library: Label prediction provenance and expected domain. Separate format conformance from spectrum quality, match confidence and biological meaning.
For students, ask which peaks and source records support a library interpretation.
Section 15 of 36
15. Explain consensus building
Combining replicate spectra can stabilise peaks but can also hide heterogeneity or instrument-specific effects.
Working checkpoint — library spectrum: Publish clustering, filtering and normalisation rules. Treat identifiers, units, charge and modifications as scientific inputs: one mismatch can change the candidate.
For parents, ask whether a convenient match still exposes uncertainty and provenance.
Section 16 of 36
16. Preserve units and precision
m/z, intensity, retention and mobility values need declared units and sensible numerical precision.
Working checkpoint — analyte: Round only for display, not for archived evidence. Keep library provenance, spectrum attributes, analytes, interpretations, peaks and controlled terms together.
For a classroom model, compare fictional peak lists with clear tolerances.
Section 17 of 36
17. Use controlled vocabulary accessions
PSI-MS and related vocabularies make methods and attributes computable across tools.
Working checkpoint — interpretation: Store accession with label and release. Read every search score beside query processing, candidate set, threshold and alternative matches.
For future study, connect chemistry to computation while checking official pathways separately.
Section 18 of 36
18. Test serialization round trips
The standard permits interchangeable serializations, so conversion must preserve the shared data model.
Working checkpoint — controlled metadata: Compare identifiers, terms, arrays and numerical tolerance. Preserve empirical sources and prediction receipts; a final library entry is not the whole construction process.
For scientific writing, cite library version, source, search method, score, validation and limits.
Section 19 of 36
19. Validate structure
A parser can check required records, field types, references and cardinalities before search software reads the library.
Working checkpoint — mzSpecLib: Keep the validator version and complete report. Separate format conformance from spectrum quality, match confidence and biological meaning.
For students, ask which peaks and source records support a library interpretation.
Section 20 of 36
20. Validate semantic meaning
A structurally valid file can still pair the wrong term, unit, analyte or charge with a spectrum.
Working checkpoint — spectral library: Review scientific plausibility independently. Treat identifiers, units, charge and modifications as scientific inputs: one mismatch can change the candidate.
For parents, ask whether a convenient match still exposes uncertainty and provenance.
Section 21 of 36
21. Validate search behaviour
A tiny fixture with known matches, near matches and non-matches shows how a search engine uses the library.
Working checkpoint — library spectrum: Record software, score and threshold. Keep library provenance, spectrum attributes, analytes, interpretations, peaks and controlled terms together.
For a classroom model, compare fictional peak lists with clear tolerances.
Section 22 of 36
22. Follow one query spectrum
Trace a query from source mzML or USI through preprocessing, candidate retrieval, score and accepted result.
Working checkpoint — analyte: Keep alternatives and rejected candidates. Read every search score beside query processing, candidate set, threshold and alternative matches.
For future study, connect chemistry to computation while checking official pathways separately.
Section 23 of 36
23. Treat similarity as evidence
A high similarity score reflects a defined comparison; it does not by itself prove molecular identity.
Working checkpoint — interpretation: Combine it with controls and orthogonal evidence. Preserve empirical sources and prediction receipts; a final library entry is not the whole construction process.
For scientific writing, cite library version, source, search method, score, validation and limits.
Section 24 of 36
24. Check transfer integrity
Large libraries can be truncated or altered during download and conversion.
Working checkpoint — controlled metadata: Publish file size and cryptographic hash. Separate format conformance from spectrum quality, match confidence and biological meaning.
For students, ask which peaks and source records support a library interpretation.
Section 25 of 36
25. Protect governed source data
A shared library can expose sensitive or licensed source material through metadata or links.
Working checkpoint — mzSpecLib: Review consent, licence and access conditions. Treat identifiers, units, charge and modifications as scientific inputs: one mismatch can change the candidate.
For parents, ask whether a convenient match still exposes uncertainty and provenance.
Section 26 of 36
26. Separate identification from quantity
A library match suggests what a spectrum represents; abundance needs a separate quantitative workflow.
Working checkpoint — spectral library: Keep mzQuantML or other quantitative evidence distinct. Keep library provenance, spectrum attributes, analytes, interpretations, peaks and controlled terms together.
For a classroom model, compare fictional peak lists with clear tolerances.
Section 27 of 36
27. Separate identity from function
A matched peptide or metabolite does not establish biological mechanism, phenotype or clinical meaning.
Working checkpoint — library spectrum: Require independent functional evidence. Read every search score beside query processing, candidate set, threshold and alternative matches.
For future study, connect chemistry to computation while checking official pathways separately.
Section 28 of 36
28. Connect to Primary Science
A fictional peak-list card lets younger learners separate an observation from the label attached to it. The goal is careful comparison, not memorising specialist jargon.
Working checkpoint — analyte: Use invented records, define every column and ask what remains unknown. Preserve empirical sources and prediction receipts; a final library entry is not the whole construction process.
For scientific writing, cite library version, source, search method, score, validation and limits.
Section 29 of 36
29. Connect to Secondary Science
spectral library supports lessons about molecules, measurement, controls and the difference between evidence and explanation.
Working checkpoint — interpretation: Trace one claim to its supporting record and state one limitation. Separate format conformance from spectrum quality, match confidence and biological meaning.
For students, ask which peaks and source records support a library interpretation.
Section 30 of 36
30. Connect to mathematics
Counts, coordinates, scores, ratios and uncertainty show why scientific data need units, definitions and compatible denominators.
Working checkpoint — controlled metadata: Recalculate one simple example and explain every symbol. Treat identifiers, units, charge and modifications as scientific inputs: one mismatch can change the candidate.
For parents, ask whether a convenient match still exposes uncertainty and provenance.
Section 31 of 36
31. Connect to computing
Record graphs, controlled terms and validators show how shared data models cross software boundaries.
Working checkpoint — mzSpecLib: Break one reference or field, run a check and repair it transparently. Keep library provenance, spectrum attributes, analytes, interpretations, peaks and controlled terms together.
For a classroom model, compare fictional peak lists with clear tolerances.
Section 32 of 36
32. Connect to pathways
Spectral libraries connect chemistry, biology, statistics, instrument science and software and can illuminate STEM education and career pathways.
Working checkpoint — spectral library: Check current official education and qualification routes separately before making decisions. Read every search score beside query processing, candidate set, threshold and alternative matches.
For future study, connect chemistry to computation while checking official pathways separately.
Section 33 of 36
33. Did you know?
A short, readable spectral library record can depend on a much longer chain of source data, identifiers, versions and validation receipts.
Working checkpoint — library spectrum: Follow one record backwards until every dependency is named. Preserve empirical sources and prediction receipts; a final library entry is not the whole construction process.
For scientific writing, cite library version, source, search method, score, validation and limits.
Section 34 of 36
34. Write a reader-ready methods note
State the specification or service, release, inputs, software, validation, uncertainty and the narrow claim the evidence supports.
Working checkpoint — analyte: Place the note beside the machine-readable material. Separate format conformance from spectrum quality, match confidence and biological meaning.
For students, ask which peaks and source records support a library interpretation.
Section 35 of 36
35. Build a validation ladder
Check bytes, structure, identifiers, controlled meanings, cross-references, scientific plausibility and a small known fixture in that order.
Working checkpoint — interpretation: Stop at the first unresolved layer instead of polishing a later result. Treat identifiers, units, charge and modifications as scientific inputs: one mismatch can change the candidate.
For parents, ask whether a convenient match still exposes uncertainty and provenance.
Section 36 of 36
36. Finish with a reproducible bundle
Deliver source data or stable identifiers, metadata, software versions, configuration, validator output, checksums and a plain-language limitations note.
Working checkpoint — controlled metadata: Make the published conclusion traceable and reviewable. Keep library provenance, spectrum attributes, analytes, interpretations, peaks and controlled terms together.
For a classroom model, compare fictional peak lists with clear tolerances.
Contents · Previous section · Continue to the Science Learning Hub