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."
1---2name: validity-constraint-enforcement-for-msdata3description: Use when 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.4license: CC-BY-4.05---67# validity-constraint-enforcement-for-msdata89## Summary1011Enforce 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.1213## When to use1415When 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.1617## When NOT to use1819- Working with an existing, pre-validated backend implementation (e.g., MsBackendMemory, MsBackendMzR)—no need to re-validate.20- Using a read-only backend wrapper (e.g., MsBackendCached) that delegates validation to its parent backend.21- Data is already guaranteed consistent by external constraints (e.g., loaded from a single coherent SQL database via MsBackendSql).2223## Inputs2425- S4 class definition extending MsBackend26- data.frame slot (spectraVars) with spectrum-level metadata27- NumericList slot (mz) with m/z peak values per spectrum28- NumericList slot (intensity) with intensity values per spectrum2930## Outputs3132- Validated MsBackend instance (passes setValidity checks)33- Character vector of validation error messages (if validation fails)34- Boolean result from validObject() call3536## How to apply3738Define 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.3940## Related tools4142- **Spectra** (defines the MsBackend virtual class and spectra data model; provides setValidity and validObject infrastructure for S4 class validation) — https://github.com/RforMassSpectrometry/Spectra43- **S4Vectors** (provides NumericList and DataFrame slot types used to store peak data and spectra metadata in MsBackend subclasses)44- **R (S4 system)** (language and object system; setClass, setValidity, validObject, setMethod are core functions for defining and validating S4 classes)4546## Examples4748```49setValidity("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)50```5152## Evaluation signals5354- validObject(backend_instance) returns TRUE for a correctly populated backend; returns an error or character vector listing constraint violations when slots are mismatched.55- nrow(spectraVars) equals length(mz) and length(intensity)—inspect via `all(nrow(backend@spectraVars) == length(backend@mz), length(backend@mz) == length(backend@intensity))`.56- 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))`.57- Attempt to create an invalid backend (e.g., mismatched slot lengths) and verify setValidity rejects it with a descriptive error message.58- After valid instantiation, call spectraData() and peaksData() methods and confirm returned DataFrame and matrices are internally consistent.5960## Limitations6162- 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.63- 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.64- Performance cost scales with number of spectra; for very large backends (millions of spectra), validation may be slow—consider deferred or partial validation strategies.65- 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.6667## Evidence6869- [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."70- [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."71- [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."72- [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"73- [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."
