Validity constraint enforcement for msdata

validity-constraint-enforcement-for-msdata

Summary

Enforce consistency constraints across S4 slots in custom MsBackend classes to ensure that spectra variable metadata, m/z values, and intensity values remain synchronized and meet mass spectrometry data requirements (sorted m/z, no NA values). This is critical when extending the virtual MsBackend class to create new mass spectrometry data storage backends.

When to use

When designing a custom MsBackend subclass (e.g., MsBackendTest) that stores spectral data in multiple slots (a data.frame for spectra variables, NumericList objects for m/z and intensity peaks). Use this skill to guard against slot desynchronization—e.g., when spectraVars rows do not match the length of mz/intensity elements, or when m/z values are unsorted or contain NA values per spectrum.

When NOT to use

• Working with an existing, pre-validated backend implementation (e.g., MsBackendMemory, MsBackendMzR)—no need to re-validate.
• Using a read-only backend wrapper (e.g., MsBackendCached) that delegates validation to its parent backend.
• Data is already guaranteed consistent by external constraints (e.g., loaded from a single coherent SQL database via MsBackendSql).

Inputs

• S4 class definition extending MsBackend
• data.frame slot (spectraVars) with spectrum-level metadata
• NumericList slot (mz) with m/z peak values per spectrum
• NumericList slot (intensity) with intensity values per spectrum

Outputs

• Validated MsBackend instance (passes setValidity checks)
• Character vector of validation error messages (if validation fails)
• Boolean result from validObject() call

How to apply

Define a setValidity() method on your MsBackend subclass that enforces three key invariants: (1) nrow(spectraVars) == length(mz) == length(intensity), ensuring all slots index the same number of spectra; (2) for each element in the mz NumericList, values must be sorted increasingly with no NA entries, as required by the Spectra package specification; (3) optionally, validate that spectra variables include required core variables (e.g., dataStorage, dataOrigin) and that intensity values are non-negative. The setValidity method should return TRUE on success or a descriptive character vector of error messages on failure. Call validObject() after instantiation to trigger validation.

Related tools

• Spectra (defines the MsBackend virtual class and spectra data model; provides setValidity and validObject infrastructure for S4 class validation) — https://github.com/RforMassSpectrometry/Spectra
• S4Vectors (provides NumericList and DataFrame slot types used to store peak data and spectra metadata in MsBackend subclasses)
• R (S4 system) (language and object system; setClass, setValidity, validObject, setMethod are core functions for defining and validating S4 classes)

Examples

setValidity("MsBackendTest", function(object) { if (nrow(object@spectraVars) != length(object@mz)) return("nrow(spectraVars) != length(mz)"); if (length(object@mz) != length(object@intensity)) return("length(mz) != length(intensity)"); if (!all(sapply(object@mz, function(x) !anyNA(x) && !is.unsorted(x)))) return("mz not sorted or contains NA"); TRUE }); validObject(backend_instance)

Evaluation signals

• validObject(backend_instance) returns TRUE for a correctly populated backend; returns an error or character vector listing constraint violations when slots are mismatched.
• nrow(spectraVars) equals length(mz) and length(intensity)—inspect via all(nrow(backend@spectraVars) == length(backend@mz), length(backend@mz) == length(backend@intensity)).
• For each element in mz NumericList, m/z values are sorted increasingly and contain no NA: all(sapply(backend@mz, function(x) all(!is.na(x)) && is.unsorted(x) == FALSE)).
• Attempt to create an invalid backend (e.g., mismatched slot lengths) and verify setValidity rejects it with a descriptive error message.
• After valid instantiation, call spectraData() and peaksData() methods and confirm returned DataFrame and matrices are internally consistent.

Limitations

• setValidity is called only at object creation and after explicit validObject() calls; modifications via direct slot assignment (@ operator) may bypass validation—use accessor methods with validity checks instead.
• Validation logic is backend-specific; core requirements (m/z sorting, no NA in mz) apply to all backends, but custom spectra variables or file format constraints must be added per subclass.
• Performance cost scales with number of spectra; for very large backends (millions of spectra), validation may be slow—consider deferred or partial validation strategies.
• The Spectra package requires m/z values sorted increasingly per spectrum with no NA values; backends storing unsorted or missing m/z data must pre-process or reject such data at initialization.

Evidence

• [other] A setValidity method enforces that the number of rows in spectraVars matches the length of both mz and intensity slots, ensuring data consistency across the backend.: "A setValidity method enforces that the number of rows in spectraVars matches the length of both mz and intensity slots, ensuring data consistency across the backend."
• [intro] m/z values within each spectrum are expected to be sorted increasingly. Missing values (NA) for m/z values are not supported.: "m/z values within each spectrum are expected to be sorted increasingly. Missing values (NA) for m/z values are not supported."
• [intro] The MsBackend virtual class defines the API that new backend classes need to implement in order to be used with the Spectra object.: "The MsBackend virtual class defines the API that new backend classes need to implement in order to be used with the Spectra object."
• [other] Define a setValidity method that enforces the constraint that the number of rows in the spectraVars data.frame matches the length of the m/z and intensity NumericList elements, and that m/z values are sorted increasingly with no NA values per spectrum.: "Define a setValidity method that enforces the constraint that the number of rows in the spectraVars data.frame matches the length of the m/z and intensity NumericList elements, and that m/z values"
• [intro] One Spectra object is supposed to contain MS (spectral) data of multiple MS spectra. m/z values within each spectrum are expected to be sorted increasingly.: "One Spectra object is supposed to contain MS (spectral) data of multiple MS spectra. m/z values within each spectrum are expected to be sorted increasingly."