Why Science? | mzQC and Mass Spectrometry Quality Metrics

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. mzQC is the HUPO-PSI JSON format for exchange, transmission and archiving of quality metrics derived from biological mass spectrometry. The official model groups metrics into runQuality elements for one run and setQuality elements for multiple runs. Each group has metadata for input files and analysis software, while qualityMetric values can be scalars, tuples, matrices or tables. Metrics use controlled terms from the PSI-MS quality-control namespace so their definitions, value types and units are unambiguous. JSON Schema checks structure, and semantic rules check vocabularies, uniqueness, types, units and table lengths. A metric supports evaluation; it does not decide fitness for every experiment without a study-specific threshold and human context. 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: mass spectrometry, ionisation and mass-to-charge evidence; ion-mobility mass spectrometry; hydrogen–deuterium exchange mass spectrometry; Science Learning Hub; Education Hub; STEM Education; Careers by Subject Capability.

Primary and official sources checked on 12 October 2026: HUPO-PSI mzQC official specification site, checked 12 October 2026; HUPO-PSI mzQC introduction and data model, checked 12 October 2026; HUPO-PSI mzQC validation rules, 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, tools and recommendations can change, so preserve dated documentation, exact source data and software versions.

A deeper reading route

Quality control turns a vague question—did this run behave well?—into defined measurements. mzQC does not mandate one universal panel. It provides a common container for metrics chosen by laboratories, repositories or workflows, preserving enough provenance and controlled meaning for another tool to read them consistently.

The format is realised in JSON and validated against a JSON Schema. Objects hold named key-value pairs, while arrays hold ordered values. This web-native representation is approachable and widely supported, yet ordinary JSON validity is only the first layer. A document can parse correctly while using a metric with the wrong unit or duplicate meaning.

runQuality groups metrics pertaining to a single mass-spectrometry run. setQuality groups metrics calculated across several runs. Keeping these levels distinct prevents a batch median from being mistaken for one injection and prevents a run outlier from being hidden inside an aggregate. Labels must be unique so humans and programs can identify each group.

Metadata records the originating input file or files and software used to calculate metrics. File locations must be unique within the relevant run or set. Hashes, USIs or repository identifiers can strengthen identity when paths are unstable. Software name, version and parameters matter because two implementations may calculate a similarly named metric differently.

qualityMetric elements carry a controlled term and value. The value can be a single number, an n-tuple, a matrix or a table, as defined by the vocabulary term. This flexibility covers simple counts and rich distributions, but it means a consumer must read the metric definition before assuming the JSON shape.

The PSI-MS controlled vocabulary reserves MS:4000000 through MS:4999999 for QC concepts. Terms define metric names, expected value structures, units and supporting values. Accessions create stable machine references, while the vocabulary release provides context. A label copied from a graph is not a substitute for the official term.

Syntactic validation uses JSON Schema draft-07 in the current official guidance. It can check required objects, cardinality and data types. Semantic validation adds rules that schema alone cannot fully express: controlled vocabularies must resolve, accessions and names must match, metric values must use allowed structures and units, and table columns must have equal lengths.

The official validation guidance requires quality metrics to be unique within their runQuality or setQuality parent. Duplicate terms can be ambiguous if they represent different filters or populations. If two variants are scientifically necessary, their distinction must be encoded through defined supporting data or separate context rather than repeated labels with hidden assumptions.

A percentage metric deserves denominator checks. The guidance notes that detailed metric validation may include checks such as percentages summing to one hundred. Counts, rates and distributions likewise need domain constraints. Schema-valid numbers can still be impossible, so laboratories should add expectation ranges and known fixtures.

Thresholds belong to a quality policy, not to mzQC syntax alone. An acceptable mass accuracy, identification rate or chromatographic width depends on instrument, method, analyte, batch and study objective. Store the measured metric separately from the decision rule and version the rule. This lets future reviewers distinguish changed data from changed acceptance criteria.

Run-to-run monitoring can reveal drift, sudden failure or batch effects. Trends require comparable metrics calculated by the same method under stable units and reference materials. A setQuality summary can support monitoring, but retain run-level points so outliers and time order remain visible. Aggregation should never erase a failed injection.

Quality metrics are diagnostic clues, not automatic causes. A change in total ion current may reflect sample load, spray stability, detector response or acquisition settings. Investigating requires complementary metrics and instrument logs. A dashboard should invite the next check rather than convert one red box into a confident explanation.

For students, mzQC is like a laboratory checklist in which every number has a dictionary definition and unit. Some values describe one experiment; others describe a whole class set. The cheerful lesson is that quality becomes easier to improve when observations, definitions and decisions are kept separate.

A durable package includes input-run identities, mzQC file, JSON Schema, PSI-MS CV release, metric calculation software and parameters, laboratory thresholds, reference-material context, validator report and hashes. It should also preserve rejected runs and corrective actions so the quality history is not rewritten after success.

Privacy and operational security matter. File locations can reveal participant codes, instruments or internal storage systems. Quality metrics may expose unreleased samples or laboratory performance. Use durable pseudonymous identifiers, minimise paths and release only under an appropriate governance and collaboration agreement.

Versioned metric frameworks help collaboration. Two laboratories can both produce valid mzQC while choosing different metric panels. Shared projects should publish the required terms, calculation versions, units, missingness rules and acceptance thresholds. Interoperability begins with common syntax and succeeds only with aligned analytical definitions.

Quality control becomes useful only when a metric has a clear meaning, scope and comparison context. A run-level value can flag one acquisition, whereas a set-level value can reveal a pattern across several runs. Neither alone proves that the biological conclusion is correct. Reviewers should ask what was measured, which input files and software produced it, what unit and value type apply, and which reference distribution or decision rule makes the number actionable.

The distinction between schema validation and semantic validation is especially important. JSON Schema can confirm that required fields and general shapes are present, while mzQC semantic rules test matters such as controlled-vocabulary identity, expected units, value types, unique labels and equal table-column lengths. A file can therefore look like valid JSON yet still describe a metric incorrectly. This is a useful data-literacy lesson: machine readability, structural validity and scientific validity are related but not interchangeable.

Students can explore this safely with fictional runs. Give each team a table of signal, retention-time and identification-count metrics, then ask them to decide whether one unusual value is a warning, an error or simply natural variation. Require every decision to name the comparison group and the possible technical cause. The exercise encourages curiosity rather than automatic rejection and shows why quality dashboards must link summaries back to instruments, samples and processing records.

Operationally, a laboratory should version its metric definitions, thresholds and software beside each mzQC file. If an alert rule changes, older runs should not silently acquire a new historical judgement. Preserving the original values and the policy used at the time supports fair comparison and later re-evaluation. It also helps teams separate an immutable observation from a revisable interpretation.

Good quality systems combine mzQC with source data, calibration records, maintenance notes and domain expertise. A tidy metric file cannot diagnose every cause, and a passing dashboard cannot guarantee correct sample identity or biological inference. Its real value is more modest and more powerful: it makes quality evidence portable, consistently labelled and easier to review across people and tools, so problems can be found earlier and discussed with precision.

A four-step claim ladder for this method

Stage	Question	Evidence	Responsible output
Group	Does the metric describe one run or a set?	runQuality and setQuality	A clear quality level
Define	Which metric and value structure apply?	PSI-MS QC term, type and unit	An unambiguous measurement
Trace	Which files and software produced it?	Metadata, locations, labels and versions	Reproducible provenance
Decide	Is the result fit for this purpose?	Threshold policy, controls and investigation	A contextual quality decision